ask-agent 0.36.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcbe9fc4bae7e7eddc9fc206e35ef22499a9fb3a308bac6d9f48c2d1d2e12f8f
-  data.tar.gz: ae9c72d61a839330d2bbc68b8049fe1e54680f0462d4dee2e886d8377df439b3
+  metadata.gz: f3486ed15f739d216a4b0dd46e8efdb29cc6cc7689a70ea4a2a6ef5477444037
+  data.tar.gz: 628f14e1905695cf814eb3ff49012f924d30ce13c92c25ef425ec695dc37502f
 SHA512:
-  metadata.gz: 7a34904c0d8c0d6397753262d4f3c359674893b5ddab7a85714f8eebf797db0cdd3b6a076ea2c18eb693ad1f2211677e88bf4f4a7f4e2e2f7fe5545892af5062
-  data.tar.gz: d78f87319a5d6b63c22e1bd7d9cacde6fd6306131f746ad5b4166d509acf5dad11b03db7e9fab6f908db752f7a592f2a4dc51fdb13fb4fa30ebc39c193894acb
+  metadata.gz: 7cd3f07a7dbcaa19379815eb1999f225bef3baa938ab34e018c0d1c0d755edbd5e78ba67881f65098e4b3a59b2f6696e75e1a6bfa2bba3ba17c9cb151918c9ae
+  data.tar.gz: 8644f8522aa5ea4719bb6e02d6dc19ce85d66f2e5e53765da02fcb8a002c67540f60ce31f787abb091a4e76b80a83fdb82d538b2866506385fa8c66e94f54d4a

data/CHANGELOG.md

@@ -1,3 +1,53 @@
+## [0.38.0] — 2026-08-07
+
+### Added
+
+- **Artifacts — tool deliverables with a web-friendly home.**
+  `Session.new(artifacts: true)` collects tool-produced files into an
+  `Ask::Agent::ArtifactStore` on the same state adapter as sessions and
+  checkpoints:
+  - Tools attach `metadata: { artifact: { filename:, mime_type:, content: | uri: } }`
+    to their result. **Inline content** (small text: reports, CSVs,
+    patches) is stored in the state store; **external URIs** (large or
+    binary files) are stored as references with metadata only.
+  - `Session#artifacts` lists them (newest first, no content payload);
+    `Session#fetch_artifact(id)` retrieves the full record. `Session#delete`
+    cleans up.
+  - **Uploader hook** — `Session.new(artifacts: true, artifact_uploader:
+    ->(content:, filename:, mime_type:) { uri })` lifts inline content to a
+    URI before storage, so apps that prefer object storage never grow the
+    database: tools return content, the session uploads, the store keeps
+    the reference.
+  - Malformed artifacts never fail the tool — the message notes
+    `[artifact not stored: ...]` instead.
+
+## [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

