ask-agent 0.25.6 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0ae07fe535ce2c8f33a24f145440bee62e70869d1d1f5cd0eb0cf71cb4b4e2f
-  data.tar.gz: ecb0c237a7b068f854547081b58c659e9b6735cc8d1d1c3f00936f3e0d24037e
+  metadata.gz: d32526c4ac8d8daa60b4f4b63e5787617c2070154cb854f6fff61222f880185d
+  data.tar.gz: cd528117e7577374e8c41a423ec72c9fd1560980017f968d215f674b1a916e3c
 SHA512:
-  metadata.gz: a3d254d5ff2f50ad781e98b087b54c4d085ff36c360970d64106ed1adcbbea926cf07e1f7603bb3a538d9ae7e72a1f2f781b1f0951510258eced384ab797a09d
-  data.tar.gz: 7be070f08f92a3c8db2897730bbf833d8942f82c154be0f23b6fd6be28a27764ddc56313c1fce837646eb551786876eaff2d1d7e846ea27da4102704d7e58100
+  metadata.gz: 4c210ccc2a08d0ed0d2bb60a560aac06635633c816bfd4d5b9ae21b2139af3ae5729b37fb46b795e48b0bbc2975c33e855cea695b507ad306ce04187330605a7
+  data.tar.gz: fb3954229781a8e34a517a0e8d81369e55579ae4c18f041ffb4c99b3295c628bb0e5b49d9f08d080b4cd6d556614ddb5b5cac685b9c7d5813bfb0371281d1e54

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.26.0] - 2026-08-05
+
+### Added
+
+- **Async tools (pending results).** A tool can return `Ask::Result.pending`
+  (ask-core 0.10.0) to hand the turn back with its interim message — the
+  agent voices it immediately and keeps talking — while the real work runs
+  in the background. The tool reads `Ask::Agent.current_session` and
+  `Ask::Agent.current_tool_call_id` (thread-locals set during the run and
+  the tool call) and completes later via
+  `Session#complete_pending_tool(tool_call_id:, result:)`, which adds the
+  tool message to the conversation and runs a follow-up turn so the agent
+  voices the answer. Completions that land mid-turn queue until the turn
+  ends. `ToolPending`/`ToolCompleted` events are emitted; the loop stops
+  after a pending call (no recursion, no loop detection, no premature
+  chat message).
+
 ## [0.25.6] - 2026-08-05
 
 ### Added

data/lib/ask/agent/events.rb

@@ -16,6 +16,10 @@ module Ask
       MessageEnd = Data.define(:tool_calls)
 
       ToolExecutionStart = Data.define(:name, :arguments, :id)
+      # Emitted when a tool returns Ask::Result.pending (async work started).
+      ToolPending = Data.define(:name, :id)
+      # Emitted when a pending (async) tool's background work completes.
+      ToolCompleted = Data.define(:name, :id, :result)
       ToolExecutionUpdate = Data.define(:name, :id, :partial_result)
       ToolExecutionEnd = Data.define(:name, :id, :result, :is_error, :duration_ms)
 

data/lib/ask/agent/loop.rb

@@ -91,16 +91,37 @@ module Ask
           # in threads (with the caller's thread-local context inherited);
           # sequential tools run in the caller thread so per-request context
           # (e.g. Rails CurrentAttributes) is visible without any copying.
+          # Pending (async) tool results skip the chat message — it is added
+          # when the background work completes.
           user_results = tool_executor.execute(
             user_tool_calls, tools, hooks: hooks, event_emitter: event_emitter,
             result_callback: lambda do |tool_call_id, result|
               tc = user_tool_calls[tool_call_id]
+              next unless tc
+              next if result[:status] == "pending"
+
               chat.add_message(role: :tool, content: result[:message].to_s, tool_call_id: tool_call_id) if tc
             end
           )
           all_tool_results.concat(user_results)
         end
 
+        # Async tools: hand the turn back with the interim reply. The
+        # session registers the pending calls; completions arrive later via
+        # Session#complete_pending_tool.
+        pending_calls = all_tool_results.select { |r| r[:status] == "pending" }
+        unless pending_calls.empty?
+          pending_calls.each do |pending_result|
+            if event_emitter.respond_to?(:register_pending_tool)
+              event_emitter.register_pending_tool(
+                pending_result[:tool_call_id], pending_result
+              )
+            end
+          end
+          @consecutive_tool_turns = 0
+          return response.content.to_s
+        end
+
         # Check loop detection
         if loop_detected?(all_tool_results)
           raise LoopDetected, all_tool_results.last[:tool_name]

data/lib/ask/agent/session.rb

@@ -33,6 +33,9 @@ module Ask
         @running = false
         @deleted = false
         @abort_requested = false
+        @pending_tools = {}
+        @pending_mutex = Mutex.new
+        @followup_pending = false
         @turn_count = 0
         @created_at = Time.now
         @_no_tools_instructed = false
@@ -85,14 +88,17 @@ module Ask
         end
       end
 
-      def run(message, tools: nil)
+      def run(message, tools: nil, reset: true)
         raise "Session deleted" if @deleted
         raise "Session already running" if @running
 
         @running = true
         @abort_requested = false
-        @turn_count = 0
-        @loop.reset!
+        Ask::Agent.current_session = self
+        if reset
+          @turn_count = 0
+          @loop.reset!
+        end
 
         emit(Events::SessionStart.new)
 
@@ -140,7 +146,16 @@ module Ask
           raise
         ensure
           @running = false
+          Ask::Agent.current_session = nil if Ask::Agent.current_session.equal?(self)
           persist! if @state
