@staix/agent-hub 0.12.44 → 0.13.0

package/src/adapters/conformance/fakes/app-server.ts

@@ -0,0 +1,119 @@
+// Fake `codex app-server` (v2 shapes from codex-cli 0.154.0 generate-json-schema). One thread, echo turns.
+export function startFakeAppServer(
+  delayMs = 30,
+  port = 0,
+  onRevert?: (params: { threadId: string; beforeTurnId: string }) => void,
+  usedPercent = 93,
+  reportApprovalPolicy = true,
+  onRequest?: (msg: any) => void,
+) {
+  let turnSeq = 0;
+  let threadTotal = 0; // the thread's running token total, as Codex keeps it
+  const usage = (n: number) => ({ totalTokens: n, inputTokens: n - 10, outputTokens: 10, cachedInputTokens: 0, reasoningOutputTokens: 0 });
+  let active = false;
+  let activeTurnId = "";
+  let steered: string[] = [];
+  const requests: any[] = [];
+  const reverted: { threadId: string; beforeTurnId: string }[] = [];
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port,
+    fetch(req, srv) {
+      if (new URL(req.url).pathname === "/healthz") return new Response("ok");
+      return srv.upgrade(req) ? undefined : new Response("no", { status: 400 });
+    },
+    websocket: {
+      async message(ws, data) {
+        const msg = JSON.parse(String(data));
+        requests.push(msg); onRequest?.(msg);
+        const reply = (result: unknown) => void ws.send(JSON.stringify({ id: msg.id, result }));
+        const note = (method: string, params: unknown) => void ws.send(JSON.stringify({ method, params }));
+        if (msg.method === "initialize") return reply({ userAgent: "fake-codex/0.154.0" });
+        if (msg.method === "thread/start") return (threadTotal = 0), reply({ thread: { id: "th1" }, model: "fake", ...(reportApprovalPolicy ? { approvalPolicy: msg.params.approvalPolicy ?? "untrusted" } : {}) });
+        if (msg.method === "thread/resume") {
+          // A thread with 5000 tokens of history; Codex 0.156 replays its saved usage to the connection that attaches.
+          threadTotal = 5000;
+          reply({ thread: { id: msg.params.threadId }, model: "fake", ...(reportApprovalPolicy ? { approvalPolicy: msg.params.approvalPolicy ?? "untrusted" } : {}) });
+          return note("thread/tokenUsage/updated", { threadId: msg.params.threadId, turnId: "old", tokenUsage: { total: usage(threadTotal), last: usage(800) } });
+        }
+        if (msg.method === "account/rateLimits/read") return reply({ rateLimits: { primary: { usedPercent, windowDurationMins: 300, resetsAt: 1_900_000_000 }, secondary: null } });
+        if (msg.method === "thread/revert") {
+          reverted.push(msg.params);
+          onRevert?.(msg.params);
+          reply({ thread: { id: msg.params.threadId, turns: [] }, itemsBackwardsCursor: null, turnsBackwardsCursor: null });
+          return note("thread/reverted", { threadId: msg.params.threadId });
+        }
+        if (msg.method === "turn/steer") {
+          if (!active || msg.params.expectedTurnId !== activeTurnId) {
+            return void ws.send(JSON.stringify({ id: msg.id, error: { code: -32000, message: "no active turn to steer" } }));
+          }
+          if (msg.params.input[0].text.includes("SILENT")) return; // app-server that never answers the steer
+          steered.push(msg.params.input[0].text.split("\n").at(-1));
+          reply({ turnId: activeTurnId });
+          // As app-server 0.159 does: the steered input becomes a user message item of the running turn.
+          return note("item/completed", { threadId: msg.params.threadId, turnId: activeTurnId, completedAtMs: Date.now(), item: { type: "userMessage", id: `u${steered.length}`, content: msg.params.input } });
+        }
+        if (msg.method !== "turn/start") return;
+        if (msg.params.input[0].text.includes("REFUSE_TURN")) return void ws.send(JSON.stringify({ id: msg.id, error: { code: -32000, message: "turn rejected" } }));
+        if (active) return void ws.send(JSON.stringify({ id: msg.id, error: { code: -32000, message: "turn in progress" } }));
+        active = true;
+        const turn = { id: `turn${++turnSeq}`, items: [], status: "inProgress" };
+        activeTurnId = turn.id;
+        steered = [];
+        const threadId = msg.params.threadId;
+        const text: string = msg.params.input[0].text.split("\n").at(-1);
+        if (text.includes("QUOTA")) {
+          // what a limited account does: refuse the turn
+          reply({ turn });
+          note("turn/started", { threadId, turn });
+          note("account/rateLimits/updated", { rateLimits: { primary: null, secondary: null, rateLimitReachedType: "usageLimitExceeded" } });
+          note("error", { error: { message: "You've hit your usage limit.", codexErrorInfo: "usageLimitExceeded" }, willRetry: false, threadId, turnId: turn.id });
+          active = false;
+          return note("turn/completed", { threadId, turn: { ...turn, status: "failed", error: { message: "usage limit" } } });
+        }
+        reply({ turn });
+        note("turn/started", { threadId, turn });
+        await Bun.sleep(delayMs);
+        const slow = /SLOW:(\d+)/.exec(text); // a turn that keeps running for this many ms
+        if (slow) await Bun.sleep(Number(slow[1]));
+        if (text.includes("EDIT:")) {
+          // `GATE:<file>` holds the edit until the test has created that file (#634): the hub captures the turn's start
+          // tree synchronously on `turn/started`, and a slow git there must finish before the edit lands, or the start
+          // tree already contains it and the turn reads as having changed nothing. A gate that never opens skips the
+          // edit altogether, so the test fails on its missing change instead of passing on a late, unsynchronized edit.
+          const gate = /GATE:(\S+)/.exec(text)?.[1];
+          if (gate) for (let attempt = 0; attempt < 1500 && !(await Bun.file(gate).exists()); attempt++) await Bun.sleep(10);
+          if (!gate || await Bun.file(gate).exists()) {
+            // A real patch (issue #108): one line appended to the file, reported with a diff that matches it.
+            const path = /EDIT:(\S+)/.exec(text)![1]!;
+            const before = await Bun.file(path).text();
+            await Bun.write(path, `${before}codex line\n`);
+            const n = before.split("\n").length - 1;
+            note("item/completed", { threadId, turnId: turn.id, completedAtMs: Date.now(), item: { type: "fileChange", id: "f2", status: "completed", changes: [{ path, kind: { type: "update", move_path: null }, diff: `@@ -${n} +${n},2 @@\n+codex line` }] } });
+          }
+          await Bun.sleep(Math.max(delayMs, 250)); // room for a steer from the item handler, on a slow CI runner too
+        }
+        if (text.includes("ITEMS")) {
+          // Tool items as Codex 0.159 reports them (issue #108): a patch, then a read the CLI parsed into an action.
+          // `ITEMS:<path>` names the file both items are about; the patch itself is up to the test.
+          const path = /ITEMS:(\S+)/.exec(text)?.[1];
+          note("item/completed", { threadId, turnId: turn.id, completedAtMs: Date.now(), item: { type: "fileChange", id: "f1", status: "completed", changes: [{ path: path ?? "/abs/src/a.ts", kind: { type: "update", move_path: null }, diff: "@@ -1 +1 @@\n-a\n+b" }] } });
+          note("item/completed", { threadId, turnId: turn.id, completedAtMs: Date.now(), item: { type: "commandExecution", id: "c1", status: "completed", command: "sed -n 1,5p src/b.ts", commandActions: [{ type: "read", command: "sed -n 1,5p src/b.ts", name: "b.ts", path: path ?? "/abs/src/b.ts" }] } });
+          await Bun.sleep(Math.max(delayMs, 250)); // room for a steer from the item handler, on a slow CI runner too
+        }
+        const item = (id: string, phase: string, t: string) =>
+          note("item/completed", { threadId, turnId: turn.id, completedAtMs: Date.now(), item: { type: "agentMessage", id, phase, text: t } });
+        item("m1", "commentary", "thinking out loud");
+        item("m2", "final_answer", `echo: ${text}${steered.map((s) => ` +steered: ${s}`).join("")}`);
+        // As Codex 0.156 reports it: the thread's running total and what this update added, 100 tokens per turn.
+        threadTotal += 100;
+        note("thread/tokenUsage/updated", { threadId, turnId: turn.id, tokenUsage: { total: usage(threadTotal), last: usage(100) } });
+        // Compaction: an estimate of the retained history in `last`, the total unchanged.
+        if (text.includes("COMPACT")) note("thread/tokenUsage/updated", { threadId, turnId: turn.id, tokenUsage: { total: usage(threadTotal), last: usage(4000) } });
+        active = false;
+        note("turn/completed", { threadId, turn: { ...turn, status: "completed" } });
+      },
+    },
+  });
+  return { url: `ws://127.0.0.1:${server.port}`, stop: () => server.stop(true), reverted, requests };
+}

