Skip to content

Work phases: what an agent is doing, said one way

Generated from PersonalClaw v0.3.9, the release this site publishes.

What an agent is doing reaches every surface as one phase of a closed set, which the gateway decides from what it measures and sends as a work_phase frame. No surface guesses a phase from words, a timer or a flag of its own.

  • Vocabulary: src/personalclaw/work_phase.py (gateway) and web/src/lib/workPhase.ts (web), pinned equal in both directions by tests/test_work_phase_vocabulary.py
  • A chat’s phases: src/personalclaw/dashboard/chat_phase.py, fed by the chat runner (dashboard/chat_runner.py), the approval registry and the owner’s questions
  • A helper’s, a loop’s and a workflow run’s phases: src/personalclaw/work_phases.py, fed by the subagent manager’s events, the approval registry, the loop store and a run’s publisher
  • Work references: src/personalclaw/workref.py
  • Design: the phase contract, each phase’s line in copy, and the agent orb’s phase to state table

Each phase has one meaning, one tone, one of four families and the copy row its line is written from. The line holds the state only; a surface adds the work’s name and cuts the line to its own room.

PhaseMeaningToneFamilyLine
queuedaccepted, not started yetprimaryactiveWaiting to start
thinkingstarted, no output yetprimaryactiveThinking
searchingsearching knowledge, memory, the web or the filesprimaryactiveSearching your knowledge
toolrunning any other toolprimaryactivethe tool’s own label
planningmaking or revising a planprimaryactivePlanning
delegatinghanding work to helpersprimaryactiveHanding off to 2 helpers
streamingwriting its answerprimaryactiveWriting
listeningpush-to-talk capture is livewarnactive
approvalwaiting on the owner’s yeswarnwaitingNeeds your OK: shell
inputwaiting on the owner’s answerinfowaitingAsks: Which branch?
donefinishedokquietDone in 12 seconds
errorfaileddangerblockedStopped: the reason
retryinga retry or a fail-over is pendingprimaryactive
waiting_modelheld behind other calls on a local modelprimaryactive
idlenothing queued or runningneutralquiet(empty)

Tones. Live work is the scheme’s primary (coral), never a colour of its own. Waiting on the owner’s yes is warn and on their answer info, a finish is ok, a failure danger, and nothing running carries no accent. Listening keeps warn, which matches the system’s own microphone dot.

Families carry urgency: active, waiting, blocked and quiet. Each surface’s own looks are variants inside them, and the line always carries the exact phase, so no surface shows a phase by colour or motion alone. The gateway’s own states map too: idle is quiet, restarting active and offline blocked.

No producer sends listening, retrying or waiting_model yet; they are in the vocabulary so every surface already has their looks.

work_phase is one frame type for every kind of work. For a chat its payload is:

FieldMeaning
workchat:<session>. A work reference is <kind>:<id>, with the kinds chat, loop, workflow, subagent, trigger and webhook; workref.parse refuses any other, and reads the names a trigger’s fire writes (tests/rails/test_every_work_id_has_a_known_writer.py)
sessionthe chat key, so an app’s socket hears only its own conversations’ phases (dashboard/ws_state.py::frame_subject)
kindchat
phase, linethe phase and its line, redacted and capped at 160 characters
sincewhen the phase or its line last changed
turn{message_id, started_at} of the running turn (the row that started it), null when nothing runs
last_step_atthe turn’s latest runtime event: a streamed chunk, a tool starting or ending, a decision raised or answered
stoppinga stop was asked and the turn has not ended; never set in a frame with no turn
steerablethe running turn takes a steer
last_outcomehow the latest settled turn ended: complete, stopped, error or interrupted (chat_runner.terminal_outcome_for_turn)
queued_messageshow many messages wait behind the turn
seqthe stream stamp (DashboardState.next_stream_seq), so a page applies a frame only when it is newer than its snapshot
retry, queueset only in retrying and waiting_model (below)
waiting, helpers_waitingwhile a turn runs, the waiting list’s ids (approval:<id>, question:<id>) of the asks it raised itself, and of the approvals its helpers raised, oldest first
waitset only in approval and input: the typed wait on the newest ask (below)

Times are UTC instants. A frame is sent when the phase, its line or one of the other fields changes, never per streamed chunk.

For a helper, a loop and a workflow run the payload is the work’s own part of it:

FieldMeaning
worksubagent:<id>, loop:<id> or workflow:<run>
kindsubagent, loop or workflow
sessionthe chat the work is for: the chat a helper works for, its own or the one whose batch it is a task of (work_phases.chat_of); "" for work no chat started: a loop, a run, and a helper started by anything else (a workflow step no chat’s batch is, an app’s own run, another helper, a loop’s worker, a schedule), whatever key its parent runs under
phase, line, sinceas a chat’s
seqthe stream stamp, as a chat’s

