@repo-os/repoos 0.5.45

package/dist/server/agents.d.ts

@@ -0,0 +1,1020 @@
+import { type ChildProcess } from "node:child_process";
+import type { Agent, AgentOutputEntry, AgentSessionStats, RepoOSConfig, SkillMeta, Task } from "../core/types.js";
+import type { Logger } from "../core/logger.js";
+import { type UsageRange } from "../core/db.js";
+/** The SSE events the runner emits. Subset of RepoEvent. */
+export type AgentEvent = {
+    type: "agent.running";
+    id: string;
+    at: string;
+} | {
+    type: "agent.exited";
+    id: string;
+    at: string;
+}
+/** A start/send/chat was accepted but held for a free maxConcurrentAgents slot. */
+ | {
+    type: "agent.queued";
+    id: string;
+    at: string;
+}
+/** A queued id left the queue — about to spawn (an agent.running follows immediately). */
+ | {
+    type: "agent.dequeued";
+    id: string;
+    at: string;
+} | {
+    type: "agent.output";
+    id: string;
+    entry: AgentOutputEntry;
+    stream: "out" | "err";
+    at: string;
+} | {
+    type: "agent.stats";
+    id: string;
+    stats: AgentSessionStats;
+    at: string;
+} | {
+    type: "task.corrected";
+    id: string;
+    path: string;
+    note: string;
+    at: string;
+};
+export declare const HANDOFF_READY_SIGNAL = "::repoos-handoff-ready::";
+/**
+ * The exact line a sandboxed agent emits to request ITS managed preview
+ * (#0121). Like the handoff signal, it is an output-only intent: the agent
+ * never touches localhost or picks a port — the runner binds it to the live
+ * run and the server starts/probes the preview on the agent's behalf.
+ */
+export declare const PREVIEW_REQUEST_SIGNAL = "::repoos-preview-request::";
+/**
+ * The transcript marker appended when a user interrupts an in-flight AI chat
+ * response. Shared so the runner and the CTO manager (and tests) never drift.
+ */
+export declare const INTERRUPTED_MARKER = "\u2014 response interrupted \u2014";
+/** A capability minted by the runner for one completed agent turn. */
+export interface AgentHandoffRequest {
+    taskId: string;
+    runId: string;
+    branch: string;
+    workdir: string;
+    sessionId?: string;
+}
+/** A capability minted when a clean turn requested its managed preview (#0121). */
+export interface AgentPreviewRequest {
+    taskId: string;
+    runId: string;
+    branch: string;
+    workdir: string;
+    sessionId?: string;
+}
+export interface StartResult {
+    ok: boolean;
+    pid?: number;
+    /** True when the request was rejected because a turn is already running. */
+    busy?: boolean;
+    /** True when accepted but held for a free slot under maxConcurrentAgents — it will spawn once one frees. */
+    queued?: boolean;
+    reason?: string;
+}
+export interface StopResult {
+    stopped: boolean;
+    reason?: string;
+}
+export interface RunningAgentInfo {
+    id: string;
+    pid: number;
+    startedAt: string;
+    /** Working directory the agent runs in (worktree path, or repo root). */
+    workdir?: string;
+}
+/** Line-buffered transcript for one task, retained across turns and pause. */
+interface Session {
+    lines: AgentOutputEntry[];
+    pending: string;
+    bytes: number;
+    workdir?: string;
+    sessionId?: string;
+    task?: Task;
+    branch?: string;
+    /** Agent name (e.g., "engineer", "reviewer", "Ross"). */
+    agent?: string;
+    /** Model name (e.g., "big pickle", "default"). */
+    model?: string;
+    /** Which session engine parses the CLI output into AgentOutputEntry cards. */
+    engine: "opencode" | "claude" | "copilot" | "qwen" | "codex" | "kiro" | "plain";
+    /** Cumulative ms across completed turns — excludes any turn in flight (0080). */
+    accumulatedMs: number;
+    /** ISO timestamp when the session was first created (never changes). */
+    createdAt?: string;
+    /** ISO timestamp the current turn started, or undefined when no turn is running. */
+    turnStartedAt?: string;
+    /** ISO timestamp of the most recent output line, or undefined until first output. */
+    lastOutputAt?: string;
+    /** Best-effort cumulative input token count reported by the CLI, or undefined if never reported. */
+    inputTokens?: number;
+    /** Best-effort cumulative output token count reported by the CLI, or undefined if never reported. */
+    outputTokens?: number;
+    /** Best-effort cumulative token count reported by the CLI, or undefined if never reported. */
+    tokens?: number;
+    /** Best-effort cumulative cost (USD) reported by the CLI, or undefined if never reported. */
+    costUsd?: number;
+    /** Cumulative prompt-cache read tokens, when the CLI reports them (Phase 0). */
+    cacheReadTokens?: number;
+    /** Cumulative prompt-cache creation tokens, when the CLI reports them. */
+    cacheCreationTokens?: number;
+    /** Cumulative model round-trips ("turns") across every invocation of this session. */
+    turns?: number;
+    /**
+     * Snapshot of inputTokens/outputTokens/tokens/costUsd/cache* taken each time
+     * a new CLI process is spawned for this session (`start()` or `send()`; see
+     * `captureUsageBaseline`). A claude `result` (or a running-total line)
+     * reports a total scoped to THAT process only — starting back at zero — so
+     * folding it straight into the session would replace/cap prior processes'
+     * totals instead of adding to them (a task resumed after review, or a
+     * follow-up turn, would see its cost drop back down). `applyUsage` adds
+     * this baseline onto authoritative/running-total values; delta-style events
+     * (already summed onto `cur`) don't need it.
+     */
+    usageBaseline?: {
+        inputTokens: number;
+        outputTokens: number;
+        tokens: number;
+        costUsd: number;
+        cacheReadTokens: number;
+        cacheCreationTokens: number;
+    };
+    /**
+     * claude stream only (0109): a `tool_use` whose `tool_result` has not
+     * arrived yet. claude emits the call and its result as separate events, so
+     * the tool card is held back until the result line arrives and the entry
+     * can carry name + input + output together. Flushed without output if the
+     * turn ends before the result.
+     */
+    pendingTool?: {
+        id: string;
+        name: string;
+        input?: string;
+    };
+    /**
+     * Edge-detection only, not part of the public stats shape: whether the last
+     * `agent.stats` snapshot we pushed already reported `stalled: true`, so the
+     * periodic check emits exactly once per stall (not every tick) and output
+     * arriving after a stall clears it exactly once too.
+     */
+    stalledEmitted: boolean;
+}
+/**
+ * Default silence window before a still-running turn is flagged as possibly
+ * stalled (0080). Conservative on purpose: silence alone is never proof of a
+ * hang (the agent could just be thinking through a slow step), so this only
+ * fires a neutral "may be stalled" warning, never a definitive "it's dead."
+ * `AgentRunner`'s constructor accepts an override for tests.
+ */
+export declare const DEFAULT_STALL_TIMEOUT_MS = 90000;
+/**
+ * Estimate cost from token count when the CLI doesn't report it explicitly.
+ * Uses rough pricing for common models: claude 3.5 sonnet $3/M input, $15/M output.
+ * This is a fallback when extractUsage yields no cost; never fabricates when
+ * the CLI provides no data at all.
+ */
+export declare function estimateCostUsd(tokens?: number): number | undefined;
+/**
+ * Best-effort usage/cost extraction from one raw output line. Tries a JSON
+ * parse first (codex `--json` usage events, opencode payloads carrying usage)
+ * and falls back to plain-text patterns (the kind of human-readable summary
+ * claude/qwen print). Returns only the fields it actually found — this must
+ * never fabricate a number for a CLI that reports nothing.
+ */
+export interface ExtractedUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+    /** Input tokens served from the provider's prompt cache (~10% price). */
+    cacheReadTokens?: number;
+    /** Input tokens written to the prompt cache this turn (~125% price). */
+    cacheCreationTokens?: number;
+    /**
+     * True when parsed from a terminal turn-summary event (claude's
+     * `type:"result"`) — its numbers are authoritative for the whole turn and
+     * should OVERWRITE the running figures, not fold via Math.max. Without this
+     * a transient mid-stream `input_tokens` latches high and never comes down
+     * (e.g. #0310 showed "177k tokens" when the real non-cached input was 236).
+     */
+    authoritative?: boolean;
+    /**
+     * True when parsed from a per-round-trip event (opencode's `step_finish`),
+     * whose token/cost figures are DELTAS for that one model call — NOT a running
+     * total and NOT authoritative. Folds by SUM, like `turns`. Without this,
+     * `Math.max` folding keeps only the single largest step and undercounts a
+     * multi-step opencode session ~5-15x on input and cache-read tokens (a
+     * 17-step reviewer run stored ~34k cache-read instead of the real ~500k).
+     */
+    deltas?: boolean;
+    /**
+     * Model round-trips (agent "turns") this line accounts for — claude's
+     * `num_turns` from a `result` event, or 1 per opencode `step_finish`. Always
+     * a DELTA: folds by SUM (not max/overwrite), so multi-invocation sessions
+     * accumulate. `undefined` when the CLI reports nothing countable.
+     */
+    turns?: number;
+}
+export declare function extractUsage(raw: string): ExtractedUsage;
+/**
+ * Fold usage/cost found in a raw output line into a running total, clamped to
+ * never move backward (some CLIs report a running total, some reset per turn).
+ * Mirrors `AgentRunner.applyUsage` so one-shot roles aggregate the same way the
+ * streaming engineer runner does. Never fabricates a number — absent fields are
+ * simply left untouched.
+ */
+export declare function foldUsage(total: ExtractedUsage, raw: string): void;
+/**
+ * Classify the cost source for a recorded session (0230). Authoritative
+ * CLI-reported cost wins; Kiro is flagged as its own unit (credits), never
+ * passed off as USD. Callers that compute a token-based estimate (the engineer
+ * runner) set `costSource` to "estimate" themselves — this only reports whether
+ * a real CLI figure was present.
+ */
+export declare function usageCostSource(agent: Agent, usage: {
+    costUsd?: number;
+}): string;
+/**
+ * Map a runner session key to the REAL task id it belongs to (0230). Engineer
+ * and review sessions are keyed by the task id directly. PM chats are keyed by
+ * a synthetic `pm-task-v2:<id>` id whose suffix is the actual task — attribute
+ * them under that real id so PM cost/tokens aggregate per-task. Non-task chats
+ * (guide) have no task and return null. Per-user PM sessions (0248) append
+ * `::<email>` after the task id; that suffix is stripped here too so cost
+ * attribution doesn't treat "<id>::<email>" as the task id.
+ */
+export declare function resolveSessionTaskId(taskKey: string | undefined): string | null;
+/**
+ * Persistent session key for Ross's board-level chat. Must match the id the
+ * guide client subscribes to and persists under (RepoGuideChat.vue uses
+ * "repoos-guide"); a previous refactor drifted this to "__repoos-guide__",
+ * which hid the guide's running/stop state from the UI.
+ */
+export declare const REPO_GUIDE_SESSION_ID = "repoos-guide";
+/** Persistent session id for the Debugger's bug-paste conversation. */
+export declare const debuggerSessionId = "__repoos-debugger__";
+/**
+ * Classify a runner session into the role label the board's "AI usage — all
+ * roles" panel groups by (0331). Exact matches on the built-in role names win
+ * first: the legacy "RepoOS Guide" name used to be swallowed into "engineer"
+ * because an earlier `includes("repoos")` probe ran before the guide check —
+ * classify on what the agent IS, not on a substring an earlier rule grabbed.
+ * Unknown names fall through ordered substring probes (guide before the rest
+ * so "ross guide"-style hybrids still land right), then to "task" when the
+ * session is keyed to a task at all, "chat" when it is not.
+ */
+export declare function classifySessionType(agentName: string | null | undefined, taskKey?: string): string;
+export interface AgentRunnerOptions {
+    /** Test/embedding overrides; production defaults are the documented policy. */
+    writeDelayMs?: number;
+    retentionDays?: number;
+    retentionCount?: number;
+    now?: () => Date;
+    /** Resolve a task from the repo task index by ID. Used to populate task/branch on resume turns. */
+    getTask?: (taskId: string) => Task | null;
+}
+/**
+ * Parse one line of opencode's `--format json` stream into a structured
+ * transcript entry. Returns null for malformed lines and for event types we
+ * don't surface (session-id, title, reasoning, …) — callers fall back to the
+ * plain-line handling in those cases.
+ */
+export declare function parseJsonEvent(raw: string): {
+    entry: AgentOutputEntry;
+    sessionID?: string;
+} | null;
+/**
+ * Result of parsing one line of claude code's `--output-format stream-json`
+ * stream (0109). Fields are mutually exclusive:
+ *
+ * - `entry` — a ready-to-surface transcript entry (assistant text, a completed
+ *   tool call, or a step boundary).
+ * - `pendingTool` — a `tool_use` whose `tool_result` hasn't arrived yet. The
+ *   line has no entry yet; the runner buffers it and emits the tool card only
+ *   when the matching `tool_result` line arrives (name + input + output
+ *   together).
+ * - `toolResult` — a `tool_result` line to attach to the buffered tool.
+ * - `sessionID` — the `system/init` event's real `session_id` field (never
+ *   regex-scraped).
+ *
+ * `null` means the line is not a claude stream event (a non-JSON warning line,
+ * unknown JSON schema, …) — callers fall back to the plain-line path.
+ */
+export interface ClaudeParseResult {
+    entry?: AgentOutputEntry;
+    sessionID?: string;
+    pendingTool?: {
+        id: string;
+        name: string;
+        input?: string;
+    };
+    toolResult?: {
+        id: string;
+        content?: string;
+        isError?: boolean;
+    };
+}
+/**
+ * Parse one line of claude code's `--output-format stream-json` stream into a
+ * structured transcript result. Mirrors `parseJsonEvent` for opencode but with
+ * claude's event shapes: content is nested under `message.content[]` (not
+ * `part`), the session id is a real `session_id` field on `system/init`, and
+ * tool results arrive as separate `user` events. Recognized-but-voiceless
+ * events (rate_limit, thinking-only assistant messages, the terminal `result`)
+ * are returned without an `entry` so the runner swallows them instead of
+ * dumping raw JSON into the transcript. `null` for anything else — callers
+ * fall back to the plain-line path.
+ */
+export declare function parseClaudeEvent(raw: string): ClaudeParseResult | null;
+/**
+ * Parse Copilot CLI's `--output-format json` JSONL stream. The CLI emits
+ * lifecycle telemetry alongside assistant and tool events; lifecycle records
+ * are recognized and swallowed so the Agent tab remains a useful transcript.
+ */
+export declare function parseCopilotEvent(raw: string): {
+    entry?: AgentOutputEntry;
+    sessionID?: string;
+} | null;
+/**
+ * Qwen's stream-json is Claude-compatible for assistant/tool content, but
+ * versions in the wild also emit the shorter `{type, content}` form. Keep
+ * this adapter deliberately tolerant so a CLI upgrade cannot turn the chat
+ * into a wall of JSON.
+ */
+export declare function parseQwenEvent(raw: string): ClaudeParseResult | null;
+interface CodexEventResult {
+    entry?: AgentOutputEntry;
+    sessionID?: string;
+}
+/** Parse Codex `exec --json` JSONL into the same chat cards as OpenCode. */
+export declare function parseCodexEvent(raw: string): CodexEventResult | null;
+/** Branch derived from a task title, mirroring the UI's `feat/<slug>` rule. */
+export declare function deriveBranch(title: string): string;
+/** Resolve the enabled `engineer` agent, or null when none is configured. */
+export declare function resolveEngineer(config: RepoOSConfig): Agent | null;
+/** Resolve the enabled `pm` agent, or null when none is configured. */
+export declare function resolvePmAgent(config: RepoOSConfig): Agent | null;
+/**
+ * Resolve the enabled `reviewer` agent, or null when it is disabled/absent.
+ *
+ * This is the single source of truth for whether a task landing in `review`
+ * gets an automatic agent review (0101): the Agents page writes the toggle
+ * into `repoos.toml`, and null here means "no agent review runs".
+ */
+export declare function resolveReviewer(config: RepoOSConfig): Agent | null;
+/**
+ * Resolve the reviewer agent for a specific task, honoring per-task review
+ * overrides (set via the Review tab's selector, like Dev/PM overrides).
+ *
+ * When the task has no review override, this behaves exactly as the global
+ * `resolveReviewer` — the Agents-page reviewer. When a `reviewAgentOverride`
+ * is set, the enabled agent with that name is used (falling back to the global
+ * reviewer base when only CLI/model are overridden); `reviewCliOverride` /
+ * `reviewModelOverride` then replace the agent's CLI and model.
+ */
+export declare function resolveReviewerForTask(config: RepoOSConfig, task: Task): Agent | null;
+export declare function resolveCto(config: RepoOSConfig): Agent | null;
+/**
+ * Resolve the agent for a specific task, honoring per-task overrides.
+ *
+ * When the task has an `agentOverride`, the enabled agent with that name is
+ * used (falling back to the base agent when the override name matches). When
+ * only `cliOverride` or `modelOverride` are set (without a different agent
+ * name), the base agent's name and instructions are kept but cli/model are
+ * overridden.
+ *
+ * @param config  Global config (provides the agents list and defaults).
+ * @param task    The task being run (may carry overrides).
+ * @param role    The role to resolve when no agent override is set (default: "engineer").
+ * @returns A merged Agent, or null when no matching enabled agent exists.
+ */
+/**
+ * True when a model-override field carries a real pin, not the "default"
+ * sentinel `AGENT_MODELS` offers for "use the base agent's own configured
+ * model, whatever that is" (config.ts). Every per-task model-override
+ * resolver (this file's `resolveAgentForTask`/`resolveReviewerForTask`, and
+ * routes/tasks.ts's inline PM-override logic) MUST run the override string
+ * through this before treating it as active — bare truthiness treats the
+ * literal string `"default"` as a real pin and force-overwrites the base
+ * agent's actual configured model with the string `"default"`, which then
+ * skips `--model` entirely (see `modelArgs` below) and falls back to the
+ * underlying CLI's own raw default — NOT the model configured on the
+ * Agents page. Confirmed live: tasks kept ending up running
+ * opencode+(no model flag) instead of the configured model every time a
+ * Dev/Review/PM override dropdown was left on (or reset to) "Default".
+ */
+export declare function isModelOverridePinned(model: string | null | undefined): boolean;
+export declare function resolveAgentForTask(config: RepoOSConfig, task: Task, role?: string): Agent | null;
+/** Resolve the enabled built-in repository assistant (by current "Ross" name or legacy "RepoOS Guide"). */
+export declare function resolveRepoGuide(config: RepoOSConfig): Agent | null;
+/** Build the read-only mission used by the persistent repository chat. */
+export declare function repoGuidePrompt(question: string, repositoryContext: string, agent: Agent): string;
+/** The Debugger agent's role name, used to route its chat prompt. */
+export declare const DEBUGGER_NAME = "debugger";
+/**
+ * The Debugger agent: a chat-first bug diagnostician (no background scan).
+ * Its CLI/model can be overridden from the persisted built-in agent state so
+ * the inline "coding agent + model" selector on the Agents page actually drives
+ * which model the Debugger runs on.
+ */
+export declare function debuggerAgent(override?: {
+    cli?: string;
+    model?: string;
+}): Agent;
+export declare function debuggerPrompt(question: string, repositoryContext: string, agent: Agent): string;
+/** Build the writable task-management mission used only by the PM chat. */
+export declare function taskPmPrompt(request: string, taskContext: string, agent: Agent): string;
+/** Pick a small relevant subset; role defaults are preferences, never an unconditional prompt append. */
+export declare function selectSkillsForRun(task: Task, agent: Agent, config: RepoOSConfig): SkillMeta[];
+/** One-shot run outcome: resolved stdout, or a human-readable failure. */
+export interface PromptResult {
+    ok: boolean;
+    output?: string;
+    error?: string;
+    /** Wall-clock elapsed ms for the run, or 0 if it never spawned. */
+    elapsedMs?: number;
+    /** Cumulative tokens/cost the CLI reported, when extractUsage found any. */
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    turns?: number;
+}
+/**
+ * Map an agent `cli` to a one-shot (print mode) invocation that writes its
+ * answer to stdout. opencode: `run`, claude: `-p`, qwen: `-p`, codex:
+ * `exec`. Explicit configured models are forwarded with the driver's model
+ * flag; `default` intentionally omits the flag and lets the CLI resolve it.
+ */
+export declare function promptCommand(agent: Agent, prompt: string): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Map an agent `cli` to a one-shot PM authoring invocation (0335). Same
+ * print-mode shape as `promptCommand`, with one difference that matters for
+ * the usage tab: structured output flags wherever the driver offers them, so
+ * `runPrompt`'s extractUsage/foldUsage sees real tokens/cost and the initial
+ * PM flesh-out lands in the ledger with figures instead of a blank row —
+ * exactly the treatment the reviewer got in 0273. Unlike `reviewCommand`,
+ * no permission-bypass flags: the PM only authors text (its output is applied
+ * via `patchTaskFile`), so it must not be able to write files or run tools.
+ *
+ * The JSONL/JSON stdout this produces is parsed back to the final answer with
+ * `extractOneShotReportText` and rendered live with `parseOneShotLine` — the
+ * same pairing the reviewer/CTO one-shots use.
+ */
+export declare function pmCommand(agent: Agent, prompt: string, cwd: string): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Map an agent `cli` to a one-shot REVIEW invocation: the agent inspects a
+ * worktree it must not modify and prints its report to stdout.
+ *
+ * Same print-mode shape as `promptCommand`, with one difference that matters:
+ * a reviewer has to READ the worktree (git diff, file reads, maybe the test
+ * suite), and stdin is ignored — so any engine that gates those calls behind a
+ * permission prompt would hang until the timeout instead of reporting. Only
+ * flags already verified for this repo's drivers are used:
+ * - claude code: `--dangerously-skip-permissions` (same reason as the runner's
+ *   start turns — nobody can answer a prompt).
+ * - opencode: `--dir <cwd>` so a linked-worktree path is not auto-rejected,
+ *   plus `--auto` so gated tool calls resolve instead of blocking.
+ * - codex: `exec` alone — its default sandbox is already read-only, which is
+ *   exactly the blast radius a reviewer should have.
+ * - qwen code: plain `-p`, matching `promptCommand`.
+ * - opencode: `--format json`, matching the interactive runner (`cliCommand`
+ *   below). Without it, `run`'s plain-text stdout interleaves the model's
+ *   step-by-step narration ("Let me look at...") with its final answer, and
+ *   nothing separates the two — the whole transcript ends up as the review
+ *   report (0264 vs 0253). `extractOneShotReportText` below picks the final
+ *   text event back out of the JSON stream.
+ */
+export declare function reviewCommand(agent: Agent, prompt: string, cwd: string): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Turn one line of a one-shot (review/CTO) agent's stdout into a transcript
+ * entry for live display. Structured event streams (opencode `--format json`,
+ * claude/qwen stream-json, codex `--json`, copilot json) get the same per-line
+ * parsing the interactive runner applies, so the review transcript reads
+ * cleanly instead of dumping raw JSON. A recognized-but-voiceless structured
+ * event (claude `result`, `system/init`, a thinking-only assistant message …)
+ * returns null so the caller can swallow it; a non-JSON line (warnings, plain
+ * text from kiro) passes through as a plain `{s, d}` entry.
+ */
+export declare function parseOneShotLine(cli: string, raw: string): AgentOutputEntry | null;
+/**
+ * Isolate the final report/answer from a one-shot agent's full captured
+ * stdout. Structured JSONL engines (opencode `--format json`, claude/qwen
+ * stream-json, codex `--json`, copilot json) carry the model's whole narration
+ * as a sequence of `text` events interleaved with tool calls — the actual final
+ * answer is the LAST `text` event, so this discards the rest (0264 vs 0253).
+ * Non-JSON one-shot CLIs (kiro) print only the final answer, so their raw
+ * output IS the report. Falls back to the raw output if no text event parses,
+ * so a format change never yields an empty report.
+ */
+export declare function extractOneShotReportText(cli: string, rawOutput: string): string;
+/**
+ * Run a coding agent once, non-interactively, and capture its full stdout.
+ * Unlike the streaming runner this is synchronous — callers wait for the whole
+ * answer (e.g. freeform task creation). Never throws: failures and timeouts
+ * resolve as `{ ok: false, error }` so an HTTP handler can respond cleanly.
+ *
+ * `onLine` streams each complete stdout line as it arrives (line-buffered, the
+ * same shape the runner uses) so a caller can forward live progress over SSE
+ * without waiting for the run to finish. It is called for real output only —
+ * never for a synthetic failure — and a trailing partial line is flushed on
+ * exit.
+ *
+ * `command` overrides the invocation (default: `promptCommand`) so a caller
+ * that needs different flags — the review agent's read-the-worktree mode —
+ * reuses this spawn/timeout/capture handling instead of duplicating it.
+ * `onSpawn` hands the live child to the caller so it can be killed early.
+ *
+ * The child inherits the server's env verbatim: unlike the streaming runner,
+ * NO `REPOOS_API_URL` / `REPOOS_TASK_ID` is injected, so a one-shot agent has
+ * no pointer at the control plane's task endpoints.
+ */
+export declare function runPrompt(agent: Agent, prompt: string, opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+    onLine?: (line: string) => void;
+    command?: {
+        cmd: string;
+        args: string[];
+    };
+    onSpawn?: (proc: ChildProcess) => void;
+}): Promise<PromptResult>;
+/**
+ * Persist a one-shot `runPrompt` run to the sessions DB (0311). One-shot AI
+ * work — freeform task/doc authoring, the auto-engineering dispatch pass —
+ * bypasses the AgentRunner, so nothing books it unless the caller does. This
+ * is the shared path for those: it folds the `PromptResult` (elapsed, tokens,
+ * cost) into a session row, classifying `costSource` the same way
+ * `recordSessionToDb` does — a real CLI figure wins, a token-only run gets an
+ * estimate, Kiro credits are never presented as USD. Best-effort: a DB failure
+ * never propagates to the request.
+ *
+ * `taskId` is null for board-level work that belongs to no single task; those
+ * rows still roll into every board-level aggregation (getSessionTypeStats /
+ * getDailyTotals / board summary), just not a task drawer.
+ */
+export declare function recordOneShotSession(repoRoot: string, agent: Agent, result: PromptResult, opts: {
+    sessionType: string;
+    taskId?: string | null;
+    sessionId?: string;
+}): void;
+export declare class AgentRunner {
+    private entries;
+    private readonly sessions;
+    private readonly config;
+    /**
+     * Cap on simultaneously-spawned agent CLI processes — each one may
+     * itself run a build/test worker pool sized to the host's core count, so
+     * unlimited concurrent agents oversubscribe the machine. Configurable via
+     * `maxConcurrentAgents` in repoos.toml; "auto" (unset) sizes it to this
+     * machine's CPU count so the same repo behaves on a laptop and a desktop.
+     */
+    private readonly maxConcurrentAgents;
+    /** Ids (taskId or chat sessionId) with a queued start/send waiting for a free slot, mapped to when they were queued. */
+    private readonly queuedIds;
+    /** FIFO of deferred spawns, drained as running agents exit (see cleanup()). */
+    private readonly startQueue;
+    private readonly emit;
+    private readonly logger?;
+    private readonly sessionsDir;
+    private readonly cacheDir;
+    private readonly logDir;
+    private readonly db;
+    private readonly writeDelayMs;
+    private readonly retentionDays;
+    private readonly retentionCount;
+    private readonly clock;
+    private readonly writeTimers;
+    private readonly pendingCompletion;
+    /**
+     * The main RepoOS server's own API URL, injected into every agent process so
+     * agents with host networking have an informational pointer at the ACTUAL
+     * control plane, never a hardcoded port. Managed previews are requested by
+     * signal (#0121), so this is not a requirement — it stays for diagnostics
+     * and future HTTP-capable drivers.
+     */
+    apiUrl?: string;
+    private readonly stallTimeoutMs;
+    private readonly stallTimer;
+    private readonly authorizedHandoffs;
+    private readonly handoffsInFlight;
+    private readonly onHandoff?;
+    /**
+     * Fired on completion of a durable REVIEW turn (0288) — including for an
+     * entry re-attached after a reload, whose process finishes on the new
+     * server. The owning ReviewManager finalizes the report from this hook
+     * rather than a post-spawn continuation that would die with the old process.
+     * `reviewKind` (run vs chat) and `exitedCleanly` are threaded through so the
+     * ReviewManager can finalize an adopted turn in the right mode and decide
+     * whether it finished cleanly.
+     */
+    private readonly onReviewDone?;
+    /**
+     * Tasks a human deliberately paused (via POST /api/tasks/:id/pause, 0070).
+     * The task stays `active` with no process, so without this the watchdog would
+     * treat a legitimately-paused task as stuck and disturb it (#0180). In-memory
+     * only: a paused task across a server restart loses the marker and reads as a
+     * stopped agent — the watchdog then surfaces it, which is the correct default
+     * (the paused process is, after all, gone).
+     */
+    private readonly pausedTasks;
+    /**
+     * Preview capabilities minted per clean run (#0121). Superseded when a new
+     * run starts for the same task, so a stale request can never start a preview
+     * against a different worktree.
+     */
+    private readonly authorizedPreviews;
+    private readonly onPreviewRequest?;
+    /** Resolve a task from the repo task index by ID. Used to populate task/branch on resume turns. */
+    private readonly getTask?;
+    /**
+     * `opts.stallTimeoutMs` overrides the 90s default (tests use a small value
+     * so stall detection doesn't need a real 90s wait); `opts.stallCheckIntervalMs`
+     * overrides the poll cadence, which otherwise scales with the timeout.
+     */
+    constructor(config: RepoOSConfig, emit: (e: AgentEvent) => void, opts?: {
+        stallTimeoutMs?: number;
+        stallCheckIntervalMs?: number;
+        onHandoff?: (request: AgentHandoffRequest) => void | Promise<void>;
+        onPreviewRequest?: (request: AgentPreviewRequest) => void | Promise<void>;
+        onReviewDone?: (sessionKey: string, exitedCleanly: boolean, reviewKind?: "run" | "chat") => void;
+        logger?: Logger;
+    } & AgentRunnerOptions);
+    /** Stop the stall-check timer (server shutdown / test cleanup). Idempotent. */
+    dispose(): void;
+    /**
+     * Re-attach to agent children that survived a server restart (0214).
+     * Reads the durable registry, checks PID aliveness, and for each still-live
+     * child tail-catches the log file and restores the in-memory entry/session
+     * so `isRunning()` reports true and SSE streaming resumes from this point.
+     * Stale entries (PID dead) are dropped — this must not resurrect dead sessions.
+     */
+    adoptRunningAgents(): void;
+    /** Replay a durable log into a transcript, optionally decoding the legacy tagged format. */
+    private replayLog;
+    /** True only while `replayLog` is rebuilding a transcript — see `applyUsage`. */
+    private replayingUsage;
+    /** Tail one durable stream file into the live transcript. */
+    private tailLog;
+    /** Persist a registry entry for one running task (0214). */
+    private writeRegistryEntry;
+    /** Remove a registry entry for a task (0214). */
+    private removeRegistryEntry;
+    /** Clear the entire durable registry (0214). */
+    private clearRegistry;
+    /** Persist a handoff request for recovery across process boundaries. */
+    private persistPendingHandoff;
+    /** Remove a persisted handoff request (by task id). */
+    private clearPendingHandoff;
+    /**
+     * Recover persisted handoff requests at server boot. Validates each request
+     * (task still exists, still active, branch matches, not already finalizing)
+     * and re-fires onHandoff for valid ones. Idempotent: a request already in
+     * handoffsInFlight is skipped.
+     */
+    recoverPendingHandoffs(): void;
+    /** Append trusted server orchestration progress to the retained transcript. */
+    system(taskId: string, text: string): void;
+    /** Validate that a handoff capability was minted by a successful active turn. */
+    validateHandoff(request: AgentHandoffRequest): boolean;
+    /** Validate and expire one runner-issued handoff capability atomically. */
+    consumeHandoff(request: AgentHandoffRequest): boolean;
+    /**
+     * Validate that a preview capability was minted by a real, current runner
+     * turn (#0121). The capability carries the task id, the run id issued for
+     * that turn, the registered branch, and the registered worktree — a forged,
+     * expired (superseded by a newer run), cross-task, or path-substituted
+     * request never matches all four.
+     */
+    validatePreview(request: AgentPreviewRequest): boolean;
+    isRunning(taskId: string): boolean;
+    /**
+     * The review turn kind ("run" | "chat") of a durable review session, if the
+     * entry is one (0288). Used by ReviewManager to finalize an ADOPTED turn in
+     * the right mode — the session's own `Run` record is not carried across a
+     * reload, but its review kind is (persisted in the registry).
+     */
+    reviewKindOf(sessionKey: string): "run" | "chat" | undefined;
+    /**
+     * Record a deliberate human pause (0070): the task stays `active` but its
+     * agent is intentionally stopped, so the watchdog must not touch it (#0180).
+     * Cleared automatically the moment a new turn starts for the task.
+     */
+    markPaused(taskId: string): void;
+    /** True when the task was explicitly paused and no new turn has started since. */
+    isPaused(taskId: string): boolean;
+    /**
+     * True while the server-side handoff for a task is still finalizing (check,
+     * commit, review). The process is already gone, so `isRunning` is false, but
+     * the task is not stuck — the close-out pipeline owns it for a few seconds.
+     */
+    isHandoffInFlight(taskId: string): boolean;
+    /** Live run telemetry for a task's session — zeros/nulls when none exists yet. */
+    stats(taskId: string): AgentSessionStats;
+    running(): RunningAgentInfo[];
+    /** Query historical stats for a task from the database. */
+    taskStats(taskId: string): import("../core/db.js").TaskStats | null;
+    /** Query historical stats grouped by session type from the database. */
+    sessionTypeStats(): import("../core/db.js").SessionTypeStats[];
+    /** Per-day usage totals (server's local time). */
+    dailyTotals(): import("../core/db.js").DailyTotals[];
+    /** Query board-level summary stats from the database, optionally scoped to a usage range (0334). */
+    boardStats(range?: UsageRange): import("../core/db.js").BoardStats | null;
+    /**
+     * Spawn the coding agent on the task. Never blocks — the child runs
+     * detached from the HTTP response. Returns a StartResult describing the
+     * launch attempt; an async spawn failure is emitted as agent.exited.
+     *
+     * `opts.cwd` is the task's worktree directory when one was provisioned;
+     * defaults to the repo root so launch still works (best-effort) when
+     * worktree setup failed or the task's branch is the main checkout.
+     */
+    start(task: Task, branch: string, agent: Agent, opts?: {
+        cwd?: string;
+        contextPack?: string;
+        resumePreamble?: string;
+    }): StartResult;
+    /** Start a persistent, non-task conversation with an explicit role mission. */
+    startChat(sessionId: string, text: string, agent: Agent, repositoryContext: string, promptBuilder?: (text: string, context: string, agent: Agent) => string): StartResult;
+    /**
+     * Spawn a durable REVIEW turn under a synthetic session key (0288), so the
+     * reviewer survives a server reload the same way engineer/PM turns do: the
+     * child's stdout/stderr stream to durable log files and its PID is registered
+     * so the next server's `adoptRunningAgents()` re-attaches and replays any
+     * output written during the handoff. On completion — even post-reload —
+     * `cleanup()` fires `onReviewDone` for the owning ReviewManager to finalize.
+     *
+     * Unlike `start`/`send`, the review agent is deliberately NOT given
+     * `REPOOS_TASK_ID` / `REPOOS_API_URL`, preserving the read-only boundary that
+     * keeps it from reaching the control plane's task endpoints (review.ts layer
+     * 2). `kind: "review"` is persisted in the durable registry so adoption knows
+     * to re-attach as a review.
+     *
+     * `reset: true` (a fresh run) clears any prior conversation; a chat turn
+     * (`reset: false`, with `humanEntry`) continues the existing one.
+     */
+    startReview(sessionKey: string, agent: Agent, mission: string, cwd: string, opts?: {
+        humanEntry?: AgentOutputEntry;
+        reset?: boolean;
+        reviewKind?: "run" | "chat";
+    }): StartResult;
+    /** Release a durable review session from the in-memory map (its file stays). */
+    discardReviewSession(sessionKey: string): void;
+    /**
+     * Send a follow-up message to a task's session, resuming the same
+     * conversation as a new turn. Rejected when the task has no session yet
+     * (`ok: false`) or when a turn is already running (`ok: false, busy: true`).
+     */
+    send(taskId: string, text: string, agent: Agent, opts?: {
+        resumePreamble?: string;
+        skipBoardDivergence?: boolean;
+    }): StartResult;
+    /** The retained transcript for a task, or null when no session exists. */
+    output(taskId: string): Session | null;
+    /** Whether a session exists for a key (in memory or persisted on disk). */
+    hasSession(sessionKey: string): boolean;
+    /** Drop a session both in memory and from disk (a fresh review run). */
+    clearSession(sessionKey: string): void;
+    /**
+     * Mark a task transcript complete and release its RAM. If its child is still
+     * draining after a stop request, cleanup performs the final flush/eviction.
+     */
+    complete(taskId: string): void;
+    /** Flush all debounced transcript writes before shutdown/reload handover. */
+    flushAll(): void;
+    /**
+     * Gate for every spawnTurn call site: at capacity, defer the spawn
+     * instead of oversubscribing the machine. The caller still gets `ok: true`
+     * immediately — `queued: true` distinguishes "will run shortly" from
+     * "running now" without changing callers' happy-path handling. `id` is
+     * marked busy via queuedIds so a second start/send for the same task/chat
+     * while queued is rejected the same way an already-running one would be.
+     */
+    private spawnOrQueue;
+    /** Tasks/chats currently waiting for a free maxConcurrentAgents slot. */
+    queued(): {
+        id: string;
+        queuedAt: string;
+    }[];
+    /** Start the next queued spawn once a slot is free (called from cleanup() on every exit). */
+    private drainQueue;
+    /**
+     * Spawn one turn and attach streaming. Everything after the spawn is async;
+     * failures surface as agent.exited via cleanup.
+     */
+    private spawnTurn;
+    /** Line-buffer a chunk into the session transcript and stream it out. */
+    private onData;
+    /** Turn one buffered line into a transcript entry and stream it out. */
+    private appendLine;
+    /**
+     * Append a transcript entry, stream it out, and enforce the output cap.
+     * `sys` entries (self-heal notices) flow on the "out" stream, matching how
+     * parsed `error`/`file-update` events already surface as sys lines.
+     */
+    private recordEntry;
+    /**
+     * Per-line bookkeeping shared by every append path: fold any usage/cost the
+     * line reported into the session and reset the stall clock. Any output is
+     * evidence the process isn't hung, so it resets the silence clock and clears
+     * a stall warning immediately — the periodic check only ever needs to raise
+     * the flag, never lower it.
+     */
+    private lineTouched;
+    /**
+     * The claude stream-json branch of `appendLine` (0109). Recognized events
+     * map onto structured entries, or are swallowed when they have no transcript
+     * representation; anything else (a non-JSON `Warning: no stdin…` line, an
+     * unknown schema) falls back to the plain-line path so nothing the CLI said
+     * is lost.
+     */
+    private appendClaudeLine;
+    /** Copilot's JSONL branch; unlike Claude, tool start/finish events stand alone. */
+    private appendCopilotLine;
+    /** Codex has one completed item per tool/message rather than Claude blocks. */
+    private appendCodexLine;
+    /** The transcript entry for a tool_use whose result never arrived. */
+    private pendingToolEntry;
+    /**
+     * Whether a raw line carries the exact capability-request `signal` in plain
+     * or structured output. Codex `--json` wraps the final assistant response in
+     * an `item.completed` event, so the signal is matched inside `item.text` too,
+     * not just as a standalone line.
+     */
+    private signalPresent;
+    /** Recognize the exact handoff-request signal in plain or structured output. */
+    private isHandoffSignal;
+    /** Recognize the exact managed-preview request signal (#0121). */
+    private isPreviewRequestSignal;
+    /**
+     * Detect the runner's capability-request signals in one output line and act:
+     * the handoff signal is recorded for turn-end finalization, and the preview
+     * request is recorded for server-side start+probe at turn exit (#0121). The
+     * surfaced entry becomes a trusted system line so the raw signal text never
+     * clutters the transcript.
+     *
+     * When a handoff signal is recognized (#0235), the request is persisted to
+     * disk immediately so it survives an interrupted turn or server restart.
+     */
+    private applySignals;
+    /**
+     * Fold any usage/cost found in a raw output line into the session. Returns
+     * true when a stored value actually changed (so callers only emit stats when
+     * there's something new to show). Also appends the raw event to
+     * `session_usage_events` — the lossless ground truth this rollup derives from.
+     *
+     * Three fold modes, matching `foldUsage`:
+     *  - authoritative (claude `result`): the turn's real total FOR THIS PROCESS
+     *    — added onto `usageBaseline` (prior processes' totals for this same
+     *    session), not a bare overwrite, so a task resumed after review doesn't
+     *    see its cumulative cost/tokens drop back down.
+     *  - deltas (opencode `step_finish`): SUM — each event is one round-trip, and
+     *    `Math.max` would keep only the largest step (0109 undercounted a
+     *    17-step reviewer run's cache-reads ~15x). Deltas accumulate directly on
+     *    `cur`, so they're baseline-safe across process boundaries already.
+     *  - otherwise (codex/claude running totals): Math.max against this
+     *    process's own total plus baseline — count up, never flicker down on a
+     *    transient mid-stream figure, and never dip below a prior process's
+     *    total either.
+     */
+    private applyUsage;
+    /**
+     * Append one raw usage-bearing line to `session_usage_events` before it is
+     * folded. Skips lines that carried no usage figure at all (the vast majority
+     * — text, tool calls, step_start). Best-effort; keyed by the CLI's own
+     * session id when known, else the runner key, plus the resolved task id and a
+     * timestamp so rows always correlate to a `sessions` row.
+     */
+    private recordUsageEvent;
+    /** Emit the current live-stats snapshot for a task. */
+    private emitStats;
+    /** Compute a fresh stats snapshot — always safe to call, even with no session. */
+    private snapshotStats;
+    /**
+     * Periodic sweep (every `stallCheckIntervalMs`) over currently-running turns:
+     * raises the stall flag the moment silence crosses the threshold. Recovery
+     * (new output, or the turn exiting) is handled inline where it happens, so
+     * this only ever needs to turn the warning ON, never off.
+     * Also polls adopted entries (0214) for PID liveness: if the adopted PID
+     * died, clean up the entry so the task doesn't read as running forever.
+     */
+    private checkStalls;
+    private tryExtractSessionId;
+    /**
+     * Signal a running agent to stop: graceful SIGTERM first, SIGKILL after a
+     * short grace period. Returns immediately; the registry clears on exit.
+     */
+    stop(taskId: string): StopResult;
+    /**
+     * Interrupt a running AI chat response (PM, guide, debugger, …). Stops the
+     * in-flight agent process via {@link stop} and appends a persistent marker to
+     * the chat's transcript so the user sees the response was user-stopped rather
+     * than completed normally. Idempotent — safe to call when nothing is running.
+     *
+     * The marker is emitted server-side (so it survives a client hydrate, not just
+     * the live SSE stream) as a `sys` entry on the session. The agent's own exit
+     * also triggers the generic `agent.exited` "stopped" notice client-side.
+     */
+    interrupt(taskId: string): StopResult;
+    /** Record a session to the database. Best-effort, never fails the server. */
+    private recordSessionToDb;
+    /** Drop the registry entry for a task (idempotent) and announce it. */
+    private cleanup;
+    /**
+     * Post-run session-id capture for Kiro CLI (#0148). Kiro does not print its
+     * session id during the run; after the process exits we query the CLI's local
+     * session list for the cwd and take the most-recently-updated entry — that is
+     * the turn that just finished. Best-effort and fail-soft: any failure leaves
+     * sessionId undefined so the next turn falls back to `-r` (most-recent resume).
+     */
+    private captureKiroSessionId;
+    /**
+     * Snapshot a session's cumulative usage into `usageBaseline` right before a
+     * new CLI process is spawned for it (`start()` / `send()`), so an
+     * authoritative or running-total figure from THAT process — which starts
+     * counting at zero — is added onto prior processes' totals in `applyUsage`
+     * instead of replacing them.
+     */
+    private captureUsageBaseline;
+    private emptySession;
+    private sessionFile;
+    /** Read and validate one versioned file. Corruption/version drift fails soft. */
+    private readPersisted;
+    private loadSession;
+    /** Boot only hot lifecycle states; completed transcripts remain cold. */
+    private loadHotSessions;
+    private schedulePersist;
+    /** Atomic temp-file + rename write; persistence remains best-effort. */
+    private persist;
+    private finishCompletion;
+    /** Remove completed files older than the age bound or beyond the count cap. */
+    private pruneSessions;
+    /**
+     * True when two absolute paths denote the same directory (realpath-normalized
+     * when possible, so macOS /var vs /private/var aliases compare equal).
+     */
+    private samePath;
+    /**
+     * Persist a handoff failure reason to the task file's Activity log.
+     * Called when a handoff signal is expected but not detected, the process
+     * exits uncleanly before handoff can be finalized, or (from handoff.ts)
+     * server-side finalization itself fails. This persists the reason so it
+     * survives server reloads and lets the task watchdog classify the failure
+     * correctly instead of falling back to its generic guess (unlike
+     * in-memory transcript entries, which the watchdog cannot see).
+     */
+    persistHandoffFailure(taskId: string, task: Task | undefined, reason: string): void;
+    /**
+     * Best-effort one-line summary of why a turn failed. Prefers the last
+     * non-empty stderr line (where CLI-level failures like an expired OAuth
+     * session land), falling back to the last `sys`/error line RepoOS itself
+     * parsed out of the CLI's own JSON stream, then a generic fallback.
+     */
+    private lastFailureLine;
+    /**
+     * Flag a task for human attention the instant its agent turn ends non-
+     * cleanly (and isn't a deliberate pause or an in-flight handoff recovery —
+     * see the call site in cleanup()). Mirrors TaskWatchdog's own
+     * `needsInput` escalation, just fired immediately instead of waiting for
+     * the next staleness poll. Never overwrites an existing needsInput note.
+     *
+     * Also bumps `dev_error_count` — unlike the needsInput note, this always
+     * increments, even on a repeat error before a human clears the flag,
+     * because it counts real dev attempts, not distinct escalations (#0271
+     * follow-up: confirmed live on #0291 — an engineer session that errors out
+     * before ever reaching a review pass left `review_passes` at 0, so the
+     * board's `D# · R#` badge showed nothing for a task that genuinely had one
+     * failed dev round. TaskDrawer.vue's `taskRounds` folds this count into
+     * `dev` so D can exceed R when a round errored without being reviewed.)
+     */
+    private escalateFailedExit;
+    /**
+     * Self-heal the #0068 divergence. Narrowly scoped: ONLY the shape where the
+     * main checkout's copy of the task is still `active` but the agent's
+     * worktree copy shows `review` or `needs_input` backed by a real commit.
+     * Any other state (task moved by a human, uncommitted worktree edit, no
+     * separate worktree) is left untouched — this is not a general bidirectional
+     * sync. The correction is surfaced (server log + a task.corrected event +
+     * a transcript sys line) because it means the checklist itself failed.
+     */
+    private healBoardDivergence;
+}
+export {};