ask-agent 0.15.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 816f21ed178b31227a58afeeed65f2428dbe9cce7d4a6ddab2c6fda7a6a60a89
-  data.tar.gz: 4dec09ce3cc94c6abc0e94bd5dee9f6ac9bde083dc7995af601a6650e692fd37
+  metadata.gz: 44a7d741bb255935ebfa4790a7da3d36dc4b4200ab8ebd1e061f8d31b194c798
+  data.tar.gz: ad33f40cffc85328e4cc753291db6fa5730fd7edffc52fcf4f96b34eade7a863
 SHA512:
-  metadata.gz: 8de0c033834105f7c147115bd84b97306fc91b787690fc9e82563835f53b8fad69ff90dfabeeada12be9a8651e9ecfffd960d8e2fa6e84ffff4709f30519a5de
-  data.tar.gz: b5d46db9e66b242ea35fafaf86c67401ad27ee8ef0099ad4811a3d8442e63bd54aa2b16be5e4a7b2aa0f7305603cf39d1b5497e66648f59a9d701489bbdc6c8c
+  metadata.gz: 3e8c63b1465e8090d050e92b03773ec1a38caf9b2c4b22abbb08f5b19007e50317d5befa058343ea6c08e11450ad0a5c5c2f99609ef64d5f00ef9855893f5086
+  data.tar.gz: 02e39e5fdb5ecdcd91dc57572a0594d90155534ed7dc282b1029a4041fe7943b94e45c5066e1c86c75b1cb0efb7824a5eb522dcd650c81ad41cfd5177dfafc98

data/CHANGELOG.md

@@ -1,4 +1,69 @@
-## [0.15.0] — 2026-07-24
+## [0.19.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Agent::SubAgent.new("definition_name")` — create sub-agents from
+  filesystem definitions**. Passing a string looks up an agent definition
+  by name (same convention as `Ask::Agent.new("name")`), reading model,
+  tools, instructions, and other settings from the definition files.
+
+  ```ruby
+  # agents/web_search/agent.rb defines model, tools, instructions
+  search = Ask::Agent::SubAgent.new("web_search")
+
+  coordinator = Ask::Agent::Session.new(
+    model: "gpt-4o",
+    tools: [search, Ask::Tools::Shell::Bash]
+  )
+  ```
+
+- **VCR-based integration tests** for SubAgent. Real API calls are recorded
+  and replayed via VCR cassettes. Run with `OPENAI_API_KEY` set to record,
+  or without to replay existing cassettes.
+
+### Changed
+
+- `Ask::Agent::SubAgent.new(name:, ...)` now supports `provider:` parameter
+  for provider-specific sub-agents.
+
+## [0.18.0] — 2026-07-26
+
+### Added
+
+- **`Ask::Agent::SubAgent` — delegate tasks to a specialized sub-agent tool**.
+  A self-contained tool class that satisfies the tool duck type (`name`,
+  `description`, `params_schema`, `call`). When the coordinator LLM calls it,
+  a fresh sub-agent session runs independently with its own model, tools,
+  and instructions.
+
+  ```ruby
+  search = Ask::Agent::SubAgent.new(
+    name: "web_search",
+    description: "Search the web for current information",
+    model: "gpt-4o-mini",
+    tools: [MyApp::Tools::WebSearch],
+    system_prompt: "You are a research assistant."
+  )
+
+  coordinator = Ask::Agent::Session.new(
+    model: "gpt-4o",
+    tools: [search, Ask::Tools::Shell::Bash]
+  )
+
+  coordinator.run("What's the latest Rails release and how stable is it?")
+  ```
+
+### Removed
+
+- **`Ask::Agent.sub_agent_tool`** factory method — replaced by the
+  `Ask::Agent::SubAgent` class directly. The class IS the tool, no
+  factory or wrapper needed.
+
+## [0.17.0] — 2026-07-26
+
+### Added
+
+- Bump ask-tools dependency for `Ask::Tools::SubAgent` support
 
 ### Added
 

data/lib/ask/agent/events.rb

@@ -11,6 +11,7 @@ module Ask
 
       MessageStart = Data.define
       TextDelta = Data.define(:content)
+      ThinkingDelta = Data.define(:content)
       ToolCallDelta = Data.define(:name, :arguments, :id)
       MessageEnd = Data.define(:tool_calls)
 

data/lib/ask/agent/loop.rb

@@ -27,6 +27,10 @@ module Ask
             event_emitter.emit(Events::TextDelta.new(content: chunk.content))
           end
 
