ask-agent 0.35.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2040f37b4e9b023374eb6169abd1f1c28fdda335a8032254a15b0d813a7cd0c9
-  data.tar.gz: 7212cbd265d8b054423cfad5ed76717eb36f1ff980c2a394cba9b0b4c256c3e9
+  metadata.gz: e22262139bd8142b9e45f22e831d59360f9465aad8fea93247352591b742d6c3
+  data.tar.gz: 1486719187105e25f794bff150fd9aa59e902096a40c15fdb822b2e7061d9bac
 SHA512:
-  metadata.gz: 1cb0c3e65bd08e9c45f93bdc378149810d7c31594f63cf69799e128b9f32496f3e71ca521cbe43d6729a9d39210bce0469a7eb6686336a45f2677fc473053cad
-  data.tar.gz: 2b6d47cfb37af4c3a2d850a551621af6d44542dd88f9483a695cfcd83b58f2bb893a7403ac91b3a01f3659936ad8f4df5c8d7cc8eb7656c22e6587db0bba0081
+  metadata.gz: 2eaacd8c0a7a32392546ccde9d218d271afa22a3a2d1c154bfc3665691060b9cc4e7ab8d658c25eb2b2e79cccb1ad3bbbf10cd65e36c4324e2fc408f8eb8d973
+  data.tar.gz: d9abb9f16f260d5ece0c403346ae0f1cb5a9edadb3e9fad0a2a56fd05c66748eb0070f16efa8441aa55275c5fc1aff724d43f0d4d6809751b932978272563fcf

data/CHANGELOG.md

@@ -1,3 +1,50 @@
+## [0.37.0] — 2026-08-07
+
+### Added
+
+- **Steer — concurrency-safe message injection.**
+  `Session#steer(message, expected_turn_id:)` lets any thread (web, CLI,
+  another agent) inject a message safely:
+  - **`:stale`** — `expected_turn_id` doesn't match the current turn id
+    (the caller was looking at an older state); the message is rejected.
+  - **`:queued`** — a turn is running; the message is held and dispatched
+    as the next user message at the next turn boundary (the loop now
+    resolves each recursive turn's message from a steer source). No more
+    abort-and-retry.
+  - **`:steered`** — the session is idle; the message enters the
+    conversation and the next run processes it. Queued leftovers drain at
+    the next run start.
+  - `Session#turn_id` tracks the running turn (bumped on `TurnStart`);
+    `Session#queued_steers` reports pending messages.
+
+### Fixed
+
+- **No more duplicate tail checkpoints.** The loop persists after every
+  turn and `run()` persists again on the way out, so every run previously
+  appended a redundant checkpoint (seqs 1,2,3 for two turns). `persist!`
+  now skips the checkpoint when the message count and turn count are
+  unchanged — `checkpoint_history` is exact.
+
+## [0.36.0] — 2026-08-07
+
+### Added
+
+- **Large-output offloading — tool results never bloat the transcript.**
+  `Session.new(offload_large_outputs: true)` (or an Integer threshold,
+  default 4000 chars) stores tool messages above the threshold in a
+  state-backed store; the transcript keeps a short preview plus a reference
+  the model retrieves with the injected `output_read` tool:
+  - `Ask::Agent::ToolOutputStore` — pure KV on the same
+    `Ask::State::Adapter` as sessions/checkpoints/memory
+    (`output:<session_id>:<call_id>` + JSON index), works with every
+    backend; in-process Memory fallback when no `state:` is given. Stored
+    outputs are capped (`max_size:`, default 50,000 chars).
+  - `output_read` is exempt from offloading — its contract is to bring the
+    full output into context on demand.
+  - `Session#delete` cleans up the session's stored outputs.
+  - The loop now passes `session_id` to the tool executor (previously nil),
+    which offloading relies on.
+
 ## [0.35.0] — 2026-08-07
 
 ### Added

data/lib/ask/agent/loop.rb

@@ -17,7 +17,7 @@ module Ask
       @max_consecutive_tool_turns = max_consecutive_tool_turns
       end
 
-      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil, tool_call_repair: nil)
+      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil, tool_call_repair: nil, steer_source: nil)
         raise MaxTurnsExceeded if @turn_count >= @max_turns
 
         event_emitter.emit(Events::TurnStart.new)
