insika 0.7.0 → 0.9.0

data/lib/insika/tools/tool_search.rb

@@ -21,7 +21,7 @@ module Insika
       def name = "tool_search"
 
       def initialize(catalog, deferred_allowed, chat, tool_registry:, event_stream:,
-                     checkpoint_store:, state:)
+                     checkpoint_store:, state:, trace_recorder: nil)
         @catalog = catalog
         @deferred_allowed = Array(deferred_allowed).map(&:to_s)
         @chat = chat
@@ -29,6 +29,7 @@ module Insika
         @event_stream = event_stream
         @checkpoint_store = checkpoint_store
         @state = state
+        @trace_recorder = trace_recorder
         @promoted = [] # names already promoted IN THIS chat — idempotency
         super()
       end
@@ -59,7 +60,8 @@ module Insika
           @promoted << entry.name
           ToolEnvelope.new(tool, state: @state, checkpoint_store: @checkpoint_store,
                                  tool_registry: @tool_registry, timeout: timeout,
-                                 skip_side_effects: Array(@state.skip_side_effects))
+                                 skip_side_effects: Array(@state.skip_side_effects),
+                                 event_stream: @event_stream, trace_recorder: @trace_recorder)
         rescue Insika::NotFoundError
           nil
         end

data/lib/insika/turn_budget.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Insika
+  # The turn's tool-call counter — one object, three jobs: count, warn, abort.
+  #
+  # `max_tool_calls` was enforced but never announced: the model learned of the
+  # ceiling only when the turn DIED with `stage: :tool_limit`. A real run in
+  # `round1.db` (task d0421891) burned all 50 calls summing a 40-number list one
+  # `calc` at a time and delivered nothing — the model had no way to know it was
+  # spending a budget at all.
+  #
+  # So the budget speaks before it kills: at 10 / 5 / 2 calls remaining the
+  # engine appends a short notice and the model gets to converge on an answer.
+  #
+  # · **User turn, never system.** The system prefix stays byte-stable, so the
+  #   Anthropic cache breakpoint (`chat_builder.rb`'s `apply_instructions`) keeps
+  #   hitting. A notice in the prompt would bill a cache WRITE every turn.
+  # · **Batch boundary only** (ToolBatch), and **a halted batch receives
+  #   nothing** — the two rules SteerInjector established for mid-turn appends.
+  # · **Off when there is no limit.** `max: nil` = count nothing, warn nothing,
+  #   abort never.
+  #
+  # KNOWN REACH (measured against DeepSeek, 2026-08-30): a model that announces
+  # ONE batch bigger than the whole budget — 30 independent tool calls in a single
+  # assistant message — never reaches a boundary before the abort, so it gets no
+  # notice. Nothing can be appended mid-batch, so that shape is out of reach by
+  # construction; it is also the shape where the model already knows what it asked
+  # for. What this catches is the SEQUENTIAL burn, which is the one `round1.db`
+  # actually shows: 46 `calc` calls, one per step.
+  class TurnBudget
+    # The three notices, verbatim and escalating — one constant, so a transcript
+    # reader can recognize an engine sentence without an origin stamp (chat
+    # messages carry none). Keyed by calls REMAINING after the call being made.
+    NOTICES = {
+      10 => "Tool budget: 10 of your %<max>d tool calls for this turn are left. " \
+            "Start converging — prefer one call that answers the question over several that circle it.",
+      5 => "Tool budget: 5 tool calls left in this turn. " \
+           "Drop anything optional and gather only what the answer actually needs.",
+      2 => "Tool budget: 2 tool calls left in this turn. " \
+           "Consolidate what you already have and answer now — do not start new work."
+    }.freeze
+
+    def self.notice(remaining, max) = format(NOTICES.fetch(remaining), max: max)
+
+    # chat: the turn's chat — must answer #add_message (the boundary append).
+    # max:  the profile's max_tool_calls. nil = no budget: no notice, no abort.
+    # emit: ->(type, data) — the Executor's emitter, bound to the task.
+    def initialize(chat:, max:, emit:)
+      @chat = chat
+      @max = max
+      @emit = emit
+      @calls = 0
+      @batch = ToolBatch.new
+      @pending = nil # a threshold was crossed; waiting for the batch boundary
+      @warned = []   # thresholds already spent (each fires at most once a turn)
+    end
+
+    # From ChatBuilder's before_tool_call, FIRST thing: counts the call about to
+    # run and raises when it is past the ceiling. The raise is the pre-existing
+    # guard-rail, moved here so the count has exactly one owner.
+    def tool_call
+      return if @max.nil?
+
+      @calls += 1
+      if @calls > @max
+        raise Insika::TimeoutError.new("tool call limit exceeded (#{@max})", stage: :tool_limit)
+      end
+
+      remaining = @max - @calls
+      @pending = remaining if NOTICES.key?(remaining) && !@warned.include?(remaining)
+    end
+
+    # From ChatBuilder's after_tool_result, with the RAW result.
+    def tool_result(result) = @batch.halt!(result)
+
+    # RubyLLM after_message: delivers the armed notice the moment the batch of
+    # tool results closes.
+    def message_ended(message)
+      return unless @batch.closed?(message)
+      return if @pending.nil?
+
+      remaining = @pending
+      @pending = nil
+      return if @batch.halted? # nothing will read it (halt_when): drop, never deliver
+
+      @warned << remaining
+      @chat.add_message(role: :user, content: self.class.notice(remaining, @max))
+      @emit.call(:tool_budget_warned, { remaining: remaining, max: @max })
+    end
+  end
+end

