@tanstack/ai-claude-code 0.3.1 → 0.4.0

package/src/adapters/text.ts

@@ -1,5 +1,8 @@
 import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
-import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
+import {
+  appendOutputSchemaInstruction,
+  toRunErrorRawEvent,
+} from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
   SandboxCapability,
@@ -26,6 +29,11 @@ import { buildPrompt } from '../messages/prompt'
 import { translateSdkStream } from '../stream/translate'
 import { mapPolicyToClaudeFlags } from './policy-map'
 import { projectClaudeWorkspace } from './projection'
+import {
+  CLAUDE_JSON_SCHEMA_PLACEHOLDER,
+  CLAUDE_RUNNER_SOURCE,
+} from './claude-run-source'
+
 import type { ClaudePolicyFlags } from './policy-map'
 import type {
   BridgeEventChannel,
@@ -89,6 +97,12 @@ export interface ClaudeCodeTextConfig {
   streamPartials?: boolean
   /** Extra environment variables for the claude process inside the sandbox. */
   env?: Record<string, string>
+  /**
+   * `'api-key'` (default) injects `ANTHROPIC_API_KEY`.
+   * `'host'` uses `claude login` and does not inject the key.
+   * Not inferred from the sandbox.
+   */
+  authMode?: 'host' | 'api-key'
   /** Emit a `file.changed` CUSTOM event with the git diff after the run (default true). */
   emitDiff?: boolean
 }
@@ -98,6 +112,27 @@ function q(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`
 }
 
+/** Copy host Anthropic auth into the sandbox process. Docker `exec` Env replaces the container env, so a key set only at create time can vanish. */
+function hostClaudeAuthEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  const apiKey = process.env.ANTHROPIC_API_KEY
+  if (apiKey) env.ANTHROPIC_API_KEY = apiKey
+  const authToken = process.env.ANTHROPIC_AUTH_TOKEN
+  if (authToken) env.ANTHROPIC_AUTH_TOKEN = authToken
+  return env
+}
+
+/**
+ * Windows Node often has USERPROFILE but no HOME. Claude then cannot find
+ * `~/.claude.json` (the `claude login` file) and prints "Not logged in".
+ */
+function localProcessHomeEnv(provider: string): Record<string, string> {
+  if (provider !== 'local-process') return {}
+  if (process.env.HOME) return {}
+  const home = process.env.USERPROFILE
+  return home ? { HOME: home } : {}
+}
+
 /** Format a host tool-bridge as claude's `--mcp-config` JSON. */
 function bridgeToMcpConfig(bridge: HostToolBridge): string {
   return JSON.stringify({
@@ -153,56 +188,71 @@ export class ClaudeCodeTextAdapter<
     )
   }
 
+  supportsCombinedToolsAndSchema(): boolean {
+    return true
+  }
+
+  combinedStructuredOutputSource(): 'event' {
+    return 'event'
+  }
+
   /** Build the `claude` command line (prompt goes via stdin, not argv). */
-  private buildCommand(
+  private buildArgv(
     options: TextOptions<ClaudeCodeTextProviderOptions>,
     resume: string | undefined,
     policyFlags: ClaudePolicyFlags,
     mcpConfigPath: string | undefined,
     permissionPromptTool: string | undefined,
-  ): string {
+    hasJsonSchema: boolean,
+  ): Array<string> {
     const config = this.adapterConfig
     const modelOptions = options.modelOptions
-    const exe = config.claudeExecutable ?? 'claude'
+    const exeParts = (config.claudeExecutable ?? 'claude').split(' ')
 
+    // `--setting-sources user` before `-p`. Do not pass `--bare`: that flag
+    // skips stored `claude login` credentials and prints
+    // "Not logged in · Please run /login" (claude-code#51047).
+    // `-p` can take the next token as the prompt, so these flags stay first.
     const args: Array<string> = [
+      ...exeParts,
+      '--setting-sources',
+      'user',
       '-p',
       '--output-format',
       'stream-json',
       '--verbose',
       '--model',
-      q(this.model),
+      this.model,
     ]
 
     if (config.streamPartials !== false) args.push('--include-partial-messages')
-    if (resume !== undefined) args.push('--resume', q(resume))
+    if (resume !== undefined) args.push('--resume', resume)
 
-    // Precedence: per-call modelOptions > adapter config > policy > sandbox default.
     const permissionMode =
       modelOptions?.permissionMode ??
       config.permissionMode ??
       policyFlags.permissionMode ??
       'bypassPermissions'
-    args.push('--permission-mode', q(permissionMode))
+    args.push('--permission-mode', permissionMode)
 
     const maxTurns = modelOptions?.maxTurns ?? config.maxTurns
     if (maxTurns !== undefined) args.push('--max-turns', String(maxTurns))
 
-    for (const dir of config.addDirs ?? []) args.push('--add-dir', q(dir))
+    for (const dir of config.addDirs ?? []) args.push('--add-dir', dir)
 
     const allowedTools = [
       ...(modelOptions?.allowedTools ?? config.allowedTools ?? []),
       ...policyFlags.allowedTools,
     ]
     if (allowedTools.length > 0) {
-      args.push('--allowedTools', q([...new Set(allowedTools)].join(',')))
+      args.push('--allowedTools', [...new Set(allowedTools)].join(','))
     }
     const disallowedTools = [
       ...(modelOptions?.disallowedTools ?? config.disallowedTools ?? []),
       ...policyFlags.disallowedTools,
     ]
     if (disallowedTools.length > 0) {
-      args.push('--disallowedTools', q([...new Set(disallowedTools)].join(',')))
+      args.push('--disallowedTools', [...new Set(disallowedTools)].join(','))
     }
 
     const systemPrompts = normalizeSystemPrompts(options.systemPrompts)
@@ -214,15 +264,18 @@ export class ClaudeCodeTextAdapter<
         config.systemPromptMode === 'replace'
           ? '--system-prompt'
           : '--append-system-prompt'
-      args.push(flag, q(joined))
+      args.push(flag, joined)
     }
 
-    if (mcpConfigPath !== undefined) args.push('--mcp-config', q(mcpConfigPath))
+    if (mcpConfigPath !== undefined) args.push('--mcp-config', mcpConfigPath)
+    if (hasJsonSchema) {
+      args.push('--json-schema', CLAUDE_JSON_SCHEMA_PLACEHOLDER)
+    }
     if (permissionPromptTool !== undefined) {
-      args.push('--permission-prompt-tool', q(permissionPromptTool))
+      args.push('--permission-prompt-tool', permissionPromptTool)
     }
 
-    return `${exe} ${args.join(' ')}`
+    return args
   }
 
   /**
@@ -308,6 +361,7 @@ export class ClaudeCodeTextAdapter<
       const sandbox = this.sandboxFrom(options)
       cleanupSandbox = sandbox
       const cwd = this.workdir(options)
+
       // Durability comes from `withSandbox(sandbox, { runs, durability })`, read
       // back off the capability bus. Absent it, everything below resolves to
       // exactly today's behavior (no journal option, no alignment, and a
@@ -390,10 +444,15 @@ export class ClaudeCodeTextAdapter<
         })
       }
 
-      const { prompt, resume } = buildPrompt(
+      const built = buildPrompt(
         options.messages,
         options.modelOptions?.sessionId,
       )
+      const resume = built.resume
+      const prompt =
+        options.outputSchema !== undefined
+          ? appendOutputSchemaInstruction(built.prompt, options.outputSchema)
+          : built.prompt
       // Both files below name themselves after `runId`, and durability makes
       // `runId` CALLER-chosen. Raw, a `/` in it would silently turn each basename
       // into a nested path (writing outside the intended directory, or failing on
@@ -421,7 +480,17 @@ export class ClaudeCodeTextAdapter<
         tempFiles.push(mcpConfigPath)
         mcpConfigArg = mcpConfigFile
       }
-      const command = this.buildCommand(
+      let jsonSchemaFile: string | undefined
+      if (options.outputSchema !== undefined) {
+        jsonSchemaFile = `tanstack-output-schema-${runIdSegment}.json`
+        const schemaPath = `${cwd}/${jsonSchemaFile}`
+        await sandbox.fs.write(schemaPath, JSON.stringify(options.outputSchema))
+        tempFiles.push(schemaPath)
+      }
+      const runnerFile = `tanstack-claude-run-${runIdSegment}.mjs`
+      await sandbox.fs.write(`${cwd}/${runnerFile}`, CLAUDE_RUNNER_SOURCE)
+      tempFiles.push(`${cwd}/${runnerFile}`)
+      const argv = this.buildArgv(
         options,
         resume,
         mapPolicyToClaudeFlags(policy),
@@ -429,7 +498,17 @@ export class ClaudeCodeTextAdapter<
         bridge && permission
           ? `mcp__${bridge.name}__${permission.toolName}`
           : undefined,
+        jsonSchemaFile !== undefined,
       )
+      // Filenames only on the shell line. JSON (schema, system prompt, MCP
+      // config path) lives in the argv file so git-bash cannot retokenize it.
+      const argvFile = `tanstack-claude-argv-${runIdSegment}.json`
+      await sandbox.fs.write(`${cwd}/${argvFile}`, JSON.stringify(argv))
+      tempFiles.push(`${cwd}/${argvFile}`)
+      const command =
+        jsonSchemaFile === undefined
+          ? `node ${q(runnerFile)} ${q(argvFile)}`
+          : `node ${q(runnerFile)} ${q(argvFile)} ${q(jsonSchemaFile)}`
 
       // Deliver the prompt. The default feeds it over stdin (keeps it out of
       // argv). Providers without a writable host→process stdin (e.g. Cloudflare)
@@ -450,17 +529,31 @@ export class ClaudeCodeTextAdapter<
         { provider: 'claude-code', model: this.model },
       )
 
+      const authMode =
+        options.modelOptions?.authMode ??
+        this.adapterConfig.authMode ??
+        'api-key'
+      const injectApiKey = authMode === 'api-key'
+
       const journalOptions = journalOptionsFor(durability, runId)
       const rawEvents = spawnNdjson(sandbox, runCommand, {
         cwd,
         ...(stdinInput !== undefined ? { input: stdinInput } : {}),
-        // claude maps `bypassPermissions` to `--dangerously-skip-permissions`,
-        // which it refuses to run as root. Sandbox containers routinely run as
-        // root (Docker / Cloudflare), so set `IS_SANDBOX=1` — claude's
-        // documented escape hatch for skip-permissions in an isolated
-        // environment — merged over the sandbox env (a caller-provided value
-        // wins). Safe to set unconditionally; it is a no-op for stricter modes.
-        env: { IS_SANDBOX: '1', ...this.adapterConfig.env },
+        // Isolated sandboxes often run as root. Claude refuses
+        // `--dangerously-skip-permissions` as root unless IS_SANDBOX=1.
+        // CLAUDE_CODE_SANDBOXED marks a real isolation boundary. Do not set
+        // either on local-process: that provider runs on the host.
+        env: {
+          ...(sandbox.provider === 'local-process'
+            ? {}
+            : {
+                IS_SANDBOX: '1',
+                CLAUDE_CODE_SANDBOXED: '1',
+              }),
+          ...(injectApiKey ? hostClaudeAuthEnv() : {}),
+          ...localProcessHomeEnv(sandbox.provider),
+          ...this.adapterConfig.env,
+        },
         ...(options.abortController?.signal
           ? { signal: options.abortController.signal }
           : options.request?.signal
@@ -509,6 +602,7 @@ export class ClaudeCodeTextAdapter<
             // which mixes in `Date.now()` / `Math.random()`). See
             // `createRunScopedIdGen` in `@tanstack/ai-sandbox`.
             genId: createRunScopedIdGen(runId),
+            ...(options.outputSchema ? { expectStructuredOutput: true } : {}),
             onSdkMessage: (message) =>
               logger.provider(`provider=claude-code type=${message.type}`, {
                 chunk: message,
@@ -585,8 +679,8 @@ export class ClaudeCodeTextAdapter<
   ): Promise<StructuredOutputResult<unknown>> {
     return Promise.reject(
       new Error(
-        'Structured output is not yet supported by the in-sandbox Claude Code adapter. ' +
-          'Use a model adapter (e.g. anthropic) for structured output, or omit outputSchema.',
+        'This harness honors outputSchema on chat() in the same turn. ' +
+          'Pass outputSchema to chat(), or use a model adapter for a one-shot extract.',
       ),
     )
   }

package/src/provider-options.ts

@@ -27,4 +27,10 @@ export interface ClaudeCodeTextProviderOptions {
   disallowedTools?: Array<string>
   /** Per-call override of the harness working directory. */
   cwd?: string
+  /**
+   * `'api-key'` (default) injects `ANTHROPIC_API_KEY`.
+   * `'host'` uses `claude login`.
+   * Not inferred from the sandbox.
+   */
+  authMode?: 'host' | 'api-key'
 }

package/src/stream/sdk-types.ts

@@ -60,12 +60,22 @@ export type SdkRawStreamEvent =
   | {
       type: 'content_block_start'
       index: number
-      content_block: { type: string }
+      content_block: {
+        type: string
+        id?: string
+        name?: string
+        input?: unknown
+      }
     }
   | {
       type: 'content_block_delta'
       index: number
-      delta: { type: string; text?: string; thinking?: string }
+      delta: {
+        type: string
+        text?: string
+        thinking?: string
+        partial_json?: string
+      }
     }
   | { type: 'content_block_stop'; index: number }
   | { type: 'message_delta' }

package/src/stream/translate.ts

@@ -1,4 +1,9 @@
 import { EventType, buildBaseUsage } from '@tanstack/ai'
+import {
+  parseJsonFromAssistantText,
+  structuredOutputCompleteChunk,
+  structuredOutputStartChunk,
+} from '@tanstack/ai/adapter-internals'
 import type { StreamChunk, TokenUsage } from '@tanstack/ai'
 import type {
   AgentSdkMessage,
@@ -18,6 +23,13 @@ export const BRIDGED_MCP_SERVER_NAME = 'tanstack'
 
 const BRIDGED_MCP_PREFIX = `mcp__${BRIDGED_MCP_SERVER_NAME}__`
 
+/**
+ * Claude Code `--json-schema` injects a fake tool named StructuredOutput.
+ * The model "calls" it with the schema JSON. The result message may omit
+ * `structured_output`; harvest the tool input in that case.
+ */
+export const SYNTHETIC_STRUCTURED_OUTPUT_TOOL = 'StructuredOutput'
+
 /** Claude Code-specific usage details attached to RUN_FINISHED usage. */
 export type ClaudeCodeProviderUsageDetails = {
   /** Total cost of the harness run in USD, as reported by Claude Code. */
@@ -34,6 +46,8 @@ export interface TranslateContext {
   onSessionId?: (sessionId: string) => void
   /** Called for each raw SDK message, for logging. */
   onSdkMessage?: (message: AgentSdkMessage) => void
+  /** Emit structured-output events from `result.structured_output`. */
+  expectStructuredOutput?: boolean
 }
 
 /**
@@ -47,6 +61,19 @@ export function stripMcpPrefix(name: string): string {
     : name
 }
 
+function isUsefulStructuredObject(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.keys(value).length > 0
+  )
+}
+
+function rememberStructuredOutput(current: unknown, next: unknown): unknown {
+  return isUsefulStructuredObject(next) ? next : current
+}
+
 function stringifyToolResultContent(
   content: SdkToolResultContent | undefined,
 ): string {
@@ -109,6 +136,11 @@ export async function* translateSdkStream(
   let runStarted = false
   /** Tool calls started but with no result yet. */
   const unresolvedToolCalls = new Set<string>()
+  const syntheticOutputToolIds = new Set<string>()
+  let capturedStructuredOutput: unknown
+  let assistantTextForHarvest = ''
+  let partialStructuredJson = ''
+  let partialIsStructuredOutput = false
   /** Anthropic message ids whose text/thinking already streamed via partials. */
   const streamedMessageIds = new Set<string>()
 
@@ -179,12 +211,42 @@ export async function* translateSdkStream(
     partialReasoningId = null
   }
 
+  function* emitStructuredOutput(object: unknown): Generator<StreamChunk> {
+    const raw = JSON.stringify(object)
+    const messageId = genId()
+    yield structuredOutputStartChunk({
+      messageId,
+      model,
+      threadId,
+      runId,
+    })
+    yield structuredOutputCompleteChunk({
+      messageId,
+      model,
+      threadId,
+      runId,
+      object,
+      raw,
+    })
+  }
+
   function* emitToolUse(block: {
     id: string
     name: string
     input: unknown
   }): Generator<StreamChunk> {
     const toolCallName = stripMcpPrefix(block.name)
+    if (
+      ctx.expectStructuredOutput === true &&
+      toolCallName === SYNTHETIC_STRUCTURED_OUTPUT_TOOL
+    ) {
+      capturedStructuredOutput = rememberStructuredOutput(
+        capturedStructuredOutput,
+        block.input,
+      )
+      syntheticOutputToolIds.add(block.id)
+      return
+    }
     const args = JSON.stringify(block.input ?? {})
     yield {
       type: EventType.TOOL_CALL_START,
@@ -226,6 +288,7 @@ export async function* translateSdkStream(
         if (alreadyStreamed) continue
         const messageId = message.message.id ?? genId()
         const text = (block as { text: string }).text
+        if (!alreadyStreamed) assistantTextForHarvest += text
         yield {
           type: EventType.TEXT_MESSAGE_START,
           messageId,
@@ -301,6 +364,10 @@ export async function* translateSdkStream(
         content?: SdkToolResultContent
         is_error?: boolean
       }
+      if (syntheticOutputToolIds.has(toolResult.tool_use_id)) {
+        syntheticOutputToolIds.delete(toolResult.tool_use_id)
+        continue
+      }
       unresolvedToolCalls.delete(toolResult.tool_use_id)
       yield {
         type: EventType.TOOL_CALL_RESULT,
@@ -320,6 +387,29 @@ export async function* translateSdkStream(
     yield* synthesizeUnresolvedResults()
 
     const usage = buildUsage(message.usage, message.total_cost_usd)
+    if (ctx.expectStructuredOutput === true) {
+      const fromResult = isUsefulStructuredObject(message.structured_output)
+        ? message.structured_output
+        : undefined
+      const fromTool = isUsefulStructuredObject(capturedStructuredOutput)
+        ? capturedStructuredOutput
+        : undefined
+      let fromText: unknown
+      if (fromResult === undefined && fromTool === undefined) {
+        const raw = assistantTextForHarvest || message.result || ''
+        if (raw.trim() !== '') {
+          try {
+            fromText = parseJsonFromAssistantText(raw)
+          } catch {
+            fromText = undefined
+          }
+        }
+      }
+      const object = fromResult ?? fromTool ?? fromText
+      if (isUsefulStructuredObject(object)) {
+        yield* emitStructuredOutput(object)
+      }
+    }
     if (message.subtype === 'success') {
       yield {
         type: EventType.RUN_FINISHED,
@@ -365,6 +455,24 @@ export async function* translateSdkStream(
       streamedMessageIds.add(partialMessageId)
     } else if (event.type === 'content_block_start') {
       partialBlockType = event.content_block.type
+      const startedBlock = event.content_block
+      partialIsStructuredOutput =
+        ctx.expectStructuredOutput === true &&
+        startedBlock.type === 'tool_use' &&
+        'name' in startedBlock &&
+        startedBlock.name === SYNTHETIC_STRUCTURED_OUTPUT_TOOL
+      if (partialIsStructuredOutput) {
+        partialStructuredJson = ''
+        if ('id' in startedBlock && typeof startedBlock.id === 'string') {
+          syntheticOutputToolIds.add(startedBlock.id)
+        }
+        if ('input' in startedBlock) {
+          capturedStructuredOutput = rememberStructuredOutput(
+            capturedStructuredOutput,
+            startedBlock.input,
+          )
+        }
+      }
       if (partialBlockType === 'text') {
         partialTextMessageId = partialMessageId ?? genId()
         partialTextContent = ''
@@ -402,6 +510,7 @@ export async function* translateSdkStream(
         typeof event.delta.text === 'string'
       ) {
         partialTextContent += event.delta.text
+        assistantTextForHarvest += event.delta.text
         yield {
           type: EventType.TEXT_MESSAGE_CONTENT,
           messageId: partialTextMessageId,
@@ -410,6 +519,12 @@ export async function* translateSdkStream(
           delta: event.delta.text,
           content: partialTextContent,
         }
+      } else if (
+        event.delta.type === 'input_json_delta' &&
+        partialIsStructuredOutput &&
+        typeof event.delta.partial_json === 'string'
+      ) {
+        partialStructuredJson += event.delta.partial_json
       } else if (
         event.delta.type === 'thinking_delta' &&
         partialReasoningId &&
@@ -424,12 +539,24 @@ export async function* translateSdkStream(
         }
       }
     } else if (event.type === 'content_block_stop') {
+      if (partialIsStructuredOutput && partialStructuredJson !== '') {
+        try {
+          capturedStructuredOutput = rememberStructuredOutput(
+            capturedStructuredOutput,
+            JSON.parse(partialStructuredJson),
+          )
+        } catch {
+          // Incomplete JSON; the complete assistant tool_use may still arrive.
+        }
+      }
       if (partialBlockType === 'text') {
         yield* closePartialText()
       } else if (partialBlockType === 'thinking') {
         yield* closePartialReasoning()
       }
       partialBlockType = null
+      partialIsStructuredOutput = false
+      partialStructuredJson = ''
     }
   }