Client (internal)
Client sessions and the client event stream, for clients that need exact UI parity (ADF Studio in daemon mode, the terminal app): one session per client, one SSE stream per session carrying executor, host and push frames (design daemon-backend.md D5). Internal: these routes MAY change between versions; a client checks clientApiVersion (GET /version) first.
On this page
Read stored values of an agent (local callers only)
/agents/{id}/identity/revealLocal callers that present this run's local proof (X-ADF-Local-Proof, the daemon-local-proof file next to the daemon settings) only, in every mode; the token alone gets 403 loopback_only. Studio on this machine shows these values in its own window (Identity panel Reveal, provider override key field). The one exception to "values never leave the daemon": key material (crypto:*) is never returned, and a value sealed in a locked envelope, or encrypted with a file password the daemon does not hold, is left out. Cache-Control: no-store; values are never logged.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
purposes | array<string> | |
prefix | string |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Values | object | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/identity/reveal" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Read stored values of an agent file (local callers only)
/files/agent/identity/revealPOST /agents/{id}/identity/reveal by file path; works on a file that is not loaded through one readonly connection (nothing written, no envelope unlocked: its plain values only, as Studio reads a file it does not have open). Local callers that present this run's local proof (X-ADF-Local-Proof, the daemon-local-proof file next to the daemon settings) only, in every mode; the token alone gets 403 loopback_only. Studio on this machine shows these values in its own window (Identity panel Reveal, provider override key field). The one exception to "values never leave the daemon": key material (crypto:*) is never returned, and a value sealed in a locked envelope, or encrypted with a file password the daemon does not hold, is left out. Cache-Control: no-store; values are never logged.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
purposes | array<string> | |
prefix | string |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Values | object | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/agent/identity/reveal?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Read the app providers' API keys (local callers only)
/settings/providers/keys/revealThe keys of Settings → Providers that GET /settings answers as __redacted__: those stored in the daemon's settings file (a key kept in the OS keychain is never returned). Local callers that present this run's local proof (X-ADF-Local-Proof) only, in every mode; the token alone gets 403 loopback_only. Studio in local mode fills its key field with them, as embedded Studio does; a remote Studio keeps the placeholder. Cache-Control: no-store; keys are never logged.
Request bodyapplication/json · object · optional
| Field | Type | Description |
|---|---|---|
ids | array<string> | Provider ids to answer; all when absent. |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 200 | Keys | object | |||
| |||||
Errors 400 · 401 · 403 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/settings/providers/keys/reveal" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'List the open client sessions
/client/sessionsWhich clients are connected (client name, version, whether its session stops the daemon when it expires), without session ids. ADF Studio names them before it offers to restart a daemon of another version (design daemon-backend.md §8.2).
Responses
| Status | Description | Body | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The open sessions | ClientSessionList | |||||||||||||||
| |||||||||||||||||
Errors 401 · 405
| 401 | Missing or wrong bearer token (unauthorized) | |
| 405 | This daemon has no client sessions |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/client/sessions" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Open a client session
/client/sessionsOpens a session; its stream (GET /client/sessions/{id}/events) holds every frame from now on, so frames between this call and the first connect are not lost. A session expires 60 s after its stream disconnects (or after this call, if it never connects); expiry releases its documents. exitDaemonWhenClosed: true (ADF Studio when "Keep the daemon running" is off): when this session expires and no other session is open, a daemon Studio started (GET /version startedBy: studio) shuts down and logs why; a daemon the CLI or a service started never does. Granting exitDaemonWhenClosed: true requires a local caller (loopback, no proxy headers; local proof behind a proxy), returning 403 loopback_only otherwise. Ordinary remote sessions are allowed. Ending the session with DELETE does not stop the daemon. A write to /agents/{id}/* that sends the header X-ADF-Client-Session: <sessionId> is not echoed back to that session (config_changed, file_updated, document_updated raised by the write itself); every other session gets them, and work the request starts (a turn, a timer) reaches that session too.
Request bodyapplication/json · ClientSessionInput · required
| Field | Type | Description |
|---|---|---|
clientrequired | string | Client name, for the daemon log ( |
versionrequired | string | Client version, for the daemon log |
exitDaemonWhenClosed | boolean | Stop a Studio-started daemon when this session expires and no other session is open. Default false. |
umbilical | boolean | Also stream the umbilical envelopes GET /events carries, as |
pid | integer | The client's process id, kept only from a caller on this machine (local proof). A new session of the same client ends that client's sessions whose pid is no longer running and whose stream is closed (a relaunch after a crash), without the orphan rule. |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 201 | The new session | ClientSessionCreated | ||||||
| ||||||||
Errors 400 · 401 · 403 · 503
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 503 | The subsystem is not configured on this daemon |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/client/sessions" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"client":"string","version":"string"}'End a client session
/client/sessions/{id}Ends the session now: its stream closes and its documents are released. The orphan rule (exitDaemonWhenClosed) applies only to expiry, not to this call.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Ended | ClientSessionEnded | ||||||
| ||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | No such client session (it ended or expired, or the daemon restarted): open a new one. |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/client/sessions/ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Stream the session's frames (Server-Sent Events)
/client/sessions/{id}/eventsOne stream per session (a new connect replaces the open one). Starts with : connected and stream.hello {epoch, oldestCursor, latestCursor}, then the frames after the resume cursor; : heartbeat every 30 s. Each frame: id: <cursor>, event: executor | host | push | umbilical | turn, data: <ClientFrame JSON>. Without since the stream starts at the session's first frame. Frames: executor = a raw executor event (as ADF Studio's AGENT_EVENT carries it): text and thinking deltas only for the session's focused agent (PUT …/focus), whatever umbilical.stream_deltas says; a tool_call_result of another agent carries result.isError and resultSize instead of the content (stripped: tool_result). host = an agent lifecycle event (agent_starting … agent_stopped, agent_state_changed, agent_loops_changed, trigger_error, startup_failed). push = a topic for every other change (inbox, approvals snapshot, mesh, config_changed, workspace data, file and folder changes, install progress, MCP and adapter status, compute). turn = a stop dropped queued chats (outcome: discarded). Executor frames of a turn carry its turnId; turn_complete and error also the absorbedTurnIds that end with it. Frames of one agent arrive in emission order. Sessions not focused on an agent get its large payloads as stubs (see ClientFrame), so one agent's large write never fills another session's ring; a single frame over 4 Mi characters becomes stream.gap oversized for the session that would get it. Ring: each session keeps its newest 4096 frames (and at most 32 Mi characters). A frame dropped before it was written (a slow reader, or a long disconnect) is announced: stream.gap {reason: evicted, dropped, …} comes before the next frame; epoch_changed when the cursor is from another session. On a gap, reload state. Fan-out is per session: a slow or absent session never delays another.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
Query parameters
| Name | Type | Description |
|---|---|---|
since | integer | Replay buffered frames whose cursor is greater than this. Process-local; resets on daemon restart. Wins over |
epoch | string | The session epoch the resume cursor came from (POST /client/sessions, |
Header parameters
| Name | Type | Description |
|---|---|---|
Last-Event-ID | string | Standard SSE resume header: the last |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | SSE stream (text/event-stream) | text/event-stream | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Option 2object | Data of the 3 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
epochrequired | string | Identifies this daemon run; cursors are only comparable within one epoch |
oldestCursorrequired | integer | null | Oldest buffered cursor (null: nothing buffered) |
latestCursorrequired | integer | Newest cursor published (0: none yet) |
Option 3Data of the stream.gap control frame on a client session stream: frames were lost; reload state.
7 fields of Option 3 · ClientStreamGap
reasonrequired | string |
|
epochrequired | string | |
requestedCursorrequired | integer | null | |
oldestCursorrequired | integer | null | |
latestCursorrequired | integer | |
dropped | integer | Frames lost ( |
size | integer | Serialized size of the oversized frame |
Errors 400 · 401 · 403 · 404
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | No such client session (it ended or expired, or the daemon restarted): open a new one. |
Error bodies use the error format.
Example
curl -N "http://127.0.0.1:7385/client/sessions/ID/events" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Accept: text/event-stream"Set the agent the session follows
/client/sessions/{id}/focusThe focused agent's text and thinking deltas and full tool results reach this session; null focuses none. An id, handle or name of a loaded agent is resolved to its id; any other string is kept as given (an agent that is not running yet).
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
agentIdrequired | string | null |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | The focus | ClientSessionFocus | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | No such client session (it ended or expired, or the daemon restarted): open a new one. |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/client/sessions/ID/focus" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agentId":"string"}'Hold an agent file open for the session
/client/sessions/{id}/documentsOpens the agent file (by filePath or agentId) as an open document held by this session (design D4): a closed file opens without starting, a running agent's file joins its runtime. The holder is the session id from the path, never the body; answers never list holders. Released by DELETE …/documents/{agentId}, by ending the session or by its expiry; while the session is live the holder sweep keeps the document open.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
filePath | string | |
agentId | string |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The held document | ClientHeldDocument | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 405 · 409
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | No such client session (it ended or expired, or the daemon restarted): open a new one. | |
| 405 | Not available on this daemon (the subsystem is read-only or lacks this operation) | |
| 409 | The file cannot be opened here (for example another file with the same agent id is open) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/client/sessions/ID/documents" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Release a held document
/client/sessions/{id}/documents/{agentId}Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
agentIdrequired | string | Agent id of the held document |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Released | ClientDocumentReleased | |||||||||
| |||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | No such session, or the session does not hold that agent |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/client/sessions/ID/documents/AGENT_ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"End a client session as its client quits
/client/sessions/{id}/quitADF Studio's quit (design daemon-backend.md §8.3). Ends the session like DELETE /client/sessions/{id}, then, with stopDaemon: true, stops the daemon only when this run was started by Studio (GET /version startedBy: studio); with other client sessions open the stop is pending until the last one ends or expires (they get daemon_orphan_hold). A daemon the CLI or a service started keeps running. When it stops, new sessions are refused before the answer is sent, so none can open between the decision and the stop. The answer and the daemon log give the reason. The shutdown is the daemon's own bounded one (the same as POST /daemon/shutdown), started after the answer. An unknown or expired session id is not an error (ended: false): the stop decision still applies. With stopDaemon: true the caller must be local (loopback, no proxy headers; the local proof behind a proxy), as for POST /daemon/shutdown.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
Request bodyapplication/json · ClientQuitInput · optional
| Field | Type | Description |
|---|---|---|
stopDaemon | boolean | Stop the daemon when allowed (Studio: |
Responses
| Status | Description | Body | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The session ended; whether the daemon stops | ClientQuitResult | |||||||||||||||
| |||||||||||||||||
Errors 400 · 401 · 403 · 405
| 400 | stopDaemon is not a boolean | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 405 | This daemon has no client sessions |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/client/sessions/ID/quit" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Re-read the credential stores a client changed
/client/reload-credentialsADF Studio moved credentials into or out of this daemon's stores while it ran (the mode-switch handover, design daemon-backend.md §11): ChatGPT and Grok sessions (auth.daemon.json), app-level MCP sign-ins and the studio-runtime:<scope> keychain entry. No secret crosses HTTP: the daemon re-reads the runtime identity entry (as GET /identity does), re-runs the credential unlock of every agent degraded on locked credentials, and brings loops that failed on a subscription's auth out of error for each subscription whose session is now in its store. Local callers only (loopback, no proxy headers; the local proof behind a proxy).
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | What the reload found | CredentialReloadResult | |||||||||||||||||||||||||||||||||||||||||||||
unlockedrequiredarray<object> | Agents whose credentials unlocked now. 2 fields of | ||||||||||||||||||||||||||||||||||||||||||||||
agentIdrequired | string | |
filePathrequired | string | null |
stillLockedrequiredAgents still degraded on locked credentials.
2 fields of stillLocked
agentIdrequired | string | |
filePathrequired | string | null |
sessionsrequiredSubscription sessions in this daemon's stores.
recoveredrequiredLoops that left an auth error.
Errors 401 · 403
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/client/reload-credentials" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Change a session's orphan behaviour
/client/sessions/{id}/exit-when-closedThe client's quit behaviour changed (ADF Studio's keepDaemonRunning): with exitDaemonWhenClosed: true the session's expiry stops a Studio-started daemon when no other session is open (the orphan rule, §8.3); with false it does not. Changing this setting requires a local caller (loopback, no proxy headers; local proof behind a proxy), returning 403 loopback_only otherwise.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Client session id (POST /client/sessions) |
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
exitDaemonWhenClosedrequired | boolean |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Changed | object | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 405
| 400 | exitDaemonWhenClosed is not a boolean | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | No such client session | |
| 405 | This daemon has no client sessions |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/client/sessions/ID/exit-when-closed" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"exitDaemonWhenClosed":true}'