Thread protocol v1¶

Status: v1, implemented by artifactr.fastapi and artifactr.mcp, with its JSON Schema in schemas/artifactr.v1.json. Its structure is settled by ADR-0005, ADR-0007 and ADR-0048. Field names may still change before the first release; after it, v1 changes only additively (see Versioning and schema).

Clients connect to a workspace over WebSocket. They receive the workspace's durable events with resume, send commands, and receive live frames for runs they are watching. REST exposes the same commands and the same reads.

Connection¶

• Endpoint: GET /v1/workspaces/{workspace_id}/stream, upgraded to WebSocket with subprotocol artifactr.v1.
• Authentication is resolved by the host application before the socket is accepted. The host supplies resolve_actor(request) -> (tenant_id, Actor); failure closes the socket with 4401.
• Frames are UTF-8 JSON text frames, one message per frame.
• One reader per socket. The server reads inbound frames in a single loop and never awaits long work in it. Commands are dispatched as tasks, so a stop_run is never stuck behind a slow command.

Handshake and resume¶

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: WebSocket upgrade (subprotocol artifactr.v1)
    S-->>C: accept (actor resolved)
    C->>S: hello {protocol, resume_after_seq or from_head, threads}
    S-->>C: welcome {protocol, head_seq, active_runs}
    S-->>C: event frames with seq > resume_after_seq
    S-->>C: replay_complete {up_to_seq}
    Note over C,S: Then: event frames as they commit, live frames for watched runs, command results

{"type": "hello", "protocol": "artifactr.v1", "resume_after_seq": 1041, "threads": ["thr_9"]}

{
  "type": "welcome",
  "protocol": "artifactr.v1",
  "workspace_id": "ws_1",
  "head_seq": 1057,
  "reset": false,
  "active_runs": [{"run_id": "run_42", "thread_id": "thr_9"}]
}

