@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/pi.d.ts

@@ -0,0 +1,475 @@
+import type { EffortReport } from './effort.js';
+import { type ProgressGuardLimits } from './progress-guard.js';
+/**
+ * Per-completion output-token ceiling Pi requests (its model-entry `maxTokens`).
+ * Generous on purpose: a reasoning model (e.g. GLM-5.2) spends tokens on its
+ * `<think>` trace before the answer + tool calls, so a tight cap truncates it
+ * mid-reasoning and the agent never commits edits. It is a ceiling, not a target
+ * — unused output tokens are not billed and Workers AI clamps the request to the
+ * model's real max — so erring high is safe. Raised to 32k after a spec-writer run
+ * truncated an intermediate tool call at the old 16k cap; the document itself
+ * stopped well under it, so this is headroom for larger specs/diffs, with
+ * {@link runDiagnostics} flagging the rare case where even 32k is not enough.
+ */
+export declare const PI_MAX_OUTPUT_TOKENS = 32768;
+/**
+ * Normalise a phase label to what the backend will actually store: trimmed, lowercased,
+ * `[a-z0-9-]` only, bounded. `''` when the label is not a phase at all.
+ *
+ * A deliberate COPY of kernel's `normalizeCallPhase` — the container image is built from `src/`
+ * plus typescript alone, so the harness can carry no runtime dependency on a workspace package
+ * (the same constraint that forced `src/host-markdown.ts`). A copy that can drift is worse than
+ * no copy: if the harness rejected a label the backend would have accepted, the call would take
+ * the plain path and land unattributed, and if it accepted one the backend rejects it would
+ * spend a request on a segment destined for `''`. `test/llm-phase.conformity.test.ts` pins the
+ * two to identical verdicts over a corpus, so the alphabet can only be changed in both.
+ */
+export declare function normalizeProxyPhase(phase: string | undefined): string;
+/**
+ * Point Pi's provider at the phase-tagged completions path for the pass about to run, so the
+ * backend can stamp WHICH slice of the run spent each call (the agent's own loop vs a pre-PR
+ * validation repair round vs a reproduction-proof repair round) — see
+ * `docs/initiatives/token-burn-instrumentation.md`. The harness drives those loops, so it is
+ * the only component that knows; reconstructing the boundary downstream from wall-clock
+ * timestamps is exactly the brittle inference this avoids.
+ *
+ * A URL segment because the harness does not make these requests: Pi does, from a config whose
+ * only per-run knobs are the base URL and the token — there is no per-request header to set.
+ *
+ * `supported` is the BACKEND's declaration that it serves the phase-tagged route, carried on the
+ * job body exactly as `webSearch` carries "point the search tool at my `/web-search`". Without it
+ * this function would encode a routing shape the receiving backend may not have: a runner pool
+ * pins its OWN harness image (`RunnerPoolManifest`), and `LOCAL_HARNESS_IMAGE` overrides the
+ * recommended pin outright, so "the image and the backend are a matched set" holds for the
+ * Cloudflare deployment and nowhere else. An image ahead of its backend would 404 EVERY model
+ * call — a dead run, not degraded telemetry. Absent/false ⇒ the plain path, and the calls land
+ * in the backend's unattributed slice.
+ *
+ * Pure so the join is unit-testable without spawning anything.
+ */
+export declare function phasedProxyBaseUrl(proxyBaseUrl: string, phase: string | undefined, supported: boolean | undefined): string;
+/** Write the Pi provider config that routes all model calls through the proxy. */
+export declare function writePiModelsConfig(opts: {
+    model: string;
+    proxyBaseUrl: string;
+    /** Output-token ceiling Pi may request per completion. Defaults to PI_MAX_OUTPUT_TOKENS. */
+    maxTokens?: number;
+}): Promise<string>;
+/**
+ * Write the composed system prompt as Pi's GLOBAL agent context
+ * (`~/.pi/agent/AGENTS.md`), which Pi reads automatically and concatenates with
+ * any `AGENTS.md`/`CLAUDE.md` the repo itself ships (global file first, then the
+ * ones walked up from the run cwd). Deliberately OUTSIDE the checkout (the same
+ * `~/.pi/agent` dir `writePiModelsConfig` already uses) so the harness's
+ * instructions never enter the git working tree — they can't be committed into a
+ * PR and they never clobber a repo's own committed `AGENTS.md`.
+ *
+ * This relies on Pi's context-file resolution: the global `~/.pi/agent/AGENTS.md`
+ * is loaded before the project-trust decision, so it applies in non-interactive
+ * (`-p`) runs without a trust prompt. That contract is pinned by `PI_VERSION` in
+ * the Dockerfile — revisit this if that bump changes context-file resolution.
+ */
+export declare function writeAgentsContext(systemPrompt: string, opts?: {
+    webSearch?: boolean;
+    guidance?: string;
+    serviceDirectory?: string;
+    contextFiles?: ContextFileInfo[];
+    multiRepo?: boolean;
+    /**
+     * Whether the checkout actually ships a `blueprints/` folder. The blueprint orientation
+     * note is only appended when it does — otherwise it is ~10 lines of dead guidance (re-sent
+     * every turn) pointing at files that don't exist. Absent/false ⇒ the note is omitted.
+     */
+    hasBlueprints?: boolean;
+}): Promise<void>;
+/** Directory in the checkout where linked-context files are materialised (see CONTEXT_DIR in agents). */
+export declare const CONTEXT_DIR = ".cat-context";
+/** The metadata the AGENTS.md context block needs to point an agent at a materialised file. */
+export interface ContextFileInfo {
+    path: string;
+    title: string;
+    url: string;
+    content: string;
+}
+/**
+ * Write the backend-prepared linked-context files into {@link CONTEXT_DIR} in the
+ * checkout so the agent can read them on demand, and add a LOCAL git exclude entry so
+ * even `git add -A` never commits them into the agent's PR. Best-effort on the exclude
+ * (a scaffold-from-scratch checkout has no `.git` yet — the files just stay untracked).
+ */
+export declare function materializeContextFiles(cwd: string, files: ContextFileInfo[]): Promise<void>;
+/** Subdirectory of {@link CONTEXT_DIR} where a skill's resources are materialised, per skill. */
+export declare const SKILL_CONTEXT_SUBDIR = "skill";
+/**
+ * Materialise the run's skills' RESOURCE files under `.cat-context/skill/<name>/` in the checkout
+ * — the path for every run that does NOT get a native install: Pi, codex, and ambient claude-code
+ * (no isolated `CLAUDE_CONFIG_DIR` to install into). Their agents read the checkout, and the
+ * skills' instructions are folded into their prompt by the backend (`renderSkillsForHarness`,
+ * which keys off ambient auth as well as the harness).
+ *
+ * Each skill gets its OWN subdirectory: several skills can apply to one run (a step's pick plus
+ * the kind's declared playbooks), and a flat directory would let two skills' `templates/report.md`
+ * overwrite each other — silently handing the agent the wrong template. The names were sanitized
+ * to a single safe path segment at the job boundary, as were the resource sub-paths (no
+ * traversal), so nested dirs are created as needed. Kept out of the agent's commits via the same
+ * `.cat-context/` git exclude entry. Skills with no resource bodies are a no-op.
+ */
+export declare function materializeSkillResources(cwd: string, skills: {
+    name: string;
+    resources: {
+        relPath: string;
+        content: string;
+    }[];
+}[]): Promise<void>;
+/**
+ * The active web-search backend for the rpiv-web-tools extension. Only the
+ * provider id is persisted to disk: the per-provider credential (and any base URL
+ * — `SEARXNG_URL`, `OLLAMA_HOST`) is read by the extension straight from the
+ * environment, so no key is ever written to the container's filesystem.
+ */
+export interface WebSearchConfig {
+    /** rpiv-web-tools provider id, e.g. `brave`, `tavily`, `exa`, `searxng`. */
+    provider: string;
+}
+/**
+ * Resolve the web-search configuration from the environment, or undefined when no
+ * provider is configured (⇒ the harness writes no rpiv-web-tools config and never
+ * nudges the agent towards the tools, so runs behave exactly as before). Enablement
+ * is CONDITIONAL on a provider being configured: if any provider's credential/URL
+ * env var is present, web search turns on with that provider (highest-priority one
+ * when several are set). `WEB_SEARCH_PROVIDER` is an explicit override that pins the
+ * active provider regardless of detection — but only when that provider's own
+ * credential/URL is also present, so a pin without a key never nudges the agent
+ * towards a tool that would error the moment it's called. No key passes through here
+ * — the extension reads each provider's own env var directly.
+ */
+export declare function webSearchConfigFromEnv(env?: NodeJS.ProcessEnv): WebSearchConfig | undefined;
+/**
+ * The env that points the rpiv-web-tools SearXNG provider at the backend's
+ * search proxy: `SEARXNG_URL` = `${proxyBaseUrl}/web-search` (the controller mounted
+ * under the LLM proxy's `/v1`), and `SEARXNG_API_KEY` = the per-job session token,
+ * which the proxy verifies exactly like the LLM proxy. Handed to Pi's child via
+ * `runPi`'s `extraEnv`, so the search key never has to enter the sandbox — the search
+ * runs server-side under the deployment's own provider key.
+ */
+export declare function webSearchProxyEnv(proxyBaseUrl: string, sessionToken: string): {
+    SEARXNG_URL: string;
+    SEARXNG_API_KEY: string;
+};
+/**
+ * Select the active rpiv-web-tools provider by writing
+ * `~/.config/rpiv-web-tools/config.json` (the file the extension reads, falling
+ * back to `brave` when `provider` is absent). Only the provider id is written —
+ * credentials and base URLs come from the environment (env wins over the file in
+ * the extension's own resolution order), so no secret is committed to disk. Written
+ * 0600 to match the extension's own permissions for that path.
+ */
+export declare function writeWebToolsConfig(config: WebSearchConfig): Promise<string>;
+/** One entry of the agent's todo list — its subject and current status. */
+export interface TodoItem {
+    /** The task's subject text, as the agent wrote it. */
+    label: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+/** Live subtask progress derived from Pi's `todo` tool — e.g. "3/8 done". */
+export interface TodoProgress {
+    /** Tasks marked completed. */
+    completed: number;
+    /** Tasks currently being worked (rpiv-todo's `in_progress` status). */
+    inProgress: number;
+    /** Total live tasks (tombstoned/deleted tasks excluded). */
+    total: number;
+    /**
+     * The individual live tasks (label + status), in list order — so the board can
+     * render the actual task list, not just the count. Absent for the simpler
+     * `todos[].done` fallback shape, which carries no per-task subject.
+     */
+    items?: TodoItem[];
+}
+/**
+ * One tool invocation in Pi's loop, captured for the run's observability trace.
+ * Metadata only (name + timing + ok) — never the tool's args or result — so the
+ * harness buffer stays tiny. The backend drains these on its existing job poll and
+ * emits them as child spans under the run trace.
+ */
+export interface ToolSpan {
+    tool: string;
+    /** Epoch ms the tool call started (approximated as the previous tool's end). */
+    startedAt: number;
+    /** Epoch ms the tool call ended (when its `tool_execution_end` event arrived). */
+    endedAt: number;
+    ok: boolean;
+}
+/**
+ * What the agent actually did this run, independent of any file changes. Used to
+ * tell a genuine no-op (the agent never reached the model / never acted) apart
+ * from a real run, so a bootstrap that produced nothing is failed rather than
+ * pushed as an empty repo. `toolCalls === 0 && assistantChars === 0` is the
+ * signature of a run where Pi never made a successful model call.
+ */
+export interface PiRunStats {
+    /** Tool calls the assistant emitted across the transcript (0 ⇒ it never acted). */
+    toolCalls: number;
+    /** Total characters of assistant text (0 ⇒ the model produced nothing). */
+    assistantChars: number;
+}
+/**
+ * Output-quality signals lifted from the agent's transcript, so the harness can fail
+ * LOUDLY on a malformed run instead of silently handing a half-baked artifact to the
+ * structured-output repair (which would manufacture a doc from garbage — the trap
+ * behind the spec-writer ⇄ companion rework loop). Two distinct invalid states, both
+ * seen in production from `kimi-k2.7-code`:
+ *  - a completion that hit the output ceiling (its answer/tool call was cut off), and
+ *  - a FINAL turn that carried no text at all (an empty `content: []` despite spending
+ *    output tokens), so there is no answer to parse.
+ */
+export interface RunDiagnostics {
+    /** Some completion ended at the output-token ceiling — its content was cut off. */
+    truncated: boolean;
+    /** The agent's FINAL completion hit the ceiling: its ANSWER (not a mid-run step) was cut off. */
+    finalTruncated: boolean;
+    /** The agent's final turn carried no text content (e.g. an empty `content: []`). */
+    finalAnswerEmpty: boolean;
+}
+/**
+ * One model call captured from a subscription harness's CLI event stream, shaped so
+ * the backend can record it into the same `llm_call_metrics` telemetry the LLM proxy
+ * writes for the Pi harness. The subscription harnesses (Claude Code / Codex) talk
+ * DIRECT to the vendor and never touch the proxy, so this is the only place their
+ * per-call bodies are observable. Claude Code's `stream-json --verbose` is a near-
+ * verbatim Anthropic Messages stream, so its calls carry full request/response
+ * bodies; Codex's `exec --json` only surfaces flat assistant text + per-turn tokens,
+ * so its rows are honestly thinner (no request transcript, no tool/command bodies).
+ */
+export interface HarnessCallMetric {
+    /** The vendor model that served this call (from the CLI event), when reported. */
+    model?: string;
+    /**
+     * The full request as an OpenAI-style chat array (`[{role, content}, …]`),
+     * JSON-stringified — the growing history as of this call. Matches the proxy's
+     * `promptText` shape so the telemetry chain delta-compresses + renders identically.
+     */
+    promptText: string;
+    /** Number of messages encoded in {@link promptText} (the telemetry chain messageCount). */
+    messageCount: number;
+    /** The assistant's response text, as a plain string (`''` for a tool-only turn). */
+    responseText: string;
+    /** The reasoning/thinking trace, as a plain string (`''` when none). */
+    reasoningText: string;
+    /**
+     * FRESH (uncached) input tokens: exclusive of BOTH cache classes below, so the three
+     * are orthogonal and additive. Every producer normalises to this — reading the already
+     * exclusive field where the vendor reports the classes apart (Anthropic), subtracting
+     * the cached share where the vendor reports an inclusive prompt count (Codex/OpenAI).
+     */
+    inputTokens: number;
+    /** Input tokens served from the vendor's prompt cache (~0.1× base input). */
+    cacheReadTokens: number;
+    /**
+     * Input tokens written INTO the vendor's cache (1.25–2× base input — dearer than fresh),
+     * kept apart from the reads so a loop that keeps re-writing the prefix is distinguishable
+     * from one riding a warm cache. 0 where the CLI reports no separate write class.
+     */
+    cacheWriteTokens: number;
+    outputTokens: number;
+    /** The provider finish/stop reason when the CLI reports one (else null). */
+    finishReason: string | null;
+    /**
+     * This call's position in the JOB's telemetry sequence, stamped by the job registry the
+     * moment the call is emitted (see `RunOptions.onCallMetric`). It is what makes a call's
+     * recorded row id stable across the two channels that carry it: the live drain (per poll,
+     * so a run's telemetry is inspectable WHILE it runs) and the terminal result (the complete
+     * list, so a transport that doesn't drain still records everything). Both channels hold the
+     * SAME metric objects, so both mint the same `<jobId>-hc-<seq>` row id and the backend's
+     * second write of an already-recorded call is a no-op instead of a duplicate row.
+     *
+     * Absent only when a producer built a metric without emitting it live; the recorder then
+     * falls back to the array index, which is what it always used before streaming existed.
+     */
+    seq?: number;
+    /**
+     * The run PHASE that spent this call (`agent` / `validation-repair` / `reproduction-repair` /
+     * …), stamped by the job registry from the same marker the handlers set as they enter each
+     * phase — so the phase axis on `llm_call_metrics` comes from the component that owns the
+     * boundary rather than from a downstream guess
+     * (`docs/initiatives/token-burn-instrumentation.md`).
+     *
+     * Stamped on the SAME object as {@link seq}, so the live drain and the terminal result can
+     * never disagree about which phase billed a call.
+     */
+    phase?: string;
+}
+/**
+ * Publish one captured model call: append it to the run's list (which becomes the terminal
+ * result's `callMetrics`) AND hand the SAME object to the live stream, where the job registry
+ * stamps its {@link HarnessCallMetric.seq} and buffers it for the next poll to drain.
+ *
+ * Every producer goes through here rather than a bare `calls.push`, so the two channels can't
+ * drift: a call that reaches the terminal list but never the live stream would be invisible
+ * until the job ends, and one that reaches only the live stream would go unrecorded if the
+ * poll response were lost.
+ *
+ * A published call must be FINAL. The backend records it the moment the drain reaches it and
+ * IGNORES the terminal repeat (first write wins, so its stored prompt delta stays valid against
+ * the chain tip it was written against), which means a field mutated after publishing never
+ * reaches the store. A producer whose calls can still change (the cumulative-usage fallback,
+ * whose totals arrive with the CLI's terminal `result` event) publishes through
+ * {@link createCallMetricPublisher} instead, which withholds exactly those.
+ */
+export declare function publishCallMetric(calls: HarnessCallMetric[], call: HarnessCallMetric, onCallMetric?: (call: HarnessCallMetric) => void): void;
+/** Appends captured calls to a run's list, streaming each one as soon as it is final. */
+export interface CallMetricPublisher {
+    /** Append a captured call, streaming it now unless its tokens can still be rewritten. */
+    publish(call: HarnessCallMetric): void;
+    /** Stream whatever is still withheld. Call once the run's totals are attributed. */
+    flush(): void;
+}
+/**
+ * A {@link publishCallMetric} wrapper for a producer whose per-call tokens may be filled in at
+ * the END of the run: a CLI that reports only a cumulative total leaves every turn at zero, and
+ * `attributeCumulativeUsage` pins the total onto the last call once the terminal `result` event
+ * arrives.
+ *
+ * Since a published call must be final (the backend stores it on the drain and ignores the
+ * terminal repeat), a call the CLI did NOT cost is appended to the list but WITHHELD from the
+ * live stream — otherwise it records as a zero-token row and the attributed numbers never land.
+ * The withholding window closes the moment any call IS costed: attribution can no longer fire, so
+ * everything held is final and released at once, in capture order, and every later call streams
+ * immediately whatever its tokens. {@link flush} covers the run that was never costed at all.
+ */
+export declare function createCallMetricPublisher(calls: HarnessCallMetric[], onCallMetric?: (call: HarnessCallMetric) => void): CallMetricPublisher;
+/** Pi's assistant summary plus {@link PiRunStats} describing what it did. */
+export interface PiRunOutcome {
+    summary: string;
+    stats: PiRunStats;
+    /**
+     * Tail of Pi's stderr (credential-scrubbed), captured even on a clean exit.
+     * On a no-op run this is where the real cause shows up — e.g. an unreachable
+     * proxy or a model the upstream rejected — so the failure is diagnosable
+     * without shelling into the (ephemeral) container.
+     */
+    stderrTail?: string;
+    /**
+     * Token usage lifted from the agent CLI's own event stream. Reported by the
+     * subscription harnesses (Claude Code / Codex), whose traffic bypasses the LLM
+     * proxy — so the backend folds it into the leased token's rolling-window counters
+     * (usage-aware rotation) and telemetry. Absent for the proxy-metered Pi harness.
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /**
+     * Per-model-call telemetry lifted from a subscription harness's CLI event stream
+     * (Claude Code / Codex), which the backend records into `llm_call_metrics` — the
+     * proxy-bypassing analogue of the per-call rows the LLM proxy writes for Pi. Absent
+     * for the proxy-metered Pi harness (the proxy is its metering point). See
+     * {@link HarnessCallMetric}.
+     */
+    callMetrics?: HarnessCallMetric[];
+    /** Output-quality signals (truncation / empty final answer); see {@link RunDiagnostics}. */
+    diagnostics?: RunDiagnostics;
+    /**
+     * The agent's effort self-assessment, lifted from its sentinel file after the run (how hard the
+     * work was, what reduced its effectiveness, the key obstacles). Absent when the agent wrote none.
+     * See {@link EffortReport}.
+     */
+    effortReport?: EffortReport;
+}
+export declare function parseTodoProgress(event: Record<string, unknown>): TodoProgress | undefined;
+/**
+ * Run Pi non-interactively against `cwd` and return its assistant summary. Uses
+ * print + JSON mode (`-p --mode json`) with `--approve` so it runs unattended.
+ *
+ * The (untrusted) prompt is fed over stdin, never as an argv positional, so a
+ * prompt beginning with `-`/`--` can't be mis-parsed as a Pi CLI flag (Pi has no
+ * `--` end-of-options terminator, so a positional `-foo` errors as "Unknown
+ * option"). Pi's print mode reads the prompt from piped stdin; we write it and
+ * close the pipe so Pi gets an immediate EOF and proceeds (an open, never-closed
+ * stdin pipe would make print mode block forever waiting for EOF).
+ */
+export declare function runPi(opts: {
+    cwd: string;
+    model: string;
+    userPrompt: string;
+    sessionToken: string;
+    /** Aborting this kills Pi (the job's inactivity/max-duration watchdog). */
+    signal?: AbortSignal;
+    /** Called on every chunk of Pi output, so the watchdog sees the agent is alive. */
+    onActivity?: () => void;
+    /** Called with the latest subtask counts each time Pi updates its todo list. */
+    onProgress?: (progress: TodoProgress) => void;
+    /**
+     * Called once per completed tool call with a compact {@link ToolSpan}. Feeds the
+     * run's observability trace (drained by the backend on its job poll); a no-op when
+     * the container payload doesn't pass it, so production behaviour is unchanged.
+     */
+    onSpan?: (span: ToolSpan) => void;
+    /**
+     * Called with every parsed Pi `--mode json` event, in stream order — the raw
+     * observability seam over the run. Used by offline tooling (the smoketest
+     * harness) to capture the full prompt/response/tool-call transcript for
+     * analysis; the container payload doesn't pass it, so production behaviour is
+     * unchanged. Throwing handlers are swallowed so a faulty observer can't break
+     * the run.
+     */
+    onEvent?: (event: Record<string, unknown>) => void;
+    /** No-progress guard bounds; defaults to the env-configured limits. */
+    guardLimits?: ProgressGuardLimits;
+    /** Whether this run is expected to edit files (false for assess-only runs like the merger). */
+    expectsEdits?: boolean;
+    /**
+     * Extra environment for Pi's child process, merged over `process.env` (but under the
+     * proxy token). Used to hand the rpiv-web-tools extension its proxy-backed SearXNG
+     * config (`SEARXNG_URL` / `SEARXNG_API_KEY`) without mutating the harness's own env.
+     */
+    extraEnv?: Record<string, string>;
+}): Promise<PiRunOutcome>;
+/**
+ * The terminal-failure message when Pi's run ended in a hard error (the model was
+ * unreachable / refused, and Pi exhausted its auto-retries), else undefined. Only
+ * the FINAL outcome counts: a mid-run hiccup the agent recovered from leaves a clean
+ * terminal `agent_end`, so it returns undefined. Scans from the end and decides on
+ * the first terminal signal it meets — the trailing `auto_retry_end` (its `success`
+ * flag) or the last `agent_end` (its `stopReason`). Pure so it is unit-testable over
+ * a fixed event sequence.
+ */
+export declare function terminalRunError(stdout: string): string | undefined;
+/**
+ * Classify a terminal run error whose text points at the LLM PROXY rejecting every model call
+ * (auth / quota / rate-limit) into an actionable remedy, else undefined. All model traffic goes
+ * through the Worker's OpenAI-compatible proxy, so a 401/402/429 surfaced in Pi's `finalError`
+ * means the leased provider key was refused, is out of credit, or was rate-limited — none of
+ * which is an agent bug. This is the first-wrap-point for Pi's own error text (per the
+ * error-message initiative's I6): we match it ONCE here and let the caller stamp the structured
+ * `llm-upstream` cause + this remedy. Pure, so it is unit-tested over fixed error strings.
+ */
+export declare function classifyLlmUpstreamError(finalError: string): string | undefined;
+/**
+ * Pi's assistant summary plus {@link PiRunStats}, derived from one pass over its
+ * output — the canonical close-of-run signal the harness uses both to report the
+ * answer and to detect a no-op run (the agent never acted).
+ */
+export declare function summarizePiRun(stdout: string): PiRunOutcome;
+/**
+ * Output-quality signals over the canonical `agent_end` transcript: whether any
+ * completion hit the output ceiling (its content was cut off), whether the FINAL
+ * completion did, and whether that final turn carried no text at all. Pure so it is
+ * unit-testable over a fixed event sequence. Defaults to all-false when there is no
+ * terminal transcript (a no-op run is already caught by {@link agentNeverActed}).
+ *
+ * `cap` is the per-completion ceiling Pi requested ({@link PI_MAX_OUTPUT_TOKENS});
+ * truncation is detected by an assistant message whose `usage.output` reached it,
+ * which is reliable even when the model reports a non-`length` stop reason (Workers
+ * AI labelled a cut-off tool call `tool_calls`, not `length`).
+ */
+export declare function diagnosticsFromEvents(events: Record<string, unknown>[], cap?: number): RunDiagnostics;
+/** {@link RunDiagnostics} over Pi's raw `--mode json` stdout (see {@link diagnosticsFromEvents}). */
+export declare function runDiagnostics(stdout: string, cap?: number): RunDiagnostics;
+/**
+ * Extract the assistant's final summary from Pi's JSON-lines output. Pi emits a
+ * terminal `agent_end` event whose `messages` is the full transcript, so the
+ * last assistant message there is the canonical answer. Falls back to scanning
+ * `message_end` events, then to a raw tail, so a schema tweak never loses output.
+ */
+export declare function parsePiOutput(stdout: string): string;

package/dist/pr-description.d.ts

@@ -0,0 +1,85 @@
+/** The sentinel file the agent writes its PR description to (relative to the checkout root). */
+export declare const PR_DESCRIPTION_FILE = ".cat-pr-description.md";
+/**
+ * Ceiling on the agent-authored body.
+ *
+ * The engine appends its verification report to the SAME body later, and that section carries
+ * its own 50,000-character ceiling (`MAX_SECTION_CHARS` in kernel's `hostMarkdown`). GitHub
+ * rejects a body over 65,536 with a 422, and the report publisher swallows its own failures —
+ * so a briefing budget that does not leave the report room would surface as a report that
+ * silently never publishes. 15,000 + 50,000 stays under the limit with room to join them.
+ *
+ * Exported because the PR-TEMPLATE note states it to the agent (`pr-template.ts`): a filled
+ * template is the one briefing shape whose length is dictated by a file the agent did not write,
+ * so an agent that does not know the ceiling can answer a long template past it and have
+ * {@link capBody} cut the repo's last sections — the very failure the inline budget avoids on the
+ * way IN.
+ */
+export declare const MAX_PR_BODY_CHARS = 15000;
+/** Opens the engine-managed region of a PR body (kept in sync with `kernel/domain/pr-report.ts`). */
+export declare const PR_REPORT_MARKER_START = "<!-- cat-factory:verification-report:start -->";
+/** Closes the engine-managed region of a PR body. */
+export declare const PR_REPORT_MARKER_END = "<!-- cat-factory:verification-report:end -->";
+/** An agent-authored PR description: an optional title plus the briefing body. */
+export interface AgentPrDescription {
+    title?: string;
+    body?: string;
+}
+/** How to read a sentinel. */
+export interface ReadPrDescriptionOptions {
+    /**
+     * Whether a lone leading `# <title>` heading may be lifted off as the PR title (see
+     * {@link splitTitle}). Default `true` — that is what the description guidance asks a free-form
+     * briefing for.
+     *
+     * FALSE when the briefing is a FILLED TEMPLATE (`pr-template.ts`): then the headings are the
+     * repo's, not the agent's, and a template whose first heading is its only level-1 one — `#
+     * Pull Request` above a set of `##` sections, an entirely ordinary shape — would have that
+     * heading silently become the pull request's title, so the PR reads "Pull Request" instead of
+     * `<block> (<pipeline>)` and the body loses the heading the repo asked for. The heuristic below
+     * is sound for the shape the guidance describes and cannot be made to cover both, so the caller
+     * that KNOWS which shape it asked for says so.
+     */
+    titleFromHeading?: boolean;
+}
+/**
+ * Read + parse + REMOVE the agent's PR-description sentinel from `dir`. Lenient: returns
+ * undefined when the file is absent (the agent wrote none) or carries nothing usable. Never
+ * throws — a bad description must never fail an otherwise-good run; the caller falls back to
+ * the dispatch-time text.
+ *
+ * A SINGLE `# <title>` heading on the first line sets the PR title; everything after it is the
+ * body (see {@link splitTitle} for why a LONE heading is required, and
+ * {@link ReadPrDescriptionOptions.titleFromHeading} for the caller that must switch it off). The
+ * whole text is secret-scrubbed, an over-budget body is truncated WITH a visible note (a silent
+ * cut would read as the complete briefing), and both halves are made inert for the host.
+ *
+ * On scrubbing: `redactSecrets`'s credential-assignment rule is deliberately eager, so a
+ * briefing sentence like "the token: handling changed" loses its next word. That is the right
+ * trade for a surface this public — the rule is shared with every other redaction path, and
+ * narrowing it so prose reads better would weaken all of them.
+ */
+export declare function readPrDescription(dir: string, opts?: ReadPrDescriptionOptions): Promise<AgentPrDescription | undefined>;
+/**
+ * Fold an agent-authored description over the dispatch-time fallback the job body carries.
+ * Field-wise: the agent's title/body each win when present, so a body-only briefing keeps the
+ * backend-composed title and vice versa.
+ */
+export declare function applyPrDescription(fallback: {
+    title: string;
+    body: string;
+}, agent: AgentPrDescription | undefined): {
+    title: string;
+    body: string;
+};
+/**
+ * The body to PATCH onto an ALREADY-OPEN pull request when a resumed run produced a fresh
+ * briefing: the new description followed by whatever the engine's managed verification-report
+ * region currently holds.
+ *
+ * Carrying the region across is what makes the refresh safe. The engine re-publishes the report
+ * on every step settlement, so dropping it here would usually self-heal — but "usually" is not
+ * a property to rest the one artefact a reviewer reads on, and a run that settles no further
+ * step (the work is already merged, the run failed after its push) would never restore it.
+ */
+export declare function preserveManagedSection(currentBody: string | undefined, nextBody: string): string;

package/dist/pr-template.d.ts

@@ -0,0 +1,101 @@
+import type { RepoSpec } from './job.js';
+import type { Logger } from './logger.js';
+/** The VCS providers a repo can live on. Bound to `RepoSpec` so the two cannot drift. */
+type ProviderName = NonNullable<RepoSpec['provider']>;
+/**
+ * How much template text is inlined into the agent's prompt.
+ *
+ * Over this, the template is NAMED rather than inlined and the agent is told to read it from the
+ * checkout — which it can, because the file is on disk. That is strictly better than the
+ * alternatives: truncating a template would have the agent fill a structure whose tail it never
+ * saw (silently dropping the repo's last sections), and skipping it entirely would abandon the
+ * feature on exactly the repos with the most demanding process.
+ */
+export declare const MAX_INLINE_PR_TEMPLATE_CHARS = 8000;
+/**
+ * The shared inline budget across a multi-repo run's legs. Each repo's template competes for it in
+ * leg order, and a leg that does not fit is NAMED rather than inlined (as above) — so a workspace
+ * of four template-carrying repos cannot quietly consume 32k of the agent's prompt.
+ */
+export declare const MAX_TOTAL_INLINE_PR_TEMPLATE_CHARS = 12000;
+/** A discovered pull-request template. */
+export interface PrTemplate {
+    /** Repo-root-relative path, forward-slashed (it is prose an agent reads). */
+    path: string;
+    /**
+     * The template's size. ALWAYS the real one, including when {@link text} is absent: an over-budget
+     * template reporting `chars: 0` would read in the log exactly like an empty file, which is the
+     * one thing discovery treats as "no template at all".
+     */
+    chars: number;
+    /** The template text. Absent ⇒ over budget, so the agent is told to read {@link path} itself. */
+    text?: string;
+}
+/** One checkout to look for a template in. */
+export interface PrTemplateTarget {
+    /** The repository checkout root (NOT a monorepo service subtree — a template is a repo fact). */
+    repoDir: string;
+    provider?: ProviderName;
+    /** Names this repo in the note. Omit when the run has a single checkout ("this repository"). */
+    repoLabel?: string;
+}
+/** What {@link resolvePrTemplateNote} tells the run about the templates it found. */
+export interface PrTemplateResolution {
+    /** The prompt note, or absent when no target ships a template (which is most repos). */
+    note?: string;
+    /**
+     * The `repoDir`s whose briefing is a FILLED TEMPLATE. The push phase reads those sentinels with
+     * `titleFromHeading: false`, because the headings in them are the repo's — see
+     * `ReadPrDescriptionOptions.titleFromHeading`. A SET keyed by directory rather than a boolean
+     * because a multi-repo run's legs need not all ship a template.
+     */
+    templated: ReadonlySet<string>;
+}
+/**
+ * THE entry point: find each target's pull-request template and build the prompt note that asks
+ * the agent to fill it, plus the set of checkouts whose sentinel will therefore hold a filled
+ * template rather than a free-form briefing (see {@link PrTemplateResolution}).
+ *
+ * Pass NO targets for a dispatch that opens no pull request — an in-place fixer amending someone
+ * else's PR, a read-only explore run. Asking such a run to fill a template would be asking for a
+ * document nothing publishes.
+ *
+ * Never rejects: a template is an improvement to a PR body, so no failure reading one may cost a
+ * run that otherwise succeeded. An unreadable or empty template is simply no template.
+ */
+export declare function resolvePrTemplateNote(args: {
+    targets: PrTemplateTarget[];
+    logger: Logger;
+}): Promise<PrTemplateResolution>;
+/**
+ * Locate the template in `repoDir`, probing the repo's OWN host convention first and the other
+ * host's second — a repo mirrored across both, or one whose provider the dispatcher did not set,
+ * still gets its template respected rather than falling to whichever list happened to be first.
+ */
+export declare function discoverPrTemplate(repoDir: string, provider?: ProviderName): Promise<PrTemplate | undefined>;
+/**
+ * The prompt note. It has to do more than show the template, because the agent has already been
+ * told (by the backend-composed `PR_DESCRIPTION_GUIDANCE`) to write a free-form briefing, and the
+ * two genuinely conflict: a template that asks for a test plan or a checklist is asking for
+ * exactly the "restated diff" that guidance rules out. So the note states which wins, and states
+ * why the template is not already applied — an agent that believes the host will merge the
+ * template with its text has no reason to reproduce the structure itself.
+ *
+ * The template is delimited with `fencedOutput`, the same helper every other captured-text-into-a-
+ * prompt path uses. Templates routinely carry fenced blocks of their own, and a fixed three-tick
+ * wrapper closes on the first of them — spilling the rest of the template, and the instructions
+ * after it, into the prompt as prose. `fencedOutput` sizes the fence one tick longer than the
+ * longest run in the body, which is what CommonMark specifies for exactly this, so no template can
+ * break out of its own block. A plain `--- BEGIN/END ---` rule would read more nicely and is
+ * trivially forgeable by the template's own content, which is the whole thing being defended.
+ */
+export declare function buildPrTemplateNote(template: PrTemplate, repoLabel?: string): string;
+/**
+ * Fold the note into a prompt. The sibling of `withDependencyNote`, and deliberately not inlined
+ * for the same reason: it rides EVERY agent pass, including the validation and reproduction
+ * REPAIR passes. Those start a fresh agent that still carries the description guidance in its
+ * system prompt, so one that is not also told about the template would rewrite the briefing
+ * free-form and undo the filled template the first pass produced.
+ */
+export declare function withPrTemplateNote(userPrompt: string, note: string | undefined): string;
+export {};