/** * CLI-side API Response Type Definitions * Issue #518: [DR1-06] All types include Mirrors comments for server-side traceability * * These types mirror server-side response shapes. Where a server module has no * imports of its own (e.g. `lib/session/prompt-view`), it is imported here by * relative path instead of restated, so the CLI build compiles it and there is * no second definition to drift (see `promptView` below). */ import type { PromptView } from '../../lib/session/prompt-view'; import type { AutoYesSuppressionReason } from '../../lib/polling/auto-yes-suppression-reason'; import type { StatusEvidence } from '../../lib/session/status-evidence-type'; import type { PromptObservation } from '../../lib/prompt-observation/types'; export interface WorktreeListResponse { worktrees: WorktreeItem[]; repositories: unknown[]; /** * The namespace the server names its tmux sessions with, or null when it * uses the legacy form (Issue #2867). Absent from servers older than #2867. */ tmuxSessionNamespace?: string | null; } export interface WorktreeItem { /** * Primary worktree identifier: a `-` slug (e.g. `anvil-develop`), * sanitized/lowercased. This is the prefix users pass to `ls --id` (Issue #1005) * and the id accepted by send/capture/wait/respond/instances. */ id: string; name: string; /** * Mirrors: src/types/models.ts Worktree.branch (Issue #1003). * Git branch captured at sync time — a distinct concept from * gitStatus.currentBranch (live) and initialBranch (session start); it lags a * checkout until the next sync. Undefined for rows synced before Issue #1003 * or written by non-sync paths; consumers fall back to {@link name}. */ branch?: string; cliToolId?: string; isSessionRunning?: boolean; isWaitingForResponse?: boolean; isProcessing?: boolean; sessionStatusByCli?: Partial>; agentInstances?: AgentInstance[]; } export interface RepositorySyncResponse { success: boolean; message: string; worktreeCount: number; repositoryCount: number; repositories: string[]; deletedCount: number; /** Sanitized, generic warnings only (SEC-MF-001); details stay in server logs. */ cleanupWarnings: string[]; } export interface AgentInstance { id: string; cliTool: string; alias: string; order: number; /** * The tmux session name the server uses for this instance — namespaced, or * an adopted legacy name (Issue #2867). Only on `GET /api/worktrees/[id]`, * and absent from servers older than #2867. */ sessionName?: string; } /** * Mirrors: src/app/api/worktrees/[id]/opencode/session/route.ts GET response * (Issue #2038). * * opencode-only. Every field is nullable because the interesting case is a * **stopped** instance: the session id there is what the next launch will pass * to `opencode -s `, and nothing is running to describe it. */ export interface OpencodeInstanceSession { instanceId: string; /** opencode's `Session.id`, or null when nothing has been recorded yet. */ sessionId: string | null; /** opencode's `Session.title`, or null. Display only. */ title: string | null; /** The directory opencode reported the session belongs to, or null. */ worktreePath: string | null; /** Epoch ms the memory was written, or null. */ updatedAt: number | null; /** Whether an opencode server is currently attached to this instance. */ live: boolean; } /** Mirrors: the same route's GET body (Issue #2038). */ export interface OpencodeSessionsResponse { instances: OpencodeInstanceSession[]; } export interface WorktreeDetailResponse extends WorktreeItem { agentInstances: AgentInstance[]; /** * Issue #4132: names this reading of the roster, for a write that replaces it. Absent * from an older server. Pinned to the route by tests/integration/cli-response-types-4159.test.ts. */ rosterRevision?: string; } /** * Mirrors: src/lib/polling/auto-yes-resolver.ts AutoYesSuppressionReason * (Issue #1843) — every value `autoYes.lastSuppression.reason` can carry. * * Re-exported, not copied: the union lives in the dependency-free module * `src/lib/polling/auto-yes-suppression-reason.ts`, which the CLI imports by a * relative path (tsconfig.cli.json sets `"paths": {}`; the resolver that also * re-exports it imports `@/config/auto-yes-config`, so the CLI cannot reach it * through there). tests/unit/cli/config/cross-validation.test.ts keeps a * bidirectional assignability assertion between this export and the resolver's, * and `SUPPRESSION_CAUSE` in src/cli/commands/wait.ts is a `Record` over it, so * a reason added server-side does not compile until `wait` has its wording. * * The first four are verdicts of a contract's `autoYes` block. `policy-lookup-failed` * (Issue #3822) is the contract NOT read — the lookup failed — and withheld for * that, not for anything the contract says. `agent-launch-dialog` is NOT a * verdict either: Issue #1829 records a CLI-lifecycle dialog the poller deliberately * leaves to the tool's own launch sequence, through the same channel. Anything * that phrases a suppression for a human has to tell the two apart — see * SUPPRESSION_CAUSE in src/cli/commands/wait.ts. */ export type { AutoYesSuppressionReason }; /** * Mirrors: src/lib/session/current-output-types.ts CurrentOutputResponseBody — * what `GET /api/worktrees/[id]/current-output` answers. [DR2-03] Every * top-level field of that type is declared here. * * Only `isRunning`, `content` and `lineCount` are on every response. The rest * is optional, for one of two reasons: * * - **the session is not running.** There is no frame, so nothing read off one * is sent: `autoYes`, `isPromptWaiting`, `promptData`, `thinking`, * `fullOutput`, * `realtimeSnippet`, `lastCapturedLine`, `isSelectionListActive`, * `lastServerResponseTimestamp` and `serverPollerActive` are absent keys * there, not `false` / `null` (Issue #3300). A reader says what absence means * (`?? false`, `?? null`) rather than assuming the key; * - **the daemon is older than the field.** The CLI is routinely newer than the * server it dials (`npm i -g` does not restart a running daemon), so a field * this build's server always sends is still optional here. * * A copy rather than an import: the server type's import graph is over a * hundred modules, dozens of them importing through `@/`, which * `tsconfig.cli.json` (`"paths": {}`) cannot resolve. The copy is held to the * original — field names and optionality — by * tests/unit/cli/types/current-output-mirror-3300.test.ts. */ export interface CurrentOutputResponse { isRunning: boolean; isPromptWaiting?: boolean; content: string; fullOutput?: string; realtimeSnippet?: string; lineCount: number; lastCapturedLine?: number; promptData?: PromptData | null; /** * Whether `/prompt-response` would answer `promptData` right now (Issue #2870). * Present only for a screen-parsed prompt; absent with no prompt and for the * structured (hook / degraded) forms. */ promptAnswerable?: boolean; /** * How `promptData` is shown and answered (Issue #3184). Absent from a server * older than #3184; read it through `readPromptView`, which derives the same * value from `promptData` then. Imported (by relative path) rather than * restated: `lib/session/prompt-view` has no imports, so the CLI build can * compile it, and a copy here would be a second definition to drift. */ promptView?: PromptView | null; /** * Auto-Yes as this session's poll reads it. **Absent when the session is not * running** — which is not "disabled": Auto-Yes is armed per worktree x * instance and outlives the session it answers for, so a stopped instance can * be armed. `GET /api/worktrees/[id]/auto-yes` answers for those too, and is * what `commandmate instances` reads (Issue #3300). */ autoYes?: { enabled: boolean; expiresAt: number | null; /** * Mirrors: src/config/auto-yes-config.ts AutoYesStopReason. Typed as a * string because a newer server may add a reason. Issue #3730: * `server-restart` — Auto-Yes is off because the previous server process * shut down while this grant was live; the grant is not restored, and the * reason stays until the grant's own deadline or the next enable / disable. */ stopReason?: string; lastSuppression?: { /** * Normally an {@link AutoYesSuppressionReason}, but deliberately typed as * the wire's `string`: this is a server response, and a server newer than * the CLI can name a reason this build has never heard of. Consumers * narrow it themselves and must stay truthful about the miss (Issue #1843). */ reason: string; mode: string | null; promptType: string; pattern?: string; at: number; /** * The waiting episode the record was written for (Issue #3798). Absent * when no wait was open, or from a server older than the field. */ episodeId?: string; } | null; /** * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.autoYes.waitingEpisodeId (Issue #3798). The waiting * episode open when the payload was built, or null. `lastSuppression` is * this wait's only when its `episodeId` is this — and not when * `lastSuppressionAnswered` says Auto-Yes answered this wait after it; * absent (an older server), the record's age decides as before. */ waitingEpisodeId?: string | null; /** * Mirrors: src/lib/auto-yes-state.ts AutoYesState.stopMatchedText * (Issue #1694). Short excerpt of what `--stop-pattern` matched, with one * line of context, present only while `stopReason` is * `stop_pattern_matched`. Bounded to STOP_MATCH_EXCERPT_MAX_BYTES UTF-8 * bytes; a trailing `…[truncated]` marker means it was cut. */ stopMatchedText?: string; /** * Mirrors: src/lib/polling/auto-yes-enter-fallback.ts AutoYesEnterFallbackPublished * (Issue #3397). The last Enter Auto-Yes sent to a choice screen * CommandMate could not read, or null when it never sent one. Optional for * a server older than #3397. Field names, optionality and wire types are * held to the server's by tests/unit/cli/types/enter-fallback-mirror-3397.test.ts. */ lastEnterFallback?: { /** * `sent`, or `no-effect` when the same screen was still up after the * Enter and Auto-Yes left it to a human. The wire's `string`, as for * `lastSuppression.reason`: a newer server may name an outcome this CLI * has not heard of. */ outcome: string; promptType: string; /** `unsupported_dialog_layout` or `prompt_no_longer_active`. */ refusalReason: string; /** Epoch ms the Enter was sent. */ sentAt: number; /** Epoch ms of the last change (`sentAt`, or when `no-effect` was found). */ at: number; /** Whether the record is about the prompt in this same response. */ currentPrompt: boolean; } | null; /** * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.autoYes.lastSuppressionAnswered (Issue #3798). True * when Auto-Yes answered the wait `waitingEpisodeId` names after * `lastSuppression` was written: the record is history, not this wait's * reason, as the push gate reads it. Absent (an older server) reads as false. */ lastSuppressionAnswered?: boolean; }; thinking?: boolean; cliToolId?: string; /** * The tmux session name this instance actually runs (or would run) under * (Issue #2886). * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.sessionName — `getSessionName(worktreeId, instanceId)` * verbatim, namespace (#2866) and legacy-adoption included, so a consumer * never has to reconstruct `mcbd-${cliToolId}-${worktreeId}` itself. * * Optional because a server older than #2886 sends no such key; a reader * falls back to the legacy construction in that case. */ sessionName?: string; isSelectionListActive?: boolean; /** Issue #1017: Codex pager/edit-previous mode (subset of isSelectionListActive). */ isPagerActive?: boolean; /** * Issue #2369: a dismiss-only overlay is on the pane — its footer offers * `Esc to close` and nothing else (Command Code's `/usage`). * * Disjoint from {@link isSelectionListActive}, unlike {@link isPagerActive} * which is a subset of it: this screen has no highlight to move, which is the * whole reason it is published separately rather than folded into the flag * the arrow pad is drawn from. * * Optional because a daemon older than #2369 sends nothing, and `undefined` * there means "this server predates the field" rather than "no such panel". */ isDismissablePanelActive?: boolean; /** * The frame is interactive but the detection layer could not classify it * (Issue #1497). The server has published this since #1120; until Issue #1708 * the CLI never read it, so a dialog the scraper failed to parse was treated * as "nothing is happening" and `wait` polled it until --timeout. * * Momentary by nature — a repaint mid-capture can raise it for a single poll — * so it is only a stop reason after it has persisted; see * UNCLASSIFIED_DWELL_MS in wait.ts. * * Produced by `isUnclassifiedFrame` in `src/lib/session/status-evidence.ts`, * and NOT the negation of {@link statusEvidence} (Issue #2011) — read the two * questions, and the frames on which their answers cross, over there. */ isUnclassifiedActive?: boolean; /** * Epoch ms the agent's launch began, while it is still starting, else null * (Issue #3179). Absent on a server that predates the field. * * While it is a number the session is published as `running` / `starting` * with every dialog flag false, and `wait` keeps polling — the launch is work * in progress, not a frame a human has to drive (exit 10) and not a session * that never started (exit 21) even when its pane does not exist yet. */ startingSince?: number | null; /** * Whether {@link sessionStatus} rests on something positive, or only on * nothing having matched (Issue #1926, design §4 D1 決定 2 / §7). * * `'positive'` — a completion marker, a thinking indicator, a parsed prompt, * a tool-specific idle-composer rule, or the agent's own `Stop` said so. * `'none'` — nothing on the frame could be read either way, so the status is * a fallback. * * ## NOT the same fact as {@link isUnclassifiedActive} (Issue #2011) * * This comment used to say the two carried one fact under two names, and the * server derived the flag from `evidence === 'none'` to match. Issue #1927 * had already broken that: it moved the evidence producer into the per-tool * detectors, and `'none'` widened from "nobody could read this frame" to "no * rule vouched for this verdict" — which an ordinary idle Claude composer * satisfies. Every idle Claude pane then raised the terminal escape hatch and * stopped `wait` completing. #2011 pulled them apart again. * * They ask different questions, and the answers cross in both directions: * * - an idle composer no tool-specific idle rule vouches for is `'none'` * and CLASSIFIED (`isUnclassifiedActive: false`) — `wait` completes on it; * - an unreadable pane whose agent reported `Stop` is `'positive'` and * UNCLASSIFIED (`isUnclassifiedActive: true`) — `wait` holds. * * This field asks "is there positive proof behind the verdict?", is produced * by the detector per tool, and widens as the §4 D1 rollout reaches each one. * {@link isUnclassifiedActive} asks "could ANY rule read this frame at all?", * is a statement about the reason vocabulary rather than about the strength of * the evidence, and is fixed: `isUnclassifiedFrame` in * `src/lib/session/status-evidence.ts` is `running` plus one of a closed set. * * Unclassified reasons: `no_recent_output`, `unknown_frame`, `default`. * Classified-but-unproven: `input_prompt`. * * A closed union, like {@link sessionStatus} and for the same reason: the * design fixes the domain at two members precisely so a newer server cannot * hand an older CLI a value it has never heard of. Adding a third would be a * breaking change, not an additive one. * * The two marker lines above and the union width are held to the server by * tests/unit/cli/types/status-evidence-contract-2015.test.ts; what it can and * cannot prove is written out there. * * Optional because a server older than #1926 sends no such key — which is not * the same as `'positive'`. Treat `undefined` as "this server does not say". */ statusEvidence?: 'positive' | 'none'; /** * The last status this server could positively confirm, or null * (Issue #1926, design §7 「直前の確定状態(証拠なしの間の表示)」). * * Equal to {@link sessionStatus} whenever `statusEvidence` is `'positive'`, * because the poll that answered just confirmed it. It says something the * other fields do not only when the evidence is `'none'`: this is what the * session last actually was, as opposed to what the fallback is calling it. * * Held in server memory, so `null` covers "nothing was ever confirmed", "the * confirmation aged out", "the server restarted" and "the session is not * running" without distinguishing them. Undefined means a server older than * #1926. */ lastKnownStatus?: 'idle' | 'ready' | 'running' | 'waiting' | null; /** Epoch ms of {@link lastKnownStatus}, null when that is null (Issue #1926). */ lastKnownStatusAt?: number | null; lastServerResponseTimestamp?: number | null; serverPollerActive?: boolean; /** * Mirrors: src/types/auto-yes-decision.ts AutoYesDecisionPublished * (Issue #3821). Auto-Yes's decision about `promptData`: `answering` (an * automatic answer is under way), `withheld` (left to a human, `reason` * says why — `server-poller-inactive` when no server poller runs for the * instance) or `none`. Wire strings, as for `lastSuppression.reason`. * Absent when the session is not running and from an older server. */ autoYesDecision?: { state: string; reason: string | null; observedAt: number; /** Which confirmation the decision is about (an opaque key; null with no prompt). */ confirmation?: string | null; }; /** * Issue #3863: how Auto-Yes answers questions on this instance while it is * on — `recommended` (with the recommended option, else the default) or * `careful` (left to a human). Beside `autoYes`, like `autoYesDecision`. * Absent while Auto-Yes is off, when the session is not running, and from a * server older than the field. Mirrors: src/types/auto-yes-answer-mode.ts * AutoYesAnswerMode, typed as the wire's `string` for a newer server. */ autoYesAnswerMode?: string; /** * Issue #520: session status from `detectSessionStatus()` — or, since Issue * #1723, from the agent's own lifecycle events when they are available and * the scraper is not reporting a prompt. `sessionStatusReason` says which. */ sessionStatus?: 'idle' | 'ready' | 'running' | 'waiting'; /** * Issue #520: reason string from `detectSessionStatus()`, or * `session_not_running`. * * Issue #1723 adds a second family, distinguishable by its `hook_` prefix * (`hook_stop`, `hook_prompt_submit`, …; see * `src/lib/session/status-mapping.ts` HOOK_STATUS_REASON). A `hook_` reason * means `sessionStatus` came from an event the agent reported rather than * from reading its terminal, so it is exact rather than inferred — the * distinction matters when triaging why `wait` did or did not stop. */ sessionStatusReason?: string; /** * Issue #1549: epoch ms of the last structured stop event, or null when the * agent has posted none. */ lastStopEventAt?: number | null; /** * Issue #1722: the last lifecycle event the agent's injected hooks reported. * Diagnostic — it tells an operator whether hooks are arriving and for which * instance. No CLI verdict reads it; that is Issue #1723. * * Mirrors: src/lib/session/current-output-types.ts StructuredEventsPayload */ structuredEvents?: { lastEventType: string | null; lastEventAt: number | null; lastEventDetail: string | null; /** * The id of the turn this instance is in, or of the last one it was in * (Issue #1926, made a real identity in #1930). * * Stable for the life of the turn: a `pre_tool_use` arriving mid-turn no * longer re-stamps it, and a session recreated in the same pane does not * inherit it. `wait` reads a change of id as "a new turn began". * * Absent from a server older than #1926, and null on one that has heard * nothing from this instance. */ turnId?: string | null; /** * Epoch ms the turn opened, or null (Issue #1926). * * The event that opens a turn is one of `user_prompt_submit` / * `pre_tool_use` / `post_tool_use` — the set `adoptTurnStart` mirrors as * {@link TURN_OPENING_EVENT_TYPES}. Null means the opening was never * observed: a `stop` arrived with no turn open, so the server publishes * null rather than guessing a time `closedAt - openedAt` would be rendered * from. */ openedAt?: number | null; /** Epoch ms the turn ended, or null while it is open (Issue #1926). */ closedAt?: number | null; /** * Why the turn ended, or null while none has (Issue #1926, filled in by * #1930). * * The six values a server produces today are `stop` (the agent's own * `Stop`), `session_end`, `stale`, `scraper_evidence`, `resync_idle` and * `generation`. A plain `string` on purpose: a newer server can name a * close reason this build has never heard of, and narrowing here would turn * a forward-compatible payload into a parse failure (Issue #1843). */ closedBy?: string | null; /** * The approvals this instance is blocked on, oldest first (Issue #1930). * * Empty on a session with no dialog open. The agent's own `tool_input` is * deliberately NOT here — see the server-side type; what is published is * what a reader can act on. * * Mirrors: src/lib/session/current-output-types.ts PendingDecisionPayload. */ pendingDecisions?: Array<{ /** The agent's own id for it, or null for a source that publishes none. */ id: string | null; at: number; /** `notification` (proved) / `permission-request` (predicted). String-typed per #1843. */ source: string; toolName: string | null; confirmedAt: number | null; scraperCorroborated: boolean; /** * Whether a verdict from the server can still reach the agent — the * source's `decisionTimeoutSeconds` applied to this record's age. * * True does **not** mean the dialog is gone. The pane is still blocked; * what has expired is the server's ability to answer it automatically. */ deliveryExpired: boolean; /** * Whether a human is being asked to approve or to choose (Issue #2040). * * `permission` / `question`. The two block a worker identically and are * answered completely differently — three fixed verdicts against the * agent's own published choices — so a reader deciding whether to answer * at all has to see this first. * * String-typed and optional for this file's two usual reasons: a newer * server may name a third kind, and a server from before #2040 sends no * such key. Absent means "this daemon predates the field", never * "unknown". */ kind?: string; /** * The choices a pending question offers, or null (Issue #2040). * * Null on every approval — an approval's three verdicts belong to the * SOURCE and are published as `promptData.decisionOptions` — and null on a * question whose payload is no longer held, because the numbers are the * payload's own order and quoting them from anything else would number a * list the agent never sent. * * These are the numbers `commandmate respond ` resolves * against on an agent that publishes decision ids. */ questionOptions?: Array<{ number: number; label: string; }> | null; }>; /** * What this instance has had dropped by the structured layer's own bounds, * and on whose authority (Issue #1930). * * The field that separates "my `stop` never arrived" from "my `stop` * arrived and something had already claimed its id" — the same symptom with * different fixes. * * Mirrors: src/lib/session/agent-event-state.ts AgentEventDropCounts. */ dedupDropped?: { dedupDropped: { identity: number; timeWindow: number; }; decisionEvicted: number; idsDiscarded: number; dialogTimedOut: number; decisionOverflow: number; }; /** * How long a dialog record is retained without being answered, in ms * (Issue #1930). * * Two values because a prediction and a proof are different statements: a * `PermissionRequest` nothing corroborated expires far sooner than a * `Notification` that proved a dialog exists. */ dialogPendingMaxMs?: { predicted: number; confirmed: number; }; /** * Epoch ms the structured layer first learned a dialog was open, or null * (Issue #1725). Non-null together with `isPromptWaiting` is how a caller * tells "the agent told us" from "the screen told us". */ promptWaitingSince?: number | null; /** `notification` / `permission-request`, or null (Issue #1725). */ promptWaitingSource?: string | null; /** * The last `tool_input` this server had to rewrite before it could * adjudicate it, or null (Issue #1902). * * Mirrors: src/lib/hooks/tool-input-normalization-state.ts * ToolInputNormalizationRecord. * * Copilot 1.0.80's `Edit` sends its apply-patch envelope as a bare string, * which `parseCopilotPermissionRequest` used to refuse — so every file edit * copilot made was answered `unknown-payload` (a no-decision) and drew a * dialog no matter what Auto-Yes said. It is now read as a patch, and this * field is how an operator sees that it was: a non-null `reason` says the * shape that was judged is not the shape the agent sent, and therefore why * the deny patterns were matched against the envelope's action headers * (`*** Add File: …`) rather than against the file body. * * `reason` is string-typed on the wire for the same reason * `lastSuppression.reason` is: a newer server may name a normalisation this * build has never heard of, and narrowing here would turn a * forward-compatible payload into a parse failure (Issue #1843). * * Optional here although the server always sends it — this mirror also * describes what an older daemon answers, and `undefined` means "this * server predates the field" rather than "nothing was normalised". */ toolInputNormalization?: { /** `string-tool-input-as-patch` / `string-tool-input-as-text`. */ reason: string; /** Key the raw value was stored under: `patch` or `text`. */ key: string; /** `typeof` the value the agent sent. `string` is the only measured one. */ receivedType: string; /** `tool_name` of the call that was normalised (`Edit` in #1902). */ toolName: string; /** Epoch ms. */ at: number; } | null; /** * The last approval this server adjudicated on the agent's behalf, or null * (Issue #1898). * * Mirrors: src/lib/hooks/permission-decision-state.ts * PermissionDecisionRecord. * * opencode's approvals are answered over a REST call nobody is holding, so * an Auto-Yes allow can approve a command, dismiss the dialog and leave no * trace on any surface an operator reads. This is that trace: what was * asked (`toolName`), what was answered (`behavior` / `reason`), whether it * reached the agent (`delivered`), and whether it retired the prompt * (`releasedPrompt`). `trigger` tells the live path apart from the * re-judgement `auto-yes --enable` performs on a dialog that was already up. * * `reason` and `trigger` are string-typed on the wire for the same reason * `lastSuppression.reason` is: a newer server may name a value this build * has never heard of, and narrowing here would turn a forward-compatible * payload into a parse failure (Issue #1843). * * Optional here although the server always sends it — this mirror also * describes what an older daemon answers. */ permissionDecision?: { /** The agent's own id for the dialog (`per_…`), or null. */ decisionId: string | null; /** `tool_name` the approval was judged as, or null. */ toolName: string | null; /** `allow`, or null for a no-decision. */ behavior: 'allow' | null; /** e.g. `auto-yes`, `auto-yes-disabled`, `policy-suppressed`. */ reason: string; /** Whether the verdict actually reached the agent. */ delivered: boolean; /** Whether this delivery retired the prompt-waiting record. */ releasedPrompt: boolean; /** `event` for the live frame, `policy-recheck` for `auto-yes --enable`. */ trigger: string; /** Epoch ms. */ at: number; } | null; /** * Which agent event source speaks for this tool, and what it declares it can * do (Issue #1924). * * Mirrors: src/lib/session/current-output-types.ts StructuredSourcePayload. * Optional here and required there for the usual reason — this CLI can be * newer than the server it is pointed at, and a build from before #1924 * sends no `source` at all. * * The string-typed fields are string-typed on purpose, exactly as * `lastSuppression.reason` is: a server newer than this CLI can declare a * `configScope`, an `eventIdentity` or a `resync` strategy this build has * never heard of, and narrowing the wire to the unions this build knows * would turn a forward-compatible payload into a parse failure. */ source?: { cliToolId: string; capabilities: { supportedEvents: string[]; configScope: string; decisionTimeoutSeconds: number | null; /** Issue #1924, §4 D3: the five declared values, verbatim. */ permissionHookPredictsDialog: boolean; sessionStartMayArriveLate: boolean; permissionReplyReleasesPrompt: boolean; /** * Where a frame-unique id for this source comes from, or null. * * Non-null is what makes an option number a VERDICT the server can POST * rather than a key it has to type, which is the gate `commandmate * respond` reads before choosing an endpoint (Issue #2040). */ eventIdentity: string | null; resync: string; /** * Issue #2197: which writer, other than the scraper, records this * tool's replies (`pull` / `push`, or null). String-typed as above, and * optional, as are the two below: a server older than the column sends * none of it. */ transcriptHistory?: string | null; /** Issue #2614: whether this source's `stop` says the agent will resume by itself. */ stopReportsSelfResume?: boolean; /** Issue #3820: whether answering `allow` means the agent draws no dialog for that call. */ permissionAllowSuppressesDialog?: boolean; }; /** * Which machinery is speaking for this pane right now (Issue #2054). * * `sse` / `hooks` / `scraper` — **string-typed, and optional, for the two * reasons the block above already gives.** A server newer than this CLI * can name a transport this build has never heard of, and a server older * than #2054 sends no `kind` at all; narrowing to the union would turn * both into a parse failure on a payload the reader could otherwise print. */ kind?: string; /** * Why this pane is not on the machinery its tool declares (Issue #2054). * * A token — `port_identity_changed`, `heartbeat_stale`, `not_subscribed`, * or whatever the transport recorded. Absent when nothing is degraded, and * absent on every push tool. */ degradedReason?: string; /** `live` / `stale`, or absent. Issue #2054, string-typed as above. */ liveness?: string; /** * What the source said about this instance's activity when its stream was * last attached, or null (Issue #2054). * * A record of one instant — `at` is when it was asked — and not a live * reading: `capture --json | jq '.structuredEvents.source.probedActivity'` * answers "was the pane mid-turn when CommandMate connected?", which is a * question the stream itself cannot answer until the turn ends. Null for * every tool that is not a subscription source. */ probedActivity?: { activity: string | null; at: number; } | null; }; /** * What the agent says about the conversation this instance is in, or null * (Issue #2040). * * Mirrors: src/lib/hooks/agent-session-telemetry.ts AgentSessionRecord. * * The half of a worker's state a terminal frame cannot show — which * session, which persona, which model, what it has cost. Read off frames * the server was already receiving, so it costs no request; null on every * tool that publishes none (all but opencode today), on an opencode pane * whose stream has not reported a session yet, and on one that has been * killed since it did. * * Every value is the agent's own, unrounded and unformatted: a reader * compares them against what the agent reports about itself, and tidying on * the way out breaks that comparison exactly when it matters. */ session?: { /** The agent's own session id, or null. */ id: string | null; /** The agent's own title for it, or null. Display only, bounded. */ title: string | null; /** Which persona is driving (opencode's `build` / `plan` / …), or null. */ agent: string | null; /** The model id, verbatim, or null. */ model: string | null; /** The provider that model belongs to, verbatim, or null. */ provider: string | null; /** What the session has cost so far, in the agent's own unit, or null. */ cost: number | null; /** * The tokens spent, as the agent counts them. * * Null members mean "the agent did not say", never zero. `cacheRead` / * `cacheWrite` are opencode's `tokens.cache.read` / `.write`, flattened; * `total` is declared on an assistant message rather than on a session, so * it is null today and is NOT this server's own sum of the other five. */ tokens: { input: number | null; output: number | null; reasoning: number | null; cacheRead: number | null; cacheWrite: number | null; total: number | null; }; /** Epoch ms this record was written, so a reader can judge its age. */ at: number; } | null; /** * How full this instance's context window is, or null (Issue #2042). * * Mirrors: src/lib/hooks/agent-session-telemetry.ts * AgentSessionContextUsage. * * **Not derivable from `session.tokens`, which is why it is its own block.** * Those counts are the session's *cumulative* spend — the figure `opencode * stats` prints — while "how much of the window is in use" is the last * finished assistant turn's footprint. Measured over two turns the session * summed to 16,999 (`2%`) where opencode's own footer read 8,508 (`1%`), and * the gap widens with every turn. * * Every member here is computed by the server from two reads of the agent's * own API, so unlike `session` this block is *derived*: `percent` is * opencode's own `round(tokens / limit.context * 100)`, transcribed from * 1.18.22 rather than guessed. * * Optional, and null until the first measurement lands — it is refreshed off * the poll path, so the poll that notices a turn ended publishes the * previous numbers and the next one publishes the new. Null forever on every * tool but opencode. */ sessionContext?: { /** The last finished assistant turn's token footprint, or null. */ tokens: number | null; /** The model's declared context window (`limit.context`), or null. */ limit: number | null; /** `round(tokens / limit * 100)`, or null when either input is null. */ percent: number | null; /** The `session.at` these numbers were measured against. */ sessionAt: number; /** Epoch ms this record was written. */ at: number; } | null; /** * What the last opencode turn changed on disk (Issue #2043), or null. * * Mirrors: src/lib/hooks/sources/opencode/diff.ts * OpencodeSessionDiffRecord. * * **`files` and `revertedFiles` are different questions.** `files` is what * the turn named by `turnMessageId` changed, read from * `GET /session/:id/diff?messageID=...` — the only call measured to answer * it on 1.18.22. `revertedFiles` is what a revert is holding back right now, * off the `session.diff` frame, and is empty whenever nothing is reverted. * * Issue #2043 assumed `session.diff` carried the first of these. It does * not: every `session.diff` frame of two file-editing turns carried * `diff: []`, including the one emitted alongside `session.idle`. See * `docs/design/opencode-server-live-verification.md` §16. * * Optional and null for every tool but opencode, and for an opencode pane * whose stream has not reported a turn yet. */ sessionDiff?: { /** The session these files belong to, or null. */ sessionId: string | null; /** The user message whose turn `files` describes, or null. */ turnMessageId: string | null; /** What that turn changed. Empty until the read has answered. */ files: AgentSessionDiffFile[]; /** Epoch ms `files` was read at, or null when it never was. */ filesAt: number | null; /** What a revert is holding back. Empty when nothing is. */ revertedFiles: AgentSessionDiffFile[]; /** The message a revert is holding back to, or null. */ revertedMessageId: string | null; /** Epoch ms the newest frame that touched this record arrived. */ at: number; } | null; }; /** * Issue #1839: the upstream (model API) fault visible on the live frame, or * null when no known signature matched. * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.upstreamFault * * **null is not an all-clear.** It means no signature from * `src/lib/detection/upstream-faults.ts` was on the rows `realtimeSnippet` * publishes — the pane may have scrolled, or the failure may have left it * blank (measured in #1834). Only a non-null value is evidence of anything. * Issue #3946: on codex's split screen the transcript's last row above that * window is read too (`model-capacity` only), so `matchedText` may be a row * that is not in `realtimeSnippet`. * * Optional here although the server always sends it, for the reason * {@link CurrentOutputResponse.model} gives: this mirror also has to describe * what an older daemon answers, and the CLI is routinely newer than the * server it dials. */ upstreamFault?: { /** `overloaded` / `retrying` / `context-limit` / `model-capacity` / `limit-reached` / `api-error` (`UPSTREAM_FAULTS`). */ id: string; /** The whole line that matched, trimmed and bounded to 200 UTF-8 bytes. */ matchedText: string; /** Epoch ms the frame was captured. */ at: number; } | null; /** * Issue #2095: a second column sharing rows with the agent's transcript, or * null when the frame's layout could not be read as two columns. * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.paneObstruction * * **null is not an all-clear**, for the same reason {@link upstreamFault}'s is * not: an opencode permission dialog removes the border row the geometry is * measured from, and no tool other than opencode is examined at all. * * The one value shipped is `opencode_sidebar` — opencode's own sidebar, turned * on by `ctrl+x b` or by its `ctrl+p` palette, painted across the same rows as * the transcript and the input box. It hides the marker that ends a turn, so * the pane reads `running` / `unknown_frame` until it is closed. `wait` does * not branch on this field; it names it in the message it already prints for * an unclassified frame. * * Optional here for the same reason as every other field on this mirror: an * older daemon sends nothing, and the CLI is routinely newer than the server * it dials. */ paneObstruction?: { /** `opencode_sidebar`. */ id: string; /** The second column's own text, trimmed and bounded to 200 UTF-8 bytes. */ matchedText: string; /** Epoch ms the frame was captured. */ at: number; } | null; /** * Text sitting unsent in the agent's input box, or null (Issue #1879). * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.composerText * * Only text a human typed is ever carried here. Null covers every other case * — the box is empty, it holds only a dim suggestion or placeholder, it is * not on screen, the tool's composer has not been measured, or the session is * not running — and {@link composerState} says which. claude and codex only. * * Absent from a server older than #1879. */ composerText?: string | null; /** * Which state {@link composerText} came from (Issue #1879): `content` (real * text, carried above), `ghost` (only a dim suggestion / placeholder), * `empty`, `unsupported_tool`, or `no_composer` (no input box on the frame, * and the answer for a session that is not running). * * Mirrors: src/lib/detection/composer-text.ts ComposerTextState — typed as * the wire's `string`, like `lastSuppression.reason`: a newer server may name * a state this build has never heard of. Absent from a server older than #1879. */ composerState?: string; /** * Issue #1785: the model the session is running, or null when nothing knows. * * Mirrors: src/lib/session/current-output-types.ts CurrentOutputPayload.model * * Optional *here* although the server always sends it, and the two are not in * conflict: this mirror also describes what an older daemon answers, and the * CLI is routinely newer than the server it dials (`npm i -g` does not restart * the running daemon). `undefined` therefore means "this server predates the * field", which the commands normalise to null — the same thing they print for * a tool that publishes no model. */ model?: string | null; /** * Issue #1785: reasoning effort, or null when nothing knows. * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.reasoningEffort — including the part where it is null * for every session until Issue #1784's extraction layer lands. */ reasoningEffort?: string | null; /** * Issue #1695: prompts the content-hash dedup guard suppressed for this * session, and when it last did. * * Mirrors: src/lib/polling/prompt-dedup-state.ts PromptDedupSkips * * The field an operator reads when a prompt was on screen but no prompt * message exists: a non-zero `skippedCount` with a recent `lastSkippedAt` * means `isDuplicatePrompt` dropped it, and a zero means the detection layer * never classified the frame at all (Issue #1676) — two causes with the same * symptom that nothing in this payload could previously separate. * * `skippedCount` is cumulative for the life of the server process, not * per-turn, so `lastSkippedAt` is what dates the evidence. * * Optional here for the same reason `model` is: this mirror also describes * what an older daemon answers, and `undefined` means "this server predates * the field" rather than "nothing was skipped". */ promptDedup?: { skippedCount: number; lastSkippedAt: number | null; }; /** * Issue #1884: which stage of the server's precedence chain picked * {@link CurrentOutputResponse.cliToolId}. * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.resolvedBy — and, like `lastSuppression.reason`, * deliberately typed as the wire's `string` rather than the union this build * knows: a server newer than the CLI can name a stage this build has never * heard of, and narrowing here would turn a forward-compatible payload into a * parse failure. * * The field to read when a session visible in tmux is reported as not * running. Absent from a server that predates #1884 — which is also a server * that resolves `?instance=` incorrectly, so its absence is itself the answer. */ resolvedBy?: string; /** * Issue #1884: the explicit `?cliTool` the roster contradicts, or null. * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputPayload.conflict. This is a read path, so the server resolves * the contradiction (roster wins) and answers 200 with it attached rather * than 400 — the commands that act refuse it instead (DR3-015). */ conflict?: { instanceId: string; rosterCliTool: string; requestedCliTool: string; } | null; /** * Which permission mode the agent is in, read off the frame (Issue #2592): * `default` / `manual` / `accept-edits` / `plan` / `auto` / `autopilot` / * `bypass` / `dont-ask` / `build`, or `unknown`. * * Mirrors: src/lib/session/current-output-types.ts * CurrentOutputResponseBody.agentMode (`AgentMode` in * src/types/cli-tool-contracts.ts). The route attaches it; it is on the HTTP * response and not on the WebSocket snapshot. * * **`unknown` is not a mode, and never means `default`.** It is the reader * declining to answer: the tool has no mode cycle, no indicator was on the * frame, or the session is not running. Most tools draw nothing in their base * mode, so a frame with no indicator cannot be told from one captured * mid-repaint or one whose footer scrolled away. * * Typed as the wire's `string` for the reason `lastSuppression.reason` is, * and absent from a server older than #2592 — which is also not `default`. */ agentMode?: string; /** * Whether the server's detection rules were read off the CLI build that is * installed (Issue #1929, design §4 D2 / §7). * * Optional **twice over**, and the two absences mean different things: * * - no `detector` key at all — either a server older than #1929, or a server * whose probe cache is still cold. `capture --json` runs on a 5-second * poll, so the probe is never awaited on that path (DR3-013); the first * polls after a restart simply carry nothing and a later one carries the * answer. Read it as "not known yet", never as "nothing is stale". * - `detector.staleness` present but `{}` — the probe HAS answered and every * tool it could read is at or below the version its rules were measured * against. * * A tool appears only when its installed build is strictly newer than * `verifiedAgainst`. A tool that is not installed, whose `--version` could not * be read, or whose executable did not resolve on `PATH` is absent — no probe * was run for it and no child process was spawned (§13.2 S17). * * Kept off `GET /api/capabilities` deliberately: an installed-CLI version list * is a software inventory, so it is published only on authenticated surfaces * (DR4-008). */ detector?: { staleness?: Record; }; } /** * `GET /api/worktrees/:id/current-output?observe=1` (Issue #3755): the same * payload plus one prompt observation of the same capture. * * A type of its own rather than a field on {@link CurrentOutputResponse}: the * route attaches it only when asked, and that interface mirrors the response * every caller gets (current-output-mirror-3300). Optional for a daemon older * than the field, which ignores `observe`. */ export interface CurrentOutputObservedResponse extends CurrentOutputResponse { promptObservation?: PromptObservation; } export interface PromptData { type: string; question: string; /** * Mirrors src/types/models.ts MultipleChoiceOption. Since Issue #1726 an * option may also carry `description` — the second line the AskUserQuestion * picker renders — when the agent's own `PreToolUse` payload supplied it. */ options?: unknown[]; status?: string; answer?: string; answeredAt?: string; /** Mirrors: src/types/models.ts PromptAnsweredBy (Issue #1685) */ answeredBy?: string; /** Human-facing context block preceding the prompt (Issue #235). */ instructionText?: string; /** * What this prompt asks approval for — the surface `autoYes.denyPatterns` are * judged against (Issue #1699). Narrower than `instructionText` on purpose: * the latter is a pane window and carries finished turns. */ approvalTarget?: string; /** * Issue #3881: set when `approvalTarget` is known not to be the whole of * what the prompt asks about — cut at its 12-row scan cap or at an * ambiguous `>` boundary (`truncated`), or reaching the top of a capture * that may have been cut (`top-unknown`). A deny miss on it withholds as * `deny-pattern-unusable`. * * Mirrors: src/types/models.ts BasePromptData.approvalTargetCompleteness. */ approvalTargetCompleteness?: 'truncated' | 'top-unknown'; /** * Issue #3881: what the screen was read as when the row was saved (kind, * phase, live rows, the target's completeness, evidence). Absent on a row * saved before #3881 or by a producer with no frame. The wire's shape, kept * loose like `options`: the CLI does not read it. * * Mirrors: src/types/prompt-reading.ts PromptReading. */ reading?: { version: number; kind: string; phase?: string; liveRange?: { startRow: number; endRow: number; }; approvalTarget: string; captureTop?: string; evidence: string[]; }; /** * The verdicts a structured approval accepts, when this payload is the * degraded `unclassified` form for a source that can be answered by decision * id (Issue #1898). * * Mirrors: src/lib/session/structured-prompt.ts StructuredDecisionOption. * * Held apart from {@link options}, which stays empty on that payload: a * reader that answers by typing an option number at the pane must go on * finding nothing here, because these numbers are verdicts delivered over the * agent's own API rather than lines on a screen. `commandmate wait` reports * them on its exit-10 output so the caller is told what `respond` will take. */ decisionOptions?: Array<{ number: number; label: string; reply: string; }>; /** * The agent's own id for the decision this dialog is (Issue #1932 / #2100). * * Mirrors: src/lib/session/structured-prompt.ts * StructuredPromptWaitingData.decisionId. * * `null` is a real answer — "this server looked and there is no addressable * decision" — and is distinct from the field being absent, which means a * daemon from before #2031 sent no such key at all. Present for BOTH kinds of * addressable decision since #2100: an approval, whose replies are * {@link decisionOptions}, and a question, whose replies are the numbered * choices published on `structuredEvents.pendingDecisions[].questionOptions`. * The two are never published together — see the note on * `readPromptQuestionChoices`. */ decisionId?: string | null; /** * What the agent asked, when this dialog is an `AskUserQuestion`-style call * (Issue #1726). * * Mirrors: src/lib/session/structured-prompt.ts * StructuredAskUserQuestionSummary. * * Whether the numbers here may be ANSWERED is not a property of this field: * it is `decisionId` plus `questionCount === 1` plus the absence of * {@link decisionOptions}. Claude publishes this summary for a picker only * its pane can see, with no id to deliver an answer to. */ askUserQuestion?: { question: string; labels: string[]; questionCount: number; }; [key: string]: unknown; } export interface PromptMessageResponse { id: string; worktreeId: string; role: string; content: string; timestamp: string; messageType: string; promptData?: PromptData; cliToolId?: string; instanceId?: string; /** * The producer's own id for this row, when it had one (Issue #2386). * * `chat_messages.request_id`, already carried by the server's internal * `ChatMessage` and already serialized by * `GET /api/worktrees/:id/messages` — it was simply missing from this mirror, * so the CLI could not see the one field that separates a transcript reader's * row from a screen scrape. * * It is a namespace plus an id, and the namespace is what a reader matches: * `-turn:` (`codex-turn:`, `claude-turn:`, `antigravity-turn:`, * `command-code-turn:`, opencode's `oc-turn:`) means "a transcript reader * wrote this, and it is the agent's own words"; `relay-sys:` / `model-changed:` * mean "CommandMate wrote this about the session"; **absent** means the row * came off the screen. `ask` requires the first of those (Issue #2386): the * codex scraper writes the idle composer into the ledger as an assistant row * with no request id in the millisecond before a send, and that junk was * being printed as the answer. */ requestId?: string; archived: boolean; } /** * One entry of `capture --prompts --json`'s `prompts` (Issue #1685), built by * `src/cli/commands/capture.ts` from a {@link PromptMessageResponse}. A field * the row does not carry is `null`. */ export interface CapturePromptEntry { id: string; timestamp: string; cliToolId: string | null; instanceId: string | null; type: string; question: string; options: unknown[] | null; status: string | null; answer: string | null; answeredAt: string | null; answeredBy: string | null; /** Issue #1699: what the contract's denyPatterns were judged against. */ approvalTarget: string | null; /** * Issue #3907: the same audit fields `wait` passes on * ({@link WaitPromptOutput}, #3881), from the stored row. */ approvalTargetCompleteness: PromptData['approvalTargetCompleteness'] | null; reading: PromptData['reading'] | null; /** Issue #1725: which structured signal reported an unclassified row. */ source: string | null; } export interface PromptResponseResult { success: boolean; answer: string; /** * e.g. `prompt_no_longer_active`, `unresolvable_answer`, and since Issue * #1726 `answer_out_of_range` — the option number is outside the list the * agent's own `AskUserQuestion` payload declared, so nothing was sent. */ reason?: string; /** Issue #1681: detail accompanying a reason that refused to send. */ message?: string; /** * Issue #1681: how a semantic yes/no or --default answer was resolved. * * Issue #1726 also reports `via: 'semantic'` here when an option LABEL was * matched against the agent's structured options (`respond Blue` → 1). */ resolved?: { /** * Issue #1898 adds `structured-decision`: the answer was delivered to the * agent's own API by decision id rather than typed at the pane, so * `optionNumber` names a verdict (1 = Allow once, 2 = Allow always, * 3 = Reject) and not a line on a screen. */ via: 'semantic' | 'default' | 'structured-decision'; optionNumber?: number; optionLabel: string; /** The approval that was answered (Issue #1898). Absent on the key paths. */ decisionId?: string; }; /** * Issue #3125: what was done on Command Code's plan review overlay. Present * only when the answer went to that overlay. */ planReview?: { action: 'comment' | 'submit' | 'approve' | 'cancel'; comment: string | null; phase: string; pendingCommentsBefore: number; approveChoice?: 'with-comments' | 'discard-comments'; }; } /** * Mirrors: src/app/api/worktrees/[id]/respond/structured-decision.ts, the body * of `POST /api/worktrees/[id]/respond` for the two id-less shapes * (Issue #2040). * * A different route from {@link PromptResponseResult} and therefore a different * mirror, even though `respond` reports both through the same lines. The * difference that matters is `resolved.via`: this route answers a QUESTION as * well as an approval, and a question's answer is a list of labels rather than * one verdict — so `optionNumber` / `optionLabel` are absent on that branch and * `answers` / `optionNumbers` / `optionLabels` / `freeText` take their place. * * Every field is optional for this file's usual reason: the CLI is routinely * newer than the daemon it dials, and a server from before #2040 answers this * body's shape only for the `{ decisionId, answer }` request. */ export interface StructuredDecisionResult { /** False when the verdict was resolved but the POST to the agent did not land. */ success: boolean; /** The option number for an approval; the chosen numbers, or the text, for a question. */ answer: string; /** `decision_not_delivered` — the only reason this shape carries on a 200. */ reason?: string; /** Detail accompanying a reason, when the server sent one. */ message?: string; resolved?: { /** `structured-decision` for an approval, `structured-question` for a question. */ via: 'structured-decision' | 'structured-question'; /** Approval only: 1 = Allow once, 2 = Allow always, 3 = Reject. */ optionNumber?: number; /** Approval only: the verdict's label. */ optionLabel?: string; /** The decision that was answered. */ decisionId?: string; /** Question only: exactly what went on the wire — one array of labels per question. */ answers?: string[][]; /** Question only: the numbers the answer named, empty for free text. */ optionNumbers?: number[]; /** Question only: the labels those numbers named. */ optionLabels?: string[]; /** Question only: whether this was prose the agent never offered as a choice. */ freeText?: boolean; }; } /** * Mirrors: src/app/api/worktrees/[id]/auto-yes/route.ts AutoYesResponse * [Issue #1898, extended by Issue #1909]. * * Every optional field is optional for the reason the rest of this file states — * the CLI is routinely newer than the daemon it talks to (`npm i -g` does not * restart a running server), so a field's absence means "this daemon predates * it", never "the answer is none". For `cliToolId` that distinction is the bug * itself: a server that does not name the agent is a server still arming a * hard-coded claude (#1909). The CLI reports what it was told and nothing more. */ export interface AutoYesSetResult { enabled: boolean; expiresAt: number | null; /** * Issue #3863: the answer mode the instance is on with (`recommended` / * `careful`) — what an omitted `answerMode` resolved to, too. Absent when * not enabled and from an older server. */ answerMode?: string; /** * Issue #4132: which enabling this is, on the same answers as `answerMode`. Handed back * as `?expectedGrantId=` to turn off this grant and no other. Absent from an older server, * which then cannot be asked for that (Issue #4159). Pinned to the route by * tests/integration/cli-response-types-4159.test.ts. */ grantId?: string; pollingStarted?: boolean; /** * Approvals that were already pending and got re-judged by this call * (Issue #1898-2). Absent when nothing was re-read — which is every hook * tool, whose `resync` capability is `none`. */ pendingDecisions?: { examined: number; delivered: number; skipped: number; }; /** * Issue #1909: the agent whose poller this request armed — and, therefore, * the agent `pendingDecisions` was re-judged for. One resolved pair. */ cliToolId?: string; /** The instance it was armed for (the primary instance's id is its cliToolId). */ instanceId?: string; /** * Which stage of the server's precedence chain chose `cliToolId`. Typed as the * wire's `string` rather than a union, like CurrentOutputResponse.resolvedBy: * a newer server may name a stage this build has never heard of, and * narrowing would turn that into a parse failure. */ resolvedBy?: string; /** Read path only; a POST that contradicts the roster is refused, not resolved. */ conflict?: { instanceId: string; rosterCliTool: string; requestedCliTool: string; } | null; /** * Issue #3723: what the contract governing the armed instance says about * Auto-Yes, or null when no contract governs it. Absent from a server older * than #3723 and from a disabling POST. `mode: 'off'` means the poller this * request armed will answer nothing. `mode` is the wire's `string`, for the * reason `resolvedBy` above is. */ contractPolicy?: AutoYesContractPolicy | null; } /** Mirrors: src/lib/polling/auto-yes-policy.ts ContractPolicySummary [Issue #3723]. */ export interface AutoYesContractPolicy { taskId: string | null; mode: string | null; allowPromptTypes: string[]; denyPatternCount: number; } /** * Mirrors: src/app/api/worktrees/[id]/auto-yes/route.ts GET with no * `?cliToolId` — the whole-worktree form (Issue #525 / #896). Only the map the * CLI reads is declared; the body also carries the worktree default agent's * state at the top level and an `agents` map keyed by cliToolId. * * `instances` holds every instance the server has an Auto-Yes state for, armed * or not, keyed by instance id (the primary instance's id is its cliToolId). An * instance with no entry has no state: it was never armed, or the state was * released with the instance. Unlike `CurrentOutputResponse.autoYes` this does * not depend on the session running (Issue #3300). * * Optional because a daemon older than #896 sends no such map. */ export interface AutoYesStatesResponse { /** * Issue #3723: `blockedByContract` is true when the instance is armed but its * contract says `autoYes.mode: 'off'`; omitted otherwise and by older servers. */ instances?: Record; /** * Issue #3863: each ENABLED instance's answer mode (`recommended` / * `careful`), keyed like `instances`. Beside the map rather than in its * entries, whose shape is kept. Absent from older servers. */ answerModeByInstance?: Record; } /** wait exit 10 CLI extended output type */ export interface WaitPromptOutput { worktreeId: string; cliToolId: string; type: string; question: string; options: unknown[]; status: string; /** * How the prompt is answered (Issue #3184), from the shared prompt view: * `screen` (keys at the pane), `api` (a decision over the agent's API) or * `terminal` (nothing to offer). Added beside `type`, which keeps its meaning. */ answerVia?: 'screen' | 'api' | 'terminal'; /** * What the prompt asks approval for, when the detector could attribute a block * to it (Issue #1699). Present so a caller that reads only this payload can * see what a `deny-pattern` verdict below was actually judged against. */ approvalTarget?: string; /** * Issue #3881: the same fields as on {@link PromptData}, for the prompt this * output was built from, copied by `wait` (`src/cli/commands/wait.ts`) when * the server sent them. Absent otherwise (older servers; `reading` is on * stored rows, so a live payload usually carries none). */ approvalTargetCompleteness?: PromptData['approvalTargetCompleteness']; reading?: PromptData['reading']; /** * Set when the contract's autoYes policy withheld an answer for this session * (Issue #1699). Without it, a prompt an operator has to answer by hand is * indistinguishable on stdout from one nobody configured Auto-Yes for — which * is why the #1699 suppression loop went unnoticed for an hour. */ autoYesSuppression?: { reason: string; mode: string | null; promptType: string; pattern?: string; ageSeconds: number; /** * Issue #3863: the Auto-Yes answer mode in effect (`recommended` / * `careful`), from `autoYesAnswerMode`. Absent when the server publishes * none (older, or Auto-Yes off). The wire's `string`, like `mode`. */ answerMode?: string; }; /** * One prompt observation of the frame this exit was decided on (Issue * #3755): the screen's kind, an observation token, and Auto-Yes as two * separate items — the poller's record and the contract re-evaluated now. * Absent when the server is older than the field. `autoYesSuppression` above * keeps its meaning (the record of this wait: by the episode ids when both * are present, Issue #3798, else a record under a minute old); this does not * read the record's time as "the reason this prompt is unanswered". */ observation?: PromptObservation; [key: string]: unknown; } export interface DailySummaryGetResponse { report: SerializedReport | null; messageCount: number; } export interface DailySummaryGenerateResponse { report: SerializedReport; generated: boolean; } export interface SerializedReport { date: string; content: string; generatedByTool: string; model: string | null; createdAt: string; updatedAt: string; } export interface VibeMetrics { periodDays: number; tasks: { total: number; succeeded: number; failed: number; notStarted: number; cancelled: number; /** 0..1 fraction; null when no tasks were created in the window. */ successRate: number | null; /** null when nothing failed in the window. */ avgRetryLoops: number | null; }; verification: { runs: number; passed: number; failed: number; notStarted: number; /** 0..1 fraction; null when no runs started in the window. */ passRate: number | null; gateFailBreakdown: Array<{ gateId: string; failCount: number; }>; }; intervention: { humanResponds: number; autoAnswered: number; /** Always null in v1: the policy suppression log is not persisted. */ suppressedByPolicy: number | null; }; } export interface VibeMetricsResponse { metrics: VibeMetrics; } export interface TemplateResponse { id: string; name: string; content: string; } export interface DailySummaryStatusResponse { generating: boolean; date?: string; tool?: string; startedAt?: string; } /** * Issue #4344: the ask correlation ledger as the CLI reads it (design * `docs/design/ask-attribution-4344.md` §3.3・§4). * Mirrors: src/types/ask-correlation.ts (held equal by * tests/unit/cli/types/ask-attribution-mirror-4344.test.ts). */ export type AskAttributionState = 'pending' | 'matched' | 'ambiguous' | 'unmatched' | 'unavailable'; /** Issue #4344: why an ask ended where it did. Mirrors src/types/ask-correlation.ts. */ export type AskAttributionReason = 'tool_unsupported' | 'server_unsupported' | 'slash_command' | 'shared_turn' | 'turn_open_at_send' | 'envelope_lost' | 'absorbed_mid_turn' | 'envelope_duplicated' | 'turn_incomplete' | 'generation_changed' | 'history_missing' | 'body_truncated' | 'send_unknown' | 'not_sent' | 'grace_expired' | 'turn_interrupted' | 'history_changed'; /** Issue #4344: how the send of a reserved ask ended. Mirrors src/types/ask-correlation.ts. */ export type AskSendState = 'reserved' | 'sent' | 'not_sent' | 'send_unknown'; /** Issue #4344: `GET /api/asks/capabilities`. Mirrors src/types/ask-correlation.ts. */ export interface AskCapabilitiesResponse { protocol: number; /** Per tool: whether the server attributes an ask's reply by the ledger. */ tools: Record; } /** * Issue #4344 (PR3 review): why an attributed tool is on or off for its version. * Mirrors src/lib/ask/ask-correlation.ts AskToolVersionState. */ export type AskToolVersionState = 'ok' | 'too_old' | 'unreadable'; /** Issue #4344 (PR3 review): one attributed tool's version. Mirrors src/lib/ask/ask-correlation.ts AskToolVersion. */ export interface AskToolVersion { minimum: string; installed: string | null; state: AskToolVersionState; } /** * Issue #4344 (PR3 review): `GET /api/asks/capabilities` with the version * readings. `versions` is optional here: a PR1/PR2 server does not send it. * Mirrors src/lib/ask/ask-correlation.ts AskCapabilitiesBody. */ export interface AskCapabilitiesBody extends AskCapabilitiesResponse { versions?: Record; } /** Issue #4344: `GET /api/asks/:askId`. Mirrors src/types/ask-correlation.ts. */ export interface AskAttributionResponse { askId: string; state: AskAttributionState; reason: AskAttributionReason | null; /** The reply, only when `state === 'matched'`. */ reply: string | null; sendState: AskSendState; /** Whether the reader has seen the native input that carried the envelope. */ nativeInputSeen: boolean; /** The answering turn also absorbed a background-task notice. */ notified: boolean; } /** Issue #4344: the `ask` field of a send's answer. Mirrors src/types/ask-correlation.ts. */ export interface AskSendAnswer { id: string | null; state: AskAttributionState; reason: AskAttributionReason | null; sendState?: AskSendState; } export interface ChatMessage { id?: number; worktreeId: string; role: string; content: string; /** Issue #4115/#4116: the process a send with a role condition reached. */ roleLaunch?: { sessionGeneration: string; injectionFingerprint: string | null; saved: boolean; stored: unknown; }; /** Issue #4115/#4116: this tool's role replaces its default instructions. */ replacesDefaultInstructions?: boolean; /** Issue #4115/#4116: OpenCode V1 continued a conversation that had another role. */ roleResume?: { continued: boolean; message: string; }; cliToolId?: string; createdAt?: string; /** * When the row was stamped, on the server's clock: the moment the body * started going in (Issue #3953), or the moment read before the send on a * path that reports no input start / a server before #3953. `ask` bounds the * earlier-ask side of its overlap check with it (Issue #3957). */ timestamp?: string; /** * Issue #3957: whether the instance was mid-turn by its own turn record at * the moment the body started going in (opened, not closed by then) — true * or false. Absent for "not known": a tool whose hooks do not report both a * turn start and its `stop`, a sender that reports no input start, a * relaunch during the send, a server before #3957. * Mirrors: src/app/api/worktrees/[id]/send/route.ts SendMessageResponse. */ turnOpenAtSend?: boolean; /** * Issue #4344: present when the send named `ask` (a synchronous `commandmate * ask`) on a server that attributes asks: `pending` with the reserved id, or * `unavailable` with why (`tool_unsupported` / `slash_command`) and no id. * Mirrors: src/types/ask-correlation.ts AskSendAnswer. */ ask?: AskSendAnswer; /** * Issue #3957: present when the send named a bound relay (`relayId`). What * the CLI may do with the relay: `not_sent` — nothing reached the worker, * withdraw it; `sent` / `unknown` — leave it (the server holds `unknown`). * Also on the error bodies after the reservation. Issue #4011: a send with * no bound relay carries it on its error bodies only (`not_sent` / `unknown`, * once the failure was recorded as its attempt; no 400), never on its 201. */ sendOutcome?: 'sent' | 'not_sent' | 'unknown'; /** * Issue #4274: present when a session brief was put in front of the message * (`attached`), when the send named `--no-brief` / `--with-brief`, or when the * delivery of a claimed brief is not known. Absent otherwise. * Mirrors: src/lib/session/session-brief.ts BriefReport. */ brief?: { /** Issue #4227: `consumed` — the screen's `full` / `decline` found its boundary used up by another send. */ state: 'attached' | 'skipped' | 'unknown' | 'not_sent' | 'consumed'; /** * A word when skipped: `no_brief`, `unsupported`, `slash_command`, `off`, `disabled`, * `target_unresolved`, `empty`, `over_limit`, `provider_failed`, `incarnation_changed`, * `settings_changed`, `superseded`, `reservation_conflict`, and (Issue #4224) * `worktree_changed` — deleted, made again or renamed after the send's entrance — and * `lifetime_unpinned` — the entrance had no evidence of the worktree's lifetime. A send whose * pin is not proven `same` writes nothing on the ledger (D2 design §20); an `unknown` delivery * may carry `worktree_changed` when its claim could not be recorded for that reason. * Issue #4227: `declined` — the screen's "don't read" used the boundary up. With `not_sent`, * `claim_held` (pr3f) — the body was not typed and the boundary could not be put back to * `pending`: it stays claimed by this server, whose next `full` / `decline` send is 409 `claimed`. */ reason?: string; boundaryId?: string; }; } /** Mirrors: src/lib/skills/compatibility.ts SkillCompatibilityStatus. */ export type SkillCompatibilityStatus = 'compatible' | 'incompatible' | 'unknown'; /** Mirrors: src/lib/skills/compatibility.ts SkillCommandMateCompatibility (subset). */ export interface SkillCompatibilityView { status: SkillCompatibilityStatus; /** English fallback message built server-side from code, range and host version. */ message: string; requiredRange: string; } /** Mirrors: src/lib/api/skills-api.ts SkillCatalogMetaDto (subset). */ export interface SkillCatalogMeta { stale: boolean; offline: boolean; state: string; /** Why the served Catalog is stale, or null when it was confirmed current. */ staleReason: string | null; fetchedAt: string; revalidatedAt: string; source: { repository: string; ref: string; revision: string | null; }; } /** Mirrors: src/lib/api/skills-api.ts SkillVersionDto (subset; artifact.url is never served). */ export interface SkillCatalogVersionSummary { version: string; declaredRisk: string; prerelease: boolean; publishedAt: string; compatibility: { commandmate: SkillCompatibilityView; }; } /** Mirrors: src/lib/api/skills-api.ts SkillDto (subset). */ export interface SkillCatalogSummary { id: string; name: string; summary: string; provider: { name: string; }; license: string; homepage: string | null; latest: string; recommendedVersion: string | null; recommendedReason: string; compatibility: SkillCompatibilityView | null; versions: SkillCatalogVersionSummary[]; } /** Mirrors: src/app/api/skills/route.ts GET response. */ export interface SkillListResponse { catalog: SkillCatalogMeta; skills: SkillCatalogSummary[]; } /** Mirrors: src/app/api/skills/[id]/route.ts GET response. */ export interface SkillDetailResponse { catalog: SkillCatalogMeta; skill: SkillCatalogSummary; } /** A typed reason an operation is refused, with the repository-relative path responsible. */ export interface SkillPlanBlocker { code: string; path: string | null; } /** Mirrors: src/lib/skills/install-plan.ts SkillInstallPlanDto (subset). */ export interface SkillInstallPlan { /** Single-use token the apply step presents unchanged. The CLI never inspects it. */ token: string; expiresAt: string; installable: boolean; requiresRiskAcknowledgement: boolean; riskAcknowledged: boolean; blockers: SkillPlanBlocker[]; warnings: string[]; target: { worktreeId: string; worktreeName: string; repositoryName: string; branch: string | null; headState: string; workingTreeDirty: boolean; /** `git status` could not be read; `workingTreeDirty` is the fail-safe guess (#3445). */ workingTreeUnknown?: boolean; /** Repository-relative; the server never serves a machine-absolute path. */ installRoot: string; /** Every root the package is placed into, primary first (#1460). */ installRoots?: string[]; existingInstall: { version: string; receiptDigest: string; } | null; }; skill: { id: string; name: string; version: string; summary: string; license: string; declaredPermissions: string[]; effectiveRisk: string; riskRationale: string; scriptPaths: string[]; executablePaths: string[]; requirements: { commands: Array<{ name: string; versionRange: string | null; }>; networkHosts: string[]; }; compatibility: { commandmate: SkillCompatibilityView; agents: Array<{ agent: string; support: string; }>; }; }; stats: { added: number; modified: number; unchanged: number; conflicted: number; unmanaged: number; }; } /** Mirrors: src/app/api/worktrees/[id]/skills/[skillId]/plan/route.ts POST response. */ export interface SkillInstallPlanResponse { plan: SkillInstallPlan; } /** * Mirrors: SkillInstallOperationDto / SkillUninstallOperationDto (subset). * `committed_reconciling` means the worktree already changed — never reported as a failure. */ export interface SkillOperationResult { operationId: string; state: string; result: 'succeeded' | 'committed_reconciling'; committed: boolean; reconcilePending: boolean; nextActionKey: string; replayed: boolean; } /** * Mirrors: src/app/api/worktrees/[id]/skills/[skillId]/install/route.ts POST response. * `files` is absent from the narrower replay body, and `install` is null when a * replay finds no index row. */ export interface SkillInstallResponse { operation: SkillOperationResult; install: { skillId: string; version: string; installRoot: string; installRoots?: string[]; files?: Array<{ path: string; }>; } | null; } /** Mirrors: api/worktrees/[id]/skills/[skillId]/git-workflow prepare response (Issue #1247). */ export interface SkillGitWorkflowPrepareResponse { workflowToken: string; target: { mode: string; branch: string; baseBranch: string | null; headCommit: string; branchCreated: boolean; remote: string; }; } /** Mirrors: api/worktrees/[id]/skills/[skillId]/git-workflow apply response (Issue #1247). */ export interface SkillGitWorkflowApplyResponse { result: { branch: string; baseBranch: string | null; changedPaths: string[]; committed: boolean; commitSha: string; pushed: boolean; pullRequestUrl: string | null; pullRequestExisted: boolean; }; } /** Mirrors: src/lib/skills/uninstall-plan.ts SkillUninstallPlanDto (subset). */ export interface SkillUninstallPlan { token: string; expiresAt: string; removable: boolean; blockers: SkillPlanBlocker[]; nextActionKey: string; target: { worktreeId: string; worktreeName: string; repositoryName: string; branch: string | null; workingTreeDirty: boolean; /** `git status` could not be read; `workingTreeDirty` is the fail-safe guess (#3445). */ workingTreeUnknown?: boolean; installRoot: string; }; skill: { id: string; version: string; effectiveRisk: string; }; removals: Array<{ path: string; }>; retained: Array<{ path: string; reason: string; }>; stats: { removable: number; modified: number; missing: number; unknown: number; irregular: number; }; } /** Mirrors: src/app/api/worktrees/[id]/skills/[skillId]/uninstall-plan/route.ts POST response. */ export interface SkillUninstallPlanResponse { plan: SkillUninstallPlan; } /** A typed reason an update is refused (Issue #1243). Paths are repository-relative. */ export interface SkillUpdateBlocker { code: string; path: string | null; /** Underlying per-path finding, when one exists (e.g. a local modification). */ detail: string | null; } /** Mirrors: src/lib/skills/update-plan.ts SkillUpdatePlanDto (subset) [Issue #1243]. */ export interface SkillUpdatePlan { /** Single-use token apply (#1244) will present unchanged. The CLI never inspects it. */ token: string; expiresAt: string; updatable: boolean; blockers: SkillUpdateBlocker[]; nextActionKey: string; requiresRiskAcknowledgement: boolean; riskIncreased: boolean; update: { fromVersion: string; toVersion: string; latestVersion: string | null; reasonCode: string; prerelease: boolean; }; target: { worktreeId: string; worktreeName: string; repositoryName: string; branch: string | null; headState: string; workingTreeDirty: boolean; /** `git status` could not be read; `workingTreeDirty` is the fail-safe guess (#3445). */ workingTreeUnknown?: boolean; /** Repository-relative; the server never serves a machine-absolute path. */ installRoot: string; /** Every recorded root the update rewrites, primary first (#1460). */ installRoots: string[]; }; skill: { id: string; name: string; version: string; effectiveRisk: string; riskRationale: string; declaredPermissions: string[]; scriptPaths: string[]; compatibility: { commandmate: SkillCompatibilityView; }; }; securityDiff: { risk: { from: { effective: string; }; to: { effective: string; }; increased: boolean; }; permissions: { added: string[]; removed: string[]; }; executables: { added: string[]; removed: string[]; }; scripts: { added: string[]; removed: string[]; }; changelogs: Array<{ version: string; changelog: string; }>; }; files: Array<{ path: string; change: string; }>; stats: { added: number; updated: number; removed: number; unchanged: number; localModified: number; localMissing: number; localUnknown: number; irregular: number; }; warnings: string[]; } /** Mirrors: src/app/api/worktrees/[id]/skills/[skillId]/update-plan/route.ts POST response. */ export interface SkillUpdatePlanResponse { plan: SkillUpdatePlan; } /** * Mirrors: src/app/api/worktrees/[id]/skills/[skillId]/update/route.ts POST * response [Issue #1244]. `update` is null when a replay finds no index row; * `reload` and `rollback` are absent from the narrower replay body. */ export interface SkillUpdateResponse { operation: SkillOperationResult; update: { skillId: string; fromVersion?: string; toVersion?: string; /** Present on the replay body instead of fromVersion/toVersion. */ version?: string; installRoot: string; installRoots?: string[]; pendingRoots?: string[]; } | null; reload?: { skillId: string; version: string; installRoot: string; agents: Array<{ agent: string; support: string; messageKey: string; }>; }; rollback?: { available: boolean; backup: { backupId: string; fromVersion: string; fileCount: number; verified: boolean; }; messageKey: string; }; } /** Mirrors: src/app/api/worktrees/[id]/skills/[skillId]/uninstall/route.ts POST response. */ export interface SkillUninstallResponse { operation: SkillOperationResult; uninstall: { skillId: string; version: string | null; installRoot?: string; removedFiles?: Array<{ path: string; }>; retained?: Array<{ path: string; reason: string; }>; fullyRemoved?: boolean; } | null; } /** Mirrors: src/app/api/skills/reindex/route.ts POST response [Issue #1248]. */ export interface SkillReindexResult { scannedWorktrees: number; indexed: number; removed: number; skipped: Array<{ worktreeId: string; skillId: string; /** Repository-relative root the directory was found at. */ root: string; reason: string; }>; /** Registered worktrees whose directory is gone; their rows were left untouched. */ unreadableWorktreeIds: string[]; } /** Mirrors: src/app/api/worktrees/[id]/verify/route.ts POST 202 response. */ export interface VerifyStartResponse { runId: number; } /** * Mirrors: src/lib/db/verification-db.ts VerificationRunStatus. * Declared here rather than imported so the CLI bundle stays free of the * server's better-sqlite3 dependency graph. */ export type VerificationRunStatus = 'running' | 'passed' | 'failed' | 'not_started' | 'error' | 'cancelled'; /** * Mirrors: src/lib/db/verification-db.ts VerificationGateSource (Issue #1791). * * `null` on gate rows written before migration v56, and absent entirely on * responses from a server older than #1791 — so a consumer must treat "no * source" as "unrecorded", never as "the repository declared it". */ export type VerificationGateSource = 'builtin' | 'verify.yaml' | 'contract'; /** Mirrors: src/lib/db/verification-db.ts VerificationGateStatus. */ export type VerificationGateStatus = 'running' | 'passed' | 'failed' | 'timeout' | 'skipped' | 'error'; /** One admitted change and the contract pattern that admitted it (Issue #1841). */ export interface VerificationScopeAdmission { path: string; /** * The first matching `scope.allow` pattern, in the contract's declaration * order, or one of the gate's exemption stand-ins (`(exempt: ...)`), which are * parenthesised precisely so they cannot be mistaken for a declared pattern. */ pattern: string; } /** * Machine-readable scope-gate evidence (Issue #1841). * * **Derived by the CLI, not sent by the server.** `verification_gate_results` * stores a status, an exit code and a log body and nothing else, so the gate's * report in `logTail` is the only carrier this evidence has; `verify --json` * and `verify show --json` parse it back out (see `parseScopeEvidence` in * src/cli/commands/verify.ts). Absent when the scope gate did not run, was * skipped, or errored — every one of those writes a message rather than a * report — and absent for every other gate. */ export interface VerificationScopeDetail { /** Capped at 100 entries, as the report is; see {@link totals}. */ admitted: VerificationScopeAdmission[]; /** Capped at 100 entries, as the report is; see {@link totals}. */ violations: string[]; /** * Counts as the gate itself made them, over *every* changed path. * * The lists above are the report's, so they stop at its cap; these do not. * A consumer asking "did anything fall outside the contract" must read * `totals.violations`, never `violations.length`. */ totals: { changed: number; admitted: number; violations: number; }; } /** * Machine-readable record of a gate that was re-run (Issue #1772). * * **Derived by the CLI, not sent by the server**, for the same reason * {@link VerificationScopeDetail} is: `verification_gate_results` holds one * status, one exit code and one duration per gate, and #1772 added no * migration, so the second run's numbers exist only in the `[flaky]` marker the * runner writes at the head of `logTail` (see `parseFlakyMarker` in * src/cli/utils/verify-runner.ts). * * Absent on every gate that ran once — which is every gate that did not declare * `retryOnFail: 1`, and every one of those that passed first time. */ export interface VerificationFlakyDetail { /** Runs the gate actually got. Always 2 today; `retryOnFail` maxes out at 1. */ runs: number; /** * `flaky` = failed, then passed. `fail` = failed twice, which is a gate that * was never flaky and whose retry said so. */ outcome: 'flaky' | 'fail'; /** One per run, in order. null for a run killed by a signal (`n/a`). */ exitCodes: (number | null)[]; /** One per run, in order. null when the marker's value could not be read. */ durationsMs: (number | null)[]; /** * How the run counted this gate: `pass` only when the gate declared * `flakyIsPass: true` and the outcome was `flaky`. Recorded rather than * recomputed, because the verify.yaml that decided it may have changed by the * time anyone reads the run back. */ verdict: 'pass' | 'fail'; /** The marker's own `exit=` value (`1,0`), for rendering without re-rounding. */ exit: string; /** The marker's own `duration=` value (`45.0s,44.0s`). */ duration: string; } /** * Mirrors: src/lib/db/verification-db.ts VerificationGateResult. * Dates arrive as ISO strings because the route serializes them through JSON. */ export interface VerificationGateResultView { id: number; runId: number; gateId: string; command: string; status: VerificationGateStatus; exitCode: number | null; durationMs: number | null; logTail: string | null; startedAt: string; finishedAt: string | null; /** * Where the gate was declared (Issue #1791): the repository's verify.yaml, * this delegation's execution contract, or the runner's own built-ins. */ source?: VerificationGateSource | null; /** * Whether `startedAt`/`finishedAt` bracket the execution `durationMs` counted * (Issue #1625). * * Rows written before #1625 stamped both at write time, and history is never * rewritten, so a consumer reading old runs must check this before treating * the timestamps as timing. `durationMs` was always correct and needs no such * check. Absent on responses from a server older than #1625. */ timingsMeasured?: boolean; /** * Scope-gate evidence, on the `scope` gate only (Issue #1841). * * Not part of the server payload: the CLI adds it to the object it prints so * a caller can read what the contract admitted without re-parsing prose. * Existing fields, `logTail` included, are untouched. */ scope?: VerificationScopeDetail; /** * Retry record, on a gate that was re-run (Issue #1772). Added by the CLI the * same way {@link VerificationGateResultView.scope} is, and for the same * reason: this is what a flake advisor reads instead of re-parsing the log. */ flaky?: VerificationFlakyDetail; } /** Mirrors: src/lib/db/verification-db.ts VerificationRunWithGates. */ export interface VerificationRunView { id: number; worktreeId: string; instanceId: string | null; taskId: string | null; trigger: string; status: VerificationRunStatus; baseRef: string | null; startedAt: string; finishedAt: string | null; gates: VerificationGateResultView[]; } /** Mirrors: src/app/api/worktrees/[id]/verify/runs/[runId]/route.ts GET response. */ export interface VerifyRunResponse { run: VerificationRunView; } /** * Mirrors: src/lib/db/verification-db.ts VerificationGateSummary (Issue #1593). * No `logTail` — the history listing does not carry log bodies, and declaring * one here would let `history` code read a field the server never sends. */ export interface VerificationGateSummaryView { gateId: string; status: VerificationGateStatus; exitCode: number | null; durationMs: number | null; /** Where the gate was declared (Issue #1791). */ source?: VerificationGateSource | null; /** * The gate's waits and execution, apart (Issue #3884). Absent for a gate * with neither a `mutex` nor a slot wait, and for runs recorded before it. */ timing?: VerificationGateTimingView; } /** Mirrors: src/lib/db/verification-db.ts VerificationGateTiming (seconds). */ export interface VerificationGateTimingView { queueSec: number; mutexSec: number; runSec: number; } /** Mirrors: src/lib/db/verification-db.ts VerificationRunWithGateSummaries. */ export interface VerificationRunSummaryView { id: number; worktreeId: string; instanceId: string | null; taskId: string | null; trigger: string; status: VerificationRunStatus; baseRef: string | null; startedAt: string; finishedAt: string | null; gates: VerificationGateSummaryView[]; } /** Mirrors: src/app/api/verification/runs/route.ts GET response. */ export interface VerificationRunHistoryResponse { runs: VerificationRunSummaryView[]; } /** * Mirrors: src/lib/verification/verify-config.ts VerifyGate. * * The three optional fields arrive as explicit `null`s rather than absent keys. * `mutex?: string` means "the file declared none", and over the wire an absent * key cannot be told apart from a server that forgot to send it. */ export interface VerifyConfigGateView { id: string; command: string; timeoutSec: number; mutex: string | null; retryOnFail: number | null; flakyIsPass: boolean | null; } /** Mirrors: src/lib/verification/verify-config.ts VerifyOptions. */ export interface VerifyConfigOptionsView { baseRef: string | null; skipInPrimaryCheckout: boolean; maxLogTailBytes: number; requireCommit: boolean; requireEnvClean: boolean; /** * Issue #2890: `$HOME` entry names `env-clean` does not count. Optional for * the same reason `VerifyOptions.envCleanIgnoreHomeEntries` is — a mirror, * not a looser wire contract: the loader always fills it (`[]` when unset), * so a config read off the route carries the key regardless. */ envCleanIgnoreHomeEntries?: string[]; } /** * Mirrors: src/app/api/worktrees/[id]/verify/config/route.ts GET response. * * `exists` and `error` are independent: a file that is present but invalid is * `exists: true` with `error` set, which is a different problem — and a * different fix — from no file at all. */ export interface VerifyConfigResponse { exists: boolean; /** Repository-relative path of the config, present or not. */ path: string; gates: VerifyConfigGateView[]; /** null when the file is absent or could not be read. */ options: VerifyConfigOptionsView | null; /** Gate ids a default full run executes, in the runner's own order. */ plannedGateIds: string[]; error: string | null; } /** One command the drafter found in CI and declined to turn into a gate. */ export interface VerifyConfigExclusionView { command: string; /** Mirrors DraftExclusionReason in src/lib/verification/verify-draft.ts. */ reason: string; /** Human-readable provenance (`file (job: …, step: …)`). */ source: string; } /** Mirrors: src/app/api/worktrees/[id]/verify/config/route.ts POST 201 response. */ export interface VerifyConfigDraftResponse { created: boolean; path: string; gates: VerifyConfigGateView[]; excluded: VerifyConfigExclusionView[]; /** Repository-relative files the scan read. */ scanned: string[]; } /** Mirrors: src/lib/db/tasks-db.ts TaskStatus. */ export type TaskStatus = 'pending' | 'running' | 'waiting_input' | 'verifying' | 'succeeded' | 'failed' | 'not_started' | 'cancelled'; /** * Mirrors: src/lib/tasks/contract-parser.ts TaskContract. * The snapshot taken at send time, as stored in `tasks.contract_json`. */ export interface TaskContractView { version: number; title: string; goal: string; scope: { allow: string[]; deny: string[]; }; verify: { gates: string[] | null; /** * Gates this contract declares for itself (Issue #1791). Absent on * responses from a server older than #1791, and on tasks recorded before * it — `contract_json` is replayed verbatim, never re-validated. */ gateDefinitions?: Array<{ id: string; command: string; timeoutSec: number; /** Machine-wide lock the gate holds while it runs (Issue #1771). */ mutex?: string; }>; }; autoYes: { mode: string | null; allowPromptTypes: string[]; denyPatterns: string[]; }; success: { requireWorkEvidence: boolean; requireScopeClean: boolean; }; } /** * Mirrors: src/lib/db/tasks-db.ts Task. * Dates arrive as ISO strings because the route serializes them through JSON. */ export interface TaskView { id: string; worktreeId: string; cliToolId: string; instanceId: string | null; title: string; goal: string; contractPath: string | null; contract: TaskContractView; status: TaskStatus; lastVerificationRunId: number | null; createdAt: string; updatedAt: string; startedAt: string | null; finishedAt: string | null; } /** Mirrors: src/app/api/worktrees/[id]/tasks/route.ts POST response. */ export interface TaskCreateResponse { task: TaskView; /** Contract preamble + goal, composed server-side; this is what gets sent. */ message: string; /** A running session with no evidence of its role, which the settings give one (Issue #4132). Absent otherwise and from older servers. */ roleWarning?: string; } /** Mirrors: src/app/api/worktrees/[id]/tasks/route.ts GET response. */ export interface TaskListResponse { tasks: TaskView[]; } /** Mirrors: src/app/api/tasks/[taskId]/route.ts GET response. */ export interface TaskDetailResponse { task: TaskView; lastVerificationRun: VerificationRunView | null; } /** * One file in `structuredEvents.sessionDiff` (Issue #2043). * * Mirrors: src/lib/hooks/sources/opencode/client.ts OpencodeFileDiff. * * `file`, `patch` and `status` are nullable because opencode's own OpenAPI * marks only `additions` and `deletions` required on `SnapshotFileDiff` * (1.18.22, `GET /doc`). */ export interface AgentSessionDiffFile { /** Repository-relative path, or null when the agent did not name one. */ file: string | null; /** Unified diff for this file, or null. */ patch: string | null; additions: number; deletions: number; /** `added` | `deleted` | `modified`, or null. */ status: 'added' | 'deleted' | 'modified' | null; } /** * One session an interrupt actually reached (Issue #2101). * * Mirrors: src/app/api/worktrees/[id]/interrupt/route.ts InterruptResult. * * `cliToolId` is `string` rather than a union for the same reason * {@link WorktreeItem.cliToolId} is: the CLI bundle keeps its own copy of the * API shapes, and a newer daemon naming a tool this build has never heard of * must print through rather than fail to parse. */ export interface InterruptedSession { cliToolId: string; /** Primary instances carry `instanceId === cliToolId` (Issue #868). */ instanceId: string; /** tmux session name, e.g. `mcbd-opencode-`. */ sessionName: string; } /** * Mirrors: src/app/api/worktrees/[id]/interrupt/route.ts POST 200 response * (Issue #2101). * * The route answers 404 `{ error: 'No active sessions found' }` instead of a * 200 with an empty list, so `interrupted` is never empty on this shape — see * `src/cli/commands/interrupt.ts` for how that 404 becomes * {@link InterruptExitCode.NO_ACTIVE_SESSIONS} rather than a generic * "resource not found". */ export interface InterruptResponse { success: boolean; /** e.g. `Interrupt sent to 1 session(s)`. */ message: string; interrupted: InterruptedSession[]; } /** * Mirrors: `RelayEndpoint` in src/lib/relay/types.ts. * * `instanceId` is always the RESOLVED id — the primary instance's id is its * tool's id (#868) — because that is the only form any other route accepts. */ export interface RelayEndpointResponse { worktreeId: string; instanceId: string; } /** * Mirrors: `SessionRelay` in src/lib/relay/types.ts. * * `state` is `string` rather than a union for the reason every other id on this * page is: the CLI bundle keeps its own copy of the API shapes, and a newer * daemon naming a state this build has never heard of must print through rather * than fail to parse. */ export interface RelayView { id: string; /** The session that asked, and is owed the answer. */ from: RelayEndpointResponse; /** The session that was asked. */ to: RelayEndpointResponse; state: string; hops: number; sentRequestId: string | null; pendingKind: string | null; /** Epoch ms. */ createdAt: number; updatedAt: number; expiresAt: number; deliveredAt: number | null; /** * Issue #3957. Optional: a server older than the binding sends none of these. * Strings rather than unions, for the reason `state` is one. */ bindMode?: string; sendState?: string | null; inputBoundaryAt?: number | null; boundaryKind?: string | null; turnOpenAtSend?: boolean | null; obsState?: string | null; holdReason?: string | null; overlap?: string | null; /** * Issue #4064. Optional: an older server sends none. Null while the payload * is queued or there is none. */ deliveryHold?: RelayDeliveryHoldResponse | null; /** * Issue #4105: what the last delivery attempt of the current payload * stopped for. Absent on an older server; null = no observation in this * server process (NOT "deliverable"). Never part of `held` / `heldCount`. */ lastDeliveryBlock?: RelayLastDeliveryBlockResponse | null; } /** * Mirrors: `RelayLastDeliveryBlock` in src/lib/relay/types.ts (Issue #4105). * Strings rather than unions, for the reason `RelayView.state` is one. */ export interface RelayLastDeliveryBlockResponse { /** `prompt_waiting` | `generating` | `session_stopped` | `foreign_session`. */ reason: string; /** The payload it was for: `reply` | `prompt` | `expired`. */ kind: string; payloadId: string | null; /** Epoch ms of the attempt that observed it. */ observedAt: number; } /** * Mirrors: `RelayDeliveryHold` in src/lib/relay/types.ts (Issue #4064). * Strings rather than unions, for the reason `RelayView.state` is one. */ export interface RelayDeliveryHoldResponse { /** `attempting` | `uncertain`. */ state: string; payloadId: string | null; /** * Issue #4082: the delivery attempt that holds it — what `relays resolve * --attempt` names. Absent on a server older than #4082; not the send * binding's attempt. */ attemptId?: string | null; kind: string | null; reason: string | null; at: number | null; /** The requester's pane to look at before anything else. */ checkCommand: string; } /** Mirrors: `RelayCounts` in src/lib/relay/types.ts. */ export interface RelayCountsResponse { pending: number; delivered: number; prompt: number; expired: number; cancelled: number; } /** Mirrors: src/app/api/relays/route.ts GET 200 response. */ export interface RelayListResponse { /** Open relays this session must answer. Empty unless `instance` was given. */ owed: RelayView[]; /** Open relays this session is waiting on. Empty unless `instance` was given. */ awaiting: RelayView[]; /** Every open relay in scope, whichever end it belongs to. */ open: RelayView[]; /** * Issue #4064: relays in scope, open or closed, whose payload is under a * delivery hold. Absent on an older server. */ held?: RelayView[]; /** * Issue #4193: closed relays in scope (by the requester) whose payload — the * expiry notice, in practice — is still undelivered and whose last delivery * attempt stopped (`lastDeliveryBlock` set). Not in `open` / `awaiting` and * not in `counts` / `heldCount`. Absent on an older server. */ closedBlocked?: RelayView[]; counts: RelayCountsResponse; /** * Issue #4082: how many payloads in scope are held as `uncertain` now — * open relays or closed, once each, not narrowed by `days`, and not one of * the per-state `counts` (never added to them). Absent on an older server: * print nothing for it rather than 0. */ heldCount?: number; } /** Mirrors: src/app/api/relays/route.ts POST 201 response. */ export interface RelayCreateResponse { relay: RelayView; /** Issue #3957: `bound` when the server honoured `bind: true`; absent on an older server. */ bindMode?: string; } /** * Issue #4437: the tool policy refusal's types live in `./tool-policy-responses`, so * `utils/tool-policy-failure` (read by `api-client`) can name them without this * module's `lib/session` / `lib/polling` imports entering the client's closure * (`tests/unit/updates/agent-update-not-in-pane-2069.test.ts`). Re-exported here. */ export type { ToolPolicyDeniedResponse, ToolPolicyDetailResponse } from './tool-policy-responses'; /** Mirrors: src/app/api/relays/[relayId]/route.ts GET 200 response (Issue #3957). */ export interface RelayGetResponse { relay: RelayView; } /** Mirrors: src/app/api/relays/[relayId]/cancel/route.ts POST 200 response. */ export interface RelayCancelResponse { relay: RelayView; } /** Mirrors: src/app/api/relays/[relayId]/resolve/route.ts POST 200 response (Issue #4082). */ export interface RelayResolveResponse { relay: RelayView; /** `confirm` | `retry` | `discard`. */ action: string; /** `retry`: queued for delivery again — not delivered yet. */ requeued: boolean; /** A reply waiting behind the resolved prompt notice was queued in its place. */ promoted: boolean; /** * Issue #4082: the relay was closed, and a reply that waited behind the * settled notice was discarded (never delivered). Absent on an older server. */ replyDiscarded?: boolean; } //# sourceMappingURL=api-responses.d.ts.map