data/lib/ask/agent/artifact_store.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module Ask
+  module Agent
+    # Session-scoped storage for tool-produced deliverables ("artifacts").
+    #
+    # Artifacts come in two kinds, chosen by the producing tool:
+    #
+    # - **content** — small text deliverables (reports, CSVs, patches,
+    #   generated code) stored inline in the state store.
+    # - **uri** — large or binary deliverables stored externally (object
+    #   storage, a file service); the store keeps the reference and
+    #   metadata only.
+    #
+    # Metadata always lives in the state store (pure KV, same adapter as
+    # sessions/checkpoints/memory — works with every backend and with the
+    # in-process Memory fallback):
+    #   artifact:<session_id>:<artifact_id>   — one key per artifact
+    #   artifact:<session_id>:index           — JSON array of ids
+    #
+    # An optional +uploader+ callback lifts inline content to a URI before
+    # storage (e.g. upload to S3), so apps that prefer object storage never
+    # grow the database: the tool returns content, the session uploads, the
+    # store keeps the reference.
+    class ArtifactStore
+      KEY_PREFIX = "artifact:"
+      INDEX_SUFFIX = ":index"
+
+      # @param state [Ask::State::Adapter] backing store
+      # @param max_content_size [Integer] inline content cap (chars)
+      # @param uploader [Proc, nil] called with (content:, filename:,
+      #   mime_type:) when a tool provides inline content; must return a URI
+      #   string. When set, inline content is uploaded and the URI stored.
+      def initialize(state:, max_content_size: 100_000, uploader: nil)
+        @state = state
+        @max_content_size = max_content_size
+        @uploader = uploader
+        @mutex = Monitor.new
+      end
+
+      # @return [Ask::State::Adapter] the underlying adapter
+      attr_reader :state
+
+      # @return [Proc, nil] the uploader callback, if any
+      attr_reader :uploader
+
+      # Store an artifact for a session.
+      #
+      # @param session_id [String]
+      # @param filename [String] required
+      # @param mime_type [String, nil]
+      # @param content [String, nil] inline content (small text); xor +uri+
+      # @param uri [String, nil] external reference (large/binary); xor
+      #   +content+
+      # @return [Hash] the stored record {id:, filename:, mime_type:, size:,
+      #   created_at:, content: | uri:}
+      # @raise [ArgumentError] on invalid input
+      def store(session_id, filename:, mime_type: nil, content: nil, uri: nil)
+        raise ArgumentError, "filename is required" if filename.to_s.strip.empty?
+        raise ArgumentError, "pass either content: or uri:, not both" if content && uri
+        raise ArgumentError, "pass either content: or uri:" unless content || uri
+
+        if content
+          content = content.to_s
+          if content.length > @max_content_size
+            raise ArgumentError, "content exceeds #{@max_content_size} chars; use uri: for large artifacts"
+          end
+          if @uploader
+            uri = @uploader.call(content: content, filename: filename.to_s, mime_type: mime_type)
+            content = nil
+          end
+        end
+
+        id = SecureRandom.uuid
+        record = {
+          id: id,
+          filename: filename.to_s,
+          mime_type: mime_type,
+          size: content ? content.length : nil,
+          created_at: Time.now.iso8601
+        }
+        record[:content] = content if content
+        record[:uri] = uri if uri
+
+        @mutex.synchronize do
+          @state.set(entry_key(session_id, id), record)
+          @state.set(index_key(session_id), (load_index(session_id) + [id]).to_json)
+        end
+        record
+      end
+
+      # @param session_id [String]
+      # @return [Array<Hash>] artifact summaries (id, filename, mime_type,
+      #   size, uri) newest first — content is not included
+      def list(session_id)
+        load_index(session_id)
+          .filter_map { |id| fetch(session_id, id) }
+          .reverse
+          .map { |r| r.slice(:id, :filename, :mime_type, :size, :uri) }
+      end
+
+      # @param session_id [String]
+      # @param id [String]
+      # @return [Hash, nil] the full record (content or uri)
+      def fetch(session_id, id)
+        data = @state.get(entry_key(session_id, id))
+        return nil unless data
+
+        symbolize(data)
+      end
+
+      # Remove every artifact 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 { |id| @state.delete(entry_key(session_id, 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, id)
+        "#{KEY_PREFIX}#{session_id}:#{id}"
+      end
+
+      def index_key(session_id)
+        "#{KEY_PREFIX}#{session_id}#{INDEX_SUFFIX}"
+      end
+
+      def symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize(v) }
+        when Array
+          obj.map { |e| symbolize(e) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

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)
@@ -157,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,
@@ -168,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/session.rb

@@ -26,6 +26,7 @@ module Ask
                      tool_call_repair: nil, checkpoints: false,
                      todos: false, plan_mode: false, memory: nil,
                      memory_learning: false, offload_large_outputs: false,
+                     artifacts: false, artifact_uploader: nil,
                      **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
@@ -41,6 +42,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
 
@@ -78,6 +86,17 @@ module Ask
           ToolOutputStore.new(state: state || persistence || Ask::State::Memory.new)
         end
 
+        # Tool deliverables (artifacts): metadata[:artifact] on tool results
+        # is collected into the store — inline content for small text,
+        # external URIs for large binaries (uploader lifts content to a URI
+        # when provided).
+        @artifact_store = if artifacts
+          ArtifactStore.new(
+            state: state || persistence || Ask::State::Memory.new,
+            uploader: artifact_uploader
+          )
+        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
@@ -98,7 +117,8 @@ module Ask
           max_retries: max_tool_retries,
           parallel: parallel_tools,
           output_offload_threshold: @offload_threshold,
-          output_store: @output_store
+          output_store: @output_store,
+          artifact_store: @artifact_store
         )
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
@@ -172,6 +192,9 @@ module Ask
       # @return [Ask::Agent::ToolOutputStore, nil] store for offloaded large
       #   tool outputs (only when large-output offloading is enabled)
       attr_reader :output_store
