smith-agents 0.10.0 → 0.12.0

data/lib/smith/budget/host_ledger.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "amount"
+
+module Smith
+  module Budget
+    # The protocol of a host's budget ledger (a workflow's `budget_ledger`),
+    # and how Smith calls it.
+    #
+    # `reserve!(amount, key:, expires_at:)` admits a provider request's hold
+    # (a Budget::Amount) when it returns true, and refuses it otherwise.
+    # `reconcile!(key, amount)` records what the request spent, in place of
+    # its hold if it had one: a key may be reconciled that was never held
+    # (a later round of a tool loop, or a result that came for a hold that
+    # expired). `release!(key)` says it spent nothing. A hold not settled by
+    # `expires_at` (its process died during the request) counts for nothing
+    # after it; Smith runs no timer. A key may come again after a crash: a
+    # reserve of it replaces its hold, a release ends its hold, and its
+    # reconcile is final (a ledger records it once). Fan-out branches call
+    # the ledger from their own threads.
+    #
+    # A refusal raises BudgetUnavailable before the request is sent. An
+    # error from building the ledger or from `reserve!` becomes
+    # BudgetLedgerError (the hold, if `reserve!` took it, is released), as
+    # nothing was sent. An error from `reconcile!` or `release!` is logged
+    # by class and the step goes on: the money is spent, and a ledger that
+    # could not record it must not cost the answer.
+    module HostLedger
+      METHODS = %i[reserve! reconcile! release!].freeze
+      INHERITED = :smith_inherited_budget_ledger
+      SCOPE_STRING_BYTES = 256
+      private_constant :INHERITED, :SCOPE_STRING_BYTES
+
+      module_function
+
+      def check!(ledger)
+        return ledger if ledger.nil? || METHODS.all? { ledger.respond_to?(_1) }
+
+        raise WorkflowError, "a budget_ledger must respond to #{METHODS.join(", ")}"
+      end
+
+      # The run's ledger from its builder and the scope it was created with.
+      def build(builder, scope)
+        check!(builder.call(scope))
+      rescue WorkflowError
+        raise
+      rescue StandardError => e
+        raise BudgetLedgerError, "the budget ledger could not be built (#{e.class})"
+      end
+
+      # Admits the hold until `seconds` (Smith.config.budget_hold_ttl, plus a
+      # batch's wait) from now.
+      def admit!(ledger, amount, key, seconds: Smith.config.budget_hold_ttl)
+        raise BudgetUnavailable unless ledger.reserve!(amount, key:, expires_at: Time.now.utc + seconds) == true
+      rescue BudgetUnavailable
+        raise
+      rescue StandardError => e
+        settle(ledger, key, nil)
+        raise BudgetLedgerError, "the budget ledger could not reserve (#{e.class})"
+      end
+
+      def settle(ledger, key, amount)
+        amount ? ledger.reconcile!(key, amount) : ledger.release!(key)
+      rescue StandardError => e
+        Smith.config.logger&.error("Smith budget ledger #{amount ? "reconcile!" : "release!"} error: #{e.class}")
+        nil
+      end
+
+      # What a response's usage cost, as an Amount, priced as Smith prices
+      # usage; a count that is not a non-negative Integer counts as 0.
+      def amount(usage, model:, provider:, mode: :sync)
+        counts = [usage.input_tokens, usage.output_tokens, usage.cache_read_tokens, usage.cache_write_tokens]
+        input, output, reads, writes = counts.map { _1.is_a?(Integer) && _1.positive? ? _1 : 0 }
+        Amount.new(
+          input_tokens: input + reads + writes, output_tokens: output,
+          cost: Pricing.compute_cost(model:, provider:, input_tokens: input, output_tokens: output,
+                                     cache_read_tokens: reads, cache_write_tokens: writes, mode:)
+        )
+      end
+
+      # The scope a run's ledger is built from: the values its `keys` have in
+      # the run's trusted context when it is created, JSON scalars (a String
+      # of at most SCOPE_STRING_BYTES bytes), kept with the run so that what
+      # a step writes later never chooses another ledger.
+      def scope!(keys, context, untrusted)
+        keys.to_h do |key|
+          raise WorkflowError, "budget_ledger scope key #{key.inspect} is untrusted" if untrusted.include?(key)
+
+          [key, scope_value!(key, context.is_a?(Hash) ? context[key] : nil)]
+        end.freeze
+      end
+
+      # A stored scope, if it names the declared keys; nil (capture it
+      # again) if the declaration changed.
+      def stored_scope(keys, stored)
+        return unless stored.is_a?(Hash) && same_keys?(keys, stored)
+
+        stored = stored.transform_keys(&:to_s)
+        keys.to_h { |key| [key, scope_value!(key, stored[key.to_s])] }.freeze
+      rescue WorkflowError
+        raise SerializationError, "persisted workflow budget_ledger_scope is invalid"
+      end
+
+      def same_keys?(keys, stored) = stored.keys.map(&:to_s).sort == keys.map(&:to_s).sort
+
+      def scope_value!(key, value)
+        case value
+        when nil, true, false, Integer then value
+        when Float then value.finite? ? value : invalid_scope!(key)
+        when String then value.bytesize <= SCOPE_STRING_BYTES ? value.dup.freeze : invalid_scope!(key)
+        else invalid_scope!(key)
+        end
+      end
+
+      def invalid_scope!(key)
+        raise WorkflowError, "budget_ledger scope key #{key.inspect} must hold a JSON scalar " \
+                             "(a String of at most #{SCOPE_STRING_BYTES} bytes)"
+      end
+
+      # A nested workflow built in the block charges `source` (the enclosing
+      # run's ledger, as a callable) unless it names a ledger of its own.
+      def inheriting(source)
+        outer = Thread.current[INHERITED]
+        Thread.current[INHERITED] = source
+        yield
+      ensure
+        Thread.current[INHERITED] = outer
+      end
+
+      def take_inherited
+        source = Thread.current[INHERITED]
+        Thread.current[INHERITED] = nil
+        source
+      end
+    end
+  end
+end

