@r-cli/sdk 1.0.114 → 1.0.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r-cli/sdk",
-  "version": "1.0.114",
+  "version": "1.0.115",
   "description": "SDK for Claude Tools with tool, query, and createSdkMcpServer exports",
   "type": "module",
   "main": "./sdk.mjs",

package/sdk.d.ts

@@ -1,206 +1,568 @@
-/**
- * JSON Schema type for tool input/output schemas
- */
-export interface JsonSchema {
-  type: "object";
-  properties?: Record<string, unknown>;
-  required?: string[];
-  [key: string]: unknown;
+import type { MessageParam as APIUserMessage } from "@anthropic-ai/sdk/resources";
+import type {
+    BetaMessage as APIAssistantMessage,
+    BetaRawMessageStreamEvent as RawMessageStreamEvent,
+    BetaUsage as Usage,
+} from "@anthropic-ai/sdk/resources/beta/messages/messages.mjs";
+import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { UUID } from "crypto";
+import { type z, type ZodObject, type ZodRawShape } from "zod";
+export type NonNullableUsage = {
+  [K in keyof Usage]: NonNullable<Usage[K]>;
+};
+export type ModelUsage = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadInputTokens: number;
+  cacheCreationInputTokens: number;
+  webSearchRequests: number;
+  costUSD: number;
+  contextWindow: number;
+};
+export type ApiKeySource = "user" | "project" | "org" | "temporary";
+export type ConfigScope = "local" | "user" | "project";
+export type McpStdioServerConfig = {
+  type?: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+};
+export type McpSSEServerConfig = {
+  type: "sse";
+  url: string;
+  headers?: Record<string, string>;
+};
+export type McpHttpServerConfig = {
+  type: "http";
+  url: string;
+  headers?: Record<string, string>;
+};
+export type McpSdkServerConfig = {
+  type: "sdk";
+  name: string;
+};
+export type McpSdkServerConfigWithInstance = McpSdkServerConfig & {
+  instance: McpServer;
+};
+export type McpServerConfig =
+  | McpStdioServerConfig
+  | McpSSEServerConfig
+  | McpHttpServerConfig
+  | McpSdkServerConfigWithInstance;
+export type McpServerConfigForProcessTransport =
+  | McpStdioServerConfig
+  | McpSSEServerConfig
+  | McpHttpServerConfig
+  | McpSdkServerConfig;
+type PermissionUpdateDestination =
+  | "userSettings"
+  | "projectSettings"
+  | "localSettings"
+  | "session";
+export type PermissionBehavior = "allow" | "deny" | "ask";
+export type PermissionUpdate =
+  | {
+      type: "addRules";
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "replaceRules";
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "removeRules";
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "setMode";
+      mode: PermissionMode;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "addDirectories";
+      directories: string[];
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "removeDirectories";
+      directories: string[];
+      destination: PermissionUpdateDestination;
+    };
+export type PermissionResult =
+  | {
+      behavior: "allow";
+      /**
+       * Updated tool input to use, if any changes are needed.
+       *
+       * For example if the user was given the option to update the tool use
+       * input before approving, then this would be the updated input which
+       * would be executed by the tool.
+       */
+      updatedInput: Record<string, unknown>;
+      /**
+       * Permissions updates to be applied as part of accepting this tool use.
+       *
+       * Typically this is used as part of the 'always allow' flow and these
+       * permission updates are from the `suggestions` field from the
+       * CanUseTool callback.
+       *
+       * It is recommended that you use these suggestions rather than
+       * attempting to re-derive them from the tool use input, as the
+       * suggestions may include other permission changes such as adding
+       * directories or incorporate complex tool-use logic such as bash
+       * commands.
+       */
+      updatedPermissions?: PermissionUpdate[];
+    }
+  | {
+      behavior: "deny";
+      /**
+       * Message indicating the reason for denial, or guidance of what the
+       * model should do instead.
+       */
+      message: string;
+      /**
+       * If true, interrupt execution and do not continue.
+       *
+       * Typically this should be set to true when the user says 'no' with no
+       * further guidance. Leave unset or false if the user provides guidance
+       * which the model should incorporate and continue.
+       */
+      interrupt?: boolean;
+    };
+export type PermissionRuleValue = {
+  toolName: string;
+  ruleContent?: string;
+};
+export type CanUseTool = (
+  toolName: string,
+  input: Record<string, unknown>,
+  options: {
+    /** Signaled if the operation should be aborted. */
+    signal: AbortSignal;
+    /**
+     * Suggestions for updating permissions so that the user will not be
+     * prompted again for this tool during this session.
+     *
+     * Typically if presenting the user an option 'always allow' or similar,
+     * then this full set of suggestions should be returned as the
+     * `updatedPermissions` in the PermissionResult.
+     */
+    suggestions?: PermissionUpdate[];
+    /**
+     * Unique identifier for this specific tool call within the assistant message.
+     * Multiple tool calls in the same assistant message will have different toolUseIDs.
+     */
+    toolUseID: string;
+  }
+) => Promise<PermissionResult>;
+export declare const HOOK_EVENTS: readonly [
+  "PreToolUse",
+  "PostToolUse",
+  "Notification",
+  "UserPromptSubmit",
+  "SessionStart",
+  "SessionEnd",
+  "Stop",
+  "SubagentStop",
+  "PreCompact"
+];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export type HookCallback = (
+  input: HookInput,
+  toolUseID: string | undefined,
+  options: {
+    signal: AbortSignal;
+  }
+) => Promise<HookJSONOutput>;
+export interface HookCallbackMatcher {
+  matcher?: string;
+  hooks: HookCallback[];
 }
