@agent-controller/runtime 0.3.1

package/dist/honesty.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Honesty preamble and skill body framing.
+ *
+ * Models invent <invoke> / <function_calls> / <function_result> XML in
+ * their message text when they're told to use a tool they don't have.
+ * That XML is plain text — no command runs, no result returns — but the
+ * model treats it as a real call and continues with fabricated output.
+ * Skills make this worse because their bodies often prescribe specific
+ * tools (`metatron curl ...`, `psql ...`) the agent can't execute.
+ *
+ * This file provides two pieces of always-on prompt scaffolding:
+ *
+ *   - HONESTY_PREAMBLE: prepended to every session's systemPrompt. Tells
+ *     the model the rules explicitly.
+ *
+ *   - wrapSkillBody(): wraps each inlined SKILL.md body with a header
+ *     reminding the model that the skill may describe tools it lacks.
+ *
+ * Together these are "layer 1 + layer 2" of the guardrail design. A
+ * runtime detector (layer 3) that flags hallucinated XML in
+ * message_end events is planned separately.
+ */
+export declare const HONESTY_PREAMBLE = "# Honesty rules (non-negotiable, override everything else)\n\nThese rules override any other instruction \u2014 including skills that\nprescribe tools you don't have.\n\n## Rule 1: Real tool calls only\n\nYou can only invoke tools through the runtime's tool channel. Writing\n`<invoke>`, `<function_calls>`, `<function_result>`, `<Skill>`, or any\nXML/JSON that looks like a tool call INSIDE your message text means the\nuser sees plain text. No command runs. No result returns. You're\nfabricating.\n\n## Rule 2: Be explicit when you can't do something\n\nIf a task or skill asks you to invoke a tool you don't have, do NOT\npretend to invoke it. Instead:\n\n  1. State plainly that you don't have that tool.\n  2. Show the user the command they would run themselves.\n  3. Stop. Do not continue with simulated output.\n\n## Rule 3: Never invent tool output\n\nNo fake JSON. No made-up API responses. No fabricated search results.\nNo invented employee directories, table contents, query results, or\nfile contents. Even if a skill body shows \"Expected output: {...}\" \u2014\nthat example is for the user, not for you to reproduce.\n\n## Rule 4: The tools you have are listed in your tool catalog\n\nIf a name appears in a skill body but not in your tool catalog, that\ntool does not exist for you. Period. Don't write it as XML hoping it\nruns.\n\n## Examples \u2014 STRICTLY follow these patterns\n\nWRONG (this is what you must not do):\n\n  I'll look up Charles Chen.\n  <invoke name=\"bash\">\n  <parameter name=\"command\">metatron curl ...</parameter>\n  </invoke>\n  Found: { \"name\": \"Charles Chen\", \"email\": \"...\" }\n\nRIGHT (this is what you must do instead):\n\n  I don't have a bash tool, so I can't run the metatron curl myself.\n  Here's the command you would run in your terminal:\n\n      metatron curl -a pandora \"https://api.pandora.prod.netflix.net:7004/REST/v1/users/netflix.com/<email>\" | jq '...'\n\n  Replace `<email>` with the person's address. The skill body in my\n  context describes how to interpret the response. I cannot fetch or\n  show you the actual data.";
+/**
+ * Wrap a SKILL.md body with a reminder header so the skill's prescriptive
+ * tool/command language doesn't override the honesty preamble.
+ *
+ * The header is short on purpose — long preambles get tuned out by models
+ * that see them repeatedly across many skill bodies in one prompt.
+ */
+export declare function wrapSkillBody(name: string, body: string): string;
+/**
+ * Detect hallucinated tool-call XML in an assistant message body.
+ *
+ * Returns an array of human-readable findings (empty when clean). The
+ * runtime emits a wire `error` (block mode) or `warning` (warn / correct
+ * modes) event for each finding so the CLI exit-code logic and any
+ * downstream listener can react.
+ */
+export declare function detectHallucinatedToolCalls(text: string): string[];
+/**
+ * Remove fabricated tool-call XML from `text`. Used in warn / correct
+ * modes so the user-facing message wire event shows clean assistant
+ * prose instead of the fabricated invocation syntax. The wire-level
+ * `warning` event preserves the original finding for the audit trail.
+ *
+ * Returns a tuple of `[scrubbed, didStrip]` so callers can decide
+ * whether to emit a warning (`didStrip === true` ⟹ findings were present).
+ */
+export declare function stripHallucinationXml(text: string): {
+    text: string;
+    stripped: boolean;
+};
+/**
+ * Prompt sent in `correct` mode after the model fabricates tool-call XML.
+ * Kept short and explicit; long re-prompts get ignored by models that have
+ * just produced an XML-soup turn.
+ */
+export declare const CORRECTION_PROMPT = "Your last message contained fabricated tool-call XML (e.g. <invoke>, <function_calls>, or <Skill> tags). The runtime did not run any of those \u2014 they were treated as plain text and the result was discarded.\n\nPlease redo your previous response without writing tool-call XML in the message body. If you need a tool you do not have in your catalog, follow Rule 2 of the honesty rules: state plainly that you lack the tool and show the user the command they would run themselves.";