data/lib/smith/budget/ledger.rb

@@ -58,12 +58,16 @@ module Smith
         @mutex.synchronize { release_reservation(token) }
       end
 
-      def remaining(key)
+      def remaining(key) = remaining_share(key, 1)
+
+      # One of parts equal shares of the remaining amount, taken from the exact
+      # internal value so that parts reservations of it always fit.
+      def remaining_share(key, parts)
         dimension = @amount_contract.dimension!(key)
         @amount_contract.known_dimension!(dimension)
         @mutex.synchronize do
           amount = @state_transition.remaining(@publication.state, dimension)
-          @representation.externalize_amount(dimension, amount)
+          @representation.externalize_remaining(dimension, amount, parts)
         end
       end
 
@@ -96,14 +100,14 @@ module Smith
         @representation.internalize(external)
       end
 
-      def create_reservation(amounts)
+      def create_reservation(amounts, checked: true)
         token = Object.new.freeze
         receipt = Reservation.new(
           ledger_identity: @identity,
           token:,
           amounts: @representation.externalize(amounts)
         )
-        next_state = @state_transition.reserve(@publication.state, amounts)
+        next_state = @state_transition.reserve(@publication.state, amounts, checked:)
         @publication.add(@public_state_validator.call(next_state), token:, amounts:)
         receipt
       end
@@ -132,3 +136,5 @@ module Smith
     end
   end
 end
+
+require_relative "spent_reservation"

data/lib/smith/budget/ledger_state_transition.rb

@@ -11,12 +11,9 @@ module Smith
 
       option :limits
 
-      def reserve(state, amounts)
+      def reserve(state, amounts, checked: true)
         DecimalContext.call do
