app-server.md +130 −9
277 277
278- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.278- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.
279- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.279- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.
280280- `thread/fork` - fork a thread into a new thread id by copying stored history. Pass `lastTurnId` to copy history through that turn and omit later turns. Emits `thread/started` for the new thread; returned threads include `forkedFromId` when available.- `thread/fork` - fork a thread into a new thread id by copying stored history. Pass `lastTurnId` to copy history through that turn and omit later turns, or `ephemeral: true` to create an in-memory fork. Emits `thread/started` for the new thread; returned threads include `forkedFromId` when available.
281- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.281- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.
282282- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filters. Returned `thread` objects include runtime `status`.- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `isPinned`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filters. Returned `thread` objects include runtime `status`.
283- `thread/turns/list` - experimental; page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.283- `thread/turns/list` - experimental; page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.
284- `thread/items/list` - experimental; page through persisted thread items, optionally restricted to one `turnId`. The active thread store must support item pagination.284- `thread/items/list` - experimental; page through persisted thread items, optionally restricted to one `turnId`. The active thread store must support item pagination.
285- `thread/loaded/list` - list the thread ids currently loaded in memory.285- `thread/loaded/list` - list the thread ids currently loaded in memory.
287- `thread/goal/set` - set the goal for a thread; emits `thread/goal/updated`.287- `thread/goal/set` - set the goal for a thread; emits `thread/goal/updated`.
288- `thread/goal/get` - read the current goal for a thread.288- `thread/goal/get` - read the current goal for a thread.
289- `thread/goal/clear` - clear the goal for a thread; emits `thread/goal/cleared`.289- `thread/goal/clear` - clear the goal for a thread; emits `thread/goal/cleared`.
290290- `thread/metadata/update` - patch SQLite-backed stored thread metadata; currently supports persisted `gitInfo`.- `thread/metadata/update` - patch SQLite-backed stored thread metadata, including persisted `gitInfo` and `isPinned`.
291- `thread/archive` - move a thread's log file into the archived directory and attempt to archive spawned descendant thread logs that aren't already archived; returns `{}` on success and emits `thread/archived` for each archived thread.291- `thread/archive` - move a thread's log file into the archived directory and attempt to archive spawned descendant thread logs that aren't already archived; returns `{}` on success and emits `thread/archived` for each archived thread.
292- `thread/delete` - permanently delete a persisted active or archived thread and any spawned descendant threads; returns `{}` on success and emits `thread/deleted` for each deleted thread.292- `thread/delete` - permanently delete a persisted active or archived thread and any spawned descendant threads; returns `{}` on success and emits `thread/deleted` for each deleted thread.
293- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.293- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread after a no-subscriber inactivity grace period and emits `thread/closed`.
333- `plugin/install` - under development; install a plugin from a marketplace path or remote marketplace name. Don't call this method from production clients yet.333- `plugin/install` - under development; install a plugin from a marketplace path or remote marketplace name. Don't call this method from production clients yet.
334- `plugin/uninstall` - under development; uninstall an installed plugin. Don't call this method from production clients yet.334- `plugin/uninstall` - under development; uninstall an installed plugin. Don't call this method from production clients yet.
335- `plugin/skill/read` - read remote plugin skill Markdown on demand by remote marketplace, plugin id, and skill name.335- `plugin/skill/read` - read remote plugin skill Markdown on demand by remote marketplace, plugin id, and skill name.
336- `app/installed` - read installed app runtime state, including each app's effective enabled and callable states.
336- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.337- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.
338- `app/read` - fetch metadata and optional display-only tool summaries for specific app ids.
337- `skills/config/write` - enable or disable skills by path.339- `skills/config/write` - enable or disable skills by path.
338- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.340- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.
339- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.341- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.
351- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home). Supported item types include config, skills, `AGENTS.md`, plugins, MCP server config, subagents, hooks, commands, and sessions; non-empty imports emit `externalAgentConfig/import/progress` and `externalAgentConfig/import/completed` as work finishes. Plugin and session imports can complete asynchronously.353- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home). Supported item types include config, skills, `AGENTS.md`, plugins, MCP server config, subagents, hooks, commands, and sessions; non-empty imports emit `externalAgentConfig/import/progress` and `externalAgentConfig/import/completed` as work finishes. Plugin and session imports can complete asynchronously.
352- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.354- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.
353- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.355- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.
354356- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including exact managed configuration, allowlists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).
355- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, `fs/copy`, `fs/watch`, `fs/unwatch`, and `fs/changed` (notify) - operate on absolute filesystem paths through the app-server v2 filesystem API.357- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, `fs/copy`, `fs/watch`, `fs/unwatch`, and `fs/changed` (notify) - operate on absolute filesystem paths through the app-server v2 filesystem API.
356 358
357Plugin summaries include a `source` union. Local plugins return359Plugin summaries include a `source` union. Local plugins return
452 resuming it. Use `itemsView` to choose whether turn items are omitted,454 resuming it. Use `itemsView` to choose whether turn items are omitted,
453 summarized, or fully loaded.455 summarized, or fully loaded.
454- `thread/items/list` is experimental and pages through persisted thread items, optionally restricted to one turn.456- `thread/items/list` is experimental and pages through persisted thread items, optionally restricted to one turn.
455457- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filtering.- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `isPinned`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filtering.
456- `thread/loaded/list` returns the thread IDs currently in memory.458- `thread/loaded/list` returns the thread IDs currently in memory.
457- `thread/archive` moves the thread's persisted JSONL log into the archived directory and attempts to archive spawned descendant thread logs that aren't already archived.459- `thread/archive` moves the thread's persisted JSONL log into the archived directory and attempts to archive spawned descendant thread logs that aren't already archived.
458- `thread/delete` permanently deletes a persisted active or archived thread and its spawned descendant threads.460- `thread/delete` permanently deletes a persisted active or archived thread and its spawned descendant threads.
459461- `thread/metadata/update` patches stored thread metadata, currently including persisted `gitInfo`.- `thread/metadata/update` patches stored thread metadata, including persisted `gitInfo` and `isPinned`.
460- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.462- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.
461- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.463- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.
462- `thread/compact/start` triggers compaction and returns `{}` immediately.464- `thread/compact/start` triggers compaction and returns `{}` immediately.
583source thread is mid-turn, the fork records an interruption marker instead of585source thread is mid-turn, the fork records an interruption marker instead of
584retaining an unmarked partial turn.586retaining an unmarked partial turn.
585 587
588Pass `ephemeral: true` to create an in-memory fork without adding it to stored
589thread listings:
590
591```json
592{
593 "method": "thread/fork",
594 "id": 13,
595 "params": {
596 "threadId": "thr_123",
597 "ephemeral": true
598 }
599}
600{
601 "id": 13,
602 "result": {
603 "thread": {
604 "id": "thr_789",
605 "sessionId": "thr_789",
606 "forkedFromId": "thr_123",
607 "ephemeral": true
608 }
609 }
610}
611```
612
613Ephemeral forks of paginated threads also require `excludeTurns: true`. That
614field is experimental and requires `capabilities.experimentalApi = true`.
615
586When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, `thread/unarchive`, and `thread/rollback` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.616When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, `thread/unarchive`, and `thread/rollback` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.
587 617
588### Read a stored thread (without resuming)618### Read a stored thread (without resuming)
639- `modelProviders` - restrict results to specific providers; unset, null, or an empty array includes all providers.669- `modelProviders` - restrict results to specific providers; unset, null, or an empty array includes all providers.
640- `sourceKinds` - restrict results to specific thread sources. When omitted or `[]`, the server defaults to interactive sources only: `cli` and `vscode`.670- `sourceKinds` - restrict results to specific thread sources. When omitted or `[]`, the server defaults to interactive sources only: `cli` and `vscode`.
641- `archived` - when `true`, list archived threads only. When `false` or omitted, list non-archived threads (default).671- `archived` - when `true`, list archived threads only. When `false` or omitted, list non-archived threads (default).
672- `isPinned` - when provided, return only threads with the matching persisted pin state. Omit it to return pinned and unpinned threads.
642- `cwd` - restrict results to threads whose session current working directory exactly matches this path, or one of the paths in an array. Relative paths resolve from the app-server process working directory.673- `cwd` - restrict results to threads whose session current working directory exactly matches this path, or one of the paths in an array. Relative paths resolve from the app-server process working directory.
643- `useStateDbOnly` - when `true`, return state database results without scanning JSONL thread logs to repair metadata. Omit it or pass `false` for the default scan-and-repair behavior.674- `useStateDbOnly` - when `true`, return state database results without scanning JSONL thread logs to repair metadata. Omit it or pass `false` for the default scan-and-repair behavior.
644- `searchTerm` - restrict results to threads whose extracted title contains this case-sensitive text fragment.675- `searchTerm` - restrict results to threads whose extracted title contains this case-sensitive text fragment.
668} }699} }
669{ "id": 20, "result": {700{ "id": 20, "result": {
670 "data": [701 "data": [
671702 { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } }, { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "isPinned": true, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
672703 { "id": "thr_b", "preview": "Fix tests", "ephemeral": true, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } } { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "isPinned": false, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
673 ],704 ],
674 "nextCursor": "opaque-token-or-null"705 "nextCursor": "opaque-token-or-null"
675} }706} }
679 710
680### Update stored thread metadata711### Update stored thread metadata
681 712
682713Use `thread/metadata/update` to patch stored thread metadata without resuming the thread. Today this supports persisted `gitInfo`; omitted fields are left unchanged, and explicit `null` clears a stored value.Use `thread/metadata/update` to patch stored thread metadata without resuming the
714thread. Set `isPinned` to pin or unpin the thread, or update `gitInfo` to change
715persisted Git metadata. Omitted fields stay unchanged; explicit `null` clears a
716stored Git metadata value.
683 717
684```json718```json
685{ "method": "thread/metadata/update", "id": 21, "params": {719{ "method": "thread/metadata/update", "id": 21, "params": {
686 "threadId": "thr_123",720 "threadId": "thr_123",
721 "isPinned": true,
687 "gitInfo": { "branch": "feature/sidebar-pr" }722 "gitInfo": { "branch": "feature/sidebar-pr" }
688} }723} }
689{ "id": 21, "result": {724{ "id": 21, "result": {
690 "thread": {725 "thread": {
691 "id": "thr_123",726 "id": "thr_123",
727 "isPinned": true,
692 "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }728 "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
693 }729 }
694} }730} }
1466 1502
1467## Apps (connectors)1503## Apps (connectors)
1468 1504
1505Use `app/installed` to read the latest committed installed app runtime snapshot.
1506Each result includes the app `id`, `runtimeName` (or `null`), effective
1507`enabled` state, and `callable` state. An app is callable only when effective
1508configuration enables it and at least one model-visible tool complies with the
1509app and tool policies.
1510
1511```json
1512{
1513 "method": "app/installed",
1514 "id": 49,
1515 "params": {
1516 "threadId": "thread-1",
1517 "forceRefresh": false
1518 }
1519}
1520{
1521 "id": 49,
1522 "result": {
1523 "apps": [
1524 {
1525 "id": "demo-app",
1526 "runtimeName": "Demo App",
1527 "enabled": true,
1528 "callable": true
1529 }
1530 ]
1531 }
1532}
1533```
1534
1535Omit `threadId` to use the global configuration instead of a loaded thread's
1536configuration. Set `forceRefresh: true` to refresh the connector runtime
1537snapshot before reading it. When global or workspace policy blocks app access,
1538an observed app can still appear with `enabled` and `callable` set to `false`.
1539
1469Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state. App entries can also include optional `branding`, `appMetadata`, and `labels` fields.1540Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state. App entries can also include optional `branding`, `appMetadata`, and `labels` fields.
1470 1541
1471```json1542```json
1526}1597}
1527```1598```
1528 1599
1600Use `app/read` when you already know the app ids and need app metadata rather
1601than installed runtime state. Pass at most 100 `appIds`. The server keeps only
1602the first occurrence of each repeated id and preserves that order in both
1603`apps` and `missingAppIds`. Unknown or inaccessible apps are returned in
1604`missingAppIds` without failing the entire request.
1605
1606```json
1607{
1608 "method": "app/read",
1609 "id": 52,
1610 "params": {
1611 "appIds": ["demo-app", "missing-app"],
1612 "includeTools": true
1613 }
1614}
1615{
1616 "id": 52,
1617 "result": {
1618 "apps": [
1619 {
1620 "id": "demo-app",
1621 "name": "Demo App",
1622 "description": "Example connector for documentation.",
1623 "iconUrl": null,
1624 "iconUrlDark": null,
1625 "distributionChannel": null,
1626 "installUrl": null,
1627 "pluginDisplayNames": [],
1628 "toolSummaries": [
1629 {
1630 "name": "search",
1631 "title": "Search",
1632 "description": "Search the app.",
1633 "isEnabled": true,
1634 "disabledReason": null,
1635 "isReadOnly": true
1636 }
1637 ]
1638 }
1639 ],
1640 "missingAppIds": ["missing-app"]
1641 }
1642}
1643```
1644
1645Set `includeTools: true` to request display-only public tool summaries. The
1646metadata response doesn't include installed app runtime state or authorize a
1647tool call; use `app/installed` to check effective `enabled` and `callable`
1648state.
1649
1529Invoke an app by inserting `$<app-slug>` in the text input and adding a `mention` input item with the `app://<id>` path (recommended).1650Invoke an app by inserting `$<app-slug>` in the text input and adding a `mention` input item with the `app://<id>` path (recommended).
1530 1651
1531```json1652```json