insika 0.1.0 → 0.3.0

data/lib/insika/tools/update_briefing.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require_relative "agent_enum"
+
+module Insika
+  module Tools
+    # Shared write-edge plumbing for the two briefing tools: the
+    # session id always comes from the turn's task — never from the model's
+    # arguments — and the :briefing_updated event carries task/session
+    # correlation for the trace.
+    module BriefingWrite
+      private
+
+      # The turn's session, from the task (turn_state.rb:7) — never the model's args.
+      def session_id
+        @state.respond_to?(:task) ? @state.task&.session_id : nil
+      end
+
+      def no_session_error = { error: "no session to brief" }
+
+      def emit(kind, field, value)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :briefing_updated,
+                              data: { kind: kind, field: field, value: value },
+                              meta: { task_id: @state.task&.id, session_id: @state.task&.session_id }
+                            ))
+      end
+    end
+
+    # Write edge of the session briefing: the agent records what it
+    # learned in THIS conversation — the working state it is accountable for
+    # (tool-written, never engine-inferred). System builtin (like remember):
+    # `require "ruby_llm"` stays in THIS file, loaded lazily by the Executor in
+    # create_chat. Wired only when the pack declared briefing_fields AND the
+    # builder has a session_store (double gate, like remember). Never enveloped:
+    # deterministic in-process writes.
+    class UpdateBriefing < RubyLLM::Tool
+      include BriefingWrite
+
+      # The class-level text carries no field list, so it can never render the
+      # empty "field must be one of: ." placeholder; the instance adds the
+      # DECLARED names (D3) to the description AND as the `field` enum (the
+      # model sees the valid set in the schema instead of inventing one —
+      # the set is instance-built. Per-instance, like the subagent tools' dynamic schemas.
+      BASE_DESCRIPTION = "Records a fact learned in this conversation into the session briefing. " \
+                         "Call it as soon as the customer gives one of these, and when they correct one."
+
+      description BASE_DESCRIPTION
+
+      def self.description_for(fields)
+        names = Array(fields).map(&:to_s)
+        names.empty? ? BASE_DESCRIPTION : "#{BASE_DESCRIPTION} field must be one of: #{names.join(', ')}."
+      end
+
+      param :field, desc: "The briefing field name (one of the declared list)"
+      param :value, desc: "The value learned. Blank clears the field."
+
+      def name = "update_briefing"
+
+      def initialize(session_store:, fields:, event_stream:, state:)
+        @session_store = session_store
+        @fields = Array(fields).map(&:to_s)
+        @event_stream = event_stream
+        @state = state
+        super()
+      end
+
+      def description
+        self.class.description_for(@fields)
+      end
+
+      # The declared names become the `field` enum in the schema the provider
+      # sees — per-turn data, like the subagent allowlist (Tools::AgentEnum).
+      def params_schema
+        @field_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @fields, path: %i[field])
+      end
+
+      # E2: an undeclared name returns an ENVELOPE error to the model and never
+      # persists. A missing session is the same shape (the model can retry later).
+      def execute(field:, value:)
+        sid = session_id
+        return no_session_error if sid.to_s.empty?
+        unless @fields.include?(field.to_s)
+          return { error: "unknown field '#{field}'; declared: #{@fields.join(', ')}" }
+        end
+
+        session = @session_store.update_briefing(sid, field: field.to_s, value: value.to_s)
+        emit("field", field.to_s, value.to_s)
+        { updated: field.to_s, briefing: session.briefing }
+      rescue Insika::NotFoundError
+        { error: "session not found" }
+      end
+
+      # The agreed next step: same engine-owned briefing object,
+      # sibling writer. Blank clears to nil.
+      class SetNextStep < RubyLLM::Tool
+        include BriefingWrite
+
+        description "Records the next step agreed with the customer " \
+                    "(e.g. 'send the payment link tomorrow at 10'). Blank clears it."
+        param :text, desc: "The agreed next step, in one sentence"
+
+        def name = "set_next_step"
+
+        def initialize(session_store:, event_stream:, state:)
+          @session_store = session_store
+          @event_stream = event_stream
+          @state = state
+          super()
+        end
+
+        def execute(text:)
+          sid = session_id
+          return no_session_error if sid.to_s.empty?
+
+          session = @session_store.set_next_step(sid, text: text.to_s)
+          emit("next_step", nil, text.to_s)
+          { next_step: session.briefing["next_step"] }
+        rescue Insika::NotFoundError
+          { error: "session not found" }
+        end
+      end
+    end
+  end
+end

