@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/logger.d.ts

@@ -0,0 +1,16 @@
+type Fields = Record<string, unknown>;
+/** The logging surface: the four levels plus `child` to bind correlation fields once. */
+export interface Logger {
+    debug: (msg: string, fields?: Fields) => void;
+    info: (msg: string, fields?: Fields) => void;
+    warn: (msg: string, fields?: Fields) => void;
+    error: (msg: string, fields?: Fields) => void;
+    /**
+     * Return a logger that merges `bound` into every line (e.g. `{ jobId, repo, branch }`),
+     * so a per-job logger carries its correlation context without each call site re-spreading
+     * it. Nestable — the returned logger's own `child` accumulates onto these bound fields.
+     */
+    child: (bound: Fields) => Logger;
+}
+export declare const log: Logger;
+export {};

package/dist/onboarding-preseed.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from './logger.js';
+/**
+ * The onboarding gates we pre-accept in a fresh config home. Kept as a single constant so
+ * the write and the assertion below can never drift, and so a new gate is added in exactly
+ * one place. If the CLI renames/adds a key, this is where the fix lands.
+ */
+export declare const ONBOARDING_PRESEED_KEYS: {
+    readonly hasCompletedOnboarding: true;
+    readonly bypassPermissionsModeAccepted: true;
+    readonly hasTrustDialogAccepted: true;
+};
+/** Write the onboarding pre-seed into `<configHome>/.claude.json`. Best-effort; never throws. */
+export declare function writeOnboardingPreseed(configHome: string): Promise<void>;
+/**
+ * Verify the pre-seed actually landed and log the pinned onboarding keys alongside the
+ * installed CLI version — the "one-line assertion after the pre-seed" from D4. It cannot
+ * introspect the CLI's true first-run gate set (the CLI never exposes it), so it does the
+ * two things it CAN do cheaply and deterministically: confirm every key we intended is
+ * present + truthy in the written file (catching a botched write), and emit a structured
+ * record pairing the keys with the CLI version so a future onboarding regression — surfaced
+ * by the cold-start watchdog as a silent, output-less start — is diffable against a new gate.
+ * Best-effort; never throws.
+ */
+export declare function assertOnboardingKeysCurrent(configHome: string, cliVersion: string | undefined, log: Logger | undefined): Promise<void>;

package/dist/package-registries.d.ts

@@ -0,0 +1,32 @@
+import type { PackageRegistrySpec } from './job.js';
+/** Where the per-job npm auth lands in a container (the user npmrc, outside any checkout). */
+export declare function npmrcPath(): string;
+/**
+ * Per-job isolation for the rendered npmrc. Set `isolatedDir` when the harness process is
+ * SHARED across concurrent jobs and its HOME is the developer's own — i.e. the local native
+ * host-process transport, which is exactly the set of jobs carrying `ambientAuth`. Absent ⇒
+ * the container default (`~/.npmrc`).
+ */
+export interface PackageRegistryScope {
+    /** A per-job directory (removed with the job) to hold this job's npmrc. */
+    isolatedDir?: string;
+}
+/**
+ * Render the job's registry entries as npmrc lines: each scope routed to its
+ * registry, plus one `_authToken` credential line per distinct host.
+ */
+export declare function renderNpmrc(entries: readonly PackageRegistrySpec[]): string;
+/**
+ * Write (or clear) the job's npmrc before the agent runs, and return the env the agent's child
+ * process needs to find it (empty for the container default, which npm picks up from HOME).
+ * Tokens are registered for output redaction so a token echoed in an npm error never reaches
+ * logs or stored output.
+ */
+export declare function configurePackageRegistries(entries: readonly PackageRegistrySpec[] | undefined, scope?: PackageRegistryScope): Promise<Record<string, string>>;
+/**
+ * The credential VALUES in npmrc content: the three keys npm accepts a secret under, on any host
+ * line. Used to register a seeded (developer-owned) file's tokens for redaction. An `${ENV_VAR}`
+ * reference is not itself a secret — npm expands it at read time — so it is skipped rather than
+ * registered as a literal to scrub.
+ */
+export declare function npmrcCredentials(content: string): string[];

