Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -100,10 +100,12 @@ Routes: `GET /api/init`, `POST /api/init`
capacity), and a CORS preflight `OPTIONS /api/settings` with an `Origin`
(CORS allowlist); the delivered webhook's deliveries are read from an HTTP
sink.
- SDK / TypeScript client: no consumer method calls `/api/init`; only the
generated TypeScript types describe it
(`clients/typescript/src/generated/agent-server-schema.ts`). The caller is a
warm-pool orchestrator.
- TypeScript client: `InitClient.getStatus()` (`GET /api/init`) and
`InitClient.initialize(request, {initApiKey})` (`POST /api/init`, sending
`initApiKey` as `X-Init-API-Key`), also reachable as
`AgentServerClient.init` and `ConversationManager.init`; driven against a
dormant server by `F34.init-client`. The Python SDK has no method for
`/api/init`. The usual caller is a warm-pool orchestrator.

## Driving it with control-agent-server

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ user and agent message, every tool action and observation, and one state
update per changed field (`execution_status`, `stats`, `last_user_message_id`,
...). Consumers append a user message with `POST .../events` (and optionally
start the agent), read history through search (filters, cursor paging, sort),
count, get-one and batch-get, and follow the conversation live over
count, get-one and batch-get (a GET with a JSON body, or its browser-safe
`POST .../events/batch` form), and follow the conversation live over
`/sockets/events/{conversation_id}`: first-frame auth, a transient
`full_state` snapshot, optional replay of history (`resend_mode=all` or
`since`), then every new event as raw JSON; a message frame sent on the socket
Expand All @@ -21,6 +22,7 @@ Routes: `GET /api/conversations/{conversation_id}/events/search`,
`GET /api/conversations/{conversation_id}/events/count`,
`GET /api/conversations/{conversation_id}/events/{event_id}`,
`GET /api/conversations/{conversation_id}/events`,
`POST /api/conversations/{conversation_id}/events/batch`,
`POST /api/conversations/{conversation_id}/events`,
`WS /sockets/events/{conversation_id}`