data/lib/insika/turn_output.rb

@@ -25,7 +25,7 @@ module Insika
   # deliberate:
   #
   # · The customer-visible stream is per MESSAGE, not per token. `ttft_ms` still
-  #   measures the provider's first token, so item 34's baselines stay comparable;
+  #   measures the provider's first token, so's baselines stay comparable;
   #   what moved is when the customer can read it. For the WhatsApp edge this
   #   changes nothing — the dispatcher accumulated the deltas into one message
   #   anyway — and the Studio keeps its live typing off `:intermediate`.
@@ -44,7 +44,7 @@ module Insika
     # decides and publishes once, at the end of the stage.
     attr_reader :candidate
 
-    # filter: Safety::OutputFilter | nil (RFC-0009 §3.2 — nil = stream untouched).
+    # filter: Safety::OutputFilter | nil (nil = stream untouched).
     # emit:   ->(type, data) — the Executor's emitter, already bound to the task.
     # public_intermediate: the agent opted this channel in (`edge_stream`), so the
     #   narration is TAGGED and `/v1/responses` gives it its own frame. Default false:

data/lib/insika/turn_state.rb

@@ -11,11 +11,11 @@ module Insika
                   :allowed_skills,
                   :chat,               # the turn's RubyLLM::Chat instance
                   :session,            # the turn's SessionStore::Session | nil (set at stage 2;
-                  #                      read by create_chat for the per-chat model pin, §10)
-                  :model_selection,    # resolved ModelSelection (v2, §10): model/provider/source/
+                  #                      read by create_chat for the per-chat model pin)
+                  :model_selection,    # resolved ModelSelection: model/provider/source/
                   #                      pinned/params/fallbacks. Set at stage 5; surfaced in usage.
                   :halt_reason,        # set by Middleware when short-circuiting (halt-as-FAILURE)
-                  :halt_response,      # set by a Middleware for the GRACEFUL halt (RFC-0009 §3.1):
+                  :halt_response,      # set by a Middleware for the GRACEFUL halt:
                   #                      the safe reply the turn completes with, WITHOUT touching the
                   #                      LLM. Distinct from halt_reason — a completion, not a failure.
                   :guardrail_block,    # audit metadata the guardrail sets alongside halt_response
@@ -25,7 +25,45 @@ module Insika
                   #                      (after_task); the Executor emits one :guardrail_flagged each.
                   :response_content,   # the turn's final assistant text, set at stage 6/on halt so the
                   #                      after_task validator can inspect it.
-                  :output_filter       # per-turn Safety::OutputFilter (nil = off); redacts the stream.
+                  :route,              # WS4: the intent route the classifier chose (Symbol | nil).
+                  #                      Set before the ask; rides the :route_classified event and the
+                  #                      terminal event additively. nil = no routing on this turn.
+                  :message_source,     # WS9: how the turn's message entered (:voice when it came
+                  #                      from a transcribed audio part; nil = typed). Rides the
+                  #                      terminal event additively.
+                   :media_attachments,  # WS9: the ask's attachments (image parts); nil = none.
+                  #                      The provider bills them; usage flows like any ask.
+                  #                      The first image URL also lands on turn_context[:image_url]
+                  #                      for data/HTTP tools (`{{ctx.image_url}}`).
+                  :output_parts,       # WS9 (saída): media the turn GENERATED, as additive
+                  #                      parts ({ type:, mime_type:, base64:, model: }). Rides
+                  #                      the terminal event (output_parts) and the /v1/responses
+                  #                      envelope; the answer text stays text on purpose — the
+                  #                      media is a separate sibling. nil = nothing generated.
+                  :channel_capabilities, # WS9 (saída): the CHANNEL's declared OUTPUT media
+                  #                      kinds (Media::OUTPUT_CAPABILITIES — image_output /
+                  #                      audio_output). Half of the gate that decides whether
+                  #                      generate_image/tts are wired at all (the other half is
+                  #                      profile.outputs). [] = the channel declared nothing —
+                  #                      no media can leak to it.
+                  :output_filter,      # per-turn Safety::OutputFilter (nil = off); redacts the stream.
+                  :stuck_outcome,      # set by the signal_stuck system tool (WS5):
+                  #                      { reason:, message: } when the agent declared it cannot
+                  #                      proceed. The Executor tags the terminal event with
+                  #                      outcome: "stuck" and emits :turn_stuck. nil = normal turn.
+                  :evidence_ledger,     # Insika::EvidenceLedger | nil — the
+                  #                      session-scoped set of product ids that entered the
+                  #                      context via an evidence-declared tool (the envelope
+                  #                      appends; the validator/enforcer read it). Built per
+                  #                      turn by the Executor; nil = no session/no evidence.
+                  :evidence_attachments, # [ {type, url, caption} ] hoarded by the
+                  #                      envelope this turn; read by the Executor at stage 8
+                  #                      for the channel delivery. Reset per turn.
+                  :context_trace_entry  # the sanitized trace entry parked at
+                  #                      prepare_turn (fingerprints + invalidation_reason);
+                  #                      the stage-8 stamp merges the cache-hit fields into
+                  #                      it and re-records the same (task_id, turn) key.
+                  #                      nil = no store wired / no session.
 
     # Internal (not part of the contract): per-CALL correlation between RubyLLM's
     # tool callbacks and the tool decorators — `current_tool_call` keys the
