One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.
// SITREP report contract.
//
// What a reporter POSTs to /api/fleet/report (a Report) and gets back (a ReportReply), the asks and answers of responding,
// the view types the UI reads, and the hand-written validator the server runs on every untrusted body. It covers both
// providers (Claude and Codex): Codex ask shapes, observe-only sessions, liveness and edit facts, machine views and agent
// messages.
//
// No imports: the Claude reporter carries a byte-identical copy at mod/claude-reporter/hooks/protocol.ts, kept equal by a
// `cmp` check. Only erasable TypeScript is used (no enums, no parameter properties), so a loader that
// strips types can run it.
// ---- Product constants ----------------------------------------------------------------------
/** The request header that carries the admin secret on every reporter call. */
export const TOKEN_HEADER = 'X-Sitrep-Token';
/**
* The request header that names the machine (its MACHINE_ID) on Claude Code's own telemetry, OTLP/HTTP JSON logs POSTed to
* /api/fleet/v1/logs with TOKEN_HEADER, whose records name no machine. Claude usage comes from those records, not from reports.
*/
export const MACHINE_HEADER = 'X-Sitrep-Machine';
/**
* A session's id on the server (SessionView.id): the id its own harness gave it (Report.session.id) at the machine it runs on
* (Report.machine.id), so the same conversation open on two machines is two sessions. Every route that names a session
* takes it, the reporters' too: PUT /api/fleet/sessions/:id/asks/:askId, GET …/asks/:askId/answer, POST …/asks/:askId/close and
* POST /api/fleet/sessions/:id/deliveries/:deliveryId/result.
*/
export const sessionKey = (nativeId: string, machineId: string): string => `${nativeId}@${machineId}`;
/**
* The coding agent (harness) a session runs in, by name: any name PROVIDER_NAME matches, such as `hermes`. The two the
* dashboard has behaviour of its own for are `Provider`; every other name takes the generic path: no resume command, and its
* model's family by model id. Every harness's cost is its usage priced, booked the same way. The UI shows it with a generic logo
* and its name.
*/
export type ProviderName = string;
/** Lower-case letters, digits and hyphens, a letter first, at most 32 characters. */
export const PROVIDER_NAME = /^[a-z][a-z0-9-]{0,31}$/;
/** The providers with behaviour of their own. */
export type Provider = 'claude' | 'codex';
export const PROVIDERS: readonly Provider[] = ['claude', 'codex'];
export const isKnownProvider = (p: ProviderName): p is Provider => (PROVIDERS as readonly string[]).includes(p);
/**
* The reporter that produces a provider's reports is always named `<provider>-reporter` (`reporterOf`), and each the server knows
* has its own supported version range (compat.ts); one it has no range for is accepted, its compatibility unknown.
*/
export type ReporterName = 'claude-reporter' | 'codex-reporter';
export const reporterOf = (provider: ProviderName): string => `${provider}-reporter`;
/** The orchestrator's own loop key in `watch` and the activity route. Agent ids never start with `@`. */
export const MAIN_LOOP = '@orchestrator';
// ---- Report building blocks -----------------------------------------------------------------
/**
* Claude Code's five effort levels, which the effort meter draws as bars. On the wire `effort` is any string: a
* Codex value outside these five is shown as text in the meter's place.
*/
export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'] as const;
export type Effort = (typeof EFFORTS)[number];
/** Where an agent is in its life: waiting to start, at work, or finished in one of three ways. */
const AGENT_STATUSES = ['queued', 'running', 'done', 'failed', 'aborted'] as const;
export type AgentStatus = (typeof AGENT_STATUSES)[number];
/** What a loop's failure is put down to (Failure.class). */
export type FailureClass = 'Tool error' | 'Blocked by permission' | 'Model API error' | 'Refusal' | 'Context window exhausted' | 'Aborted' | 'Unknown';
/** `edit` is a file edit with its absolute path; `message` is one loop messaging another. */
export type EventKind = 'start' | 'end' | 'spawn' | 'skill' | 'done' | 'fail' | 'blow' | 'compact' | 'plan' | 'wait' | 'note' | 'edit' | 'message';
/** Tokens by kind. `cacheRead` and `cacheWrite` are prompt tokens read from and written to the provider's prompt cache. */
export type TokenCounts = Record<'input' | 'output' | 'cacheRead' | 'cacheWrite', number>;
/** Tokens with cache writes split by lifetime: `cacheWrite` holds the 5-minute writes, `cacheWrite1h` the 1-hour ones (0 when not split). */
export type UsageTokens = TokenCounts & { cacheWrite1h: number };
/**
* What one model used, for the server to price against its table. `tier: 'long'` marks a long-context request: for
* Claude, a prompt (input, cache reads and cache writes together) over 100,000 tokens; for Codex, input over 272,000 tokens,
* where OpenAI's long-context pricing starts. `tier: 'fast'` marks a request made in Claude's fast mode, whose price is one
* rate at any prompt length.
*/
const USAGE_TIERS = ['std', 'long', 'fast'] as const;
export interface ModelUsage {
model: string;
tier: (typeof USAGE_TIERS)[number];
tokens: UsageTokens;
}
/** A loop's progress through its steps: how many are done, and out of how many when that is known. */
export interface StepCount {
done: number;
total: number | null;
}
/** How much of a loop's context window is in use. A value nobody knows is null, never 0. */
export type ContextFill = Record<'tokens' | 'window' | 'percent', number | null>;
/** The repository at the session's working directory. */
export interface GitInfo {
/** The branch checked out, or the short commit when HEAD is detached. */
branch: string | null;
detached: boolean;
/** Whether the checkout is a linked worktree, and its top directory when it is. */
isWorktree: boolean;
worktreePath: string | null;
/** Commits ahead of and behind the upstream, and how many paths have changes. */
ahead: number;
behind: number;
dirty: number;
}
/** How a file changed. */
const FILE_STATUSES = ['added', 'modified', 'deleted', 'renamed'] as const;
export type FileStatus = (typeof FILE_STATUSES)[number];
/** One changed file. Its line counts are null when it is binary; `from` is where a renamed file used to be. */
export interface ChangedFile {
path: string;
status: FileStatus;
added: number | null;
removed: number | null;
from: string | null;
}
/**
* What the session has changed in its repository: up to 200 of the changed files, and line totals over all of them. `since` is
* the base they are counted from: `start`, the commit HEAD was on when the session began; `upstream`, the merge base with the
* upstream once that commit is gone; `worktree`, HEAD itself.
*/
export interface FilesReport {
files: ChangedFile[];
total: number;
added: number;
removed: number;
since: (typeof FILES_SINCE)[number];
}
const FILES_SINCE = ['start', 'upstream', 'worktree'] as const;
/**
* One window of the provider plan's usage limits. Claude's come as `session.usage().rateLimits` has them. Codex's
* are named by length, `five_hour` for 300 minutes, `seven_day` for 10,080 and `<n>m` otherwise, with `used_percent` as
* `percentUsed` and `resets_at` as an ISO `resetsAt`.
*/
export interface RateLimit {
kind: string;
percentUsed: number;
resetsAt: string | null;
/**
* When the reading was taken (ISO). Claude: when the model response whose headers carried these windows came back (the
* reporter's last `turn.step` with usage); null until one comes back after the reporter starts, reloads or the session clears.
* Codex: the timestamp of the `token_count` record it came from. Absent from older reporters (before claude-reporter 0.2.0,
* codex-reporter 0.3.0).
*/
measuredAt?: string | null;
}
/** Where a plan step stands. */
const STEP_STATES = ['pending', 'active', 'done', 'blocked'] as const;
/** One step of a plan. `activeText` is its wording while under way (Claude's `activeForm`); the owner is the agent it is matched to. */
export interface PlanStep {
id: string;
text: string;
activeText: string | null;
state: (typeof STEP_STATES)[number];
ownerAgentId: string | null;
ownerLabel: string | null;
}
/**
* Where a plan came from: Claude Code's task tools (`TaskCreate`, `TodoWrite`), the Claude reporter's own plan tool
* (`reporter_plan`), or Codex's latest `update_plan` call (`codex-plan`; its snake_case statuses map `pending`→`pending`,
* `in_progress`→`active`, `completed`→`done`).
*/
export type PlanSource = 'TaskCreate' | 'TodoWrite' | 'reporter_plan' | 'codex-plan';
/** A session's plan: its title when it has one, where it came from, and its steps in order. */
export interface Plan {
title: string | null;
source: PlanSource;
steps: PlanStep[];
}
/**
* Why a loop failed, as its reporter makes it out: the class and when; the call blamed, by tool name, a one-line form of the call
* and its exit code; the last lines of its output; up to five facts the reporter saw, never guesses (a call failing again, a
* file read over and over, blowouts, a denial); and `retriedAs`, which today's reporters always send as null.
*/
export interface Failure {
class: FailureClass;
at: number;
tool: string | null;
call: string | null;
exitCode: number | null;
outputTail: string[];
evidence: string[];
retriedAs: string | null;
}
/**
* The main loop's own work, read as the AgentReport fields of the same names are; what the agents it started did is theirs, not
* counted here. `steps.done` counts the model requests the main loop has made.
*/
export interface LoopReport {
skills: string[];
lastTool: string | null;
toolCalls: number;
toolCounts: Record<string, number>;
steps: StepCount & { total: null };
}
/** What an activity entry shows: a tool call, the model's text, or `reasoning`, kept for its thinking, which reporters never send. */
const ACTIVITY_KINDS = ['tool', 'text', 'reasoning'] as const;
export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
/**
* One entry of a loop's live activity feed: a tool call (its name, a space, a short summary of its arguments) or the text the
* model wrote in one step, redacted and cut to 300 characters on the machine. Sent only with the reporter's `activityFeed`
* option on and only for a loop the last reply listed in `watch`; the server holds entries in memory under the viewer's lease.
* The optional fields describe a Bash (Codex: shell) call and appear only on a `tool` entry. A call's output is never sent:
* there are no output fields, because they would ship command output off the machine.
*/
export interface ActivityEntry {
at: number;
kind: ActivityKind;
text: string;
/** The call's id, so its result can be matched to an entry that went out while the call ran. */
id?: string;
/** The whole command, redacted, line breaks kept, cut to 20,000 characters behind a visible marker (`commandCut`). */
command?: string;
commandCut?: boolean;
/**
* How the call ended, once `done`: `failed` when it failed, with or without an `exitCode`, which is sent only when the reporter
* reads it from structured data, never parsed out of output text.
*/
done?: boolean;
failed?: boolean;
exitCode?: number;
}
/** How an agent came to be, and where its effort figure comes from: asked for, seen in its requests, taken from its parent, or not known. */
const AGENT_KINDS = ['subagent', 'fork', 'teammate'] as const;
const EFFORT_SOURCES = ['requested', 'observed', 'inherited', 'unknown'] as const;
/**
* One agent working under a session's main loop: a Claude subagent, fork or teammate, or a Codex child thread, which is sent as a
* `subagent` with the child thread's id as `id`, its `agent_role` as `type` and its `agent_nickname` as `name`.
*/
export interface AgentReport {
/** Its id, and the agent that started it (null when the main loop did). */
id: string;
parentId: string | null;
/** What sort of agent it is, its type and name as the harness gives them, and the task it was given. */
kind: (typeof AGENT_KINDS)[number];
type: string;
name: string | null;
description: string;
/** Its model and effort, and where the effort figure comes from. */
model: string | null;
effort: string | null;
effortSource: (typeof EFFORT_SOURCES)[number];
status: AgentStatus;
startedAt: number;
endedAt: number | null;
context: ContextFill;
/**
* Its own tokens per model and tier, which the server prices; absent while the reporter does not know them. Not read from a
* Claude report: a Claude agent's usage comes from Claude Code's own telemetry (MACHINE_HEADER).
*/
usageByModel?: ModelUsage[];
/**
* Not read, and kept only so that older reports still validate: the server prices `usageByModel`. Reporters send
* `costUsdEst` as null and may leave `tokens` out.
*/
costUsdEst: number | null;
tokens?: TokenCounts;
/** The skills it used, its latest tool, its tool calls, and its finished calls per tool name. */
skills: string[];
lastTool: string | null;
toolCalls: number;
toolCounts: Record<string, number> | null;
steps: StepCount | null;
/** This loop's context blowouts so far; null when the reporter cannot know (Codex hooks not active). */
blowouts: number | null;
/**
* Consecutive failed tool calls in this loop, reset to 0 by a successful tool result; null when the reporter cannot observe
* tool exit status (a Codex thread without active hooks, in legacy history mode). The server derives errored from it.
*/
toolFailures: number | null;
failure: Failure | null;
/** Excerpts of its task prompt and final answer, at most LIMITS.excerpt characters each. */
promptExcerpt: string;
answerExcerpt: string | null;
/** The whole task prompt and final answer, redacted, line breaks kept; only with the `fullPrompts` option, each sent once. */
promptText?: string;
answerText?: string;
/** The last 20 activity entries, oldest first, while a viewer watches this agent. */
activity?: ActivityEntry[];
/** The last hook, turn-step, tool or item event of this loop (epoch ms), never a heartbeat; null before the first. */
lastActivityAt: number | null;
/** A tool call of this loop has started and not finished. */
toolOpen: boolean;
}
/**
* One activity event, acknowledged by count in the reply and stored once by `id` (`sessionId:agentId|main:kind:t:n`).
*
* `data` is free-form within 4,096 characters, except for the events whose data the server reads:
* - an `edit` event carries `{ path }`, the absolute path of the file the loop edited (Claude Edit/Write/MultiEdit/NotebookEdit,
* Codex fileChange/apply_patch paths). Paths only, never contents: the validator keeps nothing else.
* - a `message` event is one loop sending a message to another loop of the same session while both run (Claude Code's agent-team
* SendMessage, Codex's send_input). `agentId` is the sender (null for the main loop), `text` the redacted message cut to
* LIMITS.text, and `data` is `{ to, toName }`: the recipient's agent id (null for the main loop) and its name as the harness
* gives it. `to` is absent when the reporter cannot tie the name to a loop of this session; then no link is drawn.
* - a `fail` event for a turn that ended on a model API failure carries `category`, the provider's own name for it (Claude
* `classic.StopFailure`: `rate_limit`, `overloaded`, `billing_error`, …; Codex: the failed turn's `codex_error_info`, or
* `system_error` for a daemon thread in that state). The main loop's (`agentId` null) drives the errored state.
* - a `blow` event (a context blowout) carries `{ kind: string; tokensBefore: number | null; tokensAfter: number | null }`, `kind`
* being one of `window-exceeded`, `server-compaction` or `auto-compact`. Only a `blow` event with a non-empty string
* `kind` adds an entry to the session's blowout log; the counts are the loops' own `blowouts`.
*/
export interface ActivityEvent {
id: string;
t: number;
kind: EventKind;
agentId: string | null;
text: string;
data: Record<string, unknown> | null;
}
/** What a session idle between turns still waits on: background work in flight, or a scheduled wake-up. */
const BACKGROUND_KINDS = ['shell', 'agent', 'monitor', 'workflow', 'wakeup', 'other'] as const;
export type BackgroundKind = (typeof BACKGROUND_KINDS)[number];
/** One piece of background work: its kind, a short description (never a whole shell command), and its status. */
export interface BackgroundTask {
type: BackgroundKind;
description: string;
status: string;
}
/** The background work a session waits on, and `wakeAt`, the epoch ms of its next wake-up (null when none or not known). */
export interface BackgroundWait {
tasks: BackgroundTask[];
wakeAt: number | null;
}
/** Where a session stands as its reporter says, and what it waits on its owner for. */
const SESSION_STATUSES = ['running', 'waiting', 'done'] as const;
const WAIT_REASONS = ['permission', 'input', 'idle'] as const;
/** One session as its reporter sees it: the main loop's state and work, and the usage of the whole session. */
export interface SessionReport {
/** The native session id (Claude's session id, Codex's root thread id), and the display name (Codex: `Thread.name` when known). */
id: string;
name: string;
status: (typeof SESSION_STATUSES)[number];
/** What the owner is waited on for: a permission, an input (a question or a plan), or `idle` (the turn ended and nothing
* was asked; not counted as needing the owner). */
waitReason: (typeof WAIT_REASONS)[number] | null;
/** What it waits on, such as `Bash(npm test)` or `Shell(pnpm test)`; at most 160 characters. */
waitNote: string | null;
/** Why it ended, and the id to resume it by; null resumes by `id`. */
endReason: string | null;
resumeId: string | null;
startedAt: number;
/** Where it runs: the working directory, the project root and repository name when known, and the repository's state. */
cwd: string;
projectRoot: string | null;
repoName: string | null;
git: GitInfo | null;
model: string | null;
effort: string | null;
context: ContextFill;
/**
* Tokens per model and tier over the session's whole life, agents included, from the harness's own record; the server prices
* them, and each rise is spend. Absent while the reporter does not know them yet. Not read from a Claude report:
* Claude usage comes from Claude Code's own telemetry, each request counted once (MACHINE_HEADER).
*/
usageByModel?: ModelUsage[];
/**
* Not read, and kept only so that older reports still validate: the server prices `usageByModel`. Reporters send
* `costUsd` as null and may leave `tokens` out.
*/
costUsd: number | null;
tokens?: TokenCounts;
rateLimits: RateLimit[];
/** The main loop's blowouts so far; null when the reporter cannot know (Codex hooks not active). */
blowouts: number | null;
/** Consecutive failed tool calls in the main loop, reset to 0 by a successful tool result; null when not observable. */
toolFailures: number | null;
/**
* Codex only: whether our hooks are active for this thread — their `hooks/list` trust state where a daemon runs, else whether a
* hook event has arrived for the thread. While false, hook-only facts are unknown.
*/
hooksActive?: boolean;
/** Its plan, the main loop's own work, and what it has changed in its repository. */
plan: Plan | null;
loop: LoopReport | null;
files: FilesReport | null;
/** Whether any client is attached; false for a background session left running; null when unknown (Codex never knows). */
attached: boolean | null;
/** Background work the session is idle on; absent when there is none. */
background?: BackgroundWait | null;
/** The reporter's `activityFeed` option, and the main loop's last 20 activity entries while a viewer watches the orchestrator. */
activityFeed?: boolean;
activity?: ActivityEntry[];
/** Whether and how far the session can be answered from the dashboard. */
respond?: RespondInfo;
/** Its open asks, 8 at most, sent only while the server's last reply said `respond: true`. */
asks?: Ask[];
/** The session this one continues after a Claude `/clear`. */
clearedFrom?: string | null;
/** The last hook, turn-step, tool or item event of the main loop (epoch ms), never a heartbeat; null before the first. */
lastActivityAt: number | null;
/** A tool call of the main loop has started and not finished. */
toolOpen: boolean;
}
/** A machine id: 1 to 32 letters, digits, `-` or `_`, so `sessionKey`'s `@` splits it off unambiguously. */
export const MACHINE_ID = /^[A-Za-z0-9_-]{1,32}$/;
/** The machine a session runs on: its short host name, the random id both reporters share, and its OS as read. */
export interface MachineInfo {
name: string;
/** 1 to 32 letters, digits, `-` or `_`; kept in `sitrep-machine-id` in the Claude config directory. */
id: string;
/** Free text such as `macOS 27.0.1`, never parsed; null when it could not be read. */
os: string | null;
}
export interface Report {
v: 1;
sentAt: number;
provider: ProviderName;
/**
* `name` is `<provider>-reporter` (`reporterOf`). `engineVersion` is the version of the engine running the session (Claude
* Code, the Codex that hosts the thread, or the other harness).
* `hostSurface` is where the session runs, as SessionView.hostSurface describes it. `build` is the commit of a reporter dev
* build, absent for a release. `daemonVersion` is the Codex managed app-server daemon's version on the machine, from the
* codex-reporter only; absent when no daemon runs.
*/
reporter: {
name: string;
version: string;
engineVersion: string | null;
hostSurface: string | null;
build?: string | null;
daemonVersion?: string | null;
};
session: SessionReport;
/** Every agent seen this session, running or finished. */
agents: AgentReport[];
/** The events not yet acknowledged. */
events: ActivityEvent[];
machine: MachineInfo;
}
/** "1 shell, 1 agent": a background wait counted by kind, as the activity feed's wait row reads it. */
export function backgroundSummary(wait: BackgroundWait): string {
const counts = new Map<string, number>();
for (const task of wait.tasks) counts.set(task.type, (counts.get(task.type) ?? 0) + 1);
return Array.from(counts, ([kind, n]) => `${String(n)} ${kind}`).join(', ');
}
/** A session that waits, but only on background work or a wake-up: nothing is asked of its person. */
export const idleOnBackground = <T extends Record<'status', string> & Pick<SessionReport, 'background'> & { waitReason: string | null }>(s: T): s is T & { background: BackgroundWait } =>
s.status === 'waiting' && s.waitReason === null && s.background != null;
// ---- Responding -------------------------------------------------------------
/** The reporter's `respond` option: how far the session takes answers from the dashboard, from none to every kind. */
export const RESPOND_LEVELS = ['off', 'questions', 'questions-and-plans', 'everything'] as const;
export type RespondLevel = (typeof RESPOND_LEVELS)[number];
/** Each kind of answer a session can take. */
export const RESPOND_KINDS = ['question', 'plan-approve', 'plan-feedback', 'permission', 'message', 'command'] as const;
export type RespondKind = (typeof RESPOND_KINDS)[number];
/**
* Why a kind the level allows is missing from `accepts`: PermissionRequest hooks do not run here (drops plan-approve and
* permission), a `claude -p` run (drops everything), or a Codex thread the reporter cannot answer — a desktop-app local
* thread, an excluded CLI run, `codex exec` — which the UI words as "Answer in its terminal" (drops everything).
* `desktop-app` comes beside `observe-only` for a Codex desktop-app local thread: observe-only; it is answered in the Codex
* app, which the UI words as "Answer in the Codex app". It never adds to `accepts`.
*/
export type RespondLimit = 'no-permission-hooks' | 'not-interactive' | 'observe-only' | 'desktop-app';
export const RESPOND_LIMIT_NAMES: readonly RespondLimit[] = ['no-permission-hooks', 'not-interactive', 'observe-only', 'desktop-app'];
/** Report.session.respond. */
export interface RespondInfo {
level: RespondLevel;
/** What the session takes now: the level's kinds less what `limits` removes; empty while the activityFeed option is off. */
accepts: RespondKind[];
limits: RespondLimit[];
}
/** What each level adds to the one below it: questions and messages, then plans, then permissions and commands. */
const ASKED: readonly RespondKind[] = ['question', 'message'];
const PLANS: readonly RespondKind[] = [...ASKED, 'plan-approve', 'plan-feedback'];
/** The kinds each level allows: all those of the level below, and its own. */
export const LEVEL_KINDS: Readonly<Record<RespondLevel, readonly RespondKind[]>> = {
off: [],
questions: ASKED,
'questions-and-plans': PLANS,
everything: [...PLANS, 'permission', 'command'],
};
/** The kinds a level allows once the limits are applied: none while the reporter's activityFeed option (`feedOn`) is off. */
export function acceptsFor(level: RespondLevel, limits: readonly RespondLimit[], feedOn: boolean): RespondKind[] {
if (!feedOn || limits.includes('not-interactive') || limits.includes('observe-only')) return [];
if (!limits.includes('no-permission-hooks')) return [...LEVEL_KINDS[level]];
return LEVEL_KINDS[level].filter((kind) => kind !== 'plan-approve' && kind !== 'permission');
}
/** What an ask waits for: answers to questions, a verdict on a plan, or leave to run a tool. */
const ASK_KINDS = ['question', 'plan', 'permission'] as const;
export type AskKind = (typeof ASK_KINDS)[number];
/** One choice a question offers: its label, what it means, and its preview when it has one. */
export interface AskOption {
label: string;
description: string;
preview: string | null;
}
/** One question. Claude: 1 to 4 options. Codex: 0 to 4 (`options` null in the request gives none), `multiSelect` false; any other provider 0 to 4. */
export interface AskQuestion {
question: string;
header: string;
options: AskOption[];
multiSelect: boolean;
/** Whether a typed answer is taken. Claude: true. Codex: true only when the native question has `isOther` or no options. */
allowsText: boolean;
}
/** The answer to one question, matched by position: the indexes of the options chosen, typed text, or null when skipped. */
export type QuestionAnswer = { options: number[] } | { text: string } | null;
/**
* Something a session waits on its person for that the dashboard can answer, redacted and cut to RESPOND_LIMITS with a visible
* marker on the machine. Its id is the Claude tool call's `tool_use_id`, or the Codex request's `itemId` with `:<approvalId>`
* after it when the request has one. Codex command, file-change and permissions approvals are `permission` asks and
* `requestUserInput` is a `question` ask. A Codex request holding an `isSecret` question is never announced as an
* ask: the reporter reports the session as `waitReason: 'input'` with a `waitNote` saying to answer in its terminal.
* The UI reads `allowsReply`, `allowsText` and `tool.denyReason`; it never infers them from the provider.
*/
export interface Ask {
id: string;
kind: AskKind;
/** The loop that asked (a subagent or Codex child thread id; null for the main loop), and when. */
agentId: string | null;
openedAt: number;
/** Whether a message can be sent in place of an answer. Claude: true. Codex: false. */
allowsReply: boolean;
/** What is asked, by kind: the questions, the plan and its file, or the tool below. */
questions?: AskQuestion[];
plan?: { text: string; filePath: string | null };
/**
* The tool and its arguments (Codex: `Shell` with command, cwd and reason; `Edit` with `changes`, each path with its operation,
* and the redacted `patch`). `cut` when anything was cut off, redacted or is missing, and then only Deny is offered. `denyReason` says whether a Deny can carry a reason: Claude Code, yes;
* Codex `decline`, no, so the reason box is hidden.
*/
tool?: { name: string; input: Record<string, unknown>; cut: boolean; denyReason: boolean };
}
/** How much responding carries: list lengths, characters per text, and how long an answer request is held. */
export const RESPOND_LIMITS = {
/** Asks open at once per session, questions per ask, options per question, and messages and commands waiting per session. */
asks: 8,
questions: 4,
options: 4,
deliveries: 20,
/** Characters of an ask's content. */
question: 1000,
header: 40,
label: 200,
description: 1000,
preview: 4000,
plan: 40_000,
toolInput: 20_000,
/** Typed answers, deny reasons, and the answer summary a close carries. */
answer: 2000,
/** Messages, replies sent instead of an answer, and plan feedback. */
message: 20_000,
/** The longest a held answer request waits, in seconds (the Claude mod's `$.http.fetch` gives up at 30). */
holdSeconds: 20,
} as const;
/** Each kind of delivery; a `reply` is a message the owner sends in place of an answer to the ask. */
export const DELIVERY_KINDS = ['question', 'reply', 'plan-approve', 'plan-feedback', 'allow-once', 'deny', 'message', 'command'] as const;
export type DeliveryKind = (typeof DELIVERY_KINDS)[number];
/** The permission mode a session continues in once the dashboard approves its plan. */
export const PLAN_MODES = ['auto', 'acceptEdits', 'default'] as const;
export type PlanMode = (typeof PLAN_MODES)[number];
/** The two commands the dashboard can send. Codex takes `compact`; it refuses `clear`, which has no native equivalent. */
export type DashboardCommand = 'clear' | 'compact';
export const DASHBOARD_COMMANDS: readonly DashboardCommand[] = ['clear', 'compact'];
/** One answer, message or command from the dashboard, as the server hands it to the reporter. */
export interface Delivery {
id: string;
kind: DeliveryKind;
/** The ask it answers (null for a message or a command), who sent it (always `Admin` in single-owner mode), and when. */
askId: string | null;
by: string;
at: number;
/** What it carries, by kind: the question answers, the mode an approved plan goes on in, the text, or the command. */
answers?: QuestionAnswer[];
mode?: PlanMode;
text?: string;
command?: DashboardCommand;
}
/** What became of a delivery, by its reporter's word. */
export const DELIVERY_RESULTS = ['took', 'queued', 'not-taken', 'refused', 'closed'] as const;
export type DeliveryResult = (typeof DELIVERY_RESULTS)[number];
/** How an ask closed without the dashboard's answer: answered in its terminal, closed by itself, or its session ended. */
export const ASK_CLOSE_OUTCOMES = ['terminal', 'closed', 'ended'] as const;
export type AskCloseOutcome = (typeof ASK_CLOSE_OUTCOMES)[number];
/** A reporter's word that an ask closed (POST …/asks/:askId/close): how, and when. */
export interface AskClose {
outcome: AskCloseOutcome;
at: number;
/** What the terminal answered, in short: question answers joined by "; ", `No, keep planning`, `allowed` or `denied`. */
answer?: string | null;
/** A plan approved in the terminal (which mode is not known). */
planApproved?: boolean;
}
/** The reply to an accepted report. */
export interface ReportReply {
/** The server's clock, and how many of the report's events, from the first, it has taken; the reporter drops those from its queue. */
ok: true;
serverTime: number;
ackedEvents: number;
/** The report's own `session.id`, and how many live sessions are on the wall. */
sessionId: string;
liveSessions: number;
/** The server's version, and its dev build's commit (null for a release). */
serverVersion: string;
serverBuild?: string | null;
/** The range this server supports for the report's own reporter (null when it has none for it), and where the reporter stands. */
reporterSupport: ReporterSupport | null;
reporterCompat: ReporterCompat;
/** The loops a viewer is watching now (`@orchestrator` for the main loop); empty while the server's activityFeed setting is off. */
watch: string[];
/** Whether the server takes answers for this session now; reporters announce asks only while it is true. */
respond: boolean;
/** Messages and commands waiting for this session, oldest first; empty while `respond` is false. Answers never come here. */
deliveries: Delivery[];
}
// ---- Prices -----------------------------------------------------------------------------------
/** USD per million tokens for one model: one row of prices.json. `cacheWrite` is the 5-minute rate. */
export interface ModelPriceSet {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
cacheWrite1h: number;
}
// ---- View types (server to UI; the UI imports them with `import type`) ---------------------------
/** The model's family, from a lowercase match on its id: Claude's four, `openai` for Codex models, else `other`. */
export type ModelFamily = 'opus' | 'sonnet' | 'haiku' | 'fable' | 'openai' | 'other';
/** A session's status on its card: what its reporter last said. */
export type SessionStatusView = SessionReport['status'];
/** `outdated`: below the reporter's supported range; `newer`: above it; `unknown`: an unreadable version, never warned about. */
export type ReporterCompat = 'ok' | 'outdated' | 'newer' | 'unknown';
/** The versions of one reporter the server reads correctly (major.minor compared, patch ignored). */
export interface ReporterSupport {
min: string;
max: string;
}
/** A plan step as the server serves it; `doneSeq` (1, 2, …) is the order the server saw steps finish, absent when not done. */
export type PlanStepView = PlanStep & { doneSeq?: number };
/** A plan as the server serves it, its steps numbered in the order they finished. */
export type PlanView = Omit<Plan, 'steps'> & { steps: PlanStepView[] };
export interface AgentView extends Omit<AgentReport, 'promptText' | 'answerText' | 'activity' | 'tokens'> {
provider: ProviderName;
/** Its tokens by kind from its usage (cache writes of either length together); null while unknown, never 0. */
tokens: TokenCounts | null;
modelFamily: ModelFamily;
/** The length of the whole prompt and answer the server holds; null when it holds none. */
promptChars: number | null;
answerChars: number | null;
/** Running, not waiting, no running agents under it, and no activity for longer than its family's threshold. */
stuck: boolean;
}
/** One blowout, from its `blow` event: when, in which loop (null for the main loop), its kind, and the context tokens around it. */
export interface BlowoutLogEntry {
t: number;
agentId: string | null;
kind: string;
tokensBefore: number | null;
tokensAfter: number | null;
}
/**
* A session's blowouts: the main loop's, its agents', and both together; the card's level (blowoutLevel: 0 none, 1 "context
* exceeded", 2 "likely losing context"); how many of its loops have had one, out of how many; and the log.
*/
export interface BlowoutSummary {
orchestrator: number;
agents: number;
total: number;
level: 0 | 1 | 2;
loopsHit: number;
loopsTotal: number;
log: BlowoutLogEntry[];
}
/**
* Why a session is errored, derived by the server: `api` when the main loop's turn ended on a model API failure
* (`detail` its category, such as `rate_limit`), `tools` when `toolFailures` is 3 or more, or above 0 while the session runs with
* no tool call open (`toolOpen` false) and 60 s have passed since `lastActivityAt` (`detail` the tool when known).
*/
export interface ErroredState {
cause: 'api' | 'tools';
detail: string | null;
}
/** Another loop that edited the same file within 5 minutes: "Also edited by <name>: <file>". */
export interface CollisionView {
/** The absolute path both edited. */
path: string;
/** The other loop: its session (this one when two of its own agents collide), its agent (null for a main loop), and its name. */
sessionId: string;
agentId: string | null;
name: string;
/** When the later of the two edits happened. */
at: number;
}
/** One loop of this session messaging another within the last 30 minutes, from a `message` event. */
export interface MessageView {
/** The sender's agent id; null for the main loop. */
from: string | null;
/** The recipient's agent id (null for the main loop); absent when the reporter could not tie `toName` to a loop. */
to?: string | null;
toName: string;
/** The redacted message, cut as the event's text is. */
text: string;
at: number;
}
export interface SessionView {
/**
* The session on the server, `<nativeId>@<machine id>` (sessionKey), so the same conversation open on two machines is two
* sessions. Every route that names a session and every link take it; nothing shows it.
*/
id: string;
/** The id the session's own harness gave it (Report.session.id): the one shown, copied and resumed. */
nativeId: string;
name: string;
provider: ProviderName;
/** The reporter's version as it reported it, and the commit of a dev build (null for a release). */
reporterVersion: string;
reporterBuild: string | null;
/** Where that version sits against the range this server supports for that reporter. */
compat: ReporterCompat;
/**
* Report.reporter.hostSurface as last reported. Claude: `terminal`, `desktop`, `vscode` or `mobile` (Claude Code's surface),
* `headless` with no surface (`claude -p`, the SDK), `background` for a `claude --bg` or agent-view job. Codex: the thread's
* `session_meta.originator` exactly as Codex writes it (`Codex Desktop`, `codex-tui`, `Claude Code`, `codex_exec`, …).
* Null when not known (older reporters).
*/
hostSurface: string | null;
/** `projectRoot ?? cwd`, any machine's home (`/Users/<name>`, `/home/<name>`) shortened to `~`. */
project: string;
/** The working directory, any machine's home shortened to `~`. */
cwd: string;
repoName: string | null;
/** `cd <cwd> && claude --resume <id>`, or `cd <cwd> && codex resume <id>`, quoted where needed; null for any other provider. */
resumeCommand: string | null;
/** The same with `--fork-session`, or `codex fork <id>`; null for any other provider. */
forkCommand: string | null;
git: GitInfo | null;
model: string | null;
modelFamily: ModelFamily;
effort: string | null;
status: SessionStatusView;
waitReason: 'permission' | 'input' | 'idle' | null;
waitNote: string | null;
endReason: string | null;
/** When it started, when the server last heard from it, and how many seconds ago that was. */
startedAt: number;
lastSeenAt: number;
secondsSinceSeen: number;
/** Report.session.lastActivityAt: the status band's "No activity for 6m 12s." counts from it. */
lastActivityAt: number | null;
toolOpen: boolean;
/** Report.session.toolFailures: the main loop's consecutive failed tool calls; null when not observable. */
toolFailures: number | null;
/** Running, not waiting, no running agents, and no activity for longer than its family's threshold. */
stuck: boolean;
/** Why the session is errored; null when it is not. */
errored: ErroredState | null;
context: ContextFill;
costUsd: number | null;
/** Why `costUsd` is null: the model has no row in the price table, or no usage is reported yet; null when it is known. */
costReason: 'unpriced' | 'pending' | null;
/** `costUsd` is known but leaves out usage on models with no price ("+ unpriced"). */
costPartial: boolean;
/** True when `name` is the owner's display name from the dashboard (PUT /api/fleet/admin/sessions/:id/name). */
renamed: boolean;
/** Every token of the session, its agents' included, from its usage; null while unknown, never 0. */
tokensTotal: number | null;
/** The plan windows the session last reported, for the orchestrator's Limits cell. */
rateLimits: RateLimit[];
/** Null when the reporter cannot know (Codex hooks not active): shown as "—", never 0. */
blowouts: BlowoutSummary | null;
/** Codex only: whether this thread's hooks are active; null for Claude. */
hooksActive: boolean | null;
plan: PlanView | null;
loop: LoopReport | null;
files: FilesReport | null;
/** What the session is idle on; null when it waits on nothing. Not a wait on the person. */
background: BackgroundWait | null;
/**
* Whether a client is attached (null when unknown), and when a session nobody is attached to is set aside from the wall (null
* while attached or unknown).
*/
attached: boolean | null;
hideAt: number | null;
/** Who the session belongs to from the credential: `Admin` for the admin secret, null when the server has none. */
owner: string | null;
machine: MachineInfo;
/** The reporter's activityFeed option as last reported; null before the first report since start. */
activityFeed: boolean | null;
/** Report.session.respond as last reported; null before the first report since start. */
respond: RespondInfo | null;
/** The session's asks, open or recently closed, without their content. */
asks: AskSummary[];
/** The `id` of the session this one continues after a /clear, on the same machine; null when none. */
clearedFrom: string | null;
/** Other loops that edited a file this session edited within the last 5 minutes. */
collisions: CollisionView[];
/** Messages between this session's loops in the last 30 minutes, oldest first, at most 20. */
messages: MessageView[];
agents: AgentView[];
/**
* `tokensPerSec`, `peakContext`, `running`, `blowoutSecondsAgo`: 60 points each, one a second, oldest first; `peakContext`
* in 0..1; missing seconds are zero-filled. `tokensPerMin`: 30 points, oldest first; point i holds the output tokens reported
* in the 60 s ending (29 − i) minutes before now, so the last point is the current rate; 0 where nothing was reported. Token
* figures are output tokens, the session's and its agents', and leave out a reporter's replay of usage it had already reported
* (as the fleet series do).
*/
series: { tokensPerSec: number[]; peakContext: number[]; running: number[]; blowoutSecondsAgo: number[]; tokensPerMin: number[] };
}
/** Where an ask stands: open, an answer taken but not confirmed, an approval the session did not take, or closed. */
export type AskState = 'open' | 'pending' | 'not-taken' | 'closed';
/**
* An ask as the state and the stream carry it: the Ask without its questions, plan or tool input, with `count`, the questions of
* a question ask (the Respond button's number; 1 for any other ask), and where it stands.
*/
export interface AskSummary extends Pick<Ask, 'id' | 'kind' | 'agentId' | 'openedAt'> {
count: number;
state: AskState;
}
/** How an ask closed, as the panel shows it. `dashboard` is an answer from the dashboard that the session took. */
export type AskOutcome = 'dashboard' | 'terminal' | 'closed' | 'ended';
/**
* A delivery as the panel reads it back: what became of it (null until the reporter says), whether this signed-in browser sent
* it, and whether the reporter has been handed it, after which it can no longer be discarded.
*/
export interface DeliveryView extends Delivery {
result: DeliveryResult | null;
mine: boolean;
handedOver: boolean;
}
/** GET /api/fleet/respond/sessions/:id/asks/:askId: the whole ask, for a signed-in Admin. */
export interface AskDetail {
/** The ask, where it stands, and when the server last heard from its session. */
ask: Ask;
state: AskState;
lastSeenAt: number;
/** The answer sent from the dashboard, while the server holds it. */
delivery: DeliveryView | null;
/** How the ask closed, once it has. */
closed: AskClosure | null;
}
/** How an ask closed: the outcome, when, who answered from the dashboard (null otherwise), the terminal's answer, a plan approved. */
export interface AskClosure {
outcome: AskOutcome;
at: number;
by: string | null;
answer: string | null;
planApproved: boolean;
}
/**
* The body of GET /api/fleet/respond/me. Signing in (POST /respond/sign-in) keeps a sign-in for 400 days unused, each use renewing
* it; POST /respond/sign-out ends the browser's own, and POST /respond/sign-out-everywhere (signed in) ends every one.
*/
export interface RespondMe {
/** The admin secret is set and the server's `respond` setting is on. */
enabled: boolean;
/** Whether this browser is signed in, under what name (`Admin`; null until signed in), and whether as the admin. */
signedIn: boolean;
name: string | null;
admin: boolean;
}
/** A stored activity event as the UI shows it: the event, with its session's id, name and model family. */
export interface ActivityView extends ActivityEvent {
sessionId: string;
sessionName: string;
modelFamily: ModelFamily;
}
/** One machine's share of today's estimated spend, for its band header. */
export interface MachineSpend {
machineId: string;
costUsd: number;
/** Tokens were spent today on a model with no price row: show "—", not a total. */
unpriced: boolean;
}
/** One machine's spend on one model. Each figure is 0 with no use in its span, and null for use on a model with no price (unknown, never $0). */
export interface SpendRecordRow {
machineId: string;
provider: ProviderName;
model: string;
family: ModelFamily;
/** Since local midnight on the server. */
today: number | null;
/** The last 7 local days, today included. */
week: number | null;
/** Every day recorded. */
alltime: number | null;
}
/** The fleet's headline figures. The session and agent figures leave out an ended session still lingering on the wall. */
export interface Kpis {
/** Live sessions, how many run, and how many the server derives as stuck. */
live: number;
running: number;
stuck: number;
/** Their agents: running, and queued. */
agentsRunning: number;
agentsWaiting: number;
costToday: number;
/** Live sessions with usage on a model with no price, wholly or in part; that usage is left out of `costToday`. */
unpricedSessions: number;
/** USD the spend record booked per minute across the fleet over the last hour, oldest minute first (what `costToday` adds up). */
costPerMinute: number[];
/** Output tokens per second across the fleet over the last minute, oldest second first. */
tokensPerSec: number[];
/** `costToday` split by machine, largest first. */
costTodayByMachine: MachineSpend[];
/** The spend record by machine and model. */
spendRecord: SpendRecordRow[];
/** The first local day the record holds (`YYYY-MM-DD`); null while it is empty. */
spendSince: string | null;
}
/**
* The server's lifecycle timers: a live session unheard from for `removeAfterMs` leaves every view; an ended one stays on the wall
* for `lingerMs`, counted in no figure; one nobody is attached to is set aside after `detachedHideAfterMs`.
*/
export interface LifecycleConfig {
removeAfterMs: number;
lingerMs: number;
detachedHideAfterMs: number;
}
/** The two server settings. */
export interface ServerSettings {
respond: boolean;
activityFeed: boolean;
}
/** What Settings edits: the three switches, the stuck thresholds per family, the lifecycle timers and retention. The
* server keeps the owner's changes in its `settings` table over `server.env` as the defaults, and applies them without a
* restart. A change that sets a setting to null drops the owner's change to it, so `server.env`'s value applies again.
* `requireSignInToView` (default false): every browser read needs a sign-in, or the admin secret in TOKEN_HEADER; without either
* the server answers `401 {"error":"sign-in required"}` (VIEW_GATED). Signing in and out, GET /respond/me, the UI's files,
* /health and the reporters' routes stay open. */
export interface EditableSettings {
respond: boolean;
activityFeed: boolean;
requireSignInToView: boolean;
stuckAfterMs: Record<ModelFamily, number>;
lifecycle: LifecycleConfig;
retention: { samplesMs: number; eventsMs: number; sessionsMs: number };
}
/** The least each group of EditableSettings' timers takes, in ms: stuck after 10 s, lifecycle timers 1 s, retention 1 hour. */
export const SETTINGS_MIN_MS = { stuckAfterMs: 10_000, lifecycle: 1_000, retention: 3_600_000 } as const;
/** The `error` of the 401 every browser read gets while `requireSignInToView` is on and the request has no sign-in. */
export const VIEW_GATED = 'sign-in required';
/** One price row in use, read-only in Settings. */
export interface PriceRowView {
/** The model id it prices. */
model: string;
label: string;
std: ModelPriceSet;
/** The row's prices for a long request, when it has them, and when they apply ("over 272K input tokens"). */
long?: { when: string; prices: ModelPriceSet };
/** The row's prices for a fast-mode request, when it has them, and when they apply ("in fast mode"). */
fast?: { when: string; prices: ModelPriceSet };
}
/** GET /api/fleet/settings (a browser read), and the reply to PUT /api/fleet/admin/settings. */
export interface SettingsBody {
settings: EditableSettings;
/** What each setting falls back to: `server.env`, else the built-in default. */
defaults: EditableSettings;
/** Read-only facts; changing them means editing `server.env` and restarting. */
about: { version: string; build: string | null; host: string; port: number; allowedHosts: string[]; timeZone: string; logLevel: string; startedAt: number };
/**
* Where this start's price table came from: `live`, LiteLLM's published price file fetched at start; `snapshot`, the copy
* shipped with the server, when the fetch failed (`error` says why). `asOf` is the ISO time the table was fetched. `rows`
* are the rows that price the models in the record, with `prices.json`'s overrides laid on top.
*/
prices: { source: 'live' | 'snapshot'; asOf: string; error: string | null; rows: PriceRowView[] };
/** Models seen in reports since start that match no price row. */
unpricedModels: string[];
}
/** A report the server refused, kept in memory only (the last 200, newest first). GET /api/fleet/refusals. */
export interface RefusalView {
at: number;
/** The sender's address. */
address: string;
/** From the report when it carried one, or from MACHINE_HEADER on telemetry, else null. */
machineId: string | null;
machineName: string | null;
/** HTTP status and the fixed reason, such as `401 bad token` or `400 $.session.status`. */
status: number;
reason: string;
}
/**
* The signed-in owner's actions, under /api/fleet/admin with the same sign-in check as the answer routes:
* - PUT /settings Partial<EditableSettings> (nested objects partial too) → SettingsBody. A setting sent
* as null resets it to `server.env`'s value; a timer below SETTINGS_MIN_MS is a 400
* - DELETE /machines/:id → { removed: string[] }; 409 while the machine is reporting
* - POST /machines/remove-silent → { removed: string[] } (every silent and not-since-restart machine)
* - DELETE /sessions/:id a stored session → { ok: true }; 409 while it is live
* - PUT /sessions/:id/name { name: string | null } (at most 80 characters; null clears) → { ok: true }
* - GET /backup a consistent copy of the database (`VACUUM INTO`), as a download
*/
export const ADMIN_BASE = '/api/fleet/admin';
/**
* One provider's plan windows on a machine: the newest reading among its live sessions of that provider, by
* `measuredAt` (by the session's last activity for a reporter that sends none), less windows past their reset.
*/
export interface ProviderRateLimits {
provider: ProviderName;
limits: RateLimit[];
}
/** A machine's reporting state from its last report: under 2 minutes, under an hour, longer, or before this server started. */
export type MachineState = 'reporting' | 'quiet' | 'silent' | 'restart';
export const MACHINE_REPORTING_MS = 120_000;
export const MACHINE_QUIET_MS = 3_600_000;
/**
* One reporter on a machine. `live`: as its live sessions there report, the worst compat among them with that session's version.
* Otherwise the version the machine last reported, judged against the range.
*/
export interface ReporterVersion {
version: string;
compat: ReporterCompat;
live: boolean;
}
/** One row of the Machines page. */
export interface MachineView {
id: string;
name: string;
os: string | null;
/** When the server last took a report from this machine (server time). */
lastReportAt: number;
state: MachineState;
/** The Claude plugin's and the Codex reporter's versions on this machine; null for one never heard from it. */
reporters: { claude: ReporterVersion | null; codex: ReporterVersion | null };
/** The Codex daemon's version last reported from this machine; null when none. */
codexDaemon: string | null;
liveSessions: number;
rateLimits: ProviderRateLimits[];
}
/** GET /api/fleet/state, and the stream's `snapshot`. */
export interface StateBody {
/** The wall: its sessions, the latest activity, the machines, and the headline figures. */
sessions: SessionView[];
events: ActivityView[];
machines: MachineView[];
kpis: Kpis;
/** The server's clock, timers and switches. */
serverTime: number;
config: LifecycleConfig;
settings: ServerSettings;
/** The server's version, its dev build's commit (null for a release), and the range it supports for each reporter. */
server: { version: string; build: string | null; reporterSupport: Record<string, ReporterSupport> };
}
export type RemovedReason = 'done' | 'dropped' | 'deleted';
/** A row of GET /api/fleet/history: one session that ended or was dropped. */
export interface HistoryRow {
/** SessionView.id. */
id: string;
/** SessionView.nativeId. */
nativeId: string;
name: string;
provider: ProviderName;
project: string;
model: string | null;
modelFamily: ModelFamily;
/** When it started and ended, and how long it ran. */
startedAt: number;
endedAt: number;
durationSec: number;
/** Its cost, and `costPartial` when that cost leaves out usage on models with no price. */
costUsd: number | null;
costPartial: boolean;
/** Why `costUsd` is null, as on cards (SessionView.costReason); null when the cost is known. */
costReason: SessionView['costReason'];
/** Null when the reporter could not know. */
blowouts: number | null;
/** How many agents it ran, and why it ended. */
agents: number;
endReason: string | null;
/** The `id` of the session this one continued after a /clear, and of the one that continued it, on the same machine; null when none. */
clearedFrom: string | null;
clearedInto: string | null;
}
// ---- Validation: strings are clamped, lists over their limit rejected --------
/** The sizes the validator holds a report to; the reporters read them too. */
export const LIMITS = {
/** Characters of a one-line string, by what it holds. */
id: 200,
short: 120,
name: 80,
machineName: 64,
os: 80,
text: 240,
line: 240,
waitNote: 160,
call: 300,
excerpt: 400,
path: 1024,
filePath: 300,
backgroundDescription: 120,
/** promptText / answerText: 20,000 characters plus room for the reporter's cut-off marker. */
fullText: 20_100,
/** Items in a list. */
agents: 200,
events: 100,
planSteps: 100,
skills: 50,
toolNames: 100,
usageModels: 40,
backgroundTasks: 20,
rateLimits: 10,
blowoutLog: 50,
files: 200,
/** Lines a failure keeps: the end of its output, and the start of its evidence. */
outputLines: 12,
evidenceLines: 5,
/** One loop's activity feed: entries kept, characters per entry, and characters of summaries over the whole report. */
activityEntries: 20,
activityText: 300,
activityChars: 60_000,
/** A Bash entry's command: 20,000 characters plus room for the cut-off marker. */
activityDetail: 20_100,
/** Characters of commands over the whole report, apart from `activityChars`. */
activityDetailChars: 200_000,
} as const;
/** The characters a respond limit leaves over for the reporter's own "[cut off at N characters]" marker. */
const CUT_MARKER_ROOM = 60;
/** The most JSON one event's `data` may take. */
const EVENT_DATA_CHARS = 4096;
/** The most lines a failure's output or evidence list may hold before it is cut to its keep. */
const FAILURE_LINES_MAX = 1000;
/** The most files a report may list before the first LIMITS.files are kept. */
const FILES_LISTED_MAX = 1000;
/** A body turned away: what is wrong with it, and the path of the first field at fault. */
export type Rejected = { ok: false; error: string; path: string };
export type ValidateResult = { ok: true; report: Report } | Rejected;
export type ValidateAskResult = { ok: true; ask: Ask } | Rejected;
class Invalid extends Error {
readonly path: string;
constructor(path: string, message: string) {
super(message);
this.path = path;
}
}
// A one-line string loses every control character but tab; a text keeps its line feeds too.
const ONE_LINE_CONTROL = /[\u0000-\u0008\u000a-\u001f\u007f]/g;
const TEXT_CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
const EVENT_KINDS: readonly EventKind[] = ['start', 'end', 'spawn', 'skill', 'done', 'fail', 'blow', 'compact', 'plan', 'wait', 'note', 'edit', 'message'];
const FAILURE_CLASSES: readonly FailureClass[] = ['Tool error', 'Blocked by permission', 'Model API error', 'Refusal', 'Context window exhausted', 'Aborted', 'Unknown'];
const PLAN_SOURCES: readonly PlanSource[] = ['TaskCreate', 'TodoWrite', 'reporter_plan', 'codex-plan'];
const absent = (v: unknown): v is null | undefined => v === null || v === undefined;
const clip = (v: string, max: number): string => (v.length > max ? v.slice(0, max) : v);
function record(v: unknown, at: string): Record<string, unknown> {
if (typeof v !== 'object' || v === null || Array.isArray(v)) throw new Invalid(at, 'expected an object');
return v as Record<string, unknown>;
}
/** A one-line string, control characters replaced by spaces, cut to `max`. */
function line(v: unknown, at: string, max: number): string {
if (typeof v !== 'string') throw new Invalid(at, 'expected a string');
return clip(v.replace(ONE_LINE_CONTROL, ' '), max);
}
function lineOrNull(v: unknown, at: string, max: number): string | null {
return absent(v) ? null : line(v, at, max);
}
/** A text that keeps its line breaks, other control characters replaced by spaces, cut to `max`. */
function text(v: unknown, at: string, max: number): string {
if (typeof v !== 'string') throw new Invalid(at, 'expected a string');
return clip(v.replace(TEXT_CONTROL, ' '), max);
}
function finite(v: unknown, at: string): number {
if (typeof v !== 'number' || !Number.isFinite(v)) throw new Invalid(at, 'expected a finite number');
return v;
}
function finiteOrNull(v: unknown, at: string): number | null {
return absent(v) ? null : finite(v, at);
}
/** A non-negative number, rounded to a whole one. */
function count(v: unknown, at: string): number {
const n = finite(v, at);
if (n < 0) throw new Invalid(at, 'expected a non-negative number');
return Math.round(n);
}
function countOrNull(v: unknown, at: string): number | null {
return absent(v) ? null : count(v, at);
}
/** A cost: never below 0, null when absent. */
function costOrNull(v: unknown, at: string): number | null {
const n = finiteOrNull(v, at);
return n === null ? null : Math.max(0, n);
}
function flag(v: unknown, at: string): boolean {
if (typeof v !== 'boolean') throw new Invalid(at, 'expected a boolean');
return v;
}
function pick<T extends string>(v: unknown, at: string, allowed: readonly T[]): T {
const found = allowed.find((a) => a === v);
if (found === undefined) throw new Invalid(at, `expected one of ${allowed.join(', ')}`);
return found;
}
function pickOrNull<T extends string>(v: unknown, at: string, allowed: readonly T[]): T | null {
return absent(v) ? null : pick(v, at, allowed);
}
function list(v: unknown, at: string, max: number): unknown[] {
if (!Array.isArray(v)) throw new Invalid(at, 'expected an array');
if (v.length > max) throw new Invalid(at, `at most ${String(max)} items allowed`);
return v as unknown[];
}
/** A field of one checked object: `field(key, check, ...args)` runs `check` on it, naming its path, `<object>.key`, in an error. */
type Field = <A extends unknown[], T>(key: string, check: (v: unknown, at: string, ...args: A) => T, ...args: A) => T;
/** An object, checked, with the reader of its fields. */
function fieldsOf(v: unknown, at: string): [Record<string, unknown>, Field] {
const o = record(v, at);
return [o, (key, check, ...args) => check(o[key], `${at}.${key}`, ...args)];
}
function names(v: unknown, at: string): string[] {
return list(v, at, LIMITS.skills).map((s, i) => line(s, `${at}[${String(i)}]`, LIMITS.short));
}
/** Calls per tool name: names clipped and merged, counts whole and non-negative, the `max` most used kept (ties by name). */
function toolCounts(v: unknown, at: string, max: number): Record<string, number> | null {
if (absent(v)) return null;
const merged = new Map<string, number>();
for (const [tool, n] of Object.entries(record(v, at))) {
const key = clip(tool.replace(ONE_LINE_CONTROL, ' '), LIMITS.short);
merged.set(key, (merged.get(key) ?? 0) + count(n, `${at}.${tool}`));
}
const ranked = Array.from(merged).sort(([an, a], [bn, b]) => b - a || (an < bn ? -1 : 1));
return Object.fromEntries(ranked.slice(0, max));
}
function tokenCounts(v: unknown, at: string): TokenCounts {
const [, f] = fieldsOf(v, at);
return { input: f('input', count), output: f('output', count), cacheRead: f('cacheRead', count), cacheWrite: f('cacheWrite', count) };
}
/** A loop's own `tokens`, still checked when sent; absent stays absent. */
const tokensIfSent = (v: unknown, at: string): { tokens?: TokenCounts } => (absent(v) ? {} : { tokens: tokenCounts(v, at) });
/** Absent stays absent; a missing `cacheWrite1h` is 0 (no split known). */
function usageByModel(v: unknown, at: string): { usageByModel?: ModelUsage[] } {
if (absent(v)) return {};
const rows = list(v, at, LIMITS.usageModels).map((row, i): ModelUsage => {
const [, f] = fieldsOf(row, `${at}[${String(i)}]`);
const [tokens, t] = f('tokens', fieldsOf);
return {
model: f('model', line, LIMITS.short),
tier: f('tier', pick, USAGE_TIERS),
tokens: { ...f('tokens', tokenCounts), cacheWrite1h: absent(tokens.cacheWrite1h) ? 0 : t('cacheWrite1h', count) },
};
});
return { usageByModel: rows };
}
/** The percentage held to 0..100. */
function contextFill(v: unknown, at: string): ContextFill {
const [, f] = fieldsOf(v, at);
const percent = f('percent', finiteOrNull);
return { tokens: f('tokens', finiteOrNull), window: f('window', finiteOrNull), percent: percent === null ? null : Math.min(100, Math.max(0, percent)) };
}
function gitInfo(v: unknown, at: string): GitInfo | null {
if (absent(v)) return null;
const [, f] = fieldsOf(v, at);
return {
branch: f('branch', lineOrNull, LIMITS.short),
detached: f('detached', flag),
isWorktree: f('isWorktree', flag),
worktreePath: f('worktreePath', lineOrNull, LIMITS.path),
ahead: f('ahead', count),
behind: f('behind', count),
dirty: f('dirty', count),
};
}
function planOf(v: unknown, at: string): Plan | null {
if (absent(v)) return null;
const [, f] = fieldsOf(v, at);
const steps = f('steps', list, LIMITS.planSteps).map((step, i): PlanStep => {
const [, s] = fieldsOf(step, `${at}.steps[${String(i)}]`);
return {
id: s('id', line, LIMITS.id),
text: s('text', line, LIMITS.text),
state: s('state', pick, STEP_STATES),
activeText: s('activeText', lineOrNull, LIMITS.text),
ownerAgentId: s('ownerAgentId', lineOrNull, LIMITS.id),
ownerLabel: s('ownerLabel', lineOrNull, LIMITS.short),
};
});
return { title: f('title', lineOrNull, LIMITS.text), source: f('source', pick, PLAN_SOURCES), steps };
}
/** Output lines: each clipped, the last (or first) `keep` kept. */
function outputLines(v: unknown, at: string, keep: number, fromEnd: boolean): string[] {
const all = list(v, at, FAILURE_LINES_MAX).map((l, i) => line(l, `${at}[${String(i)}]`, LIMITS.line));
const first = fromEnd ? Math.max(0, all.length - keep) : 0;
return all.slice(first, first + keep);
}
function failureOf(v: unknown, at: string): Failure | null {
if (absent(v)) return null;
const [, f] = fieldsOf(v, at);
const exitCode = f('exitCode', finiteOrNull);
return {
class: f('class', pick, FAILURE_CLASSES),
at: f('at', finite),
tool: f('tool', lineOrNull, LIMITS.short),
call: f('call', lineOrNull, LIMITS.call),
exitCode: exitCode === null ? null : Math.round(exitCode),
outputTail: f('outputTail', outputLines, LIMITS.outputLines, true),
evidence: f('evidence', outputLines, LIMITS.evidenceLines, false),
retriedAs: f('retriedAs', lineOrNull, LIMITS.id),
};
}
/** A loop's activity feed. Absent stays absent; Bash detail is kept on `tool` entries only, and false flags are dropped. */
function activityOf(v: unknown, at: string): { activity?: ActivityEntry[] } {
if (absent(v)) return {};
const entries = list(v, at, LIMITS.activityEntries).map((raw, i): ActivityEntry => {
const [o, f] = fieldsOf(raw, `${at}[${String(i)}]`);
const kind = f('kind', pick, ACTIVITY_KINDS);
const entry: ActivityEntry = { at: f('at', finite), kind, text: f('text', line, LIMITS.activityText) };
if (!absent(o.id)) entry.id = f('id', line, LIMITS.id);
const isTool = kind === 'tool';
// Each optional field is still type-checked on a non-tool entry, then dropped there rather than rejected. Command output
// is not part of the contract: an `output` field is ignored like any unknown field.
const command = absent(o.command) ? null : f('command', text, LIMITS.activityDetail);
const commandCut = !absent(o.commandCut) && f('commandCut', flag);
const done = !absent(o.done) && f('done', flag);
const failed = !absent(o.failed) && f('failed', flag);
const exitCode = f('exitCode', countOrNull);
if (!isTool) return entry;
if (command !== null) entry.command = command;
if (commandCut) entry.commandCut = true;
if (done) entry.done = true;
if (failed) entry.failed = true;
if (exitCode !== null) entry.exitCode = exitCode;
return entry;
});
return { activity: entries };
}
function agentOf(v: unknown, at: string): AgentReport {
const [o, f] = fieldsOf(v, at);
let steps: AgentReport['steps'] = null;
if (!absent(o.steps)) {
const [, s] = f('steps', fieldsOf);
const total = s('total', finiteOrNull);
steps = { done: s('done', count), total: total === null ? null : Math.max(0, Math.round(total)) };
}
const agent: AgentReport = {
id: f('id', line, LIMITS.id),
parentId: f('parentId', lineOrNull, LIMITS.id),
kind: f('kind', pick, AGENT_KINDS),
type: f('type', line, LIMITS.short),
name: f('name', lineOrNull, LIMITS.name),
description: f('description', line, LIMITS.text),
model: f('model', lineOrNull, LIMITS.short),
effort: f('effort', lineOrNull, LIMITS.short),
effortSource: f('effortSource', pick, EFFORT_SOURCES),
status: f('status', pick, AGENT_STATUSES),
startedAt: f('startedAt', finite),
endedAt: f('endedAt', finiteOrNull),
context: f('context', contextFill),
...f('tokens', tokensIfSent),
costUsdEst: f('costUsdEst', costOrNull),
...f('usageByModel', usageByModel),
skills: f('skills', names),
lastTool: f('lastTool', lineOrNull, LIMITS.short),
toolCalls: f('toolCalls', count),
toolCounts: f('toolCounts', toolCounts, LIMITS.toolNames),
blowouts: f('blowouts', countOrNull),
toolFailures: f('toolFailures', countOrNull),
steps,
promptExcerpt: f('promptExcerpt', line, LIMITS.excerpt),
answerExcerpt: f('answerExcerpt', lineOrNull, LIMITS.excerpt),
...f('activity', activityOf),
failure: f('failure', failureOf),
lastActivityAt: f('lastActivityAt', finiteOrNull),
toolOpen: f('toolOpen', flag),
};
if (!absent(o.promptText)) agent.promptText = f('promptText', text, LIMITS.fullText);
if (!absent(o.answerText)) agent.answerText = f('answerText', text, LIMITS.fullText);
return agent;
}
/**
* One event. `edit` must carry an absolute `data.path` and keeps nothing else; `message` keeps only `data.toName` and, when present,
* `data.to`; a `fail` event's `data.category` must be a string.
*/
function eventOf(v: unknown, at: string): ActivityEvent {
const [o, f] = fieldsOf(v, at);
const kind = f('kind', pick, EVENT_KINDS);
let data = absent(o.data) ? null : f('data', record);
if (data !== null && JSON.stringify(data).length > EVENT_DATA_CHARS) throw new Invalid(`${at}.data`, `at most ${String(EVENT_DATA_CHARS)} characters of data allowed`);
if (kind === 'edit') {
const path = line(data?.path, `${at}.data.path`, LIMITS.path);
if (!path.startsWith('/')) throw new Invalid(`${at}.data.path`, 'expected an absolute path');
data = { path };
} else if (kind === 'message') {
const toName = line(data?.toName, `${at}.data.toName`, LIMITS.short);
// `to: null` is a message to the main loop; only a missing `to` means the reporter could not tie the name to a loop.
data = data?.to === undefined ? { toName } : { to: lineOrNull(data.to, `${at}.data.to`, LIMITS.id), toName };
} else if (kind === 'fail' && data !== null && !absent(data.category)) {
data = { ...data, category: line(data.category, `${at}.data.category`, LIMITS.short) };
}
return { id: f('id', line, LIMITS.id), t: f('t', finite), kind, agentId: f('agentId', lineOrNull, LIMITS.id), text: f('text', line, LIMITS.text), data };
}
function loopOf(v: unknown, at: string): LoopReport | null {
if (absent(v)) return null;
const [, f] = fieldsOf(v, at);
const [, steps] = f('steps', fieldsOf);
return {
skills: f('skills', names),
lastTool: f('lastTool', lineOrNull, LIMITS.short),
toolCalls: f('toolCalls', count),
toolCounts: f('toolCounts', toolCounts, LIMITS.toolNames) ?? {},
steps: { done: steps('done', count), total: null },
};
}
/** The first LIMITS.files files are kept rather than a longer list rejected; `total` never falls below what is listed. */
function filesOf(v: unknown, at: string): FilesReport | null {
if (absent(v)) return null;
const [, f] = fieldsOf(v, at);
const files = f('files', list, FILES_LISTED_MAX)
.slice(0, LIMITS.files)
.map((file, i): ChangedFile => {
const [, g] = fieldsOf(file, `${at}.files[${String(i)}]`);
return { path: g('path', line, LIMITS.filePath), status: g('status', pick, FILE_STATUSES), added: g('added', countOrNull), removed: g('removed', countOrNull), from: g('from', lineOrNull, LIMITS.filePath) };
});
return { files, total: Math.max(f('total', count), files.length), added: f('added', count), removed: f('removed', count), since: f('since', pick, FILES_SINCE) };
}
/** An empty task list is no background work at all. */
function backgroundOf(v: unknown, at: string): BackgroundWait | null {
if (absent(v)) return null;
const [, f] = fieldsOf(v, at);
const tasks = f('tasks', list, LIMITS.backgroundTasks).map((task, i): BackgroundTask => {
const [, g] = fieldsOf(task, `${at}.tasks[${String(i)}]`);
return { type: g('type', pick, BACKGROUND_KINDS), description: g('description', line, LIMITS.backgroundDescription), status: g('status', line, 40) };
});
const wakeAt = f('wakeAt', finiteOrNull);
return tasks.length > 0 ? { tasks, wakeAt } : null;
}
/** `accepts` keeps only what the level allows, so a reporter cannot claim more than its level. Duplicates are folded. */
function respondOf(v: unknown, at: string): { respond?: RespondInfo } {
if (absent(v)) return {};
const [, f] = fieldsOf(v, at);
const level = f('level', pick, RESPOND_LEVELS);
const accepts = f('accepts', list, RESPOND_KINDS.length).map((k, i) => pick(k, `${at}.accepts[${String(i)}]`, RESPOND_KINDS));
const limits = f('limits', list, RESPOND_LIMIT_NAMES.length).map((k, i) => pick(k, `${at}.limits[${String(i)}]`, RESPOND_LIMIT_NAMES));
const allowed = LEVEL_KINDS[level];
return { respond: { level, accepts: Array.from(new Set(accepts)).filter((k) => allowed.includes(k)), limits: Array.from(new Set(limits)) } };
}
/** One ask: strings clamped with room for the cut-off marker, lists over their limit rejected. */
function askOf(v: unknown, at: string, provider: ProviderName): Ask {
const [, f] = fieldsOf(v, at);
const id = f('id', line, LIMITS.id);
if (id === '') throw new Invalid(`${at}.id`, 'must not be empty');
const kind = f('kind', pick, ASK_KINDS);
const ask: Ask = { id, kind, agentId: f('agentId', lineOrNull, LIMITS.id), openedAt: f('openedAt', finite), allowsReply: f('allowsReply', flag) };
const withMarker = (n: number) => n + CUT_MARKER_ROOM;
if (kind === 'question') {
const questions = f('questions', list, RESPOND_LIMITS.questions);
if (questions.length === 0) throw new Invalid(`${at}.questions`, 'expected at least one question');
// A Claude question has at least one option; any other provider's may come with none (answered by typing, as Codex's).
const fewestOptions = provider === 'claude' ? 1 : 0;
ask.questions = questions.map((q, i): AskQuestion => {
const p = `${at}.questions[${String(i)}]`;
const [, g] = fieldsOf(q, p);
const options = g('options', list, RESPOND_LIMITS.options);
if (options.length < fewestOptions) throw new Invalid(`${p}.options`, 'expected at least one option');
return {
question: g('question', text, withMarker(RESPOND_LIMITS.question)),
header: g('header', line, RESPOND_LIMITS.header),
multiSelect: g('multiSelect', flag),
options: options.map((opt, j): AskOption => {
const [oo, h] = fieldsOf(opt, `${p}.options[${String(j)}]`);
return {
label: h('label', line, withMarker(RESPOND_LIMITS.label)),
description: h('description', text, withMarker(RESPOND_LIMITS.description)),
preview: absent(oo.preview) ? null : h('preview', text, withMarker(RESPOND_LIMITS.preview)),
};
}),
allowsText: g('allowsText', flag),
};
});
} else if (kind === 'plan') {
const [, g] = f('plan', fieldsOf);
ask.plan = { text: g('text', text, withMarker(RESPOND_LIMITS.plan)), filePath: g('filePath', lineOrNull, LIMITS.path) };
} else {
const [, g] = f('tool', fieldsOf);
const input = g('input', record);
if (JSON.stringify(input).length > withMarker(RESPOND_LIMITS.toolInput)) {
throw new Invalid(`${at}.tool.input`, `at most ${String(RESPOND_LIMITS.toolInput)} characters of input allowed`);
}
ask.tool = { name: g('name', line, LIMITS.short), input, cut: g('cut', flag), denyReason: g('denyReason', flag) };
}
return ask;
}
function sessionOf(v: unknown, at: string, provider: ProviderName): SessionReport {
const [o, f] = fieldsOf(v, at);
const id = f('id', line, LIMITS.id);
if (id === '') throw new Invalid(`${at}.id`, 'must not be empty');
const background = f('background', backgroundOf);
const session: SessionReport = {
id,
name: f('name', line, LIMITS.name),
status: f('status', pick, SESSION_STATUSES),
waitReason: f('waitReason', pickOrNull, WAIT_REASONS),
waitNote: f('waitNote', lineOrNull, LIMITS.waitNote),
endReason: f('endReason', lineOrNull, LIMITS.short),
resumeId: f('resumeId', lineOrNull, LIMITS.id),
startedAt: f('startedAt', finite),
cwd: f('cwd', line, LIMITS.path),
projectRoot: f('projectRoot', lineOrNull, LIMITS.path),
repoName: f('repoName', lineOrNull, LIMITS.short),
git: f('git', gitInfo),
model: f('model', lineOrNull, LIMITS.short),
effort: f('effort', lineOrNull, LIMITS.short),
context: f('context', contextFill),
costUsd: f('costUsd', costOrNull),
...f('tokens', tokensIfSent),
...f('usageByModel', usageByModel),
rateLimits: f('rateLimits', list, LIMITS.rateLimits).map((r, i): RateLimit => {
const [ro, g] = fieldsOf(r, `${at}.rateLimits[${String(i)}]`);
const limit: RateLimit = { kind: g('kind', line, LIMITS.short), percentUsed: g('percentUsed', finite), resetsAt: g('resetsAt', lineOrNull, LIMITS.short) };
if (!absent(ro.measuredAt)) limit.measuredAt = g('measuredAt', line, LIMITS.short);
return limit;
}),
blowouts: f('blowouts', countOrNull),
toolFailures: f('toolFailures', countOrNull),
plan: f('plan', planOf),
loop: f('loop', loopOf),
files: f('files', filesOf),
attached: absent(o.attached) ? null : f('attached', flag),
...f('activity', activityOf),
...f('respond', respondOf),
lastActivityAt: f('lastActivityAt', finiteOrNull),
toolOpen: f('toolOpen', flag),
};
if (background !== null) session.background = background;
if (!absent(o.hooksActive)) session.hooksActive = f('hooksActive', flag);
if (!absent(o.activityFeed)) session.activityFeed = f('activityFeed', flag);
if (!absent(o.asks)) session.asks = f('asks', list, RESPOND_LIMITS.asks).map((a, i) => askOf(a, `${at}.asks[${String(i)}]`, provider));
if (o.clearedFrom !== undefined) session.clearedFrom = f('clearedFrom', lineOrNull, LIMITS.id);
return session;
}
/** A host name (clamped, trimmed, not empty), the shared random id, and the OS as free text (null when unread). */
function machineOf(v: unknown, at: string): MachineInfo {
const [, f] = fieldsOf(v, at);
const name = f('name', line, LIMITS.machineName).trim();
if (name === '') throw new Invalid(`${at}.name`, 'expected a host name');
const id = f('id', line, 64);
if (!MACHINE_ID.test(id)) throw new Invalid(`${at}.id`, 'expected 1 to 32 letters, digits, - or _');
const os = f('os', lineOrNull, LIMITS.os)?.trim() ?? '';
return { name, id, os: os === '' ? null : os };
}
/** A dev build's commit (7 to 40 hex digits, `-dirty` after it for a tree with edits); null for a release or anything else. */
function buildOf(v: unknown): string | null {
if (typeof v !== 'string') return null;
const trimmed = v.trim();
return /^[0-9a-f]{7,40}(?:-dirty)?$/.test(trimmed) ? trimmed : null;
}
/**
* Keeps the report's activity inside its two budgets. Summaries share LIMITS.activityChars: the orchestrator's feed first,
* then each agent's in order, and a feed that does not fit is dropped from this report. Commands share
* LIMITS.activityDetailChars in the same loop order, newest entry first: an entry whose command does not fit loses it and
* keeps its summary and how the call ended.
*/
function fitActivity(report: Report): void {
let summaryRoom: number = LIMITS.activityChars;
const fits = (entries: ActivityEntry[]): boolean => {
const size = entries.reduce((n, e) => n + e.text.length, 0);
if (size > summaryRoom) return false;
summaryRoom -= size;
return true;
};
if (report.session.activity && !fits(report.session.activity)) delete report.session.activity;
for (const agent of report.agents) if (agent.activity && !fits(agent.activity)) delete agent.activity;
let detailRoom: number = LIMITS.activityDetailChars;
const trim = (entries: ActivityEntry[]): void => {
for (const e of [...entries].reverse()) {
const size = e.command?.length ?? 0;
if (size > detailRoom) {
delete e.command;
delete e.commandCut;
} else detailRoom -= size;
}
};
if (report.session.activity) trim(report.session.activity);
for (const agent of report.agents) if (agent.activity) trim(agent.activity);
}
/**
* Validates an untrusted body as a Report. Never throws. Strings are clamped to their limits and stripped of control
* characters; lists over their limit, wrong types and unknown enum values are rejected with the path of the first offending
* field; unknown fields are dropped. The provider is any PROVIDER_NAME, and the reporter's name must be `<provider>-reporter`.
*/
export const validateReport = (body: unknown): ValidateResult =>
guarded('report', () => {
const [o, f] = fieldsOf(body, '$');
if (o.v === undefined) throw new Invalid('$.v', 'the protocol version is missing');
if (o.v !== 1) throw new Invalid('$.v', 'this server reads protocol version 1 only');
const provider = f('provider', line, LIMITS.short);
if (!PROVIDER_NAME.test(provider)) throw new Invalid('$.provider', 'expected lower-case letters, digits and hyphens, a letter first, at most 32 characters');
const [r, g] = f('reporter', fieldsOf);
const name = g('name', line, LIMITS.short);
if (name !== reporterOf(provider)) throw new Invalid('$.reporter.name', `expected ${reporterOf(provider)} for provider ${provider}`);
const report: Report = {
v: 1,
sentAt: f('sentAt', finite),
provider,
reporter: { name, version: g('version', line, LIMITS.short), engineVersion: g('engineVersion', lineOrNull, LIMITS.short), hostSurface: g('hostSurface', lineOrNull, LIMITS.short) },
session: f('session', sessionOf, provider),
agents: f('agents', list, LIMITS.agents).map((a, i) => agentOf(a, `$.agents[${String(i)}]`)),
events: f('events', list, LIMITS.events).map((e, i) => eventOf(e, `$.events[${String(i)}]`)),
machine: f('machine', machineOf),
};
// A dev build's commit and the Codex daemon's version, each only when sent and readable.
const build = buildOf(r.build);
const daemonVersion = g('daemonVersion', lineOrNull, LIMITS.short);
report.reporter = { ...report.reporter, ...(build === null ? {} : { build }), ...(daemonVersion === null ? {} : { daemonVersion }) };
fitActivity(report);
return { ok: true, report };
});
/** Validates one ask as a reporter announces it (PUT …/asks/:askId), for a session of `provider`. Never throws. */
export const validateAsk = (body: unknown, provider: ProviderName): ValidateAskResult => guarded('ask', () => ({ ok: true, ask: askOf(body, '$', provider) }));
/** Runs one validator over an untrusted body: its result, or the first fault with its path (`invalid <what>` for anything else). */
function guarded<T extends { ok: true }>(what: string, check: () => T): T | Rejected {
try {
return check();
} catch (err) {
return err instanceof Invalid ? { ok: false, error: err.message, path: err.path } : { ok: false, error: `invalid ${what}`, path: '$' };
}
}