@cat-factory/executor-harness 1.31.0

package/dist/on-call.js

@@ -0,0 +1,126 @@
+import { cloneRepo } from './git.js';
+import { extractJsonObject } from './blueprint.js';
+import { agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
+import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
+import { log } from './logger.js';
+// Async job execution for the on-call agent. The engine dispatches this when the
+// post-release-health gate detects a Datadog regression. The released PR has already
+// merged and its work branch was deleted, so we clone the BASE branch (which contains
+// the merged change), have Pi locate the merged commit (via the PR number / the
+// now-historical head branch) and correlate its diff with the regression evidence
+// (handed in via the user prompt), then return ONLY a JSON assessment of whether THIS
+// change is the likely culprit. The on-call agent makes NO commits and reverts nothing —
+// the engine raises a `release_regression` notification carrying this assessment.
+const ASSESSMENT_SHAPE_HINT = 'Expected an on-call assessment: {"culpritConfidence": number 0..1, "recommendation": ' +
+    '"revert"|"hold"|"monitor", "rationale": string, "evidence": string[]}.';
+function clamp01(value, fallback) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(1, Math.max(0, n));
+}
+function coerceRecommendation(value) {
+    return value === 'revert' || value === 'monitor' ? value : 'hold';
+}
+/**
+ * Coerce the agent's JSON into a well-formed assessment. A missing confidence defaults
+ * to a CONSERVATIVE 0 (don't imply the PR is at fault without evidence); a missing
+ * recommendation defaults to `hold` (human decides). Returns null only when no JSON
+ * object could be extracted at all.
+ */
+function coerceAssessment(raw, summary) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const o = raw;
+    const evidence = Array.isArray(o.evidence)
+        ? o.evidence.filter((e) => typeof e === 'string')
+        : [];
+    return {
+        culpritConfidence: clamp01(o.culpritConfidence, 0),
+        recommendation: coerceRecommendation(o.recommendation),
+        rationale: typeof o.rationale === 'string' && o.rationale ? o.rationale : summary.slice(0, 2000),
+        evidence,
+    };
+}
+function buildUserPrompt(job) {
+    const pr = job.prNumber !== undefined ? `#${job.prNumber}` : '';
+    // The PR has already merged into the base branch and its work branch was deleted, so the
+    // checkout is the base branch. Point the agent at how to find the merged commit.
+    const locate = job.prNumber
+        ? `It merged as a commit referencing ${pr} — find it with ` +
+            `\`git log --oneline -n 50\` (squash/merge commits include \`(${pr})\`; a merge commit ` +
+            `mentions \`#${job.prNumber}\`), then inspect it with \`git show <sha>\`.`
+        : job.headBranch
+            ? `Its work branch was \`${job.headBranch}\` (now deleted) — find the merged commit in ` +
+                `\`git log --oneline -n 50\` and inspect it with \`git show <sha>\`.`
+            : `Find the most recent merge/feature commit with \`git log --oneline -n 50\` and inspect ` +
+                `it with \`git show <sha>\`.`;
+    return [
+        job.userPrompt,
+        '',
+        `You are on the base branch \`${job.repo.baseBranch}\`, which already contains the released ` +
+            `pull request ${pr}. ${locate} Correlate that change with the regression evidence above. ` +
+            `Beware correlation vs causation.`,
+        '',
+        'Respond with ONLY a JSON object {"culpritConfidence":0.0,"recommendation":"revert"|"hold"|"monitor","rationale":"…","evidence":["…"]}.',
+    ].join('\n');
+}
+/** Run one on-call job: clone branch → Pi investigates → return the assessment (no commit). */
+export async function handleOnCall(job, opts = {}) {
+    const trace = { jobId: job.jobId, repo: `${job.repo.owner}/${job.repo.name}`, branch: job.branch };
+    return withWorkspace('on-call', async (dir) => {
+        log.info('on-call: cloning base branch', trace);
+        await cloneRepo({
+            repo: { ...job.repo, baseBranch: job.branch },
+            ghToken: job.ghToken,
+            dir,
+            // Full clone so the agent has the history to locate + diff the merged commit.
+            full: true,
+            signal: opts.signal,
+        });
+        log.info('on-call: running agent', trace);
+        const { summary, stats, stderrTail, usage } = await runAgentInWorkspace({
+            dir,
+            systemPrompt: job.systemPrompt,
+            userPrompt: buildUserPrompt(job),
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            // Investigation only — no commits/edits, so the no-edit guard must not fire.
+            expectsEdits: false,
+        }, opts);
+        const { value: assessment, diagnostics } = await resolveStructuredOutput({
+            label: 'on-call',
+            shapeHint: ASSESSMENT_SHAPE_HINT,
+            parse: (text) => coerceAssessment(extractJsonObject(text), text),
+        }, summary, {
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            model: job.model,
+            jobId: job.jobId,
+            signal: opts.signal,
+        });
+        if (!assessment) {
+            return {
+                summary,
+                stats,
+                error: noAssessmentReason(stats, stderrTail, diagnostics),
+                ...(usage ? { usage } : {}),
+            };
+        }
+        log.info('on-call: assessed', { ...trace, ...assessment });
+        return { onCallAssessment: assessment, summary, stats, ...(usage ? { usage } : {}) };
+    });
+}
+function noAssessmentReason(stats, stderrTail, diagnostics) {
+    const cause = agentNeverActed(stats)
+        ? NEVER_ACTED_CAUSE
+        : ' The agent did not return a parseable JSON assessment.';
+    return `On-call produced no assessment.${cause}${diagnostics ? diagnosticsSuffix(diagnostics) : ''}${agentOutputTail(stderrTail)}`;
+}

