@tangle-network/sdk-provider-claude-code 0.0.0-stage → 0.6.1

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2025 Tangle Network
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of this Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+Tangle Network.
+
+For licensing inquiries, contact: hello@tangle.tools

package/dist/index.d.mts

@@ -0,0 +1,528 @@
+import { AgentExecutionInput, AgentExecutionOutcome, AgentExecutionResult, BackendCapabilities, InteractionResponse, McpConfig, SdkHostServices, StreamEvent } from "@tangle-network/agent-interface";
+import { CliExecArgs, CliProviderAdapterBase, CliProviderConfig, CliTurnProcess, CliTurnSpawn, ExecutionState, HarnessId, PreparedAttachment, WorkspacePlanApplication } from "@tangle-network/sdk-provider-cli-base";
+import * as _$_tangle_network_sdk_cli_runner0 from "@tangle-network/sdk-cli-runner";
+import { StreamParserConfig } from "@tangle-network/sdk-cli-runner";
+
+//#region src/types.d.ts
+/**
+ * Authentication mode for Claude Code.
+ * - "api-key": Use ANTHROPIC_API_KEY environment variable
+ * - "oauth": Use OAuth authentication via `claude auth login` (for Max/Pro subscriptions)
+ */
+type ClaudeCodeAuthMode = "api-key" | "oauth";
+/**
+ * Claude Code-specific configuration.
+ */
+interface ClaudeCodeConfig extends CliProviderConfig {
+  /** Path to the claude CLI executable. Default: "claude" */
+  cliPath?: string;
+  /** Model to use. Default: "claude-sonnet-4-5-20250514" */
+  model?: string;
+  /**
+   * Authentication mode.
+   * - "api-key": Use apiKey or ANTHROPIC_API_KEY env var
+   * - "oauth": Use CLI-managed OAuth (for Max/Pro subscriptions)
+   * Default: "api-key" if apiKey is provided, otherwise "oauth"
+   */
+  authMode?: ClaudeCodeAuthMode;
+  /** Optional auth files to materialize under HOME before invoking the CLI. */
+  authFiles?: Array<{
+    path: string;
+    content: string;
+    mode?: number;
+  }>;
+  /** API key (ANTHROPIC_API_KEY). Only used when authMode is "api-key". */
+  apiKey?: string;
+  /** Extra flags to pass to the CLI */
+  extraFlags?: string[];
+  /**
+   * Bypass all permission checks.
+   * Uses --dangerously-skip-permissions flag.
+   * Default: true (for headless/automated use)
+   */
+  bypassPermissions?: boolean;
+  /**
+   * Route the agent's tool-permission decisions to a human through the
+   * generalized `kind:"permission"` interaction broker instead of bypassing
+   * them. When true, the adapter drops `--dangerously-skip-permissions`, hosts
+   * a per-execution permission MCP tool, and points the CLI at it via
+   * `--permission-prompt-tool`; each tool-use prompt becomes an interaction the
+   * sidecar answers with `respondToInteraction`. Opt-in — default headless
+   * behavior (bypass) is unchanged.
+   */
+  interactivePermissions?: boolean;
+  /**
+   * Run the agent in Claude Code plan mode (`--permission-mode plan`): it works
+   * read-only, then calls `ExitPlanMode` to propose a plan. That call is
+   * intercepted on the same per-execution permission MCP server and surfaced as a
+   * `kind:"plan"` interaction — accept to let the agent proceed, reject to make it
+   * revise. Hosts the permission server like `interactivePermissions`. Opt-in.
+   */
+  planMode?: boolean;
+  /**
+   * Keep a run that shares the host's own `~/.claude` free of that host's
+   * state: only project and local settings load (`--setting-sources
+   * project,local`), only this turn's MCP servers load (`--strict-mcp-config`
+   * even when there are none), and auto-memory is off. A sandbox with its
+   * own HOME leaves it unset. Default: false.
+   */
+  isolateHostSettings?: boolean;
+}
+/**
+ * Claude Code CLI event types based on stream-json output format.
+ * These match the JSONL output from `claude --output-format stream-json`.
+ */
+/**
+ * Init event - emitted at start of execution.
+ */
+interface ClaudeCodeInitEvent {
+  type: "init";
+  session_id: string;
+  tools?: string[];
+  mcp_servers?: string[];
+  model?: string;
+}
+/**
+ * System event - system status messages.
+ *
+ * In stream-json output, the session-init payload arrives as
+ * `{type:"system", subtype:"init", session_id, tools, mcp_servers, model}`
+ * rather than the documented `{type:"init", ...}` shape, so the init fields
+ * are surfaced here as optional and mapInitEvent accepts either variant.
+ */
+interface ClaudeCodeSystemEvent {
+  type: "system";
+  subtype: string;
+  message?: string;
+  session_id?: string;
+  tools?: string[];
+  mcp_servers?: string[];
+  model?: string;
+}
+/**
+ * Assistant text content block start.
+ */
+interface ClaudeCodeContentBlockStart {
+  type: "content_block_start";
+  index: number;
+  content_block: {
+    type: "text" | "tool_use" | "thinking";
+    id?: string;
+    name?: string;
+    text?: string;
+    thinking?: string;
+  };
+}
+/**
+ * Content block delta - streaming content.
+ */
+interface ClaudeCodeContentBlockDelta {
+  type: "content_block_delta";
+  index: number;
+  delta: {
+    type: "text_delta" | "input_json_delta" | "thinking_delta";
+    text?: string;
+    partial_json?: string;
+    thinking?: string;
+  };
+}
+/**
+ * Content block stop.
+ */
+interface ClaudeCodeContentBlockStop {
+  type: "content_block_stop";
+  index: number;
+}
+/**
+ * Tool use event - tool invocation.
+ */
+interface ClaudeCodeToolUseEvent {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: unknown;
+}
+/**
+ * Tool result event - tool execution result.
+ *
+ * NOTE: the current claude CLI (2.x stream-json) does NOT emit this shape at
+ * the top level — tool results arrive wrapped in a `ClaudeCodeUserEvent`
+ * (`{type:"user", message:{content:[{type:"tool_result", ...}]}}`). This
+ * top-level form is kept for replay fixtures and synthetic feeds.
+ */
+interface ClaudeCodeToolResultEvent {
+  type: "tool_result";
+  tool_use_id: string;
+  content: unknown;
+  is_error?: boolean;
+}
+/**
+ * User message event from stream-json output. The real claude CLI delivers
+ * every tool result inside one of these envelopes:
+ * `{type:"user", message:{role:"user", content:[{type:"tool_result", ...}]}}`.
+ * `content` blocks other than tool_result (e.g. echoed user text) are ignored.
+ */
+interface ClaudeCodeUserEvent {
+  type: "user";
+  message?: {
+    role?: string;
+    content?: string | Array<Record<string, unknown>>;
+  };
+}
+/**
+ * Result event - final completion. Token counts are nested under `usage`,
+ * alongside `total_cost_usd` at the top level.
+ */
+interface ClaudeCodeResultEvent {
+  type: "result";
+  subtype?: string;
+  is_error?: boolean;
+  api_error_status?: number;
+  terminal_reason?: string;
+  errors?: string[];
+  stop_reason?: string;
+  deferred_tool_use?: {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+  };
+  result?: string;
+  session_id?: string;
+  /** Cost field emitted by the claude CLI's `result` JSON. */
+  total_cost_usd?: number;
+  duration_ms?: number;
+  /** Token counts for the whole turn. */
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+  /**
+   * Per-model usage breakdown, keyed by model id (e.g.
+   * "claude-opus-4-7[1m]"). Fields are already camelCase on the wire.
+   */
+  modelUsage?: Record<string, {
+    costUSD?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+  }>;
+}
+/**
+ * Error event.
+ */
+interface ClaudeCodeErrorEvent {
+  type: "error";
+  error?: {
+    type?: string;
+    message: string;
+  };
+  message?: string;
+}
+/**
+ * Assistant message event from stream-json output.
+ *
+ * Emitted as `{type:"assistant", message:{id, content:[{type, text, ...}]}}`.
+ * Content blocks (text, tool_use, thinking) are delivered inline in the
+ * message rather than as separate content_block_* events.
+ */
+interface ClaudeCodeAssistantContentBlock {
+  type: string;
+  text?: string;
+  thinking?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+interface ClaudeCodeAssistantEvent {
+  type: "assistant";
+  is_api_error_message?: boolean;
+  error?: string;
+  message?: {
+    id?: string;
+    content?: ClaudeCodeAssistantContentBlock[];
+    usage?: {
+      input_tokens?: number;
+      output_tokens?: number;
+      cache_read_input_tokens?: number;
+      cache_creation_input_tokens?: number;
+    };
+  };
+}
+/**
+ * Union of all Claude Code CLI events.
+ */
+type ClaudeCodeEvent = ClaudeCodeInitEvent | ClaudeCodeSystemEvent | ClaudeCodeAssistantEvent | ClaudeCodeUserEvent | ClaudeCodeContentBlockStart | ClaudeCodeContentBlockDelta | ClaudeCodeContentBlockStop | ClaudeCodeToolUseEvent | ClaudeCodeToolResultEvent | ClaudeCodeResultEvent | ClaudeCodeErrorEvent | ClaudeCodeRateLimitEvent;
+/** Subscription rate-limit state, emitted when it changes (seconds since epoch). */
+interface ClaudeCodeRateLimitEvent {
+  type: "rate_limit_event";
+  rate_limit_info?: {
+    status?: string;
+    resetsAt?: number;
+  };
+}
+/**
+ * Internal state for tracking content blocks during streaming.
+ */
+interface ContentBlockState {
+  index: number;
+  type: "text" | "tool_use" | "thinking";
+  id?: string;
+  name?: string;
+  buffer: string;
+  partId?: string;
+}
+//#endregion
+//#region src/claude-launch-adapter.d.ts
+/** Owns Claude's native launch, authentication, MCP registration, and request routing. */
+declare abstract class ClaudeLaunchAdapter extends CliProviderAdapterBase<ClaudeCodeConfig, ClaudeCodeEvent> {
+  readonly provider = "claude-code";
+  protected readonly profileHarness: HarnessId;
+  protected readonly defaultCliPath = "claude";
+  /** Per-turn state must not bleed between concurrent execute calls. */
+  private readonly executionContext;
+  /**
+   * Servers installed at runtime via `addMcp` (hub connections, sandbox
+   * capabilities), kept so `buildArgs` can merge them into the single
+   * `--mcp-config` object. See the merge site for why the CLI's own config
+   * store is not sufficient on its own.
+   */
+  private readonly runtimeMcpServers;
+  /**
+   * Image attachments ride the native `--input-format stream-json` path
+   * (see `buildExecArgs`) instead of the `[Image: ...]` text marker — the
+   * base adapter pre-reads their base64/url into `attachments` and omits
+   * the marker for this kind.
+   */
+  protected nativeAttachmentKinds(): ReadonlyArray<"image" | "file">;
+  protected buildExecArgs(params: {
+    message: string;
+    config: ClaudeCodeConfig;
+    model?: string;
+    sessionId?: string;
+    mintedSessionId?: string;
+    workspaceRoot: string;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    attachments?: PreparedAttachment[];
+  }): CliExecArgs;
+  protected buildExecEnv(config: ClaudeCodeConfig): Record<string, string | undefined>;
+  /**
+   * Whether a turn launches with its prompt on stdin (`--input-format
+   * stream-json`) instead of as an argument: a new session on the box's
+   * managed token, sent through the key proxy, with no interaction server to
+   * wire. Only such a turn can take a spare process, because the proxy, not
+   * the process environment, then carries its correlation headers: a launch
+   * the proxy would not route (its own `--settings`, OAuth, an upstream the
+   * proxy cannot name) is never held, so no spare starts for it.
+   */
+  private launchesHeld;
+  /**
+   * A turn on the box's managed token sends its requests through the sidecar's
+   * model-key proxy, which reports the turn's first model request and relays
+   * every header unchanged. The correlation headers are bound against the
+   * real base URL first (bindExecutionCorrelation, inside super), so the
+   * request carries the same headers on either path. A caller's own key, or a
+   * box whose proxy is not listening, keeps the direct path.
+   */
+  protected buildTurnEnvironment(executionConfig: ClaudeCodeConfig, profilePlan: WorkspacePlanApplication | undefined, workspaceRoot: string, correlationHeaders: Readonly<Record<string, string>> | undefined): Record<string, string | undefined>;
+  /**
+   * Claude Code adds `ANTHROPIC_CUSTOM_HEADERS` (one `Name: Value` per line) to
+   * every model request, so the router records this run's trace and execution
+   * binding on each dispatch. Only the Tangle router receives them.
+   */
+  protected bindExecutionCorrelation(environment: Record<string, string | undefined>, correlationHeaders: Readonly<Record<string, string>> | undefined): Record<string, string | undefined>;
+  protected buildMcpAddArgs(name: string, config: McpConfig): string[];
+  /**
+   * Record the server for inline `--mcp-config` merging, then register it with
+   * the CLI as before.
+   *
+   * Both halves are load-bearing and neither replaces the other. The inline
+   * merge is what actually reaches the model, because a turn carrying any MCP
+   * server also carries `--strict-mcp-config` and the CLI then ignores its own
+   * store. The store registration is what `getMcpStatus` / `claude mcp list`
+   * report, which the sidecar exposes over `/agents/config/mcp`.
+   *
+   * Recorded first so a CLI registration failure cannot leave the agent without
+   * a server that will work perfectly well inline.
+   */
+  addMcp(name: string, config: McpConfig): Promise<void>;
+  protected buildMcpListArgs(): string[] | null;
+}
+//#endregion
+//#region src/claude-warm-adapter.d.ts
+/** Owns held-process preparation, reservation, and adoption for Claude turns. */
+declare abstract class ClaudeWarmAdapter extends ClaudeLaunchAdapter {
+  /**
+   * Spares a turn reserved in `mintNativeSessionId`, by native session id.
+   * The turn's spawn takes its entry, also when the spare stopped meanwhile.
+   */
+  private readonly reservedSpares;
+  /**
+   * Start the process the box's first turn will adopt: the CLI launched as an
+   * ordinary new-session managed turn would launch it, with its stdin held
+   * open, in this adapter's runtime HOME. `systemPrompt` is the prompt that
+   * turn will carry; a turn whose prompt differs stops the process and starts
+   * its own. `ready` settles false when no spare could start.
+   */
+  prewarmProcess(workspaceRootOrUndefined: string | undefined, launch: {
+    systemPrompt: string;
+  }): Promise<{
+    ready: Promise<boolean>;
+  }>;
+  /**
+   * A new session adopts the spare in its HOME when the spare can serve the
+   * turn: the same launch, and the key proxy holding the turn's headers for
+   * the spare's requests. It then runs under the spare's native session id.
+   * Every refusal is made here, before the turn records that id; a refused
+   * spare is stopped and the turn runs under an id of its own once the
+   * spare's process has exited, so no two processes ever hold one session or
+   * share the HOME.
+   */
+  protected mintNativeSessionId(context: {
+    sessionId: string;
+    workspaceRoot: string;
+    config: ClaudeCodeConfig;
+    model?: string;
+    env: Record<string, string | undefined>;
+    signal: AbortSignal;
+    buildExecArgs: (nativeSessionId: string) => CliExecArgs;
+    input: AgentExecutionInput;
+    timeoutMs?: number;
+  }): string | Promise<string>;
+  /** A turn that reserved a spare runs on its process; any other starts one. */
+  protected spawnExecutionProcess(request: CliTurnSpawn<ClaudeCodeConfig, ClaudeCodeEvent>): CliTurnProcess | Promise<CliTurnProcess>;
+  private adoptHeldSpare;
+}
+//#endregion
+//#region src/claude-event-adapter.d.ts
+/** Owns stream-json event translation and assistant/tool part state. */
+declare abstract class ClaudeEventAdapter extends ClaudeWarmAdapter {
+  protected createEventParser(state: ExecutionState, onEvent?: (event: StreamEvent) => void): StreamParserConfig<ClaudeCodeEvent>;
+  private mapEventToStreamEvents;
+  private mapInitEvent;
+  private mapSystemEvent;
+  /**
+   * Maps Claude Code stream-json "assistant" events to stream events.
+   * These contain the full message content (thinking, text, tool_use blocks).
+   */
+  private mapAssistantEvent;
+  private mapContentBlockStart;
+  private mapContentBlockDelta;
+  private mapContentBlockStop;
+  /**
+   * The real claude CLI (2.x stream-json, verified on 2.1.209) delivers every
+   * tool result inside a top-level user event:
+   * `{type:"user", message:{content:[{type:"tool_result", tool_use_id,
+   * content, is_error?}]}}` — there is NO top-level `{type:"tool_result"}`
+   * event on that wire. Each tool_result block routes through the same
+   * completion logic as the top-level shape; other block types in the user
+   * message (echoed text, etc.) carry no completion signal and are skipped.
+   */
+  private mapUserEvent;
+  /**
+   * Top-level `{type:"tool_result"}` shape — not emitted by the current CLI
+   * (results arrive via user events, see mapUserEvent) but kept for replay
+   * fixtures and synthetic feeds.
+   */
+  private mapToolResultEvent;
+  /** Shared completion path for a tool result, however the wire delivered it. */
+  private completeToolResult;
+  /**
+   * Surfaces files an agent produced this turn from a successful tool result.
+   * Built-in write/edit tools carry the path directly on their call input, so
+   * detection needs no result content; MCP tools (`mcp__*`) instead report
+   * output as content blocks, so an `{type:"image"}` block there becomes a
+   * data-URI file part. Every other tool (Bash, Read, Grep, …) has no file
+   * signal Claude Code exposes — a shell command's side effects on disk are
+   * undetectable from the CLI's tool-result event, so those yield nothing.
+   */
+  private detectFileParts;
+  private mapResultEvent;
+  private mapErrorEvent;
+}
+//#endregion
+//#region src/claude-model-auth.d.ts
+/**
+ * The URL a Claude Code process with an API key calls, and the key proxy's
+ * upstream: the config's own minus any `/vN` (the CLI appends `/v1/messages`,
+ * so a box's `<router>/v1` posted `/v1/v1/messages`), else Anthropic.
+ */
+declare function resolveClaudeCodeBaseUrl(baseUrl: string | undefined): string;
+/** Native subscription model IDs exclude the profile's provider qualification. */
+declare function normalizeExplicitClaudeModel(model: string, authMode: ClaudeCodeAuthMode): string;
+//#endregion
+//#region src/adapter.d.ts
+/**
+ * Claude Code provider adapter.
+ *
+ * Implements the SdkProviderAdapter interface for the Claude Code CLI tool.
+ * Extends CliProviderAdapterBase with Claude Code-specific event parsing and CLI arguments.
+ */
+declare class ClaudeCodeProviderAdapter extends ClaudeEventAdapter {
+  /** Shared `kind:"permission"` round-trip — see InteractionBroker. */
+  private readonly permissions;
+  getCapabilities(): BackendCapabilities;
+  protected continuationInteractions(base: boolean | Record<string, boolean> | undefined, outcome: "approved" | "rejected"): boolean | Record<string, boolean>;
+  /**
+   * Host a per-execution interaction MCP server when interactive permissions,
+   * permission or question interactions are on.
+   * Started BEFORE buildExecArgs runs (so its loopback port + token reach
+   * `--mcp-config`) and torn down in finally, denying any decision still pending
+   * when the turn unwinds (fail-closed). Plain turns use the base path.
+   */
+  execute(input: AgentExecutionInput, services: SdkHostServices, onEvent?: (event: StreamEvent) => void): Promise<AgentExecutionResult>;
+  /**
+   * Make the plan continuation's recorded native Claude session authoritative
+   * on the session store so super.execute resumes that conversation. Seed it
+   * when the local mapping is missing, and overwrite a mapping that points at a
+   * different conversation — an intervening turn can recreate the mapping with a
+   * fresh providerSessionId after the plan was submitted (e.g. the box was
+   * recycled and the store lost its entry). Leaving a stale, different id in
+   * place would resume the wrong conversation, which the plan hook then rejects
+   * as a different session than the durable plan. A mapping that already points
+   * at the recorded session is left untouched.
+   */
+  protected reseedNativeSessionForContinuation(input: AgentExecutionInput): Promise<void>;
+  respondToInteraction(response: InteractionResponse): Promise<void>;
+  /**
+   * Build the per-execution interaction MCP server. The `permission` bridge
+   * (the `--permission-prompt-tool` decider) is registered only when the turn
+   * routes permissions; the `ask_user` model tool only when the question
+   * channel is exposed — a question-only turn therefore hosts a server
+   * where the permission tool does not even exist.
+   */
+  private createPermissionServer;
+  protected executionOutcome(state: ExecutionState, _input: AgentExecutionInput): Promise<AgentExecutionOutcome>;
+}
+//#endregion
+//#region src/held-spare.d.ts
+/**
+ * The spare a turn adopted, handed to the sidecar's key proxy. `upstream` is
+ * the model base URL the spare's requests name through the proxy.
+ */
+type HeldSpareTurnSink = (input: {
+  executionId: string;
+  spareId: string;
+  upstream: string;
+  headers: Readonly<Record<string, string>>;
+}) => boolean;
+/**
+ * The sidecar registers the proxy's hook here. Without one, no turn can
+ * adopt a spare: nothing would put the turn's headers on its requests.
+ */
+declare function setHeldSpareTurnSink(next: HeldSpareTurnSink | undefined): void;
+/**
+ * A spare is launched under the native session id its turn will run as, and
+ * names the model upstream its requests reach through the key proxy.
+ */
+type ClaudeSpareLaunch = {
+  readonly nativeSessionId: string;
+  readonly upstream: string;
+};
+declare const claudeHeldSpares: _$_tangle_network_sdk_cli_runner0.HeldSpareRegistry<ClaudeCodeEvent, ClaudeSpareLaunch>;
+//#endregion
+export { type ClaudeCodeAuthMode, type ClaudeCodeConfig, type ClaudeCodeContentBlockDelta, type ClaudeCodeContentBlockStart, type ClaudeCodeContentBlockStop, type ClaudeCodeErrorEvent, type ClaudeCodeEvent, type ClaudeCodeInitEvent, ClaudeCodeProviderAdapter, type ClaudeCodeResultEvent, type ClaudeCodeSystemEvent, type ClaudeCodeToolResultEvent, type ClaudeCodeToolUseEvent, type ContentBlockState, type HeldSpareTurnSink, claudeHeldSpares, normalizeExplicitClaudeModel, resolveClaudeCodeBaseUrl, setHeldSpareTurnSink };
+//# sourceMappingURL=index.d.mts.map