insika 0.3.0 → 0.7.0

data/lib/insika/tools/save_artifact.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # `save_artifact` — the agent delivers a page (a report, a digest) to a
+    # destination that survives the channel: title + content in, a URL out,
+    # which it can include in a channel message ("today's report: <url>").
+    #
+    # A REGISTRY tool (not a ChatBuilder system tool): the per-agent
+    # `tools_allow` is the switch — registered `optional: true`, so an agent
+    # that did not name it cannot call it, and nothing global enables it.
+    # The bindings (tenant, agent, task) are the tool INSTANCE's, deposited
+    # by the Executor into `turn_context` like a data-tool's — never
+    # parameters the model types.
+    class SaveArtifact < RubyLLM::Tool
+      description "Save an HTML (or markdown / SVG) page — a report, a digest, " \
+                  "a summary — and get back a URL to share. Use when the answer " \
+                  "is a document the channel message cannot carry."
+      param :title, desc: "Short human-readable title (<= 200 chars)"
+      param :content, desc: "The page content: HTML with inline SVG for charts, " \
+                            "markdown, or SVG. No scripts, no external resources."
+      param :mime, desc: "text/html (default), text/markdown, or image/svg+xml",
+                   required: false
+
+      def name = "save_artifact"
+
+      def initialize(artifact_store:, base_url: nil, signing_key: nil, signing_ttl: nil,
+                     max_bytes: nil, event_stream: nil)
+        @artifact_store = artifact_store
+        @base_url = base_url.to_s.sub(%r{/\z}, "")
+        @signing_key = signing_key
+        @signing_ttl = signing_ttl
+        @max_bytes = max_bytes
+        @event_stream = event_stream
+        super()
+      end
+
+      # Per-turn bindings, deposited by the Executor (ToolAssembly's
+      # `turn_context=` seam — the same one data-tools use). From the TURN,
+      # never from the model (the tenant-lesson: an id the model types is
+      # inventable, and the turn looks right anyway).
+      attr_reader :turn_context
+
+      def turn_context=(ctx)
+        @turn_context = (ctx || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def execute(title:, content:, mime: "text/html")
+        # the deployment's size cap rides the tool instance (INSIKA_ARTIFACT_
+        # MAX_BYTES at wiring); absent -> the store's default.
+        attrs = { tenant: binding_tenant, agent: @turn_context&.dig(:agent_id),
+                  task_id: @turn_context&.dig(:task_id), title: title, mime: mime,
+                  content: content }
+        attrs[:max_bytes] = @max_bytes if @max_bytes
+        record = @artifact_store.create(**attrs)
+        # the authenticated Studio URL is the always-on answer; the signed
+        # link exists ONLY when a key was configured (it shares OUTSIDE the
+        # Studio and expires).
+        url = Insika::ArtifactSigning.url_for(id: record.id, base: @base_url)
+        result = { id: record.id, url: url }
+        signed = Insika::ArtifactSigning.url_for(
+          id: record.id, base: @base_url, key: @signing_key, ttl: @signing_ttl
+        )
+        result[:signed_url] = signed if signed != url
+        emit(record)
+        result
+      rescue Insika::ValidationError => e
+        { error: e.message }
+      end
+
+      private
+
+      # The tenant is the AGENT's tenant: the declared command tenant, or the
+      # deployment's "platform" in single-tenant — never the chat id (a report
+      # belongs to the agent, not to whichever chat ran it), never a parameter
+      # the model types.
+      def binding_tenant
+        declared = @turn_context&.dig(:command_tenant).to_s
+        declared.empty? ? "platform" : declared
+      end
+
+      # :artifact_saved carries ids + title — NEVER the content (a report is
+      # customer data that rides the store, not the events).
+      def emit(record)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :artifact_saved,
+                              data: { id: record.id, title: record.title },
+                              meta: { task_id: @turn_context&.dig(:task_id) }
+                            ))
+      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