data/lib/insika/turn_state.rb

@@ -61,9 +61,16 @@ module Insika
                   #                      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
+                  :evidence_attachments, # [ {type, url, caption, id} ] hoarded by the
                   #                      envelope this turn; read by the Executor at stage 8
                   #                      for the channel delivery. Reset per turn.
+                  :presentations,      # [ {component, title, items: [{id,url,caption}]} ] —
+                  #                      what a presentation tool SELECTED this turn, in call
+                  #                      order. Non-empty = the channel delivery sends these
+                  #                      instead of every hoarded card. Reset per turn.
+                  :fence_max_chars,    # per-leaf cap the ToolEnvelope applies when the
+                  #                      agent has `fencing` on — the platform's
+                  #                      `fencing.max_chars`, set per turn by the Executor.
                   :context_trace_entry  # the sanitized trace entry parked at
                   #                      prepare_turn (fingerprints + invalidation_reason);
                   #                      the stage-8 stamp merges the cache-hit fields into
@@ -167,6 +174,10 @@ module Insika
     # nil = concurrency off: no gate, no overhead, serial execution unchanged.
     attr_accessor :tool_gate
 
+    # Turns of one session already run serially through SessionActor. This gate
+    # prevents overlapping writes within a parallel batch of the current turn.
+    attr_accessor :side_effect_gate
+
     # parallel tool calls, resolved PER TURN and read by ChatBuilder
     # (whether to hand the gem `concurrency:`) and ToolAssembly (the gate's size).
     #
@@ -199,6 +210,7 @@ module Insika
       @output_parts = []
       @channel_capabilities = []
       @evidence_attachments = []
+      @presentations = []
       # 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/version.rb

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

data/lib/insika/wiring/graph.rb

@@ -422,6 +422,13 @@ module Insika
         bus = Insika::CommandBus.new
         bus.register(:create_session,
                      Insika::Commands::CreateSession.new(session_store: spine.session_store, event_stream: spine.event_stream))