package/src/adapters/conformance/fakes/codex-bin.ts

@@ -0,0 +1,15 @@
+// Stands in for the codex binary in daemon tests: `codex app-server --listen ws://127.0.0.1:<port> ...` runs the fake
+// app-server on that port. A test's wrapper script passes `--record <file>`, where each thread/revert is appended.
+import { appendFileSync } from "node:fs";
+import { startFakeAppServer } from "./app-server.ts";
+
+const arg = (name: string) => {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+};
+const record = arg("--record");
+// Daemon integration tests exercise pause behavior separately; start this fake below the default quota gate.
+startFakeAppServer(30, Number(new URL(arg("--listen") ?? "ws://127.0.0.1:0").port), (params) => {
+  if (record) appendFileSync(record, `${JSON.stringify(params)}\n`);
+}, 50);
+await new Promise(() => {}); // until the hub stops it

package/src/adapters/conformance/fakes/jcode-agent.ts

@@ -0,0 +1,91 @@
+import { createServer } from "node:net";
+import { basename, dirname, join } from "node:path";
+import { writeSync, appendFileSync, mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { createInterface } from "node:readline";
+const args = process.argv.slice(2), value = (key: string) => args[args.indexOf(key) + 1];
+const record = args.includes("--record") ? value("--record") : undefined;
+if (args.includes("version")) {
+  if (record) appendFileSync(record, JSON.stringify({ kind: "version", args, telemetry: process.env.JCODE_NO_TELEMETRY }) + "\n");
+  console.log(JSON.stringify({ semver: args.includes("--semver") ? value("--semver") : "0.98.1" }));
+} else if (args.includes("serve")) {
+  // Native jcode (0.94.0 through 0.98.1, socket.rs debug_socket_path) also binds a debug socket named by replacing
+  // ".sock" with "-debug.sock": a name without ".sock" makes both binds the same path, and serve exits on EADDRINUSE.
+  const main = value("--socket") ?? "", debugPath = join(dirname(main), basename(main).replace(".sock", "-debug.sock"));
+  const debug = createServer(socket => socket.end());
+  // #572: the native server socket speaks one JSON object per line. Only what the hub's steer uses is modelled, as observed
+  // on 0.99.0: ping (capabilities), subscribe (session), state (is_processing) and soft_interrupt (ack, then injected).
+  // `--steer-file F`: the ACP process holds its prompt until F exists and marks the turn busy with F.busy.
+  const steerFile = args.includes("--steer-file") ? value("--steer-file")! : undefined;
+  const server = createServer(socket => {
+    let buffer = "";
+    socket.on("error", () => {});
+    socket.on("data", chunk => {
+      buffer += chunk.toString();
+      const lines = buffer.split("\n"); buffer = lines.pop()!;
+      for (const line of lines) {
+        let msg: any; try { msg = JSON.parse(line); } catch { continue; }
+        const reply = (value: unknown) => socket.write(JSON.stringify(value) + "\n");
+        if (msg.type === "ping") reply({ type: "pong", id: msg.id, capabilities: args.includes("--no-soft-interrupt") ? ["session_tools"] : ["session_tools", "soft_interrupt_ids"] });
+        else if (msg.type === "subscribe") { reply({ type: "ack", id: msg.id }); reply({ type: "session", session_id: args.includes("--wrong-session") ? "other-session" : msg.target_session_id ?? "jcode-s1" }); reply({ type: "done", id: msg.id }); }
+        else if (msg.type === "state") {
+          // `--state-reply-gate F`: the reply is held until F exists, so a test can change the turn while the hub waits (no timing).
+          const respond = () => reply({ type: "state", id: msg.id, session_id: msg.session_id ?? "jcode-s1", is_processing: !!steerFile && existsSync(`${steerFile}.busy`), pending_soft_interrupts: 0 });
+          if (args.includes("--state-reply-gate")) {
+            const stateGate = value("--state-reply-gate")!;
+            writeFileSync(`${stateGate}.waiting`, "held");
+            const timer = setInterval(() => { if (existsSync(stateGate)) { clearInterval(timer); respond(); } }, 5);
+            socket.once("close", () => clearInterval(timer));
+          } else respond();
+        }
+        else if (msg.type === "soft_interrupt") {
+          if (record) appendFileSync(record, JSON.stringify({ kind: "soft_interrupt", content: msg.content, client_id: msg.client_id, urgent: msg.urgent }) + "\n");
+          if (args.includes("--no-ack")) continue;
+          // `--ack-delay-ms N`: the native server takes the message (the running turn is released at once) but answers late.
+          const acknowledge = () => { reply({ type: "ack", id: msg.id }); reply({ type: "ack", id: msg.id }); };
+          if (steerFile) writeFileSync(steerFile, "steered");
+          if (args.includes("--ack-delay-ms")) setTimeout(acknowledge, Number(value("--ack-delay-ms"))); else acknowledge();
+        }
+      }
+    });
+  });
+  debug.once("error", () => process.exit(1));
+  server.listen(main, () => debug.listen(debugPath, () => {
+    if (record) appendFileSync(record, JSON.stringify({ kind: "serve", pid: process.pid, socket: value("--socket"), home: process.env.JCODE_HOME, telemetry: process.env.JCODE_NO_TELEMETRY }) + "\n");
+    writeSync(3, "1");
+  }));
+  process.on("SIGTERM", () => {
+    if (record) appendFileSync(record, JSON.stringify({ kind: "term" }) + "\n");
+    debug.close();
+    server.close(() => setTimeout(() => process.exit(0), args.includes("--exit-delay-ms") ? Number(value("--exit-delay-ms")) : 0));
+  });
+} else if (args.includes("--resume") && !args.includes("acp")) {
+  if (record) appendFileSync(record, JSON.stringify({ kind: "tui", args, peer: process.env.AGENTHUB_PEER_ID, home: process.env.JCODE_HOME, socket: process.env.JCODE_SOCKET, telemetry: process.env.JCODE_NO_TELEMETRY }) + "\n");
+} else {
+  let session = "jcode-s1";
+  const send = (message: unknown) => process.stdout.write(JSON.stringify(message) + "\n");
+  createInterface({ input: process.stdin }).on("line", line => {
+    const msg = JSON.parse(line);
+    if (record) appendFileSync(record, JSON.stringify({ kind: "rpc", method: msg.method, params: msg.params, home: process.env.JCODE_HOME, telemetry: process.env.JCODE_NO_TELEMETRY }) + "\n");
+    if (msg.method === "initialize") send({ jsonrpc: "2.0", id: msg.id, result: { protocolVersion: 1, agentInfo: { name: "jcode", version: args.includes("--version-id") ? value("--version-id") : "0.98.1" }, agentCapabilities: { loadSession: true } } });
+    else if (msg.method === "session/new") send({ jsonrpc: "2.0", id: msg.id, result: { sessionId: session } });
+    else if (msg.method === "session/load") { session = msg.params.sessionId; send({ jsonrpc: "2.0", id: msg.id, result: args.includes("--no-load-echo") ? {} : { sessionId: session } }); }
+    else if (msg.method === "session/prompt") {
+      if (args.includes("--save-native-session")) {
+        const directory = join(process.env.JCODE_HOME!, "sessions"); mkdirSync(directory, { recursive: true });
+        writeFileSync(join(directory, `${session}.json`), JSON.stringify({ id: session, messages: [{ role: "assistant", content: "JCODE_REPLY" }] }));
+      }
+      const finish = () => {
+        send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: session, update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "JCODE_REPLY" } } } });
+        send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: args.includes("--max-tokens-stop") ? "max_tokens" : "end_turn" } });
+        if (args.includes("--exit-after-prompt")) setTimeout(() => process.exit(0), 30);
+      };
+      const steerFile = args.includes("--steer-file") ? value("--steer-file")! : undefined;
+      if (steerFile) {
+        // A turn that stays busy until the hub's steer reaches the native server (the server writes the file).
+        writeFileSync(`${steerFile}.busy`, "1");
+        const timer = setInterval(() => { if (existsSync(steerFile)) { clearInterval(timer); rmSync(`${steerFile}.busy`, { force: true }); finish(); } }, 20);
+      } else finish();
+    } else if (msg.method === "session/cancel") send({ jsonrpc: "2.0", id: msg.id, result: {} });
+    else send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "no native mode mapping" } });
+  });
+}