Expand All @@ -36,6 +38,7 @@ Routes: `GET /api/conversations/{conversation_id}/events/search`,
- `F06.get-one`: `GET .../events/{event_id}` returns the event that search lists under that id, and the same event is on disk.
- `F06.unknown-event`: an unknown event id returns 404 from get-one and `null` in its slot from batch-get.
- `F06.batch-get`: `GET .../events` with a JSON array of ids as the body returns those events in request order; no body is a 422.
- `F06.batch-post`: `POST .../events/batch` with the same JSON array returns byte for byte what the GET batch returns (events in request order, `null` for an unknown id, `[]` for `[]`), appends nothing, and answers 422 for no body or a non-array body, 404 for an unknown conversation and 401 without a key.
- `F06.not-found-auth`: every event route returns 404 for an unknown conversation, 422 for a malformed conversation id and 401 without a valid session key.
- `F06.send-validation`: a missing body, a message with an unknown role, string content or an unknown content type is rejected with 422 and nothing is appended.
- `F06.send-image`: a message with a text part and an `image` part (a `data:` URL) is persisted with its `image_urls` intact and returned the same by search, get-one and the socket replay; an `image` part without `image_urls` is a 422 and appends nothing.
Expand Down Expand Up @@ -81,8 +84,10 @@ Routes: `GET /api/conversations/{conversation_id}/events/search`,
- REST: `GET .../events/{event_id}` (TypeScript `ConversationClient.getEvent()`,
`RemoteEventsList.getEventById()`) and `GET .../events` with a JSON array body
(batch get; no SDK or TypeScript caller, because browsers cannot send a GET
body: the TypeScript `getEvents()` fans out to get-one and maps 404 to
`null`).
body) and its browser-safe form `POST .../events/batch` with the same bare
JSON array body (TypeScript `ConversationClient.batchGetEvents()`, driven by
`F34.events-batch-post`). The TypeScript `RemoteEventsList.getEventsById()`
still fans out to get-one and maps 404 to `null`.
- WebSocket: `/sockets/events/{conversation_id}` with query `resend_mode`
(`all` or `since`), `after_timestamp` (ISO 8601, required for `since`) and
the deprecated `resend_all=true` and `session_api_key`. The SDK's
Expand Down Expand Up @@ -280,6 +285,35 @@ Preconditions:
```
Events come back in request order, not log order; without a body the
route answers 422 `body: Field required`.
- **Batch get by POST (`F06.batch-post`).** The same ids through the
browser-safe form, compared byte for byte with the GET form.

Requires: `F06.search-time-window`, `F06.get-one`
```sh
B6="$AGENT_SERVER_VERIFY_RUN/fixtures/qa-f06-batch"
mkdir -p "$B6"
N6=$(control-agent-server api GET "/api/conversations/$CID/events/count" --field .)
control-agent-server api POST "/api/conversations/$CID/events/batch" --json "[\"$E2\", \"qa-missing-event\", \"$E1\"]" --expect 200 \
--check . len-eq 3 --check 0.id eq "$E2" --check 1 missing --check 2.id eq "$E1" --raw-out "$B6/post.json" --save F06.batch-post/three
control-agent-server api GET "/api/conversations/$CID/events" --json "[\"$E2\", \"qa-missing-event\", \"$E1\"]" --expect 200 \
--quiet --raw-out "$B6/get.json"
cmp "$B6/get.json" "$B6/post.json"
control-agent-server api POST "/api/conversations/$CID/events/batch" --json '[]' --expect 200 --check . len-eq 0
control-agent-server api POST "/api/conversations/$CID/events/batch" --expect 422 --check detail.0.loc contains body \
--check detail.0.type eq missing --save F06.batch-post/no-body
control-agent-server api POST "/api/conversations/$CID/events/batch" --json "{\"ids\": [\"$E2\"]}" --expect 422 \
--check detail.0.type eq list_type --save F06.batch-post/object-body
control-agent-server api POST "/api/conversations/$QA_UNKNOWN/events/batch" --json "[\"$E2\"]" --expect 404 \
--check detail contains 'Conversation not found' --save F06.batch-post/unknown-conversation
control-agent-server api POST "/api/conversations/$CID/events/batch" --json "[\"$E2\"]" --auth none --expect 401
control-agent-server api POST "/api/conversations/$CID/events/batch" --json "[\"$E2\"]" --expect 200 --check 0.id eq "$E2"
control-agent-server api GET "/api/conversations/$CID/events/count" --check . eq "$N6"
```
The POST answers `[<E2>, null, <E1>]`, the same bytes as the GET form
for the same ids; `[]` is `[]`. No body is 422 `missing` at `body`, an
object instead of the bare array is 422 `list_type`, an unknown
conversation 404 `Conversation not found`, no key 401, and the count is
unchanged: the POST reads, it appends nothing.
- **Unknown conversation, bad id, no key (`F06.not-found-auth`).**

Requires: `F06.get-one`
Expand Down Expand Up @@ -766,7 +800,9 @@ Preconditions:
them. Compare ids, not raw JSON.
- An unknown event id is a 404, and `null` in its slot of a batch
(`F06.unknown-event`); batch-get is a GET with a JSON body, which browsers
cannot send.
cannot send, so browser clients use `POST .../events/batch`
(`F06.batch-post`). `GET .../events/batch` is not that route: it is
get-one for the event id `batch` (404).
- The `SystemPromptEvent` is written on the first message, not at creation;
a conversation created without a message has an empty log and count 0.
- `POST .../events` with `run: false` never runs, even on an idle
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Routes: `WS /sockets/session/{conversation_id}`
- `F07.sync-first-during-run`: while a run holds the conversation's state lock, `sync` is still the first frame; an `error` reply to an invalid frame sent right after connecting comes after it.
- `F07.snapshot-transient`: every connection gets one `transient` frame with a `full_state` `ConversationStateUpdateEvent` and no `seq`, after `sync` (and after the replay when one ran); it is never persisted.
- `F07.snapshot-compact-stats`: the `full_state` snapshot carries each LLM's aggregate stats (`accumulated_cost`, `accumulated_token_usage`) but not the per-call `costs`, `response_latencies` and `token_usages` lists, so it stays small however long the conversation runs; `GET /api/conversations/{id}` returns the same aggregates with empty per-call lists.
- `F07.snapshot-no-skill-bodies`: the `full_state` snapshot and live `agent` state updates carry the agent with `agent_context.skills` emptied, so skill bodies never ride the socket live, while `GET /api/conversations/{id}?include_skills=true` and the stored event keep them.
- `F07.full-replay`: `after_seq=-1` (or any value below it) replays every persisted event as `durable` frames with `seq` 0..`through_seq`, in order, once each, with the same ids REST returns.
- `F07.seq-on-disk`: a durable frame's `seq` is the event's on-disk index, the `NNNNN` in `events/event-NNNNN-<event id>.json`.
- `F07.resume-cursor`: `after_seq=k` replays exactly the events with `seq > k`; `after_seq=through_seq` replays nothing.
Expand Down Expand Up @@ -479,6 +480,41 @@ Preconditions:
conversation's `base_state.json` still keeps every per-call entry; only
the wire payloads are compact. The legacy events socket's snapshot (F06)
is built the same way.
- **Snapshot without skill bodies (`F07.snapshot-no-skill-bodies`).** A
conversation whose agent carries an inline skill (a placeholder model, never
run): read its live-only snapshot, then switch its LLM (F09's route) while a
capture is open, and compare with the stored state.
```sh
KLLM='"llm": {"model": "openai/qa-placeholder", "api_key": "qa-placeholder", "base_url": "http://127.0.0.1:9/v1", "num_retries": 0}'
KID=$(control-agent-server conversation start --no-autotitle --print-id --body-json \
'{"agent_settings": {"agent_kind": "openhands", '"$KLLM"', "tools": [], "agent_context": {"skills": [{"name": "qa-f07-skill", "content": "QA_F07_SKILL_BODY", "trigger": null}]}}}')
control-agent-server api GET "/api/conversations/$KID" --query include_skills=true --expect 200 \
--check agent.agent_context.skills.0.name eq qa-f07-skill --check agent.agent_context.skills.0.content eq QA_F07_SKILL_BODY
control-agent-server ws listen "/sockets/session/$KID" --count 2 --save "F07.snapshot-no-skill-bodies/live-$KID"
control-agent-server state cat "evidence/F07.snapshot-no-skill-bodies/live-$KID.json" --not-contains QA_F07_SKILL_BODY \
--check frames.2.frame.event.key eq full_state --check frames.2.frame.event.value.agent.agent_context exists \
--check frames.2.frame.event.value.agent.agent_context.skills len-eq 0
control-agent-server ws start "/sockets/session/$KID" --name "qa-f07-skills-$KID"
control-agent-server ws read "qa-f07-skills-$KID" --wait 10 --contains '"key": "full_state"' --expect-min 1
control-agent-server api POST "/api/conversations/$KID/switch_llm" --expect 200 --check success eq true \
--json '{"llm": {"model": "openai/qa-placeholder-2", "api_key": "qa-placeholder", "base_url": "http://127.0.0.1:9/v1", "num_retries": 0, "usage_id": "qa-f07-switched"}}'
control-agent-server ws stop "qa-f07-skills-$KID" --wait 10 --kinds durable:ConversationStateUpdateEvent --contains '"key": "agent"' \
--expect-min 1 --save "F07.snapshot-no-skill-bodies/agent-$KID"
control-agent-server state cat "evidence/F07.snapshot-no-skill-bodies/agent-$KID.json" --not-contains QA_F07_SKILL_BODY \
--check frames.3.frame.type eq durable --check frames.3.frame.event.key eq agent \
--check frames.3.frame.event.value.llm.model eq openai/qa-placeholder-2 --check frames.3.frame.event.value.agent_context.skills len-eq 0
control-agent-server api GET "/api/conversations/$KID" --query include_skills=true --expect 200 \
--check agent.llm.model eq openai/qa-placeholder-2 --check agent.agent_context.skills.0.content eq QA_F07_SKILL_BODY \
--save "F07.snapshot-no-skill-bodies/info-$KID"
control-agent-server api GET "/api/conversations/$KID/events/search" --expect 200 --check items len-eq 1 \
--check items.0.key eq agent --check items.0.value.agent_context.skills.0.content eq QA_F07_SKILL_BODY
```
The conversation holds the skill (REST with `include_skills=true`), yet
the snapshot's agent has `agent_context.skills: []` and no frame of either
capture contains the body. The `switch_llm` publishes the new agent as a
durable `agent` update (seq 0, the conversation's only event), whose live
frame also has an empty skill list next to the new model. Nothing is lost:
the conversation and the stored event keep the skill with its body.
- **Interrupted stream (`F07.item-aborted`).** Start a streamed
deepseek-flash answer that takes tens of seconds (counting to 3000), wait
until its `delta` frames flow on a background capture, then interrupt the
Expand Down Expand Up @@ -791,4 +827,9 @@ Preconditions:
POSTs above use `--quiet` to keep the map-run transcript small (`--expect`
and `--check` still see the bodies); `--max-chars` only trims non-JSON
response bodies.
- Only frames published live are trimmed of skill bodies
(`F07.snapshot-no-skill-bodies`): a replay (`after_seq`) reads the stored
event, so the same durable `agent` update at the same `seq` carries
`agent_context.skills` with their bodies, as `GET .../events/search` does.
A client that needs the skills reads `GET /api/conversations/{id}?include_skills=true`.
- Agent Canvas bundles Agent Server 1.62.0 by default, whose `full_state` snapshot still carries the per-call lists, so a very long conversation keeps closing with 1013 `frame_too_large` in Canvas until it pins a release that has `F07.snapshot-compact-stats` ([OpenHands/OpenHands#18935](https://github.com/OpenHands/OpenHands/issues/18935)).
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Routes: `POST /api/conversations/{conversation_id}/switch_profile`,
- `F09.ts-client`: the TypeScript client's `ConversationClient.switchLLM`, `switchProfile` and `switchAcpModel` and `ConversationManager.switchProfile` reach the routes: each switch resolves and reads back through `getConversation`, an unknown profile rejects with 404, `switchAcpModel` on a regular conversation with 400, a call without a key with 401, and `switchAcpModel` on an ACP conversation that has not run resolves and stores the model.
- `F09.ts-client-acp-docs`: the TypeScript client's `switchAcpModel` docstrings describe what the server does before an ACP conversation's first run (200, the model is stored for the first session), not a 409.
- `F09.ts-client-acp-effort`: the TypeScript client's `ConversationClient.switchAcpEffort` stores the level on an ACP conversation that has not run (`getConversation` shows `acp_effort` and `current_effort`), and rejects with 400 on a regular conversation and with 401 without a key.
- `F09.load-plugin`: `load_plugin` with `<plugin>@<marketplace>` from a local marketplace registered on the agent's `agent_context` answers 200 and merges the plugin's skill, its command and its hooks into the live agent, visible in `GET`, `base_state.json` and on the socket.
- `F09.load-plugin`: `load_plugin` with `<plugin>@<marketplace>` from a local marketplace registered on the agent's `agent_context` answers 200 and merges the plugin's skill, its command and its hooks into the live agent, visible in `GET` and `base_state.json`; the socket pushes the `agent` and `hook_config` updates, the `agent` one without skill bodies (`skills: []`).
- `F09.load-plugin-hook-runs`: after a runtime load, the next user turn runs the plugin's `UserPromptSubmit` hook (a `HookExecutionEvent` with its output) and finishes.
- `F09.load-plugin-errors`: no registered marketplaces and no agent context are 400, a registered marketplace whose source is missing is 400, an unknown marketplace or plugin is 404, empty and malformed refs are 400, a missing `plugin_ref` is 422 and an unknown conversation 404; a bare plugin name resolves across the registered marketplaces.
- `F09.load-plugin-twice`: loading the same plugin twice leaves one copy of its hooks, so they still run once per message.
Expand Down Expand Up @@ -96,7 +96,10 @@ Routes: `POST /api/conversations/{conversation_id}/switch_profile`,
`switchAcpEffort(id, effort)`;
`RemoteConversation.switchProfile`, `switchLlm`, `switchAcpModel`,
`switchAcpEffort`;
`ConversationManager.switchProfile`. There is no TypeScript `loadPlugin`.
`ConversationManager.switchProfile`;
`ConversationClient.loadPlugin(id, ref)` and
`PluginsClient.loadPluginForConversation(id, ref)` post
`{"plugin_ref": ref}` to `load_plugin` (driven by `F34.load-plugin`).
`F09.ts-client` drives the `ConversationClient` methods and
`ConversationManager.switchProfile` (the `RemoteConversation` methods post
the same bodies to the same routes).
Expand Down Expand Up @@ -805,14 +808,17 @@ Preconditions:
--save F09.load-plugin/get
control-agent-server state cat "server/workspace/conversations/${PID//-/}/base_state.json" --max-chars 200 \
--contains qa-f09-mkt-plugin-skill --check hook_config.user_prompt_submit len-eq 1
control-agent-server ws read qa-f09-plugin --kinds ConversationStateUpdateEvent --contains qa-f09-mkt-plugin-skill --expect-min 1 --wait 20 --save F09.load-plugin/agent-frame
control-agent-server ws read qa-f09-plugin --kinds ConversationStateUpdateEvent --contains '"key": "agent"' --expect-min 1 --wait 20 --save F09.load-plugin/agent-frame
control-agent-server ws read qa-f09-plugin --contains qa-f09-mkt-plugin-skill --expect-none
control-agent-server ws stop qa-f09-plugin --kinds ConversationStateUpdateEvent --contains QA_PLUGIN_HOOK --expect-min 1 --wait 20
```
Before the load the agent has no skills and no hooks. After it, `GET`
(with `include_skills=true`) lists the plugin's skill and its command (as
the skill `qa-f09-mkt-plugin:qa-hello`), `hook_config` has the plugin's
`UserPromptSubmit` hook, `base_state.json` has both, and the socket pushed
state updates for `agent` and `hook_config`.
state updates for `agent` and `hook_config`. The `agent` update (like the
`full_state` snapshot) carries `agent_context.skills` as `[]`, so no frame
names the plugin's skill; read skills from `GET` with `include_skills=true`.
- **The loaded hook runs (`F09.load-plugin-hook-runs`).** Run one turn on
`PID`.