-          amounts.each do |key, amount|
-            requested = state.consumed[key] + state.reserved[key] + amount
-            raise BudgetExceeded unless requested.finite? && requested <= limits.fetch(key)
-          end
+          amounts.each { |key, amount| admit!(state, key, amount, checked) }
 
           LedgerState.new(consumed: state.consumed, reserved: add(state.reserved, amounts))
         end
@@ -49,6 +46,11 @@ module Smith
 
       private
 
+      def admit!(state, key, amount, checked)
+        requested = state.consumed[key] + state.reserved[key] + amount
+        raise BudgetExceeded unless requested.finite? && (!checked || requested <= limits.fetch(key))
+      end
+
       def add(current, amounts)
         merge(current, amounts) { |value, amount| value + amount }
       end

data/lib/smith/budget/request_hold.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "amount"
+
+module Smith
+  module Budget
+    # The hold a provider request asks a host's budget ledger for before it
+    # is sent: its output cap and an estimate of its input, priced from the
+    # pricing catalog.
+    #
+    # The output cap is the request's own (`max_tokens`, or its provider's
+    # name for it, as Providers::OutputLimit reads it), else the model's
+    # maximum, else for Anthropic DEFAULT_OUTPUT_CAP (what RubyLLM asks for
+    # when it knows no more), else the model's context window, else
+    # DEFAULT_OUTPUT_CAP; Smith.config.budget_hold_output_tokens, when set,
+    # caps it. The input estimate counts text (messages, tool definitions
+    # and calls, the output schema) at one token per BYTES_PER_TOKEN bytes,
+    # an image at IMAGE_TOKENS, a PDF at PAGE_TOKENS a page (its pages
+    # counted in it, else one per BYTES_PER_PAGE), another attachment's
+    # bytes as text, and each message's framing at MESSAGE_TOKENS, and is
+    # capped at the model's context window. Images and documents are
+    # recognized as RubyLLM attachments and in raw content blocks (base64
+    # `data` beside its media type, or a data URL). It is an estimate, not a
+    # bound: what the request spent replaces it.
+    module RequestHold
+      BYTES_PER_TOKEN = 3
+      IMAGE_TOKENS = 1_600
+      PAGE_TOKENS = 2_000
+      BYTES_PER_PAGE = 50_000
+      MESSAGE_TOKENS = 8
+      DEFAULT_OUTPUT_CAP = 4_096
+      OUTPUT_CAPS = Providers::OutputLimit::PARAM_PATHS.values.flatten(1).uniq.freeze
+
+      module_function
+
+      # The hold for a request RubyLLM's Provider#complete is about to make,
+      # from its `messages:`, `tools:`, `schema:` and `params:`.
+      def for_request(provider:, model:, mode: :sync, **request)
+        context_window = model.context_window if model.respond_to?(:context_window)
+        input = [input_estimate(*request.values_at(:messages, :tools, :schema)), context_window].compact.min
+        output = [output_cap(provider, request[:params], model), Smith.config.budget_hold_output_tokens].compact.min
+        Amount.new(input_tokens: input, output_tokens: output,
+                   cost: Pricing.compute_cost(model: model.id, provider: provider.to_s, input_tokens: input,
+                                              output_tokens: output, mode:))
+      end
+
+      def input_estimate(messages, tools, schema)
+        counter = Counter.new
+        Array(messages).each { counter.message(_1) }
+        tools.to_h.each_value { counter.tool(_1) }
+        counter.text(schema) if schema
+        counter.tokens
+      end
+
+      PAGE = %r{/Type\s*/Page(?![a-zA-Z])}n
+      PAGES = ObjectSpace::WeakMap.new
+      PAGES_LOCK = Mutex.new
+      private_constant :PAGE, :PAGES, :PAGES_LOCK
+
+      # A PDF's pages (its bytes from the block), counted in it once per
+      # String, else one per BYTES_PER_PAGE.
+      def pages(source)
+        PAGES_LOCK.synchronize do
+          PAGES[source] ||= begin
+            bytes = yield(source).b
+            counted = bytes.scan(PAGE).length
+            counted.positive? ? counted : [(bytes.bytesize + BYTES_PER_PAGE - 1) / BYTES_PER_PAGE, 1].max
+          end
+        end
+      end
+
+      def output_cap(provider, params, model)
+        paths = Providers::OutputLimit::PARAM_PATHS.fetch(provider.to_s, OUTPUT_CAPS)
+        [paths.lazy.filter_map { Providers::OutputLimit.lookup(params.to_h, _1) }.first,
+         (model.max_tokens if model.respond_to?(:max_tokens)),
+         (DEFAULT_OUTPUT_CAP if provider.to_s == "anthropic"),
+         (model.context_window if model.respond_to?(:context_window))]
+          .find { _1.is_a?(Integer) && _1.positive? } || DEFAULT_OUTPUT_CAP
+      end
+
+      # Counts what a request carries: bytes of text, images, document pages
+      # and messages.
+      class Counter
+        IMAGE_BLOCKS = %w[image input_image image_url].freeze
+        DOCUMENT_BLOCKS = %w[document file input_file].freeze
+        SOURCE_KEYS = %i[source inline_data inlineData].freeze
+        MEDIA_KEYS = %i[media_type mime_type mimeType].freeze
+        DATA_URL = %r{\Adata:([\w.+-]+/[\w.+-]+);base64,}
+
+        def initialize
+          @bytes = 0
+          @images = 0
+          @pages = 0
+          @messages = 0
+        end
+
+        def tokens
+          ((@bytes + BYTES_PER_TOKEN - 1) / BYTES_PER_TOKEN) + (@images * IMAGE_TOKENS) + (@pages * PAGE_TOKENS) +
+            (@messages * MESSAGE_TOKENS)
+        end
+
+        def message(message)
+          @messages += 1
+          content(message.content)
+          Array(message.tool_calls&.values).each { text(_1.to_h) } if message.respond_to?(:tool_calls)
+          thinking = message.thinking if message.respond_to?(:thinking)
+          text(thinking.text) if thinking.respond_to?(:text)
+        end
+
+        def tool(tool)
+          text(tool.name)
+          text(tool.description)
+          text(tool.params_schema) if tool.respond_to?(:params_schema)
+        end
+
+        def content(content)
+          case content
+          when RubyLLM::Content::Raw then raw(content.value)
+          when RubyLLM::Content
+            text(content.text)
+            content.attachments.each { attachment(_1) }
+          else raw(content)
+          end
+        end
+
+        def attachment(attachment)
+          return @images += 1 if attachment.image?
+          # A URL is not fetched to count it: one page.
+          return @pages += 1 if attachment.url?
+          return @pages += RequestHold.pages(attachment.content.to_s) { _1 } if attachment.pdf?
+
+          @bytes += attachment.content.to_s.bytesize
+        end
+
+        # Raw content: an image block, a block of base64 data or a data URL
+        # counts as what it carries; anything else as its text.
+        def raw(value)
+          case value
+          when Hash then block(value)
+          when Array then value.each { raw(_1) }
+          when String then string(value)
+          else text(value)
+          end
+        end
+
+        def block(hash)
+          kind = fetch(hash, :type).to_s
+          return @images += 1 if IMAGE_BLOCKS.include?(kind)
+
+          data, media = base64_data(hash)
+          return base64(data, media) if data
+          return @pages += 1 if DOCUMENT_BLOCKS.include?(kind) && !text_source?(hash)
+
+          hash.each do |key, value|
+            text(key)
+            raw(value)
+          end
+        end
+
+        # Anthropic's `source` (base64), Gemini's `inline_data`, or the
+        # block's own `data` beside a media type.
+        def base64_data(hash)
+          source = first(hash, SOURCE_KEYS) || hash
+          return unless source.is_a?(Hash) && fetch(source, :type) != "text"
+
+          data = fetch(source, :data)
+          media = first(source, MEDIA_KEYS)
+          [data, media] if data.is_a?(String) && media.is_a?(String)
+        end
+
+        def first(hash, keys) = keys.lazy.filter_map { fetch(hash, _1) }.first
+
+        def text_source?(hash)
+          source = fetch(hash, :source)
+          source.is_a?(Hash) && %w[text content].include?(fetch(source, :type).to_s)
+        end
+
+        def string(value)
+          url = DATA_URL.match(value)
+          url ? base64(value, url[1], from: url[0].bytesize) : text(value)
+        end
+
+        # Base64 data (from byte `from` of `encoded`): an image, a PDF's
+        # pages, or its decoded size as text. Only a PDF is decoded.
+        def base64(encoded, media, from: 0)
+          return @images += 1 if media.start_with?("image/")
+          if media == "application/pdf"
+            return @pages += RequestHold.pages(encoded) { _1.byteslice(from..).unpack1("m") }
+          end
+
+          @bytes += (encoded.bytesize - from) * 3 / 4
+        end
+
+        def fetch(hash, key) = hash.key?(key) ? hash[key] : hash[key.to_s]
+
+        def text(value)
+          case value
+          when nil then nil
+          when String then @bytes += value.bytesize
+          when Symbol then @bytes += value.to_s.bytesize
+          else @bytes += JSON.generate(value).bytesize
+          end
+        rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+          @bytes += value.to_s.bytesize
+        end
+      end
+    end
+  end
+end

