claude-agent-sdk 0.37.0 → 1.1.0

data/sig/claude_agent_sdk/sdk_mcp_server.rbs

@@ -0,0 +1,76 @@
+module ClaudeAgentSDK
+  # What an SDK MCP tool handler returns: a String (sent as one text block),
+  # or a Hash with a :content Array of MCP content blocks plus optional
+  # :is_error / :structured_content.
+  type tool_result = String | Hash[Symbol | String, untyped]
+
+  # An SDK MCP tool handler (the block given to ClaudeAgentSDK.create_tool).
+  # args is the tools/call arguments Hash (wire_hash).
+  interface _ToolHandler
+    def call: (wire_hash args) -> tool_result
+  end
+
+  # An SDK MCP resource reader: returns a Hash with a :contents Array.
+  interface _ResourceReader
+    def call: () -> Hash[Symbol | String, untyped]
+  end
+
+  # An SDK MCP prompt generator: returns a Hash with a :messages Array.
+  interface _PromptGenerator
+    def call: (Hash[Symbol | String, untyped] args) -> Hash[Symbol | String, untyped]
+  end
+
+  # An in-process MCP server (built by ClaudeAgentSDK.create_sdk_mcp_server).
+  # The list_*/call_*/read_*/get_* methods invoke it directly, outside a
+  # session.
+  class SdkMcpServer
+    attr_reader name: String
+
+    attr_reader version: String
+
+    attr_reader tools: Array[SdkMcpTool]
+
+    attr_reader resources: Array[SdkMcpResource]
+
+    attr_reader prompts: Array[SdkMcpPrompt]
+
+    # The underlying server object from the `mcp` gem (MCP::Server); not
+    # typed here so the signatures don't depend on that gem's.
+    attr_reader mcp_server: untyped
+
+    # Where handlers run on DIRECT invocations (a session dispatch uses the
+    # session's own mode). Defaults to :thread.
+    attr_reader callback_scheduling: :thread | :inline
+
+    # Wrapper for DIRECT invocations (a session dispatch uses the session's).
+    attr_reader callback_wrapper: _CallbackWrapper?
+
+    # A String is coerced to a Symbol; anything but :thread / :inline raises
+    # ArgumentError.
+    def callback_scheduling=: (:thread | :inline | "thread" | "inline" value) -> (:thread | :inline | "thread" | "inline")
+
+    # Raises ArgumentError unless value is callable or nil.
+    def callback_wrapper=: (_CallbackWrapper? value) -> _CallbackWrapper?
+
+    def initialize: (name: String, ?version: String, ?tools: Array[SdkMcpTool], ?resources: Array[SdkMcpResource], ?prompts: Array[SdkMcpPrompt]) -> void
+
+    # Tool definitions: { name:, description:, inputSchema:, annotations:?, _meta:? }.
+    def list_tools: () -> Array[Hash[Symbol, untyped]]
+
+    # Runs the tool's handler. Failures come back in-band with isError: true
+    # (a String handler result is wrapped into a text block).
+    def call_tool: (String name, Hash[Symbol | String, untyped] arguments) -> Hash[Symbol | String, untyped]
+
+    def list_resources: () -> Array[Hash[Symbol, untyped]]
+
+    # Raises when the resource does not exist or its reader returns no
+    # :contents.
+    def read_resource: (String uri) -> Hash[Symbol | String, untyped]
+
+    def list_prompts: () -> Array[Hash[Symbol, untyped]]
+
+    # Raises when the prompt does not exist or its generator returns no
+    # :messages.
+    def get_prompt: (String name, ?Hash[Symbol | String, untyped] arguments) -> Hash[Symbol | String, untyped]
+  end
+end

data/sig/claude_agent_sdk/session_store.rbs