package/src/adapters/conformance/fakes/model-server.ts

@@ -0,0 +1,39 @@
+// Fake OpenAI-compatible gateway (OmniRoute-like): /health, bearer check, x-omniroute-provider, scripted replies.
+import type { ChatMessage } from "../../../omniroute/client.ts";
+
+export type Script = (body: { model: string; messages: ChatMessage[]; tools?: unknown[]; max_tokens?: number }, call: number) => Partial<ChatMessage> | Promise<Partial<ChatMessage>>;
+
+export const toolCall = (name: string, args: unknown, id = `call_${name}_${Math.random().toString(36).slice(2, 8)}`) => ({
+  id,
+  type: "function" as const,
+  function: { name, arguments: typeof args === "string" ? args : JSON.stringify(args) },
+});
+
+export function startFakeModelServer(opts: { key?: string; script?: Script; healthy?: boolean; models?: string[] } = {}) {
+  const requests: { headers: Record<string, string>; body: any }[] = [];
+  const state = { healthy: opts.healthy ?? true, script: opts.script ?? ((b) => ({ content: `echo: ${b.messages.at(-1)?.content}` })) };
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/v1/models") return state.healthy ? Response.json({ data: (opts.models ?? ["m", "vllm/pinned", "vllm/x", "vllm/test", "vllm/next"]).map((id) => ({ id })) }) : new Response("down", { status: 503 });
+      if (url.pathname !== "/v1/chat/completions") return new Response("not found", { status: 404 });
+      const body = (await req.json()) as any;
+      if (opts.key && req.headers.get("authorization") !== `Bearer ${opts.key}`) return new Response("invalid api key", { status: 401 });
+      if (body.messages?.[0]?.content === "agent-hub model availability check: reply OK") {
+        return Response.json({ choices: [{ message: { role: "assistant", content: "OK" } }] });
+      }
+      requests.push({ headers: Object.fromEntries(req.headers), body });
+      let scripted: Partial<ChatMessage>;
+      try {
+        scripted = await state.script(body, requests.length);
+      } catch (e) {
+        return new Response(`upstream error: ${(e as Error).message}`, { status: 500 });
+      }
+      const message = { role: "assistant", content: null, reasoning_content: "private chain of thought", ...scripted };
+      return Response.json({ choices: [{ message }] }, { headers: { "x-omniroute-provider": "vllm" } });
+    },
+  });
+  return { url: `http://127.0.0.1:${server.port}/v1`, requests, state, stop: () => server.stop(true) };
+}