data/lib/smith/budget/spent_reservation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smith
+  module Budget
+    # Reserving for spending that has already happened (a batch result
+    # delivered after its request was admitted): never refused, so the
+    # reservation can be reconciled with what was spent, past the limits if
+    # need be. Part of Ledger.
+    module SpentReservation
+      def reserve_spent!(reservations)
+        amounts = validated_amounts(reservations, "budget reservation")
+        @mutex.synchronize { create_reservation(amounts, checked: false) }
+      end
+    end
+  end
+end
+
+Smith::Budget::Ledger.include(Smith::Budget::SpentReservation)

data/lib/smith/child_run.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Smith
+  # One run a `map`, `call` or `spawn` step asks the host's run launcher to
+  # start: its `ref` (the index of its item, so the same on every replay of
+  # the step), its `key` (the step's token and the ref together: what the
+  # launcher must be idempotent on, unique across every child-run step of
+  # every run), its workflow class, the context `input:` returned for it,
+  # the untrusted keys it inherits from its parent (the parent's untrusted
+  # keys that `input:` passed under the same names), and the artifact
+  # namespaces it may read (its parent's and the parent's ancestors', the
+  # nearest first), so a document a parent stored reaches its children.
+  ChildRun = Data.define(:ref, :key, :workflow, :input, :untrusted_keys, :artifact_namespaces) do
+    def self.key_for(await_token, ref) = Digest::SHA256.hexdigest("smith.child_run.v1:#{await_token}:#{ref}")
+
+    def initialize(artifact_namespaces: [], **)
+      super
+    end
+
+    # The child, built with what it inherits in force; both persist with
+    # it, so a restored child keeps them.
+    def build
+      Workflow::StepIO.with_inherited_untrusted_keys(untrusted_keys) do
+        Workflow::ArtifactIntegration.with_inherited_artifact_namespaces(artifact_namespaces) do
+          workflow.new(context: input)
+        end
+      end
+    end
+
+    # The entry a host reports for a finished child when it resumes the
+    # parent: `{ ref:, status: "succeeded" | "failed", state:, output: }`.
+    # A child failed when it ended in its failed state or any of its steps
+    # raised, even one its own `on_failure` handled.
+    def self.result(ref:, run_result:)
+      failed = run_result.failed? || Array(run_result.steps).any? { _1.is_a?(Hash) && _1.key?(:error) }
+      { ref:, status: failed ? "failed" : "succeeded", state: run_result.state&.to_s, output: run_result.output }
+    end
+  end
+end