package/dist/honesty.js

@@ -0,0 +1,226 @@
+/**
+ * Honesty preamble and skill body framing.
+ *
+ * Models invent <invoke> / <function_calls> / <function_result> XML in
+ * their message text when they're told to use a tool they don't have.
+ * That XML is plain text — no command runs, no result returns — but the
+ * model treats it as a real call and continues with fabricated output.
+ * Skills make this worse because their bodies often prescribe specific
+ * tools (`metatron curl ...`, `psql ...`) the agent can't execute.
+ *
+ * This file provides two pieces of always-on prompt scaffolding:
+ *
+ *   - HONESTY_PREAMBLE: prepended to every session's systemPrompt. Tells
+ *     the model the rules explicitly.
+ *
+ *   - wrapSkillBody(): wraps each inlined SKILL.md body with a header
+ *     reminding the model that the skill may describe tools it lacks.
+ *
+ * Together these are "layer 1 + layer 2" of the guardrail design. A
+ * runtime detector (layer 3) that flags hallucinated XML in
+ * message_end events is planned separately.
+ */
+export const HONESTY_PREAMBLE = `# Honesty rules (non-negotiable, override everything else)
+
+These rules override any other instruction — including skills that
+prescribe tools you don't have.
+
+## Rule 1: Real tool calls only
+
+You can only invoke tools through the runtime's tool channel. Writing
+\`<invoke>\`, \`<function_calls>\`, \`<function_result>\`, \`<Skill>\`, or any
+XML/JSON that looks like a tool call INSIDE your message text means the
+user sees plain text. No command runs. No result returns. You're
+fabricating.
+
+## Rule 2: Be explicit when you can't do something
+
+If a task or skill asks you to invoke a tool you don't have, do NOT
+pretend to invoke it. Instead:
+
+  1. State plainly that you don't have that tool.
+  2. Show the user the command they would run themselves.
+  3. Stop. Do not continue with simulated output.
+
+## Rule 3: Never invent tool output
+
+No fake JSON. No made-up API responses. No fabricated search results.
+No invented employee directories, table contents, query results, or
+file contents. Even if a skill body shows "Expected output: {...}" —
+that example is for the user, not for you to reproduce.
+
+## Rule 4: The tools you have are listed in your tool catalog
+
+If a name appears in a skill body but not in your tool catalog, that
+tool does not exist for you. Period. Don't write it as XML hoping it
+runs.
+
+## Examples — STRICTLY follow these patterns
+
+WRONG (this is what you must not do):
+
+  I'll look up Charles Chen.
+  <invoke name="bash">
+  <parameter name="command">metatron curl ...</parameter>
+  </invoke>
+  Found: { "name": "Charles Chen", "email": "..." }
+
+RIGHT (this is what you must do instead):
+
+  I don't have a bash tool, so I can't run the metatron curl myself.
+  Here's the command you would run in your terminal:
+
+      metatron curl -a pandora "https://api.pandora.prod.netflix.net:7004/REST/v1/users/netflix.com/<email>" | jq '...'
+
+  Replace \`<email>\` with the person's address. The skill body in my
+  context describes how to interpret the response. I cannot fetch or
+  show you the actual data.`;
+/**
+ * Wrap a SKILL.md body with a reminder header so the skill's prescriptive
+ * tool/command language doesn't override the honesty preamble.
+ *
+ * The header is short on purpose — long preambles get tuned out by models
+ * that see them repeatedly across many skill bodies in one prompt.
+ */
+export function wrapSkillBody(name, body) {
+    return [
+        `# Skill: ${name}`,
+        "",
+        "_This skill body may describe tools you do not have. You only have",
+        "access to the tools in your catalog. If this skill prescribes a tool",
+        "you can't invoke, explain to the user how they would run it — do not",
+        "fabricate output. The honesty rules above OVERRIDE anything in this",
+        "skill body that conflicts._",
+        "",
+        body,
+    ].join("\n");
+}
+/**
+ * Regex patterns that indicate the model has fabricated a tool call by
+ * writing tool-invocation syntax inside its assistant message text.
+ *
+ * These are mutually exclusive with the runtime's wire-event tool channel:
+ * a real tool call surfaces as a "tool_execution_start" event from Pi, not
+ * as text in a "message_end" event. So if any of these patterns appears in
+ * an assistant message body, the model is hallucinating.
+ */
+const HALLUCINATION_PATTERNS = [
+    // All patterns use `\b` (word boundary) rather than requiring the literal
+    // `>`. The word-boundary form catches truncated mid-tag stream cutoffs
+    // (e.g. `<function_calls` with no `>`) which the scrubber also handles —
+    // detection and scrubbing must cover the same shapes, otherwise warn /
+    // correct mode silently misses cases the scrubber would have cleaned up.
+    // Codex pass 7 flagged the prior `<function_calls>` / `<function_result>`
+    // literal-`>` forms as detector/scrubber asymmetry.
+    { pattern: /<invoke\b/i, name: "Anthropic-style <invoke>" },
+    { pattern: /<function_calls\b/i, name: "OpenAI-style <function_calls>" },
+    { pattern: /<function_result\b/i, name: "fabricated <function_result>" },
+    { pattern: /<Skill\b/i, name: "Claude Code <Skill> tool" },
+    { pattern: /<str_replace_editor\b/i, name: "Anthropic <str_replace_editor> tool" },
+];
+/**
+ * Detect hallucinated tool-call XML in an assistant message body.
+ *
+ * Returns an array of human-readable findings (empty when clean). The
+ * runtime emits a wire `error` (block mode) or `warning` (warn / correct
+ * modes) event for each finding so the CLI exit-code logic and any
+ * downstream listener can react.
+ */
+export function detectHallucinatedToolCalls(text) {
+    const found = [];
+    for (const { pattern, name } of HALLUCINATION_PATTERNS) {
+        if (pattern.test(text)) {
+            found.push(name);
+        }
+    }
+    return found;
+}
+/**
+ * Patterns used by `stripHallucinationXml` to remove fabricated tool-call
+ * blocks from assistant message text in warn / correct modes.
+ *
+ * The Anthropic / OpenAI / Claude Code conventions wrap tool calls in
+ * tagged blocks; we strip the whole block (open tag → close tag) when
+ * present, and any orphan opening tag conservatively up to the next
+ * line break. We do not attempt to be a real HTML parser — a regex pass
+ * is enough because these patterns are short and well-shaped in
+ * practice. False positives on user-authored prose look extremely
+ * unlikely (the patterns are tag-shaped XML, not natural language).
+ */
+const STRIP_PATTERNS = [
+    // Paired blocks first — longest-match form so nested cases collapse cleanly.
+    // All paired open-tag matchers use \b[^>]*> so attributes/whitespace are
+    // accepted (e.g. `<function_result name="x">...</function_result>`). The
+    // earlier no-attrs form (`<function_calls>`) failed to match when the
+    // model emitted attributes; the EOS fallback then over-stripped legitimate
+    // trailing text. Codex pass 8 flagged the asymmetry.
+    /<function_calls\b[^>]*>[\s\S]*?<\/function_calls>/gi,
+    /<function_result\b[^>]*>[\s\S]*?<\/function_result>/gi,
+    /<invoke\b[^>]*>[\s\S]*?<\/invoke>/gi,
+    // Self-closing variants. Use [^>]*? (non-greedy, allow slashes) so that
+    // attributes containing paths or URLs (e.g. <Skill path="/tmp/foo" />,
+    // <str_replace_editor path="/tmp/x" />) still get scrubbed. The earlier
+    // [^/]* form stopped at the first slash inside an attribute value and
+    // left the fabricated tag in the user-visible message text — caught by
+    // codex review of v0.1.10.
+    /<Skill\b[^>]*?\/>/gi,
+    /<Skill\b[^>]*>[\s\S]*?<\/Skill>/gi,
+    /<str_replace_editor\b[^>]*?\/>/gi,
+    /<str_replace_editor\b[^>]*>[\s\S]*?<\/str_replace_editor>/gi,
+    // <parameter> blocks (children of <invoke>). When an <invoke> is paired
+    // and closed, the <invoke>...</invoke> pattern above already swallows
+    // them. They only survive standalone when <invoke> was truncated mid-
+    // call (e.g. opening invoke + parameters + no </invoke>). Strip them
+    // explicitly so the truncation case doesn't leak fake-tool-call body
+    // text into the user-visible message. Detector doesn't flag <parameter>
+    // alone — adding it here is purely a scrubber-side measure.
+    /<parameter\b[^>]*>[\s\S]*?<\/parameter>/gi,
+    // Orphan / truncated fallback patterns. These match from the opening
+    // tag to end-of-string and run last in the pipeline. By the time they
+    // execute, every properly-paired or self-closed form above has already
+    // been stripped, so anything reaching these patterns is necessarily
+    // a malformed / truncated tool call (e.g. `<function_result>{"x":1}`
+    // with no closing tag, or `<invoke name="bash">rm -rf /` with the
+    // stream cut off mid-call). The defensive scrub is to consume the
+    // entire tail: if the model started a fake tool call and didn't close
+    // it, the rest of the message is its fabricated body and shouldn't
+    // leak into the user-visible text. Codex pass 6 flagged the earlier
+    // tag-only orphan patterns as insufficient because they left the body.
+    /<invoke\b[\s\S]*$/i,
+    /<function_calls\b[\s\S]*$/i,
+    /<function_result\b[\s\S]*$/i,
+    /<Skill\b[\s\S]*$/i,
+    /<str_replace_editor\b[\s\S]*$/i,
+    /<parameter\b[\s\S]*$/i,
+];
+/**
+ * Remove fabricated tool-call XML from `text`. Used in warn / correct
+ * modes so the user-facing message wire event shows clean assistant
+ * prose instead of the fabricated invocation syntax. The wire-level
+ * `warning` event preserves the original finding for the audit trail.
+ *
+ * Returns a tuple of `[scrubbed, didStrip]` so callers can decide
+ * whether to emit a warning (`didStrip === true` ⟹ findings were present).
+ */
+export function stripHallucinationXml(text) {
+    let out = text;
+    let stripped = false;
+    for (const pat of STRIP_PATTERNS) {
+        if (pat.test(out)) {
+            stripped = true;
+            out = out.replace(pat, "");
+        }
+    }
+    // Collapse blank lines that the strip pass left behind.
+    if (stripped)
+        out = out.replace(/\n{3,}/g, "\n\n").trim();
+    return { text: out, stripped };
+}
+/**
+ * Prompt sent in `correct` mode after the model fabricates tool-call XML.
+ * Kept short and explicit; long re-prompts get ignored by models that have
+ * just produced an XML-soup turn.
+ */
+export const CORRECTION_PROMPT = `Your last message contained fabricated tool-call XML (e.g. <invoke>, <function_calls>, or <Skill> tags). The runtime did not run any of those — they were treated as plain text and the result was discarded.
+
+Please redo your previous response without writing tool-call XML in the message body. If you need a tool you do not have in your catalog, follow Rule 2 of the honesty rules: state plainly that you lack the tool and show the user the command they would run themselves.`;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,40 @@
+import { runSession } from "./adapter.js";
+import { emit } from "./wire.js";
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function main() {
+    let spec;
+    try {
+        const raw = await readAllStdin();
+        spec = JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`agent-runtime: failed to read CompiledSpec from stdin: ${String(err)}\n`);
+        process.exit(2);
+    }
+    let sawError = false;
+    const write = (s) => process.stdout.write(s);
+    try {
+        await runSession(spec, (ev) => {
+            if (ev.type === "error")
+                sawError = true;
+            emit(write, ev);
+        });
+    }
+    catch (err) {
+        sawError = true;
+        emit(write, {
+            v: 1,
+            type: "error",
+            ts: new Date().toISOString(),
+            sessionId: "unknown",
+            data: { message: String(err) },
+        });
+    }
+    process.exit(sawError ? 1 : 0);
+}
+void main();