package/dist/pi-workspace.js

@@ -0,0 +1,237 @@
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CONTEXT_DIR, materializeContextFiles, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { runSubscriptionHarness } from './agent-runner.js';
+// The thin base every container agent shares: an ephemeral working directory, and
+// one Pi run inside it driven by the harness-written context. The agents differ in
+// how the directory is prepared (clone a branch, scaffold from scratch, read files
+// to build the prompt) and what they do with the result (push a branch, open a PR,
+// render files, return JSON) — but the middle (write AGENTS.md + provider config,
+// run Pi, tear the workspace down) is identical, so it lives here once. Carries no
+// secrets beyond the call: the per-job tokens arrive in the spec and are gone when
+// the workspace is removed.
+/**
+ * Run `fn` against a fresh temp working directory, always removing it afterwards
+ * (even on throw). `prefix` labels the directory (e.g. 'impl', 'merge').
+ */
+export async function withWorkspace(prefix, fn) {
+    const dir = await mkdtemp(join(tmpdir(), `${prefix}-`));
+    try {
+        return await fn(dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * The PERSISTENT-checkout root in a reused (pooled) container — a stable per-repo
+ * directory that survives across jobs so a new run can `git fetch` + switch branch
+ * instead of cloning from scratch. Only the local warm-pool transport activates this
+ * (by setting `persistentCheckout` on the job); every other runtime uses the ephemeral
+ * {@link withWorkspace} path, so this code is dormant there.
+ */
+function persistentWorkspaceRoot() {
+    return process.env.HARNESS_WORKSPACE_ROOT?.trim() || '/workspace';
+}
+/** Sanitise an owner/name path segment so a repo identity can never escape the root. */
+function safeSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';
+}
+// A per-directory async mutex: two jobs that land in the same container share ONE
+// persistent checkout, so they must not mutate its working tree concurrently. The
+// engine runs a run's steps sequentially, so contention is rare — this is correctness
+// insurance (and keeps a stray concurrent dispatch from corrupting the tree).
+const dirLocks = new Map();
+async function withDirLock(dir, fn) {
+    const prev = dirLocks.get(dir) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    // Store the SAME promise we await on for cleanup-identity. (Storing `prev.then(...)`
+    // instead would make the tail check below — `=== tail` — never match, so the entry
+    // would never be deleted and the map would grow without bound.)
+    const tail = prev.then(() => current);
+    dirLocks.set(dir, tail);
+    await prev.catch(() => { });
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        // Drop the entry once we're the tail (no later caller has queued behind us), so the
+        // map doesn't grow unbounded across distinct repo dirs.
+        if (dirLocks.get(dir) === tail)
+            dirLocks.delete(dir);
+    }
+}
+/**
+ * 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 async function withPersistentWorkspace(repo, fn) {
+    const dir = join(persistentWorkspaceRoot(), safeSegment(repo.owner), safeSegment(repo.name));
+    return withDirLock(dir, async () => {
+        await mkdir(dir, { recursive: true });
+        return fn(dir);
+    });
+}
+/**
+ * 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 async function acquireRepoCheckout(opts, fn) {
+    if (opts.persistent)
+        return withPersistentWorkspace(opts.repo, fn);
+    return withWorkspace(opts.prefix, fn);
+}
+/**
+ * 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 async function runAgentInWorkspace(spec, opts = {}) {
+    // Materialise any backend-prepared linked context into the checkout up front, so the
+    // agent (which can't reach Jira/GitHub) reads it on demand from disk. Shared by both
+    // harness paths; kept out of the agent's commits via a local git exclude entry.
+    const contextFiles = spec.contextFiles ?? [];
+    await materializeContextFiles(spec.dir, contextFiles);
+    // Subscription harnesses (Claude Code / Codex) authenticate with the leased
+    // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
+    // system prompt is passed straight to the CLI; everything around this (clone,
+    // push, watchdogs) is unchanged.
+    if (spec.harness === 'claude-code' || spec.harness === 'codex') {
+        // Ambient (native) mode authenticates with the developer's own CLI login, so no
+        // leased token is required; otherwise the leased subscription token is mandatory.
+        if (!spec.ambientAuth && !spec.subscriptionToken) {
+            throw new Error(`The ${spec.harness} harness requires a subscription token`);
+        }
+        return runSubscriptionHarness(spec.harness, {
+            cwd: spec.dir,
+            model: spec.model,
+            systemPrompt: subscriptionSystemPrompt(spec.systemPrompt, contextFiles),
+            userPrompt: spec.userPrompt,
+            ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
+            subscriptionBaseUrl: spec.subscriptionBaseUrl,
+            ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+            signal: opts.signal,
+            onActivity: opts.onActivity,
+            onProgress: opts.onProgress,
+        });
+    }
+    if (!spec.proxyBaseUrl || !spec.sessionToken) {
+        throw new Error('The Pi harness requires proxyBaseUrl and sessionToken');
+    }
+    const proxyBaseUrl = spec.proxyBaseUrl;
+    const sessionToken = spec.sessionToken;
+    // Opt-in web search/fetch (rpiv-web-tools). Two ways it turns on, both no-ops by
+    // default:
+    //  - proxy-backed (the Cloudflare/managed path): the backend set `webSearchProxy`,
+    //    so point the SearXNG provider at `${proxyBaseUrl}/web-search` with the session
+    //    token — the search runs server-side, no provider key in the sandbox.
+    //  - direct (the self-hosted runner-pool path): a provider key is present in the
+    //    container env, which `webSearchConfigFromEnv` autodetects.
+    // The proxy vars are handed to Pi's child via `extraEnv` (not the harness's own
+    // process.env), so detection runs against the same merged view the extension sees.
+    const extraEnv = spec.webSearchProxy
+        ? webSearchProxyEnv(proxyBaseUrl, sessionToken)
+        : {};
+    const webSearch = webSearchConfigFromEnv({ ...process.env, ...extraEnv });
+    if (webSearch)
+        await writeWebToolsConfig(webSearch);
+    await writeAgentsContext(spec.systemPrompt, {
+        webSearch: Boolean(webSearch),
+        guidance: spec.webToolsGuidance,
+        serviceDirectory: spec.serviceDirectory,
+        contextFiles,
+    });
+    await writePiModelsConfig({ model: spec.model, proxyBaseUrl });
+    const { signal, onActivity, onProgress, onSpan } = opts;
+    return runPi({
+        cwd: spec.dir,
+        model: spec.model,
+        userPrompt: spec.userPrompt,
+        sessionToken,
+        signal,
+        onActivity,
+        onProgress,
+        onSpan,
+        expectsEdits: spec.expectsEdits ?? true,
+        // Start from the env/built-in defaults and apply only the per-knob overrides the
+        // backend set for this kind (loosen-only), so an unspecified knob keeps its default.
+        guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
+        extraEnv,
+    });
+}
+/**
+ * Append a pointer to the materialised linked context onto a subscription harness's
+ * system prompt. The Pi harness surfaces this via AGENTS.md, but Claude Code / Codex
+ * take the system prompt straight, so the note has to ride along here. '' files ⇒ the
+ * prompt is returned unchanged.
+ */
+function subscriptionSystemPrompt(systemPrompt, files) {
+    if (!files.length)
+        return systemPrompt;
+    const list = files.map((f) => `- ${CONTEXT_DIR}/${f.path} — ${f.title}`).join('\n');
+    return `${systemPrompt}
+
+Linked context (requirements / RFCs / PRDs / tracker issues) for this task is in the
+${CONTEXT_DIR}/ directory of your checkout — read a file when relevant. Do NOT try to reach
+external systems; everything available is already on disk:
+${list}`;
+}
+/**
+ * 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 function agentNeverActed(stats) {
+    return stats.toolCalls === 0 && stats.assistantChars === 0;
+}
+/** The full-sentence "never acted" cause shared by the structured no-op reasons. */
+export const NEVER_ACTED_CAUSE = ' The agent never acted (no tool calls, no model output) — 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 function unusableFinalAnswerCause(diagnostics) {
+    if (!diagnostics)
+        return undefined;
+    if (diagnostics.finalTruncated) {
+        return 'its final answer hit the output-token ceiling and was cut off (raise the limit or narrow the task)';
+    }
+    if (diagnostics.finalAnswerEmpty) {
+        return 'its final turn produced no text (an empty completion), so there is no document to read';
+    }
+    return 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 function agentOutputTail(stderrTail, summary) {
+    if (stderrTail)
+        return ` Agent stderr: ${stderrTail.slice(-700)}`;
+    if (summary)
+        return ` Agent output: ${summary.slice(0, 700)}`;
+    return '';
+}