data/lib/smith/child_runs_failed.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "diagnostic_text"
+
+module Smith
+  # A `map` or `call` step whose child runs did not all succeed, under
+  # `on_item_failure: :fail`. Its failure family is `child_runs_failed`;
+  # details name the transition, up to MAX_REFS failed refs and the counts,
+  # and persist with the failed step.
+  class ChildRunsFailed < WorkflowError
+    DETAIL_NAMES = %i[transition failed_refs failed total].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_REFS = 20
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS
+
+    attr_reader :transition, :failed_refs, :failed, :total
+
+    def initialize(transition:, failed_refs:, total:, failed: failed_refs.length, message: nil)
+      @transition = DiagnosticText.capture(transition.to_s, max_bytes: 256)
+      @failed_refs = Array(failed_refs).first(MAX_REFS).freeze
+      @failed = failed
+      @total = total
+      super(message || "#{failed} of #{total} child runs of #{@transition} failed (refs #{@failed_refs.join(", ")})")
+    end
+
+    def details = { transition:, failed_refs:, failed:, total: }.freeze
+
+    def self.from_details(details, message: nil)
+      raise ArgumentError, "child run failure details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.to_h { |key, value| [key.is_a?(Symbol) ? key : DETAIL_KEYS[key], value] }
+      unless values.keys.sort == DETAIL_NAMES.sort && valid_counts?(values)
+        raise ArgumentError, "child run failure details are invalid"
+      end
+
+      new(transition: values[:transition], failed_refs: values[:failed_refs], failed: values[:failed],
+          total: values[:total], message:)
+    end
+
+    # Counts within bounds, and refs that are distinct indexes of the total,
+    # as many as the failures up to MAX_REFS (so neither count is negative).
+    def self.valid_counts?(values)
+      refs, failed, total = values.values_at(:failed_refs, :failed, :total)
+      return false unless values[:transition].is_a?(String) && [failed, total].all?(Integer)
+
+      failed <= total && valid_refs?(refs, failed, total)
+    end
+
+    def self.valid_refs?(refs, failed, total)
+      refs.is_a?(Array) && refs.all? { _1.is_a?(Integer) && _1.between?(0, total - 1) } &&
+        refs.length == [failed, MAX_REFS].min && refs.uniq.length == refs.length
+    end
+    private_class_method :valid_counts?, :valid_refs?
+  end
+end

