talon-agent 1.9.2 → 1.10.1

package/src/__tests__/integration/stub-claude/fake-claude.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * Stub claude CLI — replaces the real `claude` binary in integration tests.
+ *
+ * The Claude Agent SDK communicates with the `claude` CLI via streaming JSONL
+ * over stdin/stdout (`--input-format stream-json --output-format stream-json`).
+ * This script implements just enough of the protocol to drive the SDK through
+ * a scripted conversation so we can write integration tests for our handler,
+ * options, hooks, and stream processing without hitting the live API.
+ *
+ * The script to run is provided via `STUB_CLAUDE_SCRIPT` (path to JSON file)
+ * or `STUB_CLAUDE_SCRIPT_INLINE` (inline JSON). Schema is described in
+ * `protocol.ts`.
+ *
+ * Protocol summary (reverse-engineered from real SDK invocations):
+ *
+ *   SDK → binary (stdin):
+ *     1. {type: "control_request", request: {subtype: "initialize", ...}}
+ *     2. {type: "user", message: {role, content}, parent_tool_use_id, ...}
+ *     3. (after tool_use blocks dispatch) {type: "user", message: {role: "user",
+ *        content: [{type: "tool_result", tool_use_id, content}]}, ...}
+ *
+ *   binary → SDK (stdout):
+ *     1. {type: "control_response", response: {subtype: "success", request_id,
+ *        response: SDKControlInitializeResponse}}
+ *     2. {type: "system", subtype: "init", session_id, ...}
+ *     3. {type: "assistant", message: {content: [...]}, session_id, ...}
+ *     4. {type: "result", subtype: "success"|"error_during_execution"|...}
+ */
+
+import { readFileSync, appendFileSync, existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+
+const LOG_FILE = process.env.STUB_CLAUDE_LOG;
+const log = (msg) => {
+  if (LOG_FILE) appendFileSync(LOG_FILE, msg + "\n");
+};
+
+// ── Load script ──────────────────────────────────────────────────────────────
+
+const loadScript = () => {
+  if (process.env.STUB_CLAUDE_SCRIPT_INLINE) {
+    return JSON.parse(process.env.STUB_CLAUDE_SCRIPT_INLINE);
+  }
+  const path = process.env.STUB_CLAUDE_SCRIPT;
+  if (!path || !existsSync(path)) {
+    // No script provided — degrade gracefully. Used for SDK model-discovery
+    // boots and other "init only, never receive user messages" flows.
+    log(
+      `no script provided (path=${path ?? "unset"}), running in init-only mode`,
+    );
+    return { turns: [] };
+  }
+  return JSON.parse(readFileSync(path, "utf8"));
+};
+
+const SCRIPT = loadScript();
+const SESSION_ID =
+  SCRIPT.sessionId ?? "stub-session-" + randomUUID().slice(0, 8);
+
+// ── Output helpers ──────────────────────────────────────────────────────────
+
+const send = (obj) => {
+  const line = JSON.stringify(obj);
+  log("STDOUT: " + line);
+  process.stdout.write(line + "\n");
+};
+
+// Mock models the stub advertises through the standard
+// `SDKControlInitializeResponse.models` field. The production `registerClaudeModels`
+// path discovers these via `q.supportedModels()` exactly the same way it would
+// against a real `claude` binary. That's the whole point — tests run through
+// the unmodified bootstrap, no test-side overrides for model discovery.
+//
+// Schema per SDK's sdk.d.ts: `{ value, displayName, description }` (camelCase).
+const STUB_MODELS = [
+  {
+    value: "claude-sonnet-4-6",
+    displayName: "Sonnet 4.6 (stub)",
+    description:
+      "Stub model — integration test fixture. Always responds with whatever " +
+      "the test script in STUB_CLAUDE_SCRIPT specifies for this turn.",
+  },
+  {
+    value: "claude-opus-4-7",
+    displayName: "Opus 4.7 (stub)",
+    description:
+      "Stub model — integration test fixture (alias of sonnet stub).",
+  },
+  {
+    value: "default",
+    displayName: "Default (stub)",
+    description:
+      "Default stub model — used when tests don't specify one explicitly.",
+  },
+];
+
+const defaultInitResponse = {
+  commands: [],
+  agents: [],
+  output_style: "default",
+  available_output_styles: ["default"],
+  models: STUB_MODELS,
+  account: { email: "stub@stub.test", organization: { name: "stub-org" } },
+};
+
+const defaultSystemInit = {
+  type: "system",
+  subtype: "init",
+  session_id: SESSION_ID,
+  cwd: process.cwd(),
+  tools: [],
+  mcp_servers: [],
+  model: "claude-sonnet-4-6",
+  permissionMode: "bypassPermissions",
+  slash_commands: [],
+  apiKeySource: "none",
+};
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+let turnIndex = 0;
+/** Map from request_id we emitted -> resolver waiting on the SDK's response. */
+const pendingRequests = new Map();
+/** When set, the init handshake has captured these hook callback ids by event. */
+let hookCallbackIds = {};
+
+// ── Message handlers ────────────────────────────────────────────────────────
+
+const handleInitialize = (msg) => {
+  // Capture hook callback ids — needed if the stub fires hooks during a turn.
+  const hooks = msg.request?.hooks ?? {};
+  hookCallbackIds = {};
+  for (const [event, matchers] of Object.entries(hooks)) {
+    hookCallbackIds[event] = matchers.flatMap((m) => m.hookCallbackIds ?? []);
+  }
+  log("CAPTURED hookCallbackIds: " + JSON.stringify(hookCallbackIds));
+  const initResponse = SCRIPT.initResponse ?? defaultInitResponse;
+  send({
+    type: "control_response",
+    response: {
+      subtype: "success",
+      request_id: msg.request_id,
+      response: initResponse,
+    },
+  });
+  send(SCRIPT.systemInit ?? defaultSystemInit);
+};
+
+/** Send a control_request to the SDK and resolve with its control_response payload. */
+const sendControlRequest = (request) => {
+  const requestId = "stub_req_" + randomUUID().slice(0, 8);
+  return new Promise((resolve, reject) => {
+    pendingRequests.set(requestId, { resolve, reject });
+    send({ type: "control_request", request_id: requestId, request });
+    // Per-call timeout in case SDK never responds
+    setTimeout(() => {
+      if (pendingRequests.has(requestId)) {
+        pendingRequests.delete(requestId);
+        reject(
+          new Error("control_request timeout: " + JSON.stringify(request)),
+        );
+      }
+    }, 5000).unref();
+  });
+};
+
+const handleUser = async (_msg) => {
+  // Pop the next scripted turn and emit its messages
+  const turn = SCRIPT.turns?.[turnIndex];
+  turnIndex += 1;
+  if (!turn) {
+    // No more scripted turns — emit a benign result and exit
+    send({
+      type: "result",
+      subtype: "success",
+      is_error: false,
+      result: "stub: out of script",
+      duration_ms: 1,
+      duration_api_ms: 0,
+      num_turns: turnIndex,
+      session_id: SESSION_ID,
+      total_cost_usd: 0,
+      usage: { input_tokens: 0, output_tokens: 0 },
+    });
+    return;
+  }
+  for (const out of turn.emit ?? []) {
+    if (out.type === "_fire_hook") {
+      // Synthesize a hook_callback control_request to the SDK. The SDK calls
+      // the registered hook function and replies with the hook output. If the
+      // hook returns continue:false, we stop emitting subsequent items.
+      const callbackIds = hookCallbackIds[out.event] ?? [];
+      if (!callbackIds.length) {
+        log(`no hook registered for event ${out.event}, skipping`);
+        continue;
+      }
+      let stopped = false;
+      for (const callbackId of callbackIds) {
+        try {
+          const resp = await sendControlRequest({
+            subtype: "hook_callback",
+            callback_id: callbackId,
+            input: out.input,
+            tool_use_id: out.tool_use_id,
+          });
+          log("hook response: " + JSON.stringify(resp));
+          if (resp?.response?.continue === false) {
+            stopped = true;
+            break;
+          }
+        } catch (e) {
+          log("hook fire error: " + e.message);
+        }
+      }
+      if (stopped) {
+        log("hook returned continue:false, halting emit loop");
+        // Emit a result indicating hook-driven termination so the SDK iterator
+        // closes cleanly.
+        send({
+          type: "result",
+          subtype: "success",
+          is_error: false,
+          result: "stub: hook stopped",
+          duration_ms: 1,
+          duration_api_ms: 0,
+          num_turns: turnIndex,
+          session_id: SESSION_ID,
+          total_cost_usd: 0,
+          usage: { input_tokens: 0, output_tokens: 0 },
+        });
+        return;
+      }
+      continue;
+    }
+    const filled = fillDefaults(out);
+    send(filled);
+  }
+};
+
+const fillDefaults = (out) => {
+  if (out.type === "assistant") {
+    return {
+      type: "assistant",
+      message: {
+        id: "msg_" + randomUUID().slice(0, 8),
+        type: "message",
+        role: "assistant",
+        model: out.message?.model ?? "claude-sonnet-4-6",
+        content: out.message?.content ?? [],
+        stop_reason: out.message?.stop_reason ?? "end_turn",
+        stop_sequence: out.message?.stop_sequence ?? null,
+        usage: out.message?.usage ?? {
+          input_tokens: 1,
+          output_tokens: 1,
+        },
+      },
+      session_id: SESSION_ID,
+      parent_tool_use_id: out.parent_tool_use_id ?? null,
+    };
+  }
+  if (out.type === "result") {
+    // Talon's stream.ts reads token usage from `modelUsage[sdkModel]`. Build a
+    // matching shape from `usage` if the test didn't provide modelUsage explicitly.
+    const usage = out.usage ?? { input_tokens: 0, output_tokens: 0 };
+    const defaultModelUsage = {
+      "claude-sonnet-4-6": {
+        inputTokens: usage.input_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? 0,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        contextWindow: 200_000,
+      },
+    };
+    return {
+      type: "result",
+      subtype: out.subtype ?? "success",
+      is_error: out.is_error ?? false,
+      result: out.result ?? "",
+      duration_ms: out.duration_ms ?? 1,
+      duration_api_ms: out.duration_api_ms ?? 0,
+      num_turns: out.num_turns ?? turnIndex,
+      session_id: SESSION_ID,
+      total_cost_usd: out.total_cost_usd ?? 0,
+      usage,
+      modelUsage: out.modelUsage ?? defaultModelUsage,
+    };
+  }
+  return out;
+};
+
+// ── Stdin loop ──────────────────────────────────────────────────────────────
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) !== -1) {
+    const line = buf.slice(0, nl);
+    buf = buf.slice(nl + 1);
+    if (!line.trim()) continue;
+    log("STDIN: " + line);
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      log("STDIN parse error on: " + line);
+      continue;
+    }
+    if (
+      msg.type === "control_request" &&
+      msg.request?.subtype === "initialize"
+    ) {
+      handleInitialize(msg);
+    } else if (msg.type === "user") {
+      handleUser(msg).catch((e) => log("handleUser error: " + e.message));
+    } else if (msg.type === "control_response") {
+      // Response to a control_request the stub previously sent (e.g. a fired
+      // hook). Resolve the pending promise.
+      const requestId = msg.response?.request_id;
+      const pending = pendingRequests.get(requestId);
+      if (pending) {
+        pendingRequests.delete(requestId);
+        pending.resolve(msg);
+      }
+    } else if (msg.type === "control_request") {
+      // Ack other control requests with empty success so the SDK doesn't hang
+      send({
+        type: "control_response",
+        response: {
+          subtype: "success",
+          request_id: msg.request_id,
+          response: {},
+        },
+      });
+    }
+  }
+});
+
+process.stdin.on("end", () => {
+  log("STDIN ENDED");
+  // Give pending stdout writes time to flush, then exit
+  setTimeout(() => process.exit(0), 50);
+});
+
+// Safety: hard timeout so a misbehaving test doesn't hang CI
+const HARD_TIMEOUT_MS = Number(process.env.STUB_CLAUDE_TIMEOUT_MS ?? 10000);
+setTimeout(() => {
+  log(`HARD TIMEOUT after ${HARD_TIMEOUT_MS}ms`);
+  process.exit(2);
+}, HARD_TIMEOUT_MS).unref();

