claude_agent 0.7.12 → 0.7.14

data/lib/claude_agent/session_mutations.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeAgent
+  # Session mutation operations: rename and tag sessions.
+  #
+  # Appends JSONL entries to session files to modify session metadata.
+  # Follows the TypeScript SDK pattern of file-level mutations.
+  #
+  # @example Rename a session
+  #   ClaudeAgent.rename_session("abc-123-...", "My new title")
+  #
+  # @example Tag a session
+  #   ClaudeAgent.tag_session("abc-123-...", "important")
+  #
+  # @example Clear a tag
+  #   ClaudeAgent.tag_session("abc-123-...", nil)
+  #
+  module SessionMutations
+    # Unicode characters to strip from tag values (zero-width chars, directional marks)
+    UNICODE_SANITIZE_PATTERN = /[\u200B\u200C\u200D\uFEFF\u200E\u200F\u202A-\u202E\u2066-\u2069]/
+
+    module_function
+
+    # Rename a session by appending a custom-title entry to its session file.
+    #
+    # @param session_id [String] UUID of the session to rename
+    # @param title [String] New title for the session (must be non-empty)
+    # @param dir [String, nil] Project directory to find the session in.
+    #   When nil, searches all projects.
+    # @return [void]
+    # @raise [ArgumentError] If session_id is not a valid UUID or title is empty
+    # @raise [Error] If the session file is not found
+    def rename_session(session_id, title, dir: nil)
+      validate_session_id!(session_id)
+      raise ArgumentError, "title must be a non-empty string" if title.nil? || title.to_s.strip.empty?
+
+      path = find_session_file(session_id, dir: dir)
+      raise Error, "Session not found: #{session_id}" unless path
+
+      entry = {
+        type: "custom-title",
+        customTitle: title.to_s,
+        sessionId: session_id
+      }
+
+      append_jsonl(path, entry)
+    end
+
+    # Tag a session by appending a tag entry to its session file.
+    #
+    # @param session_id [String] UUID of the session to tag
+    # @param tag [String, nil] Tag value. Pass nil to clear the tag.
+    # @param dir [String, nil] Project directory to find the session in.
+    #   When nil, searches all projects.
+    # @return [void]
+    # @raise [ArgumentError] If session_id is not a valid UUID
+    # @raise [Error] If the session file is not found
+    def tag_session(session_id, tag, dir: nil)
+      validate_session_id!(session_id)
+
+      path = find_session_file(session_id, dir: dir)
+      raise Error, "Session not found: #{session_id}" unless path
+
+      sanitized_tag = tag.nil? ? "" : sanitize_unicode(tag.to_s)
+
+      entry = {
+        type: "tag",
+        tag: sanitized_tag,
+        sessionId: session_id
+      }
+
+      append_jsonl(path, entry)
+    end
+
+    # --- Private Helpers ---
+
+    # Validate that a string is a valid UUID.
+    # @param session_id [String]
+    # @raise [ArgumentError] If not a valid UUID
+    def validate_session_id!(session_id)
+      unless SessionPaths::UUID_PATTERN.match?(session_id.to_s)
+        raise ArgumentError, "Invalid session_id: #{session_id}. Must be a valid UUID."
+      end
+    end
+
+    # Find a session file by UUID, searching project directories.
+    # @param session_id [String] UUID
+    # @param dir [String, nil] Optional directory to scope the search
+    # @return [String, nil] Path to the .jsonl file or nil
+    def find_session_file(session_id, dir: nil)
+      filename = "#{session_id}.jsonl"
+
+      if dir
+        resolved = SessionPaths.realpath(dir)
+        project_dir = SessionPaths.find_project_dir(resolved)
+        return nil unless project_dir
+
+        path = File.join(project_dir, filename)
+        return path if File.exist?(path)
+
+        # Check worktrees
+        worktrees = SessionPaths.git_worktrees(resolved)
+        worktrees.each do |wt|
+          wt_project_dir = SessionPaths.find_project_dir(wt)
+          next unless wt_project_dir
+
+          wt_path = File.join(wt_project_dir, filename)
+          return wt_path if File.exist?(wt_path)
+        end
+
+        nil
+      else
+        # Search all project directories
+        base = SessionPaths.projects_dir
+        return nil unless File.directory?(base)
+
+        Dir.entries(base).each do |entry|
+          next if entry.start_with?(".")
+          dir_path = File.join(base, entry)
+          next unless File.directory?(dir_path)
+
+          path = File.join(dir_path, filename)
+          return path if File.exist?(path)
+        end
+
+        nil
+      end
+    end
+
+    # Sanitize a string by removing zero-width and directional Unicode characters.
+    # @param str [String]
+    # @return [String]
+    def sanitize_unicode(str)
+      str.gsub(UNICODE_SANITIZE_PATTERN, "")
+    end
+
+    # Atomically append a JSONL entry to a file.
+    # @param path [String] File path
+    # @param entry [Hash] JSON-serializable entry
+    def append_jsonl(path, entry)
+      File.open(path, "a") do |f|
+        f.write("#{JSON.generate(entry)}\n")
+      end
+    end
+  end
+end

data/lib/claude_agent/transport/subprocess.rb

@@ -387,8 +387,8 @@ module ClaudeAgent
           @stderr.each_line do |line|
             # Call callback if provided, otherwise just drain
             @options.stderr_callback&.call(line.chomp)
-          rescue
-            # Ignore callback errors
+          rescue => e
+            logger.debug("transport") { "stderr callback error: #{e.message}" }
           end
         rescue IOError
           # Stream closed, exit thread

data/lib/claude_agent/types/mcp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # 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
+
+  # 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
+end

data/lib/claude_agent/types/models.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # 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, :supports_fast_mode, :supports_auto_mode) do
+    def initialize(value:, display_name: nil, description: nil, supports_effort: nil, supported_effort_levels: nil, supports_adaptive_thinking: nil, supports_fast_mode: nil, supports_auto_mode: 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
+
+  # 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
+
+  # Return type for supported_agents() (TypeScript SDK v0.2.63 parity)
+  #
+  # @example
+  #   agent = AgentInfo.new(name: "Explore", description: "Search agent", model: "haiku")
+  #   agent.name         # => "Explore"
+  #   agent.description  # => "Search agent"
+  #
+  AgentInfo = Data.define(:name, :description, :model) do
+    def initialize(name:, description: nil, model: 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
+  #   )
+  #
+  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
+
+  # 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"),
+  #     agents: [AgentInfo.new(name: "Explore")]
+  #   )
+  #
+  InitializationResult = Data.define(:commands, :output_style, :available_output_styles, :models, :account, :agents, :fast_mode_state) do
+    def initialize(commands: [], output_style: nil, available_output_styles: [], models: [], account: nil, agents: [], fast_mode_state: nil)
+      super
+    end
+  end
+end

data/lib/claude_agent/types/operations.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # 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
+
+  # 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 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
+end

data/lib/claude_agent/types/sessions.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # 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,
+    :tag,
+    :created_at
+  ) do
+    def initialize(session_id:, summary:, last_modified:, file_size:, custom_title: nil, first_prompt: nil, git_branch: nil, cwd: nil, tag: nil, created_at: 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
+end

data/lib/claude_agent/types/tools.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # 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
+end