claude_agent 0.7.12 → 0.7.14

data/lib/claude_agent/types.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "types/tools"
+require_relative "types/models"
+require_relative "types/mcp"
+require_relative "types/sessions"
+require_relative "types/operations"
+
 module ClaudeAgent
   # Assistant message error types (TypeScript SDK parity)
   # Used to categorize errors returned by the assistant
@@ -16,268 +22,4 @@ module ClaudeAgent
   # API key source types (TypeScript SDK parity)
   # Indicates where the API key was sourced from
   API_KEY_SOURCES = %w[user project org temporary oauth].freeze
-
-  # Tools preset configuration (TypeScript SDK parity)
-  #
-  # @example
-  #   preset = ToolsPreset.new(preset: "claude_code")
-  #   options = ClaudeAgent::Options.new(tools: preset)
-  #
-  ToolsPreset = Data.define(:type, :preset) do
-    def initialize(type: "preset", preset: "claude_code")
-      super
-    end
-
-    def to_h
-      { type: type, preset: preset }
-    end
-  end
-  # Return type for supported_commands() (TypeScript SDK parity)
-  #
-  # @example
-  #   cmd = SlashCommand.new(name: "commit", description: "Create a commit", argument_hint: "[message]")
-  #   cmd.name        # => "commit"
-  #   cmd.description # => "Create a commit"
-  #
-  SlashCommand = Data.define(:name, :description, :argument_hint) do
-    def initialize(name:, description: nil, argument_hint: nil)
-      super
-    end
-  end
-
-  # Return type for supported_models() (TypeScript SDK parity)
-  #
-  # @example
-  #   model = ModelInfo.new(value: "claude-3-opus", display_name: "Claude 3 Opus", description: "Most capable")
-  #   model.value        # => "claude-3-opus"
-  #   model.display_name # => "Claude 3 Opus"
-  #
-  ModelInfo = Data.define(:value, :display_name, :description, :supports_effort, :supported_effort_levels, :supports_adaptive_thinking) do
-    def initialize(value:, display_name: nil, description: nil, supports_effort: nil, supported_effort_levels: nil, supports_adaptive_thinking: nil)
-      super
-    end
-  end
-
-  # Return type for mcp_server_status() (TypeScript SDK parity)
-  # Status values: "connected", "failed", "needs-auth", "pending"
-  #
-  # @example
-  #   status = McpServerStatus.new(name: "filesystem", status: "connected", server_info: {name: "fs", version: "1.0"})
-  #
-  McpServerStatus = Data.define(:name, :status, :server_info, :error, :config, :scope, :tools) do
-    def initialize(name:, status:, server_info: nil, error: nil, config: nil, scope: nil, tools: nil)
-      super
-    end
-  end
-
-  # Task usage statistics for TaskNotificationMessage (TypeScript SDK parity)
-  #
-  # @example
-  #   usage = TaskUsage.new(total_tokens: 5000, tool_uses: 3, duration_ms: 2500)
-  #
-  TaskUsage = Data.define(:total_tokens, :tool_uses, :duration_ms) do
-    def initialize(total_tokens: 0, tool_uses: 0, duration_ms: 0)
-      super
-    end
-  end
-
-  # Return type for account_info() (TypeScript SDK parity)
-  #
-  # @example
-  #   info = AccountInfo.new(email: "user@example.com", organization: "Acme Corp")
-  #
-  AccountInfo = Data.define(:email, :organization, :subscription_type, :token_source, :api_key_source) do
-    def initialize(email: nil, organization: nil, subscription_type: nil, token_source: nil, api_key_source: nil)
-      super
-    end
-  end
-
-  # Composite initialization result from supported_commands request (TypeScript SDK parity)
-  #
-  # @example
-  #   result = InitializationResult.new(
-  #     commands: [SlashCommand.new(name: "commit")],
-  #     output_style: "default",
-  #     available_output_styles: ["default", "concise"],
-  #     models: [ModelInfo.new(value: "claude-sonnet")],
-  #     account: AccountInfo.new(email: "user@example.com")
-  #   )
-  #
-  InitializationResult = Data.define(:commands, :output_style, :available_output_styles, :models, :account) do
-    def initialize(commands: [], output_style: nil, available_output_styles: [], models: [], account: nil)
-      super
-    end
-  end
-
-  # Per-model usage statistics returned in result messages (TypeScript SDK parity)
-  #
-  # @example
-  #   usage = ModelUsage.new(input_tokens: 100, output_tokens: 50, cost_usd: 0.01, max_output_tokens: 4096)
-  #
-  ModelUsage = Data.define(
-    :input_tokens,
-    :output_tokens,
-    :cache_read_input_tokens,
-    :cache_creation_input_tokens,
-    :web_search_requests,
-    :cost_usd,
-    :context_window,
-    :max_output_tokens
-  ) do
-    def initialize(
-      input_tokens: 0,
-      output_tokens: 0,
-      cache_read_input_tokens: 0,
-      cache_creation_input_tokens: 0,
-      web_search_requests: 0,
-      cost_usd: 0.0,
-      context_window: nil,
-      max_output_tokens: nil
-    )
-      super
-    end
-  end
-
-  # Permission denial information in result messages (TypeScript SDK parity)
-  #
-  SDKPermissionDenial = Data.define(:tool_name, :tool_use_id, :tool_input) do
-    def initialize(tool_name:, tool_use_id:, tool_input:)
-      super
-    end
-  end
-
-  # Result of set_mcp_servers() control method (TypeScript SDK parity)
-  #
-  # @example
-  #   result = McpSetServersResult.new(
-  #     added: ["server1"],
-  #     removed: ["old-server"],
-  #     errors: {"server2" => "Connection failed"}
-  #   )
-  #
-  McpSetServersResult = Data.define(:added, :removed, :errors) do
-    def initialize(added: [], removed: [], errors: {})
-      super
-    end
-  end
-
-  # Result of rewind_files() control method (TypeScript SDK parity)
-  #
-  # @example
-  #   result = RewindFilesResult.new(
-  #     can_rewind: true,
-  #     files_changed: ["src/foo.rb", "src/bar.rb"],
-  #     insertions: 10,
-  #     deletions: 5
-  #   )
-  #
-  RewindFilesResult = Data.define(:can_rewind, :error, :files_changed, :insertions, :deletions) do
-    def initialize(can_rewind:, error: nil, files_changed: nil, insertions: nil, deletions: nil)
-      super
-    end
-  end
-
-  # Agent definition for custom subagents (TypeScript SDK parity)
-  #
-  # @example Basic agent
-  #   agent = AgentDefinition.new(
-  #     description: "Runs tests and reports results",
-  #     prompt: "You are a test runner...",
-  #     tools: ["Read", "Grep", "Glob", "Bash"],
-  #     model: "haiku"
-  #   )
-  #
-  # @example Agent with skills and max_turns
-  #   agent = AgentDefinition.new(
-  #     description: "Research agent with specialized skills",
-  #     prompt: "You are a research expert...",
-  #     skills: ["web-search", "summarization"],
-  #     max_turns: 10
-  #   )
-  #
-  # Session metadata returned by list_sessions (TypeScript SDK parity: SDKSessionInfo)
-  #
-  # @example
-  #   session = SessionInfo.new(
-  #     session_id: "abc-123",
-  #     summary: "Fix login bug",
-  #     last_modified: 1706000000000,
-  #     file_size: 4096,
-  #     custom_title: "Login fix",
-  #     first_prompt: "Help me fix the login page",
-  #     git_branch: "fix/login",
-  #     cwd: "/Users/dev/myapp"
-  #   )
-  #
-  SessionInfo = Data.define(
-    :session_id,
-    :summary,
-    :last_modified,
-    :file_size,
-    :custom_title,
-    :first_prompt,
-    :git_branch,
-    :cwd
-  ) do
-    def initialize(session_id:, summary:, last_modified:, file_size:, custom_title: nil, first_prompt: nil, git_branch: nil, cwd: nil)
-      super
-    end
-  end
-
-  # Message from a session transcript returned by get_session_messages (TypeScript SDK v0.2.59 parity)
-  #
-  # @example
-  #   msg = SessionMessage.new(
-  #     type: "user",
-  #     uuid: "abc-123",
-  #     session_id: "def-456",
-  #     message: { "role" => "user", "content" => [{ "type" => "text", "text" => "Hello" }] }
-  #   )
-  #
-  SessionMessage = Data.define(:type, :uuid, :session_id, :message, :parent_tool_use_id) do
-    def initialize(type:, uuid:, session_id:, message:, parent_tool_use_id: nil)
-      super
-    end
-  end
-
-  AgentDefinition = Data.define(
-    :description,
-    :prompt,
-    :tools,
-    :disallowed_tools,
-    :model,
-    :mcp_servers,
-    :critical_system_reminder,
-    :skills,
-    :max_turns
-  ) do
-    def initialize(
-      description:,
-      prompt:,
-      tools: nil,
-      disallowed_tools: nil,
-      model: nil,
-      mcp_servers: nil,
-      critical_system_reminder: nil,
-      skills: nil,
-      max_turns: nil
-    )
-      super
-    end
-
-    def to_h
-      result = {
-        description: description,
-        prompt: prompt
-      }
-      result[:tools] = tools if tools
-      result[:disallowedTools] = disallowed_tools if disallowed_tools
-      result[:model] = model if model
-      result[:mcpServers] = mcp_servers if mcp_servers
-      result[:criticalSystemReminder_EXPERIMENTAL] = critical_system_reminder if critical_system_reminder
-      result[:skills] = skills if skills
-      result[:maxTurns] = max_turns if max_turns
-      result
-    end
-  end
 end