+          if chunk.respond_to?(:thinking) && chunk.thinking.to_s.strip.length > 0
+            event_emitter.emit(Events::ThinkingDelta.new(content: chunk.thinking))
+          end
+
           if chunk.tool_call?
             chunk.tool_calls.each do |id, tc|
               event_emitter.emit(Events::ToolCallDelta.new(

data/lib/ask/agent/streaming.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    # Framework-agnostic SSE streaming for agent sessions.
+    #
+    # Returns a Rack-compatible Enumerator that yields SSE-formatted strings
+    # as the agent runs. Works with any Rack server (Puma, Falcon, etc.)
+    # without requiring ActionController::Live or Rails.
+    #
+    # @example In a Rails controller (with ActionController::Live::SSE)
+    #   def create
+    #     response.headers["Content-Type"] = "text/event-stream"
+    #     sse = SSE.new(response.stream)
+    #
+    #     Ask::Agent::Streaming.run(session, prompt) do |type, data|
+    #       sse.write(data, event: type)
+    #     end
+    #   ensure
+    #     sse&.close
+    #   end
+    #
+    # @example In a Rack app (raw Enumerator)
+    #   stream = Ask::Agent::Streaming.run(session, prompt)
+    #   [200, { "Content-Type" => "text/event-stream" }, stream]
+    #
+    # @example With custom event mapping
+    #   stream = Ask::Agent::Streaming.run(session, prompt) do |event|
+    #     case event
+    #     when Events::TextDelta
+    #       { type: "delta", data: { content: event.content } }
+    #     when Events::ToolExecutionStart
+    #       { type: "tool_start", data: { name: event.name, id: event.id } }
+    #     else
+    #       nil # skip unhandled events
+    #     end
+    #   end
+    module Streaming
+      DEFAULT_EVENT_MAP = {
+        Events::TextDelta => "delta",
+        Events::ThinkingDelta => "thinking",
+        Events::ToolCallDelta => "tool_call_delta",
+        Events::ToolExecutionStart => "tool_start",
+        Events::ToolExecutionUpdate => "tool_update",
+        Events::ToolExecutionEnd => "tool_end",
+        Events::SessionEnd => "done",
+        Events::Error => "error"
+      }.freeze
+
+      class << self
+        # Run an agent session and stream events as SSE-formatted strings.
+        #
+        # Two modes:
+        #
+        # 1. **No block** — returns a Rack-compatible Enumerator that yields
+        #    raw SSE strings: "data: {\"type\":\"delta\",\"content\":\"...\"}\n\n"
+        #
+        # 2. **With block** — calls the block for each event with
+        #    `(event_type_string, data_hash)`. The block is responsible for
+        #    writing/handling the data. This mode is designed for use with
+        #    Rails' `ActionController::Live::SSE#write`.
+        #
+        # @param session [Session] the agent session to run
+        # @param prompt [String] the user's message
+        # @param event_map [Hash<Class, String>] optional custom event-to-type mapping
+        # @yield [type, data] called for each event (only in block mode)
+        # @yieldparam type [String] the SSE event type name
+        # @yieldparam data [Hash] the event data payload
+        # @return [Enumerator, nil] Enumerator in no-block mode, nil in block mode
+        def run(session, prompt, event_map: {}, &block)
+          mapping = DEFAULT_EVENT_MAP.merge(event_map)
+
+          if block
+            run_with_block(session, prompt, mapping, &block)
+            nil
+          else
+            run_with_enumerator(session, prompt, mapping)
+          end
+        end
+
+        private
+
+        def run_with_block(session, prompt, mapping)
+          errors = []
+
+          session.on_event do |event|
+            type = event_type(event, mapping)
+            data = event_data(event)
+            next unless type
+
+            yield(type, data)
+          end
+
+          # Emit start event
+          yield("start", { session_id: session.id })
+
+          session.run(prompt)
+
+          # If errors accumulated during tool execution, emit them
+          errors.each { |err| yield("error", { message: err }) }
+        rescue => e
+          yield("error", { message: e.message })
+        end
+
+        def run_with_enumerator(session, prompt, mapping)
+          Enumerator.new do |yielder|
+            errors = []
+
+            session.on_event do |event|
+              type = event_type(event, mapping)
+              data = event_data(event)
+              next unless type
+
+              yielder << sse_line(type, data)
+            end
+
+            # Emit start event
+            yielder << sse_line("start", { session_id: session.id })
+
+            session.run(prompt)
+
+            errors.each { |err| yielder << sse_line("error", { message: err }) }
+
+            yielder << sse_line("close", {})
+          rescue => e
+            yielder << sse_line("error", { message: e.message })
+          ensure
+            yielder << sse_line("close", {})
+          end
+        end
+
+        def event_type(event, mapping)
+          # Check for a direct class match
+          return mapping[event.class] if mapping.key?(event.class)
+
+          # Check for a superclass match (e.g. ToolExecutionStart is a kind of event)
+          event.class.ancestors.each do |ancestor|
+            return mapping[ancestor] if mapping.key?(ancestor)
+          end
+
+          nil
+        end
+
+        def event_data(event)
+          case event
+          when Events::TextDelta
+            { content: event.content }
+          when Events::ThinkingDelta
+            { content: event.content }
+          when Events::ToolCallDelta
+            { name: event.name, arguments: event.arguments, id: event.id }
+          when Events::ToolExecutionStart
+            { name: event.name, id: event.id, args: safe_args(event.arguments) }
+          when Events::ToolExecutionUpdate
+            { id: event.id, partial_result: event.partial_result.to_s.truncate(200) }
+          when Events::ToolExecutionEnd
+            { name: event.name, id: event.id, duration_ms: event.duration_ms, is_error: event.is_error }
+          when Events::SessionEnd
+            { turn_count: event.turn_count, tool_calls_made: event.tool_calls_made,
+              input_tokens: event.input_tokens, output_tokens: event.output_tokens,
+              cost: event.cost }
+          when Events::SessionStart
+            {}
+          when Events::Error
+            { message: event.error, recoverable: event.recoverable }
+          else
+            {}
+          end
+        end
+
+        def sse_line(type, data)
+          payload = data.merge(type: type)
+          "data: #{JSON.generate(payload)}\n\n"
+        end
+
+        def safe_args(args)
+          return {} unless args.is_a?(Hash)
+
+          safe = args.dup
+          %w[password secret token api_key key auth_token access_token sql command].each do |sensitive|
+            safe[sensitive] = "[REDACTED]" if safe.key?(sensitive)
+          end
+          safe
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/sub_agent.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # A tool that delegates a task to a specialized sub-agent.
+    #
+    # The coordinator agent sees this as a regular tool — when the LLM calls it,
+    # a fresh sub-agent session runs independently with its own model, tools,
+    # and instructions, and returns the result.
+    #
+    # Satisfies the tool duck type (name, description, params_schema, call)
+    # so it can be passed directly in the tools array.
+    #
+    # @example From a filesystem definition
+    #   # agents/web_search/agent.rb defines a WebSearch agent.
+    #   # Use it as a sub-agent by passing its name:
+    #
+    #   search = Ask::Agent::SubAgent.new("web_search")
+    #
+    #   coordinator = Ask::Agent::Session.new(
+    #     model: "gpt-4o",
+    #     tools: [search, Ask::Tools::Shell::Bash]
+    #   )
+    #
+    # @example Inline configuration
+    #   search = Ask::Agent::SubAgent.new(
+    #     name: "web_search",
+    #     description: "Search the web for current information",
+    #     model: "gpt-4o-mini",
+    #     tools: [Ask::Tools::WebSearch],
+    #     system_prompt: "You are a research assistant."
+    #   )
+    #
+    # @example Using with a different provider
+    #   review = Ask::Agent::SubAgent.new(
+    #     name: "code_review",
+    #     model: "claude-sonnet-4",
+    #     provider: :anthropic,
+    #     tools: [Ask::Tools::Shell::Read, Ask::Tools::Shell::Grep],
+    #     system_prompt: "You are a senior code reviewer."
+    #   )
+    class SubAgent
+      # @return [String] tool name visible to the LLM
+      attr_reader :name
+
+      # @return [String] tool description visible to the LLM
+      attr_reader :description
+
+      # Create a new SubAgent tool.
+      #
+      # When given a String, looks up a filesystem agent definition by name
+      # (matching the convention used by {Ask::Agent.new}). Model, tools,
+      # instructions, and other settings are read from the definition files.
+      #
+      # When given keyword arguments, configures the sub-agent inline.
+      #
+      # @overload initialize(definition_name)
+      #   @param definition_name [String] Name of a filesystem agent definition.
+      #   @raise [Ask::Agent::UnknownAgent] If no definition is found.
+      #
+      # @overload initialize(name:, description: nil, model:, tools: [],
+      #           system_prompt: nil, provider: nil, max_turns: 10, **session_opts)
+      #   @param name [String] Tool name (e.g. "web_search").
+      #   @param description [String, nil] Tool description. Auto-generated
+      #     from the model and tools count if not provided.
+      #   @param model [String] Model identifier for the sub-agent session.
+      #   @param tools [Array<Class, Object>] Tools available to the sub-agent.
+      #   @param system_prompt [String, nil] Instructions for the sub-agent.
+      #   @param provider [Symbol, nil] Provider override.
+      #   @param max_turns [Integer] Max conversation turns for the sub-agent.
+      #   @param session_opts [Hash] Additional options forwarded to Session.new.
+      def initialize(definition_name = nil, name: nil, description: nil, model: nil,
+                     tools: [], system_prompt: nil, provider: nil,
+                     max_turns: 10, **session_opts)
+        if definition_name
+          from_definition(definition_name, **session_opts)
+        else
+          @name = name
+          @description = description || default_description(model, tools)
+          @model = model
+          @tools = tools.map { |t| t.is_a?(Class) ? t.new : t }
+          @system_prompt = system_prompt
+          @provider = provider
+          @max_turns = max_turns
+          @session_opts = session_opts
+        end
+      end
+
+      # JSON Schema for the tool's parameter.
+      #
+      # @return [Hash]
+      def params_schema
+        {
+          type: "object",
+          properties: {
+            "task" => {
+              type: "string",
+              description: "The task to delegate to the sub-agent"
+            }
+          },
+          required: ["task"],
+          additionalProperties: false
+        }
+      end
+
+      # Provider-specific parameters (none by default).
+      #
+      # @return [Hash]
+      def provider_params
+        {}
+      end
+
+      # Execute the sub-agent with the given task.
+      #
+      # Creates a fresh session for each call, runs the task, and returns the
+      # result. If the sub-agent fails, returns an error result — the
+      # coordinator can decide how to proceed.
+      #
+      # @param args [Hash, String] Arguments from the LLM.
+      # @param abort_controller [Object, nil] Optional abort controller.
+      # @return [Ask::Result]
+      def call(args = {}, abort_controller = nil)
+        task = extract_task(args)
+
+        session_opts = {
+          model: @model,
+          tools: @tools.map(&:class),
+          max_turns: @max_turns
+        }
+        session_opts[:provider] = @provider if @provider
+        session_opts[:system_prompt] = @system_prompt if @system_prompt
+        session_opts.merge!(@session_opts)
+
+        session = Session.new(**session_opts)
+        result = session.run(task.to_s)
+        Ask::Result.ok(data: result.to_s)
+      rescue StandardError => e
+        Ask::Result.failure("SubAgent '#{@name}' error: #{e.message}")
+      end
+
+      # Human-readable representation.
+      #
+      # @return [String]
+      def inspect
+        "#<Ask::Agent::SubAgent name=#{@name.inspect}>"
+      end
+
+      private
+
+      def from_definition(definition_name, **session_opts)
+        Ask::Agent.rediscover!
+        entry = Ask::Agent.definitions[definition_name.to_s]
+        raise UnknownAgent, "Unknown agent: #{definition_name.inspect}" unless entry
+
+        klass, dir = entry
+        config = klass._config
+
+        @name = definition_name
+        @model = config[:model]
+        @description = "Delegate to #{definition_name} sub-agent (#{@model})"
+        @provider = config[:provider]
+
+        # Resolve tools from definition
+        resolved_tools = Ask::Agent.__send__(:resolve_definition_tools, config[:tools] || [], dir)
+        @tools = resolved_tools.map { |t| t.is_a?(Class) ? t.new : t }
+
+        # Load instructions from definition
+        prompt = klass.instructions_content
+        @system_prompt = prompt
+
+        @max_turns = config[:max_turns] || 10
+        # Merge any options from the definition config
+        @session_opts = (config[:options] || {}).merge(session_opts)
+      end
+
+      def extract_task(args)
+        case args
+        when Hash then (args["task"] || args[:task] || args.to_s).to_s
+        else args.to_s
+        end
+      end
+
+      def default_description(model, tools)
+        desc = "Delegate to a sub-agent (#{model}"
+        desc += " with #{tools.size} tool(s)" if tools.any?
+        desc + ")"
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.15.0"
+    VERSION = "0.20.0"
   end
 end

data/lib/ask/agent.rb

@@ -244,6 +244,29 @@ require_relative "agent/skills/load_skill_tool"
 require_relative "agent/scheduler"
 require_relative "agent/definition"
 require_relative "agent/cli"
+require_relative "agent/streaming"
+require_relative "agent/sub_agent"
 
 # Test helpers (loaded on demand)
 autoload :Test, "ask/agent/test"
+
+# Convenience method on the top-level Ask module.
+# Provides a quick one-shot chat without instantiating a Session directly.
+#
+#   Ask.chat("Hello")
+#   Ask.chat("Tell me about X", model: "gpt-4o")
+#   Ask.chat("Stream this") { |chunk| puts chunk.content }
+#
+module Ask
+  def self.chat(message, model: nil, system_prompt: nil, &block)
+    session = Agent::Session.new(
+      model: model || Agent.configuration.default_model,
+      system_prompt: system_prompt
+    )
+    if block
+      session.run(message, &block)
+    else
+      session.run(message)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -196,6 +196,8 @@ files:
 - lib/ask/agent/stream_transforms/pipeline.rb
 - lib/ask/agent/stream_transforms/text_buffer.rb
 - lib/ask/agent/stream_transforms/thinking_separator.rb
+- lib/ask/agent/streaming.rb
+- lib/ask/agent/sub_agent.rb
 - lib/ask/agent/system_context.rb
 - lib/ask/agent/telemetry.rb
 - lib/ask/agent/test.rb