toolnexus 0.18.0 → 0.19.0

package/dist/skill.js

@@ -13,6 +13,7 @@ import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
+import { compareCodePoints, compareDiscovery, sortEntriesByName } from "./order.js";
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
@@ -25,39 +26,84 @@ The skill name must match one of the skills listed in your system prompt.`;
 export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions and workflows for specific tasks.\n" +
     "Use the skill tool to load a skill when a task matches its description.";
 /**
- * Parse YAML frontmatter (between the leading `---` fences) with a real YAML
- * parser, so folded (`>`)/literal (`|`) block scalars, quoting, and multi-line
- * values all resolve correctly. Scalar values are coerced to strings.
+ * Parse YAML frontmatter (between the leading `---` fences) with a real YAML parser, so folded
+ * (`>`)/literal (`|`) block scalars, quoting and multi-line values all resolve correctly.
+ * Scalar values are coerced to strings.
  *
- * `malformed` is true only when fences are present but the YAML fails to parse —
- * distinguishing a malformed header from a body with no frontmatter, so the
- * inventory (S3) can report the right skip reason. loadSkills' behavior is
- * unchanged: a malformed header yields no name and the skill is skipped.
+ * LENIENT FALLBACK (ADR 0028, issue #93) — **YAML FIRST**. A line-wise `key: rest-of-line` read
+ * of `name`/`description` runs ONLY on frontmatter a real YAML parser has ALREADY refused.
+ * The order is the whole point: line-wise FIRST misparses legitimate YAML (`description: |`
+ * becomes `"|"`, a continued plain scalar truncates to its first line), and running it only
+ * after a refusal means it can never see a file whose YAML semantics matter — by construction
+ * those files have none left to preserve. No file that parses today changes value.
+ *
+ * `malformed` is true only when fences are present, YAML refused, AND the rescue found no name.
  */
+const LENIENT_KEYS = ["name", "description"];
+/** A value opening one of these is a construct the rescue does not implement — refused, never
+ *  guessed, so a half-broken block scalar degrades to "no description", not to `"|"`. */
+const LENIENT_REFUSED_OPENERS = new Set(["|", ">", "&", "*", "[", "{", "!"]);
+/** Column 0, ordinary key characters, one `:`; the value is the rest of the line. */
+const LENIENT_LINE = /^([A-Za-z0-9_][A-Za-z0-9_.-]*):[ \t]*(.*)$/;
+function unquoteScalar(v) {
+    const t = v.trim();
+    if (t.length > 1 && (t[0] === '"' || t[0] === "'") && t[t.length - 1] === t[0])
+        return t.slice(1, -1);
+    return t;
+}
+/** Rescue `name`/`description` from a frontmatter block YAML refused. First-wins, column 0. */
+function lineWiseFrontmatter(block) {
+    const data = {};
+    for (const raw of block.split(/\r?\n/)) {
+        const head = raw.slice(0, 1);
+        // indented continuation, comment, or blank — not a top-level key
+        if (head === " " || head === "\t" || head === "#" || head === "")
+            continue;
+        const m = LENIENT_LINE.exec(raw);
+        if (!m)
+            continue;
+        const key = m[1];
+        const value = m[2].trim();
+        if (!LENIENT_KEYS.includes(key) || key in data)
+            continue;
+        if (!value || LENIENT_REFUSED_OPENERS.has(value[0]))
+            continue;
+        data[key] = unquoteScalar(value);
+    }
+    return data;
+}
 function parseFrontmatter(text) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!match)
         return { data: {}, content: text, malformed: false };
     const data = {};
     let parsed;
-    let malformed = false;
+    let detail;
     try {
         parsed = parseYaml(match[1]);
     }
-    catch {
+    catch (e) {
         parsed = null;
-        malformed = true;
+        detail = e instanceof Error ? e.message : String(e);
     }
-    if (parsed && typeof parsed === "object") {
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
         for (const [key, value] of Object.entries(parsed)) {
             // Trim so block-scalar trailing newlines (chomping differs subtly between
-            // YAML libs) don't leak — keeps the five ports byte-identical.
+            // YAML libs) don't leak — keeps the ports byte-identical.
             if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
                 data[key] = String(value).trim();
             }
         }
+        return { data, content: match[2], malformed: false };
     }
-    return { data, content: match[2], malformed };
+    // YAML refused (threw, or produced something that is not a mapping): rescue the two scalars.
+    const rescued = lineWiseFrontmatter(match[1]);
+    return {
+        data: rescued,
+        content: match[2],
+        malformed: !rescued.name,
+        detail: detail ?? (rescued.name ? undefined : "frontmatter is not a YAML mapping"),
+    };
 }
 function walkSkillFiles(root) {
     const out = [];
@@ -69,11 +115,17 @@ function walkSkillFiles(root) {
         const dir = stack.pop();
         let entries;
         try {
-            entries = readdirSync(dir, { withFileTypes: true });
+            // EXPLICIT (A24): `readdirSync` is sorted on most platforms, but Node guarantees
+            // nothing. An absent sort over a directory read is the same defect class as a wrong one,
+            // and it is invisible to a grep for comparators.
+            entries = sortEntriesByName(readdirSync(dir, { withFileTypes: true }));
         }
         catch {
             continue;
         }
+        // Subdirectories are pushed REVERSED so the LIFO stack pops them in name order.
+        for (const entry of [...entries].reverse().filter((e) => e.isDirectory() || e.isSymbolicLink()).reverse().concat([]))
+            void entry;
         for (const entry of entries) {
             const full = path.join(dir, entry.name);
             let isDir = entry.isDirectory();
@@ -111,11 +163,23 @@ function walkSkillFiles(root) {
     }
     return out;
 }
+/**
+ * The `<skill_files>` SAMPLE LIST: sibling resources shown to the model when a skill is loaded.
+ *
+ * This is SHIPPED OUTPUT, so its order is part of the cross-port contract (addendum A22). It
+ * used to be raw `readdirSync` order over a LIFO `stack.pop()` walk with the cap applied MID
+ * TRAVERSAL — so the filesystem decided not merely how the sample was ordered but WHICH files
+ * appeared in it at all. Now: collect everything, then order by DEPTH ascending then Unicode
+ * CODE POINT over the path relative to the skill dir (the same `compareDiscovery` rule as
+ * discovery), and only then apply the cap. The sample is therefore a function of the tree and
+ * the cap alone — never of readdir order, and stable across machines and platforms. The
+ * ordering is PLAIN Unicode code point over the relative path (A25).
+ */
 function sampleSiblingFiles(dir, limit = 10) {
-    const out = [];
+    const found = [];
     const stack = [dir];
     const seen = new Set();
-    while (stack.length && out.length < limit) {
+    while (stack.length) {
         const cur = stack.pop();
         let entries;
         try {
@@ -125,8 +189,6 @@ function sampleSiblingFiles(dir, limit = 10) {
             continue;
         }
         for (const entry of entries) {
-            if (out.length >= limit)
-                break;
             const full = path.join(cur, entry.name);
             let isDir = entry.isDirectory();
             let isFile = entry.isFile();
@@ -156,11 +218,17 @@ function sampleSiblingFiles(dir, limit = 10) {
                 stack.push(full);
             }
             else if (isFile && entry.name !== "SKILL.md") {
-                out.push(full);
+                found.push(full);
             }
         }
     }
-    return out;
+    // Order FIRST, cap SECOND: capping during the walk let readdir order pick the sample.
+    // PLAIN code point over the path relative to the skill dir (A25) — NOT the discovery rule.
+    // A15's depth rule exists to decide WHICH FILE a duplicated skill NAME resolves to; it has no
+    // business ordering a flat listing, where it would interleave `a-root.txt, z-root.txt,
+    // alpha/f.txt` instead of `a-root.txt, alpha/f.txt, z-root.txt`.
+    found.sort((a, b) => compareCodePoints(path.relative(dir, a), path.relative(dir, b)));
+    return found.slice(0, limit);
 }
 /** Discover candidates under one on-disk root (order = discovery order). */
 function candidatesFromDir(root) {
@@ -176,18 +244,27 @@ function candidatesFromDir(root) {
         console.warn(`[toolnexus] skills dir not found: ${root}`);
         return out;
     }
-    for (const file of walkSkillFiles(root)) {
+    // DISCOVERY ORDER (addendum A1/A1a/A15): dirs in the order the CALLER passed them; within a
+    // dir, by DEPTH ASCENDING, then Unicode CODE-POINT comparison of the path relative to that dir.
+    // A symlink sorts at its DISCOVERED path, never its target.
+    //
+    // Depth comes FIRST, and that is the whole rule: code point alone makes the winner depend on
+    // the skill's own first letter. `docx`/`pdf`/`pptx` beat `synced/<uuid>/…` because d/p < s —
+    // but `xlsx` LOSES to it, because x > s. Depth-first makes "a shallower path beats a nested
+    // copy of the same name" true for EVERY name, which is what SPEC §3 already claims.
+    const files = walkSkillFiles(root).sort((a, b) => compareDiscovery(path.relative(root, a), path.relative(root, b), path.sep));
+    for (const file of files) {
         let text;
         try {
             text = readFileSync(file, "utf8");
         }
-        catch {
-            out.push({ skip: { location: file, reason: "unreadable" } });
+        catch (e) {
+            out.push({ skip: { location: file, reason: "unreadable", detail: e instanceof Error ? e.message : String(e) } });
             continue;
         }
-        const { data, content, malformed } = parseFrontmatter(text);
+        const { data, content, malformed, detail } = parseFrontmatter(text);
         if (malformed) {
-            out.push({ skip: { location: file, reason: "malformed-frontmatter" } });
+            out.push({ skip: { location: file, reason: "malformed-frontmatter", ...(detail ? { detail } : {}) } });
             continue;
         }
         if (!data.name) {
@@ -286,6 +363,7 @@ export function loadSkills(input) {
     const sampleLimit = opts.sampleLimit ?? 0;
     const merged = mergeCandidates(collectCandidates(opts));
     const skills = applySkillsFilter(merged.skills, opts.filter);
+    const skipped = merged.skipped;
     const tool = {
         name: "skill",
         description: SKILL_TOOL_DESCRIPTION,
@@ -301,7 +379,7 @@ export function loadSkills(input) {
             const info = skills[name];
             if (!info) {
                 return {
-                    output: `Skill "${name}" not found. Available skills: ${Object.keys(skills).sort().join(", ") || "none"}`,
+                    output: `Skill "${name}" not found. Available skills: ${Object.keys(skills).sort(compareCodePoints).join(", ") || "none"}`,
                     isError: true,
                 };
             }
@@ -347,10 +425,15 @@ export function loadSkills(input) {
     return {
         skills,
         tool,
+        skipped,
         prompt() {
             const described = Object.values(skills)
                 .filter((s) => s.description !== undefined)
-                .sort((a, b) => a.name.localeCompare(b.name));
+                // Unicode CODE POINT over the skill name, never `localeCompare` (addendum A22): a
+                // locale collation orders by the machine's ICU data, so the same build emitted a
+                // DIFFERENTLY ORDERED prompt on two machines. SPEC §0.10 pins this prompt as
+                // byte-identical across ports; it was not even stable within js.
+                .sort((a, b) => compareCodePoints(a.name, b.name));
             if (described.length === 0)
                 return "No skills are currently available.";
             return [

package/dist/types.d.ts

@@ -52,6 +52,17 @@ export interface Answer {
      */
     reason?: "declined" | "cancelled" | "expired";
 }
+/**
+ * Typed constructor for the common resume payload: "here is the tool's output" (ADR 0026 D2).
+ * Hand-building `{ id, ok: true, data: { output } }` is where hosts get the key wrong; this
+ * removes the key from the host's hands entirely.
+ *
+ * `output` MUST be a string. A non-string is an ERROR, never a silent degrade to `""` — a
+ * fabricated empty result is indistinguishable from an answer the human never gave.
+ */
+export declare function answerOutput(id: string, output: string): Answer;
+/** The matching refusal: `ok:false` with an advisory reason the loop does not branch on. */
+export declare function answerDeclined(id: string, reason?: Answer["reason"]): Answer;
 /** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
 export declare function pending(request: Omit<Request, "id"> & {
     id?: string;

package/dist/types.js

@@ -1,6 +1,28 @@
 /**
  * Shared contract types. See ../../SPEC.md.
  */
+/**
+ * Typed constructor for the common resume payload: "here is the tool's output" (ADR 0026 D2).
+ * Hand-building `{ id, ok: true, data: { output } }` is where hosts get the key wrong; this
+ * removes the key from the host's hands entirely.
+ *
+ * `output` MUST be a string. A non-string is an ERROR, never a silent degrade to `""` — a
+ * fabricated empty result is indistinguishable from an answer the human never gave.
+ */
+export function answerOutput(id, output) {
+    if (typeof output !== "string") {
+        throw new TypeError(`answerOutput: output must be a string, got ${output === null ? "null" : typeof output}`);
+    }
+    if (!id)
+        throw new TypeError("answerOutput: id is required (it must match the Request's id)");
+    return { id, ok: true, data: { output } };
+}
+/** The matching refusal: `ok:false` with an advisory reason the loop does not branch on. */
+export function answerDeclined(id, reason = "declined") {
+    if (!id)
+        throw new TypeError("answerDeclined: id is required (it must match the Request's id)");
+    return { id, ok: false, reason };
+}
 let _pendingSeq = 0;
 /** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
 export function pending(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/issues.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts",
     "example:judge": "node --experimental-strip-types examples/judge.ts",
     "example:multimodal": "node --experimental-strip-types examples/multimodal.ts"

package/src/acp.ts

@@ -0,0 +1,308 @@
+/**
+ * ACP (Agent Client Protocol) model source — issue #96, ADR 0031
+ * ("ACP: the warm session is the feature, and it breaks the stateless request"),
+ * openspec/changes/add-acp-model-source.
+ *
+ * ACP is to *agents* what MCP is to *tools*: JSON-RPC 2.0, one object per line,
+ * over a child process's stdin/stdout (`devin acp`, Gemini CLI, Zed's agents all
+ * speak it). This file ships ACP as nothing more than a `generate` function —
+ * the exact shape {@link InProcessOptions.generate} already defines — so the
+ * tool-calling loop, skills, MCP tools, adapters and sub-agents are entirely
+ * untouched. `loadACP` opens the connection once (`initialize` → `session/new` →
+ * optional `session/set_mode`) and hands back an {@link ACPClient} whose
+ * `.generate` can be passed straight to {@link createInProcessClient}.
+ *
+ * The hard part is not the JSON-RPC plumbing — it is that an ACP session is
+ * *stateful* while every other toolnexus model source is stateless-by-default.
+ * toolnexus assembles a complete request every turn; sending the whole thing
+ * into a session that already remembers the transcript makes some agents answer
+ * a near-duplicate prompt from stale history (reproduced in `spikes/acp/`).
+ * The mitigation (kept as the default, not left to the caller) is an explicit
+ * "this supersedes everything earlier" marker appended to every rendered
+ * prompt — see {@link renderPrompt}.
+ *
+ * Three more traps this client exists to close, all proven in the spike:
+ *  - `session/update` notifications interleave with JSON-RPC replies on the
+ *    same stdout stream, so everything arriving is demultiplexed by id.
+ *  - Only `agent_message_chunk` text may be accumulated into the reply —
+ *    `agent_thought_chunk` and tool-call narration wrap prose around
+ *    structured output and corrupt it if mixed in.
+ *  - An unanswered `session/request_permission` hangs the turn FOREVER, even
+ *    in an agent's bypass mode. The client answers with the first `allow`-kind
+ *    option the instant the request arrives; `permissionTimeoutMs` is only a
+ *    safety net for a broken agent that never asks and never replies at all.
+ */
+import { spawn } from "node:child_process"
+import { createInterface } from "node:readline"
+import path from "node:path"
+import type { InProcessRequest, InProcessResponse } from "./client.js"
+
+/** Options for {@link loadACP}. `command`/`args` spawn the ACP agent as a child
+ *  process; everything else tunes the session handshake. */
+export interface ACPOptions {
+  /** The ACP agent binary, e.g. `"devin"`. */
+  command: string
+  /** Arguments to the agent, e.g. `["acp"]`. */
+  args?: string[]
+  /** Working directory for `session/new`. Real ACP agents (e.g. `devin acp`)
+   *  reject a relative `cwd` with `-32602 Invalid params` — this is always
+   *  resolved to an absolute path before it is sent. Default: `process.cwd()`. */
+  cwd?: string
+  /** Extra environment variables for the child, merged over the current
+   *  process environment. */
+  env?: Record<string, string>
+  /** ACP `initialize` protocolVersion. Default `1`. */
+  protocolVersion?: number
+  /** Safety-net timeout (ms) for one `session/prompt` turn — NOT specifically
+   *  for the permission handshake, which this client always answers instantly.
+   *  It exists only so a broken/unresponsive agent cannot hang a caller
+   *  forever. Default 30000. */
+  permissionTimeoutMs?: number
+  /** Optional `session/set_mode` sent once, right after `session/new`. */
+  mode?: string
+}
+
+/** One warm ACP connection: one child process, one session, alive across many
+ *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
+ *  wants, so it plugs straight into {@link createInProcessClient}. */
+export interface ACPClient {
+  generate: (request: InProcessRequest) => Promise<InProcessResponse>
+  /** Terminates the agent process. Idempotent — a second call is a no-op. */
+  close: () => Promise<void>
+}
+
+/** The literal marker every rendered prompt ends with, naming the current
+ *  turn as the one to answer. Kept as a named constant (not just inlined)
+ *  because the exact wording is shared, by convention, with the other
+ *  language ports and the spike that proved it fixes the stale-answer bug. */
+const SUPERSEDES_MARKER = "SUPERSEDES-ALL-PRIOR:"
+
+interface RpcMessage {
+  jsonrpc?: string
+  id?: string | number
+  method?: string
+  params?: any
+  result?: any
+  error?: { code: number; message: string }
+}
+
+function renderContentPart(part: any): string {
+  if (typeof part === "string") return part
+  if (part == null) return ""
+  if (typeof part === "object" && "text" in part && typeof part.text === "string") return part.text
+  return JSON.stringify(part)
+}
+
+/** Flattens `content` (a string, or an array of content parts) to plain text. */
+function renderContent(content: any): string {
+  if (typeof content === "string") return content
+  if (Array.isArray(content)) return content.map(renderContentPart).join(" ")
+  return renderContentPart(content)
+}
+
+/** Renders the FULL assembled request as one prompt string — role + content
+ *  per message — then appends the supersedes marker naming the latest user
+ *  turn, per ADR 0031's proposed (and spike-confirmed) default: full request
+ *  every turn, not a delta, so this stays stateless like every other
+ *  toolnexus model source and never risks a shadow transcript drifting from
+ *  the caller's own conversation state. */
+function renderPrompt(request: InProcessRequest): string {
+  const messages = request.messages ?? []
+  const lines = messages.map((m) => `${m?.role ?? "user"}: ${renderContent(m?.content)}`)
+
+  let latest = ""
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === "user") {
+      latest = renderContent(messages[i].content)
+      break
+    }
+  }
+  if (!latest && messages.length > 0) latest = renderContent(messages[messages.length - 1]?.content)
+
+  lines.push(`${SUPERSEDES_MARKER} ${latest}`)
+  return lines.join("\n")
+}
+
+/**
+ * Opens one ACP connection: spawns `command`, performs `initialize` →
+ * `session/new` (with an absolute `cwd` and an `mcpServers` array — the exact
+ * trap real `devin acp` enforces with `-32602` otherwise) → an optional
+ * `session/set_mode`, then returns a client whose `.generate` sends exactly
+ * one `session/prompt` per call, accumulating only `agent_message_chunk`
+ * text.
+ */
+export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
+  const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd()
+  const permissionTimeoutMs = opts.permissionTimeoutMs ?? 30000
+
+  const child = spawn(opts.command, opts.args ?? [], {
+    cwd,
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+    stdio: ["pipe", "pipe", "ignore"],
+  })
+
+  let closed = false
+  let nextId = 0
+  const pending = new Map<string, (msg: RpcMessage) => void>()
+  let updateSink: ((params: any) => void) | null = null
+
+  const rl = createInterface({ input: child.stdout! })
+  rl.on("line", (raw) => {
+    const line = raw.trim()
+    if (!line) return
+    let msg: RpcMessage
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      return
+    }
+    handleLine(msg)
+  })
+
+  function write(msg: Record<string, unknown>): void {
+    child.stdin!.write(JSON.stringify(msg) + "\n")
+  }
+
+  function reply(id: unknown, result: unknown): void {
+    write({ jsonrpc: "2.0", id, result })
+  }
+
+  function call(method: string, params: unknown): Promise<any> {
+    const id = `c-${++nextId}`
+    return new Promise((resolve, reject) => {
+      pending.set(id, (msg) => {
+        if (msg.error) reject(new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`))
+        else resolve(msg.result)
+      })
+      write({ jsonrpc: "2.0", id, method, params })
+    })
+  }
+
+  /** Demultiplexes EVERYTHING arriving on stdout: replies to our requests
+   *  (matched by JSON-RPC id), `session/update` notifications (interleaved
+   *  with replies, routed to whichever turn is in flight), and
+   *  server-initiated requests like `session/request_permission`. */
+  function handleLine(msg: RpcMessage): void {
+    if (msg.method === undefined && msg.id !== undefined) {
+      const cb = pending.get(String(msg.id))
+      if (cb) {
+        pending.delete(String(msg.id))
+        cb(msg)
+      }
+      return
+    }
+    if (msg.method === "session/update") {
+      updateSink?.(msg.params)
+      return
+    }
+    if (msg.method === "session/request_permission" && msg.id !== undefined) {
+      answerPermission(msg)
+      return
+    }
+    // An unhandled server->client request still needs a reply or a
+    // strict agent may itself hang waiting on one.
+    if (msg.id !== undefined) reply(msg.id, {})
+  }
+
+  /** Answers with the FIRST option whose `kind` starts with `allow` — an
+   *  unanswered permission request hangs the turn forever (proven in
+   *  spikes/acp). This runs the instant the request arrives, never waiting
+   *  for anything else. */
+  function answerPermission(req: RpcMessage): void {
+    const options: Array<{ optionId: string; kind?: string }> = req.params?.options ?? []
+    const chosen = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow"))
+    const result = chosen
+      ? { outcome: { outcome: "selected", optionId: chosen.optionId } }
+      : { outcome: { outcome: "cancelled" } }
+    reply(req.id, result)
+  }
+
+  await call("initialize", {
+    protocolVersion: opts.protocolVersion ?? 1,
+    clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+  })
+
+  const sessionResult = await call("session/new", { cwd, mcpServers: [] })
+  const sessionId = sessionResult?.sessionId
+
+  if (opts.mode) {
+    await call("session/set_mode", { sessionId, modeId: opts.mode })
+  }
+
+  // Serialises turns: one ACP session is one conversation, so concurrent
+  // prompts must not interleave into it. Idiomatic promise-chaining queue —
+  // each generate() call attaches after whatever is already queued, and the
+  // queue itself never rejects (a failed turn does not poison later ones).
+  let turnQueue: Promise<unknown> = Promise.resolve()
+
+  async function promptOnce(request: InProcessRequest): Promise<InProcessResponse> {
+    const text = renderPrompt(request)
+    const id = `c-${++nextId}`
+
+    let content = ""
+    updateSink = (params: any) => {
+      const update = params?.update
+      if (update?.sessionUpdate === "agent_message_chunk") {
+        content += update?.content?.text ?? ""
+      }
+      // agent_thought_chunk and tool_call/tool_call_update narration are
+      // deliberately dropped — mixing them into the reply corrupts
+      // structured output a caller expects to parse.
+    }
+
+    const replyPromise = new Promise<RpcMessage>((resolve) => pending.set(id, resolve))
+    write({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: [{ type: "text", text }] } })
+
+    let timer: NodeJS.Timeout | undefined
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`toolnexus: ACP turn timed out after ${permissionTimeoutMs}ms`)),
+        permissionTimeoutMs,
+      )
+    })
+
+    try {
+      const msg = await Promise.race([replyPromise, timeout])
+      if (msg.error) throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`)
+      return { content }
+    } finally {
+      clearTimeout(timer)
+      pending.delete(id)
+      updateSink = null
+    }
+  }
+
+  const generate = (request: InProcessRequest): Promise<InProcessResponse> => {
+    if (closed) return Promise.reject(new Error("toolnexus: ACP client is closed"))
+    const turn = turnQueue.then(() => promptOnce(request))
+    turnQueue = turn.then(
+      () => undefined,
+      () => undefined,
+    )
+    return turn
+  }
+
+  const close = (): Promise<void> => {
+    if (closed) return Promise.resolve()
+    closed = true
+    rl.close()
+    return new Promise((resolve) => {
+      if (child.exitCode !== null || child.signalCode !== null) {
+        resolve()
+        return
+      }
+      const done = () => resolve()
+      child.once("exit", done)
+      child.kill()
+      // Belt-and-braces: resolve even if the child never emits `exit` (e.g.
+      // already reaped), so close() itself never hangs.
+      setTimeout(done, 1000)
+    })
+  }
+
+  const client: ACPClient = { generate, close }
+  // Non-enumerable, undocumented — internal test hook only, so the public
+  // ACPClient surface stays exactly {generate, close}.
+  Object.defineProperty(client, "_pid", { value: child.pid, enumerable: false })
+  return client
+}

package/src/agents/agent.ts

@@ -11,7 +11,7 @@ import type { PromptInput } from "../content.js"
 import fs from "node:fs"
 import { defineTool } from "../native.js"
 import type { Answer, Request, Tool } from "../types.js"
-import { AgentRuntime, isVerbError, type AgentDef, type Budget, type Handle, type RuntimeOptions, type TaskResult } from "./runtime.js"
+import { AgentRuntime, isVerbError, S, type AgentDef, type Budget, type Handle, type RuntimeOptions, type TaskResult } from "./runtime.js"
 import { Loop, guardedHooks, type Completion, type Guardrail } from "./loop.js"
 import type { ClientOptions } from "../client.js"
 import type { Toolkit } from "../toolkit.js"
@@ -32,7 +32,18 @@ export interface AgentSpec {
   budget?: Budget
   /** Model id; default "inherit" (the runtime's `llm.model`). */
   model?: string
-  /** §10 interpreter authority for this agent's subtree. */
+  /** §10 interpreter authority for this agent's subtree.
+   *
+   * IDEMPOTENCY CONTRACT (SPEC §7D rewind-to-checkpoint). A durable resume REPLAYS the suspended
+   * turn from its PRE-TURN checkpoint: "continues from its checkpoint" means the transcript is
+   * REWOUND, not carried. EVERY tool that ran in that turn RUNS AGAIN, and the suspended tool
+   * itself is always re-executed (with `ctx.answer`) — that is §10's resolution mechanism, not a
+   * bug. Reattachment by task key makes a re-run `task` call idempotent; a leaf agent's own
+   * side-effecting tools (`git push`, a charge, a delete) have NO equivalent and are the host's
+   * responsibility. Any tool reachable in a suspendable turn must be idempotent.
+   * Replaying the leaf's stored transcript instead is DEFERRED to its own change; it would not
+   * remove this requirement anyway.
+   */
   waitFor?: (request: Request) => Promise<Answer>
   onSpawn?: AgentDef["onSpawn"]
   onClose?: AgentDef["onClose"]
@@ -118,7 +129,8 @@ export class Agent {
     const runtime = this.createRuntime(opts)
     const h = runtime.spawn(runtime.root, this.name)
     if (isVerbError(h)) {
-      return { text: h.error, isError: true, status: "error", turns: 0, totalTokens: 0, runtime }
+      // A spawn refusal is an ERROR, not a limit stop: it names no `limit` (A18).
+      return { text: h.error, isError: true, status: S.error, turns: 0, totalTokens: 0, ownTokens: 0, runtime }
     }
     const woke = runtime.wake(h, prompt)
     if (!woke.ok) {