# Agent OS ACP extension protocol schema, version 1.
# This schema is intentionally standalone. It imports no secure-exec schema.
type JsonUtf8 str
type AcpRuntimeKind enum {
JAVA_SCRIPT
PYTHON
WEB_ASSEMBLY
}
type AcpCreateSessionRequest struct {
agentType: str
runtime: AcpRuntimeKind
cwd: str
args: list<str>
env: map<str><str>
protocolVersion: i32
clientCapabilities: JsonUtf8
mcpServers: JsonUtf8
skipOsInstructions: bool
additionalInstructions: optional<str>
}
type AcpSessionRequest struct {
sessionId: str
method: str
params: optional<JsonUtf8>
}
# Enumerate the agents available in this VM. The sidecar answers from the already
# projected `/opt/agentos` packages (client parses no manifests).
type AcpListAgentsRequest struct {
reserved: bool
}
type AcpAgentEntry struct {
id: str
installed: bool
adapterEntrypoint: str
}
type AcpListAgentsResponse struct {
agents: list<AcpAgentEntry>
}
type AcpGetSessionStateRequest struct {
sessionId: str
}
type AcpCloseSessionRequest struct {
sessionId: str
}
# Resume a session that exists in durable storage but is not live in the current
# VM (e.g. after a Rivet actor slept and woke with a fresh VM). The sidecar runs
# the stateless resume state machine (native session/load when the agent supports
# it, else a fresh session/new + transcript continuation preamble). `cwd`/`env`
# describe the fresh adapter launch used by the fallback tier. `transcriptPath`,
# when present, is a guest-readable path the fallback preamble points the agent at.
type AcpResumeSessionRequest struct {
sessionId: str
agentType: str
transcriptPath: optional<str>
cwd: str
env: map<str><str>
}
# Browser RESUMABLE path only (AGENTOS-WEB-ASYNC-AGENTS.md §3.2.1): the kernel
# worker feeds a chunk of the agent's stdout into the in-flight create_session /
# session/prompt handshake. The synchronous sidecar would block inside one
# pushFrame; the resumable browser path returns between steps so the worker can
# service the agent's own syscalls (incl. pi's net call for inference) on fresh,
# non-nested pushFrames. `processId` is the handshake handle returned in the
# AcpPendingResponse for the originating create/prompt request.
type AcpDeliverAgentOutputRequest struct {
processId: str
chunk: data
}
type AcpRequest union {
AcpCreateSessionRequest |
AcpSessionRequest |
AcpGetSessionStateRequest |
AcpCloseSessionRequest |
AcpResumeSessionRequest |
AcpDeliverAgentOutputRequest |
AcpListAgentsRequest
}
type AcpSessionCreatedResponse struct {
sessionId: str
pid: optional<u32>
modes: optional<JsonUtf8>
configOptions: list<JsonUtf8>
agentCapabilities: optional<JsonUtf8>
agentInfo: optional<JsonUtf8>
}
type AcpSessionRpcResponse struct {
sessionId: str
response: JsonUtf8
}
type AcpSessionStateResponse struct {
sessionId: str
agentType: str
processId: str
pid: optional<u32>
closed: bool
exitCode: optional<i32>
modes: optional<JsonUtf8>
configOptions: list<JsonUtf8>
agentCapabilities: optional<JsonUtf8>
agentInfo: optional<JsonUtf8>
}
type AcpSessionClosedResponse struct {
sessionId: str
}
# Result of AcpResumeSessionRequest. `sessionId` is the live ACP session id after
# resume: equal to the requested id for native loads, or the freshly assigned id
# for the fallback tier (the caller remaps external -> live). `mode` is "native"
# (session/load|resume succeeded) or "fallback" (a new session was created and the
# transcript-continuation preamble was armed for the next prompt).
type AcpSessionResumedResponse struct {
sessionId: str
mode: str
}
type AcpErrorResponse struct {
code: str
message: str
}
# Browser RESUMABLE path: the create_session / session/prompt request (and each
# AcpDeliverAgentOutputRequest that has not yet completed the handshake) returns
# this, carrying the `processId` handle the kernel worker drives the interaction
# with. The real result (AcpSessionCreatedResponse / AcpSessionRpcResponse) is
# delivered as the response to the AcpDeliverAgentOutputRequest that completes it.
type AcpPendingResponse struct {
processId: str
}
type AcpResponse union {
AcpSessionCreatedResponse |
AcpSessionRpcResponse |
AcpSessionStateResponse |
AcpSessionClosedResponse |
AcpSessionResumedResponse |
AcpErrorResponse |
AcpPendingResponse |
AcpListAgentsResponse
}
type AcpSessionEvent struct {
sessionId: str
notification: JsonUtf8
}
type AcpAgentStderrEvent struct {
sessionId: str
agentType: str
processId: str
chunk: data
}
# Emitted when the ACP adapter process exits without an explicit close_session —
# a crash from the host's perspective (any spontaneous exit, including code 0).
# `restart` reports the sidecar's bounded auto-restart outcome:
# "restarted" — adapter respawned and the session was natively re-attached
# (session/load | session/resume) under the same sessionId;
# the session stays live.
# "unsupported" — the respawned adapter does not advertise a native resume
# capability; the session record was evicted.
# "failed" — the respawn or the native re-attach errored; evicted.
# "exhausted" — maxRestarts was already spent for this session; evicted.
# `exitCode` is absent when the exit was observed indirectly (e.g. a write to
# the adapter's stdin failed because the process was already gone).
type AcpAgentExitedEvent struct {
sessionId: str
agentType: str
processId: str
exitCode: optional<i32>
restart: str
restartCount: u32
maxRestarts: u32
}
type AcpEvent union {
AcpSessionEvent |
AcpAgentStderrEvent |
AcpAgentExitedEvent
}
type AcpPermissionCallback struct {
sessionId: str
permissionId: str
params: JsonUtf8
}
type AcpHostRequestCallback struct {
sessionId: str
request: JsonUtf8
}
type AcpCallback union {
AcpPermissionCallback |
AcpHostRequestCallback
}
type AcpPermissionCallbackResponse struct {
permissionId: str
reply: str
}
type AcpHostRequestCallbackResponse struct {
response: optional<JsonUtf8>
}
type AcpCallbackResponse union {
AcpPermissionCallbackResponse |
AcpHostRequestCallbackResponse
}