@abdwhb-png/pi-test-harness 0.7.0

package/dist/diagnostics.js

@@ -0,0 +1,61 @@
+/**
+ * Playbook diagnostic messages — clear errors when things diverge.
+ */
+function formatAction(action) {
+    if (action.type === "say") {
+        return `says("${action.text?.slice(0, 60)}${(action.text?.length ?? 0) > 60 ? "..." : ""}")`;
+    }
+    if (action.type === "call") {
+        const params = typeof action.params === "function" ? "<late-bound>" : JSON.stringify(action.params);
+        const truncated = params.length > 80 ? params.slice(0, 80) + "..." : params;
+        return `calls("${action.toolName}", ${truncated})`;
+    }
+    return `unknown(${action.type})`;
+}
+export function formatPlaybookDiagnostic(type, state, remainingActions) {
+    if (type === "exhausted") {
+        const last = state.consumedActions[state.consumedActions.length - 1];
+        const lines = [
+            `Playbook exhausted unexpectedly.`,
+            `  Consumed ${state.consumed} action(s).`,
+        ];
+        if (last) {
+            lines.push(`  Last consumed: ${formatAction(last)} at step ${state.consumed}`);
+        }
+        lines.push("", "  The agent loop called streamFn but no more playbook actions were available.", "  This usually means a tool call produced an unexpected result that caused", "  additional streamFn calls (retries, error handling).");
+        return lines.join("\n");
+    }
+    if (type === "remaining" && remainingActions) {
+        const lines = [
+            `Playbook not fully consumed after run() completed.`,
+            `  Consumed ${state.consumed} of ${state.consumed + remainingActions.length} action(s).`,
+            `  Remaining:`,
+        ];
+        for (const action of remainingActions.slice(0, 5)) {
+            lines.push(`    - ${formatAction(action)}`);
+        }
+        if (remainingActions.length > 5) {
+            lines.push(`    ... +${remainingActions.length - 5} more`);
+        }
+        lines.push("", "  The agent loop ended before all playbook actions were used.", "  This usually means a tool was blocked by a hook or returned early,", "  causing fewer streamFn calls than expected.");
+        return lines.join("\n");
+    }
+    return "Unknown playbook diagnostic.";
+}
+export function formatToolError(step, toolName, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    const lines = [
+        `Error during tool execution at playbook step ${step} (call "${toolName}"):`,
+        `  ${message}`,
+    ];
+    if (stack) {
+        const stackLines = stack.split("\n").slice(1, 4);
+        for (const line of stackLines) {
+            lines.push(`  ${line.trim()}`);
+        }
+    }
+    lines.push("", "This error was thrown by the real tool execution, not by the playbook.", "To capture errors as tool results instead of aborting, set:", "  createTestSession({ propagateErrors: false })");
+    return lines.join("\n");
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Event collection — passively collects all events during a test run.
+ */
+import type { TestEvents } from "./types.js";
+export declare function createEventCollector(): TestEvents;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAkD,MAAM,YAAY,CAAC;AAE7F,wBAAgB,oBAAoB,IAAI,UAAU,CAkCjD"}

package/dist/events.js

@@ -0,0 +1,33 @@
+/**
+ * Event collection — passively collects all events during a test run.
+ */
+export function createEventCollector() {
+    const all = [];
+    const toolCalls = [];
+    const toolResults = [];
+    const messages = [];
+    const ui = [];
+    return {
+        all,
+        toolCalls,
+        toolResults,
+        messages,
+        ui,
+        toolCallsFor(name) {
+            return toolCalls.filter((tc) => tc.toolName === name);
+        },
+        toolResultsFor(name) {
+            return toolResults.filter((tr) => tr.toolName === name);
+        },
+        blockedCalls() {
+            return toolCalls.filter((tc) => tc.blocked);
+        },
+        uiCallsFor(method) {
+            return ui.filter((u) => u.method === method);
+        },
+        toolSequence() {
+            return toolCalls.map((tc) => tc.toolName);
+        },
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,UAAU,oBAAoB;IACnC,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,MAAM,SAAS,GAAqB,EAAE,CAAC;IACvC,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,MAAM,EAAE,GAAmB,EAAE,CAAC;IAE9B,OAAO;QACN,GAAG;QACH,SAAS;QACT,WAAW;QACX,QAAQ;QACR,EAAE;QAEF,YAAY,CAAC,IAAY;YACxB,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACvD,CAAC;QAED,cAAc,CAAC,IAAY;YAC1B,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACzD,CAAC;QAED,YAAY;YACX,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;QAC7C,CAAC;QAED,UAAU,CAAC,MAAc;YACxB,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QAC9C,CAAC;QAED,YAAY;YACX,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;QAC3C,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @abdwhb-png/pi-test-harness
+ *
+ * Test harness for pi extensions — playbook-based model mocking,
+ * session testing, sandbox install verification.
+ */
+export { when, calls, says } from "./playbook.js";
+export { createTestSession } from "./session.js";
+export { verifySandboxInstall } from "./sandbox.js";
+export { createMockPi } from "./mock-pi.js";
+export type { TestSession, TestSessionOptions, TestEvents, ToolCallRecord, ToolResultRecord, UICallRecord, MockToolHandler, MockUIConfig, SandboxOptions, SandboxResult, MockPi, MockPiCall, Turn, PlaybookAction, } from "./types.js";
+export { ToolBlockedError } from "./mock-tools.js";
+export { safeRmSync } from "./utils.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,YAAY,EACX,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,MAAM,EACN,UAAU,EACV,IAAI,EACJ,cAAc,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @abdwhb-png/pi-test-harness
+ *
+ * Test harness for pi extensions — playbook-based model mocking,
+ * session testing, sandbox install verification.
+ */
+// DSL builders
+export { when, calls, says } from "./playbook.js";
+// Session
+export { createTestSession } from "./session.js";
+// Sandbox
+export { verifySandboxInstall } from "./sandbox.js";
+// Mock Pi
+export { createMockPi } from "./mock-pi.js";
+// Errors
+export { ToolBlockedError } from "./mock-tools.js";
+// Utilities
+export { safeRmSync } from "./utils.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe;AACf,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAElD,UAAU;AACV,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,UAAU;AACV,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAoB5C,SAAS;AACT,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,YAAY;AACZ,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/mock-pi-script.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Mock pi CLI for integration tests.
+ *
+ * Reads response queue from MOCK_PI_QUEUE_DIR (set by the shim created by createMockPi).
+ * Each invocation consumes the next entry from the queue. When the queue is exhausted,
+ * the last entry repeats. If no entries are queued, outputs a default echo response.
+ *
+ * Queue protocol:
+ *   {queueDir}/queue.json  — JSON array of MockPiCall objects
+ *   {queueDir}/counter     — integer: current call index (auto-incremented)
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// Safety timeout — prevent hanging tests if something goes wrong
+const TIMEOUT_MS = 30_000;
+setTimeout(() => {
+	process.stderr.write("mock-pi-script: timeout after 30s\n");
+	process.exit(124);
+}, TIMEOUT_MS).unref();
+
+// ---------------------------------------------------------------------------
+// Queue directory (set by the shim script)
+// ---------------------------------------------------------------------------
+const queueDir = process.env.MOCK_PI_QUEUE_DIR;
+if (!queueDir) {
+	process.stderr.write("mock-pi-script: MOCK_PI_QUEUE_DIR not set\n");
+	process.exit(99);
+}
+
+// ---------------------------------------------------------------------------
+// Parse CLI arguments (matches what pi-subagents passes to pi)
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+let task = "";
+let sessionDir = null;
+
+let i = 0;
+while (i < args.length) {
+	const arg = args[i];
+
+	// Flags with a value — skip the value
+	if (
+		arg === "--session-dir" ||
+		arg === "--mode" ||
+		arg === "--models" ||
+		arg === "--tools" ||
+		arg === "--extension" ||
+		arg === "--append-system-prompt"
+	) {
+		if (arg === "--session-dir") sessionDir = args[i + 1] ?? null;
+		i += 2;
+		continue;
+	}
+
+	// Flags without a value
+	if (arg === "-p" || arg === "--no-session" || arg === "--no-extensions") {
+		i++;
+		continue;
+	}
+
+	// @file — read task from file
+	if (arg?.startsWith("@")) {
+		try {
+			task = fs.readFileSync(arg.slice(1), "utf-8");
+		} catch {
+			task = "(could not read " + arg.slice(1) + ")";
+		}
+		i++;
+		continue;
+	}
+
+	// Positional — treat as task text
+	if (arg && !arg.startsWith("-")) {
+		task = arg;
+	}
+	i++;
+}
+
+// ---------------------------------------------------------------------------
+// Read queue and counter
+// ---------------------------------------------------------------------------
+let queue = [];
+const queueFile = path.join(queueDir, "queue.json");
+if (fs.existsSync(queueFile)) {
+	try {
+		queue = JSON.parse(fs.readFileSync(queueFile, "utf-8"));
+	} catch {
+		// Malformed queue — treat as empty
+	}
+}
+
+const counterFile = path.join(queueDir, "counter");
+let counter = 0;
+if (fs.existsSync(counterFile)) {
+	try {
+		counter = parseInt(fs.readFileSync(counterFile, "utf-8").trim(), 10) || 0;
+	} catch {
+		// Missing or unreadable — start at 0
+	}
+}
+
+// Increment counter for next invocation
+fs.writeFileSync(counterFile, String(counter + 1));
+
+// Get the current entry (repeat last when exhausted, null if no queue)
+const entry =
+	queue.length > 0 ? queue[Math.min(counter, queue.length - 1)] : null;
+
+// ---------------------------------------------------------------------------
+// Delay
+// ---------------------------------------------------------------------------
+if (entry?.delay > 0) {
+	await new Promise((r) => setTimeout(r, entry.delay));
+}
+
+// ---------------------------------------------------------------------------
+// Stderr
+// ---------------------------------------------------------------------------
+if (entry?.stderr) {
+	process.stderr.write(entry.stderr + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Write files (for chain_dir output simulation)
+// ---------------------------------------------------------------------------
+if (entry?.writeFiles) {
+	for (const [filePath, content] of Object.entries(entry.writeFiles)) {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.writeFileSync(filePath, content);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// JSONL output
+// ---------------------------------------------------------------------------
+if (entry?.jsonl) {
+	for (const event of entry.jsonl) {
+		console.log(typeof event === "string" ? event : JSON.stringify(event));
+	}
+} else {
+	const taskClean = task.replace(/^Task:\s*/i, "").slice(0, 500);
+	const output = entry?.output ?? "Mock output for: " + taskClean;
+	console.log(
+		JSON.stringify({
+			type: "message_end",
+			message: {
+				role: "assistant",
+				content: [{ type: "text", text: output }],
+				model: "mock/test-model",
+				usage: {
+					input: 100,
+					output: 50,
+					cacheRead: 0,
+					cacheWrite: 0,
+					cost: { total: 0.001 },
+				},
+			},
+		}),
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Session file (if requested)
+// ---------------------------------------------------------------------------
+if (sessionDir) {
+	fs.mkdirSync(sessionDir, { recursive: true });
+	fs.writeFileSync(
+		path.join(sessionDir, "session-" + Date.now() + ".jsonl"),
+		JSON.stringify({ type: "session_start" }) + "\n",
+	);
+}
+
+process.exit(entry?.exitCode ?? 0);

package/dist/mock-pi.d.ts

@@ -0,0 +1,32 @@
+/**
+ * createMockPi — mock pi CLI for testing extensions that spawn pi as a subprocess.
+ *
+ * Creates a temp directory with a `pi` shim (`.cmd` on Windows, shell script on Linux)
+ * that prepends to PATH. The shim invokes a mock-pi-script.mjs that reads queued
+ * responses from a file-based queue. Responses are consumed in order; the last one
+ * repeats when the queue is exhausted.
+ *
+ * ```ts
+ * const mockPi = createMockPi();
+ * mockPi.install();
+ *
+ * mockPi.onCall({ output: "Hello from agent" });
+ * mockPi.onCall({ stderr: "crashed", exitCode: 1 });
+ *
+ * // ... test code that spawns pi ...
+ *
+ * mockPi.reset();
+ * mockPi.uninstall();
+ * ```
+ */
+import type { MockPi } from "./types.js";
+/**
+ * Create a mock pi CLI for testing extensions that spawn pi as a subprocess.
+ *
+ * **Concurrency constraint**: Designed for serial subprocess spawns within a single test.
+ * If your test spawns multiple pi processes concurrently, responses may be consumed
+ * out of order. Use separate `createMockPi()` instances for concurrent scenarios,
+ * or ensure your test logic doesn't depend on response ordering.
+ */
+export declare function createMockPi(): MockPi;
+//# sourceMappingURL=mock-pi.d.ts.map

package/dist/mock-pi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-pi.d.ts","sourceRoot":"","sources":["../src/mock-pi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,YAAY,CAAC;AAoCrD;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAkGrC"}

package/dist/mock-pi.js

@@ -0,0 +1,150 @@
+/**
+ * createMockPi — mock pi CLI for testing extensions that spawn pi as a subprocess.
+ *
+ * Creates a temp directory with a `pi` shim (`.cmd` on Windows, shell script on Linux)
+ * that prepends to PATH. The shim invokes a mock-pi-script.mjs that reads queued
+ * responses from a file-based queue. Responses are consumed in order; the last one
+ * repeats when the queue is exhausted.
+ *
+ * ```ts
+ * const mockPi = createMockPi();
+ * mockPi.install();
+ *
+ * mockPi.onCall({ output: "Hello from agent" });
+ * mockPi.onCall({ stderr: "crashed", exitCode: 1 });
+ *
+ * // ... test code that spawns pi ...
+ *
+ * mockPi.reset();
+ * mockPi.uninstall();
+ * ```
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Valid keys for MockPiCall — used for runtime validation. */
+const VALID_MOCK_PI_CALL_KEYS = new Set([
+    "output",
+    "exitCode",
+    "stderr",
+    "delay",
+    "jsonl",
+    "writeFiles",
+]);
+/**
+ * Resolve the mock-pi-script.mjs path.
+ *
+ * During dev (vitest): src/mock-pi.ts → sibling src/mock-pi-script.mjs
+ * After build (dist):  dist/mock-pi.js → ../src/mock-pi-script.mjs
+ */
+function findMockPiScript() {
+    // Direct sibling (running from src/ via vitest)
+    const sibling = path.join(__dirname, "mock-pi-script.mjs");
+    if (fs.existsSync(sibling))
+        return sibling;
+    // One level up to package root, then into src/ (running from dist/)
+    const fromDist = path.join(__dirname, "..", "src", "mock-pi-script.mjs");
+    if (fs.existsSync(fromDist))
+        return fromDist;
+    throw new Error("Could not find mock-pi-script.mjs. Searched:\n" +
+        `  ${sibling}\n` +
+        `  ${fromDist}`);
+}
+/**
+ * Create a mock pi CLI for testing extensions that spawn pi as a subprocess.
+ *
+ * **Concurrency constraint**: Designed for serial subprocess spawns within a single test.
+ * If your test spawns multiple pi processes concurrently, responses may be consumed
+ * out of order. Use separate `createMockPi()` instances for concurrent scenarios,
+ * or ensure your test logic doesn't depend on response ordering.
+ */
+export function createMockPi() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-mock-"));
+    let originalPath;
+    let installed = false;
+    const queueFile = path.join(dir, "queue.json");
+    const counterFile = path.join(dir, "counter");
+    // Initialize empty queue
+    fs.writeFileSync(queueFile, "[]");
+    fs.writeFileSync(counterFile, "0");
+    const scriptPath = findMockPiScript();
+    const nodeExe = process.execPath;
+    // Safety net: restore PATH if process exits without uninstall()
+    const exitHandler = () => {
+        if (originalPath !== undefined) {
+            process.env.PATH = originalPath;
+        }
+    };
+    return {
+        dir,
+        install() {
+            if (installed)
+                return;
+            originalPath = process.env.PATH;
+            if (process.platform === "win32") {
+                // Windows: .cmd batch file shim
+                const cmd = [
+                    "@echo off",
+                    `set "MOCK_PI_QUEUE_DIR=${dir}"`,
+                    `"${nodeExe}" "${scriptPath}" %*`,
+                ].join("\r\n") + "\r\n";
+                fs.writeFileSync(path.join(dir, "pi.cmd"), cmd);
+            }
+            else {
+                // Linux/macOS: shell script shim
+                const sh = [
+                    "#!/bin/sh",
+                    `MOCK_PI_QUEUE_DIR="${dir}" exec "${nodeExe}" "${scriptPath}" "$@"`,
+                ].join("\n") + "\n";
+                const piPath = path.join(dir, "pi");
+                fs.writeFileSync(piPath, sh);
+                fs.chmodSync(piPath, 0o755);
+            }
+            process.env.PATH = `${dir}${path.delimiter}${originalPath}`;
+            process.on("exit", exitHandler);
+            installed = true;
+        },
+        uninstall() {
+            if (!installed)
+                return;
+            process.removeListener("exit", exitHandler);
+            if (originalPath !== undefined) {
+                process.env.PATH = originalPath;
+                originalPath = undefined;
+            }
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort cleanup
+            }
+            installed = false;
+        },
+        onCall(response) {
+            // Validate keys to catch typos early
+            const unknown = Object.keys(response).filter((k) => !VALID_MOCK_PI_CALL_KEYS.has(k));
+            if (unknown.length > 0) {
+                throw new Error(`Unknown MockPiCall key(s): ${unknown.join(", ")}. ` +
+                    `Valid keys: ${[...VALID_MOCK_PI_CALL_KEYS].join(", ")}`);
+            }
+            const queue = JSON.parse(fs.readFileSync(queueFile, "utf-8"));
+            queue.push(response);
+            fs.writeFileSync(queueFile, JSON.stringify(queue));
+        },
+        reset() {
+            fs.writeFileSync(queueFile, "[]");
+            fs.writeFileSync(counterFile, "0");
+        },
+        callCount() {
+            try {
+                return parseInt(fs.readFileSync(counterFile, "utf-8").trim(), 10) || 0;
+            }
+            catch {
+                return 0;
+            }
+        },
+    };
+}
+//# sourceMappingURL=mock-pi.js.map

package/dist/mock-pi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-pi.js","sourceRoot":"","sources":["../src/mock-pi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/D,+DAA+D;AAC/D,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IACvC,QAAQ;IACR,UAAU;IACV,QAAQ;IACR,OAAO;IACP,OAAO;IACP,YAAY;CACZ,CAAC,CAAC;AAEH;;;;;GAKG;AACH,SAAS,gBAAgB;IACxB,gDAAgD;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;IAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAE3C,oEAAoE;IACpE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC;IACzE,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAE7C,MAAM,IAAI,KAAK,CACd,gDAAgD;QAC/C,KAAK,OAAO,IAAI;QAChB,KAAK,QAAQ,EAAE,CAChB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY;IAC3B,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAC/D,IAAI,YAAgC,CAAC;IACrC,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAE9C,yBAAyB;IACzB,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAClC,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAEnC,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAEjC,gEAAgE;IAChE,MAAM,WAAW,GAAG,GAAG,EAAE;QACxB,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,YAAY,CAAC;QACjC,CAAC;IACF,CAAC,CAAC;IAEF,OAAO;QACN,GAAG;QAEH,OAAO;YACN,IAAI,SAAS;gBAAE,OAAO;YACtB,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAEhC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;gBAClC,gCAAgC;gBAChC,MAAM,GAAG,GAAG;oBACX,WAAW;oBACX,0BAA0B,GAAG,GAAG;oBAChC,IAAI,OAAO,MAAM,UAAU,MAAM;iBACjC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;gBACxB,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;YACjD,CAAC;iBAAM,CAAC;gBACP,iCAAiC;gBACjC,MAAM,EAAE,GAAG;oBACV,WAAW;oBACX,sBAAsB,GAAG,WAAW,OAAO,MAAM,UAAU,QAAQ;iBACnE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;gBACpB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACpC,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC7B,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC7B,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,YAAY,EAAE,CAAC;YAC5D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;YAChC,SAAS,GAAG,IAAI,CAAC;QAClB,CAAC;QAED,SAAS;YACR,IAAI,CAAC,SAAS;gBAAE,OAAO;YACvB,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;YAC5C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAChC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,YAAY,CAAC;gBAChC,YAAY,GAAG,SAAS,CAAC;YAC1B,CAAC;YACD,IAAI,CAAC;gBACJ,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACR,sBAAsB;YACvB,CAAC;YACD,SAAS,GAAG,KAAK,CAAC;QACnB,CAAC;QAED,MAAM,CAAC,QAAoB;YAC1B,qCAAqC;YACrC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAC3C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,CACtC,CAAC;YACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CACd,8BAA8B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;oBACnD,eAAe,CAAC,GAAG,uBAAuB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzD,CAAC;YACH,CAAC;YAED,MAAM,KAAK,GAAiB,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;YAC5E,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACpD,CAAC;QAED,KAAK;YACJ,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAClC,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC;QAED,SAAS;YACR,IAAI,CAAC;gBACJ,OAAO,QAAQ,CAAC,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YACxE,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,CAAC,CAAC;YACV,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/mock-tools.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tool execution interceptor — wraps tool.execute() for tools in mockTools.
+ *
+ * For mocked tools, the mock replaces tool.execute() and returns controlled
+ * values. Extension hooks (tool_call / tool_result) are handled by
+ * AgentSession 0.83's internal beforeToolCall/afterToolCall — the mock
+ * must NOT re-emit them.
+ *
+ * For non-mocked tools, the real execute() is called and results are
+ * collected for event queries.
+ */
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { MockToolHandler } from "./types.js";
+import type { PlaybookState } from "./playbook.js";
+/**
+ * Thrown when an extension hook blocks a tool call.
+ * Exported for test assertions — no longer thrown by the mock itself since
+ * AgentSession 0.83's beforeToolCall handles blocking before execute().
+ */
+export declare class ToolBlockedError extends Error {
+    readonly toolBlocked: true;
+    constructor(reason: string);
+}
+/**
+ * Returns true if `err` represents a hook-based tool block.
+ *
+ * Kept for consumers that catch errors from tool execution flows, though
+ * AgentSession 0.83's beforeToolCall blocks before execute() is reached.
+ */
+export declare function isBlockedError(err: unknown): boolean;
+/**
+ * Intercept tool execution for mocked tools.
+ *
+ * Unlike the old approach, this does NOT emit tool_call/tool_result hooks
+ * manually — AgentSession 0.83's beforeToolCall/afterToolCall handles that.
+ * The mock only replaces execute() to return controlled values. Result
+ * recording is handled by the session subscriber from tool_execution_end
+ * events (which carry the final afterToolCall-modified result).
+ *
+ * Returns a Set of mocked tool names for the session subscriber to set the
+ * mocked flag on recorded results, plus a Set of toolCallIds whose mock
+ * returned a ToolResult with isError:true. Pi 0.84's agent loop hardcodes
+ * successful execute() as non-error (isError:false), so the subscriber must
+ * consult this set to preserve the mock's error intent in collected records.
+ */
+export declare function interceptToolExecution(tools: AgentTool[], mockTools: Record<string, MockToolHandler>, playbookState: PlaybookState, propagateErrors: boolean): {
+    tools: AgentTool[];
+    mockedNames: ReadonlySet<string>;
+    mockedErrorToolCallIds: ReadonlySet<string>;
+};
+//# sourceMappingURL=mock-tools.d.ts.map

package/dist/mock-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-tools.d.ts","sourceRoot":"","sources":["../src/mock-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,WAAW,EAAG,IAAI,CAAU;gBAEzB,MAAM,EAAE,MAAM;CAI1B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAWpD;AA0BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,SAAS,EAAE,EAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAC1C,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,OAAO,GACtB;IACF,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5C,CAiDA"}