Who hears it. A frame that names a chat in session reaches an app’s socket only when the app started that chat, as every chat frame does. A frame about work no chat started reaches no app’s socket, only the owner’s (dashboard/ws_state.py::WORK_FRAMES). That is the stricter of the two reaches such work could have: an app the permission middleware lets read the loops (GET /api/loops) still hears none of their phases, until a list of the work that runs says which apps may hear of it. A page that shows a chat reads a frame as that chat’s run state only when it is the chat’s own (workPhase.isAChatsPhase): a helper’s names the chat it works for, but its phase is its own.

Every kind of work says its phases or is listed with why it says none of its own (work_phase.PHASE_PRODUCERS, NO_PHASE_OF_ITS_OWN; tests/test_every_kind_of_work_says_its_phase.py):

KindSays its phases from
chatits turn (chat_phase)
subagentthe subagent manager’s events and the approval registry (work_phases)
loopits status, and its worker’s turn while it runs (work_phases)
workflowits run’s events (work_phases)
triggernone of its own: a fire is over once it has started its work, a helper or a run, which says its own
webhooknone yet: its turn runs outside the chat runner; the running list holds it while it runs, and nothing says its steps

run_chat runs inside one wrapper, _says_its_phases: it begins the turn’s phase before the turn awaits anything and ends it on every way out, an exception and a cancellation included. Nothing runs the turn engine around it (tests/rails/test_a_chat_turns_body_runs_only_inside_run_chat.py).

  • queued as soon as the turn is accepted, before its context is put together, so a first message on a new chat shows at once.
  • thinking when the model’s stream starts, or planning in the chat’s plan mode.
  • On each tool call, by what the call is (work_phase.classify_call): an agent CLI declares a kind per call, so a search is searching under its own label, a think is planning, and any other kind is a tool labelled as its card is. PersonalClaw’s own runtime declares none, so its search tools are known by name and say where they look (“Searching your knowledge”, “your memory”, “the files”, “your tools”, “the web”); any other call is a tool.
  • streaming once, on the first word of the answer after any other phase, and thinking again after a tool’s result.
  • approval while the approval registry holds a request for the chat, and input while one of the owner’s questions for it is open. Both come from the registries, so native and agent-CLI turns are covered in one place.
  • delegating while helpers the chat started are running, with their count; back to thinking when the last one ends. A helper that outlives its turn holds nothing.

Endings. Every way a turn ends sends one last frame with no turn in it:

How the turn endedPhaseLine
complete (an answer, or a command answered by the chat itself)doneDone in 12 seconds
stopped (their Stop, a move, a stop before its prompt)doneStopped
declined (their Deny, and the agent ends the turn)donethe decline’s own sentence
error (a failure, a turn past its time limit)errorStopped: the turn’s own error
interrupted (a restart or a shutdown cut it short)errorStopped: The gateway restarted before this reply finished. …

A retry of the same turn (its connection was lost before any step) is not an ending: the turn goes on in its retry. tests/test_every_way_a_turn_ends_sends_the_final_phase.py walks every exit, anchored on the outcomes terminal_outcome_for_turn can give.

How a helper, a loop and a workflow run say their phases

Section titled “How a helper, a loop and a workflow run say their phases”

A frame goes out when the phase or its line changes, never per chunk. A wait on the owner is said over the step it interrupts, which is said again when the wait ends. The last frame says how the work ended, and nothing is kept of it after.

A helper says queued while it waits for a slot, thinking once it starts, each call’s phase by the chat’s own rule (work_phase.classify_call: a search says where it looks, any other call is a tool under its own label), streaming once on its first words after another phase, and approval while its start or one of its calls waits on the owner’s OK. Its ending: a stop is done (“Stopped”), their Deny of its start is done in the decline’s own words, a failure is error with its error, and a finish is done with how long it took.

A loop says the phase of its status, and while it runs, what its worker’s turn does: the worker is a chat (loop-<id>), which says its own phases, and the loop says them too, back to running once the worker’s turn ends. A loop that is not running is not doing what its worker’s turn still says. Incident mode holds a running loop without writing its status, so the loop says it is held when the switch moves (the gateway’s watch of it) as when its status is written, the worker’s turn ending under the hold included, and runs again once the switch is off.

