ask-agent 0.37.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e22262139bd8142b9e45f22e831d59360f9465aad8fea93247352591b742d6c3
-  data.tar.gz: 1486719187105e25f794bff150fd9aa59e902096a40c15fdb822b2e7061d9bac
+  metadata.gz: f3486ed15f739d216a4b0dd46e8efdb29cc6cc7689a70ea4a2a6ef5477444037
+  data.tar.gz: 628f14e1905695cf814eb3ff49012f924d30ce13c92c25ef425ec695dc37502f
 SHA512:
-  metadata.gz: 2eaacd8c0a7a32392546ccde9d218d271afa22a3a2d1c154bfc3665691060b9cc4e7ab8d658c25eb2b2e79cccb1ad3bbbf10cd65e36c4324e2fc408f8eb8d973
-  data.tar.gz: d9abb9f16f260d5ece0c403346ae0f1cb5a9edadb3e9fad0a2a56fd05c66748eb0070f16efa8441aa55275c5fc1aff724d43f0d4d6809751b932978272563fcf
+  metadata.gz: 7cd3f07a7dbcaa19379815eb1999f225bef3baa938ab34e018c0d1c0d755edbd5e78ba67881f65098e4b3a59b2f6696e75e1a6bfa2bba3ba17c9cb151918c9ae
+  data.tar.gz: 8644f8522aa5ea4719bb6e02d6dc19ce85d66f2e5e53765da02fcb8a002c67540f60ce31f787abb091a4e76b80a83fdb82d538b2866506385fa8c66e94f54d4a

data/CHANGELOG.md

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

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/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
@@ -85,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
@@ -105,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)
@@ -179,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
@@ -441,6 +457,7 @@ module Ask
         @deleted = true
         @checkpoint_store&.delete(@id)
         @output_store&.delete(@id)
+        @artifact_store&.delete(@id)
         @state&.delete(@id)
       end
 
@@ -527,6 +544,24 @@ 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
@@ -884,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

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.37.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.37.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