@@ -99,6 +99,7 @@ module Ask
           # when the background work completes.
           user_results = tool_executor.execute(
             user_tool_calls, tools, hooks: hooks, event_emitter: event_emitter,
+            session_id: session_id,
             result_callback: lambda do |tool_call_id, result|
               tc = user_tool_calls[tool_call_id]
               next unless tc
@@ -156,10 +157,12 @@ module Ask
         # Aborted while tools ran? Skip the follow-up LLM call.
         return response.content.to_s if aborted?(event_emitter)
 
-        # Recursive call — LLM processes tool results
+        # Recursive call — LLM processes tool results. When a steer source
+        # is provided, queued steer messages become the next user message
+        # instead of an empty continuation.
         run_turn(
           chat: chat,
-          message: "",
+          message: steer_source ? steer_source.call.to_s : "",
           tools: tools,
           tool_executor: tool_executor,
           compactor: compactor,
@@ -167,7 +170,8 @@ module Ask
           event_emitter: event_emitter,
           session_id: session_id,
           persist: persist,
-          tool_call_repair: tool_call_repair
+          tool_call_repair: tool_call_repair,
+          steer_source: steer_source
         )
       end
 

data/lib/ask/agent/memory_extractor.rb

@@ -5,8 +5,7 @@ require "json"
 module Ask
   module Agent
     # Extracts durable facts from a finished session's transcript and writes
-    # them to the session's {Memory} — the "learning" half of durable memory
-    # (codex two-phase pattern, phase 1).
+    # them to the session's {Memory} — the "learning" half of durable memory.
     #
     # One LLM call with a structured-output prompt: the model reads the
     # memory-relevant messages and returns a JSON list of durable facts.

data/lib/ask/agent/output_read.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "ask/tools/tool"
+require "ask/result"
+
+module Ask
+  module Agent
+    # Tool that retrieves an offloaded tool output by call id — the other
+    # half of large-output offloading. The transcript keeps a preview plus a
+    # reference ("output_read id: \"call_123\""); this tool fetches the full
+    # output from the session's {ToolOutputStore}.
+    #
+    # Injected into the session when large-output offloading is enabled.
+    class OutputRead < Ask::Tool
+      description "Retrieve the full output of a tool call that was truncated in the conversation. " \
+                   "Use the id from the truncation note (e.g. output_read id: \"call_123\")."
+
+      param :id, type: :string, desc: "Tool call id from the truncation note", required: true
+
+      # @param store [Ask::Agent::ToolOutputStore]
+      # @param session_id [String] scopes lookups to this session
+      def initialize(store:, session_id:)
+        @store = store
+        @session_id = session_id
+        super()
+      end
+
+      def execute(id:)
+        output = @store.fetch(@session_id, id)
+        return Ask::Result.error(message: "No stored output for id #{id.inspect}") if output.nil?
+
+        Ask::Result.ok(data: output)
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -25,7 +25,8 @@ module Ask
                      skills_disclosure: true, approval: nil,
                      tool_call_repair: nil, checkpoints: false,
                      todos: false, plan_mode: false, memory: nil,
-                     memory_learning: false, **chat_options)
+                     memory_learning: false, offload_large_outputs: false,
+                     **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -40,6 +41,13 @@ module Ask
         @pending_mutex = Mutex.new
         @followup_pending = false
         @turn_count = 0
+        # Concurrency-safe steering: turn id bumped at every
+        # TurnStart; steers arriving mid-turn are queued and dispatched at
+        # the next turn boundary.
+        @turn_id = 0
+        @queued_steers = []
+        @steer_mutex = Mutex.new
+        on(Events::TurnStart) { @turn_id += 1 }
         @created_at = Time.now
         @_no_tools_instructed = false
 
@@ -65,6 +73,18 @@ module Ask
         end
         @memory_learning = !!memory_learning
 