data/lib/claude_agent/v2_session.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # V2 Session options (subset of full Options)
+  # V2 API - UNSTABLE
+  # @alpha
+  #
+  # @example
+  #   options = SessionOptions.new(
+  #     model: "claude-sonnet-4-5-20250929",
+  #     permission_mode: "acceptEdits"
+  #   )
+  #
+  SessionOptions = Data.define(
+    :model,
+    :path_to_claude_code_executable,
+    :env,
+    :allowed_tools,
+    :disallowed_tools,
+    :can_use_tool,
+    :hooks,
+    :permission_mode
+  ) do
+    def initialize(
+      model:,
+      path_to_claude_code_executable: nil,
+      env: nil,
+      allowed_tools: nil,
+      disallowed_tools: nil,
+      can_use_tool: nil,
+      hooks: nil,
+      permission_mode: nil
+    )
+      super
+    end
+  end
+
+  # V2 API - UNSTABLE
+  # Multi-turn session interface for persistent conversations.
+  #
+  # This provides a simpler interface than the full Client class,
+  # matching the TypeScript SDK's SDKSession interface.
+  #
+  # @alpha
+  #
+  # @example Create a session and send messages
+  #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
+  #   session.send("Hello!")
+  #   session.stream.each { |msg| puts msg.inspect }
+  #   session.close
+  #
+  class V2Session
+    attr_reader :session_id, :options
+
+    def initialize(options)
+      @options = options.is_a?(SessionOptions) ? options : SessionOptions.new(**options)
+      @client = nil
+      @session_id = nil
+      @closed = false
+    end
+
+    # Send a message to the agent
+    #
+    # @param message [String, UserMessage] The message to send
+    # @return [void]
+    def send(message)
+      ensure_connected!
+      content = message.is_a?(String) ? message : message
+      @client.send_message(content)
+    end
+
+    # Stream messages from the agent
+    #
+    # @return [Enumerator<message>] An enumerator of messages
+    # @yield [message] Each message received from the agent
+    def stream(&block)
+      ensure_connected!
+      if block_given?
+        @client.receive_response(&block)
+      else
+        @client.receive_response
+      end
+    end
+
+    # Close the session
+    #
+    # @return [void]
+    def close
+      return if @closed
+      @client&.disconnect
+      @closed = true
+    end
+
+    # Check if session is closed
+    #
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    def ensure_connected!
+      raise AbortError, "Session is closed" if @closed
+      return if @client&.connected?
+
+      @client = Client.new(options: build_client_options)
+      @client.connect
+      update_session_id
+    end
+
+    def build_client_options
+      Options.new(
+        model: @options.model,
+        cli_path: @options.path_to_claude_code_executable,
+        env: @options.env,
+        allowed_tools: @options.allowed_tools,
+        disallowed_tools: @options.disallowed_tools,
+        can_use_tool: @options.can_use_tool,
+        hooks: @options.hooks,
+        permission_mode: @options.permission_mode
+      )
+    end
+
+    def update_session_id
+      # Session ID is typically extracted from the first system message
+      # but since we don't have it immediately, we leave it nil until available
+      @session_id = @client.server_info&.dig("session_id")
+    end
+  end
+
+  class << self
+    # V2 API - UNSTABLE
+    # Create a persistent session for multi-turn conversations.
+    #
+    # @param options [Hash, SessionOptions] Session configuration
+    # @return [Session] A new session instance
+    # @alpha
+    #
+    # @example
+    #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
+    #
+    def unstable_v2_create_session(options)
+      V2Session.new(options)
+    end
+
+    # V2 API - UNSTABLE
+    # Resume an existing session by ID.
+    #
+    # @param session_id [String] The session ID to resume
+    # @param options [Hash, SessionOptions] Session configuration
+    # @return [Session] A session configured to resume the specified session
+    # @alpha
+    #
+    # @example
+    #   session = ClaudeAgent.unstable_v2_resume_session("session-abc123", model: "claude-sonnet-4-5-20250929")
+    #
+    def unstable_v2_resume_session(session_id, options)
+      # For resumption, we need to pass the resume option through
+      # Since SessionOptions doesn't have resume, we handle it in the Client options
+      session = V2Session.new(options)
+      session.instance_variable_set(:@resume_session_id, session_id)
+
+      # Override build_client_options to include resume
+      session.define_singleton_method(:build_client_options) do
+        Options.new(
+          model: @options.model,
+          cli_path: @options.path_to_claude_code_executable,
+          env: @options.env,
+          allowed_tools: @options.allowed_tools,
+          disallowed_tools: @options.disallowed_tools,
+          can_use_tool: @options.can_use_tool,
+          hooks: @options.hooks,
+          permission_mode: @options.permission_mode,
+          resume: @resume_session_id
+        )
+      end
+
+      session
+    end
+
+    # V2 API - UNSTABLE
+    # One-shot convenience function for single prompts.
+    #
+    # @param message [String] The prompt message
+    # @param options [Hash, SessionOptions] Session configuration
+    # @return [ResultMessage] The result of the query
+    # @alpha
+    #
+    # @example
+    #   result = ClaudeAgent.unstable_v2_prompt("What files are here?", model: "claude-sonnet-4-5-20250929")
+    #
+    def unstable_v2_prompt(message, options)
+      session = unstable_v2_create_session(options)
+      begin
+        session.send(message)
+        result = nil
+        session.stream.each do |msg|
+          result = msg if msg.is_a?(ResultMessage)
+        end
+        result
+      ensure
+        session.close
+      end
+    end
+  end
+end

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.7.12"
+  VERSION = "0.7.14"
 end

