ask-agent 0.37.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e22262139bd8142b9e45f22e831d59360f9465aad8fea93247352591b742d6c3
-  data.tar.gz: 1486719187105e25f794bff150fd9aa59e902096a40c15fdb822b2e7061d9bac
+  metadata.gz: e2b75f968977ca6b41df200a5dbba36cc73d799bc74e91ad3a201a3b9a2c78e7
+  data.tar.gz: 19fe24495b1f70b44a320c98b77ee8c2fdf9d83a5642e4bf58c071f8e16ec45c
 SHA512:
-  metadata.gz: 2eaacd8c0a7a32392546ccde9d218d271afa22a3a2d1c154bfc3665691060b9cc4e7ab8d658c25eb2b2e79cccb1ad3bbbf10cd65e36c4324e2fc408f8eb8d973
-  data.tar.gz: d9abb9f16f260d5ece0c403346ae0f1cb5a9edadb3e9fad0a2a56fd05c66748eb0070f16efa8441aa55275c5fc1aff724d43f0d4d6809751b932978272563fcf
+  metadata.gz: 5c9057c8b69cbe470beb46d9c656bf56ea15abf1d5328a93bc1a66cbef9c8f69f77aa0cfeb9f64cce264c60278f4df0c9290e3d89b71c42816ff2755d91b3e5e
+  data.tar.gz: 6df2b868b1430e00c9f2fab030ab48b1128de64b23a29b22f9c70963b977c777e20aaf75d5da529f772998116c453763b935ca92d4495efa21bd04efe309caf4

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/chat.rb

@@ -53,8 +53,9 @@ module Ask
         @prompt_caching = prompt_caching.nil? ? config.prompt_caching : prompt_caching
       end
 
-      def ask(message = nil, &block)
-        @messages << Ask::Message.new(role: :user, content: message.to_s) if message
+      def ask(message = nil, attachments: nil, &block)
+        validate_attachment_modalities!(attachments)
+        @messages << Ask::Message.new(role: :user, content: merge_attachments(message, attachments)) if message || attachments
 
         stream = block_given?
         tool_defs = @tools.map { |t| Ask::ToolDef.from_tool(t) }
@@ -79,10 +80,11 @@ module Ask
         response_msg
       end
 
-      def add_message(role:, content: nil, tool_call_id: nil, tool_calls: nil)
+      def add_message(role:, content: nil, tool_call_id: nil, tool_calls: nil, attachments: nil)
+        validate_attachment_modalities!(attachments) if role == :user
         @messages << Ask::Message.new(
           role: role,
-          content: content,
+          content: merge_attachments(content, attachments),
           tool_call_id: tool_call_id,
           tool_calls: tool_calls
         )
@@ -112,6 +114,42 @@ module Ask
 
       MAX_CHAT_RETRIES = 3
 
+      # Merge attachments into message content as content blocks: a plain
+      # string becomes a Text block followed by the attachment blocks;
+      # Array content has the blocks appended. Returns the content
+      # unchanged when there are no attachments.
+      def merge_attachments(content, attachments)
+        return content if attachments.nil? || attachments.empty?
+
+        blocks = content.is_a?(Array) ? content.dup : (content ? [Ask::Content::Text.new(content.to_s)] : [])
+        Ask::Attachment.wrap_all(attachments).each do |item|
+          blocks << (item.is_a?(Ask::Attachment) ? item.to_content : item)
+        end
+        blocks
+      end
+
+      # :inline attachments must be within the model's input modalities.
+      # :context attachments are plain text (a manifest line) and always
+      # supported. The check is skipped when the catalog has no modality
+      # info for the model.
+      def validate_attachment_modalities!(attachments)
+        return if attachments.nil? || attachments.empty?
+
+        inline = Ask::Attachment.wrap_all(attachments).select { |a| a.is_a?(Ask::Attachment) && a.inline? }
+        return if inline.empty?
+
+        modalities = @model_info.respond_to?(:modalities) ? @model_info.modalities : nil
+        supported = modalities.is_a?(Hash) ? Array(modalities[:input] || modalities["input"]) : []
+        return if supported.empty? || supported.include?("*")
+
+        unsupported = inline.reject { |a| supported.include?(a.type.to_s) }
+        return if unsupported.empty?
+
+        raise Ask::Agent::UnsupportedAttachmentError,
+          "Model #{@model_id} cannot receive #{unsupported.map(&:type).uniq.join(', ')} attachments " \
+          "(supported input modalities: #{supported.join(', ')})"
+      end
+
       def provider
         @test_provider || @provider ||= build_provider
       end

