Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Agent controller contract, v1 (draft)
The full contract between an agent controller and the Switch server (Management plus Core). Step 1 of the roadmap turns this into OpenAPI and JSON Schema files plus recorded fixtures. The types below are the source for those files.
0. Conventions
- Transport: HTTPS with JSON bodies (
application/json), and one WebSocket per controller carrying JSON frames. - Base paths: Management is
/v1/management/.... The Core controller surface is/v1/controllers/.... Agent actions use the existing/agents/{agent_id}/...routes. - Version: every request, and the socket's opening request, sends
Switch-Controller-Protocol: 2.- The server answers with the range it supports in
Switch-Controller-Protocol-Accepts: 2-2. - Protocol 2 moved the stream and the beat onto one WebSocket (§6). Protocol 1 (an SSE stream and a beat POST) is no longer accepted.
- An unsupported version returns
426with codeprotocol_unsupported.
- The server answers with the range it supports in
- Forward compatibility: receivers ignore unknown fields. An unknown enum value is read as
unknown, never as an error. - Time: RFC 3339 UTC strings. IDs: opaque strings.
- Idempotency: every mutating
POSTacceptsIdempotency-Key. A repeat returns the first result. - Errors: always this shape, with a code from §9:
type Error = { error: { code: ReasonCode; message: string; retryable: boolean; retry_after_s?: number } } - Auth:
Authorization: Bearer <access_token>on everything except enrollment and token exchange (§1).
1. Enrollment and authentication (Management)
POST /v1/management/enrollment-codes auth: user session (Console)
→ 201 { code: string, expires_at: Time } // single use, 10 min
POST /v1/management/controllers/enroll auth: one of the proofs below
{ proof: { kind: "user_session" } // Console, user signed in (bearer = user session)
| { kind: "enrollment_code", code: string } // personal VM / own machine
| { kind: "machine_secret", assertion: string } // Switch EC2, from the boot secret
controller: { kind: "console" | "daemon" | "ec2", name: string, platform: Platform, version: string },
public_key: { alg: "X25519", key: base64 } } // used to seal provider logins to this controller
→ 201 { controller_id: string, credential: string } // credential returned once, stored in the local secret store
POST /v1/management/controllers/{id}/token auth: none (credential in body)
{ credential: string }
→ 200 { access_token: string, expires_at: Time } // about 1h. Claims: controller_id, owner_id, tenant_id
POST /v1/management/controllers/{id}/credential/rotate → 200 { credential: string }
PATCH /v1/management/controllers/{id} auth: the controller's access token
{ name?: string, description?: string | null } // either or both; null or blank clears the description
→ 200 Controller // the machine as its owner's list shows it
→ 422 validation_error // name blank or > 200 chars, description > 500, nothing given
DELETE /v1/management/controllers/{id} auth: owner (user). Revokes it, and every agent on it stops
The PATCH is the controller renaming its own machine
(switch-agent-controller set-info), with the limits and effects of the
owner's own change in the gateway. A server that predates it answers 404 or
405 without an error envelope.
type Platform = { os: "macos" | "linux" | "windows"; arch: "arm64" | "x64"; os_version: string }
The token is short-lived and the credential is long-lived but revocable. An expired token returns 401 token_expired, and the controller then exchanges its credential again. A revoked credential returns 401 controller_revoked, and the controller stops all agents and exits.
2. Assignment (Management)
What this controller should run. It's pulled on start, on reconnect, and on every assignment.changed.
GET /v1/management/controllers/{id}/assignment
If-None-Match: "<revision>"
→ 200 Assignment | 304
type Assignment = {
revision: number // bumps on any change to this controller's set
agents: AgentAssignment[]
}
type AgentAssignment = {
agent_id: string
revision: number // bumps on any change to this agent. Used for fencing
desired_state: "running" | "stopped"
definition: AgentDefinition
}
type AgentDefinition = {
name: string // Switch identifier, as addressed in rooms
display_name: string | null
icon_url: string | null
provider: "claude" | "codex" | "opencode" | "cursor" | "antigravity"
model: string | null // null = provider default
advanced_config: Record<string, string | number | boolean | string[]> // the provider's "Advanced configuration", checked by the server against its schema for the provider (GET /gateway/management/advanced-config); an unset field is left out; {} for none
instructions: string // ≤ 32 KiB
provider_definition: string | null // e.g. the Claude agent definition file
auto_mode: boolean // the provider's own automatic review: safe actions run, risky ones ask. Absent from definitions stored before it existed, which read as false
auto_approve: boolean // CLI runs with its bypass-permissions flag; wins over auto_mode
isolation: "shared" | "isolated" // agent host in the controller, or a process of its own
session_limit: number
repo: { kind: "github"; installation_id: number; repository_id: number } | null
skills: Skill[]
local: { directory: string | null } // placement hint for console/daemon. Ignored on ec2
}
type Skill = { name: string; content: string } // installed into the provider's skills dir
repo and skills are not sent in v1. An agent's service grants and their skills are read by its agent host from GET /agents/{agent_id}/service-grants (§5) when a session starts, so a grant change bumps no revision.
3. Status (Management)
A full snapshot every time, not a delta. It's sent on every change, and at least every report_within_s.
PUT /v1/management/controllers/{id}/status
StatusReport // ≤ 64 KiB
→ 200 {
assignment_revision: number, // tells the controller if it's behind
report_within_s: number,
controller_release: ControllerRelease | null // the release to run; null = none named
}
type ControllerRelease = {
version: string // x.y.z, or a dev build's x.y.z-<prerelease>
url: string // https, the switch-agent-controller-<version>.tgz package
sha256: string // the package's SHA-256, 64 lowercase hex characters
}
controller_release is what the deployment sets (CONTROLLER_RELEASE_VERSION,
_URL, _SHA256; Helm switchCore.controllerRelease), and the chart from a
Switch release names that release's controller. A controller running another
version downloads the package, refuses it unless its SHA-256 matches, and installs
it and restarts once no agent session is in the middle of a turn (idle sessions
are restarted with it and resume their conversations). It says how that is going in
its report's update ({ target, state, problem? }), which Core stores with the
rest of the report. Rolling back is pointing the setting at the previous
release's package. A controller older than the field ignores it. A controller
Switch Console updates is always told null: one of kind console (Console's own),
or one whose last status said controller.updated_by: "console" (one Console runs
on an SSH host, which enrolls as a daemon). It ships with Console and updates
with it.
type StatusReport = {
seq: number // monotonic per controller. The server drops anything older
observed_at: Time
controller: {
version: string; protocol: 1; assignment_revision: number
updated_by?: "self" | "console" // who moves it onto another release: itself, following controller_release, or Switch Console, which runs it and replaces its bundle. Absent from older controllers
}
machine: {
platform: Platform
disk_free_bytes: number; disk_total_bytes: number
mem_free_bytes: number; mem_total_bytes: number
sessions_running: number; sessions_max: number
workspaces_dir?: string // absolute; where agents' workspaces are made when the definition names no directory. Absent from older controllers
}
providers: ProviderStatus[]
tools: ToolStatus[]
agents: AgentStatus[]
update?: { // why it does not run controller_release yet. Absent when it does, and from older controllers
target: string // the version it is moving to
state: "waiting_idle" | "failed" | "restart_needed" // waiting_idle: a session on the machine is in the middle of a turn
problem?: string // human-readable, when it failed
}
}
type ProviderStatus = {
provider: AgentDefinition["provider"]
installed: boolean
version: string | null
auth: "ok" | "expired" | "missing" | "unknown"
auth_source: "local" | "sealed" | null // own login on the machine, or one delivered sealed
checked_at: Time
reason?: ReasonCode
}
type ToolStatus = { tool: string; state: "ok" | "missing" | "unauthenticated" | "unsupported" | "unknown"; reason?: ReasonCode }
// `git` and `gh`, then each vendor command-line tool (`cli_tools`) a session
// on the machine has set up: `missing` when its install failed,
// `unsupported` where its release has no build for the machine
// e.g. "gh", "git", "mcp:jira". unsupported: this machine cannot run
// Switch's helper for the tool (GitHub's on Windows)
type AgentStatus = {
agent_id: string
applied_revision: number | null // null = never applied
process: "pending" | "starting" | "running" | "stopping" | "stopped" | "crashed" | "failed"
attached: boolean // receiving its events on this controller's stream
sessions: { active: number; ids: string[] }
restarts_10m: number
oom_kills: number
directory?: string | null // absolute working directory it runs in; null before one was resolved. Absent from older controllers
since: Time // when it entered the current process state
reason?: ReasonCode // required when process is crashed or failed
detail?: string // human-readable. Never contains secrets
}
4. Operations (Management)
Explicit actions that aren't part of the desired state. Created by the Manager UI, the personal agent, or Management itself.
GET /v1/management/controllers/{id}/operations?state=pending → 200 { operations: Operation[] }
POST /v1/management/operations/{op_id}/claim → 200 Operation (with lease) | 409 already_claimed | 410 cancelled
POST /v1/management/operations/{op_id}/progress { message: string } → 204 // optional, renews the lease
POST /v1/management/operations/{op_id}/result OperationResult → 204
type Operation = {
id: string
kind: OperationKind
agent_id: string | null // null for machine-level kinds
params: OperationParams // shape depends on kind, see below
created_at: Time
lease_expires_at?: Time // set on claim. An expired lease is re-offered
}
type OperationKind =
| "agent.start" | "agent.stop" | "agent.restart" // params: {}
| "provider.recheck" // params: { provider }
| "provider.login" // params: { provider, method: "device_code" | "sealed" }
| "machine.collect_diagnostics" // params: {}
type OperationResult =
| { outcome: "succeeded"; output?: Record<string, unknown> } // e.g. provider.login → { verification_uri, user_code }
| { outcome: "failed"; error: { code: ReasonCode; message: string } }
Claim leases last 5 minutes and are renewed by progress. Every operation reaches a terminal result or expires. Nothing is left pending forever.
5. Tokens and secrets
Service tokens (Core)
Service tokens are issued on agent routes (§7), so one route serves a controller acting as an agent and a directly connected agent using its own key. Implementation: service-connections-v1.md, and service-connections-v2.md for services beyond GitHub.
GET /agents/{agent_id}/service-grants auth: controller token acting as the agent (§7), or the agent's own key
→ 200 { grants: ServiceGrant[] }
POST /agents/{agent_id}/service-tokens/{service} auth: as above. No body
→ 200 { token: string, expires_at: Time, expires_in: number, use_until: Time, resources: ServiceResources, grant_revision: number }
// Cache-Control: no-store. Every issuance is recorded
→ 403 grant_missing | not_assigned | forbidden // forbidden also: the service is switched off on this server
→ 404 connector_not_connected | not_found // not_found: no such service
→ 409 connector_revoked | grant_account_changed | managed_by_controller
→ 500 internal // the vendor's token outlived its catalog lifetime; not retryable
→ 503 internal // the vendor or the connection is unavailable
expires_inis the token's remaining life in seconds, as Core counts it. Time the token from when the answer arrived, not by comparingexpires_atwith your own clock.use_untilis when to ask again:expires_at, or an hour after the issue if that is sooner. A token may outlive it (a service whose tokens live longer than an hour), but it is not used past it, so Core's checks run at least hourly. Both fields are additive; a holder that predates them keeps usingexpires_at.- Minted and pass-through tokens. GitHub's token is minted for the one request and lives at most an hour. A pass-through service hands out its owner's own access token, shared by every agent they grant; it cannot be revoked per agent, and Core renews it while at least 15 minutes remain.
type ServiceGrant = {
service: string // catalog slug: "github", "atlassian"; later "google-workspace", …
access: "read" | "write"
tool_mode: "allow" | "deny" // allow: only `tools`; deny: every tool of the level except `tools`
tools: string[]
resources: ServiceResources
revision: number // moves on every change to the grant; a token answer names the one it was issued under
skill: { name: string; content: string } | null // the service's SKILL.md
mcp_servers: { name: string; url: string; headers: Record<string, string> }[]
// the vendor's MCP servers a session calls; [] for GitHub. Additive.
// `url` and `headers` are templates (below); absent headers mean
// { Authorization: "Bearer {token}" }
cli_tools: ServiceCliTool[] // the vendor's command-line tool a session's host runs; [] for most. Additive
}
type ServiceCliTool = { // as the catalog entry's `cli` block has it
name: string // the tool's name in the session, beside `switch` and any MCP server's
binary: string // the executable, run without a shell
token_env: string | null // the only place the token goes: this variable, in the run's own environment
env: Record<string, string> | null // instead, for a key service: each variable set from its template (below)
config_env: string | null // where the tool has one: a configuration folder made for the session
allow: string[] // a command's first argument is one of these
deny: string[] // first arguments, and flags refused anywhere in a command
path_flags: Record<string, "read" | "write"> // flags whose value is a local file, kept inside the session's folder
path_args: { after: string; direction: "read" | "write" }[]
// positional local files: the argument right after the word `after`
output_cap_bytes: number // more output goes to a file, whose path is returned
timeout_s: number
token_refused: { exit_code: number; json_path: string; value: number | string }
// a run that ends so asks for the token again, once
release: { // the pinned build every session runs
version: string
targets: Record<string, { url: string; sha256: string; path: string }>
// by "<platform>-<arch>" as Node names them: the archive (HTTPS),
// its SHA-256, which must match, and the binary's path inside it
}
}
type ServiceResources =
| { installation_id: number; repository_ids: number[] } // GitHub
| Record<string, never> // a service whose token cannot be narrowed
- Who gets a token. Core issues only for an agent that holds a grant to its owner's own connection. A controller must belong to that owner and be bound to the agent (§7); an agent's own key works only while it has no binding.
- When grants are read. The agent's host reads its grants when a session starts. No stream frame announces a change: the agent's watcher reads the grants every 30 seconds while it has live sessions, and restarts a session on its own conversation (once idle) when a service was granted or taken away, or its tools changed. While it holds a token, the host reads the grants again at most every 30 seconds, when a token is asked for, and drops the token once its grant's
revisionis not the token'sgrant_revision, so a widened, narrowed or removed grant reaches running sessions within that. A removed grant also fails the next fetch, and a GitHub token already issued is revoked at once. A pass-through service's token is its owner's own and cannot be revoked alone: a token already handed out stays valid at the vendor until it expires, and while the host cannot read the grants a removed grant stops a running session byuse_until, within the hour. credential.revokedis not used for grants. It revokes the controller itself.- Templates and key tokens. A template's
{token}is the token as handed out; any other{name}is a field of a key service's token. A key service (catalogadapter: api_key) hands out its token as compact JSON,{"public": {...}, "secret": {...}}: the fields the owner pasted (secret) and picked (public, the only ones a URL may name). The host renders each server'surlandheaders, or a tool'senv, from it, and redacts everysecretvalue on its own as well as the whole token. - Where tokens go. The controller keeps tokens in memory and serves them to a session's tools and helpers. It never writes one to disk, a CLI's arguments or its environment, except GitHub's, which
gitreceives from its credential helper andghfrom its wrapper. A service withmcp_serversnever reaches the CLI at all: the session's host serves each of them to the CLI on loopback, behind a key made for the run, asks for the token on each call and calls the vendor itself. A service withcli_toolsis the same: the host serves each tool on loopback, checks every command againstallow,denyandpath_flags, asks for the token on each run, and runsbinaryitself with the token only intoken_envof that run's environment.
Provider logins (Management)
GET /v1/management/controllers/{id}/provider-credentials/{provider}
→ 200 { provider: string, revision: int, sealed: SealedLogin } // Cache-Control: no-store
→ 404 provider_login_missing
type SealedLogin = {
alg: "X25519-HKDF-SHA256-A256GCM",
key_id: string, // first 16 hex digits of SHA-256(controller public key)
ephemeral_key: base64, // 32 bytes
nonce: base64, // 12 bytes
ciphertext: base64, // AES-256-GCM, tag appended
}
- The key. The controller makes an X25519 keypair at enrollment and sends
public_key. A controller enrolled before then registers it once withPATCH /v1/management/controllers/{id}{ public_key }. A different key afterwards is refused (409): the machine is enrolled again. A controller that keeps no secrets across starts (its credential handed over by a parent) registers none, and uses only the machine's own logins. - Sealing. The owner's client (Console) seals
{ kind: "api-key" | "setup-token" | "auth-json" | "vertex", credential }to that key (avertexlogin, Claude only, holds{"v": 1, "project", "region", "credentials"}as JSON,credentialsbeing a Google service account key orauthorized_usersign-in): an ephemeral X25519 key,HKDF-SHA256(shared, salt = ephemeral public ‖ controller public, info = "switch provider login v1"), and AES-256-GCM withaad = "switch-provider-login-v1\n<controller id>\n<provider>". The server checks the envelope's shape and thatkey_idnames the machine's current key, stores only the ciphertext, and can never open it. The same construction is incore/switch_core/management/sealed_logins.py(checks) and@switch-console/agent-providerssealed-login.ts(seal and open). - On demand. The owner gives a machine a login with
PUT /gateway/management/controllers/{id}/provider-logins/{provider}{ sealed }, which answers{ login: { provider, revision, key_id, updated_at }, operation }. The operation isprovider.login{ provider, method: "sealed", revision }: the controller fetches the login, opens it, checks the provider signs in with it, and reportssucceededwith its provider status, orfailedwithprovider_login_missing,provider_login_expiredorinternal.GET …/provider-loginslists what was given (never the ciphertext).DELETE …/provider-logins/{provider}takes it back and queuesprovider.recheck. Revoking the machine deletes its logins. - The controller prefers a local login (
auth_source: "local"). It uses a sealed one (auth_source: "sealed") only for a provider it has no local login for, and only once the provider signs in with it. An agent using one gets it with its relay credentials, and is restarted when the login changes or is withdrawn. - On Switch EC2, the same sealed logins apply: no KMS is involved.
- When a CLI refreshes and rotates a login on the machine, the controller doesn't upload it back.
6. Event stream (Core)
One stream per controller. It carries events for every agent assigned to it.
POST /v1/controllers/{id}/connection
{ client: string, client_version: string,
cursors: Record<agent_id, number | "head"> } // where to resume each agent. Missing = "head"
→ 201 { connection_id: string, generation: number, heartbeat_interval_s: number,
attached: string[] } // agents Core attached to this connection
WS /v1/controllers/{id}/connection/ws?connection_id=…&generation=…
Authorization: Bearer <access token>
← { event: string, data: object } // frames below, one JSON text message each
← { event: "ping", data: {} } // every heartbeat_interval_s
→ { type: "pong", cursors: Record<agent_id, number> }
// the beat: alive, and how far each agent has read
← { event: "refused", data: { status, detail: { code, message } } }, then close 4000 + status
// 404 unknown_connection, 409 taken_over | stale_generation,
// 401 controller_revoked | token_expired, 426 protocol_unsupported
← { event: "evicted", data: { code, reason } }, then close
// a pong refused: taken_over is terminal for this client,
// the rest (no_stream, unknown_connection, …) reopen
close 1012 // the server is restarting: reconnect within a second
Connection transitions are recorded. Whichever server process holds the
socket records, once each, when it attached and when and why it went
(socket_closed, server_shutdown, heartbeat_lapsed, taken_over,
revoked) on the controller's row. Pongs are not recorded. A controller
shutting down needs to say nothing: its socket closing is recorded at once,
and so is a dropped one, which reattaching records as connected again. Every
process reads the machine's state from that record and the holding process's
lease (§8, Machine state), so it does not depend on which process holds the
socket.
Attachment is automatic. Core attaches the agents currently bound to this controller (§7), and attaches or detaches them as bindings change. There's no per-agent subscribe call.
Core knows only whether an agent is connected. A controller-backed agent is connected while its controller's socket is attached and answering pings, its owner has it running, and the controller is not revoked. Core does not know where the agent's sessions are, or whether one is running: the open and the pong carry no session map, and a body that still sends placements is refused with 422 validation_error (the one exception to ignoring unknown fields, so a controller still reporting sessions is noticed rather than silently dropped). When a connected agent is addressed, Core delivers the message and posts nothing; if a session has to start, the agent's host posts "Starting a session…" itself. When it is not connected, Core tells the room why: stopped by its owner, its machine removed, or its machine offline.
Frames. event is the type and data is the JSON object below without its type.
type StreamEvent =
| { type: "agent.event"; agent_id: string; seq: number; event: AgentProtocolEvent }
// payload unchanged from today's per-agent stream (message, room_join, command, …)
| { type: "agent.gap"; agent_id: string; rooms: string[]; reason: "overflow" | "restart" | "unknown" }
// events were lost. The controller tells the agent to read context
| { type: "agent.attached"; agent_id: string; from_seq: number }
| { type: "agent.detached"; agent_id: string; reason: "unassigned" | "superseded" | "deleted" }
| { type: "assignment.changed"; revision: number }
| { type: "operation.pending"; operation_id: string; kind: OperationKind; agent_id: string | null }
| { type: "credential.revoked" }
Cursors are per agent, because each agent keeps its own sequence in Core's buffer. That's why resume uses the cursors map and not Last-Event-ID.
7. Acting as an agent (Core)
- Binding. Management tells Core which controller may act for an agent, through Core's narrow internal interface:
bind(agent_id, controller_id, revision)andunbind(agent_id, revision). Core stores the binding and never reads Management's tables. - Existing routes, new principal. Every existing
/agents/{agent_id}/...route accepts a controller access token: message, media, typing, history, participants, tasks, moderation, mediation,events/report,runtime-state,connection/subscribe,connection/placements.- Core checks
binding(agent_id).controller_id == token.controller_id. - If that fails, it returns
403 not_assigned. - Per-agent API keys keep working for agents with no binding: third-party agents and plugins.
- Core checks
- Not used by controllers: the per-agent
GET /agents/{agent_id}/eventsstream. §6 replaces it. - CLIs never call these routes directly. The controller serves the Switch tools to its CLIs and makes the calls itself.
Sessions are not managed through this contract. A session and its transcript live with the host that runs it, and Core keeps no server-side session state. In-room session commands (!reset, !compact, !interrupt) keep reaching the session through the agent's own watcher stream, as session_command frames. How the Console reaches a session on a machine it cannot connect to directly (a cloud VM) is an open question, outside this contract.
8. Semantics
Reconcile. On every pull, for each agent:
- Not running and
desired_state = running: start it. - Running but absent or
stopped: stop it. - Running at an older
revision: restart it with the new definition. Model and instructions apply on restart.
After acting, send status.
Fencing and handover.
- An agent is bound to exactly one controller.
- To move it, Management first unbinds it from A at revision r+1, and waits for A to report it stopped, or for A to go stale.
- Then it binds the agent to B at revision r+2. B refuses to start a revision older than one it has already applied.
Machine state. Read from the recorded connection (§6), not from the status report:
online: its socket is attached, and the server process holding it is alive (its lease renewed within 15 s, and not stopped).offline: it has connected before, and its socket went (closed, a lapsed heartbeat, a takeover not replaced, the server shutting down), or the server process holding it stopped or died. A controller that stops shows offline at once when its socket closes, within about 8 s when its heartbeat lapses with the socket still open, and within 15 s when the process holding its socket died.unknown: no connection has ever been recorded for it.revoked: its credential is gone.
While it is not online Management:
- shows it, and its agents, as offline or unknown,
- refuses new placements on that controller,
- may reassign its agents only if their definition allows it. Cloud agents stay put.
The status report carries the details (providers, disk, sessions, agents) and is what placement reads them from.
Placement checks. Before binding, Management checks the target. It refuses with a reason if:
- the controller is not
online, or its last status is older than 3 ×report_within_s, - the provider is not installed, or its login is not
ok, - there's no session capacity, or the disk is nearly full.
The personal agent relays that reason to the user as is.
Offline. The controller keeps running its cached assignment. On reconnect it opens a new connection with its cursors, pulls the assignment, reconciles, and sends status. Core returns agent.gap where history was lost.
Ordering.
agent.eventframes are ordered per agent, not across agents.assignment.changedmay arrive before Core has attached a newly bound agent. The controller starts the agent anyway and waits foragent.attached.
Limits (initial):
- Status ≤ 64 KiB. Definition ≤ 32 KiB. 200 agents per controller.
- At most 1 status report per second, with bursts coalesced.
Compatibility.
- Adding fields or enum values is a minor change and needs no version bump.
- Removing or renaming anything, or changing a meaning, bumps the protocol version. The server supports N and N-1.
9. Reason codes
| Code | Where | Meaning |
|---|---|---|
protocol_unsupported |
any | Controller protocol is outside the server's range |
token_expired / controller_revoked |
auth | Re-exchange the credential / stop and exit |
not_assigned |
Core, Management | This controller isn't bound to that agent |
taken_over / stale_generation / unknown_connection |
stream | Another connection took over / outdated / reopen |
already_claimed / cancelled / lease_expired |
operations | Operation is no longer this controller's |
provider_not_installed / provider_version_unsupported |
status, placement | CLI missing, or too old |
provider_login_missing / provider_login_expired |
status, placement | No usable login |
connector_not_connected / connector_revoked |
tokens | User hasn't connected the service, or revoked it |
grant_missing |
tokens | The agent has no grant for that service |
grant_account_changed |
tokens | The owner re-linked a different account at the vendor; the grant must be made again |
forbidden |
any | Authenticated, but not allowed this action, and message says why |
definition_invalid |
status | The definition can't be applied, and detail says why |
repo_clone_failed |
status | Clone or worktree failed |
crash_loop |
status | 5 restarts in 10 minutes, stopped retrying |
out_of_memory |
status | Killed by the memory limit |
disk_full / capacity_exceeded |
status, placement | No disk / no session slots |
controller_offline |
placement | Target is not online, or its last status is stale |
internal |
any | Server or controller bug, with retryable set honestly |
10. Mapping to today
| Contract | Exists today | Change |
|---|---|---|
| §1 enrollment, EC2 | #556 machine secret and capability | Generalise to all controller kinds |
| §2 assignment | #556 GET /hosted/machines/{id}/agents |
Generalise, and add revisions per agent |
| §3 status | #556 /heartbeat, process_state, OOM and restart counts, /provider-status |
Merge into one snapshot |
| §4 operations | #556 HostedOperation, /operations/{id}/claim and /result |
Generalise the kinds |
| §5 tokens | #556 /github-credential |
Generalise to services, on the agent route /agents/{id}/service-tokens/{service}. Sealed provider logins are new |
| §6 stream | Per-agent GET /agents/{id}/events with connection, generation, beat and takeover |
One stream per controller, as a read-side merge of the per-agent buffers |
| §7 act as | Per-agent API keys on /agents/{id}/... |
Add the controller principal and the binding check |