package/src/adapters/conformance/fakes/pi-rpc.ts

@@ -0,0 +1,32 @@
+import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+const option = (flag: string) => process.argv.includes(flag) ? process.argv[process.argv.indexOf(flag) + 1] : undefined;
+const empty = process.argv.includes("--empty-session");
+const dir = option("--session-dir")!;
+mkdirSync(dir, { recursive: true });
+const existing = option("--session");
+const sessionId = option("--session-id") ?? (existing ? JSON.parse(readFileSync(existing, "utf8").split("\n")[0]!).id : "fake-session");
+const sessionFile = existing ?? join(dir, `${sessionId}.jsonl`);
+if (!empty && !existsSync(sessionFile)) writeFileSync(sessionFile, JSON.stringify({ type: "session", id: sessionId, cwd: process.cwd() }) + "\n");
+let messageCount = 0;
+const send = (value: unknown) => process.stdout.write(`${JSON.stringify(value)}\n`);
+createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line) as { id?: string; type?: string };
+  if (request.type === "get_state") send({ type: "response", id: request.id, command: "get_state", success: true, data: { isStreaming: false, isCompacting: false, pendingMessageCount: 0, messageCount, sessionId, sessionFile } });
+  else if (request.type === "set_model") send({ type: "response", id: request.id, command: "set_model", success: true });
+  else if (request.type === "prompt" || request.type === "steer") { messageCount++; send({ type: "response", id: request.id, command: request.type, success: true }); }
+});
+
+const exitTrigger = option("--exit-trigger");
+if (exitTrigger) {
+  const timer = setInterval(() => {
+    if (!existsSync(exitTrigger)) return;
+    clearInterval(timer);
+    if (process.argv.includes("--exit-consume-trigger")) rmSync(exitTrigger);
+    const signal = option("--exit-signal");
+    if (signal) process.kill(process.pid, signal as NodeJS.Signals);
+    else process.exit(Number(option("--exit-code") ?? 0));
+  }, 10);
+  timer.unref();
+}