data/lib/claude_agent.rb

@@ -36,7 +36,10 @@ require_relative "claude_agent/session_paths"        # Shared session path infra
 require_relative "claude_agent/list_sessions"       # Session discovery (TypeScript SDK v0.2.53 parity)
 require_relative "claude_agent/get_session_messages"    # Session transcript reading (TypeScript SDK v0.2.59 parity)
 require_relative "claude_agent/session_message_relation" # Chainable message query object
-require_relative "claude_agent/session"                  # Session finder + V2 Session API (unstable)
+require_relative "claude_agent/session_mutations"          # Session rename/tag mutations
+require_relative "claude_agent/get_session_info"           # Single session lookup
+require_relative "claude_agent/v2_session"                  # V2 Session API (unstable)
+require_relative "claude_agent/session"                    # Session finder
 
 module ClaudeAgent
   class << self
@@ -56,9 +59,11 @@ module ClaudeAgent
     # @param dir [String, nil] Directory to scope sessions to (includes git worktrees).
     #   When nil, returns sessions from all projects.
     # @param limit [Integer, nil] Maximum number of sessions to return.
+    # @param include_worktrees [Boolean] When dir is in a git repo, include sessions
+    #   from all git worktree paths. Defaults to true.
     # @return [Array<SessionInfo>]