@@ -31,10 +31,15 @@ module Insika
                   :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}}`).
+                   :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
@@ -114,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

data/lib/insika/version.rb

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

data/lib/insika/wiring/graph.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "graph_chat"
+
 module Insika
   module Wiring
     # SHARED composition core for both roots: the minimal wiring
@@ -78,11 +80,21 @@ module Insika
         # followup) so the engine, the tools and the Studio always have stores.
         contact_store       = Insika::ContactStore.new(store: backend)
         followup_store      = Insika::FollowupStore.new(store: backend)
+        # the recurring-schedule rows: one row per
+        # declared schedule, declaration + runtime state. Built unconditionally
+        # (empty and free when no pack declares schedules) so the engine, the
+        # doctor and the Studio always have a store.
+        schedule_store      = Insika::ScheduleStore.new(store: backend)
         # the distilled proposals + the latched dedup ledger +
         # the per-session markers. Built unconditionally (empty and free when
         # no pack declares distill) so the wiki, the engine and the LGPD
         # purges always have a store.
         proposal_store      = Insika::ProposalStore.new(store: backend)
+        # concepts extracted from finished turns. Built
+        # unconditionally (empty and free when no pack declares knowledge)
+        # so the extractor, the Studio and the LGPD purges always have a
+        # store.
+        knowledge_store      = Insika::KnowledgeStore.new(store: backend)
         # refinement RUNS (reports over real traffic). Runtime data,
         # same backend as sessions/tasks — the collector and the command that write it
         # are the root's business (deployment-only, like the memory commands).
@@ -93,6 +105,11 @@ module Insika
         # when no pack declares harvest) so the engine, the Studio and the
         # LGPD purges always have a store.
         harvest_store        = Insika::HarvestStore.new(store: backend)
+        # the report destination — one record per run, no
+        # versioning. Built unconditionally (empty and free when nothing saves)
+        # so the tool, the routes, the retention sweep and the tenant purge
+        # always have a store.
+        artifact_store       = Insika::ArtifactStore.new(store: backend)
 
         code_tool_registry = Insika::ToolRegistry.new
         workflow_registry  = Insika::WorkflowRegistry.new
@@ -118,7 +135,10 @@ module Insika
           funnel_store: funnel_store,
           contact_store: contact_store,
           followup_store: followup_store,
+          schedule_store: schedule_store,
           proposal_store: proposal_store,
+          knowledge_store: knowledge_store,
+          artifact_store: artifact_store,
           code_tool_registry: code_tool_registry,
           workflow_registry: workflow_registry, policy_registry: policy_registry,
           capability_registry: Insika::CapabilityRegistry.new, hooks: Insika::Hooks.new,
@@ -141,6 +161,13 @@ module Insika
       def build(spine:, profiles:, tool_registry:, tool_catalog:, skill_catalog:,
                 prompt_catalog:, guardrails:, context_providers:, edge_limiter: nil,
                 executor_extra: {})
+        # the save_artifact tool: a REGISTRY tool registered OPTIONAL (the
+        # per-agent allowlist is the switch — an agent that did not name it
+        # cannot call it). Registered in the shared code registry, so both
+        # roots (base registry + the deployment's overlay, which composes it)
+        # expose it. The gem's require lives IN the factory block (loaded on
+        # the 1st instance, turn time -> wiring-load stays gem-free).
+        register_artifact_tool(spine)
         spine.hooks.register(:task, after: guardrails.output_validator)
         middleware = Insika::MiddlewareStack.new([edge_limiter, guardrails.input_guardrail].compact)
 
@@ -188,6 +215,9 @@ module Insika
         # parity). The base graph wires it over the same backend the context
         # trace uses.
         model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
+        # the per-turn extraction hook (nil = the loop is off,
+        # parity). Gated per-agent by `profile.knowledge`.
+        knowledge_store: spine.knowledge_store,
         **executor_extra
       )
 
@@ -233,7 +263,8 @@ module Insika
             followup_store: spine.followup_store, # records age out too
             contact_store: spine.contact_store, # cells age out too
             proposal_store: spine.proposal_store, # proposals age out too
-            harvest_store: spine.harvest_store # candidates/log/snapshots too
+            harvest_store: spine.harvest_store, # candidates/log/snapshots too
+            artifact_store: spine.artifact_store # reports expire on their own TTL
           ),
           interval: tick_env("INSIKA_TICK_INTERVAL") || Insika::Tick::DEFAULT_INTERVAL,
           stale_after: tick_env("INSIKA_TICK_STALE_AFTER") || Insika::Tick::DEFAULT_STALE_AFTER
@@ -256,6 +287,16 @@ module Insika
           contact_store: spine.contact_store, task_store: spine.task_store,
           profiles: profiles, executor: executor, event_stream: spine.event_stream
         )
+        # the recurring-schedule firer — the tick's
+        # fourth duty, wired here after the Tick, gated by its own claim
+        # window. Always built: a pack that declares `schedules` later finds
+        # its firer already on the tick (inert when no profile declares one).
+        executor.tick.schedule = Insika::ScheduleEngine.new(
+          store: spine.backend, schedule_store: spine.schedule_store,
+          task_store: spine.task_store, session_store: spine.session_store,
+          profiles: profiles, executor: executor, budget_ledger: spine.budget_ledger,
+          event_stream: spine.event_stream
+        )
         # the distillation engine — the tick-duty that finds idle
         # customer sessions and distills them on its own worker fiber (a
         # supervisor child, started in serving mode next to the tick).
@@ -307,13 +348,16 @@ module Insika
           memory_store: spine.memory_store, memory_audit_store: spine.memory_audit_store,
           refinement_store: spine.refinement_store,
           harvest_store: spine.harvest_store,
+          artifact_store: spine.artifact_store,
           outbox_store: spine.outbox_store, shadow_pair_store: spine.shadow_pair_store,
           inbound_log: spine.inbound_log,
           outcome_store: spine.outcome_store,
           funnel_store: spine.funnel_store,
           contact_store: spine.contact_store,
           followup_store: spine.followup_store,
+          schedule_store: spine.schedule_store,
           proposal_store: spine.proposal_store,
+          knowledge_store: spine.knowledge_store,
           token_store: spine.token_store, budget_ledger: spine.budget_ledger,
           circuit_state: spine.circuit_state,
           channel_registry: spine.channel_registry, channel_delivery: channel_delivery,
@@ -327,6 +371,49 @@ module Insika
         )
       end
 
+      # The boot step behind every root's `load_plugins` (Server::Boot's first
+      # named step). Discovers plugin manifests, validates them, requires the
+      # entries and registers their contributions into the ALREADY-BUILT graph —
+      # which is safe by construction: every seam the Loader touches resolves at
+      # turn time (registries and hooks by name, the middleware stack and the
+      # provider list per call, the catalogs on reload), and the step runs
+      # single-fiber before the server accepts connections.
+      #
+      # Roots, highest precedence first (duplicate id -> first root wins):
+      #   1. workspace  — INSIKA_PLUGIN_DIR (the operator's override spot);
+      #   2. gems       — whatever called Insika::Plugin.announce (default-enabled);
+      #   3. bundled    — `bundled_root` (the repo's plugins/; requires enabling).
+      # INSIKA_PLUGINS enables workspace/bundled ids; INSIKA_PLUGINS_DISABLED is
+      # the absolute veto (deny wins, like every allowlist in the engine).
+      def load_plugins(graph, env: ENV, bundled_root: nil)
+        announced = Insika::Plugin.announced_roots
+        workspace = Insika::EnvSchema.read("INSIKA_PLUGIN_DIR", env)
+        roots = ([workspace] + announced + [bundled_root]).compact.map { |d| File.expand_path(d.to_s) }
+
+        result = Insika::Plugin::Loader.new(
+          roots: roots,
+          registries: {
+            tools: graph.code_tool_registry, workflows: graph.workflow_registry,
+            policies: graph.policy_registry, capabilities: graph.capability_registry,
+            channels: graph.channel_registry, hooks: graph.hooks,
+            middleware: graph.middleware, context_providers: graph.context_providers
+          },
+          enabled: plugin_csv(Insika::EnvSchema.read("INSIKA_PLUGINS", env)),
+          disabled: plugin_csv(Insika::EnvSchema.read("INSIKA_PLUGINS_DISABLED", env)),
+          announced_roots: announced, event_stream: graph.event_stream
+        ).load_all
+
+        # Plugin knowledge joins at the LOWEST precedence: an operator's
+        # workspace/authored skill always beats a same-named plugin one.
+        graph.skill_catalog.add_roots(result[:skill_dirs])
+        graph.prompt_catalog.add_roots(result[:prompt_dirs])
+        result
+      end
+
+      def plugin_csv(value)
+        value.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
       # The CORE command surface every root needs — turn essentials + the operator
       # controls (pause/approve) the Studio dispatches. Registering pause_task/
       # approve_action HERE is the crux of: it retires the config.ru:28-34 patch.
@@ -411,16 +498,18 @@ module Insika
                        model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
                        outcome_store: spine.outcome_store,
                        funnel_store: spine.funnel_store, # the fold dies with the tenant
-                       followup_store: spine.followup_store,
-                       contact_store: spine.contact_store,
-                       proposal_store: spine.proposal_store,
-                       harvest_store: spine.harvest_store,
-                       task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
-                       outbox_store: spine.outbox_store,
-                       shadow_pairs: spine.shadow_pair_store,
-                       token_store: spine.token_store, # revoked BEFORE the sweep
-                       event_stream: spine.event_stream
-                     ))
+                        followup_store: spine.followup_store,
+                        contact_store: spine.contact_store,
+                        proposal_store: spine.proposal_store,
+                        harvest_store: spine.harvest_store,
+                        schedule_store: spine.schedule_store,
+                        artifact_store: spine.artifact_store,
+                        task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
+                          outbox_store: spine.outbox_store,
+                          shadow_pairs: spine.shadow_pair_store,
+                          token_store: spine.token_store, # revoked BEFORE the sweep
+                          event_stream: spine.event_stream
+                        ))
         # the operator's baseline freeze — the number
         # read. Synchronous control command, dispatched from the Studio.
         bus.register(:freeze_funnel_baseline,
@@ -434,6 +523,12 @@ module Insika
         bus.register(:cancel_followup,
                      Insika::Commands::CancelFollowup.new(followup_store: spine.followup_store,
                                                           event_stream: spine.event_stream))
+        # the report destination's Studio mutation — delete one
+        # artifact (the only write on the Artifacts tab; a bus command, like
+        # every Studio mutation).
+        bus.register(:delete_artifact,
+                     Insika::Commands::DeleteArtifact.new(artifact_store: spine.artifact_store,
+                                                          event_stream: spine.event_stream))
         bus.register(:revoke_contact,
                      Insika::Commands::RevokeContact.new(contact_store: spine.contact_store,
                                                          followup_store: spine.followup_store,
@@ -493,6 +588,23 @@ module Insika
         # code path; the engine keeps the automatic pass when the root does
         # not pass a runner here (nil = the command is not on the bus).
         bus.register(:run_distillation, run_distillation) if run_distillation
+        # the demo seed's ONE path — the CLI's `insika demo:seed` builds
+        # the same Insika::Demo::Seeder itself (no executor, no bus, from
+        # Graph.spine alone), and the Studio's "Seed demo data" button
+        # dispatches this bus command; nothing else writes the demo agent.
+        config_store = Insika::ConfigStore.new(store: spine.backend)
+        demo_seeder = Insika::Demo::Seeder.new(
+          profiles: profiles, store: spine.backend, session_store: spine.session_store,
+          task_store: spine.task_store, outcome_store: spine.outcome_store,
+          funnel_store: spine.funnel_store, followup_store: spine.followup_store,
+          refinement_store: spine.refinement_store, pending_action_store: spine.pending_action_store,
+          proposal_store: spine.proposal_store, memory_store: spine.memory_store,
+          golden_store: Insika::GoldenStore.new(config_store: config_store),
+          baseline_store: Insika::BaselineStore.new(config_store: config_store),
+          event_stream: spine.event_stream
+        )
+        bus.register(:seed_demo_data,
+                     Insika::Commands::SeedDemoData.new(seeder: demo_seeder, event_stream: spine.event_stream))
         bus
       end
 
@@ -505,7 +617,9 @@ module Insika
         :harvest_store,
         :token_store, :budget_ledger, :circuit_state, :outbox_store, :shadow_pair_store,
         :inbound_log, :outcome_store, :funnel_store,
-        :contact_store, :followup_store, :proposal_store,
+        :contact_store, :followup_store, :schedule_store, :proposal_store,
+        :knowledge_store,
+        :artifact_store,
         :code_tool_registry, :workflow_registry, :policy_registry, :capability_registry, :hooks,
         :channel_registry, keyword_init: true
       )
@@ -520,7 +634,10 @@ module Insika
         :inbound_log, :token_store,
         :budget_ledger, :circuit_state, :outcome_store, :funnel_store,
         :contact_store, :followup_store, :proposal_store,
+        :schedule_store,
         :harvest_store,
+        :knowledge_store,
+        :artifact_store,
         :channel_registry, :channel_delivery,
         :code_tool_registry, :tool_registry, :workflow_registry, :policy_registry, :capability_registry,
         :tool_catalog, :skill_catalog, :prompt_catalog,
@@ -531,6 +648,61 @@ module Insika
       ) do
         def durable? = backend.is_a?(Insika::Stores::SQLite)
       end
+
+      # The save_artifact tool, registered OPTIONAL on the shared code registry
+      # (the per-agent allowlist is the switch). The signing/base config is
+      # bound at registration time from the environment — the tool instance is
+      # per-deployment, and the tenant/agent/task bindings arrive per-turn via
+      # the deposited turn context.
+      # `run_persona_eval` (C3.1): a QA agent's own probe against a SIBLING
+      # agent of THIS SAME graph. Registered OPTIONAL on the shared code
+      # registry, same switch as `save_artifact` — but unlike that one, this
+      # is NOT called unconditionally from `build`: it needs a `golden_store`
+      # and a `settings_store` (the persona model + judge panel), and neither
+      # lives on the spine (the base/minimal wiring builds without either, the
+      # same way it builds without a Studio) — so each root calls this itself,
+      # once it has both. `config/deployment.rb` (round1, and the actual
+      # production `config.ru` root) and `DSL::Runtime` both do.
+      #
+      # `graph` is the ALREADY-RETURNED `Graph::Result` — bus/executor fully
+      # assembled by the time a caller has it to pass here, so `GraphChat.new`
+      # needs no laziness of its own (the tool's own factory block is what is
+      # lazy — this method just registers it).
+      # `llm:` — the caller's own RubyLLM::Context, when it has one
+      # (DSL::Runtime does; config/deployment.rb does not, and reads the
+      # process-wide RubyLLM constant like the rest of that root already
+      # does). Forwarded as-is so the tool's OWN persona/judge calls spend
+      # the right credentials instead of silently defaulting to nil.
+      def register_persona_eval_tool(graph, golden_store:, settings_store:, llm: nil)
+        graph.code_tool_registry.register("run_persona_eval", optional: true) do
+          require "ruby_llm"
+          require_relative "../tools/run_persona_eval"
+          Insika::Tools::RunPersonaEval.new(
+            golden_store: golden_store, profiles: graph.profiles, tool_registry: graph.tool_registry,
+            runtime: GraphChat.new(graph: graph), graph: graph, settings_store: settings_store,
+            budget_ledger: graph.budget_ledger, event_stream: graph.event_stream, llm: llm
+          )
+        end
+      end
+
+      def register_artifact_tool(spine)
+        signing_key = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_KEY")
+        signing_ttl = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_TTL")
+        max_bytes = Insika::EnvSchema.read("INSIKA_ARTIFACT_MAX_BYTES")
+        base_url = Insika::Coercion.presence(Insika::EnvSchema.read("INSIKA_PUBLIC_URL"))
+        spine.code_tool_registry.register("save_artifact", optional: true) do
+          require "ruby_llm"
+          require_relative "../tools/save_artifact"
+          Insika::Tools::SaveArtifact.new(
+            artifact_store: spine.artifact_store,
+            base_url: base_url,
+            signing_key: signing_key,
+            signing_ttl: signing_ttl&.to_i,
+            max_bytes: max_bytes&.to_i,
+            event_stream: spine.event_stream
+          )
+        end
+      end
     end
   end
 end

data/lib/insika/wiring/graph_chat.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Insika
+  module Wiring
+    # A synchronous, in-process "chat" seam over an assembled `Graph::Result`:
+    # dispatch a Command, drain the event stream to its terminal event, hand
+    # back the outcome. Extracted from `DSL::Runtime#chat`/`#run_workflow`
+    # (C3.1) so a graph built OUTSIDE the DSL — `config/deployment.rb`, the
+    # actual production/round1 composition root `config.ru` boots — can hand a
+    # `#chat`-capable object to anything that needs one (today:
+    # `run_persona_eval`'s `Evals::GraphTransport` seam), without a second copy
+    # of this dispatch+drain plumbing. `DSL::Runtime` now delegates here too —
+    # one implementation, exercised by both roots.
+    class GraphChat
+      TERMINAL = %i[task_completed task_failed task_cancelled].freeze
+
+      def initialize(graph:)
+        @graph = graph
+      end
+
+      # 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
+      # Insika::Error on a failed/cancelled turn, or the command's own
+      # rejection (unknown agent, bad schema) verbatim.
+      def chat(message, agent:, session_id: nil, timeout: nil)
+        command = Insika::Command.build(
+          :send_message, { agent: agent.to_s, message: message, session_id: session_id },
+          transport: :cli
+        )
+        run_command(command, session_id: session_id, timeout: timeout)[:text]
+      end
+
+      # Dispatch + drain, generic over any Command — the seam a workflow run
+      # also needs (a :trigger_workflow Command carries :output, not :text).
+      # Subscribes BEFORE dispatching (the fiber may emit eagerly) and binds to
+      # the dispatched task. A synchronous handler error (unknown agent/
+      # workflow, bad input against the schema) propagates untouched — the
+      # caller sees the real ValidationError/NotFoundError, not a turn failure.
+      def run_command(command, session_id:, timeout:)
+        require "async"
+        outcome = {}
+        rejected = nil
+        Async do |task|
+          serving = !session_id.nil?
+          @graph.executor.supervised = true if serving
+          ensure_session(session_id) if session_id
+          sub = @graph.event_stream.subscribe
+          res = begin
+            @graph.bus.dispatch(command)
+          rescue StandardError => e
+            # CAPTURED, not re-raised inside the reactor: letting it escape the
+            # Async block logs "Task may have ended with unhandled exception" —
+            # alarming noise for a DOCUMENTED rejection (a schema violation, an
+            # unknown agent). Re-raised verbatim below, outside the reactor.
+            sub.close
+            rejected = e
+            next
+          end
+          sub.bind(task_id: res[:task_id])
+          drain(sub, outcome, task, timeout)
+          teardown_serving if serving
+        end.wait
+        raise rejected if rejected
+        raise Insika::Error, "turn #{outcome[:error]}" if outcome[:error]
+
+        outcome
+      end
+
+      private
+
+      # Reads the stream until this turn reaches a terminal event, then stops.
+      # A workflow run also carries its typed OUTPUT, which is not the turn text.
+      def drain(sub, outcome, task, timeout)
+        reader = task.async do
+          sub.each do |ev|
+            case ev.type
+            when :task_completed      then outcome[:text] = ev.data[:content].to_s
+            when :workflow_completed  then outcome[:output] = ev.data[:output]
+            when :task_failed         then outcome[:error] = "failed: #{ev.data[:message] || ev.data[:error]}"
+            when :task_cancelled      then outcome[:error] = "cancelled"
+            end
+            sub.close if TERMINAL.include?(ev.type)
+          end
+        end
+        timeout ? task.with_timeout(timeout) { reader.wait } : reader.wait
+      rescue Async::TimeoutError
+        outcome[:error] = "timed out after #{timeout}s"
+        sub.close
+      end
+
+      def ensure_session(session_id)
+        @graph.session_store.find(session_id) || @graph.session_store.create(id: session_id, vars: {})
+      end
+
+      def teardown_serving
+        @graph.executor.stop_session_actors
+        @graph.executor.instance_variable_get(:@supervisor)&.stop
+      end
+    end
+  end
+end