data/lib/smith/content.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Smith
+  # Content parts of a Smith::Message: text, and documents and images held
+  # as artifacts of the run (`Smith.artifacts.store` inside a step), never
+  # as bytes, so a message with parts stays small and JSON-shaped wherever
+  # it is stored or digested.
+  #
+  #   ref = Smith.artifacts.store(pdf_bytes, content_type: "application/pdf")
+  #   Smith::Message.user([Smith::Content.document(ref, media_type: "application/pdf"),
+  #                        Smith::Content.text("List the parties to this contract.")])
+  #
+  # `cache: true` marks the part as the end of a prefix Anthropic may cache;
+  # other providers cache on their own and ignore it.
+  module Content
+    DOCUMENT_TYPES = %w[application/pdf text/plain].freeze
+    IMAGE_TYPES = %w[image/png image/jpeg image/gif image/webp].freeze
+    MAX_TEXT_BYTES = 1024 * 1024
+    MAX_REF_BYTES = 1024
+    # The bytes one document part may hold when it is sent: as base64 it
+    # still fits a 32 MiB request.
+    MAX_PART_BYTES = 24 * 1024 * 1024
+    # An artifact ref as Smith's stores make them: a run's namespace, then
+    # colon-separated names of letters, digits, `-` and `_`. No path, dot or
+    # NUL can reach a store through it.
+    REF = /\A[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)+\z/
+
+    module_function
+
+    def text(text, cache: false) = part({ "type" => "text", "text" => text }, cache)
+
+    def document(ref, media_type:, cache: false)
+      part({ "type" => "document", "artifact" => ref, "media_type" => media_type }, cache)
+    end
+
+    def image(ref, media_type:, cache: false)
+      part({ "type" => "image", "artifact" => ref, "media_type" => media_type }, cache)
+    end
+
+    def part(fields, cache)
+      raise WorkflowError, "a content part's cache: must be true or false" unless [true, false].include?(cache)
+
+      check!(cache ? fields.merge("cache" => true) : fields)
+    end
+
+    # A part, String or Symbol keyed (and Symbol valued), checked and
+    # returned frozen with String keys and UTF-8 Strings: a text part with
+    # more than whitespace, or a document or image part naming an artifact
+    # (REF) and a media type of its kind, each with an optional
+    # `"cache" => true`.
+    def check!(value)
+      fields = value.is_a?(Hash) ? value.to_h { |key, field| [key.to_s, utf8(field)] } : {}
+      unless valid?(fields)
+        raise WorkflowError, "a content part is Smith::Content.text, .document or .image (documents " \
+                             "#{DOCUMENT_TYPES.join(", ")}; images #{IMAGE_TYPES.join(", ")})"
+      end
+
+      fields.freeze
+    end
+
+    def utf8(field)
+      return field.to_s.freeze if field.is_a?(Symbol)
+      return field unless field.is_a?(String)
+
+      field.dup.force_encoding(Encoding::UTF_8).freeze
+    end
+
+    def valid?(fields)
+      return false unless fields.fetch("cache", true) == true
+
+      keys = fields.keys - ["cache"]
+      case fields["type"]
+      when "text" then keys.sort == %w[text type] && text?(fields["text"])
+      when "document" then held?(keys, fields, DOCUMENT_TYPES)
+      when "image" then held?(keys, fields, IMAGE_TYPES)
+      else false
+      end
+    end
+
+    def text?(text) = bounded?(text, MAX_TEXT_BYTES) && text.match?(/\S/)
+
+    def held?(keys, fields, media_types)
+      keys.sort == %w[artifact media_type type] && bounded?(fields["artifact"], MAX_REF_BYTES) &&
+        REF.match?(fields["artifact"]) && media_types.include?(fields["media_type"])
+    end
+
+    def bounded?(value, max_bytes)
+      value.is_a?(String) && value.valid_encoding? && value.bytesize.between?(1, max_bytes)
+    end
+
+    def cached?(part) = part["cache"] == true
+    private_class_method :part, :utf8, :valid?, :text?, :held?, :bounded?
+  end
+end