+        # Large-output offloading: tool results above a size threshold are
+        # stored in a ToolOutputStore (state adapter when present, else
+        # in-process) and the transcript keeps a preview + reference.
+        @offload_threshold = case offload_large_outputs
+        when true then 4000
+        when Integer then offload_large_outputs
+        else nil
+        end
+        @output_store = if @offload_threshold
+          ToolOutputStore.new(state: state || persistence || Ask::State::Memory.new)
+        end
+
         # Plan mode — research phase gated to read-only tools until a human
         # approves the model's plan (submitted via the exit_plan_mode tool).
         @plan_mode = plan_mode.is_a?(Hash) ? true : !!plan_mode
@@ -81,7 +101,12 @@ module Ask
         @tools = resolve_tools(tools)
         @chat = build_chat(model, system_prompt, @tools, **chat_options)
         @loop = Loop.new(max_turns: max_turns)
-        @tool_executor = ToolExecutor.new(max_retries: max_tool_retries, parallel: parallel_tools)
+        @tool_executor = ToolExecutor.new(
+          max_retries: max_tool_retries,
+          parallel: parallel_tools,
+          output_offload_threshold: @offload_threshold,
+          output_store: @output_store
+        )
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
         @audit_log = build_audit_log(audit_log)
@@ -151,6 +176,9 @@ module Ask
       # @return [Ask::Agent::Memory, nil] durable memory (only when passed
       #   via the +memory:+ option)
       attr_reader :memory
+      # @return [Ask::Agent::ToolOutputStore, nil] store for offloaded large
+      #   tool outputs (only when large-output offloading is enabled)
+      attr_reader :output_store
 
       def run(message, tools: nil, reset: true)
         raise "Session deleted" if @deleted
@@ -176,6 +204,10 @@ module Ask
           @_no_tools_instructed = true
         end
 
+        # Leftover queued steers from a previous run become user messages
+        # before this run starts.
+        drain_leftover_steers
+
         begin
           @tool_executor.telemetry = @telemetry
 
@@ -189,6 +221,7 @@ module Ask
 	            event_emitter: self,
 	            session_id: @id,
             tool_call_repair: @tool_call_repair,
+            steer_source: method(:drain_one_steer),
 	            persist: @state ? method(:persist!) : nil
 	          )
 
@@ -407,6 +440,7 @@ module Ask
       def delete
         @deleted = true
         @checkpoint_store&.delete(@id)
+        @output_store&.delete(@id)
         @state&.delete(@id)
       end
 
@@ -495,6 +529,20 @@ module Ask
 
       # --- Plan mode ---
 
+      # Pop the next queued steer (called by the loop at each turn
+      # boundary); returns "" when nothing is queued.
+      def drain_one_steer
+        @steer_mutex.synchronize { @queued_steers.shift }.to_s
+      end
+
+      # Move any queued steers left over from a previous run into the
+      # conversation (the session was idle, so they are dispatched now).
+      def drain_leftover_steers
+        while (message = drain_one_steer) != ""
+          @chat.add_message(role: :user, content: message)
+        end
+      end
+
       # Extract durable facts from this session's transcript into memory
       # (memory_learning: true). Best-effort — extraction never breaks the
       # session; failures are swallowed.
@@ -560,6 +608,45 @@ module Ask
         )
       end
 
+      # --- Steer (concurrency-safe message injection) ---
+
+      # @return [Integer] id of the turn currently running (or the last
+      #   completed turn when idle)
+      attr_reader :turn_id
+
+      # Inject a message into the session safely, from any thread (web, CLI,
+      # another agent):
+      #
+      # - **:stale** — the caller's `expected_turn_id` does not match the
+      #   current turn id (the caller was looking at an older state).
+      # - **:queued** — a turn is running; the message is held and dispatched
+      #   as the next user message at the next turn boundary.
+      # - **:steered** — the session is idle; the message is added to the
+      #   conversation and processed by the next run.
+      #
+      # @param message [String]
+      # @param expected_turn_id [Integer, nil] the turn id the caller
+      #   believes is current; nil skips the check
+      # @return [Hash] {status: :stale|:queued|:steered, turn_id: Integer}
+      def steer(message, expected_turn_id: nil)
+        @steer_mutex.synchronize do
+          if expected_turn_id && expected_turn_id != @turn_id
+            return { status: :stale, turn_id: @turn_id }
+          end
+          if @running
+            @queued_steers << message.to_s
+            return { status: :queued, turn_id: @turn_id }
+          end
+        end
+        @chat.add_message(role: :user, content: message.to_s)
+        { status: :steered, turn_id: @turn_id }
+      end
+
+      # @return [Integer] steers queued and not yet dispatched
+      def queued_steers
+        @steer_mutex.synchronize { @queued_steers.size }
+      end
+
       # --- Async (pending) tools ---
 
       # Registers a pending tool call (called by the loop when a tool