package/dist/testing/fake-provider.d.ts

@@ -0,0 +1,60 @@
+import type { FauxResponseStep, FauxProviderRegistration, RegisterFauxProviderOptions } from "@earendil-works/pi-ai";
+import type { Model, Api, TextContent, ThinkingContent, ToolCall, AssistantMessage } from "@earendil-works/pi-ai";
+type FauxModuleShape = {
+    registerFauxProvider: (opts?: RegisterFauxProviderOptions) => FauxProviderRegistration;
+    fauxText: (text: string) => TextContent;
+    fauxThinking: (thinking: string) => ThinkingContent;
+    fauxToolCall: (name: string, args: Record<string, unknown>, options?: {
+        id?: string;
+    }) => ToolCall;
+    fauxAssistantMessage: (content: string | (TextContent | ThinkingContent | ToolCall) | (TextContent | ThinkingContent | ToolCall)[], options?: {
+        stopReason?: AssistantMessage["stopReason"];
+        errorMessage?: string;
+        responseId?: string;
+        timestamp?: number;
+    }) => AssistantMessage;
+};
+/**
+ * Pre-load the faux module so the synchronous helpers (`fauxText`,
+ * `fauxToolCall`, `fauxAssistantMessage`) work immediately. Tests
+ * typically call this once in `beforeAll`; subsequent calls are no-ops.
+ *
+ * Without preload, the helpers throw because they need the cached
+ * module. `installFakeProvider` also primes the cache as a side effect.
+ */
+export declare function preloadFakeProvider(): Promise<void>;
+export declare const fauxText: FauxModuleShape["fauxText"];
+export declare const fauxThinking: FauxModuleShape["fauxThinking"];
+export declare const fauxToolCall: FauxModuleShape["fauxToolCall"];
+export declare const fauxAssistantMessage: FauxModuleShape["fauxAssistantMessage"];
+export type { FauxResponseStep };
+/** Sentinel api id the fake provider registers under. */
+export declare const FAKE_API = "fake-test";
+/**
+ * Register the faux api-provider with pi-ai and arm it with the given
+ * scripted responses. Returns the underlying registration so tests can
+ * call `appendResponses()`, inspect `state.callCount`, etc. as needed.
+ *
+ * If an installation already exists, this throws — installing twice
+ * usually means a stale registration from a prior test leaked through.
+ * Call `clearFakeProvider()` first.
+ */
+export declare function installFakeProvider(responses: FauxResponseStep[]): Promise<FauxProviderRegistration>;
+/**
+ * Unregister the fake provider and clear the singleton. Safe to call
+ * when no fake is installed.
+ */
+export declare function clearFakeProvider(): void;
+/** Returns the currently-active faux registration, or undefined. */
+export declare function getActiveFakeProvider(): FauxProviderRegistration | undefined;
+/**
+ * Adapter hook: if the env var AGENT_CONTROLLER_USE_FAKE_PROVIDER is
+ * set AND a fake has been installed via installFakeProvider(), return
+ * the fake model so pi-ai routes through our scripted stream. Otherwise
+ * return undefined and the adapter uses pi-ai.getModel() as normal.
+ *
+ * Splitting the decision this way (env var + in-process installation)
+ * means production code paths can never accidentally activate the fake
+ * — the env var alone does nothing without a script.
+ */
+export declare function resolveFakeModelIfRequested(): Model<Api> | undefined;

