@skill-harness/adapters 0.5.0 → 0.7.0

package/dist/pi-json.d.ts

@@ -0,0 +1,22 @@
+import type { ExecutionTraceV1, ModelRef, RunMode } from "@skill-harness/core";
+export interface PiJsonRunOptions {
+    args: string[];
+    cwd: string;
+    timeoutMs: number;
+    piVersion: string | null;
+    subject: ModelRef;
+    scenarioId: string;
+    mode: RunMode;
+    rep: number;
+    turn: number;
+    changedPaths?: string[];
+    homeDir?: string;
+}
+export interface PiJsonRunResult {
+    trace: ExecutionTraceV1;
+    isComplete: boolean;
+    malformedLines: number;
+    code: number | null;
+    stderr: string;
+}
+export declare function runPiJson(opts: PiJsonRunOptions): Promise<PiJsonRunResult>;

package/dist/pi-json.js

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { parseTrace } from "@skill-harness/core";
+/**
+ * Run `pi --mode json` and build an execution trace, **streaming**.
+ *
+ * The streaming is not an optimization, it is the requirement. pi's
+ * `message_update` events re-send the entire accumulated message on every delta,
+ * so stdout is quadratic in the answer's length — a trivial three-tool-call run
+ * measured **52 MB** of stdout wrapping 12 KB of terminal events. Buffering that
+ * into a string (which is what the shared `exec()` helper does) would exhaust
+ * memory partway through a long wave, taking the whole run with it.
+ *
+ * So this deliberately does NOT reuse `exec()`. The two quadratic event types are
+ * dropped as each line arrives, so the giant ones are never retained; the
+ * remainder — a few KB of terminal events — is held until `close` and parsed
+ * once. What this bounds is the 52 MB, not the residue.
+ */
+/**
+ * The two quadratic event types, matched at the head of the object where pi
+ * emits `type`. Line-anchored so a value inside the payload cannot masquerade as
+ * the event kind.
+ */
+const SKIPPED_TYPE_RE = /^\s*\{\s*"type"\s*:\s*"(?:message_update|tool_execution_update)"/;
+/** How much stderr to retain — enough to diagnose, bounded so a loop cannot blow up. */
+const MAX_STDERR_CHARS = 8000;
+export function runPiJson(opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("pi", opts.args, {
+            cwd: opts.cwd,
+            // stdin from /dev/null: pi hangs waiting on it otherwise, and a hang in a
+            // wave is indistinguishable from a slow model until the timeout fires.
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const kept = [];
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill("SIGKILL");
+            reject(new Error(`pi --mode json timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs);
+        const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        rl.on("line", (line) => {
+            // Prefilter before the full parse: the events skipped here are both the
+            // overwhelming majority of lines and by far the largest.
+            //
+            // Anchored on the `type` field, NOT a substring of the whole line. A raw
+            // `line.includes('"message_update"')` also matched any event whose
+            // ARGUMENTS contained that text — so a `tool_execution_start` for, say,
+            // `grep '"message_update"' logs/` was dropped before parsing, and a
+            // dropped start means the call never enters the trace at all. A
+            // `forbid_calls` gate on that tool then passed for want of the evidence.
+            if (!line.trim())
+                return;
+            if (SKIPPED_TYPE_RE.test(line))
+                return;
+            kept.push(line);
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < MAX_STDERR_CHARS)
+                stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const parsed = parseTrace(kept, {
+                piVersion: opts.piVersion,
+                subject: opts.subject,
+                scenarioId: opts.scenarioId,
+                mode: opts.mode,
+                rep: opts.rep,
+                turn: opts.turn,
+                changedPaths: opts.changedPaths,
+                homeDir: opts.homeDir,
+            });
+            resolve({ ...parsed, code, stderr: stderr.slice(0, MAX_STDERR_CHARS) });
+        });
+    });
+}
+//# sourceMappingURL=pi-json.js.map

package/dist/pi.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdtempSync, readFileSync, statSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { tmpdir, homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { runPiJson } from "./pi-json.js";
 import { exec, onPath, envNum } from "@skill-harness/core";
 const PI_TIMEOUT_MS = envNum("PI_TIMEOUT_MS", 300_000);
 /**
@@ -51,6 +52,28 @@ function skillFlags(mode, skillDir) {
         }
     }
 }
+/**
+ * Extension flags. `--no-extensions` is ALWAYS present (it already was), and each
+ * declared path is added with `--extension`.
+ *
+ * Measured on pi 0.83.0: `--no-extensions --extension <path>` loads exactly the
+ * declared extension and nothing discovered, even with `-a` project-local trust
+ * active. Paths are resolved by the caller; a relative one handed to a child
+ * process running in a neutral cwd would silently resolve to nothing — the same
+ * class of failure as the `--skill` incident.
+ */
+function extensionFlags(extensions) {
+    if (!extensions || extensions.length === 0)
+        return [];
+    return extensions.flatMap((p) => {
+        const abs = resolve(p);
+        if (!existsSync(abs)) {
+            throw new Error(`env.extensions names ${abs}, which does not exist — pi would start without it and the ` +
+                `scenario would silently test an agent with no subagent tool at all.`);
+        }
+        return ["--extension", abs];
+    });
+}
 function header(turnNo, total, text) {
     const label = total === 1 ? "USER" : `USER (turn ${turnNo}/${total})`;
     return `>>> ${label}:\n${text}\n`;
@@ -91,6 +114,7 @@ export const piAdapter = {
         const common = [
             "--no-context-files",
             "--no-extensions",
+            ...extensionFlags(req.extensions),
             "--provider",
             req.model.provider,
             "--model",
@@ -123,6 +147,72 @@ export const piAdapter = {
         }
         return parts.join("\n");
     },
+    /**
+     * Structured run: same flags, same turn loop, plus `--mode json` and a trace
+     * per turn.
+     *
+     * Shares `skillFlags` and the turn structure with `run()` on purpose — if the
+     * two drifted, a trace-gated scenario would be measuring a different delivery
+     * than an ungated one, and the gate would be attesting to the wrong execution.
+     *
+     * The transcript is REBUILT from each turn's final assistant message rather
+     * than read from stdout, which is byte-identical to print mode's output (proven
+     * on a deterministic prompt; see docs/pi-native-capture-design-2026-08-08.md §2).
+     */
+    async runStructured(req) {
+        const common = [
+            "--no-context-files",
+            "--no-extensions",
+            ...extensionFlags(req.extensions),
+            "--provider",
+            req.model.provider,
+            "--model",
+            req.model.model,
+        ];
+        const flags = req.systemPromptFile
+            ? ["--no-skills", "--append-system-prompt", readFileSync(req.systemPromptFile, "utf8")]
+            : skillFlags(req.mode, req.skillDir);
+        const piVersion = await this.version();
+        const total = req.turns.length;
+        const traces = [];
+        const parts = [];
+        const session = total === 1 ? null : mkdtempSync(join(tmpdir(), "sc-pi-session-"));
+        for (let i = 0; i < total; i++) {
+            const turnFlags = session === null
+                ? ["--no-session"]
+                : i === 0
+                    ? ["--session-dir", session]
+                    : ["--session-dir", session, "-c"];
+            const args = [...flags, ...common, "--mode", "json", ...turnFlags, "-p", req.turns[i]];
+            const r = await runPiJson({
+                args,
+                cwd: req.cwd,
+                timeoutMs: PI_TIMEOUT_MS,
+                piVersion,
+                subject: req.model,
+                scenarioId: req.scenarioId ?? "(unknown)",
+                mode: req.mode,
+                rep: req.rep ?? 0,
+                turn: i,
+                homeDir: homedir(),
+            });
+            // A stream with no terminal events at all is not evidence of a clean run.
+            // Fail loudly here rather than let an empty trace satisfy a `forbid_calls`
+            // gate — "the model called nothing" and "we recorded nothing" must not
+            // reach the scorer looking the same.
+            if (!r.isComplete) {
+                throw new Error(`pi --mode json produced no terminal events for turn ${i + 1}/${total}` +
+                    ` (exit ${r.code}${r.malformedLines ? `, ${r.malformedLines} malformed line(s)` : ""})` +
+                    (r.stderr.trim() ? `: ${r.stderr.trim()}` : ""));
+            }
+            traces.push(r.trace);
+            parts.push(header(i + 1, total, req.turns[i]));
+            parts.push(`<<< ASSISTANT:\n${r.trace.final_text.trim()}\n`);
+            if (r.code !== 0)
+                parts.push(`[pi exited ${r.code} on turn ${i + 1}]\n${r.stderr.trim()}\n`);
+        }
+        return { transcript: parts.join("\n"), traces };
+    },
     /**
      * Run the judge: no skills, no context files, no session, single prompt.
      * Judge provider `claude-code` routes to the Claude Code CLI (`claude -p`),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@skill-harness/adapters",
-    "version": "0.5.0",
+    "version": "0.7.0",
     "description": "skill-harness harness adapters — pi runner + claude-code judge routing (internal API)",
     "type": "module",
     "license": "MIT",
@@ -40,6 +40,6 @@
         "prepack": "cp ../../LICENSE ./LICENSE"
     },
     "dependencies": {
-        "@skill-harness/core": "0.5.0"
+        "@skill-harness/core": "0.7.0"
     }
 }