StatusPhaseLine
intakethinkingAnalyzing
planningplanningPlanning
reviewapprovalNeeds your OK: its plan
readyqueuedWaiting to start
runningthinkingRunning
pausedidlePaused
stagnant, blockedinputStalled, Blocked
needs_inputinputNeeds your answer
completedoneDone
failederrorStopped: its error
stoppeddoneStopped
held (running, while incident mode holds it)queuedHeld until incident mode is off
ended early (complete at a ceiling, not its goal)errorEnded early

A workflow run says the phase of its status, a tool for each step it starts (named as its author named the step), and while it waits at a gate, the gate’s ask: a yes or no is approval, any other answer input, and an event gate, which waits for something to happen rather than for them, queued. The gate’s ask outlasts the run’s own needs-input status until the gate is answered or the run leaves it, and a step started while it waits does not say over it. An escalation asks nothing of them, and is no gate. Incident mode holds a running run without changing its status: the run’s publisher says it is held, and that it carries on (workflows/incident_hold.py).

StatusPhaseLine
draftqueuedWaiting to start
runningthinkingRunning
pausedidlePaused
needs_inputinput (or the gate’s ask)Needs your answer
completedoneDone
failed, escalatederrorStopped: its error
cancelleddoneStopped
declineddonethe decline’s own sentence
held (running, while incident mode holds it)queuedHeld until incident mode is off

While a turn runs, the gateway sends its chat’s work_phase again every 15 s, with the phase unchanged and last_step_at current, as a frame that carries data. A turn whose model is silent still says it is running. It is one task per running turn (named work_phase:<chat>), cancelled where the turn’s last frame is sent. The turn’s status row says “No new activity for 1m” once last_step_at (the turn’s start, while it has taken no step) is a minute old, in a working phase that does not say what it waits on itself (retrying, waiting_model), and drops it at the next step (web/src/ui/TurnStatusRow.tsx).

A retry and a wait on a busy local model are the turn’s phase, said from the event that measured each and never from a timer:

  • retrying, with retry: {attempt, of, next_at, reason}: the native loop’s retry of a failed inference (EVENT_RETRYING before its backoff, with the provider’s failure in humanize_provider_error’s sentence, and again as the retry’s call is made), its move to the next model of the chain (the line is “Trying ”, and the next model’s answer, EVENT_MODEL_SUBSTITUTION, ends it), and an agent CLI sent again after its connection was lost before any step (until the resent turn starts). Live work, coral: a retry is not a failure until it fails.
  • waiting_model, with queue: {model, behind}: the turn’s call waits behind other calls on a local model (guardrails.local_queue, whose waits count the calls ahead). The queue says when a wait starts or ends (handlers/model_waits.py), and the chat goes back to thinking when the model takes its call.

Each field is set only in its phase, null otherwise.

An ask that names the chat, raised while its turn runs, is its phase: the newest approval (approval, “Needs your OK: ”), else the newest question (input, “Asks: ”). The payload names each ask by the waiting list’s id (personalclaw.waiting): waiting holds the turn’s own approvals and questions, and helpers_waiting the approvals of the helpers it started (an approval’s id names its helper, subagent.approval_subagent_id). wait is the newest ask’s typed record (personalclaw/work_wait.py, Wait): reason (owner_answer for an approval, input for a question), resume_condition {kind: "answered", ref: <its waiting list id>}, deadline_at (the approval window after it was asked, null for none) and evidence_source (approval_registry, question_registry). Each reason is known from its own registries (work_wait.REASONS), and the constructor refuses any other source, and model_text by name: a model’s words never make a wait (tests/test_a_wait_is_typed.py). Once nothing runs, the chat waits on nothing.

Listening is the shell’s system state, with the sources that hold the microphone, not a phase of one chat: a dictation is not yet anyone’s message. A window reports each capture source it holds (the composer’s dictation, hands-free, the Knowledge recorder) through web/src/lib/pushToTalk.ts’s useCaptureReport; the shell keeps them per window and source, clears a window’s when it closes or its renderer is gone, and tells the tray, every window (pclaw-desktop:listening) and the gateway (desktop/pushToTalk.js, listeningReport). The gateway keeps it (POST /api/listening, GET /api/listening, both the owner’s) and sends a listening frame {on, sources, since} when it changed, which reaches the owner’s sockets and no app’s (ws_state.OWNER_FRAMES). A plain browser tab has no shell and reports nothing.