@@ -0,0 +1,105 @@
+module ClaudeAgentSDK
+  # Values of ClaudeAgentOptions#session_store_flush.
+  SESSION_STORE_FLUSH_MODES: Array[String]
+
+  # A SessionStore key. String keys: 'project_key' and 'session_id' always;
+  # 'subpath' (e.g. "subagents/agent-<id>") only for a subagent transcript.
+  type session_key = Hash[String, String?]
+
+  # A session summary as built by ClaudeAgentSDK.fold_session_summary:
+  # { 'session_id' => String, 'mtime' => Integer, 'data' => Hash[String, untyped] }.
+  type session_summary = Hash[String, untyped]
+
+  # The duck type ClaudeAgentOptions#session_store and the session functions'
+  # session_store: accept. Only #append and #load are required; an adapter
+  # need not subclass SessionStore. Keys and entries cross this boundary as
+  # String-keyed Hashes (docs/types.md#hash-keys).
+  #
+  # The SDK also probes (SessionStore.implements?) for these OPTIONAL methods
+  # and uses them when present — they cannot be expressed as optional
+  # interface members, so they are listed here:
+  #
+  #   def list_sessions: (String project_key) -> Array[{ 'session_id' => String, 'mtime' => Integer }]
+  #   def list_session_summaries: (String project_key) -> Array[session_summary]
+  #   def delete: (session_key key) -> void        # a main key cascades to its subkeys
+  #   def list_subkeys: (session_key key) -> Array[String]
+  #   def callback_scheduling: () -> (:thread | :inline)   # :inline = fiber-native adapter
+  #
+  # ClaudeAgentSDK::Testing.run_session_store_conformance checks an adapter
+  # against the behavioral contracts.
+  interface _SessionStore
+    # Mirrors a batch of transcript entries. Must be thread-safe per key and
+    # should dedupe by entry['uuid'].
+    def append: (session_key key, Array[transcript_hash] entries) -> void
+
+    # The full transcript for key, or nil when it was never written.
+    def load: (session_key key) -> Array[transcript_hash]?
+  end
+
+  # Optional base class for adapters. Its methods raise NotImplementedError,
+  # which marks an optional method as absent (see .implements?).
+  class SessionStore
+    # True when store overrides method rather than inheriting the
+    # NotImplementedError default (works for duck-typed adapters too).
+    def self.implements?: (untyped store, Symbol | String method) -> bool
+
+    def append: (session_key key, Array[transcript_hash] entries) -> void
+
+    def load: (session_key key) -> Array[transcript_hash]?
+
+    def list_sessions: (String project_key) -> Array[Hash[String, String | Integer]]
+
+    def list_session_summaries: (String project_key) -> Array[session_summary]
+
+    def delete: (session_key key) -> void
+
+    def list_subkeys: (session_key key) -> Array[String]
+  end
+
+  # In-memory SessionStore for tests and development; data is lost on exit.
+  # Implements every optional method.
+  class InMemorySessionStore < SessionStore
+    def initialize: () -> void
+
+    def append: (session_key key, Array[transcript_hash]? entries) -> void
+
+    def load: (session_key key) -> Array[transcript_hash]?
+
+    def list_sessions: (String project_key) -> Array[Hash[String, String | Integer]]
+
+    def list_session_summaries: (String project_key) -> Array[session_summary]
+
+    def delete: (session_key key) -> void
+
+    def list_subkeys: (session_key key) -> Array[String]
+
+    # Test helper: all entries for key ([] when absent).
+    def get_entries: (session_key key) -> Array[transcript_hash]
+
+    # Test helper: number of stored main transcripts.
+    def size: () -> Integer
+
+    # Test helper: removes everything.
+    def clear: () -> void
+  end
+
+  # Test helpers shipped for third-party SessionStore adapter authors.
+  module Testing
+    # Raised by run_session_store_conformance on the first violated contract.
+    class ConformanceError < StandardError
+    end
+
+    # The optional SessionStore methods skip_optional: accepts.
+    OPTIONAL_METHODS: Array[String]
+
+    # Asserts the SessionStore behavioral contracts against a fresh store
+    # from make_store (called once per contract). Raises ConformanceError on
+    # a violation; returns nil otherwise.
+    def self.run_session_store_conformance: (_StoreFactory make_store, ?skip_optional: Array[String | Symbol], ?check_uuid_dedupe: bool) -> nil
+
+    # Returns a fresh store per call.
+    interface _StoreFactory
+      def call: () -> _SessionStore
+    end
+  end
+end

data/sig/claude_agent_sdk/streaming.rbs