+        # A snapshot loaded into a conversation before its first turn — what an eval
+        # case declares as `state:`. The HTTP route and the in-process eval transport
+        # both dispatch this one command.
+        bus.register(:seed_session,
+                     Insika::Commands::SeedSession.new(session_store: spine.session_store,
+                                                       memory_store: spine.memory_store,
+                                                       event_stream: spine.event_stream))
         bus.register(:cancel_task,
                      Insika::Commands::CancelTask.new(task_store: spine.task_store, executor: executor))
         bus.register(:pause_task,

data/lib/insika/wiring/graph_chat.rb

@@ -18,6 +18,10 @@ module Insika
         @graph = graph
       end
 
+      # The graph this seam speaks for — an eval transport reaches its bus and
+      # event stream through here.
+      attr_reader :graph
+
       # One turn, in-process -> the assistant's text. `agent:` is REQUIRED —
       # this seam has no notion of "the default agent" (that is a DSL::Runtime
       # concept, filled in by its own caller before delegating here). Raises

data/lib/insika.rb

@@ -99,6 +99,7 @@ require_relative "insika/context/catalog_provider"
 require_relative "insika/context/builder"
 require_relative "insika/context/providers/request"
 require_relative "insika/context/providers/prompt"
+require_relative "insika/context/providers/fence_notice"
 require_relative "insika/context/providers/skill"
 require_relative "insika/context/providers/skill_trigger"
 require_relative "insika/context/providers/tool_search"
@@ -146,6 +147,7 @@ require_relative "insika/skill_store"
 require_relative "insika/secret_masking"
 require_relative "insika/tool_store"
 require_relative "insika/tool_trace_store"
+require_relative "insika/tool_usage_report"
 require_relative "insika/context_trace_store"
 # the model-visible payload of one ask + its durable trace —
 # "model-visible means logged" (the conformance suite's reconstruction half).
@@ -229,6 +231,7 @@ require_relative "insika/system_file_store"
 require_relative "insika/recovery"
 require_relative "insika/command_bus"
 require_relative "insika/commands/create_session"
+require_relative "insika/commands/seed_session"
 require_relative "insika/commands/cancel_task"
 require_relative "insika/commands/pause_task"
 require_relative "insika/commands/approve_action"
@@ -275,6 +278,10 @@ require_relative "insika/commands/revoke_contact"
 # the report destination's Studio mutation — delete one artifact
 # (a bus command, like every Studio mutation).
 require_relative "insika/commands/delete_artifact"
+# in-session compaction (RFC-0044) — the summarizer (pure, injected
+# ask) and the boundary math; the trigger lives in the Executor, the
+# persistence in SessionStore, the read path in the Session provider.
+require_relative "insika/compaction"
 # session distillation — the distiller (pure, injected ask)
 # and the proposal store (proposals + the latched dedup ledger + the
 # per-session distilled marker).
@@ -332,12 +339,16 @@ require_relative "insika/session_actor"
 require_relative "insika/skill_catalog"
 require_relative "insika/tool_catalog"
 require_relative "insika/steer_injector"
+require_relative "insika/tool_batch"
 require_relative "insika/loop_detector"
+require_relative "insika/turn_budget"
 require_relative "insika/balloon_splitter"
 require_relative "insika/turn_output"
 require_relative "insika/turn_state"
 require_relative "insika/turn_timing"
 require_relative "insika/capability/resolved_tool"
+require_relative "insika/fence"
+require_relative "insika/spoken_transcript"
 require_relative "insika/tool_envelope"
 require_relative "insika/tool_assembly"
 require_relative "insika/chat_builder"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: insika
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Guilherme Lages Santos
@@ -296,6 +296,7 @@ files:
 - lib/insika/commands/run_harvest.rb
 - lib/insika/commands/run_refinement.rb
 - lib/insika/commands/seed_demo_data.rb
+- lib/insika/commands/seed_session.rb
 - lib/insika/commands/send_message.rb
 - lib/insika/commands/session_purge.rb
 - lib/insika/commands/set_agent_tools.rb
@@ -311,6 +312,7 @@ files:
 - lib/insika/commands/write_golden.rb
 - lib/insika/commands/write_skill.rb
 - lib/insika/commands/write_system_file.rb
+- lib/insika/compaction.rb
 - lib/insika/config_store.rb
 - lib/insika/contact_store.rb
 - lib/insika/context/builder.rb
@@ -319,6 +321,7 @@ files:
 - lib/insika/context/priority.rb
 - lib/insika/context/provider.rb
 - lib/insika/context/providers/briefing.rb
+- lib/insika/context/providers/fence_notice.rb
 - lib/insika/context/providers/knowledge.rb
 - lib/insika/context/providers/memory.rb
 - lib/insika/context/providers/prompt.rb
@@ -360,6 +363,7 @@ files:
 - lib/insika/event_stream.rb
 - lib/insika/evidence.rb
 - lib/insika/executor.rb
+- lib/insika/fence.rb
 - lib/insika/followup_engine.rb
 - lib/insika/followup_policy.rb
 - lib/insika/followup_store.rb
@@ -486,6 +490,7 @@ files:
 - lib/insika/soak/envelope.rb
 - lib/insika/soak/report.rb
 - lib/insika/soak/runner.rb
+- lib/insika/spoken_transcript.rb
 - lib/insika/steer_injector.rb
 - lib/insika/store.rb
 - lib/insika/stores/memory.rb
@@ -562,6 +567,7 @@ files:
 - lib/insika/token_estimator.rb
 - lib/insika/token_store.rb
 - lib/insika/tool_assembly.rb
+- lib/insika/tool_batch.rb
 - lib/insika/tool_catalog.rb
 - lib/insika/tool_definition.rb
 - lib/insika/tool_envelope.rb
@@ -570,6 +576,7 @@ files:
 - lib/insika/tool_registry.rb
 - lib/insika/tool_store.rb
 - lib/insika/tool_trace_store.rb
+- lib/insika/tool_usage_report.rb
 - lib/insika/tools/a2a_remote.rb
 - lib/insika/tools/agent_enum.rb
 - lib/insika/tools/concurrency.rb
@@ -577,6 +584,7 @@ files:
 - lib/insika/tools/generate_image.rb
 - lib/insika/tools/load_knowledge.rb
 - lib/insika/tools/load_skill.rb
+- lib/insika/tools/present.rb
 - lib/insika/tools/remember.rb
 - lib/insika/tools/run_persona_eval.rb
 - lib/insika/tools/save_artifact.rb
@@ -587,6 +595,7 @@ files:
 - lib/insika/tools/tool_search.rb
 - lib/insika/tools/tts.rb
 - lib/insika/tools/update_briefing.rb
+- lib/insika/turn_budget.rb
 - lib/insika/turn_output.rb
 - lib/insika/turn_state.rb
 - lib/insika/turn_timing.rb