List the roster
const url = 'http://127.0.0.1:7799/api/roster';const options = {method: 'GET', headers: {cookie: 'cotal_web_session=<cotal_web_session>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url http://127.0.0.1:7799/api/roster \ --cookie cotal_web_session=<cotal_web_session>Return the dashboard observer’s current presence roster. Rows can include offline peers; freshness is reported separately by the presence-view SSE event.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”The current snapshot or history page.
Presence plus an optional progress signal. Working rows currently report progress.kind as unknown because the dashboard has no session-store observer.
object
Epoch ms of the last work progress the harness reported (a turn event such as a token or a tool call). ts is only the heartbeat: a seat whose turn stopped advancing keeps heartbeating while this stays old. Missing means the connector reports none.
Freeform “what I’m doing right now”.
Epoch ms when the current activity was set. A status change does not move it, so an activity left behind while hooks flip the status every turn still reads as old.
This instance’s current global attention mode. Advisory, within-space observability — a peer can see “they’re in focus” and choose to DM. Published from the connector’s authoritative state (presence is a mirror, never the source of truth for delivery). open/absent ⇒ receives all.
A2A-inspired identity record for an endpoint or agent.
object
The agent-instance actor token under {@link owner } (server-derived from the spawn ledger in user mode; the connection id in the dev default). The other half of {@link id } .
A2A-style one-line summary of what this agent does (discovery / observability).
Unique, stable for the lifetime of this connection. The owner+actor principal dot-form <owner>.<actor> (= principalKey().key) under the owner+actor grammar — the wire identity every msg.from.id carries and every sender guard compares against. Peers address each other by this.
‘agent’ (participates in coordination) or a plain ‘endpoint’ (logger, dashboard…).
Free-form advisory display metadata. Reserved flat string keys are connector, model, provider (the effective provider the connector reported), host, cwd, repo, branch, head, sessionKind, and sessionId.
object
Human-readable display name.
The human/account owner token this agent acts under (opaque, per-space; "local" in the no-login dev default). One of the two halves of {@link id } ; travels in presence so peers resolve name→principal.
Wire-contract version this participant speaks (the SPEC.md version, "0.2" today). A change signal, not negotiation: v0 has none, but a peer can detect a mismatch instead of silently misreading a future envelope. Omitted ⇒ assume the v0.x line.
Cotal addition: the role this participant plays (planner, reviewer, …).
object
Cotal: free-form “what it can do” tags (A2A skill-tags, flattened) — discovery only.
Per-channel attention overrides this instance currently has (runtime, reset on restart). Keys are concrete channel names. Advisory: lets a peer see “locally muted #deploys → DM to reach me”. NOT access control — the broker still authorizes and delivers; this is a receive-side presentation.
object
Per-channel attention override (more specific than the global {@link AttentionMode } ).
quiet— still delivered + buffered, but never wakes; an@-mention still wakes (per-channeldnd).muted— channel messages dropped on receive, incl.@-mentions (“don’t receive this channel”).
Structured condition reported by the harness. Missing means nothing was reported.
object
Closed, provider-neutral categories a connector may relay from its harness’s native signal.
Free-text detail reported by the harness.
Epoch ms when this condition began.
The harness’s native value, preserved verbatim.
Opaque reference whose meaning belongs to the provider that issued it.
This incarnation’s lifecycle UID (SPEC §6/§13.1: MUST in auth mode from v0.4) — the value the alias currently maps to, published so peers/observers can attribute the alias’s live occupant. Advisory observability, never authority (authority is the ledger/broker grants).
The process that publishes this record, with its observed start. Status, activity, heartbeats and reconnects inside the process leave it unchanged; a new process publishes a new one. An offline record keeps it to name the process that went away, so it dates a running duration only while the record is live. Missing means the publisher reports none: unknown, not zero.
object
Opaque CSPRNG id minted once per OS process and lifecycleUid scope, never reused. A new process or lifecycle scope gets a new id; reconnect within that scope keeps it.
Where a {@link PresenceRuntime } start was observed. Closed: a consumer that meets any other value treats the observation as unsupported rather than guessing what it dates.
endpoint-process: the OS process that holds this presence’s mesh connection, observed by that process itself.
Epoch ms when the process started, read in-process from its own clock origin (performance.timeOrigin). Never a launch request, registration, heartbeat, status or activity time. Every lifecycle in this process shares this start, including one registered later. It does not date a separate parent, model harness or lifecycle.
Lifecycle status of a participant.
idle: connected, no active taskwaiting: blocked — awaiting input, approval, or a peerworking: actively executing a task / in a turnoffline: disconnected or heartbeat lapsed (derived by observers, not self-set while live)
Epoch ms when the instance entered its current status and activity. A change to either moves it; a heartbeat or a repeated report does not, so an activity that outlived what it described reads as old even while ts stays fresh. Never carried by an offline record.
Epoch ms of the last heartbeat.
object
Example
[ { "attention": "open", "card": { "kind": "agent" }, "channelModes": { "additionalProperty": "quiet" }, "condition": { "code": "rate_limit" }, "runtime": { "source": "endpoint-process" }, "status": "idle", "progress": { "kind": "unknown" } }]A valid one-use k query token is exchanged for a dashboard session. The response redirects to the same path without its query. A valid existing cookie takes precedence over k.
Headers
Section titled “Headers”The requested path without the query string.
Cotal_web_session=
No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.
object
Example
{ "error": "unauthenticated"}Origin is checked before session authentication. An origin outside this listener’s allowed origins is refused.
object
Example
{ "error": "cross-origin"}These read routes accept no request body. An announced body is refused before it is read; the connection is closed.
object
Examplegenerated
{ "error": "example"}The request failed. The body names the failure; a failed read does not terminate the dashboard.
object
Examplegenerated
{ "error": "example"}