@@ -34,7 +72,7 @@ module Insika
     #
     # They live in FIBER STORAGE, not in ivars, and that is the whole point:
     # `before_tool_call` → `tool.call` → `after_tool_result` all run in the SAME
-    # fiber, and with `ToolConcurrency` (item 30) there is one fiber PER CALL. A
+    # fiber, and with `ToolConcurrency` there is one fiber PER CALL. A
     # single slot on this shared object would let one in-flight call overwrite
     # another's — a side-effect recorded under the wrong id (so a resume skips the
     # wrong tool, or re-runs a non-idempotent one) and a mislabelled event. Both
@@ -56,7 +94,7 @@ module Insika
       Fiber[NAME_KEY] = name
     end
 
-    # Internal (§11 R1): the chat's message count RIGHT AFTER `assemble` (seeded
+    # Internal (R1): the chat's message count RIGHT AFTER `assemble` (seeded
     # history) and BEFORE `ask`. persist_turn slices `chat.messages.drop(baseline)`
     # to serialize the turn's real exchange — user + assistant(tool_calls) + tool
     # results + final assistant — into the transcript. nil = no chat recorded
@@ -70,13 +108,13 @@ module Insika
     # capability_registry or empty profile.capabilities (parity).
     attr_accessor :capability_names
 
-    # Internal (RFC-0015): the turn's resolved QueuePolicy. Read at stage 6 to decide
+    # Internal: the turn's resolved QueuePolicy. Read at stage 6 to decide
     # whether this run accepts steered messages, and how they are worded. Resolved once
     # per turn, in build_turn_state — an edit to the agent mid-run does not change the
     # rules the run started under.
     attr_accessor :queue_policy
 
-    # Internal (item 33): true when this turn re-enters the pipeline via
+    # Internal: true when this turn re-enters the pipeline via
     # resume_task/recovery. The EdgeLimiter reads it to NEVER re-count or block a
     # turn that was already admitted — a crash/pause under a saturated window must
     # not swallow a legitimate message with the rate-limit reply.
@@ -86,13 +124,13 @@ module Insika
     # (`remember` tool). Set in run_pipeline; nil = DEFAULT_TENANT in the MemoryStore.
     attr_accessor :tenant
 
-    # Internal (Phase 6/D2/G4): turn context deposited into the data-tools to
+    # Internal: turn context deposited into the data-tools to
     # resolve {{ctx.*}} (chat_id/agent_id/tenant/store_id) and emit
     # X-Chat-Id/X-Store-Id/X-Agent-Id. A Hash of symbols, set in run_pipeline.
     # Comes from the TURN, never from the model's args (R2). Distinct from `tenant` (memory).
     attr_accessor :turn_context
 
-    # Internal (Phase 6, observability): the turn's token usage (input/output/
+    # Internal (observability): the turn's token usage (input/output/
     # total/cached + model), captured from the provider's response at stage 6. Goes
     # to the terminal event (:task_completed) — feeds the usage of
     # /v1/responses and the Telemetry (OTEL). nil = turn with no model response