package/src/adapters/conformance/index.ts

@@ -0,0 +1,11 @@
+/** Bun test registration kit. Importing this entry registers no suite and starts no native transport. */
+export { registerConformance, registerExternalChannelConformance, until, type AdapterConformance, type ConformanceFixture } from "./kit.ts";
+export { registerAcpConformance, type AcpConformanceOptions } from "./acp.ts";
+export { registerCodexConformance } from "./codex.ts";
+export { registerOwnedAcpConformance } from "./owned-acp.ts";
+export { registerLocalConformance, registerPiConformance } from "./local-pi.ts";
+export { createFromDefinition, expire } from "./factories.ts";
+export { ACP_LEGS, assertAcpLegEnrollment, assertEnrollment, definitionIdentities, type AcpLeg } from "./enrollment.ts";
+export { fakePaths } from "./fake-paths.ts";
+export { startFakeAppServer } from "./fakes/app-server.ts";
+export { startFakeModelServer, toolCall, type Script } from "./fakes/model-server.ts";

package/src/adapters/conformance/kit.ts

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import type { Envelope } from "../../hub/envelope.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+
+export async function until(condition: () => boolean, label: string): Promise<void> {
+  const deadline = Date.now() + 5000;
+  while (!condition() && Date.now() < deadline) await Bun.sleep(10);
+  expect(condition(), label).toBe(true);
+}
+export interface ConformanceFixture {
+  peer: PeerAdapter;
+  messages: string[];
+  /** Claude's native hooks own busy; channel insertion itself has no native acceptance evidence. */
+  busyOnDeliver: boolean;
+  settle?(): Promise<void>;
+  verifyTransport(): void | Promise<void>;
+  close(): Promise<void>;
+}
+export interface AdapterConformance {
+  kind: string;
+  create(): Promise<ConformanceFixture>;
+}
+
+/** Shared observable contract; every invocation uses the real adapter and its fake native transport. */
+export function registerConformance(adapter: AdapterConformance): void {
+  test(`P4 ${adapter.kind}: transport delivery, synchronous occupancy and owned teardown`, async () => {
+    const f = await adapter.create();
+    try {
+      expect(f.peer.id).toBe(adapter.kind);
+      expect(f.peer.state).toBe("idle");
+      const envelope: Envelope = newEnvelope("user", "conformance ping", { to: [adapter.kind] });
+      const delivering = f.peer.deliver([envelope]);
+      // Attach the rejection observer before teardown, even if an assertion fails while delivery is pending.
+      const outcome = delivering.then(() => undefined, error => error as Error);
+      expect(f.peer.state).toBe(f.busyOnDeliver ? "busy" : "idle");
+      expect(await outcome).toBeUndefined();
+      await f.settle?.();
+      await until(() => f.messages.length === 1 && f.peer.state === "idle", `${adapter.kind} one settled reply`);
+      expect(f.messages[0]).not.toBeEmpty();
+      await f.verifyTransport();
+      const metadata = f.peer.recoveryMetadata?.();
+      expect(JSON.stringify(metadata ?? {})).not.toContain("conformance ping");
+    } finally { await f.close(); }
+    await until(() => f.peer.state === "offline", `${adapter.kind} stop observed offline`);
+  }, 20_000);
+}
+
+/** Host-owned authenticated channel fixtures share the observable delivery contract, not a driven native factory. */
+export function registerExternalChannelConformance(adapter: AdapterConformance): void { registerConformance(adapter); }

