@cleocode/adapters 2026.4.91 → 2026.4.94

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

@@ -1,21 +1,26 @@
 /**
- * Claude SDK Spawn Provider
+ * Claude SDK Spawn Provider — Vercel AI SDK edition.
  *
- * Implements `AdapterSpawnProvider` using the `@anthropic-ai/claude-agent-sdk`
- * programmatic API instead of shelling out to the `claude` CLI.
+ * Implements {@link AdapterSpawnProvider} using the Vercel AI SDK
+ * (`ai` v6 + `@ai-sdk/anthropic`) instead of the legacy
+ * `@anthropic-ai/claude-agent-sdk`. CLEO retains its own orchestration
+ * primitives (`composeSpawnPayload`, playbook runtime, agent registry);
+ * the SDK is strictly the LLM bridge.
  *
  * Differences from `ClaudeCodeSpawnProvider`:
- * - Uses SDK `query()` instead of a detached child process
+ * - Uses `generateText()` via Vercel AI SDK instead of a detached child process
  * - Awaits full completion before returning (synchronous output capture)
- * - Session IDs from the SDK enable future multi-turn resumption
+ * - Session IDs are generated by CLEO and tracked in `SessionStore`
  * - No temp files, no OS PIDs — tracking is purely in-memory session IDs
  * - `canSpawn()` uses 3-tier key resolution (env var → stored key → Claude Code OAuth)
  *
  * CANT enrichment is identical to the CLI provider: `buildCantEnrichedPrompt()`
- * is called before `query()` and the result is passed as the SDK prompt string.
+ * is called before `generateText()` and the result is passed as the user prompt.
  *
- * @task T581
+ * @task T581 (original)
+ * @task T933 (SDK consolidation — Vercel AI SDK migration)
  * @see T752 — canSpawn() OAuth fix
+ * @see ADR-052 — SDK consolidation decision
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -23,7 +28,6 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
 import { getErrorMessage } from '@cleocode/contracts';
-import { getServers } from './mcp-registry.js';
 import { SessionStore } from './session-store.js';
 import { resolveTools } from './tool-bridge.js';
 
@@ -86,19 +90,19 @@ function resolveAnthropicApiKey(): string | null {
 const DEFAULT_MODEL = 'claude-sonnet-4-5';
 
 /**
- * Spawn provider that uses the Anthropic Claude Agent SDK for programmatic
- * subagent execution.
+ * Spawn provider that uses the Vercel AI SDK (`ai` v6 + `@ai-sdk/anthropic`)
+ * for programmatic subagent execution.
  *
- * Each call to `spawn()` runs a full SDK `query()` to completion and
- * captures the output. Sessions are tracked in `SessionStore` so callers
- * can inspect active sessions via `listRunning()` and cancel them via
- * `terminate()`.
+ * Each call to `spawn()` runs a single `generateText()` call to completion and
+ * captures the output. Sessions are tracked in `SessionStore` so callers can
+ * inspect active sessions via `listRunning()` and remove them via `terminate()`.
  *
  * @remarks
- * The `permissionMode: 'bypassPermissions'` + `allowDangerouslySkipPermissions: true`
- * combination mirrors the `--dangerously-skip-permissions` flag used by
- * the CLI provider. Both are required by the SDK when bypassing all tool
- * permission prompts.
+ * Unlike the legacy `@anthropic-ai/claude-agent-sdk`, the Vercel AI SDK is
+ * strictly an LLM bridge — it does not manage a Claude Code subprocess or
+ * provide built-in MCP server wiring. Tool use is available through the SDK's
+ * tool system, but CLEO orchestration (composeSpawnPayload, playbooks, the
+ * agent registry) remains the source of truth for scaffolding.
  */
 export class ClaudeSDKSpawnProvider implements AdapterSpawnProvider {
   /** In-memory session registry. */
@@ -112,9 +116,6 @@ export class ClaudeSDKSpawnProvider implements AdapterSpawnProvider {
    * - `~/.local/share/cleo/anthropic-key` (user-stored via cleo config)
    * - Claude Code OAuth token (zero-config for Claude Code users)
    *
-   * No binary check is needed because the SDK manages the Claude Code
-   * subprocess internally.
-   *
    * @returns `true` when any Anthropic credential is available
    */
   async canSpawn(): Promise<boolean> {
@@ -122,24 +123,24 @@ export class ClaudeSDKSpawnProvider implements AdapterSpawnProvider {
   }
 
   /**
-   * Spawn a subagent using the Claude Agent SDK.
+   * Spawn a subagent using the Vercel AI SDK.
    *
-   * Enriches the prompt via CANT context, runs the SDK `query()` to
-   * completion, captures all assistant text output, and returns a
-   * `SpawnResult` with the final output and exit code.
+   * Enriches the prompt via CANT context, runs `generateText()` to completion,
+   * and returns a `SpawnResult` with the final output and exit code.
    *
    * @param context - Spawn context with taskId, prompt, options
    * @returns Resolved spawn result (status: 'completed' or 'failed')
    */
   async spawn(context: SpawnContext): Promise<SpawnResult> {
     const instanceId = `sdk-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const sessionId = `cleo-${instanceId}`;
     const startTime = new Date().toISOString();
 
     // Register in session store immediately so listRunning() reflects it
-    // before the async query starts.
+    // before the async generation starts.
     this.sessions.add({
       instanceId,
-      sessionId: undefined,
+      sessionId,
       taskId: context.taskId,
       startTime,
     });
@@ -158,92 +159,54 @@ export class ClaudeSDKSpawnProvider implements AdapterSpawnProvider {
         // CANT enrichment unavailable — use raw prompt
       }
 
-      // Lazy-import the SDK to avoid hard failures when ANTHROPIC_API_KEY
-      // is absent (canSpawn() guards the normal path, but tests may import
-      // this module without the key).
-      const { query } = await import('@anthropic-ai/claude-agent-sdk');
+      // Lazy-import the SDK to avoid hard failures when credentials are absent
+      // (canSpawn() guards the normal path, but tests may import this module
+      // without a key).
+      const { createAnthropic } = await import('@ai-sdk/anthropic');
+      const { generateText } = await import('ai');
 
-      // Build allowedTools from the spawn context or fall back to CLEO defaults.
+      const apiKey = resolveAnthropicApiKey();
+      if (!apiKey) {
+        this.sessions.remove(instanceId);
+        return {
+          instanceId,
+          taskId: context.taskId,
+          providerId: 'claude-sdk',
+          status: 'failed',
+          startTime,
+          endTime: new Date().toISOString(),
+          exitCode: 1,
+          error: 'No Anthropic credentials available (env, stored key, or Claude Code OAuth)',
+        };
+      }
+
+      // Build the Anthropic provider with the resolved key.
+      const anthropicProvider = createAnthropic({ apiKey });
+
+      // Record the tool allowlist in metadata even though the AI SDK lacks
+      // built-in tool execution for arbitrary Claude Code tools. Downstream
+      // orchestration (composeSpawnPayload) applies allowlists before prompt
+      // composition; this array is surfaced so telemetry remains complete.
       const toolAllowlist = context.options?.toolAllowlist as string[] | undefined;
       const allowedTools = resolveTools(toolAllowlist);
 
-      // Resolve available MCP servers for the working directory.
-      const workDir = context.workingDirectory ?? process.cwd();
-      const mcpServers = getServers(workDir);
-
-      // Resume support: pass a prior session ID if provided.
-      const resumeSessionId = context.options?.resumeSessionId as string | undefined;
+      const modelId = (context.options?.model as string) ?? DEFAULT_MODEL;
 
-      const sdkQuery = query({
+      const result = await generateText({
+        model: anthropicProvider(modelId),
         prompt: enrichedPrompt,
-        options: {
-          cwd: workDir,
-          model: (context.options?.model as string) ?? DEFAULT_MODEL,
-          allowedTools,
-          permissionMode: 'bypassPermissions',
-          allowDangerouslySkipPermissions: true,
-          ...(Object.keys(mcpServers).length > 0 ? { mcpServers } : {}),
-          ...(resumeSessionId ? { resume: resumeSessionId } : {}),
+        providerOptions: {
+          anthropic: {
+            // Preserve allowlist metadata for trace visibility.
+            cleoAllowedTools: allowedTools,
+          },
         },
       });
 
-      // Stream messages from the SDK, collecting text output and session ID.
-      const textParts: string[] = [];
-      let exitCode = 0;
-      let finalError: string | undefined;
-
-      for await (const message of sdkQuery) {
-        // Capture the session ID from the first message that carries it.
-        if ('session_id' in message && typeof message.session_id === 'string') {
-          this.sessions.setSessionId(instanceId, message.session_id);
-        }
-
-        if (message.type === 'assistant') {
-          // Aggregate text blocks from assistant messages.
-          for (const block of message.message.content) {
-            if (block.type === 'text') {
-              textParts.push(block.text);
-            }
-          }
-        } else if (message.type === 'result') {
-          if (message.subtype === 'success') {
-            // The result field on success contains the final summary text.
-            if (message.result) {
-              textParts.push(message.result);
-            }
-            exitCode = message.is_error ? 1 : 0;
-          } else {
-            // Error subtypes: error_max_turns, error_during_execution, etc.
-            exitCode = 1;
-            if ('errors' in message && Array.isArray(message.errors) && message.errors.length > 0) {
-              finalError = (message.errors as string[]).join('; ');
-            } else {
-              // Fallback: use the subtype string as the error description so
-              // `finalError` is always truthy for non-success result messages.
-              finalError = String(message.subtype);
-            }
-          }
-        }
-      }
-
       const endTime = new Date().toISOString();
       this.sessions.remove(instanceId);
 
-      const output = textParts.join('\n').trim();
-
-      if (finalError) {
-        return {
-          instanceId,
-          taskId: context.taskId,
-          providerId: 'claude-sdk',
-          status: 'failed',
-          output,
-          exitCode,
-          startTime,
-          endTime,
-          error: finalError,
-        };
-      }
+      const output = (result.text ?? '').trim();
 
       return {
         instanceId,
@@ -251,7 +214,7 @@ export class ClaudeSDKSpawnProvider implements AdapterSpawnProvider {
         providerId: 'claude-sdk',
         status: 'completed',
         output,
-        exitCode,
+        exitCode: 0,
         startTime,
         endTime,
       };
@@ -293,10 +256,10 @@ export class ClaudeSDKSpawnProvider implements AdapterSpawnProvider {
   /**
    * Remove a session from tracking.
    *
-   * The underlying SDK query runs inside `spawn()` and cannot be cancelled
-   * externally once the async iterator is in flight. Removing the entry from
-   * the store prevents it from appearing in `listRunning()` but does not
-   * interrupt the in-progress HTTP request.
+   * The underlying `generateText()` call runs inside `spawn()` and cannot be
+   * cancelled externally once the HTTP request is in flight. Removing the
+   * entry from the store prevents it from appearing in `listRunning()` but
+   * does not interrupt the in-progress request.
    *
    * @param instanceId - ID of the spawn instance to terminate
    */

package/src/providers/codex/install.ts

@@ -11,9 +11,17 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
-/** Lines that should appear in AGENTS.md to reference CLEO. */
-const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+/**
+ * Lines that should appear in AGENTS.md to reference CLEO.
+ * The CLEO-INJECTION.md path is resolved dynamically to support non-default
+ * XDG / OS installation locations (T916).
+ */
+const INSTRUCTION_REFERENCES = [
+  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
+  '@.cleo/memory-bridge.md',
+];
 
 /**
  * Install provider for Codex CLI.

package/src/providers/cursor/install.ts

@@ -17,9 +17,17 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
-/** Lines that should appear in instruction files to reference CLEO. */
-const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+/**
+ * Lines that should appear in instruction files to reference CLEO.
+ * The CLEO-INJECTION.md path is resolved dynamically to support non-default
+ * XDG / OS installation locations (T916).
+ */
+const INSTRUCTION_REFERENCES = [
+  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
+  '@.cleo/memory-bridge.md',
+];
 
 /**
  * Install provider for Cursor.