ask-agent 0.35.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2040f37b4e9b023374eb6169abd1f1c28fdda335a8032254a15b0d813a7cd0c9
-  data.tar.gz: 7212cbd265d8b054423cfad5ed76717eb36f1ff980c2a394cba9b0b4c256c3e9
+  metadata.gz: fcbe9fc4bae7e7eddc9fc206e35ef22499a9fb3a308bac6d9f48c2d1d2e12f8f
+  data.tar.gz: ae9c72d61a839330d2bbc68b8049fe1e54680f0462d4dee2e886d8377df439b3
 SHA512:
-  metadata.gz: 1cb0c3e65bd08e9c45f93bdc378149810d7c31594f63cf69799e128b9f32496f3e71ca521cbe43d6729a9d39210bce0469a7eb6686336a45f2677fc473053cad
-  data.tar.gz: 2b6d47cfb37af4c3a2d850a551621af6d44542dd88f9483a695cfcd83b58f2bb893a7403ac91b3a01f3659936ad8f4df5c8d7cc8eb7656c22e6587db0bba0081
+  metadata.gz: 7a34904c0d8c0d6397753262d4f3c359674893b5ddab7a85714f8eebf797db0cdd3b6a076ea2c18eb693ad1f2211677e88bf4f4a7f4e2e2f7fe5545892af5062
+  data.tar.gz: d78f87319a5d6b63c22e1bd7d9cacde6fd6306131f746ad5b4166d509acf5dad11b03db7e9fab6f908db752f7a592f2a4dc51fdb13fb4fa30ebc39c193894acb

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [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

@@ -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

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
@@ -65,6 +66,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 +94,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 +169,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
@@ -407,6 +428,7 @@ module Ask
       def delete
         @deleted = true
         @checkpoint_store&.delete(@id)
+        @output_store&.delete(@id)
         @state&.delete(@id)
       end
 
@@ -772,6 +794,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
 

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.36.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.36.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: