insika 0.2.0 → 0.7.0

data/lib/insika/templates.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # Template gallery: example agents shipped INSIDE the gem
+  # (`lib/insika/templates/<name>/{agent.rb,README.md}`), one DSL file per
+  # template that is BOTH doors — `insika new <name>` copies it for the user
+  # to run and edit, and this module `evaluate`s the same file to hand its
+  # pack(s) to the Studio's "New from template" gallery. No parallel pack
+  # format to drift.
+  #
+  # A template's `agent.rb` guards its CLI demo footer with
+  # `if __FILE__ == $PROGRAM_NAME` (false when this module evaluates it) and
+  # ends with the bare `Insika.agent`/`Insika.system` result as its LAST
+  # expression, so `evaluate` gets it back as the string-eval's return value
+  # — no registration call, no second source of truth.
+  module Templates
+    ROOT = File.expand_path("templates", __dir__)
+
+    Entry = Data.define(:name, :title, :trail, :description, :capabilities, :studio, :env, :requires) do
+      def studio? = studio
+    end
+
+    module_function
+
+    # -> [String] template dirs that have an agent.rb, lexicographic.
+    def names
+      return [] unless Dir.exist?(ROOT)
+
+      Dir.children(ROOT).select { |n| File.file?(agent_path(n)) }.sort
+    end
+
+    # -> [Entry] every template, parsed metadata only (no evaluation — cheap,
+    # safe to call on every render of the Studio gallery).
+    def all = names.map { |n| read(n) }
+
+    # -> Entry for one template. Raises NotFoundError for an unknown name —
+    # same discipline as a missing agent/MCP instance.
+    def read(name)
+      path = agent_path(name)
+      raise Insika::NotFoundError, "template '#{name}' not found" unless File.file?(path)
+
+      meta = frontmatter(File.read(path))
+      Entry.new(
+        name: name.to_s, title: presence(meta["title"]) || name.to_s, trail: presence(meta["trail"]),
+        description: meta["description"].to_s,
+        capabilities: split_list(meta["capabilities"]),
+        studio: meta.fetch("studio", true) != false,
+        env: split_list(meta["env"]), requires: presence(meta["requires"])
+      )
+    end
+
+    # Evaluates the template's agent.rb in an ISOLATED scope (a fresh Object's
+    # instance_eval) and returns whatever its last expression is — the built
+    # `Insika::DSL::Definition` or `Insika::DSL::System`. $PROGRAM_NAME here is
+    # whatever process called this (rspec, the CLI, the Studio server), never
+    # this file's path, so the template's own `if __FILE__ == $PROGRAM_NAME`
+    # demo footer never runs: no network call, no ARGV parsing, no puts.
+    #
+    # The fresh-Object receiver keeps a template's local variables and `def`s
+    # from leaking into the next one evaluated in the same process; a
+    # top-level CONSTANT would still leak (Ruby scopes constant assignment
+    # lexically, not by `self`) — wave-1 templates simply don't declare any
+    # (the conformance spec, would catch a future one that did).
+    def evaluate(name)
+      path = agent_path(name)
+      raise Insika::NotFoundError, "template '#{name}' not found" unless File.file?(path)
+
+      Object.new.instance_eval(File.read(path), path)
+    end
+
+    # -> [Pack] one per agent, regardless of whether the template is a single
+    # `Insika.agent` (Definition#to_pack) or a system (System#to_packs).
+    def packs_for(name)
+      built = evaluate(name)
+      built.respond_to?(:to_packs) ? built.to_packs : [built.to_pack]
+    end
+
+    def agent_path(name) = File.join(ROOT, name.to_s, "agent.rb")
+    def readme_path(name) = File.join(ROOT, name.to_s, "README.md")
+
+    # A `# ---` … `# ---` comment block at the very top of the file, YAML
+    # inside (each line stripped of its leading `# `). Not real Ruby
+    # frontmatter (there's no such thing) — a convention this module alone
+    # parses, so the metadata lives in the one file without needing a
+    # side-channel manifest.
+    def frontmatter(source)
+      lines = source.lines
+      # Every template starts with the same magic comment every other .rb
+      # file in the gem does — skip it (and any blank line) before looking
+      # for the block, so templates don't have to break that convention.
+      lines = lines.drop(1) while lines.first && (lines.first.strip.empty? || lines.first.strip == "# frozen_string_literal: true")
+      return {} unless lines.first&.strip == "# ---"
+
+      body = lines.drop(1)
+                  .take_while { |l| l.strip != "# ---" }
+                  .map { |l| l.sub(/\A#\s?/, "") }
+                  .join
+      YAML.safe_load(body) || {}
+    end
+    private_class_method :frontmatter
+
+    def split_list(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+    private_class_method :split_list
+
+    def presence(str) = Insika::Coercion.presence(str)
+    private_class_method :presence
+  end
+end

data/lib/insika/testing/store_contract.rb

@@ -69,18 +69,18 @@ RSpec.shared_examples "an Insika store" do
     end
 
     it " converts Symbols (keys and values) to Strings" do #
-      store.set("s", "k", { chave: :valor })
-      expect(store.get("s", "k")).to eq({ "chave" => "valor" })
+      store.set("s", "k", { key: :value })
+      expect(store.get("s", "k")).to eq({ "key" => "value" })
     end
 
     it " returns nil for an absent key, never an exception" do #
-      expect(store.get("s", "nao-existe")).to be_nil
+      expect(store.get("s", "missing-key")).to be_nil
     end
 
     it " overwrites silently (last-write-wins)" do #
-      store.set("s", "k", "primeiro")
-      store.set("s", "k", "segundo")
-      expect(store.get("s", "k")).to eq("segundo")
+      store.set("s", "k", "first")
+      store.set("s", "k", "second")
+      expect(store.get("s", "k")).to eq("second")
     end
 
     it " set returns the same object passed in (not the round-trip)" do #
@@ -128,6 +128,27 @@ RSpec.shared_examples "an Insika store" do
     end
   end
 
+  describe "#scopes" do
+    it " returns scope names sorted lexicographically" do #
+      store.set("zeta", "k", 1)
+      store.set("alpha", "k", 1)
+      store.set("alpha:child", "k", 1)
+      expect(store.scopes).to eq(["alpha", "alpha:child", "zeta"])
+    end
+
+    it " filters by prefix with start_with? (not include?)" do #
+      store.set("s", "k", 1)
+      store.set("s:child", "k", 1)
+      store.set("s2", "k", 1) # trap: contains "s" but does not start with "s:"
+      expect(store.scopes("s:")).to eq(["s:child"])
+    end
+
+    it " returns [] when nothing matches (or the store is empty)" do #
+      expect(store.scopes("nope")).to eq([])
+      expect(store.scopes).to eq([])
+    end
+  end
+
   describe "scope isolation" do
     it " keeps scopes independent in get/list/delete" do #
       store.set("s1", "k", 1)

data/lib/insika/tick.rb

@@ -3,21 +3,23 @@
 require "time"
 
 module Insika
-  # The periodic tick: durability stops waiting for a reboot. One
-  # pass does two things, in this order:
+# The periodic tick: durability stops waiting for a reboot. One
+  # pass does three things, in this order:
   #
   #   1. DRAIN the outbox (`ChannelDelivery#sweep`) — replies a previous pass
   #      (or process) recorded and never claimed. Ungated: every record carries
   #      its own transactional claim, so N workers draining is safe.
-  #   2. SWEEP stale orphaned tasks (`Recovery#run(stale_after:)`) — gated by a
-  #      bucketed claim (`Recovery.claim_sweep` on "tick:<epoch/interval>"), so
-  #      exactly one worker per window sweeps. The staleness threshold is the
-  #      liveness gate: a live :running turn is bounded by turn_timeout, so
-  #      anything untouched past it cannot be alive.
+  #   2. The engine's background duties, each gated by its OWN claim window so
+  #      their O(n) scans never ride the 60 s loop: retention (daily), the
+  #      outcome fold, the follow-up firer, and the recurring-schedule firer
+  #      (the engine's own cron — it superseded the "point your own cron at
+  #      the route" decision, see docs/SCHEDULING.md).
+  #   3. SWEEP stale orphaned tasks (`Recovery#run(stale_after:)`) — gated by a
+  #      bucketed claim, so exactly one worker per window sweeps. The staleness
+  #      threshold is the liveness gate: a live :running turn is bounded by
+  #      turn_timeout, so anything untouched past it cannot be alive.
   #
-  # It is NOT a job queue: no schedules, no priorities, no fan-out. The
-  # refinement hook once pictured here is dropped by merit —
-  # docs/REFINEMENT.md's "no scheduler in the engine" stands.
+  # It is NOT a job queue: no schedules queue, no priorities, no fan-out.
   class Tick
     # 60s: a customer waiting on WhatsApp is the deadline. 900s = 3x the
     # default turn_timeout (300s) — the rule, not the number: the threshold
@@ -31,7 +33,8 @@ module Insika
 
     def initialize(store:, recovery:, channel_delivery:, logger: nil,
                    interval: DEFAULT_INTERVAL, stale_after: DEFAULT_STALE_AFTER,
-                   sleeper: nil)
+                   sleeper: nil, retention: nil, funnel: nil, followup: nil,
+                   schedule: nil)
       @store = store
       @recovery = recovery
       @channel_delivery = channel_delivery
@@ -39,8 +42,25 @@ module Insika
       @interval = interval.to_i
       @stale_after = stale_after.to_i
       @sleeper = sleeper || method(:default_sleep)
+      @retention = retention # the daily age-based sweep; nil = none
+      @funnel = funnel # the tick-driven outcome fold; nil = none
+      @followup = followup # the tick-driven follow-up firer; nil = none
+      @schedule = schedule # the recurring-schedule firer; nil = none
     end
 
+    # the fold is wired after the Tick is built (the graph passes
+    # it to `executor.tick.funnel =` — the outcome/funnel stores come from the
+    # spine). Setter + kwarg: same shape as `retention`.
+    attr_accessor :funnel
+
+    # the follow-up firer, wired after the Tick is built (same
+    # shape as `funnel` — the stores come from the spine).
+    attr_accessor :followup
+
+    # the recurring-schedule firer, wired after the Tick is built
+    # (same shape — the stores come from the spine).
+    attr_accessor :schedule
+
     def enabled? = @interval.positive?
 
     # One pass, pure (no reactor needed): the serving loop calls it on a timer,
@@ -49,6 +69,22 @@ module Insika
     def run_once
       drained = @channel_delivery ? @channel_delivery.sweep : { dispatched: [] }
       summary = { dispatched: drained[:dispatched], resumed: [], failed: [] }
+      # WS8 retention: cheap when not claimed (its own daily window) — the
+      # O(n) scans never ride the 60 s loop.
+      retention_summary = @retention&.run
+      summary[:retention] = retention_summary if retention_summary
+      # the outcome fold — one pass per claim window, cheap
+      # when another worker holds it. Sits next to retention, on the same tick.
+      funnel_summary = @funnel&.run
+      summary[:funnel] = funnel_summary if funnel_summary
+      # the follow-up firer — the tick's third duty, gated by its
+      # OWN claim window so the O(n) scans never ride the 60 s loop.
+      followup_summary = @followup&.run
+      summary[:followup] = followup_summary if followup_summary
+      # the recurring-schedule firer — the tick's fourth duty,
+      # the same claim-window discipline as the follow-up firer.
+      schedule_summary = @schedule&.run
+      summary[:schedule] = schedule_summary if schedule_summary
       return summary unless claim_window
 
       result = @recovery.run(stale_after: @stale_after)

data/lib/insika/timezone.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Insika
+  # IANA timezone handling through the OS tz database — the
+  # engine's only route to a zone NAME (Ruby stdlib's `Time#getlocal` takes an
+  # offset, not a zone name). Shared by FollowupPolicy (quiet hours), the cron
+  # parser (next-fire materialization) and the doctor (zone existence).
+  #
+  # IANA names are resolved by pointing Ruby's `TZ` at the zone for the
+  # computation. Save/restore keeps the global intact; under the engine's
+  # cooperative fiber model — no IO between the save and the restore — the
+  # mutation is atomic on the calling fiber.
+  module Timezone
+    # The candidate tz-data roots (TZDIR first — Ruby's own lookup env). The
+    # zone name maps to a FILE under the root ("America/Sao_Paulo" ->
+    # "America/Sao_Paulo").
+    TZ_ROOTS = ([ENV["TZDIR"]] +
+                %w[/usr/share/zoneinfo /usr/share/lib/zoneinfo /etc/zoneinfo])
+               .compact.freeze
+
+    module_function
+
+    # -> bool: is `zone` an IANA name the OS tz database knows? A bogus zone
+    # is a malformed declaration — refused where the doctor can name it (an
+    # unknown ENV["TZ"] silently behaves as UTC, so existence is checked
+    # against the database, not by asking Time).
+    def known?(zone)
+      zone = zone.to_s
+      return true if zone == "UTC" || zone == "Etc/UTC"
+
+      TZ_ROOTS.any? { |root| File.directory?(root) && File.exist?(File.join(root, zone)) }
+    end
+
+    # Yields `time` interpreted in the given IANA zone (via a save/restore of
+    # ENV["TZ"] — the stdlib-only route to the OS tz database). Returns the
+    # block's value.
+    def in_zone(zone, time)
+      previous = ENV["TZ"]
+      ENV["TZ"] = zone.to_s
+      yield time
+    ensure
+      ENV["TZ"] = previous
+    end
+  end
+end

data/lib/insika/tool_definition.rb

@@ -34,7 +34,8 @@ module Insika
   # (masks/reconciles); the definition itself is agnostic to masking.
   ToolDefinition = Data.define(
     :name, :description, :parameters, :request, :response,
-    :secret_headers, :side_effect, :timeout, :group, :tags, :halt_when
+    :secret_headers, :side_effect, :timeout, :group, :tags, :halt_when,
+    :evidence                       # Insika::Evidence::Spec | nil
   )
 
   class ToolDefinition
@@ -46,7 +47,7 @@ module Insika
     ARRAY_SUGAR = PARAM_TYPES.map { |t| "array:#{t}" }.freeze
     HTTP_METHODS = %w[GET HEAD POST PUT PATCH DELETE].freeze
     IDEMPOTENT = %w[GET HEAD].freeze              # side_effect default = false
-    EXTRACTS = %w[body_raw status json_path].freeze
+    EXTRACTS = %w[body_raw status json_path evidence_envelope].freeze
     NAME_RE = /\A[a-z][a-z0-9_]*\z/               # identifier for the model
     # A `.` in the placeholder enables the turn-context namespace `{{ctx.*}}`
     # separate from the model's `{{param}}`. Params follow NAME_RE (no
@@ -56,7 +57,7 @@ module Insika
     # resolved by DataDefinedTool. Closed allowlist (a typo becomes a validation
     # error, not a silently empty header).
     CTX_PREFIX = "ctx."
-    CTX_FIELDS = %w[chat_id store_id agent_id tenant].freeze
+    CTX_FIELDS = %w[chat_id store_id agent_id tenant image_url].freeze
 
     # ---- safe subset of JSON Schema (R1) --------------------------------------
     # Types supported by EVERY provider (OpenAI/Anthropic/Gemini/DeepSeek/Bedrock).
@@ -74,7 +75,7 @@ module Insika
     # `parameters` accepts JSON Schema (Hash) OR the legacy flat array.
     def self.build(name:, description:, request:, parameters: nil, response: nil,
                    secret_headers: nil, side_effect: nil, timeout: nil, group: nil, tags: nil,
-                   halt_when: nil)
+                   halt_when: nil, evidence: nil)
       name = name.to_s
       raise Insika::ValidationError, "name must match #{NAME_RE.inspect}" unless NAME_RE.match?(name)
 
@@ -84,6 +85,10 @@ module Insika
       schema = normalize_params(parameters)
       req = normalize_request(request, top_level_names(schema))
       resp = normalize_response(response)
+      if resp[:extract] == "evidence_envelope" && evidence.nil?
+        raise Insika::ValidationError,
+              "extract 'evidence_envelope' requires an 'evidence' declaration"
+      end
 
       method = req[:method]
       effect = side_effect.nil? ? !IDEMPOTENT.include?(method) : (side_effect ? true : false)
@@ -93,7 +98,8 @@ module Insika
         secret_headers: Array(secret_headers).map(&:to_s), side_effect: effect,
         timeout: timeout.nil? ? nil : Integer(timeout),
         group: normalize_group(group), tags: normalize_tags(tags),
-        halt_when: normalize_halt_when(halt_when)
+        halt_when: normalize_halt_when(halt_when),
+        evidence: Insika::Evidence::Spec.parse(evidence)
       )
     end
 