package/src/adapters/conformance/local-pi.ts

@@ -0,0 +1,100 @@
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { LocalPeer } from "../local-worker.ts";
+import type { PiPeer } from "../pi.ts";
+import { OmniRoute } from "../../omniroute/client.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import { startFakeModelServer, toolCall } from "./fakes/model-server.ts";
+import { until } from "./kit.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+
+
+export function registerLocalConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "local-worker") throw new Error(definition.kind + ": conformance requires local-worker transport factory");
+  test(`P4 ${label}: a consumed model result from an expired generation cannot publish into the next turn`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-local-late-"));
+    let release = () => {}, observed = false, parsed = () => {};
+    const parsedLate = new Promise<void>(resolve => { parsed = resolve; });
+    const server = startFakeModelServer({ key: "conformance-key", script: async body => {
+      const text = String(body.messages.at(-1)?.content);
+      if (text.includes("OLD_GENERATION")) await new Promise<void>(resolve => { release = resolve; observed = true; });
+      return { content: text.includes("OLD_GENERATION") ? "stale answer" : "current answer" };
+    } });
+    const oldUrl = process.env.AGENTHUB_OMNIROUTE_URL, oldKey = process.env.OMNIROUTE_API_KEY;
+    process.env.AGENTHUB_OMNIROUTE_URL = server.url; process.env.OMNIROUTE_API_KEY = "conformance-key";
+    const omni = new OmniRoute({ urls: [server.url], access_hosts: [] }), chat = omni.chat.bind(omni);
+    omni.chat = async (body, options = {}) => {
+      const old = String(body.messages.at(-1)?.content).includes("OLD_GENERATION");
+      const result = await chat(body, old ? { ...options, signal: undefined } : options);
+      if (old) parsed(); return result;
+    };
+    const messages: string[] = [];
+    const peer = createFromDefinition<LocalPeer>(definition, { local: { cwd: dir, omni, fixedModel: "vllm/fixed", tools: { deny: [], permit: async () => false } } });
+    peer.onMessage = text => { messages.push(text); };
+    let oldTurn: Promise<void> | undefined;
+    try {
+      await peer.start(); oldTurn = peer.deliver([newEnvelope("user", "OLD_GENERATION")]); oldTurn.catch(() => {});
+      await until(() => observed, "old gateway call held"); expire(peer);
+      expect(peer.state).toBe("idle");
+      await peer.deliver([newEnvelope("user", "CURRENT_GENERATION")]);
+      await until(() => messages.length === 1, "new generation publishes");
+      release(); await parsedLate; await oldTurn; await new Promise<void>(resolve => setImmediate(resolve));
+      expect(messages).toEqual(["current answer"]); expect(peer.state).toBe("idle");
+    } finally { release(); await peer.stop(); await oldTurn?.catch(() => {}); server.stop();
+      if (oldUrl === undefined) delete process.env.AGENTHUB_OMNIROUTE_URL; else process.env.AGENTHUB_OMNIROUTE_URL = oldUrl;
+      if (oldKey === undefined) delete process.env.OMNIROUTE_API_KEY; else process.env.OMNIROUTE_API_KEY = oldKey;
+      rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  test(`P4 ${label}: tool approval refusal prevents the write and hub tools use the host callback`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-local-approval-")), path = join(dir, "a.txt"); writeFileSync(path, "before");
+    const asked: string[] = [], called: string[] = [];
+    const server = startFakeModelServer({ key: "conformance-key", script: body => {
+      const tools = body.messages.filter(message => message.role === "tool").length;
+      return tools === 0 ? { tool_calls: [toolCall("write", { path: "a.txt", content: "after" })] }
+        : tools === 1 ? { tool_calls: [toolCall("hub_task_list", {})] } : { content: "done" };
+    } });
+    const oldUrl = process.env.AGENTHUB_OMNIROUTE_URL, oldKey = process.env.OMNIROUTE_API_KEY;
+    process.env.AGENTHUB_OMNIROUTE_URL = server.url; process.env.OMNIROUTE_API_KEY = "conformance-key";
+    const peer = createFromDefinition<LocalPeer>(definition, { local: { cwd: dir, omni: new OmniRoute({ urls: [server.url], access_hosts: [] }), fixedModel: "vllm/fixed",
+      tools: { deny: [], permit: async title => { asked.push(title); return false; } }, taskTool: async name => { called.push(name); return "[]"; } } });
+    try {
+      await peer.start(); await peer.deliver([newEnvelope("user", "edit and list tasks")]);
+      await until(() => peer.state === "idle", "local tools settled");
+      expect(readFileSync(path, "utf8")).toBe("before"); expect(asked).toHaveLength(1); expect(called).toEqual(["hub_task_list"]);
+    } finally { await peer.stop(); server.stop(); if (oldUrl === undefined) delete process.env.AGENTHUB_OMNIROUTE_URL; else process.env.AGENTHUB_OMNIROUTE_URL = oldUrl;
+      if (oldKey === undefined) delete process.env.OMNIROUTE_API_KEY; else process.env.OMNIROUTE_API_KEY = oldKey;
+      rmSync(dir, { recursive: true, force: true }); }
+  });
+
+}
+
+export function registerPiConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "pi-rpc") throw new Error(definition.kind + ": conformance requires pi-rpc transport factory");
+  test(`P4 ${label}: recovery resumes its exact persisted session and rejects a stale bridge generation`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-pi-resume-")), stateDir = join(dir, "state"), sessions = join(stateDir, "pi-sessions");
+    mkdirSync(sessions, { recursive: true });
+    const sessionFile = join(sessions, "saved-session.jsonl"); writeFileSync(sessionFile, JSON.stringify({ type: "session", id: "saved-session", cwd: dir }) + "\n");
+    const peer = createFromDefinition<PiPeer>(definition, { pi: { cwd: dir, stateDir, sessionFile, mode: "headless", backend: "dgx", cmd: [process.execPath, fakePaths.piRpc],
+      relay: { url: "http://127.0.0.1:9/v1", token: "fixture", models: [{ id: "dgx/coding" }] }, tools: [], executeTool: async () => "fixture" } });
+    const messages: string[] = []; peer.onMessage = text => { messages.push(text); };
+    try {
+      await peer.start(); expect(peer.recoveryMetadata()).toMatchObject({ sessionId: "saved-session", sessionFile });
+      const launch = peer.tuiLaunch!;
+      const event = async (body: unknown) => fetch(`${launch.env.AGENTHUB_PI_BRIDGE_URL}/event`, { method: "POST", headers: { authorization: `Bearer ${launch.env.AGENTHUB_PI_BRIDGE_TOKEN}`, "content-type": "application/json" }, body: JSON.stringify(body) });
+      await peer.deliver([newEnvelope("user", "resumed turn")]);
+      expect((await event({ type: "agent_start", generation: 3, sessionId: "saved-session" })).status).toBe(200);
+      await event({ type: "agent_end", generation: 2, text: "stale answer" });
+      await event({ type: "agent_settled", generation: 2 });
+      expect(peer.state).toBe("busy"); expect(messages).toEqual([]);
+      await event({ type: "agent_end", generation: 3, text: "current answer" });
+      await event({ type: "agent_settled", generation: 3 });
+      expect(peer.state).toBe("idle"); expect(messages).toEqual(["current answer"]);
+    } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+  });
+
+}

