live status contract
The live status contract is the stable, compact snapshot that an external Codex Desktop monitor polls to render kasmos orchestration state. The current schema_version is 2.
access
Codex Desktop reads the live_status MCP tool from http://127.0.0.1:7434/mcp. The tool accepts a project and an optional cap.
The same assembled contract is available from the daemon control API over its Unix socket:
GET /v1/repos/{project}/live-status
kas monitor status --json emits this contract for CLI consumers.
The daemon heartbeat is best effort. If the daemon is unavailable, the MCP tool still returns task-store data with daemon_running set to false. Daemon-derived uptime and repo_count may be absent or zero, and stale_instance attention is unavailable because instance health requires the daemon.
Poll every 1–5 seconds. Consumers should reuse the latest snapshot between polls rather than treating this endpoint as an event stream. Arrays are capped and the payload contains summary state rather than logs, transcripts, or task bodies, preserving the compactness guarantee.
top-level fields
| field | type | meaning |
|---|---|---|
schema_version | integer | Wire-schema version. Currently 2. |
generated_at | timestamp | Snapshot assembly time, normalized to UTC and encoded as RFC3339Nano JSON. |
project | string | Kasmos project whose state was assembled. |
daemon_running | boolean | Whether a daemon heartbeat was available when the snapshot was assembled. |
uptime | string, optional | Daemon uptime. Omitted when empty. |
repo_count | integer, optional | Repositories known to the daemon. Omitted when zero. |
lifecycle | LifecycleCounts | Counts of tasks in active lifecycle buckets. |
active_agents | ActiveAgent[] | Capped list of current agent instances. |
attention | AttentionItem[] | Capped list of durable conditions that may need action. |
truncated | Truncation | Counts of items omitted from the capped arrays. |
projects | string[], optional | Available project names, included only when requested. |
tasks | TaskSummary[], optional | Bounded task summaries, included only when requested. |
events | EventItem[], optional | Bounded recent orchestration events, included only when requested. |
focus | TaskFocus, optional | Wave and readiness detail for a requested task. |
lifecycle counts
LifecycleCounts contains integer fields planning, ready, implementing, reviewing, verifying, and total. total is the sum of those five active buckets. Done, cancelled, and other statuses are not included.
active agents
Each ActiveAgent contains:
| field | type | meaning |
|---|---|---|
task | string | Task associated with the instance. |
role | string | Agent role. |
wave | integer, optional | Current wave number. Omitted when zero. |
stage | string, optional | Derived stage: loading, ready, or running. Omitted when no stage applies. |
ready | boolean, optional | Whether the instance is ready. Omitted when false. |
active | boolean, optional | Whether the instance is active. Omitted when false. |
worktree | string, optional | Worktree basename. This is never an absolute path. |
branch | string, optional | Git branch associated with the instance. |
task_number | integer, optional | Wave task number. |
last_activity | timestamp, optional | Most recent observed activity in UTC. |
paused | boolean, optional | Whether the instance is explicitly paused. |
The basename-only form of active_agents[].worktree is a contract guarantee, not an implementation detail. Model-visible consumers must never receive the daemon's absolute local worktree path.
The daemon control endpoint, CLI JSON output, MCP tool, and widget all populate the same extended agent fields, including worktree, branch, task number, last activity, and paused state.
monitor sections
Schema v2 adds four opt-in sections. projects lists available projects. tasks contains filename, lifecycle and phase, topic, branch, wave and subtask progress, review and pull-request state, and blocker status. events contains timestamped, bounded event summaries with optional task, agent, wave, task-number, and level metadata. focus contains the selected task's filename and goal, its waves and wave tasks, and readiness state.
These sections are omitted unless requested, preserving the compact default snapshot. All v1 fields and their meanings are unchanged, so v1 consumers continue to work when they ignore unknown fields.
attention
Each AttentionItem contains task, kind, and an optional detail string. detail is omitted when empty.
kind is one of:
| value | durable source |
|---|---|
needs_decision | The task's stored execution phase is wave_waiting, meaning orchestration is waiting at a persisted decision boundary. |
review_feedback | The task is back in implementing with stored review feedback, meaning a fixer must address it. Historical feedback is not surfaced during re-review, verification, or terminal states. |
stale_instance | The daemon reports a non-empty instance health reason; that reason is returned in detail. This kind is unavailable without the daemon. |
stuck is intentionally not part of v1. Stuck detection belongs to the planned SSE follow-up rather than this polling snapshot.
truncation and cap
The default cap is 20 items per active_agents and attention array. Callers may override it with cap; non-positive values select the default, and values above the hard maximum of 100 are reduced to 100. Active agents are sorted by task, role, and wave before truncation, so repeated snapshots select the same bounded subset when state is unchanged.
Truncation contains optional integer fields active_agents, attention, tasks, and events. Each value is the number of items omitted from its corresponding array, not the total number available. A field is omitted when no items were truncated.
versioning policy
Consumers must inspect schema_version before interpreting the payload.
- Adding optional fields is backward compatible and does not bump
schema_version. - Renaming or removing a field, or changing a field's type or meaning incompatibly, requires a
schema_versionbump. - Consumers should ignore unknown fields so additive changes remain compatible.
Schema v2 is additive and leaves every v1 field unchanged. It was bumped despite that compatibility so monitor clients can feature-detect the opt-in projects, tasks, events, and focus sections without probing for individual fields.