@@ -0,0 +1,15 @@
+module ClaudeAgentSDK
+  # Builders for streaming input: a prompt that is an Enumerator of JSONL
+  # user messages.
+  module Streaming
+    # One JSON-encoded user message, newline-terminated. content is a String
+    # or an Array of content-block Hashes.
+    def self.user_message: (String | Array[Hash[Symbol | String, untyped]] content, ?session_id: String, ?parent_tool_use_id: String?) -> String
+
+    def self.from_array: (_Each[String | Array[Hash[Symbol | String, untyped]]] messages, ?session_id: String) -> Enumerator[String, void]
+
+    # The block receives an Enumerator::Yielder; each value it yields becomes
+    # one user message.
+    def self.from_block: (?session_id: String) { (Enumerator::Yielder yielder) -> void } -> Enumerator[String, void]
+  end
+end

data/sig/claude_agent_sdk/transport.rbs

@@ -0,0 +1,98 @@
+module ClaudeAgentSDK
+  # What `query(transport:)` and Client need from a transport. A custom
+  # transport may subclass Transport or be any object with these methods.
+  # read_messages must yield each stdout line parsed with
+  # `JSON.parse(line, symbolize_names: true)` (see docs/types.md#hash-keys).
+  # #close must be idempotent. (Transport#ready? is part of the abstract
+  # class but the SDK never calls it, so it is not required here.)
+  interface _Transport
+    def connect: () -> void
+
+    def write: (String data) -> void
+
+    def read_messages: () { (wire_hash message) -> void } -> void
+
+    def close: () -> void
+
+    def end_input: () -> void
+  end
+
+  # Client's transport_class: Client calls
+  # `transport_class.new(options, **transport_args)`.
+  interface _TransportClass
+    def new: (ClaudeAgentOptions options, **untyped transport_args) -> _Transport
+  end
+
+  # Abstract base for custom transports: every method raises
+  # NotImplementedError until overridden.
+  class Transport
+    def connect: () -> void
+
+    def write: (String data) -> void
+
+    def read_messages: () { (wire_hash message) -> void } -> void
+                     | () -> Enumerator[wire_hash, void]
+
+    def close: () -> void
+
+    def ready?: () -> bool
+
+    def end_input: () -> void
+  end
+
+  # The default transport: spawns the `claude` CLI and speaks stream-JSON
+  # over its stdin/stdout.
+  class SubprocessCLITransport < Transport
+    # The legacy two-argument form `new(prompt, options)` ignores prompt.
+    def initialize: (ClaudeAgentOptions options) -> void
+                  | (untyped prompt, ClaudeAgentOptions options) -> void
+
+    def connect: () -> void
+
+    def write: (String data) -> void
+
+    def read_messages: () { (wire_hash message) -> void } -> void
+                     | () -> Enumerator[wire_hash, void]
+
+    def close: () -> void
+
+    def ready?: () -> bool
+
+    def end_input: () -> void
+  end
+
+  # Builds the CLI argv SubprocessCLITransport would spawn (for custom
+  # transports that run the CLI elsewhere; see docs/client.md).
+  class CommandBuilder
+    def initialize: (String cli_path, ClaudeAgentOptions options) -> void
+
+    def build: () -> Array[String]
+  end
+
+  # Downloads a pinned Claude Code CLI into vendor/claude (Docker/CI deploys).
+  # Every failure raises CLIInstallError.
+  module CLIInstaller
+    # The CLI version this gem release is tested against.
+    PINNED_CLI_VERSION: String
+
+    # The directory vendor/claude resolves against (nil: the cwd at call
+    # time). An absolute, frozen path once set.
+    def self.root: () -> String?
+
+    def self.root=: ((String | Pathname)? path) -> (String | Pathname)?
+
+    # Absolute path of the default install directory.
+    def self.default_dir: () -> String
+
+    # Installs the CLI ('stable', 'latest' or a concrete version) and returns
+    # the absolute path of the binary. Idempotent and safe to run
+    # concurrently.
+    def self.install: (?version: String, ?dir: (String | Pathname)?) -> String
+
+    # Installs PINNED_CLI_VERSION.
+    def self.install_pinned: (?dir: (String | Pathname)?) -> String
+
+    # Path of an already-installed binary, or nil.
+    def self.installed_path: (?dir: (String | Pathname)?) -> String?
+  end
+end

