insika 0.2.0 → 0.3.0

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

@@ -31,7 +31,7 @@ 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)
       @store = store
       @recovery = recovery
       @channel_delivery = channel_delivery
@@ -39,8 +39,20 @@ module Insika
       @interval = interval.to_i
       @stale_after = stale_after.to_i
       @sleeper = sleeper || method(:default_sleep)
+      @retention = retention # WS8: 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
     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
+
     def enabled? = @interval.positive?
 
     # One pass, pure (no reactor needed): the serving loop calls it on a timer,
@@ -49,6 +61,18 @@ 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
       return summary unless claim_window
 
       result = @recovery.run(stale_after: @stale_after)

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,44 @@
+# 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.
+    class GenerateImage < RubyLLM::Tool
+      description "Generate an image and attach it to the reply as an output part. " \
+                  "Use when the customer asked for a picture or an image would help."
+      param :prompt, desc: "What to draw, in detail"
+      param :size, desc: "Optional canvas size, e.g. 1024x1024 (default from the agent config)",
+            required: false
+
+      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)
+        cfg = @config.merge("size" => size.to_s).reject { |_, v| v.to_s.empty? }
+        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
+    end
+  end
+end

data/lib/insika/tools/schedule_followup.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "time"
+
+module Insika
+  module Tools
+    # `schedule` — the agent books a follow-up with a customer at
+    # a future time. The tool ONLY validates shape + the dedup rule (D6/D7):
+    # everything that can block (contact state, frequency, quiet hours, a
+    # malformed policy) is decided at FIRE time by the policy in force then —
+    # the schedule is a promise made in-conversation. The consent record IS
+    # the tool call itself: the customer agreeing in-conversation writes
+    # :granted.
+    #
+    # System builtin (like remember): `require "ruby_llm"` stays in THIS file,
+    # loaded lazily by the Executor in create_chat. Never enveloped.
+    class ScheduleFollowup < RubyLLM::Tool
+      description "Schedule a follow-up with this customer at a future time. Use " \
+                  "when the customer agrees to be contacted again (a product, a " \
+                  "cart, a pending payment). The cancellation policy is permanent: " \
+                  "a customer who opted out can never be rescheduled."
+      param :at, desc: "ISO 8601 (absolute) or relative '+6h' / '+2d'"
+      param :reason, desc: "Short machine-readable reason, e.g. 'pix pending, " \
+                           "customer said she would pay tonight'"
+
+      def name = "schedule"
+
+      def initialize(contact_store:, followup_store:, state:, event_stream: nil, **)
+        @contact_store = contact_store
+        @followup_store = followup_store
+        @state = state
+        @event_stream = event_stream
+        super()
+      end
+
+      def execute(at:, reason:)
+        followup = @state.profile.followup
+        # D9: a malformed policy is a tool error naming the rule (the
+        # ValidationError rescue below).
+        Insika::FollowupPolicy.parse!(followup)
+
+        resolved = resolve_at(at)
+        return { error: resolved } if resolved.is_a?(String)
+
+        reason = reason.to_s.strip
+        return { error: "reason is required (1..200 chars)" } if reason.empty? || reason.length > 200
+
+        at_time = resolved
+        return { error: "the follow-up must be at least 5 minutes in the future" } if at_time < Time.now.utc + 300
+
+        tenant = @state.respond_to?(:tenant) ? @state.tenant : nil
+        # D7: the tool call IS the consent — recorded WITHOUT un-silencing a
+        # silent customer (only a customer message reopens, D2). A revoked
+        # customer raises (the error names the opt-out).
+        @contact_store.consent(tenant: tenant, customer: customer)
+        record = @followup_store.create(
+          tenant: tenant, agent: @state.profile.id, customer: customer,
+          session_id: @state.task&.session_id, at: at_time, reason: reason,
+          arm: arm(followup), transport: transport
+        )
+        emit(record.id, record.at)
+        { scheduled: record.id, at: record.at, reason: record.reason }
+      rescue Insika::ValidationError => e
+        { error: e.message }
+      end
+
+      private
+
+      # The customer is the SAME string the message contract carries — from
+      # the running task's command, never from the model's arguments.
+      def customer
+        command = @state.task&.command
+        return nil unless command.is_a?(Hash)
+
+        payload = command["payload"] || command[:payload] || {}
+        payload["customer"] || payload[:customer]
+      end
+
+      def arm(followup)
+        return Insika::FollowupPolicy::DEFAULT_ARM unless followup.is_a?(Hash)
+
+        arm = followup["arm"].to_s
+        arm.empty? ? Insika::FollowupPolicy::DEFAULT_ARM : arm
+      end
+
+      # The transport is provenance captured at schedule time (D5): the fired
+      # turn's reply travels out of band through the SAME channel.
+      def transport
+        command = @state.task&.command
+        return nil unless command.is_a?(Hash)
+
+        meta = command["meta"] || command[:meta] || {}
+        meta["transport"] || meta[:transport]
+      end
+
+      # ISO-8601 UTC or `+(\d+)([mhd])+` relative forms; anything else is a
+      # tool error. -> Time | String (the error).
+      def resolve_at(raw)
+        text = raw.to_s.strip
+        if (m = text.match(/\A\+(\d+)([mhd])\z/))
+          seconds = m[1].to_i * { "m" => 60, "h" => 3600, "d" => 86_400 }.fetch(m[2])
+          return Time.now.utc + seconds
+        end
+        begin
+          Time.iso8601(text).utc
+        rescue ArgumentError
+          return "`at` must be ISO 8601 (absolute) or relative '+6h' / '+2d'"
+        end
+      end
+
+      # :followup_scheduled carries ids + at, NEVER the reason text — a reason
+      # is contact data that rides the record and the Studio, not the events.
+      def emit(id, at)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :followup_scheduled,
+                              data: { id: id, at: at },
+                              meta: { task_id: @state.task&.id, session_id: @state.task&.session_id }
+                            ))
+      end
+    end
+
+    # `cancel_followup` — the sibling of `schedule`. Refuses a
+    # record that is already fired (":fired — it is in the air; it fires
+    # once"), refuses a record of another tenant (WS1), and is an idempotent
+    # no-op for an already-cancelled one.
+    class CancelFollowup < RubyLLM::Tool
+      description "Cancel a previously scheduled follow-up by its id. A follow-up " \
+                  "that already fired cannot be cancelled."
+      param :id, desc: "The id returned by the schedule tool"
+
+      def name = "cancel_followup"
+
+      def initialize(followup_store:, state:, **)
+        @followup_store = followup_store
+        @state = state
+        super()
+      end
+
+      def execute(id:)
+        record = @followup_store.find(id.to_s)
+        return { error: "no follow-up with id #{id}" } if record.nil?
+        if record.status == "fired"
+          return { error: "follow-up #{id} is already fired — it is in the air; it fires once" }
+        end
+        if record.status == "blocked"
+          return { error: "follow-up #{id} is already blocked (#{record.blocked_reason})" }
+        end
+
+        tenant = (@state.respond_to?(:tenant) ? @state.tenant : nil).to_s
+        unless record.tenant == (tenant.empty? ? "platform" : tenant)
+          return { error: "follow-up #{id} belongs to another tenant" }
+        end
+
+        return { cancelled: record.id } if record.status == "cancelled" # idempotent
+
+        @followup_store.cancel(id: record.id)
+        { cancelled: record.id }
+      rescue Insika::ValidationError => e
+        { error: e.message }
+      end
+    end
+  end
+end