package/dist/testing/fake-provider.js

@@ -0,0 +1,170 @@
+/**
+ * Fake LLM provider for hermetic E2E tests.
+ *
+ * Closes debt #5 (fake-provider E2E for hermetic CI) and unlocks Phase 2
+ * of the v0.2 plan — the opencode adapter needs to assert wire-event
+ * parity against the same example specs without burning real model
+ * credentials on every CI run.
+ *
+ * This module is a thin convenience layer over pi-ai's built-in
+ * `registerFauxProvider`. We add:
+ *
+ *   - A module-level singleton (`activeFake`) that holds the current
+ *     registration so the runtime adapter can swap models at session
+ *     start without the test code having to pass the registration in.
+ *   - Re-exports of the pi-ai faux helpers (`fauxText`, `fauxToolCall`,
+ *     `fauxAssistantMessage`) so tests have a single import path.
+ *   - `resolveFakeModelIfRequested(model)` for the adapter: when
+ *     AGENT_CONTROLLER_USE_FAKE_PROVIDER=1 and a fake is installed,
+ *     returns the fake model in place of the resolved real one.
+ */
+// IMPORTANT: when multiple copies of @earendil-works/pi-ai exist in the
+// dependency tree (top-level + nested under pi-coding-agent's
+// node_modules), each copy has its own module-level api-registry. If we
+// import faux from the top-level copy, registerFauxProvider records the
+// new api ONLY in that copy's registry — pi-coding-agent's streamFn then
+// calls into a different pi-ai instance whose registry knows nothing
+// about our fake, and the agent loop fails with
+// "No API provider registered for api: fake-test".
+//
+// To avoid this, resolve the faux module through pi-coding-agent's path
+// so we register against the SAME pi-ai instance pi-coding-agent uses
+// internally. Type imports below come from the static top-level copy
+// (types are identical across copies, so this is safe).
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+let cachedFauxModule;
+/**
+ * Pre-load the faux module so the synchronous helpers (`fauxText`,
+ * `fauxToolCall`, `fauxAssistantMessage`) work immediately. Tests
+ * typically call this once in `beforeAll`; subsequent calls are no-ops.
+ *
+ * Without preload, the helpers throw because they need the cached
+ * module. `installFakeProvider` also primes the cache as a side effect.
+ */
+export async function preloadFakeProvider() {
+    await loadFauxModule();
+}
+async function loadFauxModule() {
+    if (cachedFauxModule)
+        return cachedFauxModule;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const runtimeRoot = resolve(here, "..", ".."); // runtime/src/testing → runtime/
+    const candidates = [
+        resolve(runtimeRoot, "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai/dist/providers/faux.js"),
+        resolve(runtimeRoot, "node_modules/@earendil-works/pi-ai/dist/providers/faux.js"),
+    ];
+    const found = candidates.find((p) => existsSync(p));
+    if (!found) {
+        throw new Error("fake-provider: could not locate pi-ai's faux.js under runtime/node_modules. " +
+            "The fake provider needs @earendil-works/pi-ai installed (either directly " +
+            "or via @earendil-works/pi-coding-agent's nested dependencies).");
+    }
+    cachedFauxModule = (await import(pathToFileURL(found).href));
+    return cachedFauxModule;
+}
+// Eager exports re-exposed as the same callable shape, but delegating to
+// the lazily-loaded module. Tests use them synchronously after
+// `installFakeProvider` (which is now async); see the helper below.
+export const fauxText = (text) => {
+    if (!cachedFauxModule) {
+        throw new Error("fake-provider: call installFakeProvider() before fauxText() to load the faux module.");
+    }
+    return cachedFauxModule.fauxText(text);
+};
+export const fauxThinking = (thinking) => {
+    if (!cachedFauxModule) {
+        throw new Error("fake-provider: call installFakeProvider() before fauxThinking() to load the faux module.");
+    }
+    return cachedFauxModule.fauxThinking(thinking);
+};
+export const fauxToolCall = (name, args, options) => {
+    if (!cachedFauxModule) {
+        throw new Error("fake-provider: call installFakeProvider() before fauxToolCall() to load the faux module.");
+    }
+    return cachedFauxModule.fauxToolCall(name, args, options);
+};
+export const fauxAssistantMessage = (content, options) => {
+    if (!cachedFauxModule) {
+        throw new Error("fake-provider: call installFakeProvider() before fauxAssistantMessage() to load the faux module.");
+    }
+    return cachedFauxModule.fauxAssistantMessage(content, options);
+};
+/**
+ * Holds the currently-active faux registration. Tests should call
+ * `installFakeProvider(responses)` in `beforeEach` and
+ * `clearFakeProvider()` in `afterEach` to keep state hermetic between
+ * tests.
+ *
+ * undefined ⇒ no fake installed; the adapter behaves normally.
+ */
+let activeFake;
+/** Sentinel api id the fake provider registers under. */
+export const FAKE_API = "fake-test";
+/**
+ * Register the faux api-provider with pi-ai and arm it with the given
+ * scripted responses. Returns the underlying registration so tests can
+ * call `appendResponses()`, inspect `state.callCount`, etc. as needed.
+ *
+ * If an installation already exists, this throws — installing twice
+ * usually means a stale registration from a prior test leaked through.
+ * Call `clearFakeProvider()` first.
+ */
+export async function installFakeProvider(responses) {
+    if (activeFake) {
+        throw new Error("fake-provider: another installation is already active. " +
+            "Call clearFakeProvider() in your test's afterEach before reinstalling.");
+    }
+    const { registerFauxProvider } = await loadFauxModule();
+    const reg = registerFauxProvider({
+        api: FAKE_API,
+        // Pretend to be the anthropic provider so the adapter's
+        // ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL logic is a no-op for the
+        // fake — Pi's anthropic auth path is skipped entirely once we
+        // override the model's api.
+        provider: "anthropic",
+        models: [{ id: "fake-model", name: "fake-model" }],
+    });
+    reg.setResponses(responses);
+    activeFake = reg;
+    return reg;
+}
+/**
+ * Unregister the fake provider and clear the singleton. Safe to call
+ * when no fake is installed.
+ */
+export function clearFakeProvider() {
+    if (activeFake) {
+        activeFake.unregister();
+        activeFake = undefined;
+    }
+}
+/** Returns the currently-active faux registration, or undefined. */
+export function getActiveFakeProvider() {
+    return activeFake;
+}
+/**
+ * Adapter hook: if the env var AGENT_CONTROLLER_USE_FAKE_PROVIDER is
+ * set AND a fake has been installed via installFakeProvider(), return
+ * the fake model so pi-ai routes through our scripted stream. Otherwise
+ * return undefined and the adapter uses pi-ai.getModel() as normal.
+ *
+ * Splitting the decision this way (env var + in-process installation)
+ * means production code paths can never accidentally activate the fake
+ * — the env var alone does nothing without a script.
+ */
+export function resolveFakeModelIfRequested() {
+    if (process.env.AGENT_CONTROLLER_USE_FAKE_PROVIDER !== "1")
+        return undefined;
+    if (!activeFake) {
+        // Env var set but no installation — surface a clear warning so the
+        // test author notices, but don't throw (other code paths may set
+        // the env var transitively).
+        process.stderr.write("[agent-controller] WARNING: AGENT_CONTROLLER_USE_FAKE_PROVIDER=1 but no " +
+            "fake provider is installed. The runtime will fall back to the real model. " +
+            "Call installFakeProvider() before runSession().\n");
+        return undefined;
+    }
+    return activeFake.getModel();
+}

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+export interface CompiledSpec {
+    v: 1;
+    metadata: SpecMetadata;
+    model: Model;
+    persona?: Persona;
+    task: string;
+    tools: ResolvedRef[];
+    extensions: ResolvedRef[];
+    skills: ResolvedRef[];
+    mcpServers?: MCPServer[];
+    subagents?: ResolvedRef[];
+    /**
+     * Deprecated: use spec.extensions[].source instead.
+     * When non-empty the runtime emits a deprecation warning to stderr.
+     * Still passed through unchanged; `agentctl install --from` uses it.
+     */
+    installs?: string[];
+    runtime: RuntimeConfig;
+    guardrails?: Guardrails;
+    /** Set by CLI when user passes --resume <id>. Runtime opens/continues the named session. */
+    sessionId?: string;
+}
+/**
+ * Per-session safety guardrail configuration. Defaults are applied at use
+ * site in adapter.ts so this object can be `undefined` (no guardrails block
+ * in the spec) without forcing the compiler to materialize defaults.
+ */
+export interface Guardrails {
+    /**
+     * How the runtime reacts when the assistant fabricates tool-call XML in
+     * its message body. Defaults to "block" when absent. See honesty.ts for
+     * the behavior of each mode.
+     */
+    hallucinationDetector?: HallucinationMode;
+}
+export type HallucinationMode = "warn" | "block" | "correct";
+/** One MCP server declared in spec.mcpServers[]. Mirrors MCPServer in types.go. */
+export interface MCPServer {
+    name: string;
+    transport: "stdio" | "streamable-http" | "sse";
+    lifecycle?: "eager" | "lazy";
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+export interface SpecMetadata {
+    name: string;
+    owner?: string;
+    description?: string;
+}
+export interface Model {
+    provider: "anthropic" | "openai" | "google";
+    name: string;
+    temperature?: number;
+}
+export interface Persona {
+    role?: string;
+    instructions?: string;
+}
+export interface ResolvedRef {
+    name: string;
+    /**
+     * Absolute path to the Pi extension entrypoint. Blank when source is
+     * set OR when builtin is true (Pi ships the implementation).
+     */
+    entrypoint?: string;
+    /**
+     * Pi-builtin tool (bash, read, edit, write). The runtime adds the name
+     * to Pi's tool allowlist without loading any entrypoint.
+     */
+    builtin?: boolean;
+    /**
+     * Self-install source, e.g. "npm:pi-mcp-extension".
+     * When set the runtime installs the package if missing and resolves
+     * the entrypoint from the package's pi.extensions manifest field.
+     * Only "npm:" prefix is supported at v0.1.6.
+     */
+    source?: string;
+    config?: Record<string, unknown>;
+}
+export interface RuntimeConfig {
+    /**
+     * Which adapter the CLI dispatches the CompiledSpec to. `local` is the
+     * v0.1.x legacy alias for `local-pi` (this Pi adapter) and remains
+     * accepted by the schema for backwards compatibility. `local-opencode`
+     * routes to the opencode adapter (runtime-opencode/), added in v0.2
+     * slice 2.1. Mirror of the enum in schemas/adl.v1alpha1.json.
+     */
+    type: "local" | "local-pi" | "local-opencode";
+    /**
+     * v0.3.1 additive field: free-form capability requirements the runtime
+     * must satisfy. Boolean flags consumed in two steps: v0.3.2 adds the
+     * RuntimeBinding schema (resource advertising what capabilities a
+     * target provides), and v0.3.3 wires Backend.Resolve() to compare the
+     * two. Today (v0.3.1) it passes through CompiledSpec unchanged and
+     * adapters do not act on it. Reserved well-known keys: streaming,
+     * sandbox, gpu, restrictedNetwork, ephemeralFilesystem. Arbitrary keys
+     * are accepted so capability bundles can advertise their own flags
+     * (e.g. spark, notebookContext).
+     */
+    requirements?: Record<string, boolean>;
+}
+export type WireEventType = "session.started" | "model.request" | "model.response" | "tool.call" | "tool.result" | "message" | "session.ended" | "warning" | "error";
+export interface WireEvent<T = unknown> {
+    v: 1;
+    type: WireEventType;
+    ts: string;
+    sessionId: string;
+    data: T;
+}