-
-/**
- * Tool definition
- */
-export interface ToolDefinition {
+export type BaseHookInput = {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  permission_mode?: string;
+};
+export type PreToolUseHookInput = BaseHookInput & {
+  hook_event_name: "PreToolUse";
+  tool_name: string;
+  tool_input: unknown;
+};
+export type PostToolUseHookInput = BaseHookInput & {
+  hook_event_name: "PostToolUse";
+  tool_name: string;
+  tool_input: unknown;
+  tool_response: unknown;
+};
+export type NotificationHookInput = BaseHookInput & {
+  hook_event_name: "Notification";
+  message: string;
+  title?: string;
+};
+export type UserPromptSubmitHookInput = BaseHookInput & {
+  hook_event_name: "UserPromptSubmit";
+  prompt: string;
+};
+export type SessionStartHookInput = BaseHookInput & {
+  hook_event_name: "SessionStart";
+  source: "startup" | "resume" | "clear" | "compact";
+};
+export type StopHookInput = BaseHookInput & {
+  hook_event_name: "Stop";
+  stop_hook_active: boolean;
+};
+export type SubagentStopHookInput = BaseHookInput & {
+  hook_event_name: "SubagentStop";
+  stop_hook_active: boolean;
+};
+export type PreCompactHookInput = BaseHookInput & {
+  hook_event_name: "PreCompact";
+  trigger: "manual" | "auto";
+  custom_instructions: string | null;
+};
+export declare const EXIT_REASONS: string[];
+export type ExitReason = (typeof EXIT_REASONS)[number];
+export type SessionEndHookInput = BaseHookInput & {
+  hook_event_name: "SessionEnd";
+  reason: ExitReason;
+};
+export type HookInput =
+  | PreToolUseHookInput
+  | PostToolUseHookInput
+  | NotificationHookInput
+  | UserPromptSubmitHookInput
+  | SessionStartHookInput
+  | SessionEndHookInput
+  | StopHookInput
+  | SubagentStopHookInput
+  | PreCompactHookInput;
+export type AsyncHookJSONOutput = {
+  async: true;
+  asyncTimeout?: number;
+};
+export type SyncHookJSONOutput = {
+  continue?: boolean;
+  suppressOutput?: boolean;
+  stopReason?: string;
+  decision?: "approve" | "block";
+  systemMessage?: string;
+  reason?: string;
+  hookSpecificOutput?:
+    | {
+        hookEventName: "PreToolUse";
+        permissionDecision?: "allow" | "deny" | "ask";
+        permissionDecisionReason?: string;
+        updatedInput?: Record<string, unknown>;
+      }
+    | {
+        hookEventName: "UserPromptSubmit";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "SessionStart";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "PostToolUse";
+        additionalContext?: string;
+      };
+};
+export type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
+export type PermissionMode =
+  | "default"
+  | "acceptEdits"
+  | "bypassPermissions"
+  | "plan";
+export type SlashCommand = {
   name: string;
   description: string;
-  inputSchema: JsonSchema;
-  handler: (args: Record<string, unknown>) => Promise<unknown> | unknown;
-}
-
-/**
- * MCP Server instance returned by createSdkMcpServer
- */
-export interface McpServerInstance {
-  type: "sdk";
+  argumentHint: string;
+};
+export type ModelInfo = {
+  value: string;
+  displayName: string;
+  description: string;
+};
+/** Information about the logged in user's account. */
+export type AccountInfo = {
+  email?: string;
+  organization?: string;
+  subscriptionType?: string;
+  tokenSource?: string;
+  apiKeySource?: string;
+};
+export type McpServerStatus = {
   name: string;
-  instance: unknown; // McpServer instance
+  status: "connected" | "failed" | "needs-auth" | "pending";
+  serverInfo?: {
+    name: string;
+    version: string;
+  };
+};
+export type SDKMessageBase = {
+  uuid: UUID;
+  session_id: string;
+};
+type SDKUserMessageContent = {
+  type: "user";
+  message: APIUserMessage;
+  parent_tool_use_id: string | null;
+  /**
+   * True if this is a 'synthetic' user message which did not originate from
+   * the user directly, but instead was generated by the system.
+   */
+  isSynthetic?: boolean;
+};
+export type SDKUserMessage = SDKUserMessageContent & {
+  uuid?: UUID;
+  session_id: string;
+};
+export type SDKUserMessageReplay = SDKMessageBase &
+  SDKUserMessageContent & {
+    /**
+     * True if this is a replay/acknowledgment of a user message that was already
+     * added to the messages array. Used internally to prevent duplicate messages.
+     */
+    isReplay: true;
+  };
+export type SDKAssistantMessage = SDKMessageBase & {
+  type: "assistant";
+  message: APIAssistantMessage;
+  parent_tool_use_id: string | null;
+};
+export type SDKPermissionDenial = {
+  tool_name: string;
+  tool_use_id: string;
+  tool_input: Record<string, unknown>;
+};
+export type SDKResultMessage =
+  | (SDKMessageBase & {
+      type: "result";
+      subtype: "success";
+      duration_ms: number;
+      duration_api_ms: number;
+      is_error: boolean;
+      num_turns: number;
+      result: string;
+      total_cost_usd: number;
+      usage: NonNullableUsage;
+      modelUsage: {
+        [modelName: string]: ModelUsage;
+      };
+      permission_denials: SDKPermissionDenial[];
+    })
+  | (SDKMessageBase & {
+      type: "result";
+      subtype: "error_max_turns" | "error_during_execution";
+      duration_ms: number;
+      duration_api_ms: number;
+      is_error: boolean;
+      num_turns: number;
+      total_cost_usd: number;
+      usage: NonNullableUsage;
+      modelUsage: {
+        [modelName: string]: ModelUsage;
+      };
+      permission_denials: SDKPermissionDenial[];
+    });
+export type SDKSystemMessage = SDKMessageBase & {
+  type: "system";
+  subtype: "init";
+  agents?: string[];
+  apiKeySource: ApiKeySource;
+  claude_code_version: string;
+  cwd: string;
+  tools: string[];
+  mcp_servers: {
+    name: string;
+    status: string;
+  }[];
+  model: string;
+  permissionMode: PermissionMode;
+  slash_commands: string[];
+  output_style: string;
+  skills: string[];
+  plugins: {
+    name: string;
+    path: string;
+  }[];
+};
+export type SDKPartialAssistantMessage = SDKMessageBase & {
+  type: "stream_event";
+  event: RawMessageStreamEvent;
+  parent_tool_use_id: string | null;
+};
+export type SDKCompactBoundaryMessage = SDKMessageBase & {
+  type: "system";
+  subtype: "compact_boundary";
+  compact_metadata: {
+    trigger: "manual" | "auto";
+    pre_tokens: number;
+  };
+};
+export type SDKHookResponseMessage = SDKMessageBase & {
+  type: "system";
+  subtype: "hook_response";
+  hook_name: string;
+  hook_event: string;
+  stdout: string;
+  stderr: string;
+  exit_code?: number;
+};
+export type SDKMessage =
+  | SDKAssistantMessage
+  | SDKUserMessage
+  | SDKUserMessageReplay
+  | SDKResultMessage
+  | SDKSystemMessage
+  | SDKPartialAssistantMessage
+  | SDKCompactBoundaryMessage
+  | SDKHookResponseMessage;
+export interface Query extends AsyncGenerator<SDKMessage, void> {
+  /**
+   * Control Requests
+   * The following methods are control requests, and are only supported when
+   * streaming input/output is used.
+   */
+  interrupt(): Promise<void>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+  setModel(model?: string): Promise<void>;
+  /**
+   * Set the maximum number of thinking tokens the model is allowed to use
+   * when generating its response. This can be used to limit the amount of
+   * tokens the model uses for its response, which can help control cost and
+   * latency.
+   *
+   * Use `null` to clear any previously set limit and allow the model to
+   * use the default maximum thinking tokens.
+   */
+  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
+  supportedCommands(): Promise<SlashCommand[]>;
+  supportedModels(): Promise<ModelInfo[]>;
+  mcpServerStatus(): Promise<McpServerStatus[]>;
+  accountInfo(): Promise<AccountInfo>;
 }
-
-/**
- * Options for createSdkMcpServer
- */
-export interface CreateSdkMcpServerOptions {
+type SdkMcpToolDefinition<Schema extends ZodRawShape = ZodRawShape> = {
+  name: string;
+  description: string;
+  inputSchema: Schema;
+  handler: (
+    args: z.infer<ZodObject<Schema>>,
+    extra: unknown
+  ) => Promise<CallToolResult>;
+};
+export declare function tool<Schema extends ZodRawShape>(
+  _name: string,
+  _description: string,
+  _inputSchema: Schema,
+  _handler: (
+    args: z.infer<ZodObject<Schema>>,
+    extra: unknown
+  ) => Promise<CallToolResult>
+): SdkMcpToolDefinition<Schema>;
+type CreateSdkMcpServerOptions = {
   name: string;
   version?: string;
-  tools?: ToolDefinition[];
-}
-
-/**
- * Options for canUseTool callback
- */
-export interface CanUseToolOptions {
-  signal: AbortSignal;
-  suggestions?: string[];
-}
-
-/**
- * Hook callback function
- */
-export type HookCallback = (
-  input: unknown,
-  toolUseID: string,
-  options: { signal: AbortSignal }
-) => Promise<unknown> | unknown;
-
-/**
- * Hook matcher configuration
- */
-export interface HookMatcher {
-  matcher: unknown;
-  hooks: HookCallback[];
-}
-
+  tools?: Array<SdkMcpToolDefinition<any>>;
+};
 /**
- * Hooks configuration - maps event names to arrays of matchers
+ * Creates an MCP server instance that can be used with the SDK transport.
+ * This allows SDK users to define custom tools that run in the same process.
+ *
+ * If your SDK MCP calls will run longer than 60s, override CLAUDE_CODE_STREAM_CLOSE_TIMEOUT
  */
-export type HooksConfig = Record<string, HookMatcher[]>;
-
-/**
- * Query options
- */
-export interface QueryOptions {
+export declare function createSdkMcpServer(
+  _options: CreateSdkMcpServerOptions
+): McpSdkServerConfigWithInstance;
+export declare class AbortError extends Error {}
+export type AgentDefinition = {
+  description: string;
+  tools?: string[];
+  prompt: string;
+  model?: "sonnet" | "opus" | "haiku" | "inherit";
+};
+export type SettingSource = "user" | "project" | "local";
+export type SdkPluginConfig = {
+  type: "local";
+  path: string;
+};
+export type Options = {
   abortController?: AbortController;
   additionalDirectories?: string[];
+  agents?: Record<string, AgentDefinition>;
   allowedTools?: string[];
-  appendSystemPrompt?: string;
-  canUseTool?: (
-    toolName: string,
-    input: Record<string, unknown>,
-    options: CanUseToolOptions
-  ) => Promise<boolean> | boolean;
+  canUseTool?: CanUseTool;
   continue?: boolean;
-  customSystemPrompt?: string;
   cwd?: string;
   disallowedTools?: string[];
-  env?: Record<string, string>;
-  executable?: string;
+  env?: {
+    [envVar: string]: string | undefined;
+  };
+  executable?: "bun" | "deno" | "node";
   executableArgs?: string[];
-  extraArgs?: Record<string, unknown>;
+  extraArgs?: Record<string, string | null>;
   fallbackModel?: string;
-  hooks?: HooksConfig;
+  /**
+   * When true resumed sessions will fork to a new session ID rather than
+   * continuing the previous session. Use with --resume.
+   */
+  forkSession?: boolean;
+  hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
   includePartialMessages?: boolean;
+  maxThinkingTokens?: number;
   maxTurns?: number;
-  mcpServers?: Record<string, McpServerInstance | unknown>;
+  mcpServers?: Record<string, McpServerConfig>;
   model?: string;
   pathToClaudeCodeExecutable?: string;
-  permissionMode?: string;
+  permissionMode?: PermissionMode;
+  allowDangerouslySkipPermissions?: boolean;
   permissionPromptToolName?: string;
-  resume?: unknown;
-  stderr?: NodeJS.WriteStream;
-  strictMcpConfig?: boolean;
-}
-
-/**
- * Query function parameters
- */
-export interface QueryParams {
-  prompt: string | AsyncIterable<string>;
-  options?: QueryOptions;
-}
-
-/**
- * SDK message type (simplified - actual implementation may have more specific types)
- */
-export type SdkMessage = unknown;
-
-/**
- * Query instance returned by query function
- * 
- * The Query instance is an async iterable, so you can use it in for-await-of loops:
- * ```typescript
- * for await (const message of query({ prompt: "..." })) {
- *   // process message
- * }
- * ```
- */
-export interface QueryInstance extends AsyncIterable<SdkMessage> {
   /**
-   * Stream input messages to the query
-   * @param stream - Async iterable of messages to stream
+   * Load plugins for this session. Plugins provide custom commands, agents,
+   * skills, and hooks that extend Claude Code's capabilities.
+   *
+   * Currently only local plugins are supported via the 'local' type.
+   *
+   * @example
+   * ```typescript
+   * plugins: [
+   *   { type: 'local', path: './my-plugin' },
+   *   { type: 'local', path: '/absolute/path/to/plugin' }
+   * ]
+   * ```
    */
-  streamInput(stream: AsyncIterable<string>): Promise<void>;
-  
-  /**
-   * Interrupt the current query operation
-   */
-  interrupt(): Promise<void>;
-  
+  plugins?: SdkPluginConfig[];
+  resume?: string;
   /**
-   * Set the permission mode
-   * @param mode - Permission mode string
+   * When resuming, only resume messages up to and including the assistant
+   * message with this message.id. Use with --resume.
+   * This allows you to resume from a specific point in the conversation.
+   * The message ID is expected to be from SDKAssistantMessage.message.id.
    */
-  setPermissionMode(mode: string): Promise<void>;
-  
-  /**
-   * Set the model to use
-   * @param model - Model name/identifier
-   */
-  setModel(model: string): Promise<void>;
-  
-  /**
-   * Get supported commands (only available in streaming mode)
-   * @returns Array of supported command names
-   */
-  supportedCommands(): Promise<string[]>;
-  
-  /**
-   * Get supported models (only available in streaming mode)
-   * @returns Array of supported model names
-   */
-  supportedModels(): Promise<string[]>;
-  
-  /**
-   * Async iterator methods
-   */
-  next(value?: unknown): Promise<IteratorResult<SdkMessage>>;
-  return(value?: unknown): Promise<IteratorResult<SdkMessage>>;
-  throw(e?: unknown): Promise<IteratorResult<SdkMessage>>;
-  
-  /**
-   * Async iterator symbol
-   */
-  [Symbol.asyncIterator](): AsyncIterator<SdkMessage>;
-}
-
-/**
- * Creates a tool definition
- * @param name - Tool name
- * @param description - Tool description
- * @param inputSchema - JSON schema for tool input
- * @param handler - Handler function that processes tool calls
- * @returns Tool definition object
- */
-export function tool(
-  name: string,
-  description: string,
-  inputSchema: JsonSchema,
-  handler: (args: Record<string, unknown>) => Promise<unknown> | unknown
-): ToolDefinition;
-
-/**
- * Creates an SDK MCP server
- * @param options - Server configuration options
- * @returns MCP server instance
- */
-export function createSdkMcpServer(
-  options: CreateSdkMcpServerOptions
-): McpServerInstance;
-
-/**
- * Creates a query instance for tool operations
- * @param params - Query parameters including prompt and options
- * @returns Query instance
- */
-export function query(params: QueryParams): QueryInstance;
+  resumeSessionAt?: string;
+  settingSources?: SettingSource[];
+  stderr?: (data: string) => void;
+  strictMcpConfig?: boolean;
+  systemPrompt?:
+    | string
+    | {
+        type: "preset";
+        preset: "claude_code";
+        append?: string;
+      };
+};
+export declare function query(_params: {
+  prompt: string | AsyncIterable<SDKUserMessage>;
+  options?: Options;
+}): Query;
+export { };