Skip to content

Self-improving AI Employees for everyone

74.4 KB
Raw Blame

Chat protocol (v2)

The wire contract between the server's chat runtime (server/services/chat/) and the shared chat UI (client/src/features/chat/). Home's employee page and Dev's console Chat pane both speak it. It follows AG-UI's event model and ordering (events, activity events), carried on the existing WebSocket with snake_case fields in the repo's CloudEvents envelope (services/events/envelope.py), never as literal camelCase AG-UI JSON.

Status: built. Change this document in the same commit as any change to the shapes below, and bump protocol_version (returned by get_chat_messages) when an existing field changes meaning. Version 2 distinguishes resumable generation Stop from terminal legacy chat Stop. The generation's execution_control_version, rather than the wire version alone, selects the behavior.

Only the AG-UI events the chat uses are sent. A tool call shows as a step, not as TOOL_CALL_* events; reasoning is never streamed; and a draft waiting for the owner is an approval card that follows approval_lifecycle (Approvals), so no run ends with AG-UI's interrupt outcome. A controlled generation can suspend and resume its existing run through workflow control without ending the chat run.

Concepts

Term Meaning
Session One conversation. Its id is the workflow id ("default" with no workflow open).
Run One answer the employee works on: an owner message, an edit, a regenerate, or a button press in generated UI (kinds message, edit, regenerate, action). An approved send is not a run: ApprovedToolCallWorkflow sends it.
Lane At most one non-terminal run per session. A second send is refused with run_in_progress; the composer shows Stop while a run is live and Resume while its controlled generation is stopped. Suspension keeps the lane occupied.
Message tree Messages link to their parent. Owner messages that share a parent are branches; replies under the same owner message are versions. The session's active leaf picks the path shown.
Part Structured content attached to a reply: steps, generated UI, artifacts, approvals, sources, follow-ups.
Generation The deployment generation a message was written in (run_key). A Reset clears the thread.

Delivery

Run events never ride StatusBroadcaster.broadcast (which reaches every socket). A socket receives a session's run events only after chat_subscribe succeeds. That handler applies the same checks as the canvas handlers: refuse the internal socket, load the workflow, and compare its owner with the socket's execution principal.

{"type": "chat_run_event",
 "data": {"specversion": "1.0", "id": "r_7f3c…:12", "source": "opencompany://services/chat",
          "type": "com.opencompany.chat.run.text.content", "subject": "r_7f3c…",
          "time": "2026-10-03T21:40:12.512Z", "datacontenttype": "application/json",
          "data": {"workflow_id": "…", "session_id": "…", "run_id": "r_7f3c…", "seq": 12,
                   "hub_epoch": "e_91ab…", "message_id": "r_7f3c….0.1", "delta": "Saturday is "}}}
  • Scope fields (workflow_id, session_id, run_id) live inside data, never as top-level CloudEvents extension attributes.
  • seq increases by one per run. The client drops duplicates (run_id, seq) and asks for a snapshot on a gap.
  • hub_epoch changes when the server process restarts. A changed epoch means the client must resync.
  • chat_subscribe answers with the session's live runs as snapshots, each with the seq it reflects. The hub is read before the database, so an event published meanwhile carries a higher seq than its snapshot: drop events with seq at or below the snapshot's, and buffer events that arrive before the response.
  • Each subscriber has a bounded queue (hub.subscriber_queue_size in server/config/chat_defaults.json). A socket that falls that far behind has its queue replaced by one custom opencompany.resync per session it follows (data: {session_id, hub_epoch, name, value}, no run_id); the client then takes fresh snapshots. Text deltas are batched before they are published (see Streaming, steps and Stop), not merged in the queue.
  • Publishers call publish_run_event (services/chat/hub.py), which delivers in-process. A standalone worker (python -m services.temporal.worker) has no sockets, so it relays instead; see Standalone workers.
  • chat.updated remains an identity-only broadcast ({workflow_id, session_id, role}) that tells every open thread to refetch get_chat_messages: after a message is added, after a clear, and when a run ends (role null), since a run's end changes what its thread offers (its answer can be tried again, the owner's message edited: editable).

Events

Every event's data carries {workflow_id, session_id, run_id, seq, hub_epoch} plus the fields below. The CloudEvents type is com.opencompany.chat.run.<suffix>; subject is the run id; id is <run_id>:<seq>.