data/lib/ask/agent/loop.rb

@@ -17,12 +17,12 @@ 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, steer_source: 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, attachments: nil)
         raise MaxTurnsExceeded if @turn_count >= @max_turns
 
         event_emitter.emit(Events::TurnStart.new)
 
-        response = chat.ask(message) do |chunk|
+        response = chat.ask(message, attachments: attachments) do |chunk|
           if chunk.content.to_s.strip.length > 0
             event_emitter.emit(Events::TextDelta.new(content: chunk.content))
           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,8 +192,11 @@ 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)
+      def run(message, tools: nil, reset: true, attachments: nil)
         raise "Session deleted" if @deleted
         raise "Session already running" if @running
 
@@ -214,6 +230,7 @@ module Ask
 	          response = @loop.run_turn(
 	            chat: @chat,
 	            message: message,
+	            attachments: attachments,
 	            tools: active_tools,
 	            tool_executor: @tool_executor,
 	            compactor: @compactor,
@@ -427,7 +444,7 @@ module Ask
         data[:messages].each do |msg|
           session.chat.add_message(
             role: msg[:role].to_sym,
-            content: msg[:content],
+            content: deserialize_content(msg[:content]),
             tool_call_id: msg[:tool_call_id]
           )
         end
@@ -441,6 +458,7 @@ module Ask
         @deleted = true
         @checkpoint_store&.delete(@id)
         @output_store&.delete(@id)
+        @artifact_store&.delete(@id)
         @state&.delete(@id)
       end
 
@@ -527,6 +545,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
@@ -627,8 +663,11 @@ module Ask
       # @param message [String]
       # @param expected_turn_id [Integer, nil] the turn id the caller
       #   believes is current; nil skips the check
+      # @param attachments [Array<Ask::Attachment>, nil] files to attach
+      #   (applied when the session is idle; queued steers keep the
+      #   message text only — the loop resolves queued messages as text)
       # @return [Hash] {status: :stale|:queued|:steered, turn_id: Integer}
-      def steer(message, expected_turn_id: nil)
+      def steer(message, expected_turn_id: nil, attachments: nil)
         @steer_mutex.synchronize do
           if expected_turn_id && expected_turn_id != @turn_id
             return { status: :stale, turn_id: @turn_id }
@@ -638,7 +677,7 @@ module Ask
             return { status: :queued, turn_id: @turn_id }
           end
         end
-        @chat.add_message(role: :user, content: message.to_s)
+        @chat.add_message(role: :user, content: message.to_s, attachments: attachments)
         { status: :steered, turn_id: @turn_id }
       end
 
@@ -884,6 +923,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
@@ -920,7 +963,7 @@ module Ask
         data[:messages].each do |msg|
           target.chat.add_message(
             role: msg[:role].to_sym,
-            content: msg[:content],
+            content: self.class.deserialize_content(msg[:content]),
             tool_call_id: msg[:tool_call_id]
           )
         end
@@ -938,13 +981,26 @@ module Ask
         @tools.reject { |t| t.is_a?(Ask::Skills::LoadSkillTool) }
       end
 
+      # Persist content blocks as their +to_h+ hashes so attachments
+      # survive save/load; plain messages stay strings.
+      def self.serialize_content(message)
+        message.content_blocks ? message.content_blocks.map(&:to_h) : message.content.to_s
+      end
+
+      # Rebuild message content from a persisted value: block hashes are
+      # reconstructed via Ask::Content.from_h (deep_symbolize_keys may have
+      # symbol keys — from_h normalizes).
+      def self.deserialize_content(content)
+        content.is_a?(Array) ? content.map { |block| Ask::Content.from_h(block) } : content
+      end
+
       def persist!
         payload = {
           id: @id,
           messages: @chat.messages.map { |m|
             {
               role: m.role,
-              content: m.content.to_s,
+              content: self.class.serialize_content(m),
               tool_call_id: m.tool_call_id,
               created_at: Time.now.iso8601
             }

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.39.0"
   end
 end

data/lib/ask/agent.rb

@@ -18,6 +18,7 @@ module Ask
     class ToolExecutionError < Error; end
     class CompactionFailed < Error; end
     class SessionNotPersisted < Error; end
+    class UnsupportedAttachmentError < Error; end
 
     class UnknownAgent < Error; end
 
@@ -49,6 +50,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.39.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