@dreki-gg/pi-subagent 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @dreki-gg/pi-subagent
 
+## 0.10.0
+
+### Minor Changes
+
+- db4b119: Add a Cursor ACP backend: set a subagent's model to `cursor:<model>` (e.g. `cursor:composer-2.5`) to run the task on Cursor's agent via the Agent Client Protocol instead of spawning a `pi` process. Routing happens in one shared dispatcher, so it works across single / parallel / chain modes and the `/run-agent` command with an unchanged result shape. Permission requests are auto-approved; the `tools` allowlist and `thinking` level do not apply to `cursor:` models. Requires `cursor-agent` installed and authenticated (`agent login`).
+
 ## 0.9.2
 
 ### Patch Changes

package/README.md

@@ -26,6 +26,36 @@ Notes:
 - `/run-agent` provides autocomplete for `--model` and `--thinking`
 - the `subagent` tool supports the same fields in its schema, but this package does not currently add custom interactive autocomplete for tool-call JSON parameters
 
+## Cursor Composer (ACP backend)
+
+Set a subagent's model to `cursor:<model>` to run the task on Cursor's agent via the
+[Agent Client Protocol](https://agentclientprotocol.com/) instead of spawning a `pi`
+process. A bare `cursor:` (or `cursor`) defaults to `composer-2.5`.
+
+```jsonc
+// single run on Composer 2.5
+{ "agent": "worker", "task": "…", "model": "cursor:composer-2.5" }
+```
+
+Works across every mode (single / parallel / chain) and the `/run-agent` command —
+routing happens in one shared dispatcher, so the result shape and rendering are
+identical to pi-backed subagents.
+
+**Prerequisites**
+
+- `cursor-agent` installed (default `~/.local/bin/cursor-agent`). Override the binary
+  with the `CURSOR_AGENT_BIN` env var.
+- Authenticated once: `agent login` (or set `CURSOR_API_KEY`).
+
+**Behavior notes**
+
+- Cursor runs **its own tools** in ACP headless mode and auto-executes them; the
+  subagent `tools` allowlist and `thinking` level do **not** apply to `cursor:` models.
+- Permission prompts (`session/request_permission`) are auto-approved (most permissive
+  allow option) so runs never block. Cursor typically does not prompt for normal ops.
+- The model is passed as `cursor-agent --model <model> acp`; see `cursor-agent --list-models`
+  for available ids (e.g. `cursor:gpt-5.2`).
+
 ## Opinionated Defaults
 
 This package is intentionally opinionated about orchestration:

package/extensions/subagent/agent-runner.ts

@@ -1,7 +1,8 @@
 import type { ResolvedPaths } from '@earendil-works/pi-coding-agent';
 import { discoverAgents, type AgentScope } from './agents.js';
 import type { AgentResult } from './agent-runner-types.js';
-import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { emptyUsage, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { dispatchSubagent } from './cursor/dispatch.js';
 
 export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
 
@@ -51,7 +52,7 @@ export async function runAgent(
     model: selectedModel,
   };
 
-  const spawnResult = await spawnPiAgent({
+  const spawnResult = await dispatchSubagent({
     cwd: options.cwd ?? cwd,
     agentName: agent.name,
     task,

package/extensions/subagent/cursor/acp-runner.ts

@@ -0,0 +1,143 @@
+/**
+ * Run a subagent task on Cursor's Composer family via `cursor-agent acp`,
+ * driven by the official @agentclientprotocol/sdk library (the current home of
+ * the Agent Client Protocol TypeScript SDK, formerly @zed-industries/agent-client-protocol).
+ *
+ * Returns the same SpawnPiAgentResult shape as spawnPiAgent so it is a drop-in
+ * backend behind dispatchSubagent — rendering, synthesis, and handoffs are
+ * unchanged.
+ */
+
+import { spawn } from 'node:child_process';
+import { Readable, Writable } from 'node:stream';
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  type Client,
+  type RequestPermissionRequest,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk';
+import type { SpawnPiAgentOptions, SpawnPiAgentResult } from '../spawn-utils.js';
+import { emptyUsage } from '../spawn-utils.js';
+import { parseCursorModel } from './model.js';
+import {
+  buildCancelledResponse,
+  buildPermissionResponse,
+  selectPermissionOption,
+} from './permissions.js';
+import { CursorUpdateReducer } from './update-mapping.js';
+
+const CURSOR_BIN = process.env.CURSOR_AGENT_BIN || 'cursor-agent';
+
+export async function runCursorAcpAgent(options: SpawnPiAgentOptions): Promise<SpawnPiAgentResult> {
+  const { model } = parseCursorModel(options.model);
+  const displayModel = `cursor:${model}`;
+
+  const result: SpawnPiAgentResult = {
+    exitCode: 0,
+    messages: [],
+    stderr: '',
+    wasAborted: false,
+    usage: emptyUsage(),
+    model: displayModel,
+  };
+
+  const reducer = new CursorUpdateReducer(displayModel);
+  const seenToolCalls = new Set<string>();
+
+  const proc = spawn(CURSOR_BIN, ['--model', model, 'acp'], {
+    cwd: options.cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  proc.stderr.on('data', (d: Buffer) => {
+    result.stderr += d.toString();
+  });
+
+  // Bridge Node child stdio to Web streams for ndJsonStream.
+  const stream = ndJsonStream(
+    Writable.toWeb(proc.stdin) as WritableStream<Uint8Array>,
+    Readable.toWeb(proc.stdout) as unknown as ReadableStream<Uint8Array>,
+  );
+
+  const client: Client = {
+    async requestPermission(params: RequestPermissionRequest) {
+      const optionId = selectPermissionOption(params.options);
+      return optionId ? buildPermissionResponse(optionId) : buildCancelledResponse();
+    },
+    async sessionUpdate(note: SessionNotification) {
+      const update = note.update;
+      reducer.apply(update);
+
+      if (update.sessionUpdate === 'tool_call' && !seenToolCalls.has(update.toolCallId)) {
+        seenToolCalls.add(update.toolCallId);
+        options.onToolExecutionStart?.({
+          toolCallId: update.toolCallId,
+          toolName: update.title || update.kind || 'tool',
+          args: (update.rawInput as Record<string, unknown>) ?? {},
+        });
+      }
+
+      // Live snapshot for streaming TUI updates.
+      result.messages = [reducer.current()];
+      options.onMessage?.(reducer.current());
+    },
+  };
+
+  const conn = new ClientSideConnection(() => client, stream);
+
+  let sessionId: string | undefined;
+  const onAbort = () => {
+    result.wasAborted = true;
+    if (sessionId) conn.cancel({ sessionId }).catch(() => {});
+    proc.kill('SIGTERM');
+    setTimeout(() => {
+      if (!proc.killed) proc.kill('SIGKILL');
+    }, 5000);
+  };
+  if (options.signal) {
+    if (options.signal.aborted) onAbort();
+    else options.signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  try {
+    await conn.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+    });
+
+    const session = await conn.newSession({ cwd: options.cwd, mcpServers: [] });
+    sessionId = session.sessionId;
+
+    const promptText = options.systemPrompt?.trim()
+      ? `${options.systemPrompt}\n\nTask: ${options.task}`
+      : `Task: ${options.task}`;
+
+    const promptResult = await conn.prompt({
+      sessionId,
+      prompt: [{ type: 'text', text: promptText }],
+    });
+
+    const finalized = reducer.finalize(promptResult.stopReason);
+    result.messages = finalized.messages;
+    result.usage = finalized.usage;
+    result.stopReason = finalized.stopReason;
+    result.exitCode = result.wasAborted ? 1 : 0;
+  } catch (err) {
+    result.exitCode = 1;
+    result.errorMessage = err instanceof Error ? err.message : String(err);
+    const finalized = reducer.finalize(result.wasAborted ? 'cancelled' : 'error');
+    result.messages = finalized.messages;
+    result.usage = finalized.usage;
+    result.stopReason = finalized.stopReason;
+  } finally {
+    try {
+      proc.stdin.end();
+    } catch {
+      /* ignore */
+    }
+    if (!proc.killed) proc.kill();
+  }
+
+  return result;
+}

package/extensions/subagent/cursor/dispatch.ts

@@ -0,0 +1,18 @@
+/**
+ * Single routing seam for subagent backends.
+ *
+ * Models prefixed with `cursor:` run through Cursor's ACP server (Composer
+ * family); everything else spawns a pi process as before. Both backends return
+ * the identical SpawnPiAgentResult shape, so callers are backend-agnostic.
+ */
+
+import { spawnPiAgent, type SpawnPiAgentOptions, type SpawnPiAgentResult } from '../spawn-utils.js';
+import { parseCursorModel } from './model.js';
+import { runCursorAcpAgent } from './acp-runner.js';
+
+export function dispatchSubagent(options: SpawnPiAgentOptions): Promise<SpawnPiAgentResult> {
+  if (parseCursorModel(options.model).isCursor) {
+    return runCursorAcpAgent(options);
+  }
+  return spawnPiAgent(options);
+}

package/extensions/subagent/cursor/model.ts

@@ -0,0 +1,34 @@
+/**
+ * Cursor model-prefix parsing.
+ *
+ * A subagent model of the form `cursor:<model>` routes the run through
+ * `cursor-agent acp` (Cursor's Composer family) instead of spawning a pi
+ * process. A bare `cursor:` or `cursor` defaults to `composer-2.5`.
+ */
+
+const CURSOR_PREFIX = 'cursor:';
+const DEFAULT_CURSOR_MODEL = 'composer-2.5';
+
+export interface ParsedCursorModel {
+  /** True when the model selects the Cursor ACP backend. */
+  isCursor: boolean;
+  /** The resolved model id: bare Cursor model name when isCursor, else passthrough. */
+  model: string;
+}
+
+export function parseCursorModel(model?: string): ParsedCursorModel {
+  if (!model) return { isCursor: false, model: '' };
+
+  const trimmed = model.trim();
+
+  if (trimmed === 'cursor') {
+    return { isCursor: true, model: DEFAULT_CURSOR_MODEL };
+  }
+
+  if (trimmed.toLowerCase().startsWith(CURSOR_PREFIX)) {
+    const rest = trimmed.slice(CURSOR_PREFIX.length).trim();
+    return { isCursor: true, model: rest || DEFAULT_CURSOR_MODEL };
+  }
+
+  return { isCursor: false, model: trimmed };
+}

package/extensions/subagent/cursor/permissions.ts

@@ -0,0 +1,26 @@
+/**
+ * Auto-approval policy for Cursor ACP permission requests.
+ *
+ * In ACP headless mode Cursor usually executes tool calls without prompting,
+ * but when it does send `session/request_permission` the client must answer or
+ * the turn blocks. We auto-select the most permissive "allow" option.
+ */
+
+import type { PermissionOption, RequestPermissionResponse } from '@agentclientprotocol/sdk';
+
+/**
+ * Choose which option to grant. Prefers `allow_always`, then `allow_once`,
+ * then the first option. Returns undefined when no options are offered.
+ */
+export function selectPermissionOption(options: PermissionOption[]): string | undefined {
+  const byKind = (kind: PermissionOption['kind']) => options.find((o) => o.kind === kind)?.optionId;
+  return byKind('allow_always') ?? byKind('allow_once') ?? options[0]?.optionId;
+}
+
+export function buildPermissionResponse(optionId: string): RequestPermissionResponse {
+  return { outcome: { outcome: 'selected', optionId } };
+}
+
+export function buildCancelledResponse(): RequestPermissionResponse {
+  return { outcome: { outcome: 'cancelled' } };
+}

package/extensions/subagent/cursor/update-mapping.ts

@@ -0,0 +1,141 @@
+/**
+ * Map Cursor ACP `session/update` notifications into the pi Message[] +
+ * UsageStats shape the rest of the subagent code consumes.
+ *
+ * A single ACP prompt turn is accumulated into one pi AssistantMessage whose
+ * content interleaves text parts and toolCall parts in arrival order, so the
+ * existing renderers (getFinalOutput / getDisplayItems) work unchanged.
+ */
+
+import type {
+  AssistantMessage,
+  Message,
+  StopReason,
+  TextContent,
+  ThinkingContent,
+  ToolCall,
+} from '@earendil-works/pi-ai';
+import type { SessionNotification } from '@agentclientprotocol/sdk';
+import type { UsageStats } from '../agent-runner-types.js';
+import { emptyUsage } from '../spawn-utils.js';
+
+type SessionUpdate = SessionNotification['update'];
+
+function blockText(content: { type: string; text?: string }): string {
+  return content?.type === 'text' ? (content.text ?? '') : '';
+}
+
+export function mapStopReason(raw?: string): StopReason {
+  switch (raw) {
+    case 'end_turn':
+    case 'completed':
+      return 'stop';
+    case 'max_tokens':
+    case 'max_turn_requests':
+      return 'length';
+    case 'cancelled':
+      return 'aborted';
+    case 'refusal':
+    case 'error':
+      return 'error';
+    default:
+      return 'stop';
+  }
+}
+
+/**
+ * Accumulates ACP session updates into a single pi assistant message.
+ * Stateful but free of I/O — unit-testable by feeding `apply()` a sequence.
+ */
+export class CursorUpdateReducer {
+  private readonly assistant: AssistantMessage;
+  private hasContent = false;
+  readonly usage: UsageStats = emptyUsage();
+
+  constructor(model: string) {
+    this.assistant = {
+      role: 'assistant',
+      content: [],
+      api: 'cursor-acp',
+      provider: 'cursor',
+      model,
+      usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      },
+      stopReason: 'stop',
+      timestamp: Date.now(),
+    };
+  }
+
+  /** Apply one `update` payload from a SessionNotification. */
+  apply(update: SessionUpdate): void {
+    switch (update.sessionUpdate) {
+      case 'agent_message_chunk': {
+        const text = blockText(update.content);
+        if (text) {
+          this.markTurn();
+          this.appendText(text);
+        }
+        break;
+      }
+      case 'agent_thought_chunk': {
+        const text = blockText(update.content);
+        if (text) {
+          this.markTurn();
+          const part: ThinkingContent = { type: 'thinking', thinking: text };
+          this.assistant.content.push(part);
+        }
+        break;
+      }
+      case 'tool_call': {
+        this.markTurn();
+        const part: ToolCall = {
+          type: 'toolCall',
+          id: update.toolCallId,
+          name: update.title || update.kind || 'tool',
+          arguments: (update.rawInput as Record<string, unknown>) ?? {},
+        };
+        this.assistant.content.push(part);
+        break;
+      }
+      // tool_call_update / plan / available_commands_update / current_mode_update:
+      // no projection needed for subagent output.
+      default:
+        break;
+    }
+  }
+
+  private markTurn(): void {
+    if (!this.hasContent) {
+      this.hasContent = true;
+      this.usage.turns = Math.max(this.usage.turns, 1);
+    }
+  }
+
+  private appendText(text: string): void {
+    const last = this.assistant.content.at(-1);
+    if (last && last.type === 'text') {
+      (last as TextContent).text += text;
+    } else {
+      const part: TextContent = { type: 'text', text };
+      this.assistant.content.push(part);
+    }
+  }
+
+  /** Current assistant message (live snapshot for streaming callbacks). */
+  current(): AssistantMessage {
+    return this.assistant;
+  }
+
+  /** Finalize and return the collected messages + usage. */
+  finalize(rawStopReason?: string): { messages: Message[]; usage: UsageStats; stopReason: string } {
+    this.assistant.stopReason = mapStopReason(rawStopReason);
+    const messages: Message[] = this.hasContent ? [this.assistant] : [];
+    return { messages, usage: this.usage, stopReason: rawStopReason ?? 'end_turn' };
+  }
+}

package/extensions/subagent/index.ts

@@ -44,6 +44,7 @@ import type { AgentResult } from './agent-runner-types.js';
 import { getFinalText } from './agent-result-utils.js';
 import { buildHandoffFromResult, renderHandoffForPrompt } from './handoffs.js';
 import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { dispatchSubagent } from './cursor/dispatch.js';
 import { registerListAgentsTool } from './list-agents.js';
 import { registerCreateAgentCommand } from './create-agent.js';
 
@@ -356,7 +357,7 @@ async function runSingleAgent(
   };
 
   let spawnResult: Awaited<ReturnType<typeof spawnPiAgent>> | undefined;
-  spawnResult = await spawnPiAgent({
+  spawnResult = await dispatchSubagent({
     cwd: cwd ?? defaultCwd,
     agentName: agent.name,
     task,
@@ -526,6 +527,13 @@ export default function (pi: ExtensionAPI) {
   ): Promise<Array<{ value: string; label?: string; description?: string }>> {
     const items = new Map<string, { value: string; label?: string; description?: string }>();
 
+    // Cursor ACP backend: cursor:<model> routes through `cursor-agent acp`.
+    items.set('cursor:composer-2.5', {
+      value: 'cursor:composer-2.5',
+      label: 'cursor:composer-2.5',
+      description: 'Cursor Composer 2.5 via ACP (requires cursor-agent + agent login)',
+    });
+
     try {
       const authStorage = AuthStorage.create();
       const modelRegistry = ModelRegistry.create(authStorage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"
@@ -30,6 +30,9 @@
       "./prompts"
     ]
   },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.0.0"
+  },
   "devDependencies": {
     "@types/node": "24",
     "oxfmt": "^0.43.0",

package/prompts/worker.md

@@ -1,8 +1,7 @@
 ---
 name: worker
 description: General-purpose subagent with full capabilities, isolated context
-model: openai/gpt-5.5
-thinking: low
+model: cursor:composer-2.5
 sessionStrategy: fork-at
 ---
 

package/test/cursor-acp-runner.e2e.test.ts

@@ -0,0 +1,42 @@
+/**
+ * End-to-end check against a real `cursor-agent acp` server.
+ * Gated behind CURSOR_ACP_E2E=1 (requires cursor-agent installed + `agent login`).
+ *
+ *   CURSOR_ACP_E2E=1 bun test test/cursor-acp-runner.e2e.test.ts
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCursorAcpAgent } from '../extensions/subagent/cursor/acp-runner.js';
+
+const E2E = !!process.env.CURSOR_ACP_E2E;
+const maybe = E2E ? it : it.skip;
+
+describe('runCursorAcpAgent (e2e)', () => {
+  maybe(
+    'completes a real Composer 2.5 turn',
+    async () => {
+      const cwd = await mkdtemp(join(tmpdir(), 'cursor-acp-e2e-'));
+      const result = await runCursorAcpAgent({
+        cwd,
+        agentName: 'e2e',
+        task: 'Reply with exactly the word: ok',
+        model: 'cursor:composer-2.5',
+      });
+
+      const text = result.messages
+        .filter((m) => m.role === 'assistant')
+        .flatMap((m) => (m as any).content)
+        .filter((p: any) => p.type === 'text')
+        .map((p: any) => p.text)
+        .join('');
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stopReason).toBeDefined();
+      expect(text.trim().length).toBeGreaterThan(0);
+    },
+    120_000,
+  );
+});

package/test/cursor-model.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'bun:test';
+import { parseCursorModel } from '../extensions/subagent/cursor/model.js';
+
+describe('parseCursorModel', () => {
+  it('treats undefined/empty as non-cursor', () => {
+    expect(parseCursorModel(undefined)).toEqual({ isCursor: false, model: '' });
+    expect(parseCursorModel('')).toEqual({ isCursor: false, model: '' });
+  });
+
+  it('passes through normal models', () => {
+    expect(parseCursorModel('anthropic/claude-sonnet')).toEqual({
+      isCursor: false,
+      model: 'anthropic/claude-sonnet',
+    });
+  });
+
+  it('routes cursor:<model> to the cursor backend', () => {
+    expect(parseCursorModel('cursor:composer-2.5')).toEqual({
+      isCursor: true,
+      model: 'composer-2.5',
+    });
+    expect(parseCursorModel('cursor:gpt-5.2')).toEqual({ isCursor: true, model: 'gpt-5.2' });
+  });
+
+  it('defaults bare cursor / empty suffix to composer-2.5', () => {
+    expect(parseCursorModel('cursor')).toEqual({ isCursor: true, model: 'composer-2.5' });
+    expect(parseCursorModel('cursor:')).toEqual({ isCursor: true, model: 'composer-2.5' });
+  });
+
+  it('is case-insensitive on the prefix and trims', () => {
+    expect(parseCursorModel('  Cursor:composer-2.5  ')).toEqual({
+      isCursor: true,
+      model: 'composer-2.5',
+    });
+  });
+});

package/test/cursor-permissions.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'bun:test';
+import type { PermissionOption } from '@agentclientprotocol/sdk';
+import {
+  buildCancelledResponse,
+  buildPermissionResponse,
+  selectPermissionOption,
+} from '../extensions/subagent/cursor/permissions.js';
+
+const opt = (kind: PermissionOption['kind'], optionId: string): PermissionOption => ({
+  kind,
+  optionId,
+  name: optionId,
+});
+
+describe('selectPermissionOption', () => {
+  it('prefers allow_always', () => {
+    const options = [
+      opt('reject_once', 'r'),
+      opt('allow_once', 'ao'),
+      opt('allow_always', 'aa'),
+    ];
+    expect(selectPermissionOption(options)).toBe('aa');
+  });
+
+  it('falls back to allow_once when no allow_always', () => {
+    expect(selectPermissionOption([opt('reject_once', 'r'), opt('allow_once', 'ao')])).toBe('ao');
+  });
+
+  it('falls back to the first option when no allow kinds', () => {
+    expect(selectPermissionOption([opt('reject_once', 'r'), opt('reject_always', 'ra')])).toBe('r');
+  });
+
+  it('returns undefined for empty options', () => {
+    expect(selectPermissionOption([])).toBeUndefined();
+  });
+});
+
+describe('response builders', () => {
+  it('builds a selected outcome', () => {
+    expect(buildPermissionResponse('aa')).toEqual({
+      outcome: { outcome: 'selected', optionId: 'aa' },
+    });
+  });
+
+  it('builds a cancelled outcome', () => {
+    expect(buildCancelledResponse()).toEqual({ outcome: { outcome: 'cancelled' } });
+  });
+});

package/test/cursor-update-mapping.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'bun:test';
+import type { SessionNotification } from '@agentclientprotocol/sdk';
+import { CursorUpdateReducer, mapStopReason } from '../extensions/subagent/cursor/update-mapping.js';
+
+type Update = SessionNotification['update'];
+
+const textChunk = (text: string): Update => ({
+  sessionUpdate: 'agent_message_chunk',
+  content: { type: 'text', text },
+});
+
+const toolCall = (toolCallId: string, title: string, rawInput: Record<string, unknown>): Update =>
+  ({
+    sessionUpdate: 'tool_call',
+    toolCallId,
+    title,
+    rawInput,
+  }) as Update;
+
+describe('CursorUpdateReducer', () => {
+  it('coalesces message chunks into one assistant text part', () => {
+    const r = new CursorUpdateReducer('composer-2.5');
+    r.apply(textChunk('Hello'));
+    r.apply(textChunk(' world'));
+    const { messages, usage } = r.finalize('end_turn');
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe('assistant');
+    const textPart = (messages[0] as any).content.find((p: any) => p.type === 'text');
+    expect(textPart.text).toBe('Hello world');
+    expect(usage.turns).toBe(1);
+  });
+
+  it('records tool calls as toolCall parts', () => {
+    const r = new CursorUpdateReducer('composer-2.5');
+    r.apply(textChunk('working'));
+    r.apply(toolCall('t1', 'Edit file', { path: 'a.ts' }));
+    const { messages } = r.finalize('end_turn');
+    const parts = (messages[0] as any).content;
+    const tool = parts.find((p: any) => p.type === 'toolCall');
+    expect(tool.name).toBe('Edit file');
+    expect(tool.arguments).toEqual({ path: 'a.ts' });
+  });
+
+  it('produces no messages when nothing was emitted', () => {
+    const r = new CursorUpdateReducer('composer-2.5');
+    const { messages, usage } = r.finalize();
+    expect(messages).toHaveLength(0);
+    expect(usage.turns).toBe(0);
+  });
+
+  it('maps stop reasons to pi StopReason', () => {
+    expect(mapStopReason('end_turn')).toBe('stop');
+    expect(mapStopReason('max_tokens')).toBe('length');
+    expect(mapStopReason('cancelled')).toBe('aborted');
+    expect(mapStopReason('refusal')).toBe('error');
+    expect(mapStopReason(undefined)).toBe('stop');
+  });
+});