package/src/adapters/conformance/owned-acp.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { JcodePeer } from "../jcode.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+import { until } from "./kit.ts";
+
+
+/** The owned-ACP protocol flavor and its unmanaged mode ceiling are supplied explicitly. */
+export function registerOwnedAcpConformance(definition: AdapterDefinition, { label = definition.displayName, unmanagedReason }: { label?: string; unmanagedReason?: string } = {}): void {
+  if (definition.start.daemonPort !== "owned-acp") throw new Error(definition.kind + ": conformance requires owned-acp transport factory");
+  if (!unmanagedReason?.trim()) throw new Error(definition.kind + ": owned-ACP unmanaged mode reason must be explicit");
+  test(`P4 ${label}: watchdog waits for the consumed late native result without publishing it into a successor`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-jcode-watchdog-")), home = join(dir, "home"), release = join(dir, "release");
+    mkdirSync(home); writeFileSync(join(home, "mcp.json"), "{}");
+    const messages: string[] = [], failed: unknown[] = [];
+    const peer = createFromDefinition<JcodePeer>(definition, { jcode: { cwd: dir, home,
+      command: [process.execPath, fakePaths.jcodeAgent, "--steer-file", release],
+    } });
+    peer.onMessage = text => { messages.push(text); }; peer.onFailed = envelopes => { failed.push(envelopes); };
+    try {
+      await peer.start();
+      expect(unmanagedReason).toContain("no verified native permission-mode mapping");
+      expect(peer.permissionModeState).toBe("unmanaged");
+      await expect(peer.setPermissionMode("ask")).rejects.toThrow("no verified mode mapping");
+      await peer.deliver([newEnvelope("user", "old Jcode turn")]);
+      await until(() => existsSync(`${release}.busy`), "native Jcode consumed the held prompt");
+      expire(peer);
+      expect(peer.state).toBe("busy"); expect(messages).toEqual([]);
+      writeFileSync(release, "release");
+      // Returning idle proves the old prompt settled, not merely that a cancel notification was written.
+      await until(() => peer.state === "idle", "Jcode late prompt result consumed after watchdog cancellation");
+      expect(messages).toEqual([]); expect(failed).toEqual([]);
+      await peer.deliver([newEnvelope("user", "successor Jcode turn")]);
+      await until(() => messages.length === 1 && peer.state === "idle", "only the successor Jcode answer publishes");
+      expect(messages).toEqual(["JCODE_REPLY"]);
+    } finally { writeFileSync(release, "release"); await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+  }, 20_000);
+
+}