@@ -111,19 +149,19 @@ module Insika
     # by the coordinator for await(:approval)).
     attr_accessor :requires_approval, :approval_coordinator, :actor
 
-    # Internal (item 30 / D4): the turn's shared in-flight cap for tool calls —
+    # Internal: the turn's shared in-flight cap for tool calls —
     # ONE Async::Semaphore(tool_concurrency), installed by ToolAssembly#wrap_tools
     # and acquired by every ToolEnvelope, INCLUDING the ones tool_search promotes
     # mid-turn (they read it off the state, so the cap survives promotion).
     # nil = concurrency off: no gate, no overhead, serial execution unchanged.
     attr_accessor :tool_gate
 
-    # Item 30: parallel tool calls, resolved PER TURN and read by ChatBuilder
+    # parallel tool calls, resolved PER TURN and read by ChatBuilder
     # (whether to hand the gem `concurrency:`) and ToolAssembly (the gate's size).
     #
     # `requested_tool_concurrency` is what the operator configured;
     # `tool_concurrency` is what this turn actually gets. They differ for exactly
-    # one reason — D3: `Executor#request_approval` blocks on `actor.await(:approval)`,
+    # one reason —: `Executor#request_approval` blocks on `actor.await(approval)`,
     # and the mailbox is one queue per TASK. Two fibers waiting there share it,
     # `dequeue` wakes exactly one, the message is consumed, and the other fiber
     # hangs until `approval_timeout` (~1h). So a turn that can suspend for a human
@@ -147,6 +185,9 @@ module Insika
       @turn = turn
       @message = message
       @capability_names = {}
+      @output_parts = []
+      @channel_capabilities = []
+      @evidence_attachments = []
       # Fiber storage is INHERITED by fibers created later, so a turn spawned from
       # inside a tool call (a subagent child) would start out carrying its
       # parent's correlation. Clearing at turn start keeps a child from keying its

data/lib/insika/turn_timing.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # Opt-in per-turn latency breakdown (item 34 / §13.1, action 1: locate the
+  # Opt-in per-turn latency breakdown (locate the
   # TTFB cost with real-turn data). OFF unless INSIKA_TURN_TIMING is set — when
   # off the Executor never allocates one and the hot path pays only `nil&.mark`.
   #
@@ -16,7 +16,7 @@ module Insika
   #
   # `ttft_ms` is the PROVIDER's first token, not the first byte the customer can
   # read: TurnOutput publishes a message once it ends, so the customer-visible
-  # answer lands inside `gen_ms`. Measuring the provider is the point — item 34's
+  # answer lands inside `gen_ms`. Measuring the provider is the point —'s
   # baselines (~720 ms, provider-bound) stay comparable across that change.
   class TurnTiming
     # EnvSchema owns "is this flag on?" (1/true/yes/on) — the same predicate that
@@ -26,22 +26,42 @@ module Insika
       Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_TURN_TIMING", env))
     end
 
-    def initialize
+    # The marks that only mean something under INSIKA_TURN_TIMING. A `breakdown:
+    # false` clock (a channel turn with the flag off) ignores them and measures
+    # only first_balloon_ms.
+    BREAKDOWN_MARKS = %i[prep_start ask first_token done].freeze
+    private_constant :BREAKDOWN_MARKS
+
+    # breakdown: true (the default) is the flag-on clock: prep/ttft/gen/total.
+    # false is the   channel clock: only :inbound -> :first_balloon,
+    # so a channel turn with the flag off still answers H-latência.
+    def initialize(breakdown: true)
       @marks = {}
+      @breakdown = breakdown
     end
 
     def mark(name)
+      return unless @breakdown || !BREAKDOWN_MARKS.include?(name)
+
       @marks[name] ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    # Has this mark fired? Used by `SendMessage` to prove the channel clock was
+    # stamped at 202 acceptance (`:inbound` before the debounce window), and by
+    # the pipeline to know a threaded clock already started.
+    def marked?(name) = @marks.key?(name)
+
     # -> Hash of phase deltas in ms (only the windows whose endpoints both fired;
     # a workflow turn has no ask/first_token, so those are simply absent).