GET /api/chat/sessions rows, GET /api/chat/sessions/{session} and the chats of GET /api/projects/{id}/linked carry the chat’s run_state (_ChatSession.run_state): the last work_phase payload sent for it, served with phase: "idle", an empty line, no turn and no waits once nothing runs. A chat that never ran here is served the idle payload. A page that opens or reconnects mid-turn reads the same state the frames say, and a chat’s running, stopping and steerable state, whether it waits on the owner’s OK, and how its last turn ended, are read there and nowhere else: the routes’ own flags for them are gone (web/src/lib/noSurfaceDerivesRunning.test.ts). The chat page’s stall reconciler, which recovers an approval card whose frame it lost, reads the approval phase.

  • The chat’s own turn view reads its turn’s frames directly, as it reads the turn’s other frames, applying one only when its seq is newer than the snapshot’s. The head of the running reply shows them: the agent orb in the phase’s look and the phase’s line beside it, settling on the ending the last frame says (agent-orb.md). So do the loop and code cockpits for their worker’s turn: their list of its steps gains a phase’s line once per change, but none for a phase the list shows its own way (a step’s, which its row says, and in the code cockpit the writing, whose words it shows), nor for the thinking said after each step’s result (workPhase.phaseFeedLine).
  • Every ambient surface treats a frame as a doorbell, never as a payload. Mission Control’s Working lane and the agent worlds read the running list below, rung by its running_changed frame (agent-activity-feed.md); Home reads the phase from the chat list, rung by work_phase.

A surface paints what an agent is doing in its phase’s tone and in no tone of its own, reading it from web/src/lib/workPhase.ts (phaseColor, phaseToken, phaseText, phaseAccent):

  • A loop’s and a workflow run’s status are painted as the phase the gateway says they are (LOOP_STATUS_PHASES and RUN_STATUS_PHASES, the web’s copies of work_phase.py’s, which tests/test_work_phase_vocabulary.py pins equal): their plan waiting for launch is warn, a run or a loop waiting on their answer info, queued and held work coral, a stop and a cancel ok, a failure and an early end danger.
  • An agent world’s states are painted as the phase each stands for (WORLD_PHASE): working is coral, and live work held up is queued’s coral, told apart by its ring, its pace and its word.
  • A needs-you row in the Inbox, the bell and the Projects board is painted by what it waits on: their yes (approval, warn) or their answer (input, info).
  • The microphone chip is listening’s warn, the system’s own microphone dot.

web/src/lib/everySurfacePaintsAPhaseInItsTone.test.ts holds each of these to its phase’s tone, with a planted off-tone row as its control.

GET /api/running lists every piece of live work once (src/personalclaw/running_now.py): a chat with a turn running, a helper that has not ended (a queued one included), a loop or a workflow run that has started and not ended, a trigger’s fire whose work has no row of its own, and a webhook’s turn. Each row is the work’s last frame with the row’s own fields beside it (name, agent, started_at, route, blocked, waiting, project_id, loop_kind: the project the work is in and a loop’s kind, by the rule both lists share, work_project), so a chat’s row is its run_state, but for waiting: the row’s own names each ask waiting on the owner for the work by its registry id, its helpers’ included, where the run state’s names the turn’s own asks by their waiting list ids (and helpers_waiting its helpers’). Work no producer has said anything of yet reads its phase from its status, by the tables above. A loop’s workers and planner are their loop, and a loop backed by a run is one row, a loop, named by its run. blocked is true in queued, waiting_model and retrying; waiting names the approvals and the owner’s questions that wait on them for the work. Rows are ordered by when the work began (a chat’s turn, a helper, a loop’s or a run’s creation, a fire, a webhook’s turn), so a row never moves as its phase does. finished is the last 20 endings, each kept 10 minutes, newest first.

GET /api/running/count answers {live, blocked, waiting, finished} from the same reading, and neither read opens a loop’s findings. An app reads a row only when its socket would hear that work’s phase frame (ws_state.WORK_FRAMES), an agent only its own chat’s work, and the owner everything; the count is cut the same way. Neither route has a ROUTE_AUTHZ row: an app reaches them only when its manifest declares /api/running. An app that reads the list names the running-list core feature in requiresCoreFeatures, so a PersonalClaw built before the list refuses to install it rather than answering it nothing. A core before 0.3.9 serves no project_id or loop_kind, so an app reads a missing one as "".

The list says it moved in one running_changed frame per 150 ms window (running_now.changed): a doorbell naming the work that moved, {"changed": [{"work", "session"}, ...]}, never a payload to render, so a reader reads the list again. It rings when a row is added or removed or its phase or line changes (every work_phase frame but a liveness re-send, and a loop worker’s, whose loop’s frame rings), when an approval or an agent’s question a row waits on is asked or answered, when a webhook’s turn starts or ends, and when a trigger’s claim is written or released. A streamed chunk, a liveness re-send of an unchanged phase and a command’s output ring nothing. An app’s socket hears a ring cut to the work whose phase frame it may hear (ws_state.RUNNING_LIST_FRAMES), and none when that is nothing.