AG-UI event Suffix Fields
RUN_STARTED started kind, parent_run_id?, user_message_id?, reply_message_id, started_at
RUN_FINISHED finished outcome (below), result {reply_message_id?, no_reply?}, duration_ms, step_count
RUN_ERROR failed message (safe to show, at most 500 chars), code, hint?, requires_user_action?
STEP_STARTED step.started step_id (the tool call's id), step_name, icon?
STEP_FINISHED step.finished step_id, step_name, state (done, failed, skipped), detail? (at most 200 chars), duration_ms, narration?
TEXT_MESSAGE_START text.started message_id (segment id {run_id}.{iteration}.{attempt}), role: "assistant"
TEXT_MESSAGE_CONTENT text.content message_id, delta (never empty)
TEXT_MESSAGE_END text.ended message_id, final (bool), reply_message_id? (with final: true)
ACTIVITY_SNAPSHOT activity.snapshot message_id (the part id), activity_type, content (an object), replace
ACTIVITY_DELTA activity.delta message_id, activity_type, patch (RFC 6902 operations on content)
CUSTOM custom name, value

activity_type values: json_render (a generated UI, patch by patch), approval (a draft's card) and artifact (a Canvas document the run wrote). Sources and follow-ups arrive with the saved reply, in its parts.

custom names: opencompany.segment_discarded ({message_id}: a retried LLM attempt replaces this segment), opencompany.stopping (legacy terminal Stop) and opencompany.resync. Controlled Stop derives its display from generation control; it does not emit a second chat pause lifecycle.

Text segments. Only the agent that answers the owner streams text. A segment that ends with final: false was written beside tool calls (narration, "Let me check the calendar."); the segment with final: true is the reply. Text that could still turn out to be NO_REPLY or a <followups> block is held back on the server and never streamed.

Outcomes (run.finished):

outcome.type Meaning
success The run ended. result.reply_message_id names the saved reply, or result.no_reply is true.
stopped A legacy or uncontrolled chat run ended after Stop (an OpenCompany addition to AG-UI's outcomes). Controlled Stop does not emit this terminal outcome.

Runs nothing will finish end with run.failed: code not_delivered (never picked up, or the employee stopped first), timed_out (running longer than its current runs.max_running_s window; the watchdog cancels its Temporal workflow first, so nothing keeps working on the answer), interrupted (its workflow closed without finishing it and no reply was saved; with a saved reply it finishes instead). A Reset ends live runs with code reset, the owner's Clear with cleared, and both delete them. Intentional suspension of a controlled generation excludes its live runs from pickup and running expiry; Resume starts a fresh timeout window, as described below.

Handlers

All are WebSocket request/response handlers with snake_case payloads. Failures answer {success: false, error: "<code>", …}.

Chat (server/services/chat/handlers.py)

Handler Request Response
send_chat_message {session_id, message, role: "user", timestamp?, client_message_id?, attachments?: [{path}], options?: Options, ui_event?: {part_id, element_id, action, params}} {success, message_id, run_id, delivery: "now" | "queued", timestamp}; run_id is null when the message starts no run; {success, message_id: null, run_id: null, declined: {run_id, approval_ids}, delivery, timestamp} when it answered a call the lane run waits on (see Approvals); attachment_rejected for files that cannot go (see Attachments); model_unavailable for a model that can't answer (see Model and thinking)
get_chat_messages {session_id, limit?, all_generations?} {success, protocol_version, session_id, messages, thread: {active_leaf_id, revision}, active_runs: [RunSnapshot]}
chat_subscribe {session_id} {success, session_id, hub_epoch, active_runs: [RunSnapshot]}
chat_unsubscribe {session_id} {success, session_id, hub_epoch}
get_chat_run {run_id} {success, run: RunSnapshot}, or not_found
stop_chat_run {run_id, expected_revision?, idempotency_key?} (revision/key required for controlled generations) Controlled: generation control snapshot plus {run_id, resumable: true}, state is pausing or paused. Legacy: {success, run_id, state: "stopping" | "stopped"}. not_stoppable for a terminal run.
chat_ui_state {session_id, part_id, changes: [{path, value}]} (at most 32; the last value per path wins) {success, part_id, state_revision}; not_found, invalid_request
edit_chat_message {session_id, message_id, message, expected_revision?, client_message_id?, options?: Options} {success, message_id, run_id, delivery} (the edit's id; a resent client_message_id answers the first edit)
regenerate_chat_reply {session_id, message_id, expected_revision?, options?: Options} (the latest answer, or the owner's last message when its run gave none) {success, message_id, run_id, delivery} (message_id: the owner's message answered again)
switch_chat_branch {session_id, message_id, expected_revision?} (a message beside one on the path) {success, leaf_id}
set_chat_feedback {session_id, message_id, value: "up" | "down" | null} {success, message_id, value, reaches: ["next_turn"]} ([] when taken back)
get_chat_context {session_id} {success, session_id, commands: [{command, description, fill, suggest}], capabilities: {attachments, web, model_choice}, limits: {max_attachments, max_upload_bytes}}
get_chat_models {session_id} (a workflow's chat; invalid_request for default) {success, session_id, auto: Model, models: [Model], efforts: [{id, label, hint}]}; Model is {id, name, short, description, effort, effort_note, available, reason} (see Model and thinking)
clear_chat_messages {session_id} {success}; also clears runs, parts, snapshots, notes and feedback, and makes the employee forget the conversation

send_chat_message with the same client_message_id (1 to 100 letters, digits or _.:-) returns the message and run the first call created, and dispatches nothing again.

Options are the choices sent with a message, an edit or a retry, kept on the run it starts (ChatRun.options): {web?: bool, model?: "auto" | "<provider>::<model>", effort?: "low" | "high"}. An option left out changes nothing.

RunSnapshot is the state the client reducer would hold after replaying the run's events (server/services/chat/reducer.py folds them the same way): {run_id, session_id, workflow_id, kind, state, seq, hub_epoch, user_message_id, reply_message_id, parent_run_id, created_at, started_at, finished_at, steps, segments: [{message_id, text, final}], activities: [{message_id, activity_type, content, patches}], outcome, result, error, error_code}. state is queued, pending, running, stopping, finished, error or stopped. A snapshot read after a server restart has its steps but no text segments or activities (those are stored with the reply).

For a run whose owning generation declares execution_control_version: 1, snapshots from get_chat_messages, chat_subscribe and get_chat_run also include workflow_control, serialized from that generation's existing control row. It includes workflow_id, root_execution_id, generation, execution_control_version, state, revision, the control capabilities, and last_resumed_at. This is derived control state, not an additional ChatRun.state: a suspended run may still have state running, pending or queued. Terminal states in the chat reducer remain terminal even when a control snapshot is present.

Approvals (server/services/approvals/handlers.py)

Handler Request Response
list_approvals {workflow_id?, status?: <row status> | "open" | "recent", run_id?, kind?: "gate" | "tool_call" | "effect", limit? (at most 100)}; status defaults to pending {success, approvals, counts: {workflow_id: pending}, server_time}
get_approvals {approval_ids} (at most 100) {success, approvals, server_time}
decide_approval {approval_id, decision: "send" | "undo" | "discard" | "restore" | "retry" | "dismiss", decision_key, text?, subject?, confirm?, note?, always?} {success, approval, idempotent?, will_send_on_resume}
get_ask_first {workflow_id} {success, workflow_id, ask_first: bool | null, mode: "outside" | "everything" | "money_only" | null, revision} (null: the workflow has no rule)
set_ask_first {workflow_id, ask_first | mode, expected_revision?} {success, workflow_id, ask_first, mode, revision, replies_gated, needs_apply}; rule_conflict (with the current values) when it moved
list_approval_allows {workflow_id} {success, workflow_id, allows: [{id, node_type, operation, scope_kind: "host" | "recipient" | "operation" | "tool", scope_value, label, created_at}], money: [{node_type, operation, label, allow_id}]}; money is the employee's money tools and operations, allow_id set where one is switched on
add_approval_allow {workflow_id, node_type, operation?}, one of the money options {success, allow}; invalid_request for anything else
remove_approval_allow {workflow_id, allow_id} {success}; not_found

open lists what the owner may still act on, or is on its way: pending, approved and not handed on, sending, failed, and discarded while it can be restored. recent lists everything, newest first. Only the owner's own drafts and workflows answer; any other id reads as not_found. decide_approval errors: already_decided, expired, cancelled, too_late (Undo after it went, Restore after its window), confirm_required (a retry of a send that broke off), approval_conflict, send_unavailable (nothing could start the send; the draft is back as it was), not_found, invalid_request (also for always on a card that offers no rule, and a note over 50,000 characters). The same decision_key again answers idempotent with the row as it is. note goes with discard; always with send saves the rule the card offers (always in its summary). will_send_on_resume is true for an approved row whose employee is stopped (generation above 0): it goes after Resume.

ApprovalSummary: {approval_id, workflow_id, node_id, kind: "gate" | "tool_call" | "effect", status, channel, channel_label, action?, recipient, recipient_label, body, subject?, context_excerpt?, details: [{label, value}], created_at, expires_at, revision, max_length, editable, approved_by?: "owner" | "auto", edited?, undo_until?, restore_until?, consumed_at?, outcome?: {certainty: "sent" | "not_sent" | "unknown", error?, at?}, outcome_labels: {sent, failed}, run_id?, tool_call_id?, ui_part_id?, agent_node_id?, deployment_state?, note?}, and on a tool_call row approval_class: "read" | "write" | "send" | "money" | null, generic (a tool with no spec: the card shows what it runs with), waits (its turn waits on it) and always: {label, scope} | null (the rule Always allow would save). status is pending, approved, sending, sent, failed, discarded, expired or cancelled; see Approvals. outcome_labels is what the card says once it went and when it did not: a held tool call's plugin words it (its ApprovalSpec.outcome_labels, "Email sent" for the email apps), a gate's draft says "Message sent". A draft that is not editable has no message to edit, and the card sends it as it is.

Plugins

Handler Owner Request Response
canvas_version nodes/tool/canvas {workflow_id, node_id, item_id, version} {success, item: CanvasItem-at-that-version & {latest}}
dictation_status nodes/speech {session_id} {success, available, provider}
transcribe_audio nodes/speech {session_id, path, language?} (path under uploads/) {success, text, language, provider}; speech_unavailable

Worker relay (server/services/chat/relay.py)

Internal: the backend accepts it on /ws/internal only (the worker token, services/authz/ws_surface.py INTERNAL_SOCKET_HANDLERS), and a client socket gets access_denied. The worker sends it without a request_id.

Handler Request Response
chat_run_publish {items} (at most 500): {kind: "run_event", run_id, session_id, workflow_id, suffix, fields, event_key}, {kind: "broadcast", type: "chat.updated" | "approval_lifecycle", data: <CloudEvent>, session_id?}, {kind: "resync", session_ids} {success, published, refused}; invalid_items

Standalone workers

The hub delivers to the sockets of the process it runs in. The backend's embedded workers share that process, but a standalone worker (run_standalone_worker, for horizontal scaling) does not. It starts a relay at boot (start_relay), and from then on publish_run_event, announce_chat_updated (services/chat_thread.py) and broadcast_approval_change (services/approvals/events.py) queue what they would have published. One writer sends the queue in order over the worker's own /ws/internal connection as chat_run_publish frames, at most hub.relay_batch_size items to a frame (server/config/chat_defaults.json), reconnecting with backoff when the backend restarts. The backend publishes each run event into its own hub, so seq, hub_epoch and the event_key dedupe are the backend's, exactly as for its own events. It sends each broadcast to its sockets only when the CloudEvent type matches the wire key.

Nothing waits on the relay, and nothing is resent. Past hub.relay_queue_size queued items an event is dropped, and so is a frame the connection lost. The next frame that gets through ends with a resync item for the sessions those belonged to, and the backend sends their subscribers opencompany.resync. Their clients take fresh snapshots, in which a stored terminal state wins. The rows are the record: text deltas a resync cannot restore are in the saved reply. Other broadcasts from a standalone worker's activities (node status, agent progress, Canvas and Memory updates) still reach only that process.

Messages

get_chat_messages returns the active path, oldest first:

{id, legacy_id, role, kind, text, message, timestamp, run_key, run_id, parent_id, status, attachments,
 parts, feedback, siblings: {index, count, ids}, editable, client_message_id?,
 run?: {run_id, state, outcome, error?: {message, code, hint?}, steps?: [{step_id, name, state, detail?,
        duration_ms?}], duration_ms?}}
  • id is the message's stable id (m_… for the owner's, a_<run id> for a run's reply; rows saved before chat runs are m<number>). legacy_id is the database row number.
  • message equals text; it is kept for older readers.
  • client_message_id is echoed on the owner's messages that carried one, so an optimistic row and its saved row keep one key.
  • run says how the run a message started (or answers) stood when the thread was read: its state, outcome, for a failed run the error with the hint the run recorded, the steps it saved, and once it has ended how long it worked (duration_ms). It is how a reload still shows that a message went unanswered and what the employee did; while the session is subscribed, the run's events are fresher (see Client).
  • siblings are the messages beside it (the same parent and role), oldest first, itself included: the owner's edits of a message, or the answers tried for one. index is its own place.
  • editable says the owner may change it now (the server decides): their text message a run answered, in the live generation (Edit), and the answer the path ends at once its run has ended (Try again).
  • run_id on the owner's message names the run answering it on this path: the run of the answer after it, else its newest run (an answer being tried again), else the run it started.
  • feedback is the owner's rating of an answer: up, down or null.
  • kind: text, report (Post to Talk: not editable), action (a button press), notice.
  • status: complete, stopped, error.

A reply shows, in this order whatever order they were produced in: its run's steps (run.steps above), its text, then its parts: generated UI, artifacts, approvals, sources, follow-ups. A reply ended by legacy Stop has status: "stopped". Controlled suspension does not change a saved reply's status or allocate a replacement reply.

parts: {
  ui?:        [{part_id, spec, state, state_revision, elements}],
  artifacts?: [{workflow_id, canvas_node_id, item_id, version, title, format}],
  approvals?: [{approval_id, tool_call_id?}],
  sources?:   [{n, title, url, detail?}],
  followups?: [string]
}

Approvals are joined live from the approvals store; the part only names them ({approval_id, tool_call_id}).

Artifacts name the documents (Canvas notes) the run wrote or revised, one entry per item at the latest version the run left it: the canvas tool calls show_artifact (artifact:<item_id>, so a later version replaces the earlier one) and publishes an activity.snapshot with activity_type: "artifact" and message_id: "artifact_<item_id>". The card (features/chat/turns/ArtifactCard.tsx) shows the title, Document or Code, the version, and Open, which asks the host to show the item at that version (Home: the Workspace's Canvas tab; the editor: the Canvas dock; see canvas_node.md). The client shows each saved document at the newer of its saved and live versions.

A run's tools record parts on the run as they go (chat_run_parts, keyed so a retried activity writes the same row; services/chat/parts.py). Reply in Chat saves its reply with the parts recorded so far, and the run's end seals any later ones into it, creating an empty-text reply when the run showed an interface, made a draft or wrote a document but wrote no text (sources alone make none: they show only where a reply cites them); the end is published after the seal, so its result.reply_message_id names a reply that holds them. A sealed item the reply already holds stays as it is there (the owner may have changed an interface's state since), except a document's, where the run's newer version wins in place.

Generated UI

  • Source. The employee calls the show_ui tool (chatUi plugin, nodes/chat/chat_ui) with a json-render flat spec {root, state, elements}. services/genui/spec.py checks it against server/config/chat_genui_catalog.json (JSON Schema per component, which prop each input binds, what each layout may hold, the limits): a spec that breaks a rule fails the call with every reason, so the model writes it again; unknown types, unreachable elements, stray fields and props are left out and reported back. The tool's description is generated from the same manifest, byte for byte the same for the same file, and a test on each side reads the other's catalogue. The checked spec is saved as a ui part and streamed as activity.snapshot (empty spec) followed by one activity.delta per patch: add /root, add /state, then add /elements/<id> in depth-first order (services/genui/patches.py, matching the handoff's *.patches.jsonl line for line). Only the agent answering the owner's chat message can show UI; a call anywhere else says nothing was shown.

  • Owner edits. $bindState writes go to the interface's own state store and to chat_ui_state; the last write per path wins, and the client sends after 300 ms idle, when the page hides, when the chat closes and before a button press goes (features/chat/data/uiState.ts). The server keeps them on the part (state, state_revision), on the reply once it is saved, so a reload shows them.

  • Buttons. A press resolves $state params at click time; the client tags each press with its element and label (json-render hands a handler the params only). ask sends its text as the owner's message only when it is what the button says (case and spacing aside); otherwise the text goes into the composer for review. Any other action becomes send_chat_message{ui_event: {part_id, element_id, action, params}}: the server checks it against the saved spec (a Button whose press runs that action, params it declares), saves the owner's message as the button's label (kind: "action", the press in meta.ui_event), starts a run of kind action, and sends the employee the line [ui-event]{"ui_id", "element", "label", "action", "params"}[/ui-event]. A press while the employee is still answering is held back with a notice. ui_event_rejected says why one does not fit.

  • Sanitising. json-render 0.21 does not guard state paths (setByPath descends into __proto__), does not validate props against the catalog, and supports watch (actions fired by state changes), repeat, $computed and an action binding's confirm, onSuccess and onError (the last two set state or run further actions). Both sides therefore (the client in client/src/lib/jsonRender/):

    • refuse __proto__, constructor and prototype path segments everywhere ($state, $bindState, $template, visible, action params, patch paths); an expression that reads such a path is dropped, and a visible condition that reads one is false;
    • keep only an element's type, props, children, visible and on, and only an action binding's action and params: watch, repeat, slots, confirm, onSuccess, onError and preventDefault go;
    • drop $computed, and $item, $index and $bindItem, which mean nothing without repeat;
    • validate every element's props (the client degrades one bad prop at a time with forgiving zod schemas);
    • drop unknown component types before rendering.

    json-render renders each element inside its own error boundary, so one failing element renders nothing instead of breaking the reply.

Runs

server/services/chat/ (never imports nodes/):

  • Admission (ledger.admit_message). send_chat_message writes the owner's message and its run in one write transaction reserved before its first read (Database.reserved_session, SQLite BEGIN IMMEDIATE), after checking the lane; a partial unique index on chat_runs enforces it too. A message starts a run only when a chat trigger in the deployed graph (the control generation's graph_snapshot) accepts its session, judged by that trigger's own filter (event_waiter.build_filter). Otherwise it is saved and dispatched without a run, like the editor's "default" session, which keeps its unscoped delivery.
  • Dispatch. The chat_message_received event (services/chat/events.py, source opencompany://services/chat) has the run id as its CloudEvent id when tracked, otherwise the saved message id, and carries message_id and run_id in data. The generation controller receives it through on_event, deduplicates each registered trigger's event key, and queues or starts its child MachinaWorkflow; legacy standalone listeners retain their existing route. The child id is <slug>-<trigger label>-<event id>. It is never broadcast. Open threads hear of the message (chat.updated) only after the dispatch attempt, so the sender's answer, which admits the run into their store, reaches them before their thread can read the run: told first, the thread showed the run live and read it with get_chat_run. The ingress path still uses eventually consistent Visibility and logs delivery errors: saving a message or returning delivery does not prove Temporal accepted its Signal. The accumulator's durable pending-event guarantee begins at Signal acceptance; no ingress outbox was added. A duplicate client_message_id returns the original message and run without redispatching it.
  • Start and finish. MachinaWorkflow, behind the machina-chat-run-v1 patch, reads the run id only from an event with that source and type, claims the run (chat_run.start: pending or queued to running, recording the Temporal workflow and run ids) once the firing trigger's output is stored, passes run_scope {run_id, session_id} to every node context (the chat's session, which the claim answers from the run's row; the workflow's own session is its execution's), and finishes it at its single exit (chat_run.finish). With several chat triggers in one graph, the first to claim tracks the run and the others run untracked. Only the claimant may finish.
  • The reply. chatReply with a run_scope saves the answer through ledger.post_reply: the first reply takes the run's reply id a_<run id>, another reply node in the same run a_<run id>.<n>, and a retry from the same node saves nothing new. A run whose conversation was reset or cleared posts nothing.
  • One chain. Every message is appended after the session's active leaf (chat_threads) inside the same reserved transaction, so concurrent writes never fork the thread.
  • The watchdog (services/chat/watchdog.py, started by main.py) sweeps every runs.watchdog_interval_s and ends the runs nothing will finish (codes above). It resolves each controlled run's owning generation, not the workflow's latest successor. While that generation is pausing, paused or resuming, its pending, queued and running runs are excluded from age expiry. After successful Resume, the existing generation manifest stores last_resumed_at: pending pickup counts from the latest of creation, server start and Resume; queued pickup follows the resumed delivery window; running expiry counts from the later of run start and Resume. Stop does not move controlled runs into the legacy stopping state, so they bypass grace-period cancellation. A running run past runs.max_running_s, controlled or not, has its workflow cancelled before it ends timed_out, unless its generation is paused or a turn of it waits for the owner. Temporal closure checks follow the current Workflow ID and compare execution chains across continue-as-new.

Streaming, steps and Stop

Settings are in server/config/chat_defaults.json (stream, steps, runs).

  • Who streams. agent.prepare_payload gives an agent a chat_stream (services/chat/stream.py chat_stream_for) when the run's run_scope reached it, it is not working for another agent (no parent_node_id), and its output goes straight to a node whose plugin declares answers_chat_run (Reply in Chat). The payload also carries chat_run_id for every agent of the run. Both ride the AgentWorkflow's activity inputs only (LLM steps and tool calls), so no workflow patch was needed and recorded histories replay unchanged.

  • Text. agent.execute_llm_step passes a ChatStreamEmitter as the provider's on_event sink (providers that declare streaming in llm_defaults.json stream; for the others the unifier replays the finished response as events: see Native LLM SDK). Deltas go out every stream.flush_ms or stream.flush_chars. A retried attempt first sends opencompany.segment_discarded for each earlier attempt's segment. Streaming never changes the step's result.

  • Steps. BaseNode.as_activity wraps every tool call that carries a chat_stream and a tool_call_id (services/chat/steps.py): step.started when it begins, step.finished when it ends, saved on the run as it finishes (ledger.record_step, at most steps.max_per_run). The label is the plugin's chat_step ("Searched the web"), else "Used "; plugins with chat_step_hidden (the clock, the checklist) show none, and skill loads (agent.skill.invoke) never pass through it. A tool may put a short line in its result as _step_detail ("3 events on Saturday"): it is shown under the step and taken out before the model reads the result.

  • Controlled Stop/Resume (execution_control_version: 1 on the owning generation). stop_chat_run resolves the run's exact generation using workflow_id and run_key matched to root_execution_id, then calls generation Stop with the revision, idempotency key and expected generation root. Already admitted work finishes and its results are recorded; queued work waits. The run remains nonterminal with the same reply identity, subscriptions, partial output and occupied lane. Live snapshots include the derived workflow_control; no additional persisted chat pause state exists. The watchdog excludes pausing, paused and resuming generations from pickup and running expiry; successful Resume supplies a fresh timeout window using lifecycle metadata last_resumed_at. Resume uses resume_workflow and releases the existing continuation. Independent Workspace tasks and separately approved sends remain independent. Full execution-tree admission, checkpoint, rollover and compatibility rules are in Temporal Workflow Control.

  • Legacy Stop (stop_chat_run, ledger.request_stop). A run nothing has picked up (pending, or queued until Resume) ends stopped at once and frees the lane; a workflow that picks it up later claims it still stopped (chat_run.start) and its agent answers nothing. A running run moves to stopping (custom opencompany.stopping) and stops itself:

    • its agent's model step polls the run every runs.stop_poll_s while the provider writes (an activity heartbeat arrives too late to stop a stream mid-sentence), drops the call, and returns what the owner saw so far as the final answer; a step about to start returns at once, before paying for a request;
    • a tool call not started yet is answered "Not run: the owner stopped this answer." without running;
    • Reply in Chat saves the partial answer with status: "stopped", and the run finishes with outcome stopped.

    A run still stopping runs.stop_grace_s after Stop (a long tool, a lost workflow) is ended by the watchdog, which cancels its Temporal workflow. The conversation keeps the stopped turn: the request and the partial answer (its text block marked stopped), or the request alone when nothing was written; a tool call a cancelled run left without a result is answered when the conversation is next loaded (see Agent Context Flow).

  • Agents that are not AgentWorkflows. Only the agents in AGENT_WORKFLOW_TYPES (services/temporal/workflow.py) run as an AgentWorkflow and are prepared by agent.prepare_payload. The others (Claude Code, Codex, RLM) run as one activity and get no chat_stream: nothing they write streams, their tool calls show no steps, they cannot show UI, and their answer appears when Reply in Chat saves it. Controlled Stop drains their whole activity before suspension. Legacy Stop moves their run to stopping, and the watchdog ends it runs.stop_grace_s later.

Controlled Stop acknowledgement

The client sends stop_chat_run {run_id, expected_revision, idempotency_key}. The server authorizes the run's session, resolves its immutable owning generation and supplies expected_root_execution_id: run.run_key to pause_workflow. A stale chat run cannot stop a newly started generation. The response is the existing workflow control payload, with run_id and resumable: true added; it is not a terminal chat-run snapshot.

pausing means Stop was requested and admission is closing or work is draining. Only paused acknowledges that admitted business work and result bookkeeping have settled across the controlled execution tree. For example, Stop during tool A lets A finish once and records its result; tool B from the same model response stays pending. Resume starts B in the same continuation without requesting that model response again. Admitted parallel tools drain concurrently under their declared retry policies. An LLM call keeps its existing unlimited retries, so a persistent provider outage can leave the generation Stopping until that call settles.

The request's acknowledgement deadline may expire while that durable transition continues. Keep the returned or refreshed pausing state, reconcile with get_workflow_control_status, and do not synthesize a chat stopped outcome or cancel the workflow. Resume sends resume_workflow {workflow_id, expected_revision, idempotency_key} after checking that the latest control still names the run's owning root; it releases existing descendants before producer admission reopens. The protocol uses completed Temporal Updates for control acknowledgement and read-only Queries for status, following Workflow Messaging Patterns.

Run and reply ids, saved parts, completed steps, subscriptions and lane occupancy survive suspension. Live text already received stays in the mounted conversation and in the process's hub snapshot. A reload restores the owning generation's control and persisted chat state; a server process restart still cannot reconstruct text deltas that were never saved in a reply. This existing streaming limitation is separate from durable Temporal continuation: Resume does not explicitly rerun completed tools to reconstruct the display.

Client

client/src/features/chat/ is the shared chat; only its index.ts is public (an ESLint rule keeps the rest private, tests excepted). Hosts give it a ChatHost (host.ts): the session and scope, who answers, whether the message box sends now, waits for Resume, shows but takes nothing yet (wait, with the host's placeholder: a new hire still starting) or is closed, and what sits around the conversation (notices, a top slot, a slot after the thread, an empty state, greetings that fill the box in place of the suggested commands, a footnote, how to tell the owner something), and two optional reports: onSent (a message went, or a draft the owner approved was sent) and onComposerChange (the box gained or lost the cursor or its text), which Home turns into the orb's spikes and energy. Home's employee page (EmployeeChat) and the editor's console pane (ConsoleChat, compact, scope live) are the two hosts.

  • Run events reach stores/chatRunStore.ts through one case 'chat_run_event' in WebSocketContext.tsx. lib/agui/events.ts checks each frame (source, type prefix, subject, id = <run id>:<seq>, scope fields) and lib/agui/reduceRun.ts folds it, the same way services/chat/reducer.py does. Frames are folded once per animation frame. Per run: a duplicate seq changes nothing; a gap, an unknown run already past seq 1, a new hub_epoch or the hub's resync frame mark the session syncing, hold what arrives meanwhile, and ask for a fresh snapshot, after which the held frames fold in and the ones the snapshot covers drop out; one that still cannot fold is dropped, never asked for again. A run's end folds in even across a gap or for a run not seen before (its saved reply holds what was missed), an ended run takes nothing more, and an ended reading of a run beats a live one whatever their seq (the hub forgets a run's seq once it ends).
  • Subscribing (data/runs.ts): a mounted chat subscribes its session whenever the socket is ready (so again after every reconnect) and whenever the store asks for a snapshot, retrying a failed subscribe after 1, 3, then every 10 seconds; the last chat following a session unsubscribes it. Runs the store held as live that a snapshot no longer lists ended unseen and are read once with get_chat_run. Until the first snapshot the thread's own active_runs stand in; after it the store alone says which runs are live, and a message whose run still reads live is read with get_chat_run (useThreadRunReconcile), as is a run this tab admitted itself (a resent message is answered with the run it started before) once the thread says that run has ended.
  • Turns (thread/model.ts): one per message with a divider where run_key changes. A run that is going, failed or was stopped (or finished, while its answer is on the way) shows on its last answer, or on a turn of its own right after its last message before it has answered (a live run whose messages are out of view goes last). Failures whose code only says no answer came (not_delivered, timed_out, interrupted) disappear once an answer lands; reset and cleared never show. A message sent from this tab and its saved row share a key (its client_message_id), and a run's first answer takes the key its run's turn had, so neither remounts.
  • Sending (data/send.ts): the message shows at once; the server's answer admits its run into the store (queued or pending), so the employee shows working before the run's first event. While the lane is held, Send is Stop in a running generation, disabled Stopping during pausing, and Resume during controlled suspension. A refused or failed send takes the message out of the thread and puts its text back in the box (state/composerStore.ts, a draft per session that survives switching conversations); after a failure in transit the draft keeps its client_message_id, so sending it again is the same message: the server answers with the first send's message and run, and when the thread already holds that message the local copy gives way to it.
  • A working run (turns/AssistantTurn.tsx): skeleton lines until text comes; then the latest segment, muted while it is narration, with a caret while it streams (ReplyMarkdown renders each finished block once, markdown/blocks.ts); a status line saying "Thinking", "Writing · N tok/s" or "Stopping…", with an Esc hint. The steps disclosure (turns/StepsDisclosure.tsx) sits on the run's first turn: "Working…" and open while the run works, "Worked for 12s · 3 steps" after; a run read back later starts it closed. A finished run keeps its turn until its saved reply lands in the thread, so the streamed answer and the reply stay one element.
  • Stop/Resume (data/stop.ts, data/control.ts): Stop or Esc sends stop_chat_run for the lane's run. Controlled requests use WebSocketContext.controlMutation, with a fresh idempotency key per bounded request attempt and the current control revision. Success and failure responses merge authoritative control snapshots before the request is judged; a transport or acknowledgement failure triggers a status resync. Controlled runs retain their chat state: the status line shows Stopping, the stopped turn says it waits for Resume, and the composer offers Resume, then disabled Resuming. useChatWorkflowControl merges a reload snapshot with newer broadcasts for the same root and retains the run's owning snapshot when a successor root differs. Resume re-reads status and checks the owning root before sending the current revision. Esc has no effect while stopped, stopping or resuming. Legacy responses still update the run's terminal lifecycle.
  • The box's extras (composer/): Attach, a paste and a drop on the chat (DropOverlay) all call addAttachments (composer/attachments.ts), which uploads each file at once into the box (state/attachmentStore.ts, chips with progress and Remove); Send waits while one uploads and sends the finished ones' paths. The microphone (VoiceRecorder, MediaRecorder with live levels) shows when dictation_status says a provider can transcribe. A draft that is one word starting with / opens SlashMenu (Popover over cmdk; focus stays in the box, which carries aria-controls and aria-activedescendant). The Web chip keeps the employee off web search for the next messages (composerStore.web). On Home, where capabilities.model_choice says the employee takes it, the model picker sits before the microphone (composer/ModelPicker.tsx; the host's modelPicker): a Popover anchored to the whole box (PopoverAnchor virtualRef), a cmdk list of Auto and the models from get_chat_models (data/models.ts), and a LevelSlider (components/ui/slider.tsx) for the level, or the model's effort_note. The choice lives in the owner's settings (chat_model / chat_effort), saved at once and put back when save_user_settings refuses it (SettingsSaveError, its detail shown); a message waits until it is known. Every send, edit and retry carries the same options (sendOptions in data/send.ts), and a model_unavailable refusal shows the server's detail. In an empty chat on Home, commands marked suggest show as cards that fill the box; the editor's chat, a console for trying chat triggers, shows none. Cmd/Ctrl+K focuses the box on Home; the editor's palette has Focus Chat.
  • Changing the conversation (data/branches.ts, thread/turnActions.ts): under the owner's message a hover bar (turns/UserTurn.tsx: time, ‹ 1 / 2 › between versions, Edit, Copy; Edit opens turns/UserEditBox.tsx in place, Enter sends, Esc cancels, ArrowUp in an empty box edits the last message); under a finished answer (turns/ReplyActions.tsx) Copy, Good and Bad (pressing again takes the rating back), Try again on the latest answer, ‹ 1 / 2 › between answers, and the time. A run that stopped or failed without an answer has Try again in its note. Each command sends the thread's revision as read; a refusal is told in the host's words (turns/runCopy.ts branchRefusalText), not_running through the host's own refusal. A rating shows at once and goes back when it does not save; its toast says the employee will see it next time (feedbackThanks). Suggested questions hide while the box holds text, and under a stopped answer.
  • Generated UI (features/chat/genui/, turns/GeneratedUiBlock.tsx): a reply's interfaces come from its saved parts.ui, or while the run streams them from its json_render activities (data/parts.ts), the run's first turn keeping them until the saved reply carries them, so one element shows throughout and keeps what the owner set. The renderer (genui/ChatUi.tsx, with json-render, in its own chunk) sanitizes again (genui/prepare.ts), draws the twelve components (genui/views.tsx, through lib/jsonRender/guard.tsx), reveals a live one element by element (forward only, so patches arriving in bursts never restart it), and routes any button action (genui/actions.ts, a Proxy over action names). The slot picker sits in a panel, and a toggle's whole row is its switch's label. Development builds show, on one row under the interface, its element count, the number of patches that build it (specToPatches, what the Inspect chip's patches tab lists) and the Inspect chip.

Approvals

What an employee sends to someone waits for the owner's OK while its workflow asks first (server/services/approvals/, models in server/models/approvals.py).

  • The rule. workflow_rules holds a workflow's Ask first, read every time something would send, so the chat's Ask first chip (set_ask_first) changes it with no restart. An employee's row is seeded from its ground rules the first time anything asks (a seeder the employees package registers), and a change is mirrored back into those rules and the employee's card. A workflow with no row (one built in the editor) has no rule: its tool calls run as before, and its approval gates wait for the owner as they always did.
  • Two kinds of draft, and one card for what may have happened. A gate row is an approvalGate node holding its run (an app reply). An effect row is a call that broke off midway and may have happened (see "At most once" below); the owner checks it and dismisses it. A tool_call row is a call to a tool whose plugin declares an approval spec (services/plugin/approval.py: which operations send, who it goes to, the body and subject the owner may edit, the card's other lines). BaseNode.as_activity checks every agent tool call (services/approvals/tool_calls.py): with Ask first on, a call that sends does not run; its row keeps what would run (the node's settings with the call's arguments over them, never the identity the node sends as) and the model reads that it waits for the owner. Whether a call sends is judged on what it runs with: a locked field (server_controlled_fields) the model set is put back to the node's setting first (tool_calls.as_it_runs, NodeExecutor's rule), so a model cannot talk a call out of being held. A tool that cannot wait is refused (Stripe) or runs restricted (the browser, read-only). With Ask first off the call runs; one made answering the owner in the chat leaves a row (approved_by: auto) with how it went. An approval gate with the rule off lets its draft through at once, recorded the same way.
  • Agents that are not AgentWorkflows (Claude Code, Codex, RLM; see Streaming, steps and Stop) call their tools in process (services/handlers/tools.py execute_tool), where tool_calls.check_in_process applies the same rule without drafts: with Ask first on, a call that sends is not run and the model reads why, the browser runs read-only, and nothing is recorded.
  • Decisions (services/approvals/decisions.py), each a compare-and-swap on the row's revision recorded in approval_decisions: send (pending -> approved; it goes after UNDO_SECONDS, 5, and Undo works until then; a held call's Undo also works past that while its send is not claimed, as while it waits for Resume), undo (approved -> pending), discard (pending -> discarded; Restore works for RESTORE_SECONDS on a gate's draft, whose run waits that long, and until expiry for a held call), restore, retry (failed -> approved; when the send broke off it may have gone, so the owner confirms) and dismiss (an effect row: failed -> cancelled). A gate waits through the Undo and Restore windows before it lets the draft through or not.
  • Sending a held call. Send starts ApprovedToolCallWorkflow (approval-send-<id>-r<revision>): it sleeps until the Undo window closes, claims the row at that revision (approvals.claim_send: approved -> sending; an Undo, a newer Send or a cancel moved it, and nothing runs), runs the node's own activity once with no retry, and records the outcome (approvals.record_outcome): sent, not_sent, or unknown when the activity broke off. The node's activity runs only under that claim.
    • Nothing goes while its employee is stopped (execution.send_state). The claim refuses (stopped) while the generation is pausing, paused or resuming, and the row stays approved.
    • The chat watchdog's round (reconcile.recover_sends, every round) starts such a send again once its employee runs, and so a send that never started.
    • A send whose generation ended (a Reset, a failure, a newer generation) is cancelled, and the employee told. A manual run's send (generation 0) is not held.
    • A send that never reported ends failed with an unknown outcome.
  • At most once. Temporal runs an activity again only when an attempt broke off (the worker stopped, a timeout); a failure the node reports comes back as a result and is not retried. A later attempt runs only a call that is safe to repeat (services/approvals/repeats.py: reads, waits, keyed calls, operations that do the same thing twice); any other call is not run again (tool_calls.redo_refusal, checked in BaseNode.as_activity after the approvals check, in the Coding Agent's workspace tools and in the legacy node activity). It answers SendOutcomeUnknown (a send the card can show: it may have gone out) or OutcomeUnknown (it may have happened), and tool_calls.record_unknown leaves the owner a card with outcome unknown: a tool_call row for such a send, with Send again behind a confirmation, else an effect row with Dismiss (dismiss: failed -> cancelled), which shows what the call ran with, without secrets. A graph node's answer carries requires_user_action and a hint, so its employee pauses at once, and its employee reads an [update] note; a graph node's send keeps what it sent, its templates resolved and its secrets left out, so Send again resends it and the node's settings put the secrets back. A call cut midway (the run cancelled it, its heartbeat lapsed, or the worker shut down) leaves the same card at once. A cancel stays a cancel. A worker shutdown retries a call safe to repeat; any other answers at once with the same envelope, since a later attempt could only refuse it. Held calls are drafts, made once per call, and still retry.
  • The employee hears how it went: an [update]{...}[/update] note (approval:<id>) at the start of its next turn in the chat, for a send that went, failed, was discarded or expired, and for a graph node's call that may have happened.
  • In the chat. A draft made answering the owner is recorded on the run (parts.approvals) and shown at once (an activity.snapshot with activity_type: "approval"); its card sits on that reply. A draft made in a run a button press started (its owner message carries meta.ui_event) records that interface (ui_part_id, ledger.ui_part_of_run), and the card says "Linked to the form above". Drafts no reply in view made (a gate's, from the employee's own work) show after the conversation. The card (features/chat/approval/): Discard / Edit / Send while it waits, "Sends in Ns" with Undo, Sending, Sent (and when, and whether Ask first was off), Restore while it can, Try again (asking first when it may have gone), and "Sends when you resume" for an approved draft whose employee is stopped (with Undo on a held call's). An effect card has no recipient and no message: "{name} tried to …", May have happened, and Dismiss only (Dismissed afterwards). Countdowns use the server's clock (server_time). Ctrl/Cmd+Enter sends the newest waiting draft; in the edit box it sends that one.
  • Ends. Clearing or resetting the chat cancels the drafts its runs made that still wait, and their failed sends, whose Try again would send from a conversation that is gone; a Reset cancels the waiting gates too (approvalGate.reset_execution_state); deleting the workflow deletes its drafts and its rule. Leaving a branch cancels only the drafts that still wait (see Branches), so a failure shows again on the way back.
  • Expiry. A gate's draft expires after the node's timeout_hours (168 by default), and the waiting gate ends it expired and lets nothing through. A held call's draft expires 168 hours after it was made (DEFAULT_TIMEOUT_HOURS). The chat watchdog ends every draft past its expiry on its next round (reconcile.expire_due) and announces it: a held call's, telling the employee, and a gate's, so one no gate waits on any more does not stay waiting. A decision that reaches a draft past its expiry ends it the same way and answers expired. Rows are kept until their workflow is deleted.
  • Generations that wait for the owner (RFC-0007, approval_wait_version 1, frozen per generation). Start does not write it yet, so every generation works as above until it does. In such a generation:
    • What asks is the workflow's mode (workflow_rules.mode), applied to the call's class (services/approvals/classes.py), for every tool an agent calls, with or without a spec.
      • outside asks before sends and money, everything before writes too, and money_only before money and deletes only. A rule with no mode follows Ask first: on is outside, off is money_only.
      • A read never asks, and a tool the class table does not list is a send.
      • A tool with no spec asks on a generic card. The browser asks only when it fetches a URL, and otherwise runs read-only. Stripe asks instead of being refused.
    • Always-allow rules (approval_allows, services/approvals/allows.py) let a matching call run unasked.
      • A card whose turn waits on it offers one (Always allow), but never for money: the employee's list switches money tools on instead (list_approval_allows).
      • The chat shows the Ask first menu, with "Allowed without asking", in place of the chip while the latest generation waits (approval_wait_version in the control snapshot, from serialize_control).
    • The agent answering a chat run waits in its turn (a turn row, waits: true). AgentWorkflow waits in ApprovalWorkflow for the answer (Temporal Architecture).
      • Allow runs the call in the turn, once, and the model reads its real result. There is no Undo, no ApprovedToolCallWorkflow, no Restore and no [update] note.
      • Decline (with an optional note), expiry and a cancel tell the model that nothing ran.
      • Chat Stop pauses the employee while the call waits; a call allowed meanwhile runs after Resume.
    • Every other held call (another run's, a teammate's, a CLI or in-process agent's) is a draft. A CLI or in-process draft is keyed by its call id (an MCP call's request digest), and a call without one is refused.
    • A message sent while the turn waits declines the call instead of starting a run.
      • The message is the note, nothing is saved in the thread, and send_chat_message answers declined. The same client_message_id again answers the same.
      • The model reads that the owner sent a message instead of answering.
      • A message with files, or a button press, answers run_in_progress.
    • The run's clock. The chat watchdog does not time out a run whose turn waits, and the owner's answer starts its window again. When the run's workflow closes, or a Reset ends its generation, the calls its turns waited on are cancelled (waiting.cancel_waits).
    • The approvalGate waits outside Stop's checkpoint: Stop completes while it waits, and the node after it runs after Resume.
  • Broadcast. approval_lifecycle (source opencompany://services/approvals, type com.opencompany.approval.<stage>: requested, decided, undone, restored, sending, sent, failed, expired, cancelled), identity only, with the chat run when there is one.

Attachments

services/chat/attachments.py. The chat uploads each file first (POST /api/workspace/{workflow_id}/uploads, which stores it under uploads/) and sends only the paths with the message. The server rebuilds each reference from the file itself (name, type, size, address), refusing a path outside uploads/, a file no longer there, or more than six (attachment_rejected); only a workflow's chat takes files, and a message may be files alone. The message keeps the references (attachments on the wire), the chat trigger's output carries them, and an edit keeps the original's.

The agent answering the run reads them after the owner's words as [attachments]{"files": [{path, name, type, bytes}]}[/attachments] (services/chat/guide.py chat_turn), so its file tools can open them. Images also travel on the opening user message as ref-only image blocks (agent.prepare_payload user_images -> agent_workflow._owner_message), hydrated per provider call for a provider that declares vision.user_images (llm_defaults.json: Anthropic, OpenAI, Gemini; each encoder's own shape) and named with their workspace path for any other.

Web off (options.web: false, kept on the run) leaves the tools in the search group out of that run (agent_activities._without_web_tools, over the options _chat_run_options reads once). Dictation (nodes/speech/_handlers.py): the first provider in speech_defaults.json dictation.providers with a stored key transcribes a recording the chat uploaded, and the recording is deleted. Commands come from chat_defaults.json commands.generic and the employee's apps (employee_apps.json commands, found through the saved graph's node types); {name} is the workflow's name, and suggest puts a command in an empty chat. capabilities.web is whether the saved graph has a search tool.

Model and thinking

services/chat/choice.py. Home's employee chat has a model picker: Auto, then the models in llm_defaults.json chat_models (each a provider::model id from that provider's popular_models), and how hard the model thinks: Quick (effort: "low"), Balanced (no effort sent: the agent's own settings) or Thorough ("high"). Every word the picker shows comes from chat_defaults.json choice. The Dev editor's chat has no picker: each node keeps its model.

  • Auto is the owner's default model (Set Global Model, UserSettings.default_llm_provider / default_llm_model). With none set it is the OpenCompany Gateway's default while the gateway serves it (gateway_default, Gemini 3.8 Flash; see llm_gateway.md). With neither it changes nothing, and the employee answers on its own model.
  • The choice is the owner's, saved with their settings (UserSettings.chat_model, default "auto", and chat_effort, default "") through save_user_settings, which refuses a model the picker doesn't offer or an effort other than low / high (chat_choice_refused). The client sends it as options.model / options.effort with every message, edit and retry.
  • Admission resolves it (run_options) and keeps the result on the run: Auto becomes the default's provider::model (nothing when no default is set). A model whose provider has no key, or one the picker no longer offers, is refused with model_unavailable and a detail in the owner's words, and nothing is saved; there is never a silent fallback to another model.
  • Only the agent that answers the chat run applies it (chat_stream_for): agent.prepare_payload replaces the node's provider and model with the chosen ones before the credential check, and drops the node's own api_key, so the chosen provider's key is the one checked. Other agents in the run keep their own models. The LLM step falls back to a node's own key only for the node's own provider (_resolve_activity_api_key), so a node's key never goes to another vendor.
  • Effort rides the prepared payload into each LLM step (effort, activity input only) and reaches the provider only for a model in its provider's effort_models (ChatUnifier, supports_effort): Anthropic as output_config.effort, OpenAI as reasoning_effort (Chat Completions) or reasoning.effort (Responses), Gemini 3 as thinking_level. It never turns thinking on or off; any other model answers as without it, and the picker shows effort_note ("{model} sets its own pace") in place of the levels.
  • get_chat_models lists the picker for one employee: Auto's row says what Auto uses now (the default model, or the answering agent's own), then the offered models whose provider is connected, plus the saved choice's row even when it can't answer (available: false with its reason).
  • capabilities.model_choice (get_chat_context) is whether the employee applies a choice: its answering agent runs as an AgentWorkflow (AGENT_WORKFLOW_TYPES, with TEMPORAL_AGENT_WORKFLOW_ENABLED on). A Claude Code or RLM agent never does, so the client shows no picker for it. The saved graph decides it, so the client refetches the context (queryKeys.chatContext) when the server saves a change to that graph (workflow_ops_apply with persisted, handled by useSavedGraphSync): after Turn on Talk the picker shows without a reload.

Branches

services/chat/branches.py. A session's messages form a tree: each row names the one before it (parent_uid) and chat_threads.active_leaf_uid is where the path shown ends; get_chat_messages returns that path only.

  • Edit (edit_chat_message) adds the new text beside the message it edits (same parent; meta.edit_of names the original) and starts a run of kind edit answering it (parent_run_id: the original's run).
  • Try again (regenerate_chat_reply) moves the leaf back to the owner's message and starts a run of kind regenerate for it (user_message_id: that message), whose answer goes beside the old one. Only the answer the path ends at, or the owner's last message when its run ended without an answer.
  • Switch (switch_chat_branch) moves the leaf to the newest message in the chosen version's branch.

Memory follows the path. agent.prepare_payload records, on the chat run an agent with a stored conversation works for, that conversation as the run began (chat_runs.context_cursors[agent] = {generation, length, digest}, the digest leaving out the stored ts stamps; the first preparation in a run wins). A move takes every agent the runs on the part it leaves touched back to the cursor of the first such run, after checking the stored conversation still starts that way, and keeps their conversations under the left branch's leaf (chat_branch_snapshots, at most branches.max_snapshots_per_session per session and branches.max_snapshot_bytes each, config/chat_defaults.json). A switch restores the snapshots of the branch it moves to. It all runs in one reserved write transaction under the conversation store's locks (conversation_lock), and is refused with:

  • revision_conflict: expected_revision is not the thread's revision (something was added meanwhile);
  • run_in_progress: a run holds the lane;
  • cannot_rewind: a stored conversation no longer starts the way it did (summarized or cleared since); going back to an empty conversation always works;
  • branch_unavailable: the branch switched to has no kept conversation for an agent that worked on it;
  • older_generation: a message or run from before the live generation;
  • not_editable / not_found: not the owner's text message a run answered, not the latest answer, or not on the path.

After it commits, the Context listeners hear of each conversation changed, the drafts the runs on the part left made that still wait are cancelled (approval_lifecycle cancelled), and an [update] note (branch:<run id>) tells the employee what those runs sent anyway. chat.updated follows (role user for an edit, null for a retry or a switch), after the dispatch for an edit or a retry, as for a new message.

Feedback

set_chat_feedback keeps the owner's rating of an answer (chat_feedback, one per answer; services/chat/ feedback.py) and leaves a [feedback]{"rating": "good" | "bad", "answer": "<excerpt>"}[/feedback] note (feedback:<message id>; taking the rating back drops it while untold). reaches lists where the rating goes: next_turn, the employee's next turn (empty when the rating is taken back).

Notes to the employee

Things the employee should learn on its next turn are kept in chat_notes (services/chat/notes.py) and put ahead of that turn's user message, one bracketed line each: [ui-state]{"ui_id", "state"}[/ui-state], written by chat_ui_state for what the owner set without pressing anything; [update]{...}[/update] for what became of a draft (approval:<id>) or what a branch left behind still sent (branch:<run id>); and [feedback]{...}[/feedback] for a rating. A note is keyed per session (ui-state:<part id>), so a newer one replaces an older one not yet told. agent.prepare_payload claims the session's untold notes for the agent answering a run (the one with a chat_stream); the run's end marks them told when it answered (it finished, or it stopped having written something), so a run that failed or stopped before writing offers them again, and a note changed after its claim stays untold. Clearing the chat forgets them.

The answering agent's system prompt ends with a fixed guide (services/chat/guide.py CHAT_REPLY_GUIDE, byte for byte the same on every turn): bracketed lines come from OpenCompany, not from the owner; a search result numbered n is cited as [n]; and how to suggest follow-ups.

Follow-ups

The answering agent may end its reply with <followups>["…", "…"]</followups> (a list of lines works too). The stream holds the block back; Reply in Chat takes it off the reply (guide.split_followups: the last block, at most 3 suggestions, 160 characters each, repeats dropped) and saves the suggestions as parts.followups. Outside a chat run the block is dropped, and a message that is only the block posts nothing. The chat shows them as buttons under the latest answer only, once it is done; one sends its text as the owner's message, or waits in the box while an answer is still coming.

Sources

A plugin that declares chat_sources (the web searches) returns results with addresses. When the answering agent calls it, BaseNode.as_activity numbers them for the conversation (services/chat/sources.py: the session's counter chat_threads.next_source, so a number never repeats in a conversation and an older [n] keeps meaning what it did), writes n on each result the model reads, and saves {n, title, url, detail?} (at most 10 per call) as a sources part of the run; the reply carries them as parts.sources. The guide tells the agent to cite what it relies on as [n]. The client numbers a reply's sources 1, 2, ... in the order its text first cites them (markdown/citations.ts): each [n] outside code reads as a chip with that number and a tooltip naming the source, and the cited sources are listed under the answer (turns/SourceChips.tsx); sources it did not cite are not shown. A reply may cite a source an earlier search found: each answer resolves [n] against the conversation's sources up to it (thread/model.ts, ChatTurn.sources).

Fixtures

client/src/features/chat/__fixtures__/ holds the design handoff's examples in this protocol's shapes, for client and server tests alike:

  • <name>.spec.json and <name>.patches.jsonl (saturday-booking, reply-insights, reminders): json-render specs and the depth-first patch stream for each. SlotPicker options use the catalog's generic keys (time, detail, recommended, unavailable, note) instead of the handoff's salon ones.
  • saturday-booking.events.json: the handoff's AG-UI run as chat_run_event frames, as the server sends them: steps, text, a generated UI streamed as activity.delta patches, the card of a held WhatsApp send (activity_type: "approval", as parts.show_approval publishes it), and finished with outcome success.

Error codes

Code Where Meaning
run_in_progress send, edit, regenerate, switch A run is live in this session; run_id names it (send only).
save_failed send, edit, regenerate, switch The change could not be saved; nothing was dispatched.
not_running send, edit, regenerate, switch The employee is not running and cannot queue messages (a switch: nothing was started since the last Reset).
engine_unavailable send, edit, regenerate A workflow's chat while Temporal is not connected: nothing could deliver the message, so nothing was saved.
invalid_request send, save, edit, regenerate, get_chat_models A malformed field (detail says which): an empty message, a role other than the owner's, a bad client_message_id, or an effort other than low / high; get_chat_models for the default session.
model_unavailable send, edit, regenerate The model chosen can't answer: its provider isn't connected, or the picker no longer offers it. detail says so in the owner's words; nothing was saved.
chat_choice_refused save_user_settings A saved chat_model the picker doesn't offer, or a chat_effort other than "", low or high.
read_failed get_chat_messages, chat_subscribe The thread could not be read. Never answered as an empty thread.
not_found get_chat_run, stop_chat_run No such run.
attachment_rejected send A file outside uploads/, gone, or more than six; detail says which.
not_stoppable stop_chat_run The run ended before Stop reached it; state says how.
idempotency_key_required / expected_revision_required controlled stop_chat_run The generation mutation lacks its request identity or revision.
control_generation_conflict controlled stop_chat_run, Resume The run's owning root differs from the generation currently being controlled. Refresh control; do not target the successor using the old run.
control_revision_conflict controlled stop_chat_run, Resume The generation revision changed; the response/status supplies the authoritative control. This revision is distinct from the thread's revision.
workflow_control_transition_pending controlled stop_chat_run, Resume, Reset A durable lifecycle transition is still in progress. Reconcile control status; the chat run remains live. A version 1 Stop or Resume whose drain outlasts 10 s answers success with transition_pending: true instead; Reset answers this code when Workspace cleanup has not answered in 240 s, with the row still resetting.
revision_conflict edit, regenerate, switch expected_revision is not the thread's revision.
rule_conflict set_ask_first expected_revision is stale; the answer carries the current value.
not_editable edit, regenerate, decide Not the owner's text message a run answered, not the latest answer, the editor's default chat, or an edited argument that is not editable.
older_generation edit, regenerate, switch A message or run from before the employee restarted.
cannot_rewind edit, regenerate, switch An agent's stored conversation no longer starts the way it did when the run being undone began.
branch_unavailable switch The branch's kept conversations are gone (too many branches, or too large to keep).
ui_event_rejected send The element or action does not match the saved spec.
access_denied all The session names no saved workflow, the socket's principal does not own it, or it is the internal worker socket.
too_late decide The Undo or Restore window has passed.
speech_unavailable transcribe_audio No dictation provider has a stored key.