package/dist/pi-workspace.d.ts

@@ -0,0 +1,194 @@
+import type { RepoSpec } from './job.js';
+import type { McpServerSpec, SkillSpec } from './agent-capabilities.js';
+import { type ContextFileInfo, type PiRunOutcome, type PiRunStats, type RunDiagnostics } from './pi.js';
+import { type ProgressGuardLimits } from './progress-guard.js';
+import type { RunOptions } from './runner.js';
+import { type SubscriptionHarness } from './agent-runner.js';
+/** Which container harness runs an agent (the default Pi, or a subscription CLI). */
+export type HarnessKind = 'pi' | SubscriptionHarness;
+/**
+ * Run `fn` against a fresh temp working directory, always removing it afterwards
+ * (even on throw). `prefix` labels the directory (e.g. 'impl', 'merge').
+ *
+ * Teardown is **best-effort**: on Windows (native local mode) a just-exited child —
+ * git, or the developer's own `claude`/`codex` CLI — can still hold a transient handle
+ * on a file in the checkout, so a straight `rm` throws `EBUSY`/`EPERM` and, running in
+ * the `finally`, would fail an otherwise-successful run. We lean on `fs.rm`'s Windows
+ * backoff (`maxRetries`/`retryDelay`) and, if it STILL can't remove the dir, log and
+ * swallow: a leaked temp dir is harmless (the OS reclaims the temp root), a failed run
+ * is not.
+ */
+export declare function withWorkspace<T>(prefix: string, fn: (dir: string) => Promise<T>): Promise<T>;
+/**
+ * Run `fn` against a STABLE per-repo working directory (`<root>/<owner>/<repo>`) that is
+ * NOT removed afterwards — the persistent-checkout analogue of {@link withWorkspace}. The
+ * caller (via `prepareExistingCheckout`) clean-sweeps + fetches the dir into the right
+ * state before use; serialised per dir so concurrent jobs can't corrupt the shared tree.
+ */
+export declare function withPersistentWorkspace<T>(repo: RepoSpec, fn: (dir: string) => Promise<T>): Promise<T>;
+/**
+ * Acquire a working directory for a run: a STABLE, reused per-repo checkout when the job
+ * opted into persistent checkout (the warm-pool path), else a fresh ephemeral temp dir
+ * (every other runtime). The two flows differ ONLY in dir lifecycle — the caller populates
+ * the dir (clone vs `prepareExistingCheckout`) itself, so it can keep its flow-specific
+ * resume / full-clone / branch logic.
+ */
+export declare function acquireRepoCheckout<T>(opts: {
+    persistent: boolean;
+    prefix: string;
+    repo: RepoSpec;
+}, fn: (dir: string) => Promise<T>): Promise<T>;
+/** What every agent needs to drive Pi against an already-prepared directory. */
+export interface AgentRunSpec {
+    /** The prepared working directory (cloned/scaffolded by the caller). */
+    dir: string;
+    /** Composed role + best-practice fragments; written to Pi's global AGENTS.md context. */
+    systemPrompt: string;
+    /** The concrete task prompt handed to Pi. */
+    userPrompt: string;
+    model: string;
+    /**
+     * Which harness runs the agent. Absent ⇒ the default Pi harness (proxy +
+     * sessionToken). For `claude-code` / `codex`, `subscriptionToken` carries the
+     * leased credential and the proxy fields are unused (the CLI talks direct).
+     */
+    harness?: HarnessKind;
+    /** The leased subscription credential for `claude-code` / `codex`. */
+    subscriptionToken?: string;
+    /** Anthropic-compatible base URL for a non-Anthropic Claude-Code vendor (GLM/Kimi). */
+    subscriptionBaseUrl?: string;
+    /**
+     * Native local execution: run the developer's installed `claude` / `codex` with its
+     * OWN ambient login instead of a leased credential. Set only by the local native
+     * transport; a no-op for the Pi harness.
+     */
+    ambientAuth?: boolean;
+    /** Pi proxy base URL (Pi harness only). */
+    proxyBaseUrl?: string;
+    /**
+     * The backend serves the phase-tagged completions route, so this pass may tag the URL it
+     * points Pi at with the phase it is running under (see {@link HarnessAuthFields.proxyPhasePath}
+     * and `phasedProxyBaseUrl`). Absent ⇒ the plain path.
+     */
+    proxyPhasePath?: boolean;
+    /** Pi proxy session token (Pi harness only). */
+    sessionToken?: string;
+    /**
+     * For a monorepo service, the subdirectory (relative to the repo root) this run
+     * operates within — `spec.dir` already points there. Surfaced to the agent in
+     * AGENTS.md so it knows it's in a monorepo and where its service lives. Absent ⇒
+     * whole-repo run (no monorepo note).
+     */
+    serviceDirectory?: string;
+    /**
+     * Whether this run is expected to edit files. Defaults to true; set false for
+     * assess-only runs (the merger) so the no-progress guard's no-edit bound — which
+     * would otherwise fire on a run that correctly makes zero edits — is skipped.
+     */
+    expectsEdits?: boolean;
+    /**
+     * Per-knob overrides for the progress guard, set by the backend per agent kind (it
+     * only LOOSENS limits, never tightens). Each present knob overrides the env/default;
+     * absent knobs keep {@link progressGuardLimitsFromEnv}. Absent ⇒ env/default for all.
+     */
+    guardLimits?: Partial<ProgressGuardLimits>;
+    /**
+     * Per-kind web-search guidance composed by the backend (so it can speak to what
+     * this agent kind does). Surfaced in AGENTS.md only when web search is configured;
+     * absent ⇒ the generic blurb is used. See `writeAgentsContext`.
+     */
+    webToolsGuidance?: string;
+    /**
+     * Linked-context files the backend prepared (requirements / RFCs / PRDs / tracker
+     * issues). Materialised into CONTEXT_DIR in the checkout before the run and pointed at
+     * from AGENTS.md, so the agent reads them on demand. Absent ⇒ none.
+     */
+    contextFiles?: ContextFileInfo[];
+    /**
+     * The skills to make available for this run — a `skill` step's picked skill and/or the playbooks
+     * the running agent kind declares. Installed HARNESS-AWARE: the claude-code runner writes them
+     * natively into the config dir's `skills/`; for Pi/codex the resource files are materialised
+     * under `.cat-context/skill/<name>/` (their prompt already carries the folded-in instructions).
+     * Absent ⇒ no skills.
+     */
+    skills?: SkillSpec[];
+    /**
+     * Tool servers (MCP) to wire into the agent CLI. Served by the subscription harnesses only —
+     * Pi has no MCP client, and the BACKEND is what decides that (it drops an unservable server and
+     * tells the agent so), which is why this path simply forwards whatever it is given rather than
+     * re-deciding. Absent ⇒ the CLI's built-in tools only.
+     */
+    mcpServers?: McpServerSpec[];
+    /**
+     * Enable proxy-backed web search: point the rpiv-web-tools SearXNG provider at the
+     * backend's search proxy (`${proxyBaseUrl}/web-search`) with the session token as
+     * the bearer — so the search runs server-side under the deployment's key and no
+     * provider secret reaches the sandbox. Off ⇒ web search is on only if a provider key
+     * is present directly in the container env (the self-hosted runner-pool path).
+     */
+    webSearchProxy?: boolean;
+    /**
+     * Multi-repo run (service-connections phase 3): the cwd (`dir`) is the WORKSPACE ROOT with
+     * every involved repo checked out as a sibling under it. Suppresses the single-repo monorepo
+     * note in AGENTS.md and adds the multi-repo mechanics note instead. Absent ⇒ single-repo.
+     */
+    multiRepo?: boolean;
+}
+/**
+ * Whether the run's checkout actually ships a `blueprints/` folder — what gates the blueprint
+ * orientation note in AGENTS.md (an external repo has none, so the note would be ~10 lines of
+ * dead guidance pointing at files that don't exist, re-sent on every turn).
+ *
+ * A MULTI-REPO run's `dir` is the workspace ROOT with each repo checked out as a sibling under
+ * it, so the root itself never holds `blueprints/`: the legs are checked too, and the note is
+ * included when ANY leg ships one (it orients the agent to the concept, and the agent finds the
+ * per-repo folder from there). Best-effort throughout — any stat/readdir failure simply omits
+ * the note rather than failing the dispatch.
+ */
+export declare function checkoutHasBlueprints(dir: string, multiRepo: boolean): Promise<boolean>;
+/**
+ * Write Pi's global agent context (`~/.pi/agent/AGENTS.md`) + provider config,
+ * then run Pi once in `spec.dir` and return its summary/stats/stderr. The context
+ * lives outside the checkout so it never lands in a commit; the shared middle of
+ * every container agent.
+ */
+export declare function runAgentInWorkspace(spec: AgentRunSpec, opts?: RunOptions): Promise<PiRunOutcome>;
+/**
+ * Whether the claude-code runner will install this run's skills natively (into the CLI's config
+ * dir) rather than the caller materialising them into the checkout. True ONLY for a
+ * leased-credential claude-code run, which gets a throwaway per-run config home. An AMBIENT run
+ * uses the developer's own `~/.claude`, which the runner will not write a skill into — it would
+ * outlive the run in their personal setup, and two concurrent jobs carrying same-named skills
+ * would overwrite each other's.
+ */
+export declare function installsSkillNatively(spec: Pick<AgentRunSpec, 'harness' | 'ambientAuth'>): boolean;
+/**
+ * True when Pi exited cleanly without a single tool call or token of output — the
+ * signature of a run where it never reached the model. Used by every agent's
+ * no-op reason to point at the most likely cause (an unreachable proxy / rejected
+ * model) rather than a genuine "nothing to do".
+ */
+export declare function agentNeverActed(stats: PiRunStats): boolean;
+/** The full-sentence "never acted" cause shared by the structured no-op reasons. */
+export declare const NEVER_ACTED_CAUSE = " The agent never acted (no tool calls, no model output) \u2014 it most likely could not reach the model.";
+/**
+ * A human-readable cause when the agent's FINAL answer is unusable — its last turn was
+ * cut off at the output ceiling, or carried no text at all (an empty completion) — or
+ * `undefined` when the final answer looks fine.
+ *
+ * This is OPT-IN per agent, never a blanket harness rule. Only agents whose work
+ * product is a final text/document the pipeline hands ONWARD to be reviewed or parsed
+ * (the spec-writer, the blueprinter) should treat a non-undefined result as a hard
+ * failure — for them an empty/cut-off final turn means there is nothing trustworthy to
+ * review, which is exactly what drove the spec-writer ⇄ companion rework loop. Agents
+ * whose product is a side effect (a pushed PR/commit from the coder or ci-fixer, a
+ * self-contained validation) legitimately end with no final text and MUST NOT call this.
+ */
+export declare function unusableFinalAnswerCause(diagnostics: RunDiagnostics | undefined): string | undefined;
+/**
+ * The credential-scrubbed tail where a no-op's real cause shows up: a slice of Pi's
+ * stderr, or — when stderr is empty — a slice of its summary. Empty when neither is
+ * present. Shared by every agent's no-op reason so the cause is always diagnosable
+ * without shelling into the (ephemeral) container.
+ */
+export declare function agentOutputTail(stderrTail: string | undefined, summary?: string): string;

package/dist/pi-workspace.js

@@ -182,6 +182,10 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             expectsEdits: spec.expectsEdits ?? true,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
+            // Per-slice review capture, so a parallel review's finished slices are persisted as they
+            // land rather than only in the terminal output. Only the subscription runners fan work out
+            // across subagents, so this is the only path that can produce it.
+            onSliceReviews: opts.onSliceReviews,
             // Stream this run's per-call telemetry to the job's live drain. The subscription
             // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
             // proxy as they happen), so this is the only path that needs the hook.