@@ -772,6 +859,9 @@ module Ask
           resolved << MemoryWrite.new(memory: @memory, session_id: @id) unless resolved.any? { |t| t.name == "memory_write" }
           resolved << MemorySearch.new(memory: @memory) unless resolved.any? { |t| t.name == "memory_search" }
         end
+        if @output_store
+          resolved << OutputRead.new(store: @output_store, session_id: @id) unless resolved.any? { |t| t.name == "output_read" }
+        end
         resolved
       end
 
@@ -870,7 +960,17 @@ module Ask
           }
         }
         @state.set(@id, payload)
-        @checkpoint_store.checkpoint(@id, payload) if @checkpoints
+        # Checkpoint only when the conversation actually changed since the
+        # last one: the loop persists after every turn and run() persists
+        # again on the way out, so without this check every run would append
+        # a duplicate tail checkpoint.
+        if @checkpoints
+          head = @checkpoint_store.load(@id)
+          head_messages = head ? (head["messages"] || head[:messages] || []) : []
+          head_turn = head ? (head.dig("metadata", "turn_count") || head.dig(:metadata, :turn_count)) : nil
+          unchanged = head_messages.size == payload[:messages].size && head_turn == @turn_count
+          @checkpoint_store.checkpoint(@id, payload) unless unchanged
+        end
       end
 
       def try_auto_meta_agent

data/lib/ask/agent/tool_executor.rb

@@ -11,10 +11,12 @@ module Ask
 
       attr_reader :total_executions
 
-      def initialize(max_retries: 3, parallel: true)
+      def initialize(max_retries: 3, parallel: true, output_offload_threshold: nil, output_store: nil)
         @max_retries = max_retries
         @parallel = parallel
         @total_executions = 0
+        @output_offload_threshold = output_offload_threshold
+        @output_store = output_store
       end
 
       attr_writer :telemetry
@@ -185,6 +187,15 @@ module Ask
           result[:result].to_s
         end
 
+        # Large outputs never enter the transcript: store the full message
+        # and keep a short preview plus a reference the model can retrieve
+        # with the output_read tool. output_read's own result is exempt —
+        # its contract is to bring the full output into context on demand.
+        if @output_offload_threshold && message.length > @output_offload_threshold &&
+           tool_call.name != "output_read"
+          message = offload_message(message, tool_call.id)
+        end
+
         inner = result[:result]
         status = if result[:is_error] == true
           "error"
@@ -236,6 +247,15 @@ module Ask
         { result: e.message, is_error: true, error: e.class.name }
       end
 
+      # Store a large tool message in the output store and return a short
+      # preview that references it, so the transcript never carries the full
+      # output.
+      def offload_message(message, tool_call_id)
+        @output_store.store(@session_id, tool_call_id, message)
+        preview = message[0, 300]
+        "#{preview}\n...(output truncated: #{message.length} chars — full output via output_read id: \"#{tool_call_id}\")"
+      end
+
       def retryable_error_name?(error_name)
         return false unless error_name
 