data/lib/insika/tools/tts.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # The agent's SPEECH output (WS9, saída). The engine transports media, never
+    # meaning: the words belong to the customer's channel (a voice note on
+    # WhatsApp), and the contract here just produces the audio bytes and carries
+    # them in the turn's `output_parts`.
+    #
+    # Wired ONLY when both gates pass (ChatBuilder): the agent opted in
+    # (`outputs.tts`) AND the channel declared it can receive the media
+    # (`channel.capabilities` includes "audio_output") — nothing leaks by
+    # default. The clip is an envelope part, never part of the answer text;
+    # the turn counts the call in its usage (`usage.media`) — the provider's
+    # speech API reports no token counts, so the part carries the model for
+    # consumer-side pricing.
+    class Tts < RubyLLM::Tool
+      description "Synthesize speech for the reply — a voice clip travels as an " \
+                  "output part in the envelope, the channel supports it. Use when the " \
+                  "customer should HEAR the answer rather than read it."
+      param :text, desc: "The words to speak"
+      param :voice, desc: "Optional voice override (default from the agent config)",
+            required: false
+
+      def name = "tts"
+
+      # runner: a duck exposing #generate_media_output(:tts, text, 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(text:, voice: nil)
+        cfg = @config.merge("voice" => voice.to_s).reject { |_, v| v.to_s.empty? }
+        part, usage = @runner.generate_media_output(:tts, text.to_s, cfg)
+        @state.output_parts << part
+        @runner.account_media_usage(@state, part, usage)
+        "speech synthesized and attached to the reply (#{part["mime_type"]})"
+      end
+    end
+  end
+end