data/lib/smith/context/session.rb

@@ -5,11 +5,12 @@ module Smith
     class Session
       attr_reader :messages
 
-      def initialize(messages:, context_manager:, persisted_context:, seed_message_count: 0)
+      def initialize(messages:, context_manager:, persisted_context:, seed_message_count: 0, untrusted_keys: nil)
         @messages = messages
         @context_manager = context_manager
         @persisted_context = persisted_context
         @seed_message_count = seed_message_count
+        @untrusted_keys = untrusted_keys
       end
 
       def inject_state!
@@ -19,10 +20,21 @@ module Smith
         return unless formatter
 
         @messages.replace(
-          StateInjection.inject(@messages, formatter: formatter, persisted: @persisted_context)
+          StateInjection.inject(@messages, formatter: formatter, persisted: trusted_context)
         )
       end
 
+      # The context without its untrusted keys: the run's own and those of
+      # any workflow it is nested in, when the run passes them, or else its
+      # context manager's.
+      def trusted_context
+        untrusted = @untrusted_keys
+        untrusted ||= @context_manager.respond_to?(:untrusted_keys) ? @context_manager.untrusted_keys : []
+        return @persisted_context if untrusted.empty? || !@persisted_context.is_a?(Hash)
+
+        @persisted_context.except(*untrusted)
+      end
+
       def masked_view
         return @messages unless @context_manager