@@ -104,7 +110,7 @@ module Insika
         name: h[:name], description: h[:description], parameters: h[:parameters],
         request: h[:request] || {}, response: h[:response],
         secret_headers: h[:secret_headers], side_effect: h[:side_effect], timeout: h[:timeout],
-        group: h[:group], tags: h[:tags], halt_when: h[:halt_when]
+        group: h[:group], tags: h[:tags], halt_when: h[:halt_when], evidence: h[:evidence]
       )
     end
 
@@ -405,7 +411,7 @@ module Insika
     # String-keyed Hash for persistence (ConfigStore stringifies again, but we
     # normalize here so the record is stable across backends).
     def to_h
-      {
+      h = {
         "name" => name, "description" => description,
         "parameters" => parameters,
         "request" => request.transform_keys(&:to_s),
@@ -415,6 +421,10 @@ module Insika
         "group" => group, "tags" => tags,
         "halt_when" => halt_when&.transform_keys(&:to_s)
       }
+      # present only when declared — a tool without evidence is byte-identical
+      # to today (no declaration, no envelope processing).
+      h["evidence"] = evidence.to_h if evidence
+      h
     end
 
     # -> true when this response ENDS the turn (no further model call). `body` is the

data/lib/insika/tool_envelope.rb

@@ -56,6 +56,11 @@ module Insika
 
       started = monotonic
       result = with_gate { Async::Task.current.with_timeout(@timeout, ToolTimeout) { __getobj__.call(args) } }
+      # the ONE seam every tool result passes on its way to the model.
+      # For a declared-evidence tool: reshape to the lean envelope, record the ids
+      # on the ledger, hoard the attachments. No evidence = the result passes
+      # through untouched (one nil-check — parity).
+      result = process_evidence(result)
       record_side_effect!(call_id) if side_effect?
       trace(call_id, args, result, started)
       result
@@ -136,5 +141,69 @@ module Insika
       @checkpoint_store.record_side_effect(@state.task.id, turn: @state.turn,
                                                            tool_call_id: call_id)
     end
+
+    # ----   evidence ---------------------------------------------
+
+    # The evidence spec for the wrapped tool (D4). Resolution order:
+    #   1. the wrapped tool responds to `evidence` -> its spec (the data-tool
+    #      path — DataDefinedTool exposes its definition's evidence);
+    #   2. otherwise the tool_registry entry's metadata carries an `evidence`
+    #      spec (the code-tool path — a registry tool opts in at registration).
+    # No spec = pass the result through untouched (parity, byte-identical).
+    def evidence_spec
+      tool = __getobj__
+      if tool.respond_to?(:evidence)
+        raw = tool.evidence
+        return raw && Insika::Evidence::Spec.parse(raw)
+      end
+
+      entry = @tool_registry.respond_to?(:entries) ? registry_entry(real_name) : nil
+      metadata = entry&.respond_to?(:metadata) ? entry.metadata : nil
+      raw = metadata && (metadata[:evidence] || metadata["evidence"])
+      raw && Insika::Evidence::Spec.parse(raw)
+    end
+
+    def registry_entry(name)
+      @tool_registry.entries.find { |e| e.name == name.to_s }
+    end
+
+    # -> result (possibly reshaped). NEVER raises out: a broken evidence result
+    # becomes the envelope error the model can act on, exactly like a malformed
+    # CALL is today. A tool ERROR result is never reshaped (an error must reach
+    # the model verbatim — the DataDefinedTool rule).
+    def process_evidence(result)
+      spec = evidence_spec
+      return result unless spec
+      return result if result.is_a?(Hash) && (result[:error] || result["error"])
+
+      raw = Insika::Evidence::Processor.raw(spec, result)
+      bad = Insika::SchemaGuard.violation_output(spec, raw)
+      return { error: bad } if bad
+
+      lean, attachments = Insika::Evidence::Processor.build(spec, raw)
+      record_evidence!(spec, lean)
+      hoard_attachments!(attachments)
+      lean
+    rescue StandardError => e
+      { error: "evidence processing failed: #{e.message}" }
+    end
+
+    # Ledger write + attachment hoarding, both via the state (duck-typed — the
+    # envelope's existing specs construct state stubs without these readers).
+    def record_evidence!(_spec, lean)
+      ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+      return unless ledger
+
+      ids = Array(lean["items"]).map { |i| i["id"] }
+      ledger.record(ids) unless ids.empty?
+    end
+
+    def hoard_attachments!(attachments)
+      return if attachments.empty?
+      return unless @state.respond_to?(:evidence_attachments)
+
+      @state.evidence_attachments ||= []
+      @state.evidence_attachments.concat(attachments)
+    end
   end
 end

data/lib/insika/tool_manifest.rb

@@ -77,7 +77,11 @@ module Insika
         "tags" => (Array(defaults["tags"]) | Array(t["tags"])), # inherited default; tags unioned
         # Per-tool only: "this result ends the turn" is a property of THIS backend's
         # response, never something a manifest default should hand to its siblings.
-        "halt_when" => t["halt_when"]
+        "halt_when" => t["halt_when"],
+        # the evidence declaration (lean envelope + ledger feed are the
+        # SAME data contract — D1). Normalized here; a malformed declaration is a
+        # ValidationError at ingestion, isolable per tool (R4).
+        "evidence" => t["evidence"] && Insika::Evidence::Spec.parse(t["evidence"]).to_h
       }.compact
     end
 