+    # first_balloon_ms is the inbound -> first outbox flush window.
+    # A missing number is never a zero — no mark, no key.
     def to_h
       {
         prep_ms: delta(:prep_start, :ask),
         ttft_ms: delta(:ask, :first_token),
         gen_ms: delta(:first_token, :done),
-        total_ms: delta(:prep_start, :done)
+        total_ms: delta(:prep_start, :done),
+        first_balloon_ms: delta(:inbound, :first_balloon)
       }.compact
     end
 

data/lib/insika/usage_ledger.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # Fixed-window counters on the KV Store (item 33 / §12 G7): the durable side of
+  # Fixed-window counters on the KV Store: the durable side of
   # the edge limits. One scope, keys shaped "kind:id:window_start" — the window
   # start bucketed on the epoch keeps every process/worker on the SAME bucket
   # without coordination (the Store's transaction serializes the read-modify-write,

data/lib/insika/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Insika
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/insika/vitals.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Insika
+  # Process vitals. One cheap read-only answer to "which process
+  # is this, how long has it been up, how much memory does it hold, and what is
+  # the Ruby heap doing?" It touches NO store, allocates nothing meaningful,
+  # and knows nothing about soaks — a general operator surface the soak
+  # happens to be the first consumer of. Exposed at GET /v1/vitals (operator
+  # only).
+  module Vitals
+    # Stamped when this file is first required: the process's own start, which
+    # is what "uptime" has to mean (Falcon's controller start is not this
+    # worker's). Per-process, not per-App, so a worker respawn under a live
+    # container keeps its real age and a new pid reads as a new clock.
+    STARTED_AT = Time.now.utc
+
+    # The subset of GC.stat that answers "is the Ruby heap growing, or is this
+    # the allocator?" — the difference between a leak and fragmentation, which
+    # is the first fork of any leak hunt .
+    GC_KEYS = %i[heap_live_slots heap_free_slots heap_allocated_pages
+                 total_allocated_objects total_freed_objects
+                 major_gc_count minor_gc_count
+                 malloc_increase_bytes oldmalloc_increase_bytes].freeze
+
+    module_function
+
+    # -> Hash with STRING keys (it is a JSON body, not an internal value
+    # object). `executor:`/`db_path:` are optional — absent, the body simply
+    # omits those readings. `env:` is injected for specs.
+    def snapshot(executor: nil, db_path: nil, env: ENV)
+      {
+        "boot_id" => EnvSchema.read("INSIKA_BOOT_ID", env).to_s,
+        "pid" => Process.pid,
+        "started_at" => STARTED_AT.iso8601,
+        "uptime_s" => (Time.now.utc - STARTED_AT).round,
+        "version" => Insika::VERSION,
+        "ruby" => RUBY_DESCRIPTION,
+        "yjit" => (defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled?),
+        "rss_bytes" => rss_bytes,
+        "gc" => gc_stat,
+        "threads" => Thread.list.size,
+        "in_flight" => executor&.in_flight&.size,
+        "db_bytes" => db_bytes(db_path),
+        "at" => Time.now.utc.iso8601
+      }
+    end
+
+    # Resident set size in bytes. Linux first (/proc/self/status VmRSS) —
+    # production is a Linux container; macOS/dev fall back to `ps`. Neither
+    # readable -> nil, NEVER a guess: a fabricated RSS would silently pass an
+    # envelope.
+    def rss_bytes
+      if File.file?("/proc/self/status")
+        match = File.read("/proc/self/status", encoding: "ASCII-8BIT")[/^VmRSS:\s+(\d+)\s*kB/, 1]
+        return Integer(match) * 1024 if match
+      end
+
+      out = `ps -o rss= -p #{Process.pid} 2>/dev/null`.strip
+      return Integer(out) * 1024 unless out.empty?
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def gc_stat
+      stat = GC.stat
+      GC_KEYS.each_with_object({}) { |key, acc| acc[key.to_s] = stat[key] }
+    end
+
+    # SQLite file + WAL + shm bytes. -> { "db" =>, "wal" =>, "shm" => } | nil.
+    def db_bytes(path)
+      return nil if path.nil? || path.to_s.empty?
+
+      {
+        "db" => File.size(path.to_s),
+        "wal" => File.exist?("#{path}-wal") ? File.size("#{path}-wal") : 0,
+        "shm" => File.exist?("#{path}-shm") ? File.size("#{path}-shm") : 0
+      }
+    rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR
+      nil
+    end
+  end
+end