insika 0.2.0 → 0.7.0

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

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

@@ -33,7 +33,7 @@ module Insika
   #   answer; the fragment is still on the stream as `:intermediate` for whoever is
   #   debugging it.
   #
-  # `halt_when` (PR #130) is the one case where narration IS the turn: the tool
+  # `halt_when` is the one case where narration IS the turn: the tool
   # already answered the customer, and the model's lead-in ("vou te inscrever
   # agora") is all the turn is worth. That text is retained and published by the
   # Executor's halt branch — see #halt_text.

data/lib/insika/turn_state.rb

@@ -25,11 +25,50 @@ 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.
+                  :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 + document parts);
+                  #                      nil = none. The provider bills them; usage flows like
+                  #                      any ask. The first URL of each kind also lands on
+                  #                      turn_context (`{{ctx.image_url}}` / `{{ctx.document_url}}`).
+                  :image_attachments,  # WS9: the IMAGE subset of media_attachments (nil = no
+                  #                      inbound image this turn). The default edit SOURCE for
+                  #                      generate_image — kept separate from
+                  #                      media_attachments because that one may also hold a
+                  #                      document, which is never a paint(with:) source.
+                  :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):
+                  :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
@@ -80,6 +119,12 @@ module Insika
     # rules the run started under.
     attr_accessor :queue_policy
 
+    # Internal: the run's SteerInjector, or nil when steering is off (or the chat
+    # cannot host the boundary). Rebuilt per ATTEMPT — a WS3 fallback builds a new
+    # chat, and the injector belongs to the chat it appends to. The Executor reaches
+    # for it at the end of stage 6 to absorb whatever no tool boundary took.
+    attr_accessor :steer_injector
+
     # 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
@@ -151,6 +196,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

@@ -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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Insika
-  VERSION = "0.2.0"
+  VERSION = "0.7.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