• The server owns the protocol version. An unsupported protocol closes the socket with 4400.
• Resume is by seq, never by timestamp. The server subscribes to the log from resume_after_seq before replaying, so no event can fall between replay and live delivery.
• resume_after_seq of 0 replays from the beginning of retained history. If the client has seen events this log does not have (its position is past head_seq, for example after the server's data was reset), or the position is older than retention, welcome carries reset: true: the client discards what it holds and rebuilds from the replay. The decision is artifactr.core.resume.
• from_head: true starts at the head of the log instead, for a client that needs only what happens from now on, such as a terminal starting a new thread. Nothing is replayed: replay_complete (up_to_seq is head_seq) follows welcome at once, and reset is false. active_runs are listed and watched as on any connection. The client's position is then welcome.head_seq, and it reconnects with resume_after_seq from there, so it does not miss what was committed while it was away. A hello with from_head and a nonzero resume_after_seq closes with 4400.
• threads filters thread-scoped events (messages, runs). Workspace-scoped events (artifacts, proposals) are always delivered.
• A hello not received within the server's timeout closes the socket with 4408.

Server frames¶

event: durable¶

Every durable event arrives in the same envelope. The stored envelope and the wire frame have the same shape; the models are Envelope and Event in artifactr.core.

{
  "type": "event",
  "seq": 1042,
  "id": "6f1c0f7e-3b0e-4a8a-9d7b-1a2b3c4d5e6f",
  "ts": "2026-09-28T14:03:11.204Z",
  "workspace_id": "ws_1",
  "thread_id": "thr_9",
  "run_id": "run_42",
  "actor": {"kind": "agent", "thread_id": "thr_9", "run_id": "run_42", "name": "assistant"},
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "event": {
    "type": "artifact_changed",
    "artifact_id": "plan_1",
    "kind": "plan",
    "version": 8,
    "patch": {"kind": "json_patch", "ops": [{"op": "replace", "path": "/tasks/t3/status", "value": "done"}]},
    "summary": "completed Ship v1",
    "proposal_id": null,
    "thread_id": "thr_9",
    "run_id": "run_42"
  }
}

actor.kind is one of user (id, name?), agent (thread_id, run_id?, name), external_agent (client_id, name?), system (name) or evaluator (name, version). Every event of one thread's agent is the same participant, whatever its run.

traceparent is the W3C trace context of the span that committed the event, or null when it was not traced. For a command, that is its artifactr.commit span. It has the name, format and meaning of reflexr's traceparent, so a client reads both the same way, and what an event causes elsewhere can link back to it (ADR-0033).

Artifact and proposal events are workspace-scoped, and also carry the thread_id and run_id they originated in, when there is one.

A patch is one of:

• {"kind": "json_patch", "ops": [...]}: RFC 6902 operations over the artifact's JSON data.
• {"kind": "text_edits", "field": "text", "edits": [{"old": "...", "new": "..."}]}: anchored replacements in one text field, where each old occurs exactly once when applied. An empty old writes into an empty field.

live: ephemeral¶

Live frames carry a run's token-level output. They have no seq, are not stored, and delivery is best-effort: a watcher that falls behind loses its oldest frames. Within one run they arrive in order. The models are LiveFrame and LiveEvent in artifactr.core.

{"type": "live", "run_id": "run_42", "event": {"type": "text_delta", "part": 0, "delta": "Here is the"}}

Durable events supersede live frames. When the agent's message_posted arrives, it is the authoritative text for that message. When artifact_changed arrives, it replaces any draft for that artifact.

Clients receive live frames for runs in the threads they subscribed to. watch_run attaches to a specific run.

command_result¶

Every command gets exactly one result.

{"type": "command_result", "command_id": "c_17", "ok": true, "outcome": {"type": "applied", "artifact_id": "plan_1", "version": 9, "seq": 1043}}

{
  "type": "command_result",
  "command_id": "c_18",
  "ok": false,
  "rejection": {"type": "version_conflict", "message": "artifact plan_1 is at version 8, but the change was based on 7", "artifact_id": "plan_1", "base": 7, "head": 8}
}

outcome.type is applied (artifact_id, version), proposed (proposal_id), resolved (proposal_id, decision, version?) or recorded (run_id?: the run a post_message or answer_deferred started or resumed, or null when it steered the thread's active run, left a paused run's requests unanswered, or was a notice). rejection.type is one of version_conflict, validation_failed, patch_failed, not_found, forbidden or invalid_state; every rejection has a message and its typed details.

replay_complete¶

{"type": "replay_complete", "up_to_seq": 1057}

Sent once, when replay has reached the head_seq announced in welcome, even if the last replayed events belonged to threads the client does not follow. Every later event frame is live.

v0.1 retains the whole log, so a reset is followed by a full replay. Snapshots for resuming beyond retention are an open question.

error¶

{"type": "error", "message": "not a command frame: Input should be a valid dictionary"}

A frame the server could not parse, or a command that failed unexpectedly on the server. Rejections are not errors: they arrive as command_result frames with ok: false.

Client frames: commands¶

After hello, a client sends command frames. Each wraps one command with a client-chosen command_id, which correlates it with its command_result and is also an idempotency key: the server remembers recent results, keyed by tenant, workspace, sender and command_id, and answers a repeated id with the original result, outcome or rejection, instead of running the command again. REST, the WebSocket and MCP share that memory (Deduplication).

{"type": "command", "command_id": "c_17", "command": {"type": "post_message", "thread_id": "thr_9", "content": "Draft the plan"}}

The command is one of the Command models in artifactr.core, or stop_run or watch_run. Ids of anything a command creates (artifact_id, thread_id, message_id, proposal_id) may be chosen by the client; they are generated when omitted. A frame that is not a valid command frame gets an error frame in reply, and the connection stays open.

{
  "type": "command",
  "command_id": "c_18",
  "command": {
    "type": "edit_artifact",
    "artifact_id": "plan_1",
    "base_version": 7,
    "patch": {"kind": "json_patch", "ops": [{"op": "add", "path": "/tasks/t9", "value": {"title": "Write changelog"}}]}
  }
}

Every command is carried out by artifactr.agent.Runner.execute, whichever transport it arrives on, so it behaves identically everywhere.

Deduplication¶

Every surface hands a command with its id to Runner.execute, which carries it out the first time the id is seen and remembers the result in the runner's CommandResults. A command is known by the tenant and workspace it was sent to, the sender (its actor's participant, so a changed display name does not matter) and its command_id; a repeated id returns the first result whatever command it comes with. By default the runner remembers the 10,000 most recent results in its process (InMemoryCommandResults), so a retry that reaches another process, or arrives after the result was forgotten, runs again, and so does one that arrives while the first is still being carried out.