+          # A pending tool completed while this run was busy: voice the
+          # result now that the turn is over (one follow-up per completion).
+          follow_up = @pending_mutex.synchronize do
+            take = @followup_pending
+            @followup_pending = false
+            take
+          end
+          run_follow_up if follow_up
         end
 
         @tool_calls_made = @tool_executor.total_executions
@@ -308,6 +323,59 @@ module Ask
 
       def abort_requested? = @abort_requested
 
+      # --- Async (pending) tools ---
+
+      # Registers a pending tool call (called by the loop when a tool
+      # returned Ask::Result.pending). The background work completes later
+      # via #complete_pending_tool.
+      def register_pending_tool(tool_call_id, result)
+        @pending_mutex.synchronize do
+          @pending_tools[tool_call_id] = result
+        end
+        emit(Events::ToolPending.new(name: result[:tool_name], id: tool_call_id))
+        nil
+      end
+
+      # Completes a pending (async) tool call from a background thread.
+      #
+      # Adds the tool result to the conversation and, when the session is
+      # idle, runs a follow-up turn so the agent voices the answer. If a
+      # turn is running, the follow-up fires as soon as it ends.
+      #
+      # @param tool_call_id [String] the original tool call id
+      # @param result [Hash] tool result hash ({message:, is_error:, ...})
+      # @return [Boolean] true if the completion was registered
+      def complete_pending_tool(tool_call_id:, result:)
+        follow_up = @pending_mutex.synchronize do
+          pending = @pending_tools.delete(tool_call_id)
+          return false unless pending
+
+          @chat.add_message(
+            role: :tool,
+            content: result[:message].to_s,
+            tool_call_id: tool_call_id
+          )
+          if @running
+            @followup_pending = true
+            false
+          else
+            true
+          end
+        end
+        emit(Events::ToolCompleted.new(name: result[:tool_name], id: tool_call_id, result: result))
+        run_follow_up if follow_up
+        true
+      end
+
+      # A follow-up turn driven by an async completion: runs the loop with
+      # the tool message already in the conversation, preserving turn state.
+      def run_follow_up
+        run("", reset: false)
+      rescue => e
+        emit(Events::Error.new(error: e.message, recoverable: false))
+        raise
+      end
+
       # Load a skill by name or file path.
       # Injects the skill's full instructions into the conversation as a system message.
       #

data/lib/ask/agent/tool_executor.rb

@@ -81,7 +81,7 @@ module Ask
         end
 
         threads.each(&:join)
-        tool_calls.keys.map { |id| results[id] }.compact
+        tool_calls.keys.filter_map { |id| results[id]&.merge(tool_call_id: id) }
       end
 
       def execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
@@ -90,7 +90,7 @@ module Ask
           break if sibling_abort.aborted?
 
           result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort)
-          results << result
+          results << result.merge(tool_call_id: id)
           result_callback&.call(id, result)
           break if result[:critical_failure]
           break if result[:halted]
@@ -126,10 +126,13 @@ module Ask
         ))
 
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        Thread.current[:ask_agent_tool_call_id] = tool_call.id
         result = begin
           execute_with_retry(tool, tool_call.id, args, abort_controller)
         rescue Exception => e
           { result: e.message, is_error: true, error: e.class.name }
+        ensure
+          Thread.current[:ask_agent_tool_call_id] = nil
         end
         duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).to_i
         @total_executions += 1
@@ -171,10 +174,19 @@ module Ask
           result[:result].to_s
         end
 
+        inner = result[:result]
+        status = if result[:is_error] == true
+          "error"
+        elsif inner.respond_to?(:pending?) && inner.pending?
+          "pending"
+        else
+          "success"
+        end
+
         {
           tool_name: tool_call.name,
           message: message,
-          status: is_error ? "error" : "success",
+          status: status,
           result: result,
           critical_failure: critical,
           halted: halted
@@ -197,7 +209,13 @@ module Ask
 
       def try_call(tool, args, abort_controller = nil)
         result = tool.call(args, abort_controller: abort_controller)
-        is_error = result.respond_to?(:ok?) ? !result.ok? : false
+        is_error = if result.respond_to?(:pending?) && result.pending?
+          false  # async tool: work continues in the background
+        elsif result.respond_to?(:ok?)
+          !result.ok?
+        else
+          false
+        end
         hash = { result: result, is_error: is_error }
         if result.respond_to?(:metadata) && result.metadata&.dig(:halted)
           hash[:halted] = true

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.25.6"
+    VERSION = "0.26.0"
   end
 end

data/lib/ask/agent.rb

@@ -270,6 +270,33 @@ require_relative "agent/sub_agent"
 # Test helpers (loaded on demand)
 autoload :Test, "ask/agent/test"
 
+# The session running on this thread (set during Session#run). Async
+# tools read it to complete their background work:
+#
+#   session = Ask::Agent.current_session
+#   call_id = Ask::Agent.current_tool_call_id
+#   Thread.new { ...; session.complete_pending_tool(tool_call_id: call_id, result: {...}) }
+module Ask
+  module Agent
+    class << self
+      # @return [Ask::Agent::Session, nil] the session running on this thread
+      def current_session
+        Thread.current[:ask_agent_current_session]
+      end
+
+      # @param session [Ask::Agent::Session, nil]
+      def current_session=(session)
+        Thread.current[:ask_agent_current_session] = session
+      end
+
+      # @return [String, nil] the tool call id being executed on this thread
+      def current_tool_call_id
+        Thread.current[:ask_agent_tool_call_id]
+      end
+    end
+  end
+end
+
 # Convenience method on the top-level Ask module.
 # Provides a quick one-shot chat without instantiating a Session directly.
 #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.25.6
+  version: 0.26.0
 platform: ruby
 authors:
 - Kaka Ruto