data/sig/claude_agent_sdk/types/base.rbs

@@ -0,0 +1,39 @@
+module ClaudeAgentSDK
+  # Base class of the SDK's value types (messages, content blocks, hook
+  # inputs/outputs, option values).
+  #
+  # Attribute names are accepted in several spellings — Symbol or String,
+  # snake_case or camelCase — by .new, #[] and #[]=, which reach attributes
+  # only. The camelCase readers (`msg.sessionId`) are public API too but are
+  # resolved dynamically (method_missing), so they have no static signature
+  # here: prefer the snake_case readers, or #[], in typed code.
+  class Type
+    # Returns object unchanged when it already is an instance, nil for nil,
+    # and otherwise builds one (leniently: unknown keys never raise).
+    def self.wrap: (untyped object) -> instance?
+
+    # Builds an instance from a Hash (leniently); nil for anything else.
+    def self.from_hash: (untyped hash) -> instance?
+
+    # attributes: a Hash of attribute name => value (the keyword form
+    # `Klass.new(name: value)` passes the same Hash). On a user-constructed
+    # (strict) type an unknown key raises ArgumentError; types parsed from
+    # CLI output ignore it.
+    def initialize: (?Hash[Symbol | String, untyped]? attributes) -> void
+
+    # Reads an attribute; nil for a name that is not an attribute.
+    def []: (Symbol | String name) -> untyped
+
+    # Writes an attribute through its setter; returns value. A name that is
+    # not an attribute is ignored, or raises ArgumentError on a strict type.
+    def []=: (Symbol | String name, untyped value) -> untyped
+
+    # The wire (CLI) form; types that are sent to the CLI override this.
+    def to_h: () -> Hash[Symbol, untyped]
+
+    # Bounded, credential-filtered, human-oriented rendering.
+    def inspect: () -> String
+
+    def to_s: () -> String
+  end
+end

data/sig/claude_agent_sdk/types/content_blocks.rbs

@@ -0,0 +1,79 @@
+module ClaudeAgentSDK
+  # A raw Hash inside a content block: Symbol keys on live messages, String
+  # keys on blocks parsed from a transcript (SessionMessage#content_blocks).
+  type block_hash = wire_hash | transcript_hash
+
+  # A content block of a UserMessage / AssistantMessage / SessionMessage.
+  type content_block = TextBlock
+                     | ThinkingBlock
+                     | ToolUseBlock
+                     | ToolResultBlock
+                     | ServerToolUseBlock
+                     | ServerToolResultBlock
+                     | UnknownBlock
+
+  class TextBlock < Type
+    attr_accessor text: String?
+
+    def to_s: () -> String
+  end
+
+  class ThinkingBlock < Type
+    attr_accessor thinking: String?
+
+    attr_accessor signature: String?
+  end
+
+  class ToolUseBlock < Type
+    attr_accessor id: String?
+
+    attr_accessor name: String?
+
+    attr_accessor input: block_hash?
+  end
+
+  class ToolResultBlock < Type
+    attr_accessor tool_use_id: String?
+
+    # A String, or an Array of content-block Hashes.
+    attr_accessor content: (String | Array[block_hash])?
+
+    attr_accessor is_error: bool?
+  end
+
+  # A server-side tool call (advisor, web_search, code_execution, ...).
+  class ServerToolUseBlock < Type
+    attr_accessor id: String?
+
+    attr_accessor name: String?
+
+    attr_accessor input: block_hash?
+  end
+
+  # The result of a server-side tool call. content is passed through from
+  # the API as-is and its shape depends on the tool.
+  class ServerToolResultBlock < Type
+    attr_accessor tool_use_id: String?
+
+    attr_accessor content: untyped
+
+    attr_accessor is_error: bool?
+  end
+
+  # A block type this SDK version does not model ("document", "image", ...):
+  # type is the original block type, data the raw block.
+  class UnknownBlock < Type
+    attr_accessor type: String?
+
+    attr_accessor data: block_hash?
+  end
+
+  # A tool call a PreToolUse hook deferred (ResultMessage#deferred_tool_use).
+  class DeferredToolUse < Type
+    attr_accessor id: String?
+
+    attr_accessor name: String?
+
+    attr_accessor input: block_hash?
+  end
+end