Expand Down Expand Up @@ -917,7 +923,7 @@ Preconditions:
- **Restart (`F09.restart-persist`).** Restart the server and read every
switched conversation back; then run a turn on `RID`.

Requires: `F09.switch-profile`, `F09.acp-model-deferred`, `F09.load-plugin`
Requires: `F09.switch-llm-ws`, `F09.switch-profile`, `F09.acp-model-deferred`, `F09.load-plugin`
```sh
control-agent-server restart
control-agent-server api GET "/api/conversations/$CID" --quiet --check agent.llm.model eq openai/qa-f09-ws --check agent.llm.usage_id eq qa-f09-ws --save F09.restart-persist/cid
Expand Down Expand Up @@ -982,7 +988,9 @@ Preconditions:
that the load is what adds the plugin.
- Plugin commands become skills named `<plugin>:<command>`, and
`GET /api/conversations/{id}` trims `agent.agent_context.skills` to `[]`
unless `include_skills=true`.
unless `include_skills=true`. Socket and webhook
`ConversationStateUpdateEvent`s (`full_state` and `agent`) always carry
`agent_context.skills` as `[]`; the persisted state keeps the skills.
- `switch_acp_model` before the first run only persists the model; the
provider's capability (`supports_runtime_model_switch`) and
`available_models` are unknown (`false`, `[]`) until a session started. A
Expand Down
Loading
Loading