Self-improving AI Employees for everyone
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 insidedata, never as top-level CloudEvents extension attributes. seqincreases by one per run. The client drops duplicates(run_id, seq)and asks for a snapshot on a gap.hub_epochchanges when the server process restarts. A changed epoch means the client must resync.chat_subscribeanswers with the session's live runs as snapshots, each with theseqit reflects. The hub is read before the database, so an event published meanwhile carries a higherseqthan its snapshot: drop events withseqat or below the snapshot's, and buffer events that arrive before the response.- Each subscriber has a bounded queue (
hub.subscriber_queue_sizeinserver/config/chat_defaults.json). A socket that falls that far behind has its queue replaced by onecustomopencompany.resyncper session it follows (data: {session_id, hub_epoch, name, value}, norun_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.updatedremains an identity-only broadcast ({workflow_id, session_id, role}) that tells every open thread to refetchget_chat_messages: after a message is added, after a clear, and when a run ends (rolenull), 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?}}
idis the message's stable id (m_…for the owner's,a_<run id>for a run's reply; rows saved before chat runs arem<number>).legacy_idis the database row number.messageequalstext; it is kept for older readers.client_message_idis echoed on the owner's messages that carried one, so an optimistic row and its saved row keep one key.runsays how the run a message started (or answers) stood when the thread was read: itsstate,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).siblingsare 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.indexis its own place.editablesays 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_idon 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.feedbackis the owner's rating of an answer:up,downor 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_uitool (chatUiplugin,nodes/chat/chat_ui) with a json-render flat spec{root, state, elements}.services/genui/spec.pychecks it againstserver/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 auipart and streamed asactivity.snapshot(empty spec) followed by oneactivity.deltaper patch:add /root,add /state, thenadd /elements/<id>in depth-first order (services/genui/patches.py, matching the handoff's*.patches.jsonlline for line). Only the agent answering the owner's chat message can show UI; a call anywhere else says nothing was shown.Owner edits.
$bindStatewrites go to the interface's own state store and tochat_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
$stateparams at click time; the client tags each press with its element and label (json-render hands a handler the params only).asksends 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 becomessend_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 inmeta.ui_event), starts a run of kindaction, 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_rejectedsays why one does not fit.Sanitising. json-render 0.21 does not guard state paths (
setByPathdescends into__proto__), does not validate props against the catalog, and supportswatch(actions fired by state changes),repeat,$computedand an action binding'sconfirm,onSuccessandonError(the last two set state or run further actions). Both sides therefore (the client inclient/src/lib/jsonRender/):- refuse
__proto__,constructorandprototypepath segments everywhere ($state,$bindState,$template,visible, action params, patch paths); an expression that reads such a path is dropped, and avisiblecondition that reads one is false; - keep only an element's
type,props,children,visibleandon, and only an action binding'sactionandparams:watch,repeat,slots,confirm,onSuccess,onErrorandpreventDefaultgo; - drop
$computed, and$item,$indexand$bindItem, which mean nothing withoutrepeat; - 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.
- refuse
Runs
server/services/chat/ (never imports nodes/):
- Admission (
ledger.admit_message).send_chat_messagewrites the owner's message and its run in one write transaction reserved before its first read (Database.reserved_session, SQLiteBEGIN IMMEDIATE), after checking the lane; a partial unique index onchat_runsenforces it too. A message starts a run only when a chat trigger in the deployed graph (the control generation'sgraph_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_receivedevent (services/chat/events.py, sourceopencompany://services/chat) has the run id as its CloudEvent id when tracked, otherwise the saved message id, and carriesmessage_idandrun_idindata. The generation controller receives it throughon_event, deduplicates each registered trigger's event key, and queues or starts its childMachinaWorkflow; 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 withget_chat_run. The ingress path still uses eventually consistent Visibility and logs delivery errors: saving a message or returningdeliverydoes not prove Temporal accepted its Signal. The accumulator's durable pending-event guarantee begins at Signal acceptance; no ingress outbox was added. A duplicateclient_message_idreturns the original message and run without redispatching it. - Start and finish. MachinaWorkflow, behind the
machina-chat-run-v1patch, reads the run id only from an event with that source and type, claims the run (chat_run.start:pendingorqueuedtorunning, recording the Temporal workflow and run ids) once the firing trigger's output is stored, passesrun_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.
chatReplywith arun_scopesaves the answer throughledger.post_reply: the first reply takes the run's reply ida_<run id>, another reply node in the same runa_<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 bymain.py) sweeps everyruns.watchdog_interval_sand 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 ispausing,pausedorresuming, its pending, queued and running runs are excluded from age expiry. After successful Resume, the existing generation manifest storeslast_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 legacystoppingstate, so they bypass grace-period cancellation. A running run pastruns.max_running_s, controlled or not, has its workflow cancelled before it endstimed_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_payloadgives an agent achat_stream(services/chat/stream.pychat_stream_for) when the run'srun_scopereached it, it is not working for another agent (noparent_node_id), and its output goes straight to a node whose plugin declaresanswers_chat_run(Reply in Chat). The payload also carrieschat_run_idfor 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_steppasses aChatStreamEmitteras the provider'son_eventsink (providers that declarestreaminginllm_defaults.jsonstream; for the others the unifier replays the finished response as events: see Native LLM SDK). Deltas go out everystream.flush_msorstream.flush_chars. A retried attempt first sendsopencompany.segment_discardedfor each earlier attempt's segment. Streaming never changes the step's result.Steps.
BaseNode.as_activitywraps every tool call that carries achat_streamand atool_call_id(services/chat/steps.py):step.startedwhen it begins,step.finishedwhen it ends, saved on the run as it finishes (ledger.record_step, at moststeps.max_per_run). The label is the plugin'schat_step("Searched the web"), else "Used "; plugins withchat_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: 1on the owning generation).stop_chat_runresolves the run's exact generation usingworkflow_idandrun_keymatched toroot_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 derivedworkflow_control; no additional persisted chat pause state exists. The watchdog excludespausing,pausedandresuminggenerations from pickup and running expiry; successful Resume supplies a fresh timeout window using lifecycle metadatalast_resumed_at. Resume usesresume_workflowand 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) endsstoppedat once and frees the lane; a workflow that picks it up later claims it stillstopped(chat_run.start) and its agent answers nothing. A running run moves tostopping(customopencompany.stopping) and stops itself:- its agent's model step polls the run every
runs.stop_poll_swhile 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 outcomestopped.
A run still stopping
runs.stop_grace_safter 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 markedstopped), 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).- its agent's model step polls the run every
Agents that are not AgentWorkflows. Only the agents in
AGENT_WORKFLOW_TYPES(services/temporal/workflow.py) run as an AgentWorkflow and are prepared byagent.prepare_payload. The others (Claude Code, Codex, RLM) run as one activity and get nochat_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 tostopping, and the watchdog ends itruns.stop_grace_slater.
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.tsthrough onecase 'chat_run_event'inWebSocketContext.tsx.lib/agui/events.tschecks each frame (source, type prefix,subject,id=<run id>:<seq>, scope fields) andlib/agui/reduceRun.tsfolds it, the same wayservices/chat/reducer.pydoes. Frames are folded once per animation frame. Per run: a duplicateseqchanges nothing; a gap, an unknown run already pastseq1, a newhub_epochor the hub's resync frame mark the sessionsyncing, 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 theirseq(the hub forgets a run'sseqonce 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 withget_chat_run. Until the first snapshot the thread's ownactive_runsstand in; after it the store alone says which runs are live, and a message whoserunstill reads live is read withget_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 whererun_keychanges. 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;resetandclearednever show. A message sent from this tab and its saved row share a key (itsclient_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 (queuedorpending), 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 duringpausing, 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 itsclient_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 (ReplyMarkdownrenders 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 sendsstop_chat_runfor the lane's run. Controlled requests useWebSocketContext.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.useChatWorkflowControlmerges 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 calladdAttachments(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 whendictation_statussays a provider can transcribe. A draft that is one word starting with/opensSlashMenu(Popover over cmdk; focus stays in the box, which carriesaria-controlsandaria-activedescendant). The Web chip keeps the employee off web search for the next messages (composerStore.web). On Home, wherecapabilities.model_choicesays the employee takes it, the model picker sits before the microphone (composer/ModelPicker.tsx; the host'smodelPicker): a Popover anchored to the whole box (PopoverAnchor virtualRef), a cmdk list of Auto and the models fromget_chat_models(data/models.ts), and aLevelSlider(components/ui/slider.tsx) for the level, or the model'seffort_note. The choice lives in the owner's settings (chat_model/chat_effort), saved at once and put back whensave_user_settingsrefuses it (SettingsSaveError, itsdetailshown); a message waits until it is known. Every send, edit and retry carries the sameoptions(sendOptionsindata/send.ts), and amodel_unavailablerefusal shows the server'sdetail. In an empty chat on Home, commands markedsuggestshow 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 opensturns/UserEditBox.tsxin 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.tsbranchRefusalText),not_runningthrough 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 savedparts.ui, or while the run streams them from itsjson_renderactivities (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, throughlib/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_rulesholds 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
gaterow is an approvalGate node holding its run (an app reply). Aneffectrow is a call that broke off midway and may have happened (see "At most once" below); the owner checks it and dismisses it. Atool_callrow is a call to a tool whose plugin declares anapprovalspec (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_activitychecks 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.pyexecute_tool), wheretool_calls.check_in_processapplies 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 inapproval_decisions:send(pending -> approved; it goes afterUNDO_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 forRESTORE_SECONDSon 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) anddismiss(aneffectrow: 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, orunknownwhen 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
failedwith an unknown outcome.
- Nothing goes while its employee is stopped (
- 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 inBaseNode.as_activityafter the approvals check, in the Coding Agent's workspace tools and in the legacy node activity). It answersSendOutcomeUnknown(a send the card can show: it may have gone out) orOutcomeUnknown(it may have happened), andtool_calls.record_unknownleaves the owner a card with outcomeunknown: atool_callrow for such a send, with Send again behind a confirmation, else aneffectrow with Dismiss (dismiss: failed -> cancelled), which shows what the call ran with, without secrets. A graph node's answer carriesrequires_user_actionand ahint, 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 (anactivity.snapshotwithactivity_type: "approval"); its card sits on that reply. A draft made in a run a button press started (its owner message carriesmeta.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). Aneffectcard 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 itexpiredand 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 answersexpired. Rows are kept until their workflow is deleted. - Generations that wait for the owner (RFC-0007,
approval_wait_version1, 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.outsideasks before sends and money,everythingbefore writes too, andmoney_onlybefore money and deletes only. A rule with no mode follows Ask first: on isoutside, off ismoney_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_versionin the control snapshot, fromserialize_control).
- A card whose turn waits on it offers one (Always allow), but never for money: the employee's list switches
money tools on instead (
- The agent answering a chat run waits in its turn (a
turnrow,waits: true). AgentWorkflow waits inApprovalWorkflowfor 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.
- Allow runs the call in the turn, once, and the model reads its real result. There is no Undo, no
- 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_messageanswersdeclined. The sameclient_message_idagain 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 message is the note, nothing is saved in the thread, and
- 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.
- What asks is the workflow's mode (
- Broadcast.
approval_lifecycle(sourceopencompany://services/approvals, typecom.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; seellm_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", andchat_effort, default"") throughsave_user_settings, which refuses a model the picker doesn't offer or an effort other thanlow/high(chat_choice_refused). The client sends it asoptions.model/options.effortwith every message, edit and retry. - Admission resolves it (
run_options) and keeps the result on the run: Auto becomes the default'sprovider::model(nothing when no default is set). A model whose provider has no key, or one the picker no longer offers, is refused withmodel_unavailableand adetailin 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_payloadreplaces the node's provider and model with the chosen ones before the credential check, and drops the node's ownapi_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'seffort_models(ChatUnifier,supports_effort): Anthropic asoutput_config.effort, OpenAI asreasoning_effort(Chat Completions) orreasoning.effort(Responses), Gemini 3 asthinking_level. It never turns thinking on or off; any other model answers as without it, and the picker showseffort_note("{model} sets its own pace") in place of the levels. get_chat_modelslists 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: falsewith itsreason).capabilities.model_choice(get_chat_context) is whether the employee applies a choice: its answering agent runs as an AgentWorkflow (AGENT_WORKFLOW_TYPES, withTEMPORAL_AGENT_WORKFLOW_ENABLEDon). 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_applywithpersisted, handled byuseSavedGraphSync): 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_ofnames the original) and starts a run of kindeditanswering 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 kindregeneratefor 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_revisionis 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.jsonand<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 aschat_run_eventframes, as the server sends them: steps, text, a generated UI streamed asactivity.deltapatches, the card of a held WhatsApp send (activity_type: "approval", asparts.show_approvalpublishes it), andfinishedwith outcomesuccess.
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. |