@cleocode/adapters 2026.4.47 → 2026.4.49

package/src/providers/claude-sdk/__tests__/spawn.test.ts

@@ -0,0 +1,448 @@
+/**
+ * Tests for ClaudeSDKSpawnProvider
+ *
+ * The SDK `query()` function is mocked so tests run without a real
+ * ANTHROPIC_API_KEY or network connection.
+ *
+ * @task T581
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ClaudeSDKSpawnProvider } from '../spawn.js';
+
+// ---------------------------------------------------------------------------
+// Mock the SDK module
+// ---------------------------------------------------------------------------
+
+/** Minimal SDK message iterator builder for tests. */
+function makeQueryIterator(messages: Array<Record<string, unknown>>) {
+  return {
+    [Symbol.asyncIterator]: async function* () {
+      for (const msg of messages) {
+        yield msg;
+      }
+    },
+  };
+}
+
+vi.mock('@anthropic-ai/claude-agent-sdk', () => ({
+  query: vi.fn(),
+}));
+
+// Mock CANT enrichment so tests don't need the cleo CLI.
+vi.mock('../../../cant-context.js', () => ({
+  buildCantEnrichedPrompt: vi.fn(({ basePrompt }: { basePrompt: string }) =>
+    Promise.resolve(basePrompt),
+  ),
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function getQueryMock() {
+  const { query } = await import('@anthropic-ai/claude-agent-sdk');
+  return query as ReturnType<typeof vi.fn>;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ClaudeSDKSpawnProvider', () => {
+  let provider: ClaudeSDKSpawnProvider;
+
+  beforeEach(() => {
+    provider = new ClaudeSDKSpawnProvider();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // -------------------------------------------------------------------------
+  // canSpawn
+  // -------------------------------------------------------------------------
+
+  describe('canSpawn()', () => {
+    it('returns true when ANTHROPIC_API_KEY is set', async () => {
+      process.env.ANTHROPIC_API_KEY = 'test-key';
+      expect(await provider.canSpawn()).toBe(true);
+    });
+
+    it('returns false when ANTHROPIC_API_KEY is absent', async () => {
+      const saved = process.env.ANTHROPIC_API_KEY;
+      delete process.env.ANTHROPIC_API_KEY;
+      try {
+        expect(await provider.canSpawn()).toBe(false);
+      } finally {
+        if (saved !== undefined) {
+          process.env.ANTHROPIC_API_KEY = saved;
+        }
+      }
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // listRunning / terminate
+  // -------------------------------------------------------------------------
+
+  describe('listRunning()', () => {
+    it('returns empty array when no spawns are active', async () => {
+      expect(await provider.listRunning()).toEqual([]);
+    });
+  });
+
+  describe('terminate()', () => {
+    it('is a no-op for unknown instance IDs', async () => {
+      await expect(provider.terminate('nonexistent')).resolves.toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // spawn — success path
+  // -------------------------------------------------------------------------
+
+  describe('spawn() — success', () => {
+    it('returns completed status with aggregated output', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'system',
+            subtype: 'init',
+            session_id: 'sess-abc',
+            tools: [],
+            mcp_servers: [],
+            model: 'claude-sonnet-4-5',
+            permissionMode: 'bypassPermissions',
+            cwd: '/tmp',
+            slash_commands: [],
+            output_style: 'auto',
+          },
+          {
+            type: 'assistant',
+            session_id: 'sess-abc',
+            message: {
+              content: [
+                { type: 'text', text: 'Hello from' },
+                { type: 'text', text: ' the SDK.' },
+              ],
+            },
+          },
+          {
+            type: 'result',
+            subtype: 'success',
+            session_id: 'sess-abc',
+            result: 'Done.',
+            is_error: false,
+            duration_ms: 100,
+            duration_api_ms: 80,
+            num_turns: 1,
+            total_cost_usd: 0.001,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      const result = await provider.spawn({
+        taskId: 'T001',
+        prompt: 'Do something.',
+        workingDirectory: '/tmp',
+      });
+
+      expect(result.status).toBe('completed');
+      expect(result.providerId).toBe('claude-sdk');
+      expect(result.taskId).toBe('T001');
+      expect(result.output).toContain('Hello from');
+      expect(result.output).toContain('the SDK.');
+      expect(result.output).toContain('Done.');
+      expect(result.exitCode).toBe(0);
+      expect(result.startTime).toBeTruthy();
+      expect(result.endTime).toBeTruthy();
+    });
+
+    it('passes allowedTools from context options', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'result',
+            subtype: 'success',
+            session_id: 'sess-xyz',
+            result: '',
+            is_error: false,
+            duration_ms: 10,
+            duration_api_ms: 8,
+            num_turns: 1,
+            total_cost_usd: 0,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      await provider.spawn({
+        taskId: 'T002',
+        prompt: 'Read only.',
+        options: { toolAllowlist: ['Read', 'Grep'] },
+      });
+
+      expect(queryMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          options: expect.objectContaining({
+            allowedTools: ['Read', 'Grep'],
+          }),
+        }),
+      );
+    });
+
+    it('uses default tools when no toolAllowlist provided', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'result',
+            subtype: 'success',
+            session_id: 'sess-xyz',
+            result: '',
+            is_error: false,
+            duration_ms: 10,
+            duration_api_ms: 8,
+            num_turns: 1,
+            total_cost_usd: 0,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      await provider.spawn({ taskId: 'T003', prompt: 'Default tools.' });
+
+      expect(queryMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          options: expect.objectContaining({
+            allowedTools: expect.arrayContaining(['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep']),
+          }),
+        }),
+      );
+    });
+
+    it('sets permissionMode to bypassPermissions', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'result',
+            subtype: 'success',
+            session_id: 'sess-perm',
+            result: '',
+            is_error: false,
+            duration_ms: 5,
+            duration_api_ms: 4,
+            num_turns: 1,
+            total_cost_usd: 0,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      await provider.spawn({ taskId: 'T004', prompt: 'Permissions.' });
+
+      expect(queryMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          options: expect.objectContaining({
+            permissionMode: 'bypassPermissions',
+            allowDangerouslySkipPermissions: true,
+          }),
+        }),
+      );
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // spawn — error paths
+  // -------------------------------------------------------------------------
+
+  describe('spawn() — error handling', () => {
+    it('returns failed status on SDK error subtype', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'result',
+            subtype: 'error_during_execution',
+            session_id: 'sess-err',
+            is_error: true,
+            errors: ['Something went wrong'],
+            duration_ms: 50,
+            duration_api_ms: 40,
+            num_turns: 1,
+            total_cost_usd: 0,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      const result = await provider.spawn({ taskId: 'T005', prompt: 'Fail.' });
+
+      expect(result.status).toBe('failed');
+      expect(result.exitCode).toBe(1);
+      expect(result.error).toContain('Something went wrong');
+    });
+
+    it('returns failed status when query() throws', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockImplementation(() => {
+        throw new Error('Network error');
+      });
+
+      const result = await provider.spawn({ taskId: 'T006', prompt: 'Throw.' });
+
+      expect(result.status).toBe('failed');
+      expect(result.exitCode).toBe(1);
+      expect(result.error).toContain('Network error');
+    });
+
+    it('returns failed status when error_max_turns reached', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'result',
+            subtype: 'error_max_turns',
+            session_id: 'sess-max',
+            is_error: true,
+            errors: [],
+            duration_ms: 200,
+            duration_api_ms: 180,
+            num_turns: 10,
+            total_cost_usd: 0.05,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      const result = await provider.spawn({ taskId: 'T007', prompt: 'Max turns.' });
+
+      expect(result.status).toBe('failed');
+      expect(result.exitCode).toBe(1);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Session resume
+  // -------------------------------------------------------------------------
+
+  describe('spawn() — session resume', () => {
+    it('passes resume option when resumeSessionId is provided', async () => {
+      const queryMock = await getQueryMock();
+      queryMock.mockReturnValue(
+        makeQueryIterator([
+          {
+            type: 'result',
+            subtype: 'success',
+            session_id: 'sess-resume',
+            result: 'resumed',
+            is_error: false,
+            duration_ms: 20,
+            duration_api_ms: 15,
+            num_turns: 1,
+            total_cost_usd: 0,
+            usage: {},
+            modelUsage: {},
+            permission_denials: [],
+          },
+        ]),
+      );
+
+      await provider.spawn({
+        taskId: 'T008',
+        prompt: 'Continue work.',
+        options: { resumeSessionId: 'prior-session-id' },
+      });
+
+      expect(queryMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          options: expect.objectContaining({
+            resume: 'prior-session-id',
+          }),
+        }),
+      );
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SessionStore unit tests
+// ---------------------------------------------------------------------------
+
+describe('SessionStore', () => {
+  it('stores and retrieves entries', async () => {
+    const { SessionStore } = await import('../session-store.js');
+    const store = new SessionStore();
+
+    store.add({ instanceId: 'i1', sessionId: undefined, taskId: 'T1', startTime: '2026-01-01' });
+    expect(store.get('i1')).toBeDefined();
+    expect(store.size()).toBe(1);
+  });
+
+  it('updates session ID', async () => {
+    const { SessionStore } = await import('../session-store.js');
+    const store = new SessionStore();
+
+    store.add({ instanceId: 'i2', sessionId: undefined, taskId: 'T2', startTime: '2026-01-01' });
+    store.setSessionId('i2', 'sdk-session-123');
+    expect(store.get('i2')?.sessionId).toBe('sdk-session-123');
+  });
+
+  it('removes entries', async () => {
+    const { SessionStore } = await import('../session-store.js');
+    const store = new SessionStore();
+
+    store.add({ instanceId: 'i3', sessionId: undefined, taskId: 'T3', startTime: '2026-01-01' });
+    store.remove('i3');
+    expect(store.get('i3')).toBeUndefined();
+    expect(store.size()).toBe(0);
+  });
+
+  it('lists active entries', async () => {
+    const { SessionStore } = await import('../session-store.js');
+    const store = new SessionStore();
+
+    store.add({ instanceId: 'i4', sessionId: undefined, taskId: 'T4', startTime: '2026-01-01' });
+    store.add({ instanceId: 'i5', sessionId: undefined, taskId: 'T5', startTime: '2026-01-02' });
+    expect(store.listActive()).toHaveLength(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ToolBridge unit tests
+// ---------------------------------------------------------------------------
+
+describe('resolveTools()', () => {
+  it('returns default tools when called with no args', async () => {
+    const { resolveTools, DEFAULT_TOOLS } = await import('../tool-bridge.js');
+    expect(resolveTools()).toEqual([...DEFAULT_TOOLS]);
+  });
+
+  it('returns provided list unchanged', async () => {
+    const { resolveTools } = await import('../tool-bridge.js');
+    expect(resolveTools(['Read', 'Bash'])).toEqual(['Read', 'Bash']);
+  });
+
+  it('returns default tools when empty array passed', async () => {
+    const { resolveTools, DEFAULT_TOOLS } = await import('../tool-bridge.js');
+    expect(resolveTools([])).toEqual([...DEFAULT_TOOLS]);
+  });
+});

package/src/providers/claude-sdk/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @packageDocumentation
+ *
+ * Claude Agent SDK spawn provider for CLEO.
+ * Uses `@anthropic-ai/claude-agent-sdk` instead of the CLI for programmatic
+ * subagent execution with structured output and session tracking.
+ *
+ * Enabled via `provider.claude.mode = 'sdk'` in CLEO config.
+ *
+ * @task T581
+ */
+
+export type { McpServerMap, McpStdioConfig } from './mcp-registry.js';
+export { getServers } from './mcp-registry.js';
+export type { SessionEntry } from './session-store.js';
+export { SessionStore } from './session-store.js';
+export { ClaudeSDKSpawnProvider } from './spawn.js';
+export { DEFAULT_TOOLS, resolveTools } from './tool-bridge.js';

package/src/providers/claude-sdk/mcp-registry.ts

@@ -0,0 +1,96 @@
+/**
+ * MCP Registry for Claude SDK Spawn Provider
+ *
+ * Resolves available CLEO MCP servers and returns their configurations in the
+ * format expected by the SDK's `mcpServers` option. Each server is represented
+ * as an `McpStdioServerConfig` (command + optional args/env).
+ *
+ * Resolution is best-effort: if a server binary cannot be found in PATH or
+ * `node_modules/.bin/`, it is silently omitted from the returned map. This
+ * ensures agents always spawn even when some MCP servers are unavailable.
+ *
+ * @task T581
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Minimal stdio MCP server configuration understood by the SDK. */
+export interface McpStdioConfig {
+  type?: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+/** Map of server name to its stdio configuration. */
+export type McpServerMap = Record<string, McpStdioConfig>;
+
+/**
+ * Descriptor for a CLEO-provided MCP server candidate.
+ *
+ * @internal
+ */
+interface McpServerCandidate {
+  /** Key used in the SDK `mcpServers` map. */
+  name: string;
+  /** Executable name to look up in PATH and node_modules/.bin/. */
+  binary: string;
+  /** Resolved extra args to pass after the binary. */
+  args?: string[];
+}
+
+/** Known CLEO MCP servers, in resolution priority order. */
+const CLEO_MCP_CANDIDATES: readonly McpServerCandidate[] = [
+  { name: 'brain', binary: 'cleo-mcp-brain' },
+  { name: 'nexus', binary: 'cleo-mcp-nexus' },
+  { name: 'tasks', binary: 'cleo-mcp-tasks' },
+] as const;
+
+/**
+ * Locate a binary in `node_modules/.bin/` relative to the given directory.
+ *
+ * @param binary - Executable name without path
+ * @param workingDir - Project root to resolve `.bin/` from
+ * @returns Absolute path if found, otherwise undefined
+ */
+function findInNodeModules(binary: string, workingDir: string): string | undefined {
+  const binPath = join(workingDir, 'node_modules', '.bin', binary);
+  if (existsSync(binPath)) {
+    return binPath;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve available CLEO MCP servers for the given working directory.
+ *
+ * Checks each known CLEO MCP server candidate against `node_modules/.bin/`
+ * in the provided directory. Only servers whose binary can be located are
+ * included in the returned map.
+ *
+ * @param workingDirectory - Project root directory for binary resolution
+ * @returns Map of available server name to stdio config (may be empty)
+ *
+ * @example
+ * ```typescript
+ * const servers = getServers('/path/to/project');
+ * // { brain: { type: 'stdio', command: '/path/to/project/node_modules/.bin/cleo-mcp-brain' } }
+ * ```
+ */
+export function getServers(workingDirectory: string): McpServerMap {
+  const result: McpServerMap = {};
+
+  for (const candidate of CLEO_MCP_CANDIDATES) {
+    const resolvedPath = findInNodeModules(candidate.binary, workingDirectory);
+    if (resolvedPath) {
+      result[candidate.name] = {
+        type: 'stdio',
+        command: resolvedPath,
+        ...(candidate.args ? { args: candidate.args } : {}),
+      };
+    }
+  }
+
+  return result;
+}

package/src/providers/claude-sdk/session-store.ts

@@ -0,0 +1,103 @@
+/**
+ * Session Store for Claude SDK Spawn Provider
+ *
+ * Maintains an in-memory map of active SDK sessions keyed by instanceId.
+ * Each entry records the session ID returned by the SDK, the task ID, and
+ * the start time. Session IDs can be used with `options: { resume: sessionId }`
+ * in subsequent `query()` calls for multi-turn continuations.
+ *
+ * Persistence to conduit.db is intentionally deferred: the in-memory store
+ * is sufficient for single-process lifetimes and avoids coupling the spawn
+ * provider to the conduit subsystem at construction time.
+ *
+ * @task T581
+ */
+
+/** A single tracked SDK session entry. */
+export interface SessionEntry {
+  /** Unique instance ID assigned at spawn time. */
+  instanceId: string;
+  /** Claude SDK session ID returned in the first SDK message (if captured). */
+  sessionId: string | undefined;
+  /** CLEO task ID this session is executing. */
+  taskId: string;
+  /** ISO timestamp when the session was created. */
+  startTime: string;
+}
+
+/**
+ * In-memory store for active Claude SDK sessions.
+ *
+ * Provides CRUD operations over a `Map<instanceId, SessionEntry>`.
+ * Thread-safe within a single Node.js process (single-threaded event loop).
+ */
+export class SessionStore {
+  private readonly store = new Map<string, SessionEntry>();
+
+  /**
+   * Register a new session entry.
+   *
+   * @param entry - The session entry to add
+   */
+  add(entry: SessionEntry): void {
+    this.store.set(entry.instanceId, entry);
+  }
+
+  /**
+   * Update the SDK session ID for an existing entry once it is received
+   * from the first SDK message.
+   *
+   * No-op if the instanceId is not found.
+   *
+   * @param instanceId - ID of the spawn instance
+   * @param sessionId - SDK-assigned session identifier
+   */
+  setSessionId(instanceId: string, sessionId: string): void {
+    const entry = this.store.get(instanceId);
+    if (entry) {
+      entry.sessionId = sessionId;
+    }
+  }
+
+  /**
+   * Retrieve an entry by instance ID.
+   *
+   * @param instanceId - ID of the spawn instance
+   * @returns The session entry, or undefined if not found
+   */
+  get(instanceId: string): SessionEntry | undefined {
+    return this.store.get(instanceId);
+  }
+
+  /**
+   * Remove an entry by instance ID.
+   *
+   * @param instanceId - ID of the spawn instance to remove
+   */
+  remove(instanceId: string): void {
+    this.store.delete(instanceId);
+  }
+
+  /**
+   * List all active session entries.
+   *
+   * @returns Array of all tracked session entries
+   */
+  listActive(): SessionEntry[] {
+    return Array.from(this.store.values());
+  }
+
+  /**
+   * Return the number of tracked sessions.
+   */
+  size(): number {
+    return this.store.size;
+  }
+
+  /**
+   * Clear all tracked sessions. Intended for testing only.
+   */
+  clear(): void {
+    this.store.clear();
+  }
+}