Control protocol
All 139 operation ids grouped into 25 domains, each with its Host handler location.
Transport rules
The control channel is fixed at /agentkit: 139 operation ids across 25 domains.
| Rule | Value | Source |
|---|---|---|
| Control channel | /agentkit | src/contracts/operations.mjs:144 |
| Request envelope | { operationId, payload }; the payload must be serializable JSON | src/contracts/wire.mjs |
| Response envelope | { ok: true, value } or { ok: false, error } | src/contracts/wire.mjs |
| Cancellation | Fourth argument is an AbortSignal; one terminal envelope, no retry of unknown effects | src/contracts/definitions.mjs:8 |
| Idempotency | list / get / status / *.history are read-only; everything else follows its operation semantics | — |
Domain summary
25 domains, largest first. sessions and agents carry most of the interaction surface.
| Domain | Size | Summary |
|---|---|---|
host | 2 | Host discovery and computer-control entry points. |
templates | 6 | Expert template catalog, preparation, export and summon. |
platform | 1 | Platform resource view shared across templates. |
template-resources | 3 | List, prepare and install resources declared by a template. |
template-workflows | 6 | Template workflow start, status, cancel and cache. |
teams | 8 | Team save, start, status, history and stop. |
team-templates | 2 | Team template list and detail. |
sessions | 24 | Session export, native recovery, child tasks, A2A, approvals and command output. The largest domain. |
agents | 11 | Local and cloud Agent lifecycle, execution policy and conversation surface. |
models | 5 | Model catalog, credential sync and Codex model catalog. |
resources | 2 | Resource catalog list and delete. |
mcp | 4 | MCP server create, update, probe and delete. |
credentials | 1 | Credential write. |
settings | 2 | Global settings read and update. |
skills | 5 | Skill discovery, preview, commit and installed preview. |
plugins | 12 | DSH and Codex plugin install, enable, disable and remove. |
star-harness | 5 | Local Star Harness install, enable and workspace binding. Callable by the Studio host owner only. |
builds | 4 | Build create, list, download and portable export. |
operations | 2 | Long operation list and cancel. |
schedules | 8 | Schedule CRUD, manual run and delivery targets. |
traces | 4 | Trace overview, list, detail and OTLP ingest. |
evaluations | 6 | Evaluation create, read, targets, eval sets and import. |
channels | 4 | Channel connection, update and action. |
server | 1 | Server action entry point. |
deployments | 11 | Deployment prepare, create, update, reconcile, logs and remove. |
Full list
The handler column points at the Host dispatch entry; the parenthetical marks a prefix-dispatched domain or a retired id.
| Domain | Operation id | Action | Handler |
|---|---|---|---|
host | host/compatibility | Read compatibility | src/host/routes/host.mjs:7 |
host | host/computer | Drive computer | src/host/routes/host.mjs:9 |
templates | templates/list | List | src/host/routes/templates.mjs:8 |
templates | templates/prepare | Prepare | src/host/routes/templates.mjs:12 |
templates | templates/export | Export | src/host/routes/templates.mjs:15 |
templates | templates/avatar | Read avatar | src/host/routes/templates.mjs:11 |
templates | templates/summon-plan | Build summon plan | src/host/routes/templates.mjs:13 |
templates | templates/summon | Summon | src/host/routes/templates.mjs:14 |
platform | platform/resources | List resources | src/host/routes/templates.mjs:19 |
template-resources | template-resources/list | List | src/host/routes/templates.mjs:10 (prefix dispatch) |
template-resources | template-resources/prepare | Prepare | src/host/routes/templates.mjs:10 (prefix dispatch) |
template-resources | template-resources/install | Install | src/host/routes/templates.mjs:10 (prefix dispatch) |
template-workflows | template-workflows/start | Start | src/host/routes/templates.mjs:9 (prefix dispatch) |
template-workflows | template-workflows/status | Read status | src/host/routes/templates.mjs:9 (prefix dispatch) |
template-workflows | template-workflows/cancel | Cancel | src/host/routes/templates.mjs:9 (prefix dispatch) |
template-workflows | template-workflows/detail | Read detail | src/host/routes/templates.mjs:9 (prefix dispatch) |
template-workflows | template-workflows/cache | Read cache | src/host/routes/templates.mjs:9 (prefix dispatch) |
template-workflows | template-workflows/clearCache | Clear cache | src/host/routes/templates.mjs:9 (prefix dispatch) |
teams | teams/list | List | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/save | Save | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/remove | Remove | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/start | Start | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/status | Read status | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/history | Read history | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/resume | Resume | src/host/routes/templates.mjs:7 (prefix dispatch) |
teams | teams/stop | Stop | src/host/routes/templates.mjs:7 (prefix dispatch) |
team-templates | team-templates/list | List | src/host/routes/templates.mjs:6 (prefix dispatch) |
team-templates | team-templates/detail | Read detail | src/host/routes/templates.mjs:6 (prefix dispatch) |
sessions | sessions/export-log | Export transcript | src/host/routes/sessions.mjs:16 |
sessions | sessions/native-inject | Inject native event | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-recovery-status | Read recovery status | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-recovery-resume | Resume native session | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-recovery-reconcile | Reconcile native recovery | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-background-review | Review in background | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-resource-retire | Retire native resource | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-workspace-repair | Repair workspace | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-conversation-status | Read conversation status | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-conversation-rewind | Rewind conversation | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-conversation-workspace-preview | Preview workspace | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-a2a-control | Control A2A | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/dsh-a2a-history | Read A2A history | src/host/routes/sessions.mjs:9 |
sessions | sessions/dsh-a2a-control | Control DSH A2A | src/host/routes/sessions.mjs:9 |
sessions | sessions/native-child-tasks | List child tasks | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-child-promote | Promote child task | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-child-send | Send to child task | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-child-cancel | Cancel child task | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-child-history | Read child task history | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-child-result | Read child task result | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-child-file | Read child task file | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-command-output | Read command output | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-approval-status | Read approval status | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
sessions | sessions/native-approval-decision | Submit approval decision | src/host/routes/sessions.mjs:7 (retired, throws STUDIO_LEGACY_HARNESS_RETIRED) |
agents | agents/list | List | src/host/routes/agents.mjs:94 |
agents | agents/create-local | Create local | src/host/routes/agents.mjs:21 |
agents | agents/update-cloud | Update cloud | src/host/routes/agents.mjs:49 |
agents | agents/ensure-preset | Ensure preset | src/host/routes/agents.mjs:123 |
agents | agents/managed-delete | Delete managed resource | src/host/routes/agents.mjs:67 |
agents | agents/execution-policy | Read execution policy | src/host/routes/agents.mjs:97 |
agents | agents/execution-policy-set | Set execution policy | src/host/routes/agents.mjs:107 |
agents | agents/conversation-surface | Read conversation surface | src/host/routes/agents.mjs:146 |
agents | agents/local-get | Read local | src/host/routes/agents.mjs:21 |
agents | agents/update-local | Update local | src/host/routes/agents.mjs:21 |
agents | agents/local-delete | Delete local | src/host/routes/agents.mjs:8 |
models | models/sync-credential | Sync credential | src/host/routes/models.mjs:4 |
models | models/credential-status | Read credential status | src/host/routes/models.mjs:6 |
models | models/create | Create | src/host/routes/models.mjs:8 |
models | models/catalog | Read catalog | src/host/routes/models.mjs:14 |
models | models/codex | Read Codex catalog | src/host/routes/models.mjs:18 |
resources | resources/list | List | src/host/routes/resources.mjs:8 |
resources | resources/delete | Delete | src/host/routes/resources.mjs:36 |
mcp | mcp/create | Create | src/host/routes/resources.mjs:23 |
mcp | mcp/update | Update | src/host/routes/resources.mjs:27 |
mcp | mcp/probe | Probe | src/host/routes/resources.mjs:32 |
mcp | mcp/delete | Delete | src/host/routes/resources.mjs:36 |
credentials | credentials/put | Write | src/host/routes/credentials.mjs:2 |
settings | settings/get | Read | src/host/routes/models.mjs:10 |
settings | settings/update | Update | src/host/routes/models.mjs:12 |
skills | skills/discover | Discover | src/host/routes/skills.mjs:4 |
skills | skills/preview-discovered | Preview discovered | src/host/routes/skills.mjs:4 |
skills | skills/commit-discovered | Commit discovered | src/host/routes/skills.mjs:4 |
skills | skills/list | List | src/host/routes/skills.mjs:4 |
skills | skills/preview-installed | Preview installed | src/host/routes/skills.mjs:4 |
plugins | plugins/dsh-list | List DSH plugins | src/host/routes/plugins.mjs:7 |
plugins | plugins/dsh-discover | Discover DSH plugins | src/host/routes/plugins.mjs:9 |
plugins | plugins/dsh-index-refresh | Refresh remote index | src/host/routes/plugins.mjs:11 |
plugins | plugins/dsh-install | Install DSH plugin | src/host/routes/plugins.mjs:13 |
plugins | plugins/dsh-remove | Remove DSH plugin | src/host/routes/plugins.mjs:15 |
plugins | plugins/dsh-enable | Enable DSH plugin | src/host/routes/plugins.mjs:17 |
plugins | plugins/dsh-disable | Disable DSH plugin | src/host/routes/plugins.mjs:17 |
plugins | plugins/dsh-update | Update DSH plugin | src/host/routes/plugins.mjs:21 |
plugins | plugins/codex-list | List Codex plugins | src/host/routes/plugins.mjs:32 |
plugins | plugins/codex-inspect | Inspect Codex plugin | src/host/routes/plugins.mjs:32 |
plugins | plugins/codex-install | Install Codex plugin | src/host/routes/plugins.mjs:25 |
plugins | plugins/codex-remove | Remove Codex plugin | src/host/routes/plugins.mjs:25 |
star-harness | star-harness/status | Read status | src/host/routes/star-harness.mjs:4 |
star-harness | star-harness/install | Install | src/host/routes/star-harness.mjs:8 |
star-harness | star-harness/enable | Enable | src/host/routes/star-harness.mjs:9 |
star-harness | star-harness/bind | Bind workspace | src/host/routes/star-harness.mjs:10 |
star-harness | star-harness/unbind | Unbind workspace | src/host/routes/star-harness.mjs:11 |
builds | builds/create | Create | src/host/routes/builds.mjs:5 |
builds | builds/list | List | src/host/routes/builds.mjs:5 |
builds | builds/download | Download | src/host/routes/builds.mjs:5 |
builds | builds/export-portable | Export portable bundle | src/host/routes/builds.mjs:5 |
operations | operations/list | List | src/host/routes/builds.mjs:5 |
operations | operations/cancel | Cancel | src/host/routes/builds.mjs:5 |
schedules | schedules/list | List | src/host/routes/schedules.mjs:15 |
schedules | schedules/create | Create | src/host/routes/schedules.mjs:19 |
schedules | schedules/get | Read | src/host/routes/schedules.mjs:21 |
schedules | schedules/update | Update | src/host/routes/schedules.mjs:23 |
schedules | schedules/delete | Delete | src/host/routes/schedules.mjs:25 |
schedules | schedules/run | Run | src/host/routes/schedules.mjs:27 |
schedules | schedules/occurrences | Read occurrences | src/host/routes/schedules.mjs:29 |
schedules | schedules/delivery-targets | List delivery targets | src/host/routes/schedules.mjs:6 |
traces | traces/overview | Read overview | src/host/routes/traces.mjs:10 |
traces | traces/list | List | src/host/routes/traces.mjs:21 |
traces | traces/get | Read | src/host/routes/traces.mjs:23 |
traces | traces/otlp | Ingest OTLP | src/host/routes/traces.mjs:25 |
evaluations | evaluations/list | List | src/host/routes/evaluations.mjs:9 |
evaluations | evaluations/create | Create | src/host/routes/evaluations.mjs:19 |
evaluations | evaluations/get | Read | src/host/routes/evaluations.mjs:11 |
evaluations | evaluations/targets | List targets | src/host/routes/evaluations.mjs:13 |
evaluations | evaluations/evalsets | Read eval sets | src/host/routes/evaluations.mjs:15 |
evaluations | evaluations/import | Import | src/host/routes/evaluations.mjs:17 |
channels | channels/connection | Read connection | src/host/routes/channels.mjs:9 |
channels | channels/update | Update | src/host/routes/channels.mjs:11 |
channels | channels/agent-update | Update agent link | src/host/routes/channels.mjs:13 |
channels | channels/action | Run action | src/host/routes/channels.mjs:15 |
server | server/action | Run action | src/host/routes/server.mjs:5 |
deployments | deployments/prepare | Prepare | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/create | Create | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/prepareUpdate | Preflight update | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/applyUpdate | Apply update | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/list | List | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/get | Read | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/refresh | Refresh | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/repairAccess | Repair access | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/reconcile | Reconcile | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/logs | Read logs | src/host/routes/deployments.mjs:4 (prefix dispatch) |
deployments | deployments/remove | Remove | src/host/routes/deployments.mjs:4 (prefix dispatch) |
Retired and contract-only ids
21 ids stay in the contract, but Host dispatch throws STUDIO_LEGACY_HARNESS_RETIRED (src/host/routes/sessions.mjs:8). This is intentional: old clients get a recognizable code instead of a 404.
Do not depend on retired ids
sessions/native-* belongs to the removed in-process Harness. New integrations should use the native session API of the matching runtime; see Session events.
Version and compatibility
| Item | Value | Notes |
|---|---|---|
| Operation ids | 139 | Adding or removing one is a breaking change |
| Domains | 25 | A new domain must land here and in the router |
| Channel | /agentkit | Hardcoded in the client, not configurable |
Developer entry points
| Item | Source |
|---|---|
| Operation list | src/contracts/operations.mjs |
| Wire codec | src/contracts/wire.mjs |
| Operation definitions | src/contracts/definitions.mjs |
| Host routes | src/host/routes/index.mjs |
| Client bridge | src/remote/control-client.mjs |
Related tests:
| Test file | Location |
|---|---|
| host-compatibility.test.mjs | tests/host-compatibility.test.mjs |
| host-route-contracts.test.mjs | tests/host-route-contracts.test.mjs |
| studio-wire-contracts.test.mjs | tests/studio-wire-contracts.test.mjs |
| host-dispatcher.test.mjs | tests/host-dispatcher.test.mjs |
| host-route-contracts.test.mjs | tests/host-route-contracts.test.mjs |
| local-agent-edit-conflicts.test.mjs | tests/local-agent-edit-conflicts.test.mjs |