data/lib/insika/tools/data_defined_tool.rb

@@ -43,6 +43,11 @@ module Insika
       def name = @definition.name
       def description = @definition.description
 
+      # the tool's own evidence declaration (a Spec | nil). The
+      # envelope's duck-typed resolution checks this FIRST — a data-tool declares
+      # its evidence on its definition, never in the registry metadata.
+      def evidence = @definition.evidence
+
       # FULL (nested) JSON Schema straight into RubyLLM's params_schema — it is what
       # the providers serialize (OpenAI/Anthropic/Gemini/Bedrock prefer
       # params_schema; parameters is just a fallback). Provider-agnostic and
@@ -148,6 +153,11 @@ module Insika
         when "status" then { status: result[:status] }
         when "body_raw" then http_ok?(result) ? result[:body] : http_error(result)
         when "json_path" then extract_json(result)
+        # the raw response body under an envelope-only key, so the
+        # ToolEnvelope can parse items/attachments. A non-2xx is an ERROR like
+        # any other extract — an error must reach the model verbatim.
+        when "evidence_envelope"
+          http_ok?(result) ? { "__insika_body" => result[:body].to_s } : http_error(result)
         end
       end
 

data/lib/insika/tools/generate_image.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # The agent's IMAGE output (WS9, saída). The engine transports media, never
+    # meaning: what the image IS for (a virtual try-on, a product mockup) is the
+    # skill's business — the contract here just produces the bytes and carries
+    # them in the turn's `output_parts`.
+    #
+    # Wired ONLY when both gates pass (ChatBuilder): the agent opted in
+    # (`outputs.image`) AND the channel declared it can receive the media
+    # (`channel.capabilities` includes "image_output") — nothing leaks by
+    # default. The image is an envelope part, never part of the answer text;
+    # the provider's tokens are merged into the turn's usage like any ask.
+    #
+    # Also EDITS — `source_image_urls` (or, absent that, the turn's
+    # own inbound photo) rides `paint(with:)`; `mask_url` rides `paint(mask:)`.
+    # What the edit MEANS (a try-on, a mockup) is the skill's business; this
+    # tool only transports the bytes.
+    class GenerateImage < RubyLLM::Tool
+      description "Generate an image, or EDIT one, and attach it to the reply as an " \
+                  "output part. Use when the customer asked for a picture, or asked to " \
+                  "transform/edit a photo (a virtual try-on, a mockup on their wall, a " \
+                  "touch-up). Omitting source_image_urls generates a new image from the " \
+                  "prompt alone — UNLESS this turn carries an inbound photo, in which case " \
+                  "that photo is edited by default (pass source_image_urls explicitly to " \
+                  "generate from scratch instead)."
+      # explicit JSON-schema form (the `param` DSL only reaches strings/scalars,
+      # and source_image_urls needs a typed array — the bare-array gotcha, #128).
+      params(
+        type: "object",
+        properties: {
+          prompt: { type: "string", description: "What to draw, or what edit to make, in detail" },
+          size: { type: "string",
+                  description: "Optional canvas size, e.g. 1024x1024 (default from the agent config)" },
+          source_image_urls: {
+            type: "array",
+            description: "Image URLs to edit instead of generating from scratch — e.g. " \
+                         "the photo the customer just sent in this conversation " \
+                         "({{ctx.image_url}}), or any other URL from this chat. Omit to use " \
+                         "the turn's inbound photo by default (if any), or to generate a " \
+                         "fresh image when there is none.",
+            items: { type: "string" }
+          },
+          mask_url: { type: "string",
+                      description: "Optional mask image URL marking which area of the " \
+                                   "source(s) to edit (transparent = editable)" }
+        },
+        required: %w[prompt]
+      )
+
+      def name = "generate_image"
+
+      # runner: a duck exposing #generate_media_output(:image, prompt, config)
+      # -> [part, usage] and #account_media_usage(part, usage) (the Executor).
+      def initialize(runner:, config:, state:, **)
+        @runner = runner
+        @config = config
+        @state = state
+        super()
+      end
+
+      def execute(prompt:, size: nil, source_image_urls: nil, mask_url: nil)
+        cfg = @config.merge("size" => size.to_s, "mask_url" => mask_url.to_s)
+                      .reject { |_, v| v.to_s.empty? }
+        cfg = cfg.merge(source_config(source_image_urls))
+        part, usage = @runner.generate_media_output(:image, prompt.to_s, cfg)
+        @state.output_parts << part
+        @runner.account_media_usage(@state, part, usage)
+        "image generated and attached to the reply (#{part["mime_type"]})"
+      end
+
+      private
+
+      # Explicit URLs win over the default; a turn with inbound images (no
+      # explicit URLs) hands `Output.generate_image` the ALREADY-FETCHED
+      # attachments (bypassing the URL fetch — they are bytes we hold).
+      def source_config(source_image_urls)
+        urls = Array(source_image_urls).map(&:to_s).reject(&:empty?)
+        return { "source_urls" => urls } if urls.any?
+        return {} unless Array(@state.image_attachments).any?
+
+        { "source_attachments" => @state.image_attachments }
+      end
+    end
+  end
+end