Beyond the memory, core refuses a command that creates something with an id already used, as invalid_state, whichever process it reaches: create_thread, create_artifact, propose_change and post_message (ADR-0045). A client that chooses those ids and repeats them on a retry gets each command carried out once; invalid_state then means an earlier attempt succeeded. For post_message it means the message was posted, but not that its turn ran: if the process that posted it died before starting the turn, the turn never runs. An id the client omits is generated anew each time.

Close codes¶

REST¶

REST mirrors the commands and exposes reads; artifactr.fastapi.artifactr_router serves both. Command bodies are the same command frames as over the WebSocket.

Authentication is the host's: resolve_actor(request) returns the tenant and actor, or raises Unauthorized (401). An optional authorize(tenant, workspace, actor) refuses with 403, whose detail is the forbidden rejection, as for every other rejection a read raises.

Rejections map to HTTP status codes (artifactr.fastapi.STATUS_CODES): version_conflict and invalid_state → 409, validation_failed and patch_failed → 422, not_found → 404, forbidden → 403. watch_run over REST is rejected as invalid_state.

MCP mapping¶

External agents connect over MCP (artifactr.mcp.ArtifactrMcp) with the same authority as any other actor. The host's resolve(ctx) returns the client's tenant and ExternalAgentActor. An optional authorize(tenant, workspace, actor), the same hook as REST's, is asked on every tool call, resource read and resource subscription that names a workspace. Every tool goes through the same workspace rules and Runner.

Every tool that changes something (create_artifact, edit_text, edit_artifact, archive_artifact, respond_to_proposal, post_message, give_feedback) takes an optional command_id, the command frame's idempotency key: a retry with the same id returns the first result (Deduplication). The MCP request id cannot serve, since a retry is a new request.

Rejections are returned as tool errors carrying the rejection's message. A workspace authorize refuses is a tool error too, carrying this workspace is not yours to use, the message of REST's 403.

A resource read of an artifact that does not exist, of another tenant, or in a workspace authorize refuses fails with the JSON-RPC error INVALID_PARAMS (-32602), as the MCP SDK reports a missing resource, and a subscriptions/listen request that names one fails the same way. The error's data holds the uri and the rejection, the same object as REST's error body, so a client can tell not_found from forbidden. INTERNAL_ERROR means only that the server failed.

{"code": -32602, "message": "artifact plan_9 does not exist", "data": {"uri": "artifactr://acme/ws_1/artifacts/plan_9", "rejection": {"type": "not_found", "message": "artifact plan_9 does not exist", "entity": "artifact", "id": "plan_9"}}}

Versioning and schema¶

• The protocol identifier is artifactr.v1, also accepted as the WebSocket subprotocol. Within v1, changes are additive only: new optional fields and new event types. Clients must ignore unknown fields and keep unknown event types as opaque envelopes, since they still carry a seq.
• Breaking changes get a new subprotocol, artifactr.v2, served alongside v1 during migration.
• The JSON Schema for every frame is generated from the Pydantic models (TypeAdapter(...).json_schema()) into schemas/artifactr.v1.json and checked in. CI fails if it drifts. Clients generate their types from it, for example with json-schema-to-typescript.