Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
"""Request bodies and wire shapes for the management routes.
Field names follow `docs/design/controller-contract-v1.md` wherever v1
implements the same message. Bodies a controller sends ignore unknown fields
(the contract's forward-compatibility rule), and a status report keeps them,
since it is stored and shown as sent. Bodies a person's client sends through
the gateway refuse unknown fields, so a misspelt key fails rather than being
dropped.
The JSON fixtures under `core/tests/switch_core/fixtures/agent_controllers/`
are the recorded form of these shapes; the controller's own tests parse the
same files.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any, Literal, Self
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
from switch_core.config import ControllerRelease
from switch_core.db.models import (
Agent,
AgentController,
AgentControllerOperation,
SealedProviderLogin,
)
from switch_core.db.models import AgentDefinition as AgentDefinitionRow
from switch_core.management.advanced_config import validate_advanced_config
from switch_core.management.sealed_logins import PublicKey, key_id
from switch_core.process_lease import ProcessLeases
from switch_core.providers.registry import AgentProviderId
Provider = AgentProviderId
ControllerKind = Literal["console", "daemon", "ec2"]
DesiredState = Literal["running", "stopped"]
Isolation = Literal["shared", "isolated"]
MAX_INSTRUCTIONS_BYTES = 32 * 1024
MAX_CONTROLLER_NAME_CHARS = 200
MAX_CONTROLLER_DESCRIPTION_CHARS = 500
MAX_STATUS_BYTES = 64 * 1024
# Process states that must carry a reason code.
FAILED_PROCESS_STATES = frozenset({"crashed", "failed"})
def wire_time(value: datetime) -> str:
"""RFC 3339 in UTC with a `Z`, the contract's time format."""
return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
def wire_time_or_none(value: datetime | None) -> str | None:
return None if value is None else wire_time(value)
class _ControllerBody(BaseModel):
model_config = ConfigDict(extra="ignore")
class _StatusBody(BaseModel):
model_config = ConfigDict(extra="allow")
class _GatewayBody(BaseModel):
model_config = ConfigDict(extra="forbid")
# ── Shared pieces ─────────────────────────────────────────────────────────────
class Platform(_StatusBody):
os: str
arch: str
os_version: str
class DefinitionV1(_GatewayBody):
"""The v1 agent definition, as a person's client submits it."""
provider: Provider
model: str | None = None
# The provider's "Advanced configuration", checked against its schema in
# `advanced_config`.
advanced_config: dict[str, Any] = Field(default_factory=dict)
instructions: str = ""
# The provider's own automatic review: safe actions run, risky ones still
# ask. A stored definition without the key predates it and reads as off
# (`stored_definition`).
auto_mode: bool = True
# Bypass: every permission check skipped. Wins over `auto_mode`.
auto_approve: bool = False
directory: str | None = None
# `shared`: the agent host runs inside its machine's controller.
# `isolated`: it runs as a process of its own (a systemd unit on a cloud
# machine, which runs every agent isolated).
isolation: Isolation = "shared"
@field_validator("instructions")
@classmethod
def _instructions_fit(cls, value: str) -> str:
if len(value.encode()) > MAX_INSTRUCTIONS_BYTES:
raise ValueError(
f"instructions must be at most {MAX_INSTRUCTIONS_BYTES} bytes"
)
return value
@model_validator(mode="after")
def _advanced_config_fits_the_provider(self) -> DefinitionV1:
validate_advanced_config(self.provider, self.advanced_config)
return self
# ── Controller-facing requests ────────────────────────────────────────────────
class EnrollmentCodeProof(_ControllerBody):
kind: Literal["enrollment_code"]
code: str
def _controller_name(value: str) -> str:
"""A machine's name, trimmed, and refused when nothing is left."""
trimmed = value.strip()
if not trimmed:
raise ValueError("a device's name must not be blank")
return trimmed
def _controller_description(value: str | None) -> str | None:
"""A machine's description, trimmed; blank is no description."""
if value is None:
return None
trimmed = value.strip()
return trimmed or None
class ControllerDescription(_ControllerBody):
"""What a controller says about itself when it enrolls.
`description` is the owner's note on what the machine is for, given at
enrollment (`--description`) and editable afterwards; absent is none."""
kind: ControllerKind
name: str = Field(min_length=1, max_length=MAX_CONTROLLER_NAME_CHARS)
description: str | None = Field(
default=None, max_length=MAX_CONTROLLER_DESCRIPTION_CHARS
)
platform: Platform
version: str
@field_validator("name")
@classmethod
def _name_is_not_blank(cls, value: str) -> str:
return _controller_name(value)
@field_validator("description")
@classmethod
def _blank_description_is_none(cls, value: str | None) -> str | None:
return _controller_description(value)
class EnrollRequest(_ControllerBody):
proof: EnrollmentCodeProof
controller: ControllerDescription
public_key: PublicKey | None = None
class TokenRequest(_ControllerBody):
credential: str
class StatusControllerInfo(_StatusBody):
version: str
protocol: int
assignment_revision: int
# Who moves it onto another release: itself, following the release Core
# names, or Switch Console, which runs it (on an SSH host, say) and
# replaces its bundle. Absent from a controller older than this field.
updated_by: Literal["self", "console"] | None = None
class MachineStatus(_StatusBody):
platform: Platform
disk_free_bytes: int
disk_total_bytes: int
mem_free_bytes: int
mem_total_bytes: int
sessions_running: int
sessions_max: int
# The absolute directory the controller makes agents' workspaces in. A
# controller older than this field does not send it.
workspaces_dir: str | None = None
class ProviderStatus(_StatusBody):
provider: str
installed: bool
version: str | None
auth: str
auth_source: str | None
checked_at: str
reason: str | None = None
class ToolStatus(_StatusBody):
tool: str
state: str
reason: str | None = None
class AgentSessions(_StatusBody):
active: int
ids: list[str]
class AgentStatus(_StatusBody):
agent_id: str
applied_revision: int | None
process: str
attached: bool
sessions: AgentSessions
restarts_10m: int
oom_kills: int
# The absolute working directory the agent runs in; null before the
# controller resolved one, absent from a controller older than this field.
directory: str | None = None
since: str
reason: str | None = None
detail: str | None = None
@model_validator(mode="after")
def _failure_has_a_reason(self) -> AgentStatus:
if self.process in FAILED_PROCESS_STATES and not self.reason:
raise ValueError(f"an agent whose process is {self.process} needs a reason")
return self
class StatusReport(_StatusBody):
seq: int = Field(ge=0)
observed_at: str
controller: StatusControllerInfo
machine: MachineStatus
providers: list[ProviderStatus]
tools: list[ToolStatus]
agents: list[AgentStatus]
class ProgressRequest(_ControllerBody):
message: str
class OperationFailure(_ControllerBody):
code: str
message: str
class OperationResultRequest(_ControllerBody):
outcome: Literal["succeeded", "failed"]
output: dict[str, Any] | None = None
error: OperationFailure | None = None
@model_validator(mode="after")
def _outcome_matches(self) -> OperationResultRequest:
if self.outcome == "failed" and self.error is None:
raise ValueError("a failed result needs an error")
if self.outcome == "succeeded" and self.error is not None:
raise ValueError("a succeeded result carries no error")
return self
def stored(self) -> dict[str, Any]:
if self.outcome == "failed":
assert self.error is not None
return {"outcome": "failed", "error": self.error.model_dump()}
result: dict[str, Any] = {"outcome": "succeeded"}
if self.output is not None:
result["output"] = self.output
return result
class _ControllerStreamBody(_ControllerBody):
"""The connection open and beat. Unknown fields are ignored as on every
controller body, except `placements`: Core no longer tracks where a
controller's sessions are, and a controller still reporting them is
refused so the mismatch is seen rather than silently dropped."""
@model_validator(mode="before")
@classmethod
def _placements_refused(cls, data: Any) -> Any:
if isinstance(data, dict) and "placements" in data:
raise ValueError(
"placements is not accepted: Switch tracks only whether a "
"controller-backed agent is connected, not where its sessions are"
)
return data
class ControllerConnectionRequest(_ControllerStreamBody):
"""Opening the controller's stream: where to resume each of its agents.
A cursor is a sequence number in that agent's own buffer, or `"head"`. An
agent left out starts at its head.
"""
client: str | None = None
client_version: str | None = None
cursors: dict[str, int | Literal["head"]]
@field_validator("cursors")
@classmethod
def _cursors_are_sequences(
cls, value: dict[str, int | Literal["head"]]
) -> dict[str, int | Literal["head"]]:
for agent_id, cursor in value.items():
if isinstance(cursor, int) and cursor < 0:
raise ValueError(f"cursor for {agent_id} must not be negative")
return value
def resume_cursors(self) -> dict[str, int | None]:
return {
agent_id: None if cursor == "head" else cursor
for agent_id, cursor in self.cursors.items()
}
# ── Gateway requests ──────────────────────────────────────────────────────────
class ConsoleControllerRequest(_GatewayBody):
name: str = Field(min_length=1, max_length=MAX_CONTROLLER_NAME_CHARS)
description: str | None = Field(
default=None, max_length=MAX_CONTROLLER_DESCRIPTION_CHARS
)
kind: Literal["console"]
platform: Platform
version: str
public_key: PublicKey | None = None
@field_validator("name")
@classmethod
def _name_is_not_blank(cls, value: str) -> str:
return _controller_name(value)
@field_validator("description")
@classmethod
def _blank_description_is_none(cls, value: str | None) -> str | None:
return _controller_description(value)
class _ControllerDetailsChange(BaseModel):
"""Rename a machine or change its description. Either or both; a key left
out is left as it is, and `description: null` (or blank) clears it — read
`model_fields_set`, not the value."""
name: str | None = Field(
default=None, min_length=1, max_length=MAX_CONTROLLER_NAME_CHARS
)
description: str | None = Field(
default=None, max_length=MAX_CONTROLLER_DESCRIPTION_CHARS
)
@field_validator("name")
@classmethod
def _name_is_not_blank(cls, value: str | None) -> str | None:
if value is None:
raise ValueError("a device's name cannot be cleared")
return _controller_name(value)
@field_validator("description")
@classmethod
def _blank_description_is_none(cls, value: str | None) -> str | None:
return _controller_description(value)
@model_validator(mode="after")
def _changes_something(self) -> Self:
if not self.model_fields_set:
raise ValueError("give a name, a description, or both")
return self
class UpdateControllerRequest(_ControllerDetailsChange):
"""The owner's change, through the gateway."""
model_config = ConfigDict(extra="forbid")
class ControllerInfoRequest(_ControllerDetailsChange):
"""The controller's own change (`switch-agent-controller set-info`), and
the key its provider logins are sealed to, which a controller enrolled
before it made one registers once."""
model_config = ConfigDict(extra="ignore")
public_key: PublicKey | None = None
@field_validator("public_key")
@classmethod
def _key_is_not_cleared(cls, value: PublicKey | None) -> PublicKey:
if value is None:
raise ValueError("a controller's public key cannot be cleared")
return value
class CreateManagedAgentRequest(_GatewayBody):
name: str
description: str
display_name: str | None = None
# Null for the icon its name generates (`agent_icon.generated_icon_url`),
# or for no icon when the server has third-party avatars off.
icon_url: str | None = None
controller_id: str | None
desired_state: DesiredState
definition: DefinitionV1
class PutManagedAgentRequest(_GatewayBody):
controller_id: str | None
desired_state: DesiredState
definition: DefinitionV1
class PatchManagedAgentRequest(_GatewayBody):
"""Any subset of the three. `controller_id: null` unplaces the agent, so a
key that is absent and a key that is null mean different things — read
`model_fields_set`, not the value."""
definition: DefinitionV1 | None = None
desired_state: DesiredState | None = None
controller_id: str | None = None
class CreateOperationRequest(_GatewayBody):
controller_id: str
agent_id: str | None = None
kind: str
params: dict[str, Any] = Field(default_factory=dict)
# ── Wire shapes ───────────────────────────────────────────────────────────────
def stored_definition(definition: dict[str, Any]) -> dict[str, Any]:
"""A stored v1 definition with the fields it may predate filled in as they
read: a definition saved before `auto_mode` existed has it off."""
return {**definition, "auto_mode": definition.get("auto_mode", False)}
def assignment_entry(row: AgentDefinitionRow, agent: Agent) -> dict[str, Any]:
"""An `AgentAssignment`: the stored v1 definition, plus the agent's `name`,
`display_name` and `icon_url` read from its own row.
The definition is the v1 shape, `directory` included, rather than the
target contract's (which nests it as `local.directory` and adds fields v1
does not have); `agent-controllers-v1.md` defines it this way."""
definition = row.definition
return {
"agent_id": row.agent_id,
"revision": row.revision,
"desired_state": row.desired_state,
"definition": {
"name": agent.name,
"display_name": agent.display_name,
"icon_url": agent.icon_url,
"provider": definition["provider"],
"model": definition.get("model"),
"advanced_config": definition.get("advanced_config", {}),
"instructions": definition.get("instructions", ""),
"auto_mode": definition.get("auto_mode", False),
"auto_approve": definition.get("auto_approve", False),
"directory": definition.get("directory"),
"isolation": definition.get("isolation", "shared"),
},
}
def operation_wire(operation: AgentControllerOperation) -> dict[str, Any]:
"""An `Operation` as a controller sees it. `lease_expires_at` is present only
while the operation is claimed."""
wire: dict[str, Any] = {
"id": operation.id,
"kind": operation.kind,
"agent_id": operation.agent_id,
"params": operation.params,
"created_at": wire_time(operation.created_at),
}
if operation.state == "claimed" and operation.lease_expires_at is not None:
wire["lease_expires_at"] = wire_time(operation.lease_expires_at)
return wire
def operation_view(operation: AgentControllerOperation) -> dict[str, Any]:
"""An operation as its owner sees it in the gateway: everything, state included."""
return {
"id": operation.id,
"controller_id": operation.controller_id,
"agent_id": operation.agent_id,
"kind": operation.kind,
"params": operation.params,
"state": operation.state,
"lease_expires_at": wire_time_or_none(operation.lease_expires_at),
"result": operation.result,
"created_by": operation.created_by,
"created_at": wire_time(operation.created_at),
"updated_at": wire_time(operation.updated_at),
}
def workspaces_dir_of(controller: AgentController) -> str | None:
"""The workspaces directory the controller last reported, or None when
its last report did not carry one."""
if controller.status is None:
return None
machine = controller.status.get("machine")
directory = machine.get("workspaces_dir") if isinstance(machine, dict) else None
return directory if isinstance(directory, str) and directory else None
def connection_view(
controller: AgentController, leases: ProcessLeases
) -> dict[str, Any] | None:
"""The controller's connection as last recorded: the current one, or the
last one once its socket went. None when none was ever recorded.
A connection the row shows open whose holding process is no longer
alive is shown as ended when and why that process stopped holding it:
`server_shutdown` at its lease's `stopped_at`, or `server_lost` after its
last renewal (when unknown once the lease is pruned)."""
if controller.connected_at is None:
return None
disconnected_at = controller.disconnected_at
reason = controller.disconnect_reason
if disconnected_at is None and not leases.holds(controller.connection_process_id):
disconnected_at, reason = leases.ended(controller.connection_process_id)
return {
"connected_at": wire_time(controller.connected_at),
"disconnected_at": wire_time_or_none(disconnected_at),
"disconnect_reason": reason,
}
def updated_by_console(controller: AgentController) -> bool:
"""Whether Switch Console updates this controller: Console's own, or one
Console runs elsewhere and says so in its status. Either ships with
Console and cannot follow the release Core names."""
if controller.kind == "console":
return True
info = (controller.status or {}).get("controller") or {}
return info.get("updated_by") == "console"
def release_for(
controller: AgentController, release: ControllerRelease | None
) -> ControllerRelease | None:
"""The release this controller is told to run. None for one Switch Console
updates, whatever is set."""
return None if updated_by_console(controller) else release
def controller_release_view(
controller: AgentController, release: ControllerRelease | None
) -> dict[str, str] | None:
"""The release the controller is told to run, or null when it is told none."""
wanted = release_for(controller, release)
if wanted is None:
return None
return {"version": wanted.version, "url": wanted.url, "sha256": wanted.sha256}
def release_view(
controller: AgentController, release: ControllerRelease | None
) -> dict[str, Any] | None:
"""Whether the controller runs the release it is told to run: the version
wanted, the one it last reported, and whether they are the same. Null when
it is told none."""
release = release_for(controller, release)
if release is None:
return None
return {
"wanted": release.version,
"running": controller.version,
"current": controller.version == release.version,
}
def controller_view(
controller: AgentController,
state: str,
leases: ProcessLeases,
release: ControllerRelease | None,
) -> dict[str, Any]:
return {
"id": controller.id,
"name": controller.name,
"description": controller.description,
"kind": controller.kind,
"platform": controller.platform,
"version": controller.version,
"release": release_view(controller, release),
"state": state,
"last_seen_at": wire_time_or_none(controller.last_seen_at),
"connection": connection_view(controller, leases),
"status": controller.status,
"assignment_revision": controller.assignment_revision,
"workspaces_dir": workspaces_dir_of(controller),
"public_key": public_key_view(controller),
"created_at": wire_time(controller.created_at),
"revoked_at": wire_time_or_none(controller.revoked_at),
}
def public_key_view(controller: AgentController) -> dict[str, str] | None:
"""The key the owner's client seals this machine's provider logins to,
with the id a sealed login names it by; null for one that has none."""
if controller.public_key is None:
return None
return {**controller.public_key, "key_id": key_id(controller.public_key["key"])}
def sealed_login_view(row: SealedProviderLogin) -> dict[str, Any]:
"""What the owner sees of a sealed login: never the ciphertext."""
return {
"provider": row.provider,
"revision": row.revision,
"key_id": row.sealed["key_id"],
"updated_at": wire_time(row.updated_at),
}
def agent_status_from(
controller: AgentController | None, agent_id: str
) -> dict[str, Any] | None:
"""The agent's entry in its controller's last status report, if there is
one. `directory` is always present: null when the controller has not
resolved one or predates the field."""
if controller is None or controller.status is None:
return None
agents = controller.status.get("agents")
for entry in agents if isinstance(agents, list) else []:
if isinstance(entry, dict) and entry.get("agent_id") == agent_id:
return {**entry, "directory": entry.get("directory")}
return None
def managed_agent_view(
row: AgentDefinitionRow,
agent: Agent,
controller: AgentController | None,
controller_state: str | None,
template: dict[str, Any] | None,
) -> dict[str, Any]:
"""`template` is the template that created the agent, as its install
records it ({id, key, revision}), or None for one no template run the
server vouches for created."""
return {
"agent_id": agent.id,
"name": agent.name,
"display_name": agent.display_name,
"icon_url": agent.icon_url,
"description": agent.description,
"controller_id": row.controller_id,
"controller_name": controller.name if controller is not None else None,
"controller_kind": controller.kind if controller is not None else None,
"controller_state": controller_state,
"desired_state": row.desired_state,
"revision": row.revision,
"definition": stored_definition(row.definition),
"status": agent_status_from(controller, agent.id),
"template": template,
"created_at": wire_time(row.created_at),
"updated_at": wire_time(row.updated_at),
}