@agent-controller/runtime-opencode 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CCDevelopForFun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# `@agent-controller/runtime-opencode` — opencode runtime adapter
+
+Node/TypeScript adapter that runs an [agent-controller](https://github.com/CCDevelopForFun/agent-controller) `CompiledSpec` against the [sst/opencode](https://opencode.ai) CLI via the official `@opencode-ai/sdk`, and emits the NDJSON wire-event stream that `agentctl` consumes. Sibling to the Pi adapter ([`@agent-controller/runtime`](https://www.npmjs.com/package/@agent-controller/runtime)); both consume the same `CompiledSpec` and emit the same wire-event format.
+
+Requires **Node 22+**.
+
+## Install
+
+```bash
+npm install -g @agent-controller/runtime-opencode
+# or per-project
+npm install --save-dev @agent-controller/runtime-opencode
+```
+
+The `opencode` CLI must also be on `PATH`. Install with `npm install -g opencode-ai` or follow https://opencode.ai/docs/.
+
+## Use with `agentctl`
+
+`agentctl` (the Go CLI) spawns this package as a subprocess when `spec.runtime.type` is `local-opencode`. The example specs under [`examples/`](https://github.com/CCDevelopForFun/agent-controller/tree/main/examples) reference cwd-relative registry entries that ship with the source repo but not with this npm package. For an npm-only install, use a self-contained spec:
+
+```bash
+# 1) Write a self-contained spec (no tools[]/extensions[]/skills[]/subagents[])
+cat > /tmp/hello-opencode.yaml <<'EOF'
+apiVersion: agent-controller.dev/v1alpha1
+kind: Agent
+metadata: { name: hello-opencode }
+spec:
+  model: { provider: anthropic, name: claude-sonnet-4-20250514 }
+  persona: { role: Helpful demo, instructions: Answer concisely. }
+  task: Say hello.
+  tools: []
+  runtime: { type: local-opencode }
+EOF
+
+# 2) Point agentctl at the adapter and run
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# global install
+AGENT_CONTROLLER_RUNTIME="$(npm root -g)/@agent-controller/runtime-opencode/dist/index.js" \
+  agentctl run /tmp/hello-opencode.yaml
+
+# or per-project
+AGENT_CONTROLLER_RUNTIME="./node_modules/@agent-controller/runtime-opencode/dist/index.js" \
+  agentctl run /tmp/hello-opencode.yaml
+```
+
+Credentials via environment: `ANTHROPIC_API_KEY` (and / or `ANTHROPIC_BASE_URL`). Auth from `~/.opencode/auth.json` is intentionally NOT used — the adapter isolates `HOME` to prevent ambient config leakage.
+
+`agentctl` (matching version) is available from the [GitHub Releases page](https://github.com/CCDevelopForFun/agent-controller/releases) as cross-platform binaries.
+
+## Architecture role
+
+This package is the **subprocess** spawned by `agentctl run` when `spec.runtime.type` is `local-opencode`. It:
+
+1. Reads a `CompiledSpec` JSON document from stdin
+2. Rejects unsupported ADL surface (`spec.sessionId`) at startup with a clear error (other opencode-incompatible shapes — `spec.extensions[]`, `spec.installs[]`, custom Pi-extension tools, built-ins with `config` — are rejected at `agentctl compile` since v0.3.0)
+3. Builds an opencode-native config (`cfg.agent[primary]`, `cfg.agent[subagent_N]`, `cfg.mcp[server_N]`) from the spec via `buildOpencodeConfig`
+4. Spawns opencode via `@opencode-ai/sdk`'s `createOpencode()` with an isolated `HOME` / `XDG_*` / cwd so ambient user config can't leak undeclared capabilities
+5. Submits the task via `session.promptAsync()` (non-blocking)
+6. Consumes the SSE event stream via a producer-consumer queue
+7. Translates opencode events into wire-protocol events (tool.call/result, message, session.ended/error/warning, hallucination warnings)
+8. Disables opencode's native agents (`plan`, `build`, `general`, `explore`, `scout`) so the `task` tool can't bypass the ADL allowlist
+
+## ADL allowlist preservation
+
+Several layers of defense keep ADL's "only declared capabilities are reachable" contract intact:
+
+1. Opencode permissions start from a deny baseline (`"*": "deny"` + every known opencode tool explicitly denied), then declared tools become `allow`
+2. Native opencode agents are disabled so the `task` tool can't delegate to undeclared agents
+3. MCP server names are validated against `[A-Za-z0-9._-]+` (no glob metacharacters), against opencode built-in prefixes (`repo`, `doom`, `external`), and for sanitization collisions
+4. Opencode-incompatible spec shapes are rejected at `agentctl compile` (v0.3.0)
+
+## Capability differences vs the Pi adapter
+
+See [`docs/architecture/harness-matrix.md`](https://github.com/CCDevelopForFun/agent-controller/blob/main/docs/architecture/harness-matrix.md) for the per-feature table. Highlights:
+
+| Feature | Pi adapter | opencode adapter |
+|---|---|---|
+| Custom Pi-format tools / extensions | ✅ | ❌ rejected at `agentctl compile` |
+| Session resume (`--resume`) | ✅ | ❌ rejected by `agentctl run` |
+| `task` tool / native subagent delegation | via vendored ext | ✅ native |
+| `cancelled` reason on SIGINT | ❌ (surfaces as `error`) | ✅ |
+| `bash` allowlist via tool `config` | ❌ rejected at `agentctl compile` (use [`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system)) | ❌ rejected at `agentctl compile` |
+
+## Building from source
+
+```bash
+git clone https://github.com/CCDevelopForFun/agent-controller.git
+cd agent-controller/runtime-opencode
+npm install --ignore-scripts
+npm run build           # tsc → dist/
+npm test                # vitest
+```
+
+## Cross-references
+
+- [agent-controller README](https://github.com/CCDevelopForFun/agent-controller#readme) — project overview + quickstart
+- [Dual-adapter architecture overview](https://github.com/CCDevelopForFun/agent-controller/blob/main/docs/architecture/overview.md)
+- [Harness capability matrix](https://github.com/CCDevelopForFun/agent-controller/blob/main/docs/architecture/harness-matrix.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/CCDevelopForFun/agent-controller/blob/main/LICENSE).

package/dist/event-translator.d.ts

@@ -0,0 +1,77 @@
+import type { WireEvent } from "./types.js";
+import type { GlobalEvent } from "@opencode-ai/sdk";
+export type HallucinationMode = "block" | "warn" | "correct";
+/**
+ * Per-session state shared across translateEvent calls. The caller owns
+ * one instance per session and passes it on every call. Keeps the
+ * function pure from the caller's perspective while allowing stateful
+ * text accumulation.
+ */
+export interface TranslatorState {
+    /**
+     * Tracks the last seen `part.text` snapshot for each part ID. When
+     * `properties.delta` is absent (optional in the SDK), we derive the
+     * incremental text by diffing against the previous snapshot.
+     * Codex pass 16 of slice 2.4 caught that `delta ?? ""` dropped all
+     * output for full-part update events that opencode sends without delta.
+     */
+    partTextSnapshots: Map<string, string>;
+    /** Accumulated assistant text parts for the current turn. */
+    textBuffer: string;
+    /** Message ID we're currently accumulating text for. */
+    currentMessageId: string | undefined;
+    /**
+     * Role of the current message being accumulated. TextParts arrive via
+     * message.part.updated and carry no role field; we learn the role from
+     * message.updated events and track it here so we only buffer assistant
+     * text. Codex pass 5 of slice 2.4 caught that user prompt/correction
+     * text was being buffered as assistant output.
+     */
+    currentMessageRole: "user" | "assistant" | undefined;
+    /**
+     * Map from messageID to role, populated from message.updated events.
+     * Used to look up role when a text part arrives before its message.updated.
+     */
+    messageRoles: Map<string, "user" | "assistant">;
+    /**
+     * Pre-role text buffer: keyed by messageID, accumulates deltas that
+     * arrived before the corresponding message.updated role event. When the
+     * role event arrives, we flush pre-role deltas into textBuffer (if
+     * assistant) or discard them (if user). Codex pass 10 of slice 2.4
+     * caught that "skip unknown-role text" permanently dropped early deltas
+     * that the stream would not replay.
+     */
+    preRoleBuffer: Map<string, string>;
+    /**
+     * Set of tool callIDs for which we have already emitted a `tool.call`
+     * wire event. Guards against emitting duplicate tool.call events when
+     * opencode sends multiple `message.part.updated` events while the same
+     * tool part stays in "running" status (streamed input JSON, progress
+     * metadata, etc.). Codex pass 13 of slice 2.4 caught this.
+     */
+    emittedToolCalls: Set<string>;
+}
+export declare function createTranslatorState(): TranslatorState;
+/**
+ * Result of translating a single opencode GlobalEvent into zero or more
+ * wire events. `sessionIdle` signals the caller that the model has
+ * finished its turn and no more events are coming for this prompt.
+ * `sessionError` signals a terminal failure the caller should surface.
+ */
+export interface TranslationResult {
+    wireEvents: WireEvent[];
+    sessionIdle: boolean;
+    sessionError: string | undefined;
+}
+/**
+ * Translate one opencode GlobalEvent to wire events.
+ *
+ * @param gev           The raw GlobalEvent from the SSE stream.
+ * @param sessionId     The stable session ID the caller selected.
+ * @param targetSession The opencode session ID (from session.create) — we
+ *                      ignore events for other sessions that might arrive
+ *                      on the same SSE stream.
+ * @param state         Mutable translator state (text accumulation).
+ * @param hallucinationMode  Block/warn/correct guardrail, from spec.guardrails.
+ */
+export declare function translateEvent(gev: GlobalEvent, sessionId: string, targetSession: string, state: TranslatorState, hallucinationMode?: HallucinationMode): TranslationResult;

package/dist/event-translator.js

@@ -0,0 +1,322 @@
+/**
+ * Translate opencode's SSE event stream into our wire-protocol events.
+ *
+ * Phase 2 slice 2.4 — this is the core mapping layer between the opencode
+ * SDK's event model and the NDJSON wire protocol that `agentctl run` reads.
+ *
+ * Wire protocol reference: runtime/src/types.ts (WireEventType union) and
+ * cli/internal/wire/events.go. Changes here must stay in sync with both.
+ *
+ * opencode's data model: text content arrives via `message.part.updated`
+ * events (TextPart streaming), not from the Message object itself
+ * (AssistantMessage.summary is a boolean flag, not text). We accumulate
+ * text in a per-session buffer and emit the full assembled text as a wire
+ * `message` event when `session.idle` signals the turn is complete. This
+ * mirrors the Pi adapter's behaviour (emit whole-message events, not
+ * per-token deltas).
+ *
+ * Events translated:
+ *   message.part.updated (TextPart) → accumulated in textBuffer; flushed
+ *                                      as wire `message` on session.idle
+ *   message.part.updated (ToolPart, running)   → wire `tool.call`
+ *   message.part.updated (ToolPart, completed) → wire `tool.result`
+ *   message.part.updated (ToolPart, error)     → wire `tool.result` (isError=true)
+ *   message.updated (user, with summary)       → wire `message` (role=user)
+ *   session.idle                               → flushes text buffer + signals
+ *                                                "turn complete" to caller
+ *   session.error                              → signals terminal failure
+ *
+ * Events intentionally NOT translated:
+ *   file.edited, session.compacted, todo.updated, session.diff
+ *   pty.*, lsp.*, tui.*, etc.    — implementation noise, not ADL surface
+ */
+import { stamp } from "./wire.js";
+import { detectHallucinatedToolCalls, stripHallucinationXml } from "./honesty.js";
+/**
+ * Flush the current text buffer to wireEvents, running hallucination
+ * detection first. Used both at session.idle (normal path) and when a
+ * new messageID arrives mid-turn (multi-message turns in tool-using
+ * sessions). Modifies state.textBuffer. Codex pass 30 of slice 2.4
+ * caught that intermediate flushes bypassed guardrail checks.
+ */
+function flushBuffer(text, sessionId, hallucinationMode, wireEvents) {
+    if (!text)
+        return undefined;
+    const findings = detectHallucinatedToolCalls(text);
+    if (findings.length > 0) {
+        if (hallucinationMode === "block") {
+            const errMsg = `Assistant message contains fabricated tool-call XML: ${findings.join(", ")}. ` +
+                `The model is hallucinating tool invocations instead of using the runtime's tool channel.`;
+            wireEvents.push(stamp(sessionId, "error", {
+                kind: "hallucinated_tool_call",
+                mode: hallucinationMode,
+                message: errMsg,
+                patterns: findings,
+            }));
+            return `Assistant message contained fabricated tool-call XML (${findings.join(", ")})`;
+        }
+        const { text: scrubbed } = stripHallucinationXml(text);
+        wireEvents.push(stamp(sessionId, "warning", {
+            kind: "hallucinated_tool_call",
+            mode: hallucinationMode,
+            message: `Fabricated tool-call XML stripped from message: ${findings.join(", ")}.`,
+            patterns: findings,
+        }));
+        wireEvents.push(stamp(sessionId, "message", { text: scrubbed, role: "assistant" }));
+    }
+    else {
+        wireEvents.push(stamp(sessionId, "message", { text, role: "assistant" }));
+    }
+    return undefined;
+}
+export function createTranslatorState() {
+    return {
+        partTextSnapshots: new Map(),
+        textBuffer: "",
+        currentMessageId: undefined,
+        currentMessageRole: undefined,
+        messageRoles: new Map(),
+        preRoleBuffer: new Map(),
+        emittedToolCalls: new Set(),
+    };
+}
+/**
+ * Translate one opencode GlobalEvent to wire events.
+ *
+ * @param gev           The raw GlobalEvent from the SSE stream.
+ * @param sessionId     The stable session ID the caller selected.
+ * @param targetSession The opencode session ID (from session.create) — we
+ *                      ignore events for other sessions that might arrive
+ *                      on the same SSE stream.
+ * @param state         Mutable translator state (text accumulation).
+ * @param hallucinationMode  Block/warn/correct guardrail, from spec.guardrails.
+ */
+export function translateEvent(gev, sessionId, targetSession, state, hallucinationMode = "block") {
+    const ev = gev.payload;
+    const wireEvents = [];
+    let sessionIdle = false;
+    let sessionError;
+    switch (ev.type) {
+        case "message.updated": {
+            const msg = ev.properties.info;
+            if (msg.sessionID !== targetSession)
+                break;
+            const role = msg.role;
+            // Track role so text-accumulation in message.part.updated below
+            // can decide whether to buffer (assistant only). Codex pass 5 caught
+            // that text parts carry no role and user prompt text was being buffered.
+            state.messageRoles.set(msg.id, role);
+            // Flush any pre-role buffer that accumulated before this event.
+            // Codex pass 10 caught that "skip unknown-role text" permanently
+            // dropped early deltas — we now stash them and flush here.
+            const preRoleText = state.preRoleBuffer.get(msg.id);
+            if (preRoleText) {
+                state.preRoleBuffer.delete(msg.id);
+                if (role === "assistant") {
+                    // Retroactively add the pre-role text to the main buffer. If we
+                    // were already buffering a different message, flush it first with
+                    // guardrail checks — codex pass 30 caught the silent drop.
+                    if (state.currentMessageId !== msg.id) {
+                        if (state.textBuffer && state.currentMessageRole === "assistant") {
+                            const err = flushBuffer(state.textBuffer, sessionId, hallucinationMode, wireEvents);
+                            if (err)
+                                sessionError ??= err;
+                        }
+                        state.textBuffer = "";
+                        state.currentMessageId = msg.id;
+                        state.currentMessageRole = "assistant";
+                    }
+                    state.textBuffer += preRoleText;
+                }
+                else if (role === "user") {
+                    // Emit user pre-role text as a wire message event immediately.
+                    // Codex pass 26 of slice 2.4 caught that discarding it broke
+                    // trace parity — the known-role path emits user messages, so
+                    // the out-of-order case must too.
+                    wireEvents.push(stamp(sessionId, "message", { text: preRoleText, role: "user" }));
+                }
+            }
+            // No wire event emitted from message.updated — text arrives via
+            // message.part.updated deltas and is flushed on session.idle.
+            break;
+        }
+        case "message.part.updated": {
+            const part = ev.properties.part;
+            if (!part || part.sessionID !== targetSession)
+                break;
+            // Tool parts MUST be checked first. ToolPart updates can arrive with a
+            // non-empty `properties.delta` (opencode streams the input JSON as the
+            // model generates it). If we checked `isTextOrHasDelta` first, a
+            // ToolPart with a delta would be erroneously buffered as assistant text
+            // and the tool.call / tool.result wire events would be skipped.
+            // Codex pass 7 of slice 2.4 caught this ordering bug.
+            if (isToolPart(part)) {
+                const toolPart = part;
+                const toolState = toolPart.state;
+                if (toolState.status === "running") {
+                    // Emit tool.call exactly once per callID. opencode can send
+                    // multiple "running" updates as input is streamed or metadata
+                    // changes. Downstream wire consumers expect a single tool.call
+                    // followed by tool.result — guard with the seen-IDs set.
+                    // Codex pass 13 of slice 2.4 caught the duplicate emission.
+                    if (!state.emittedToolCalls.has(toolPart.callID)) {
+                        state.emittedToolCalls.add(toolPart.callID);
+                        wireEvents.push(stamp(sessionId, "tool.call", {
+                            toolName: toolPart.tool,
+                            callId: toolPart.callID,
+                            args: toolState.input,
+                        }));
+                    }
+                }
+                else if (toolState.status === "completed") {
+                    wireEvents.push(stamp(sessionId, "tool.result", {
+                        callId: toolPart.callID,
+                        isError: false,
+                        content: toolState.output,
+                    }));
+                }
+                else if (toolState.status === "error") {
+                    const errState = toolState;
+                    const errOut = errState.error ?? "tool error (no detail)";
+                    wireEvents.push(stamp(sessionId, "tool.result", {
+                        callId: toolPart.callID,
+                        isError: true,
+                        content: errOut,
+                    }));
+                }
+                break;
+            }
+            // Text accumulation: only accumulate delta from TextParts. Reasoning
+            // parts, thinking blocks, and other non-text part types also carry
+            // `properties.delta`, but they must NOT be emitted as user-visible
+            // message text. Codex pass 9 of slice 2.4 caught that the earlier
+            // "any non-tool part with a delta" condition leaked reasoning into the
+            // wire `message` event. Restrict strictly to part.type === "text".
+            if (isTextPart(part)) {
+                const msgID = part.messageID;
+                if (!msgID)
+                    break;
+                // Resolve the role for this text part. message.updated events are
+                // supposed to arrive before message.part.updated for the same
+                // message, but race conditions can occur.
+                const role = state.messageRoles.get(msgID) ??
+                    (state.currentMessageId === msgID ? state.currentMessageRole : undefined);
+                // Derive the incremental text first (before role checks) so all
+                // branches can use it. Prefer `properties.delta` when present.
+                // When delta is absent (SDK type makes it optional), derive from
+                // the diff against the previous part.text snapshot. Codex pass
+                // 16 of slice 2.4 caught that `delta ?? ""` dropped all output
+                // for full-part update events without a delta field.
+                const evDeltaOptional = ev.properties.delta;
+                const currText = part.text ?? "";
+                // Always update snapshot so subsequent no-delta events compute
+                // diffs from the correct baseline. Codex pass 17 caught staleness.
+                const prevText = state.partTextSnapshots.get(part.id) ?? "";
+                state.partTextSnapshots.set(part.id, currText);
+                let delta;
+                if (evDeltaOptional !== undefined) {
+                    delta = evDeltaOptional;
+                }
+                else {
+                    delta = currText.startsWith(prevText) ? currText.slice(prevText.length) : currText;
+                }
+                // Emit user-role text parts immediately as wire message events
+                // so the audit trace matches the Pi adapter. User text is NOT run
+                // through the hallucination detector. Codex pass 18 caught that
+                // we were silently dropping user text.
+                if (role === "user") {
+                    if (!part.synthetic && delta) {
+                        wireEvents.push(stamp(sessionId, "message", { text: delta, role: "user" }));
+                    }
+                    break;
+                }
+                // Only accumulate text when we KNOW the message is assistant.
+                // Accumulating user prompt/correction text would trip the hallucination
+                // detector (CORRECTION_PROMPT itself contains <invoke>-like XML).
+                // Codex passes 5 + 8 of slice 2.4 refined this rule.
+                if (role !== undefined && role !== "assistant")
+                    break;
+                // (delta is already computed above)
+                if (role === undefined) {
+                    // Role not yet known — stash in pre-role buffer (if non-synthetic).
+                    if (!part.synthetic && delta) {
+                        const prev = state.preRoleBuffer.get(msgID) ?? "";
+                        state.preRoleBuffer.set(msgID, prev + delta);
+                    }
+                    break;
+                }
+                const synthetic = part.synthetic;
+                if (state.currentMessageId !== msgID) {
+                    // Flush the previous assistant buffer before switching — include
+                    // guardrail checks so intermediate messages are also scanned.
+                    // Codex pass 29 introduced the flush; pass 30 caught it skipped
+                    // hallucinaton detection.
+                    if (state.textBuffer && state.currentMessageRole === "assistant") {
+                        const err = flushBuffer(state.textBuffer, sessionId, hallucinationMode, wireEvents);
+                        if (err)
+                            sessionError ??= err;
+                    }
+                    state.textBuffer = "";
+                    state.currentMessageId = msgID;
+                    state.currentMessageRole = role;
+                }
+                if (!synthetic && delta) {
+                    state.textBuffer += delta;
+                }
+                break;
+            }
+            // Non-text, non-tool part (reasoning, file, step marker, etc.) — ignore.
+            break;
+        }
+        case "session.idle": {
+            if (ev.properties.sessionID !== targetSession)
+                break;
+            // Flush the final assistant text buffer via flushBuffer (shared helper
+            // that also runs hallucination guardrails). This is the same path
+            // used for intermediate messageID flushes in multi-message turns.
+            const rawText = state.textBuffer;
+            state.textBuffer = "";
+            state.currentMessageId = undefined;
+            if (rawText) {
+                const err = flushBuffer(rawText, sessionId, hallucinationMode, wireEvents);
+                if (err)
+                    sessionError ??= err;
+            }
+            sessionIdle = true;
+            break;
+        }
+        case "session.error": {
+            // Accept this error when either:
+            //   (a) the sessionID matches our target session, OR
+            //   (b) sessionID is absent — allowed by the SDK type; since we spawn
+            //       a dedicated one-session server, unscoped errors are ours.
+            // Codex pass 8 of slice 2.4 caught that strict equality dropped
+            // terminal errors when sessionID was undefined.
+            const errSessionID = ev.properties.sessionID;
+            if (errSessionID !== undefined && errSessionID !== targetSession)
+                break;
+            const err = ev.properties.error;
+            const errMsg = err && "data" in err
+                ? String(err.data.message ?? JSON.stringify(err))
+                : "opencode session.error (no detail)";
+            sessionError ??= errMsg;
+            break;
+        }
+        // All other event types are intentionally ignored.
+        default:
+            break;
+    }
+    return { wireEvents, sessionIdle, sessionError };
+}
+// ── helpers ────────────────────────────────────────────────────────────────
+function isToolPart(part) {
+    return (typeof part === "object" &&
+        part !== null &&
+        part.type === "tool");
+}
+function isTextPart(part) {
+    return (typeof part === "object" &&
+        part !== null &&
+        part.type === "text" &&
+        typeof part.text === "string");
+}

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.";