talon-agent 1.9.2 → 1.10.1

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

@@ -0,0 +1,108 @@
+/**
+ * Types describing the JSON script that drives `fake-claude.mjs`.
+ *
+ * A script is a list of "turns." Each turn is consumed in order — the Nth user
+ * message the SDK sends to the binary triggers the Nth turn's `emit` array.
+ * Within a turn, each emitted message is written to stdout as a single JSONL
+ * line. The stub binary fills in safe defaults (session_id, message id, usage,
+ * stop_reason) so test scripts only need to specify what's relevant.
+ *
+ * For the SDK's content-block shapes, see the upstream type definitions:
+ *   node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts
+ */
+
+export interface StubScript {
+  /** Override the auto-generated session id. */
+  sessionId?: string;
+  /** Override the default `SDKControlInitializeResponse` payload. */
+  initResponse?: Record<string, unknown>;
+  /** Override the default `system/init` event. */
+  systemInit?: Record<string, unknown>;
+  /** Sequential turns. Turn N is consumed on the Nth user message received. */
+  turns?: StubTurn[];
+}
+
+export interface StubTurn {
+  /** Messages to write to stdout when this turn fires, in order. */
+  emit?: StubEmit[];
+}
+
+export type StubEmit = StubAssistant | StubResult | StubFireHook | StubRaw;
+
+/**
+ * Pseudo-emit handled by `fake-claude.mjs` — synthesizes a `hook_callback`
+ * control_request to the SDK, mimicking what the real CLI does when it
+ * dispatches a tool batch and reaches a hook event. If the hook returns
+ * `continue: false`, the stub halts subsequent emits in this turn.
+ */
+export interface StubFireHook {
+  type: "_fire_hook";
+  event:
+    | "PreToolUse"
+    | "PostToolUse"
+    | "PostToolBatch"
+    | "Stop"
+    | "SessionStart"
+    | "SessionEnd";
+  input: Record<string, unknown>;
+  tool_use_id?: string;
+}
+
+export interface StubAssistant {
+  type: "assistant";
+  message?: {
+    model?: string;
+    content?: ContentBlock[];
+    stop_reason?: string;
+    stop_sequence?: string | null;
+    usage?: { input_tokens: number; output_tokens: number };
+  };
+  parent_tool_use_id?: string | null;
+}
+
+export interface StubResult {
+  type: "result";
+  subtype?:
+    | "success"
+    | "error_during_execution"
+    | "error_max_turns"
+    | "error_during_streaming";
+  is_error?: boolean;
+  result?: string;
+  duration_ms?: number;
+  duration_api_ms?: number;
+  num_turns?: number;
+  total_cost_usd?: number;
+  usage?: { input_tokens: number; output_tokens: number };
+}
+
+/**
+ * Escape hatch for raw protocol messages (e.g. `system`, `stream_event`,
+ * arbitrary control responses) that don't fit the high-level helpers.
+ */
+export interface StubRaw {
+  type: string;
+  [key: string]: unknown;
+}
+
+// ── Content blocks (subset, mirrors @anthropic-ai/sdk Anthropic.Messages) ───
+
+export type ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock;
+
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+export interface ToolUseBlock {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface ThinkingBlock {
+  type: "thinking";
+  thinking: string;
+  signature?: string;
+}

package/src/__tests__/integration/stub-claude/sea-config.json

@@ -0,0 +1,7 @@
+{
+  "main": "fake-claude.cjs",
+  "output": "sea-prep.blob",
+  "disableExperimentalSEAWarning": true,
+  "useCodeCache": false,
+  "useSnapshot": false
+}

package/src/__tests__/integration/talon-bootstrap.ts

@@ -0,0 +1,206 @@
+/**
+ * Functional-test bootstrap for Talon's claude-sdk backend against the stub
+ * binary.
+ *
+ * Calls the **production** `initAgent()` entry point with `claudeBinary`
+ * pointed at the stub. No workarounds — the stub advertises its mock models
+ * via the standard `SDKControlInitializeResponse.models` field, so
+ * `registerClaudeModels()` discovers them by spawning the stub and walking
+ * the real init handshake. The result is the entire production code path
+ * exercised end-to-end: model discovery, prompt enrichment, system-prompt
+ * rebuild, options builder, SDK query, stream processing, dedup, session
+ * bookkeeping — only the binary the SDK spawns is fake.
+ *
+ * Usage in tests:
+ *
+ *   import { runTalonTurn } from "./talon-bootstrap.js";
+ *   import { assistantText, successResult } from "./stub-claude/helpers.js";
+ *
+ *   const result = await runTalonTurn({
+ *     prompt: "hello",
+ *     script: { turns: [{ emit: [assistantText("hi"), successResult()] }] },
+ *   });
+ *
+ *   expect(result.text).toBe("hi");
+ *   expect(result.toolUses).toHaveLength(0);
+ */
+
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import type { TalonConfig } from "../../util/config.js";
+import { initAgent } from "../../backend/claude-sdk/state.js";
+import { handleMessage } from "../../backend/claude-sdk/handler.js";
+import { resetSession } from "../../storage/sessions.js";
+
+import type { StubScript } from "./stub-claude/protocol.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// See stub-claude/helpers.ts for the Windows-vs-POSIX rationale.
+const STUB_BINARY = resolve(
+  __dirname,
+  process.platform === "win32"
+    ? "stub-claude/fake-claude.exe"
+    : "stub-claude/fake-claude.mjs",
+);
+
+let booted = false;
+const bootedTmpDirs: string[] = [];
+
+/**
+ * Idempotent boot — first call initializes the agent, subsequent calls reuse
+ * the same in-process state. Safe to call from every test's beforeAll.
+ */
+export async function ensureBooted(): Promise<void> {
+  if (booted) return;
+
+  const workspace = mkdtempSync(resolve(tmpdir(), "talon-stub-workspace-"));
+  bootedTmpDirs.push(workspace);
+
+  const config: TalonConfig = {
+    frontend: "terminal",
+    backend: "claude",
+    claudeBinary: STUB_BINARY,
+    model: "claude-sonnet-4-6",
+    maxMessageLength: 4000,
+    concurrency: 1,
+    pulse: false,
+    pulseIntervalMs: 300_000,
+    heartbeat: false,
+    heartbeatIntervalMinutes: 60,
+    plugins: [],
+    botDisplayName: "Talon (stub)",
+    teamsWebhookPort: 19878,
+    teamsGraphPollMs: 10_000,
+    systemPrompt: "Test system prompt.",
+    workspace,
+  };
+
+  // Run the production bootstrap — `initAgent` calls `registerClaudeModels`
+  // which spawns the stub binary, performs the init handshake, and pulls the
+  // model list out of the SDKControlInitializeResponse. The stub advertises
+  // its mock models in `defaultInitResponse.models` (`fake-claude.mjs`), so
+  // discovery resolves naturally without any test-side override.
+  await initAgent(config);
+  booted = true;
+}
+
+/** Tear-down hook for tests that want a clean slate. */
+export function teardownBootstrap(): void {
+  for (const dir of bootedTmpDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  booted = false;
+}
+
+// ── Per-turn runner ────────────────────────────────────────────────────────
+
+export interface RunTalonTurnArgs {
+  prompt: string;
+  script: StubScript;
+  chatId?: string;
+  senderName?: string;
+  isGroup?: boolean;
+  /** Reset the session bookkeeping for this chat before running. */
+  resetSession?: boolean;
+}
+
+export interface RunTalonTurnResult {
+  /** Full assistant text accumulated across `onTextBlock` calls. */
+  text: string;
+  /** Tool calls observed via `onToolUse`. */
+  toolUses: { name: string; input: Record<string, unknown> }[];
+  /** Streaming deltas, in order. */
+  streamDeltas: { phase?: string; text: string }[];
+  /** Token + duration stats from `handleMessage`. */
+  inputTokens: number;
+  outputTokens: number;
+  durationMs: number;
+  /** Lines from the stub's protocol log. */
+  protocolLog: string[];
+  /** Tmp dir used (cleaned up automatically). */
+  tmpDir: string;
+}
+
+/**
+ * Drives a full Talon turn against the stub binary. Real `handleMessage`
+ * runs end-to-end — prompt building, SDK query, stream processing, session
+ * persistence — but the SDK talks to the stub instead of the API.
+ */
+export async function runTalonTurn(
+  args: RunTalonTurnArgs,
+): Promise<RunTalonTurnResult> {
+  await ensureBooted();
+
+  const {
+    prompt,
+    script,
+    chatId = "stub-chat-" + Math.random().toString(36).slice(2, 10),
+    senderName = "TestUser",
+    isGroup = false,
+    resetSession: shouldResetSession = false,
+  } = args;
+
+  if (shouldResetSession) resetSession(chatId);
+
+  const tmpDir = mkdtempSync(resolve(tmpdir(), "talon-turn-"));
+  const scriptPath = resolve(tmpDir, "script.json");
+  const logPath = resolve(tmpDir, "protocol.log");
+  writeFileSync(scriptPath, JSON.stringify(script));
+
+  process.env.STUB_CLAUDE_SCRIPT = scriptPath;
+  process.env.STUB_CLAUDE_LOG = logPath;
+  process.env.STUB_CLAUDE_TIMEOUT_MS = "10000";
+
+  const textChunks: string[] = [];
+  const toolUses: { name: string; input: Record<string, unknown> }[] = [];
+  const streamDeltas: { phase?: string; text: string }[] = [];
+
+  try {
+    const result = await handleMessage({
+      chatId,
+      text: prompt,
+      senderName,
+      isGroup,
+      onTextBlock: async (text) => {
+        textChunks.push(text);
+      },
+      onToolUse: (name, input) => {
+        toolUses.push({ name, input });
+      },
+      onStreamDelta: (accumulated, phase) => {
+        streamDeltas.push({ phase, text: accumulated });
+      },
+    });
+
+    let protocolLog: string[] = [];
+    try {
+      const { readFileSync } = await import("node:fs");
+      protocolLog = readFileSync(logPath, "utf8").split("\n").filter(Boolean);
+    } catch {
+      /* no log if stub never started */
+    }
+
+    return {
+      text: textChunks.join(""),
+      toolUses,
+      streamDeltas,
+      inputTokens: result.inputTokens,
+      outputTokens: result.outputTokens,
+      durationMs: result.durationMs,
+      protocolLog,
+      tmpDir,
+    };
+  } finally {
+    delete process.env.STUB_CLAUDE_SCRIPT;
+    delete process.env.STUB_CLAUDE_LOG;
+    delete process.env.STUB_CLAUDE_TIMEOUT_MS;
+  }
+}
+
+/** Cleanup helper for tests that want to remove their tmp dirs. */
+export function cleanupTurn(result: RunTalonTurnResult): void {
+  rmSync(result.tmpDir, { recursive: true, force: true });
+}

package/src/__tests__/integration/talon-functional.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Functional tests: drives Talon's `handleMessage` end-to-end against the stub
+ * binary. Tests cover real conversational structures — single-turn replies,
+ * tool-call dispatch, multi-turn dialogue, error paths.
+ *
+ * Unlike `sdk-stub.test.ts` which pokes `query()` directly with a custom hook,
+ * these tests run the full Talon code path: prompt building, system-prompt
+ * rebuild, options builder (including the production PostToolBatch hook),
+ * stream processing, session bookkeeping. The stub binary plays the role of
+ * the live API.
+ */
+
+import { describe, it, expect, afterAll } from "vitest";
+import {
+  runTalonTurn,
+  cleanupTurn,
+  teardownBootstrap,
+} from "./talon-bootstrap.js";
+import {
+  assistantText,
+  endTurnWithText,
+  successResult,
+} from "./stub-claude/helpers.js";
+
+/** Pull delivered text from end_turn tool calls — same path the bridge uses. */
+function deliveredText(
+  toolUses: { name: string; input: Record<string, unknown> }[],
+): string {
+  return toolUses
+    .filter((t) => t.name.endsWith("end_turn") || t.name === "end_turn")
+    .map((t) => (typeof t.input.text === "string" ? t.input.text : ""))
+    .join("");
+}
+
+// Skip if the stub binary isn't on disk (e.g. someone forgot to run
+// `npm run build:stub-sea` on Windows). On POSIX the .mjs source is always
+// shipped so this is effectively always true.
+import { existsSync } from "node:fs";
+import { resolve as resolvePath, dirname as dirnamePath } from "node:path";
+import { fileURLToPath as fileUrl } from "node:url";
+const __testDir = dirnamePath(fileUrl(import.meta.url));
+const stubReady = existsSync(
+  resolvePath(
+    __testDir,
+    process.platform === "win32"
+      ? "stub-claude/fake-claude.exe"
+      : "stub-claude/fake-claude.mjs",
+  ),
+);
+
+describe.skipIf(!stubReady)("Talon functional — bootstrap", () => {
+  it("discovers the stub's advertised models through the production initAgent path", async () => {
+    // No `registerClaudeModelsStatic` workaround — the stub advertises models
+    // in its init handshake response, the production model-discovery path
+    // pulls them out of `q.supportedModels()`, tests run through unmodified
+    // bootstrap.
+    await import("./talon-bootstrap.js").then((m) => m.ensureBooted());
+    const { getModels } = await import("../../core/models.js");
+    const ids = getModels().map((m) => m.id);
+    expect(ids).toContain("claude-sonnet-4-6");
+    expect(ids).toContain("default");
+    // The stub also advertises an opus model; if discovery is real, we see it.
+    expect(ids).toContain("claude-opus-4-7");
+  }, 20000);
+});
+
+describe.skipIf(!stubReady)("Talon functional — single-turn", () => {
+  afterAll(() => {
+    teardownBootstrap();
+  });
+
+  it("delivers a final reply via end_turn and triggers PostToolBatch", async () => {
+    const [assistant, hook] = endTurnWithText("hello back");
+    const result = await runTalonTurn({
+      prompt: "say hello",
+      script: {
+        turns: [
+          {
+            emit: [assistant, hook, successResult("hello back")],
+          },
+        ],
+      },
+      resetSession: true,
+    });
+
+    // The stub delivered via end_turn. The handler should have captured the
+    // tool call (which is how the bridge would deliver to the user).
+    expect(deliveredText(result.toolUses)).toBe("hello back");
+    // No plain text blocks should leak — production contract is "no scratchpad".
+    expect(result.text).toBe("");
+    expect(result.protocolLog.length).toBeGreaterThan(0);
+    cleanupTurn(result);
+  }, 20000);
+
+  it("treats raw assistant text without end_turn as scratchpad (dropped)", async () => {
+    // This documents the production contract: text not routed through end_turn
+    // is private scratchpad. The flow-violation retry path would fire too in
+    // production; we don't assert on the retry here, only on first-turn drop.
+    const result = await runTalonTurn({
+      prompt: "send raw text",
+      script: {
+        turns: [
+          {
+            emit: [assistantText("this should be dropped"), successResult()],
+          },
+          // Second turn handles the scratchpad-violation re-prompt that fires:
+          // we just emit a clean end_turn() to close.
+          {
+            emit: [...endTurnWithText(""), successResult()],
+          },
+        ],
+      },
+      resetSession: true,
+    });
+
+    // The raw text never reaches onTextBlock — it's private scratchpad.
+    expect(result.text).toBe("");
+    cleanupTurn(result);
+  }, 25000);
+
+  it("emits progress text before tool calls via onTextBlock", async () => {
+    // Real production pattern: model writes a brief "thinking out loud" text
+    // chunk before calling a tool. That text flows through `progressTexts`
+    // → `onTextBlock`, separate from the trailing/scratchpad path.
+    const [endTurn, hook] = endTurnWithText("done");
+    const result = await runTalonTurn({
+      prompt: "step then deliver",
+      script: {
+        turns: [
+          {
+            emit: [
+              {
+                type: "assistant",
+                message: {
+                  stop_reason: "tool_use",
+                  content: [
+                    { type: "text", text: "Working on it... " },
+                    {
+                      type: "tool_use",
+                      id: "tu_progress",
+                      name: "mcp__telegram-tools__end_turn",
+                      input: { text: "done" },
+                    },
+                  ],
+                },
+              },
+              hook,
+              successResult("done"),
+            ],
+          },
+        ],
+      },
+      resetSession: true,
+    });
+
+    expect(result.text).toContain("Working on it");
+    expect(deliveredText(result.toolUses)).toBe("done");
+    // We crafted the assistant message manually instead of using the helper.
+    void endTurn;
+    cleanupTurn(result);
+  }, 20000);
+
+  it("records token usage from the stub's result message", async () => {
+    const [assistant, hook] = endTurnWithText("ok");
+    const result = await runTalonTurn({
+      prompt: "test usage",
+      script: {
+        turns: [
+          {
+            emit: [
+              assistant,
+              hook,
+              {
+                type: "result",
+                subtype: "success",
+                result: "ok",
+                usage: { input_tokens: 42, output_tokens: 17 },
+              },
+            ],
+          },
+        ],
+      },
+      resetSession: true,
+    });
+
+    expect(result.inputTokens).toBe(42);
+    expect(result.outputTokens).toBe(17);
+    cleanupTurn(result);
+  }, 20000);
+});

package/src/__tests__/package.functional.test.ts

@@ -0,0 +1,178 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const REPO_ROOT = resolve(import.meta.dirname, "../..");
+// 4 minutes — Windows runners regularly take 3+ minutes for `npm install` on
+// the published tarball (cold cache + Windows fs latency); 3min was right at
+// the edge. Bumped from 180k after a post-merge timeout on `main`
+// (run 25603848100, 2026-05-09).
+const FUNCTIONAL_TIMEOUT_MS = 240_000;
+const NPM_CLI = process.env.npm_execpath;
+
+type RunResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+};
+
+const workDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of workDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}, 60_000);
+
+function makeWorkDir(name: string): string {
+  const dir = mkdtempSync(join(tmpdir(), `talon-${name}-`));
+  workDirs.push(dir);
+  return dir;
+}
+
+function childEnv(home: string): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,
+    TALON_QUIET: "1",
+    NO_COLOR: "1",
+  };
+}
+
+function run(
+  command: string,
+  args: string[],
+  options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    shell?: boolean;
+  } = {},
+): RunResult {
+  const child = spawnSync(command, args, {
+    cwd: options.cwd ?? REPO_ROOT,
+    env: options.env ?? process.env,
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? 30_000,
+    windowsHide: true,
+    shell: options.shell ?? false,
+  });
+
+  return {
+    code: child.status,
+    stdout: child.stdout ?? "",
+    stderr: child.error
+      ? `${child.stderr ?? ""}\n${child.error.message}`
+      : (child.stderr ?? ""),
+  };
+}
+
+function runNpm(
+  args: string[],
+  options: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): RunResult {
+  if (NPM_CLI) return run(process.execPath, [NPM_CLI, ...args], options);
+  return run(process.platform === "win32" ? "npm.cmd" : "npm", args, {
+    ...options,
+    shell: process.platform === "win32",
+  });
+}
+
+function expectOk(result: RunResult): void {
+  expectExitOk(result);
+  expect(
+    result.stderr,
+    `process exited with ${result.code}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+  ).toBe("");
+}
+
+function expectExitOk(result: RunResult): void {
+  expect(
+    result.stderr,
+    `process exited with ${result.code}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+  ).not.toContain("spawnSync");
+  expect(result.code).toBe(0);
+}
+
+function packInto(dir: string): string {
+  const result = runNpm(["pack", "--json", "--pack-destination", dir], {
+    timeoutMs: 30_000,
+  });
+  expectOk(result);
+
+  const entries = JSON.parse(result.stdout) as Array<{
+    filename: string;
+    files: Array<{ path: string }>;
+  }>;
+  const pack = entries[0];
+  expect(pack).toBeDefined();
+
+  const packedFiles = new Set(pack.files.map((file) => file.path));
+  for (const required of [
+    "bin/talon.js",
+    "src/cli.ts",
+    "src/util/mcp-launcher.mjs",
+    "prompts/base.md",
+    "tsconfig.json",
+  ]) {
+    expect(packedFiles.has(required), `${required} should be packed`).toBe(
+      true,
+    );
+  }
+
+  return join(dir, pack.filename);
+}
+
+describe("package functional smoke tests", () => {
+  it(
+    "published tarball includes runtime assets and exposes a working CLI",
+    () => {
+      const packDir = makeWorkDir("pack");
+      const installDir = makeWorkDir("install");
+      const homeDir = makeWorkDir("home");
+      const tarball = packInto(packDir);
+
+      writeFileSync(join(installDir, "package.json"), "{}\n");
+      expectExitOk(
+        runNpm(
+          ["install", "--ignore-scripts", "--no-audit", "--no-fund", tarball],
+          {
+            cwd: installDir,
+            timeoutMs: FUNCTIONAL_TIMEOUT_MS,
+          },
+        ),
+      );
+
+      const cli = join(
+        installDir,
+        "node_modules",
+        "talon-agent",
+        "bin",
+        "talon.js",
+      );
+      const help = run(process.execPath, [cli, "--help"], {
+        cwd: installDir,
+        env: childEnv(homeDir),
+      });
+
+      expectOk(help);
+      expect(help.stdout).toContain("Usage: talon [command]");
+      expect(help.stdout).toContain("doctor");
+    },
+    FUNCTIONAL_TIMEOUT_MS,
+  );
+
+  it("source CLI status command is non-interactive and isolated from the real home directory", () => {
+    const homeDir = makeWorkDir("source-home");
+    const result = run(process.execPath, ["bin/talon.js", "status"], {
+      env: childEnv(homeDir),
+    });
+
+    expectOk(result);
+    expect(result.stdout).toContain("Stopped");
+    expect(result.stdout).toContain("Run talon setup");
+  });
+});