-    def list_sessions(dir: nil, limit: nil)
-      ListSessions.call(dir: dir, limit: limit)
+    def list_sessions(dir: nil, limit: nil, offset: nil, include_worktrees: true)
+      ListSessions.call(dir: dir, limit: limit, offset: offset, include_worktrees: include_worktrees)
     end
 
     # Read messages from a past session's transcript
@@ -76,6 +81,35 @@ module ClaudeAgent
       GetSessionMessages.call(session_id, dir: dir, limit: limit, offset: offset)
     end
 
+    # Rename a session by appending a custom-title entry to its file.
+    #
+    # @param session_id [String] UUID of the session to rename
+    # @param title [String] New title
+    # @param dir [String, nil] Project directory to scope the search
+    # @return [void]
+    def rename_session(session_id, title, dir: nil)
+      SessionMutations.rename_session(session_id, title, dir: dir)
+    end
+
+    # Tag a session by appending a tag entry to its file.
+    #
+    # @param session_id [String] UUID of the session to tag
+    # @param tag [String, nil] Tag value. Pass nil to clear.
+    # @param dir [String, nil] Project directory to scope the search
+    # @return [void]
+    def tag_session(session_id, tag, dir: nil)
+      SessionMutations.tag_session(session_id, tag, dir: dir)
+    end
+
+    # Look up a single session by ID.
+    #
+    # @param session_id [String] UUID of the session
+    # @param dir [String, nil] Project directory to scope the search
+    # @return [SessionInfo, nil]
+    def get_session_info(session_id, dir: nil)
+      GetSessionInfo.call(session_id, dir: dir)
+    end
+
     # Resume a previous Conversation by session ID
     #
     # @param session_id [String] Session ID to resume