package/src/__tests__/integration/stub-claude/helpers.ts

@@ -0,0 +1,263 @@
+/**
+ * Test helpers for driving the SDK against the stub claude binary.
+ *
+ * Typical usage in a test:
+ *
+ *   const result = await runWithStub({
+ *     script: {
+ *       turns: [{
+ *         emit: [
+ *           assistantText("hello"),
+ *           assistantToolUse("mcp__telegram-tools__end_turn", { text: "hi" }),
+ *           successResult(),
+ *         ],
+ *       }],
+ *     },
+ *     sdkOptions: { ...overrides },
+ *     prompt: "user message",
+ *   });
+ *
+ *   expect(result.messages.some(m => m.type === "assistant")).toBe(true);
+ *   expect(result.hookFires.PostToolBatch).toBe(1);
+ */
+
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  Options,
+  HookCallback,
+  HookEvent,
+  HookCallbackMatcher,
+} from "@anthropic-ai/claude-agent-sdk";
+
+import type {
+  StubScript,
+  StubAssistant,
+  StubResult,
+  StubFireHook,
+  ContentBlock,
+  ToolUseBlock,
+  TextBlock,
+} from "./protocol.js";
+
+// ── Fixture helpers ─────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// On Windows, Node 20.19+ refuses to spawn `.cmd` shims via child_process
+// (CVE-2024-27980 mitigation). The SDK calls `spawn` directly without
+// `shell: true`, so we use a SEA-compiled (.exe) binary instead. Build
+// it once before the test run via `npm run build:stub-sea`.
+const STUB_BINARY = resolve(
+  __dirname,
+  process.platform === "win32" ? "fake-claude.exe" : "fake-claude.mjs",
+);
+
+export function assistantText(text: string): StubAssistant {
+  const block: TextBlock = { type: "text", text };
+  return { type: "assistant", message: { content: [block] } };
+}
+
+export function assistantToolUse(
+  name: string,
+  input: Record<string, unknown>,
+  id?: string,
+): StubAssistant {
+  const block: ToolUseBlock = {
+    type: "tool_use",
+    id: id ?? "toolu_" + randomUUID().slice(0, 8),
+    name,
+    input,
+  };
+  return {
+    type: "assistant",
+    message: { content: [block], stop_reason: "tool_use" },
+  };
+}
+
+export function assistantBlocks(...blocks: ContentBlock[]): StubAssistant {
+  return { type: "assistant", message: { content: blocks } };
+}
+
+export function successResult(text = ""): StubResult {
+  return { type: "result", subtype: "success", result: text };
+}
+
+/**
+ * Pseudo-emit that triggers a registered hook on the SDK side. The stub binary
+ * sends a `control_request: hook_callback` to the SDK and waits for the
+ * response. If the hook returns `continue: false`, the stub halts subsequent
+ * emits in the same turn and emits a synthetic success result.
+ *
+ * Use this to verify hook wiring: the SDK only fires hooks if `options.hooks`
+ * was correctly translated into the init handshake's `hookCallbackIds`.
+ */
+/**
+ * Convenience: emit an assistant message that delivers `text` through the
+ * canonical `end_turn` tool call, plus the matching PostToolBatch hook fire
+ * (which is how the real production hook terminates the SDK loop).
+ *
+ * Mirrors the pattern Talon's system prompt teaches the model: final replies
+ * go through `end_turn(text=...)`. Drop-in for tests that want to exercise
+ * the production delivery path.
+ */
+export function endTurnWithText(
+  text: string,
+  toolUseId?: string,
+): [StubAssistant, ReturnType<typeof fireHook>] {
+  const id = toolUseId ?? "toolu_" + randomUUID().slice(0, 8);
+  const assistant = assistantToolUse(
+    "mcp__telegram-tools__end_turn",
+    { text },
+    id,
+  );
+  const hook = fireHook(
+    "PostToolBatch",
+    {
+      tool_calls: [
+        {
+          tool_name: "mcp__telegram-tools__end_turn",
+          tool_input: { text },
+          tool_use_id: id,
+        },
+      ],
+    },
+    id,
+  );
+  return [assistant, hook];
+}
+
+export function fireHook(
+  event:
+    | "PreToolUse"
+    | "PostToolUse"
+    | "PostToolBatch"
+    | "Stop"
+    | "SessionStart"
+    | "SessionEnd",
+  input: Record<string, unknown>,
+  toolUseId?: string,
+): StubFireHook {
+  return {
+    type: "_fire_hook",
+    event,
+    input: { hook_event_name: event, ...input },
+    tool_use_id: toolUseId,
+  };
+}
+
+// ── Runner ──────────────────────────────────────────────────────────────────
+
+export interface RunWithStubArgs {
+  script: StubScript;
+  prompt: string;
+  /** Extra SDK options merged on top of the test defaults. */
+  sdkOptions?: Partial<Options>;
+  /** Hard timeout for the whole run (default 8s). */
+  timeoutMs?: number;
+}
+
+export interface RunWithStubResult {
+  /** Every message the SDK yielded, in order. */
+  messages: unknown[];
+  /** Per-event hook fire counts. Only set for hooks `runWithStub` injected. */
+  hookFires: Partial<Record<HookEvent, number>>;
+  /**
+   * Per-event arrays of hook inputs (in order). Lets tests assert on what the
+   * hook actually saw — e.g. which tool names were in the PostToolBatch.
+   */
+  hookInputs: Partial<Record<HookEvent, unknown[]>>;
+  /** Lines captured from the binary's protocol log. */
+  protocolLog: string[];
+  /** The temp dir used (cleaned up on success). */
+  tmpDir: string;
+}
+
+/**
+ * Runs `query()` against the stub binary with the given script. Returns
+ * everything the SDK yielded plus hook fire counts. Used by integration tests
+ * to assert end-to-end behavior of options, hooks, and stream processing.
+ */
+export async function runWithStub(
+  args: RunWithStubArgs,
+): Promise<RunWithStubResult> {
+  const { script, prompt, sdkOptions = {}, timeoutMs = 8000 } = args;
+
+  const tmpDir = mkdtempSync(resolve(tmpdir(), "stub-claude-"));
+  const scriptPath = resolve(tmpDir, "script.json");
+  const logPath = resolve(tmpDir, "protocol.log");
+  writeFileSync(scriptPath, JSON.stringify(script));
+
+  // Spy hooks: wrap any hook the test passes so we can count fires.
+  const hookFires: Partial<Record<HookEvent, number>> = {};
+  const hookInputs: Partial<Record<HookEvent, unknown[]>> = {};
+  const wrappedHooks: Partial<Record<HookEvent, HookCallbackMatcher[]>> = {};
+
+  if (sdkOptions.hooks) {
+    for (const event of Object.keys(sdkOptions.hooks) as HookEvent[]) {
+      const matchers = sdkOptions.hooks[event] ?? [];
+      wrappedHooks[event] = matchers.map((matcher) => ({
+        ...matcher,
+        hooks: matcher.hooks.map<HookCallback>((fn) => async (...rest) => {
+          hookFires[event] = (hookFires[event] ?? 0) + 1;
+          (hookInputs[event] ??= []).push(rest[0]);
+          return fn(...rest);
+        }),
+      }));
+    }
+  }
+
+  // Wire the binary path + the env var carrying the script.
+  process.env.STUB_CLAUDE_SCRIPT = scriptPath;
+  process.env.STUB_CLAUDE_LOG = logPath;
+  process.env.STUB_CLAUDE_TIMEOUT_MS = String(timeoutMs);
+
+  const options: Options = {
+    pathToClaudeCodeExecutable: STUB_BINARY,
+    permissionMode: "bypassPermissions",
+    allowDangerouslySkipPermissions: true,
+    ...sdkOptions,
+    hooks: wrappedHooks,
+  };
+
+  const messages: unknown[] = [];
+  const abort = new AbortController();
+  const hardTimer = setTimeout(() => abort.abort(), timeoutMs).unref();
+
+  try {
+    const it = query({
+      prompt,
+      options: { ...options, abortController: abort },
+    });
+    for await (const msg of it) {
+      messages.push(msg);
+    }
+  } finally {
+    clearTimeout(hardTimer);
+    delete process.env.STUB_CLAUDE_SCRIPT;
+    delete process.env.STUB_CLAUDE_LOG;
+    delete process.env.STUB_CLAUDE_TIMEOUT_MS;
+  }
+
+  let protocolLog: string[] = [];
+  try {
+    const { readFileSync } = await import("node:fs");
+    protocolLog = readFileSync(logPath, "utf8").split("\n").filter(Boolean);
+  } catch {
+    /* log file may not exist if binary failed to start */
+  }
+
+  return { messages, hookFires, hookInputs, protocolLog, tmpDir };
+}
+
+/**
+ * Convenience: clean up the tmp dir created by `runWithStub`. Tests may want
+ * to inspect it on failure, so cleanup is opt-in rather than automatic.
+ */
+export function cleanup(result: RunWithStubResult): void {
+  rmSync(result.tmpDir, { recursive: true, force: true });
+}