data/lib/ask/agent/tool_output_store.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    # State-backed storage for large tool outputs, keeping them out of the
+    # conversation transcript.
+    #
+    # When a tool result exceeds the session's offload threshold, the
+    # executor stores the full output here and the transcript keeps a short
+    # preview plus a reference the model can retrieve with the output_read
+    # tool (and the web UI can fetch from the same store).
+    #
+    # Storage shape (pure KV — works with every Ask::State::Adapter backend
+    # including custom get/set/delete adapters):
+    #   output:<session_id>:<call_id>   — one key per offloaded output
+    #   output:<session_id>:index       — JSON array of call ids (write order)
+    #
+    #   store = Ask::Agent::ToolOutputStore.new(state: adapter)
+    #   store.store(session_id, "call_1", huge_output)
+    #   store.fetch(session_id, "call_1")   # => huge_output
+    #   store.delete(session_id)            # session cleanup
+    class ToolOutputStore
+      KEY_PREFIX = "output:"
+      INDEX_SUFFIX = ":index"
+
+      # @param state [Ask::State::Adapter] backing store
+      # @param max_size [Integer] stored outputs are truncated to this many
+      #   characters (with a truncation marker)
+      def initialize(state:, max_size: 50_000)
+        @state = state
+        @max_size = max_size
+        @mutex = Monitor.new
+      end
+
+      # @return [Ask::State::Adapter] the underlying adapter
+      attr_reader :state
+
+      # Store an output for a tool call (idempotent per call id — a later
+      # store with the same call id replaces the earlier one).
+      #
+      # @param session_id [String]
+      # @param call_id [String]
+      # @param content [String]
+      # @return [String] the stored content (possibly truncated)
+      def store(session_id, call_id, content)
+        stored = content.to_s
+        stored = "#{stored[0, @max_size]}\n...(output truncated)" if stored.length > @max_size
+
+        @mutex.synchronize do
+          @state.set(entry_key(session_id, call_id), stored)
+          index = load_index(session_id)
+          @state.set(index_key(session_id), (index + [call_id]).uniq.to_json)
+        end
+        stored
+      end
+
+      # @param session_id [String]
+      # @param call_id [String]
+      # @return [String, nil] the stored output, or nil when absent
+      def fetch(session_id, call_id)
+        @state.get(entry_key(session_id, call_id))
+      end
+
+      # Remove every output for a session (called by Session#delete).
+      #
+      # @param session_id [String]
+      # @return [void]
+      def delete(session_id)
+        @mutex.synchronize do
+          load_index(session_id).each { |call_id| @state.delete(entry_key(session_id, call_id)) }
+          @state.delete(index_key(session_id))
+        end
+        nil
+      end
+
+      private
+
+      def load_index(session_id)
+        raw = @state.get(index_key(session_id))
+        raw ? JSON.parse(raw) : []
+      end
+
+      def entry_key(session_id, call_id)
+        "#{KEY_PREFIX}#{session_id}:#{call_id}"
+      end
+
+      def index_key(session_id)
+        "#{KEY_PREFIX}#{session_id}#{INDEX_SUFFIX}"
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.35.0"
+    VERSION = "0.37.0"
   end
 end

data/lib/ask/agent.rb

@@ -47,6 +47,8 @@ module Ask
     autoload :MemoryWrite, "ask/agent/memory_write"
     autoload :MemorySearch, "ask/agent/memory_search"
     autoload :MemoryExtractor, "ask/agent/memory_extractor"
+    autoload :ToolOutputStore, "ask/agent/tool_output_store"
+    autoload :OutputRead, "ask/agent/output_read"
 
     module Middleware
       autoload :Base, "ask/agent/middleware/base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -189,6 +189,7 @@ files:
 - lib/ask/agent/middleware/model_fallback.rb
 - lib/ask/agent/middleware/pipeline.rb
 - lib/ask/agent/middleware/retry_on_failure.rb
+- lib/ask/agent/output_read.rb
 - lib/ask/agent/persistence/base.rb
 - lib/ask/agent/persistence/in_memory.rb
 - lib/ask/agent/policies/approval_policy.rb
@@ -215,6 +216,7 @@ files:
 - lib/ask/agent/tool_abort_controller.rb
 - lib/ask/agent/tool_call_repair.rb
 - lib/ask/agent/tool_executor.rb
+- lib/ask/agent/tool_output_store.rb
 - lib/ask/agent/version.rb
 homepage: https://github.com/ask-rb/ask-agent
 licenses: