Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Agent management and agent controllers: v1 implementation spec
Status: in progress. This is the implementation spec for the first slice of the
agent-controller design. It covers the Core management module behind a flag and the
headless agent controller. The full target contract is
controller-contract-v1.md (to be added alongside); this file says what v1 builds, and
where it deliberately stops short.
Shape
- Management (Core package
switch_core/management/, off unless theagent_managementfeature flag is on): the source of truth for managed agents. It holds agent definitions, which controller each one runs on, controller enrollment and credentials, controller status, and operations. - Agent controller (
console/packages/agent-controller, a Node CLI): one per machine. It pulls its assignment, runs each assigned agent through the existing shared-host agent host (the same--watch-*runtime the Console sidecar uses), and reports status. - Core's messaging path is unchanged. Each managed agent still holds its own per-agent agent host connection to the agent bridge.
v1 scope and deliberate deviations from the target contract
| Target contract | v1 | Why |
|---|---|---|
Controllers act as agents on /agents/{id}/... with a controller token |
Not in v1. The controller fetches a per-agent API key from Management for each bound agent. Every fetch rotates the key, which invalidates any earlier holder | The agent host and session hosts read the agent token once, from the credentials file, and cannot refresh a short-lived token. Moving to scoped tokens needs a runtime change first |
| One SSE stream per controller carrying agent events | The controller stream carries only nudges (assignment.changed, operation.pending, credential.revoked). Agent events stay on per-agent agent host streams |
Avoids touching message delivery. That is roadmap step 7 |
| Connector tokens, sealed provider logins | Not in v1. Service tokens are specified in service-connections-v1.md |
Later steps |
| Enrollment by EC2 machine secret | Not in v1. Supported: Console sign-in (gateway) and one-time code (headless) | |
| Operations | agent.restart and provider.recheck only. Core rejects other kinds with 400 operation_unsupported |
|
| Per-tenant flag | Deployment-wide env flag | No per-tenant flag mechanism exists yet |
Core
Config (config.py)
agent_management_enabled: whether theagent_managementfeature flag is on (FEATURE_FLAGS_ENABLED).AGENT_MANAGEMENT_ENABLED=true, the setting it replaced, stops startup.controller_token_secret: str | None = None(CONTROLLER_TOKEN_SECRET). Required when the flag is on: a model validator raises if it is missing or shorter than 32 chars. It is separate fromjwt_secret_keyon purpose.controller_status_interval_seconds: int = 60. Returned to controllers asreport_within_s. Placement needs a status within 3 intervals. Whether a machine is online is read from its recorded connection instead (see "Liveness" below).
With the flag off, none of the routes below are mounted, and the middleware branch is inactive.
Tables (all TenantScoped, RLS like every scoped table, one migration)
agent_controllersid,owner_id(users),name,descriptionnull (the owner's note on what the machine is for),kind(console|daemon|ec2),platformJSONB null,versionnull,public_keynull.api_key_id: the credential, anapi_keysrow of typecontroller, holding the hash only.assignment_revisionint default 0,status_seqbigint null,statusJSONB null.last_seen_atnull (the last status),revoked_atnull,created_at,updated_at.- The connection, as the switch-core process holding its socket last recorded it (all null
until the first):
connection_id,connection_process_id,connected_at,disconnected_at,disconnect_reason(socket_closed,server_shutdown,heartbeat_lapsed,taken_over,revoked).
switch_core_processes(global, no tenant): each switch-core process's lease,id,started_at,beat_at,stopped_atnull.agent_controller_enrollment_codes:id,owner_id,api_key_id(anapi_keysrow of typecontroller_enrollment, so the existing global hash → tenant lookup works),expires_at,used_atnull,controller_idnull,created_at.agent_definitions:id,agent_id(FK agents, cascade, unique per tenant),owner_id,controller_id(FK agent_controllers, null = unplaced),revisionint,desired_state(running|stopped),definitionJSONB,created_at,updated_at.agent_controller_operations:id,controller_id,agent_idnull,kind,paramsJSONB,state(pending|claimed|succeeded|failed|cancelled|expired),lease_expires_atnull,resultJSONB null,created_by(users),created_at,updated_at.
Controller and enrollment api_keys rows must not appear in the user's API-key list,
and must not be revealable. encrypted_key holds an empty string for these types, because
nothing may decrypt them.
Credentials and tokens
- Controller credential:
swcc_+token_urlsafe(32). It is stored as a sha256 hash, as anapi_keysrow of typecontroller. - Enrollment code:
swce_+token_urlsafe(18). Single use, valid for 10 minutes. - Access token:
swct_+ an HS256 JWT signed withcontroller_token_secret.aud="switch-controller", claimscid,tid(tenant),oid(owner),iat,exp.- Valid for 1 hour.
- Every POST/PUT that creates something accepts
Idempotency-Key. v1 may treat that as best effort, but naturally idempotent routes (claim, result) must be idempotent.
Agent-bridge routes (bearer). Errors use {"error": {"code", "message", "retryable"}}
Public (they authenticate through the body):
POST /v1/management/controllers/enroll- Body:
{proof:{kind:"enrollment_code", code}, controller:{kind, name, description?, platform, version}, public_key?}. nameis trimmed and must not be blank (at most 200 characters);descriptionis optional, at most 500 characters, and blank means none.- Returns
201 {controller_id, credential}.
- Body:
POST /v1/management/controllers/{id}/token- Body:
{credential}. - Returns
200 {access_token, expires_at}, or401 controller_revoked | invalid_credential.
- Body:
Controller access token ({id} must match the token's cid, otherwise 403 forbidden):
POST /v1/management/controllers/{id}/credential/rotatereturns{credential}.PATCH /v1/management/controllers/{id}- Body:
{name?, description?}, at least one: the controller renames its own machine (switch-agent-controller set-info). The same validation and effects as the owner'sPATCH /gateway/management/controllers/{id}, including the rename reaching Core's bindings. Returns the controller as the owner's list shows it.
- Body:
GET /v1/management/controllers/{id}/assignment- Honours
If-None-Match; returns200with anETagheader, or304.
- Honours
PUT /v1/management/controllers/{id}/status- Body: a
StatusReport. - Returns
{assignment_revision, report_within_s, controller_release}.controller_releaseis{version, url, sha256}, the controller package the deployment names (CONTROLLER_RELEASE_*), or null when it names none and for aconsolecontroller, which updates with Switch Console. - An older
seqis ignored, and the response is still 200.
- Body: a
GET /v1/management/controllers/{id}/operations?state=pending- Expired leases are re-offered.
POST /v1/management/operations/{op}/claim- Returns the operation with
lease_expires_at(5 min), or409 already_claimed | 410 cancelled.
- Returns the operation with
POST /v1/management/operations/{op}/progressrenews the lease. Returns204.POST /v1/management/operations/{op}/result- Body:
{outcome:"succeeded", output?} | {outcome:"failed", error:{code,message}}. - Returns
204.
- Body:
POST /v1/management/controllers/{id}/agents/{agent_id}/credentials(v1 only)- Returns
{agent_id, api_key}, or403 not_assigned. - Rotates the agent's API key (
AgentCore.rotate_agent_api_key).
- Returns
GET /v1/controllers/{id}/events(SSE)- The first frame is
connection_state {controller_id, assignment_revision, report_within_s}. - Then
assignment.changed {revision},operation.pending {operation_id, kind, agent_id}, andcredential.revoked {}. - A
: keepalivecomment is sent every 15s. - Notifications are process-local (an in-memory notifier, since Core is single process). A controller resyncs fully on every reconnect.
- The first frame is
Gateway routes (cookie, get_current_user, owner-only)
POST /gateway/management/enrollment-codesreturns{code, expires_at, server_url}.server_urlis the agent bridge's public origin (GATEWAY_PUBLIC_URL), the--serverto enroll with, or null when it is not configured; the gateway page's own address is not a stand-in, since a gateway need not serve the agent bridge.POST /gateway/management/controllers- Console enrollment by a signed-in user.
- Body:
{name, description?, kind:"console", platform, version, public_key?}. - Returns
{controller_id, credential}.
GET /gateway/management/controllers- Returns the list, each with its
description, derivedstate(online|offline|unknown|revoked, see "Liveness" below),last_seen_at(its last status),connection({connected_at, disconnected_at, disconnect_reason}or null when it never connected;disconnect_reasonis alsoserver_shutdownorserver_lostwhen the row shows it open but the process holding it stopped or died), its laststatus, andworkspaces_dir: the directory the controller makes agents' workspaces in, from that status (machine.workspaces_dir), null when it has not reported one.releaseis{wanted, running, current}: the controller version the deployment names, the one the controller last reported, and whether they are the same; null when the deployment names none, and for aconsolecontroller. How the controller's move to it is going is in its status'supdate({target, state, problem}), when it reports one.
- Returns the list, each with its
PATCH /gateway/management/controllers/{id}- Body:
{name?, description?}, at least one. Renames the machine and/or changes its description;description: null(or blank) clears it. Same limits as at enrollment;422 validation_errorotherwise. Someone else's controller is404. - A new name also reaches Core's bindings (
ControllerPresence.rename_controller), since it is the name a room is told when the machine is offline.
- Body:
DELETE /gateway/management/controllers/{id}- Revokes it: deletes the credential, sends the
credential.revokednudge, and leaves definitions placed but shown.
- Revokes it: deletes the credential, sends the
GET /gateway/management/agentsandGET /gateway/management/agents/{agent_id}.- Each agent's
statusis its entry in its controller's last status report, withdirectoryalways present: where the agent runs, null until the controller resolved it.
- Each agent's
POST /gateway/management/agentscreates and places a new agent.- Body:
{name, description, display_name?, controller_id, desired_state, definition}. - It registers the agent through
AgentCore.register_agent, using the known-agent spec for the provider (claude→claude-code,codex,opencode,antigravity,cursor), withowner_only=True. A managed agent always starts a session when addressed; there is no setting for it.
- Body:
PUT /gateway/management/agents/{agent_id}- Adopts an agent the user already owns, or replaces its definition and placement.
PATCH /gateway/management/agents/{agent_id}- Changes
definition,desired_stateorcontroller_id. - Moving bumps both controllers'
assignment_revision. The new controller's credential fetch rotates the key, which fences the old one out.
- Changes
DELETE /gateway/management/agents/{agent_id}- Stops managing the agent: removes the definition, and the controller stops it. It does not delete the agent.
POST /gateway/management/operationsandGET /gateway/management/operations?controller_id=.GET /gateway/management/advanced-configreturns each provider's advanced-configuration schema,{"providers": {"claude": {"fields": [...]}, "codex": ..., "opencode": ..., "cursor": {"fields": []}, "antigravity": {"fields": []}}}(see Advanced configuration below), andGET /gateway/management/providersthe providers in order, each with its label and the same fields. These two are served whether or not agent management is on: Switch Console builds the advanced-configuration form of the agents it runs itself from them too.
Placement checks run on create, adopt and move, and on a change to running. Each failure returns 409 with a reason:
controller_revokedcontroller_offline: not online (never connected, its socket went, or the process holding it stopped), or no status, or the last status is staleprovider_not_installedprovider_login_missingorprovider_login_expired
A provider whose auth is unknown passes.
The working directory is always named. On create, and on every change through PUT, PATCH
or update_agent_detail, a definition whose directory is null gets
<workspaces_dir>/<agent name>, the controller's own workspace for the agent (its
DataLayout.workspace(name)), when the target controller has reported workspaces_dir.
A move clears a directory equal to the old controller's workspace for the agent before filling
in the new one's. A controller that has not reported workspaces_dir leaves it null, and still
reports the directory it resolved in the agent's status. The controller makes a missing
directory inside its workspaces directory; any other directory must already exist.
Any change that affects a controller bumps its assignment_revision and nudges it.
Definition (v1)
{"provider": "claude|codex|opencode|antigravity|cursor",
"model": null, "advanced_config": {}, "instructions": "", "auto_mode": true,
"auto_approve": false, "directory": null, "isolation": "shared"}
auto_mode (default true on create) asks the provider for its own automatic review:
safe actions run, risky ones still ask a person. auto_approve is bypass, every permission
check skipped, and wins over auto_mode. A definition stored before auto_mode existed has
no such key and reads as false (schemas.stored_definition): the managed-agent view, the
assignment entry and an agent's update all fill it in that way, so an existing agent keeps
its behaviour until someone turns auto mode on.
Advanced configuration
advanced_config carries the provider's "Advanced configuration", the per-provider settings
Switch Console offers for its own agents. The server owns one fixed schema per provider
(management/advanced_config.py), checks every create and update against it whatever
machine runs the agent, and serves it at GET /gateway/management/advanced-config and
through the get_advanced_config(provider) agent operation. Switch Console and the
controller hold no copy of the fields; their provider plugins only apply values, by key.
Controllers report nothing about settings; they apply what they are given, and report
definition_invalid for a key their build does not apply or a value of a shape it cannot
apply, rather than starting the agent without it.
- Each served field is
{key, label, type, help, placeholder, options, catalogue}.typeistextortextarea(a string),number(finite),boolean,list(strings) orselect(a string amongoptions).optionsis[{value, label}]for a select, null otherwise; its first entry is{"value": "", "label": <unset label>}("Default", "Inherit", ...), which a form shows for "unset" and which is not an accepted value.catalogueis null,{kind: "model"}, or{kind: "model-variant", model_field}. - Claude:
tools,disallowedTools(lists),permissionMode,color,maxTurns,background,isolation(Claude's git worktree, unrelated to the definition's ownisolation),effort,memory. Codex:effort,verbosity,reasoningSummary,webSearch("true"/"false"). OpenCode:variant,temperature,topP,maxSteps,webSearch,smallModel. Cursor and Antigravity: none.modeland the instructions stay top-level definition fields. - An unset field is left out, never null,
""or[]. At most 32 keys, strings at most 4096 characters, lists at most 64 items of 1 to 256 characters. An unknown key, a wrong type or a value outside a select's options is refused as422 validation_error, the message naming the provider and the field. A definition is replaced whole, so changingproviderneeds anadvanced_configthe new provider takes.
The assignment entry adds the agent's name, display_name and icon_url, read from the agents row.
Reason codes
These are the codes from the contract, plus forbidden, invalid_credential, enrollment_code_invalid,
operation_unsupported, not_found and validation_error.
Contract fixtures
core/tests/switch_core/fixtures/agent_controllers/ holds one JSON file per wire message.
- Core tests check that real route responses match the fixture's shape, with volatile values normalised.
- The controller's TypeScript tests parse the same files with its schemas.
Agents managing agents
An agent may act on its owner's agent management through four agent operations. They
exist only while management runs: they are declared in their own operation group
(registry.gated_operation), and Management.install enables it by handing Core
management's implementation of AgentManagementPort
(bridges/agent/protocol/agent_management.py, implemented by
management/agent_operations.py). With the flag off they are on neither door: not in
GET /ops, 404 on POST /ops/{name}, and not listed or callable over MCP (the MCP server
registers every declared operation and filters by the registry per request).
list_machines(): the owner's controllers that are not revoked, each{id, name, description, kind, state, last_seen_at, providers: [{provider, installed, version, auth}], agents_running}. Revoked machines are left out rather than flagged; the managed-agent list still shows an agent placed on one, with the machine'sstate: "revoked".agents_runningcounts the agents the last status reports asrunning, null before any status.get_advanced_config(provider): the provider's advanced-configuration fields, as the gateway serves them.create_agent(name, description, machine, provider, model=None, advanced_config=None, instructions="", directory=None, auto_mode=True, auto_approve=False, display_name=None, icon_url=None, start=True): builds the sameCreateManagedAgentRequestthe gateway route takes and callsManagementService.create_managed_agent, so validation, placement checks, owner-only addressing and registration are the gateway's.machineis an id among the owner's controllers (any state; a revoked one is then refused ascontroller_revoked), or else an exact name among those not revoked; a shared name is refused with the candidates listed. The agent is owned by the calling agent's owner, withauto_sessiontrue and the capability off. Returns{agent_id, name, machine: {id, name}, desired_state, hint}.list_managed_agents(): the owner's managed agents, each{agent_id, name, display_name, description, provider, model, advanced_config, auto_mode, auto_approve, machine: {id, name, state} | null, desired_state, actual: {process, reason, detail, applied_revision, since, directory} | null, revision},actualbeing the agent's entry in its controller's last status, plus top-leveldirectory, the one the definition names.
The capability. agents.can_manage_agents (boolean, default false) gates all four,
listing included since it discloses the owner's machines. It is the agent's, read from its
row on every call, so it holds however the call authenticated: the agent's own key or a
controller acting as the agent. An agent with no owner is refused. Only the agent's owner
sets it, with PUT /gateway/agents/{agent_id}/can-manage-agents {enabled} (not an admin:
the agent would act on the owner's own machines); the agent detail carries it as
can_manage_agents. An agent created through create_agent (or the gateway) starts with
it off.
Where owners set things. The gateway's agent page has an "Agent management" section with the capability switch (shown only where management runs), and the Machines page an edit action for a machine's name and description. In Switch Console, an agent's settings carry the same switch for Switch agents, and the "This computer as a machine" card shows and edits this computer's name and description. Console's own enrollment sends no description.
Refusals. Without the capability: 403, "Agent X is not allowed to manage agents. Ask
your owner to enable 'can manage agents' for X ...". Everything management refuses is an
AgentManagementRefused (a ValueError, so 400 over HTTP) whose message starts "Nothing
was created:", says why in terms of the machine (placement codes are reworded: the machine
has not reported recently, the provider is not installed or not logged in there, ...) and
ends with the reason code in parentheses. Another person's machine, by id or name, gets
exactly the answer a missing one does.
Headless agent controller (console/packages/agent-controller)
- CLI
switch-agent-controller, released as its own npm package onswitch-agent-controller-v*GitHub releases, with aninstall.sh(see RELEASING.md):enroll --server <agent-bridge-url> --code <code> [--name] [--description] [--data-dir] [--secret-store]run [--data-dir] [--env-file] [--agent-runtime default|separate-user]set-info [--name] [--description] [--data-dir]: renames the machine and/or changes its description on the server, with the controller's own credential, and records the new name locally.status [--data-dir]install-service/uninstall-service: a systemd user unit or a launchd agentinstall-service --separate-users/uninstall-service --separate-users: as root, once, on Linux with systemd and polkit; see "Each agent as a Linux user of its own" belowdoctor: what the machine lacks to run agentsupdate [--check]: the newest release, from GitHub
- Data dir:
SWITCH_CONTROLLER_DATA_DIR, otherwise the OS default.- macOS:
~/Library/Application Support/Switch/agent-controller - Linux:
$XDG_STATE_HOME/switch/agent-controller, or~/.local/state/switch/agent-controller - Mode 0700.
- macOS:
- Store:
node:sqlite, one file. It holds identity, the assignment cache, per-agent applied revision and runtime state, and the status seq. It is a cache that can be rebuilt from the server. - Secrets: behind a
SecretStoreinterface: the macOS keychain (the default on a Mac), the desktop keyring throughsecret-tool(on request), or a file backend (0600, the default on Linux) that logs a warning at startup. The data directory records which oneenrollused. - Run loop:
- Exchange the token, refreshing it before expiry. On
controller_revoked: stop all agents, wipe the credential, and exit non-zero. - Open the nudge stream, reconnecting with jittered backoff capped at 8 s and reset whenever a stream attaches: every agent is offline while it is down.
- On connect and on
assignment.changed: pull the assignment with ETag, then reconcile. - On
operation.pending: list, claim, execute and report. - As a safety net, resync fully every 10 minutes.
- Exchange the token, refreshing it before expiry. On
- Reconcile, per agent:
- Running, and not applied or at an older revision:
- Ensure the credentials: fetch from the credentials endpoint if there is no local file, or after an auth failure.
- Write them to
<data>/agents/<id>/credentials.json(0600), outside the agent's working directory. - Ensure the working directory:
definition.directory, otherwise~/.switch/agents/<server>/<name>, where<server>is the server's address (localhost-8000,switch.example.com). A missing directory inside that folder is made; any other must exist. - Write the agent host root
<data>/agent hosts/<id>/withwatch.json {enabled:true, spawn:true}and aSharedHostConfigtemplate, as the Console builds. - Start the agent host (
runAgentHost) in the controller's process, after stopping the running one when the revision changed. Its sessions are the controller's child processes.
- Stopped or removed: write
watch.json {enabled:false}, stop the agent host and its sessions, and delete the credentials of removed agents. - Nothing an agent runs outlives the controller: stopping the controller stops every agent host and session, and the next run starts them again from their journals and confirmed cursors.
- Running, and not applied or at an older revision:
- Status: sent on every change, and every
report_within_s.- Machine: os, arch, disk, memory, sessions, and
workspaces_dir(~/.switch/agents/<server>, absolute). - Providers: installed via a PATH lookup, auth via the bundle's
--probe, cached for 10 min.provider.recheckforces a probe. - Agents: read from each running agent host's state and
supervisor/failure.json, mapped to the contract's process states and reason codes, withdirectory, the working directory its agent host was configured with.
- Machine: os, arch, disk, memory, sessions, and
- Operations:
agent.restartrestarts the agent host.provider.recheckforces a probe and reports. - Provider logins given to the machine (
sealed-logins.ts, contract §5):enrollmakes an X25519 keypair and sends the public half; a controller enrolled before registers it once (PATCH .../controllers/{id} {public_key}). The owner's Console seals a login to it; Core stores the ciphertext (sealed_provider_logins) and queuesprovider.login {provider, method: "sealed"}, which the controller answers after opening the login and probing the provider with it.ProviderStatusesprefers the machine's own login and falls back to a given one (auth_source: "sealed");ensureRelayCredentialswrites it into the agent's credentials (providerLogin),startAgentputs its environment in the template and runs the agent isolated, and the agent host writes its login file (readProviderLogin,materializeHostedProvider). - Each agent as a Linux user of its own (
--agent-runtime separate-user,separate-users.ts,systemd-runtime.ts): root sets up once a pool of system userssa<uid>-NNin a groupswitch-agents-<uid>that only the controller also joins, a template unitswitch-agent-<uid>@.service, a polkit rule letting the controller's user start, stop, restart and reset only those units, and the controller as a system service of its user. The controller then needs no root. Each agent claims a free pool user (kept in the store'sagent_users; none free iscapacity_exceeded) and runs as that user's unit, with systemd restarting it, seeing only its own directory, always at<agents dir>/agent, so the paths it records stay valid when it later runs as another user. The controller writes itsconfig.jsonandwatch.jsonthere (sticky directory, group-readable files) and the relay credentials and provider environment the unit loads (LoadCredential=,EnvironmentFile=); the agent host writes its health and records group-readable (SWITCH_HOST_SHARED_GROUP=1). The unit hides the home directories, the controller's data and the other agents (their processes too,ProtectProc=invisible), blocks the instance metadata address, and makes the rest of the system read-only. A removed agent frees its user, and its directory moves toreleased/<agent id>until it comes back; before an agent starts, root hands it the files in its directory that another pool user owns. Provider logins are the provider settings in the controller's environment only: the controller user's own logins are in a home the agents cannot see.
Step 10, option B: controller-backed agents on one stream per controller
Decided after v1. This replaces the v1 per-agent key workaround and the nudge-only stream. The flag and everything else above stay as they are.
Model
- Controller-backed agent: an agent whose
agent_definitions.controller_idis set. Core treats it differently from a directly connected agent:- It has no per-agent connection in
AgentConnectionRegistry, no placements and no room claims. - Presence comes from its controller. The agent is connected while its controller's stream is attached and its heartbeat is fresh, its owner has it running, and the controller is not revoked. That, and which rooms it is a member of, is all Core knows: where its sessions are, and whether one is running, is the controller's business.
- It has no per-agent connection in
- Directly connected agent: an agent with no controller. Nothing changes for it.
- Its per-agent API key cannot open an event stream while the agent is controller-backed
(
409 managed_by_controller). The key-fetch route (POST /v1/management/controllers/{id}/agents/{agent_id}/credentials) is removed, and so are the controller's credential files.
The Core / Management boundary
- Core owns an in-memory
ControllerPresence, inbridges/agent/protocol/. It records which controller each agent is bound to, and whether each controller's stream is attached and when it last beat. - Management fills it at startup (all bindings) and on every binding change, through a narrow API. Core never imports Management and never reads its tables.
- Every presence reader in Core asks
ControllerPresencefor controller-backed agents and theAgentConnectionRegistryfor the others:- statuses (LIVE / DISCONNECTED)
- the agent client's reachability replies (never a "Starting a session…" promise: the agent's host posts that itself)
- the bridges'
agent_online - role leases (a lease held by a controller-backed agent lives while the agent is live)
- probes and snapshots
Acting as an agent
- A controller access token is accepted on every agent route:
/agents/{agent_id}/..., includingops, media, typing and history/agent-sessions/..., where the agent comes from anX-Switch-Agent-Idheader
- A central check in the middleware requires the agent to be bound to that controller now.
Otherwise the request fails with
403 not_assigned. It then setsscope["agent"], so the handlers stay unchanged. - Room context for operations: a controller sends
X-Switch-Room-Id, meaning the room the calling session works in, which the controller tracks locally. Core checks that the agent is a member and uses it where a session selector would have resolved a room. connect_to_roomfor a controller-backed agent only checks membership and returns the room context. It claims nothing.
The controller stream (GET /v1/controllers/{id}/events)
- Open:
POST /v1/controllers/{id}/connectionwith{cursors: {agent_id: seq | "head"}}. It returns{connection_id, generation, heartbeat_interval_s, agents}. - Takeover: reopening takes over, with
generationfencing like today's agent connections. - Beat:
POST /v1/controllers/{id}/connection/beat {connection_id, generation, cursors}, every 2 s, with a 6 s TTL. A lapse makes all its agents not live. - Frames. Every frame carries
agent_id, plus the agent's own sequence where it has one:agent.event: today's domain event payload andsequence, plusmissedcounts computed as today, with one counting reader per controller stream and agent.agent.gap: today's gap fields.agent.session_command: in-room commands such as!resetand!compact, withroom_id. The controller routes it to the session working in that room.agent.approval_outcomeagent.attached {from_seq, rooms},agent.detached {reason}andagent.rooms {rooms}(membership changed).- Plus the management nudges:
assignment.changed,operation.pending,credential.revoked.
- Reading: a read-side merge over the existing per-agent
EventBuffer, from each agent's cursor,filter=all(the controller filters locally). There is no buffer per controller. Bindings changing mid-stream attach or detach agents live.
Agent hosts in the controller's process, and the local relay
- Each agent's definition says where its agent host runs:
isolation: "shared"(the default) in the controller's process, as below;isolatedin a process of its own, which reaches the same hub over a WebSocket on the relay's port (/hub). Cloud machines run every agent isolated, as a systemd unit. Changing an agent's isolation restarts it the other way. - One upstream stream. Each agent's agent host runs inside the controller's process and is handed
its events from that stream directly (
AgentHub): in order, filtered to what addresses the agent, with gaps, resets, room controls and approval outcomes. Events that arrive while its agent host is not running are held (bounded); its cursor moves only once the agent host has taken an event. The agent host states its sessions' rooms in memory, for the relay and for routing session commands; none of it is sent upstream. - The shared agent host code (
runAgentHost) takes the function that opens its event stream: the controller passes its hub, an isolated agent host the hub over its WebSocket (openHubStream, chosen bySWITCH_AGENT_HUBin its credentials), while Console passes the agent host's own connection to Switch. Only the controller holds the agent protocol's connection to Switch; nothing on the machine imitates it. - A loopback HTTP relay (
127.0.0.1, a per-agent bearer token minted locally) is what each agent host uses asSWITCH_API_ENDPOINTfor its calls to Switch. It forwards everything with the controller access token, theX-Switch-Agent-Idheader, andX-Switch-Room-Idresolved from the placements. It serves no event stream and no connection bookkeeping of its own. The credentials file names the relay, its hub and its local token, never a Switch credential.
Core implementation notes (decisions the spec left open)
- No placements. Core does not know where a controller-backed agent's
sessions are. The open and the beat carry no session map; a body that still
sends
placementsis refused with422 validation_error, an exception to ignoring unknown controller fields so a controller still reporting sessions is noticed. Per-agent room membership (agent.attached {rooms},agent.rooms) is kept: that is membership, not sessions. - Presence states. A controller-backed agent is
LIVEwhile it is connected (its controller's stream attached and beating, set to running, the controller not revoked), whatever itsconnection_model, andDISCONNECTEDotherwise; asession_passiveagent isAWAITING_MANUAL_POLLas any other. There is noDORMANTorNO_SESSIONfor it. An agent whose owner set it tostoppedis not connected however healthy its controller is. While connected it is present (agents_present_in,rooms_occupied, so the runtime-state sweep keeps its state) in every room it is a member of, and in none otherwise. A role holder ispresent_herein a room it is connected to and a member of; Core never names another room as itssession_room. The agent detail shows one room-agnostic session while it is connected. - Room replies. An addressed agent that is connected is available: the
message is delivered and Core posts nothing, neither "Starting a session…"
nor "I don't have a session in this room"; the agent's host posts any
"Starting a session…" notice itself. Not connected, the reply says why: its
owner stopped it and has to set it running, or its machine (the
controller's name, carried on the binding) is offline or reconnecting, or
has been removed once it is revoked. A controller-backed agent is never
told to open Switch Console.
In-room session commands (
!reset,!compact) are still relayed on the controller's stream with the room, and the controller picks the session. - Liveness is "socket attached and a pong within 6 s"; the connection sweep closes lapsed controller connections. Heartbeats stay in the memory of the process holding the socket.
- Recorded transitions.
ControllerPresencestays the in-memory fast path for routing and agent presence, and tells a ledger (ControllerConnectionLedger, Core's port, implemented bymanagement/connection_ledger.py) of each transition, once: the socket attaching to a connection that had none, and the socket going, with why (socket_closed,server_shutdown,heartbeat_lapsed,taken_over,revoked). The ledger writes them to the controller's row from one background task, never per beat. A connecting replaces the row; a closing is written only while the row still names that connection, so a process closing a connection the controller has since replaced through another process leaves the replacement standing. - Process lease. Each switch-core process renews a lease in
switch_core_processesevery 5 s (management/process_lease.py), one write per process however many machines it holds, and marks it stopped as it shuts down. A machine is online while its socket is recorded attached and its holding process's lease was renewed within 15 s and is not stopped; so a process that dies without writing its closings takes its machines offline within 15 s. Leases are written and compared on the database's clock. - Holder id. A controller-backed agent holds things under
controller:{controller_id}:{agent_id}: the operation caller's session key and session id, the reader of its unread counts, and the holder of a role lease (live while the agent is). Moving the agent changes it, so a lease does not survive a move. - Act-as routes. Every
/agents/{agent_id}/...and/agent-sessions/...route; on/agents/rooms/...,/agents/feature-flagsand/agent-sessions/...the agent comes fromX-Switch-Agent-Idalone. Refused for a controller token: registration (403 forbidden), any non-agent route (403 forbidden), and the per-agent connection surface the controller holds for the agent —events,notifications,rooms/{id}/events,connection/*,watch/heartbeat— with409 managed_by_controller.X-Switch-Connection-Idand the session selector headers are ignored for a controller principal. - Own key. A controller-backed agent's own API key (or OIDC token) is
refused on every route with
409 managed_by_controller, in the contract envelope. Binding an agent closes any connection it still held. - Open/beat bodies.
POST /connectionreturnsagents: string[](the agent ids bound now); the beat returns{agents}.clientandclient_versionare optional on open;placementsis refused on both. A beat with no stream attached is409 no_stream. Each open is a new server-generated connection id and generation and takes over the previous one. A secondGET /eventson the same connection takes the stream over and resumes every agent from its latest beat-confirmed cursor (or where the earlier stream attached it). - Frames wrap today's per-agent payloads unchanged:
agent.event {agent_id, seq, event},agent.session_command {agent_id, room_id, command}(command.sessionIdis null: the controller picks the session from the room),agent.approval_outcome {agent_id, outcome}, and the stream ends withevicted {code, reason}(taken_over,heartbeat_lapsed,closed) or aftercredential.revoked.connection_stateaddsconnection_id,generationandheartbeat_interval_s. - Revocation leaves the agents bound to the revoked controller (still controller-backed, not live) until they are moved or removed.
- Controller-token cache. The controller row a controller token re-reads
and the agent row it acts as are memoised (
ControllerAuthCache, separate from the agent API-key cache) forAGENT_AUTH_CACHE_TTL_SECONDS(0 disables it).ControllerPresencedrops a controller's entry when it is revoked and an agent's when it is bound, moved, unbound or deleted; the binding check itself is never cached.