+      # @return [Ask::Agent::ArtifactStore, nil] store for tool deliverables
+      #   (only when the +artifacts:+ option is enabled)
+      attr_reader :artifact_store
 
       def run(message, tools: nil, reset: true)
         raise "Session deleted" if @deleted
@@ -197,6 +220,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
 
@@ -210,6 +237,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
 	          )
 
@@ -429,6 +457,7 @@ module Ask
         @deleted = true
         @checkpoint_store&.delete(@id)
         @output_store&.delete(@id)
+        @artifact_store&.delete(@id)
         @state&.delete(@id)
       end
 
@@ -515,8 +544,40 @@ module Ask
         forked
       end
 
+# --- Artifacts (tool deliverables) ---
+
+# @return [Array<Hash>] artifact summaries for this session (id,
+#   filename, mime_type, size, uri), newest first
+# @raise [RuntimeError] when artifacts are not enabled
+def artifacts
+  require_artifacts!
+  @artifact_store.list(@id)
+end
+
+# @param id [String] artifact id
+# @return [Hash, nil] the full record (content or uri)
+# @raise [RuntimeError] when artifacts are not enabled
+def fetch_artifact(id)
+  require_artifacts!
+  @artifact_store.fetch(@id, id)
+end
+
       # --- 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.
@@ -582,6 +643,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
@@ -819,6 +919,10 @@ module Ask
         compactor
       end
 
+      def require_artifacts!
+        raise "artifacts are not enabled (pass artifacts: true)" unless @artifact_store
+      end
+
       def require_checkpoints!
         raise "checkpointing is not enabled (pass state: and checkpoints: true)" unless @checkpoints
       end
@@ -895,7 +999,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,12 +11,13 @@ module Ask
 
       attr_reader :total_executions
 
-      def initialize(max_retries: 3, parallel: true, output_offload_threshold: nil, output_store: nil)
+      def initialize(max_retries: 3, parallel: true, output_offload_threshold: nil, output_store: nil, artifact_store: nil)
         @max_retries = max_retries
         @parallel = parallel
         @total_executions = 0
         @output_offload_threshold = output_offload_threshold
         @output_store = output_store
+        @artifact_store = artifact_store
       end
 
       attr_writer :telemetry
@@ -196,6 +197,19 @@ module Ask
           message = offload_message(message, tool_call.id)
         end
 
+        # Collect tool-produced deliverables (metadata[:artifact]) into the
+        # session's artifact store. Best-effort: a malformed artifact is
+        # noted in the message, never a tool failure.
+        if @artifact_store && result[:result].respond_to?(:metadata) &&
+           (artifact = result[:result].metadata[:artifact])
+          begin
+            attrs = symbolize_artifact(artifact)
+            @artifact_store.store(@session_id, **attrs)
+          rescue ArgumentError => e
+            message += "\n[artifact not stored: #{e.message}]"
+          end
+        end
+
         inner = result[:result]
         status = if result[:is_error] == true
           "error"
@@ -256,6 +270,17 @@ module Ask
         "#{preview}\n...(output truncated: #{message.length} chars — full output via output_read id: \"#{tool_call_id}\")"
       end
 
+      # Normalize an artifact hash from tool metadata (accepts string keys)
+      # to the store's keyword contract.
+      def symbolize_artifact(artifact)
+        {
+          filename: artifact[:filename] || artifact["filename"],
+          mime_type: artifact[:mime_type] || artifact["mime_type"],
+          content: artifact[:content] || artifact["content"],
+          uri: artifact[:uri] || artifact["uri"]
+        }
+      end
+
       def retryable_error_name?(error_name)
         return false unless error_name
 

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.36.0"
+    VERSION = "0.38.0"
   end
 end

data/lib/ask/agent.rb

@@ -49,6 +49,7 @@ module Ask
     autoload :MemoryExtractor, "ask/agent/memory_extractor"
     autoload :ToolOutputStore, "ask/agent/tool_output_store"
     autoload :OutputRead, "ask/agent/output_read"
+    autoload :ArtifactStore, "ask/agent/artifact_store"
 
     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.36.0
+  version: 0.38.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -165,6 +165,7 @@ files:
 - lib/ask-agent.rb
 - lib/ask/agent.rb
 - lib/ask/agent/approval_queue.rb
+- lib/ask/agent/artifact_store.rb
 - lib/ask/agent/chat.rb
 - lib/ask/agent/checkpoint_store.rb
 - lib/ask/agent/cli.rb