insika 0.1.0 → 0.3.0

data/docs/domain.md

@@ -0,0 +1,115 @@
+---
+title: The domain-free core
+parent: Operate & prove it
+nav_order: 9
+permalink: /domain/
+---
+
+# The domain-free core — what ships, what a deployment declares, and how to clear it
+
+The engine is domain-free by construction (RFC-0036): the gem carries no store
+vocabulary, no persona, and no fixed conversation language. This page is the
+removability map — for every artifact that could make a deployment look like
+"the Brazilian store harness", here is what ships, what the doctor reports, and
+how to clear it.
+
+## What ships and what does not
+
+One selection function owns the gem payload: `Insika::Packaging.payload_files`
+— the gemspec and the audit spec (`spec/insika/domain_boundary_spec.rb`) call
+the same function, so the boundary is a fact the suite asserts on, never a
+prose promise. It ships:
+
+- `lib/` — the engine, the server, the Studio (the compiled JS only);
+- `docs/` — the public documentation;
+- `README.md`, `LICENSE`, `CHANGELOG.md`, `bin/insika`.
+
+It never ships: `deploy/`, `packs/`, `examples/`, `plugins/`, `evals/`,
+`scripts/`, `spec/` — even a tracked pack cannot ship. Packs, personas and
+deployment wiring are checkout material, and that is the point: the reference
+deployment is not the gem.
+
+The proof command is `insika doctor --domain`: a read-only inventory of what a
+deployment declares, plus the built-in corpora still in effect. A bare install
+with no agents names nothing; an install that boots an agent reports the
+built-in pt-BR guardrail corpus as `source: gem-default` — the removability
+surface, not a store. The section never fails the doctor's exit code: it is
+informational, the RFC's proof surface.
+
+## The guardrail corpus — clear the shipped pt-BR content
+
+The deterministic guardrail patterns ship as language-tagged data
+(`Safety::Corpus`). A deployment clears a language by config, per agent:
+
+```jsonc
+// pack: agent.config.json
+{ "guardrails": { "corpora": { "languages": ["en"] } } }
+```
+
+```ruby
+# DSL
+agent = Insika.agent("store-support") do
+  instructions "…"
+  guardrails corpora: { languages: ["en"] }
+end
+```
+
+- `languages` filters the shipped families: `nil` = all (the default),
+  `[]` = none, `["en"]` = the EN-only corpus. An EN-only deployment drops the
+  pt-BR input heuristics **and** the CPF/CNPJ output redaction — a documented
+  consequence: the tax-id formats are pt-BR data, and the universal "secret"
+  redaction is never cleared.
+- `extra` adds source-string patterns per family:
+
+```jsonc
+{ "guardrails": { "corpora": { "extra": { "abuse": ["/\\bdupa\\b/i"] } } } }
+```
+
+- `guardrails.responses` replaces the built-in pt-BR fallback replies (the
+  safe refusals). Set a `default` to clear every category at once.
+
+See [Security](SECURITY.md) for the guardrail layers; the doctor's domain
+section enumerates any agent still running the built-in pt-BR corpus or the
+built-in replies, with the clear path in each entry. An unknown language or
+family, or a malformed pattern, is refused at boot — `insika doctor` reports it
+as an error and the agent never turns with a broken corpus.
+
+## Marking a deployment — declare, never infer
+
+The engine never guesses a store. Domain markers are data a deployment
+declares, and the doctor reads only those declarations:
+
+- **Personas/packs** — `metadata.domain` on the agent profile:
+
+```jsonc
+{ "metadata": { "domain": "e-commerce-pt-BR" } }
+```
+
+```ruby
+metadata domain: "e-commerce-pt-BR"
+```
+
+- **Outcome funnel** — `funnel:` on the profile (see
+  [Outcomes](AGENTS.md#outcomes--business-results-over-real-traffic-ws7)).
+  Vocabulary note: in the gem and the doctor output it is an **outcome
+  funnel**, never "conversion" — the stage names are the deployment's, and a
+  bare install shows no funnel and no stage names at all.
+- **Evidence** — the `evidence:` declaration on a tool manifest (see
+  [Tools](TOOLS.md)); the kinds are the deployment's vocabulary, never gem
+  constants.
+
+`insika doctor --domain` enumerates all four with their source —
+`deployment` for declared data, `gem-default` for the built-in corpus still in
+effect — and a bare boot names none.
+
+## The conformance claim — model-visible means logged
+
+"Every byte that reaches the provider is reconstructable from checkpoints +
+traces" is a spec, not a promise. For each (task, turn) the engine records the
+model-visible payload at the provider boundary — the system text, the tool
+schemas, and the full message stream (`ModelVisibleTraceStore`) — next to the
+durable transcript (the checkpoint). The conformance suite
+(`spec/insika/conformance/model_visible_spec.rb`) drives real turns on a
+capturing chat and asserts a three-way byte identity: what the chat held ==
+the checkpoint transcript == the model trace. A path whose bytes are not
+logged is a fix in the engine, never a waiver in the suite.

data/docs/index.md

@@ -34,9 +34,9 @@ Ruby `>= 3.3` and a provider key (the demo uses DeepSeek). The whole program:
 require "insika"
 
 assistant = Insika.agent("assistant") do
-  model "deepseek-chat"
+  model "deepseek-v4-flash"
   provider :deepseek
-  instructions "You are Bia, a concise and friendly assistant. Answer briefly."
+  instructions "You are a concise and friendly assistant. Answer briefly."
 end
 
 puts assistant.reply("hi, what can you do?")   # one turn, in-process

data/docs/onboarding/start.md

@@ -51,7 +51,7 @@ require "insika"
 
 assistant = Insika.agent("assistant") do
   provider :deepseek            # ← the provider slug from {{MODELS_URL}}
-  model "deepseek-chat"         # ← a model id from {{MODELS_URL}}
+  model "deepseek-v4-flash"         # ← a model id from {{MODELS_URL}}
   instructions "You are a concise, friendly assistant. Answer briefly."
 end
 

data/lib/insika/agent_profile.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "coercion"
+require_relative "tool_definition"
 
 module Insika
   # Single point of per-agent policy.
@@ -16,11 +17,24 @@ module Insika
     :id, :model, :provider,
     :base_prompt, :prompt_files,
     :tools_allow, :tools_deny,
-    :tools_allow_groups,              # per-GROUP allowlist (Phase 7/D4/F5, Stage C):
+    :tools_allow_groups,              # per-GROUP allowlist:
     #                                   union with tools_allow; deny wins; both
     #                                   nil = all (parity). Expands to the group's
     #                                   tools in the ToolAllowlist policy.
     :skills,
+    :skills_eager,                    # progressive disclosure OFF, wholly or in part:
+    #                                   nil/false = level 1 + load_skill (parity); true = every
+    #                                   allowed skill; [names] = exactly these. An eager skill's
+    #                                   BODY enters the prompt each turn, it leaves the
+    #                                   <available_skills> catalog and load_skill refuses it.
+    #                                   Removes the activation DECISION (no miss rate) at the
+    #                                   cost of the bodies' tokens — measure them against
+    #                                   context_budget before turning it on. Same opt-in as
+    #                                   `memory`. It lives HERE and not in the SKILL.md
+    #                                   frontmatter because skills are shared between agents:
+    #                                   a per-skill flag forced one decision onto every
+    #                                   allowlist holding the skill. NOT `Allowlist`
+    #                                   semantics — nil means NONE here (SkillCatalog#eager_for).
     :context_providers,               # provider allowlist
     :workflows_allow,                 # applied by WorkflowAllowlist
     :policies,                        # names in the Policy Registry
@@ -30,7 +44,7 @@ module Insika
     :capabilities,                    # intents the agent can trigger.
     #                                   nil = NONE (opt-in, see above).
     :subagents,                       # allowlist of child agent ids this agent MAY spawn
-    #                                   (RFC-0010, item 21). CAPACITY field — NEVER inherits;
+    # CAPACITY field — NEVER inherits;
     #                                   opt-in like `capabilities`: nil/absent = NONE (do NOT
     #                                   "fix" to nil = all). Present => the `spawn_subagent`
     #                                   system tool is wired (ChatBuilder), gated by this set.
@@ -40,7 +54,7 @@ module Insika
     :memory,                          # cross-session memory.
     #                                   nil/false = OFF (parity: provider []; the `remember`
     #                                   tool not wired); true = ON. Same opt-in as capabilities.
-    :prompt_caching,                  # Anthropic prompt caching (§11 R3): nil/false = OFF
+    :prompt_caching,                  # Anthropic prompt caching (R3): nil/false = OFF
     #                                   (parity); true = ON. Same opt-in as `memory`. When ON
     #                                   AND the resolved provider is Anthropic, ChatBuilder sets
     #                                   ONE cache breakpoint at the end of the system block
@@ -50,34 +64,108 @@ module Insika
     #                                   a context provider injecting volatile content into
     #                                   :system turns every turn into a paid cache WRITE with
     #                                   no read hit. Enable only for stable-system agents.
-    :params,                          # LLM generation params (v2, §10): a Hash with
+    :tool_persistence,                # the engine's "Tool discipline" block in the system
+    #                                   prompt (retry weak/empty tool results with a different
+    #                                   approach before giving up). THE ONE OPT-OUT FIELD:
+    #                                   nil/true = ON (the proven default — every reference
+    #                                   harness ships it), false = OFF. Deliberately inverted
+    #                                   from the opt-in fields above: the exception here is
+    #                                   turning the good behavior OFF, so that is what an
+    #                                   operator declares. Read by Context::Providers::Prompt.
+    :tool_output_compression,          # MECHANICAL tool-result dedupe in the replayed
+    #                                   history (A3/C3): nil/false = OFF (parity); true = ON.
+    #                                   Same opt-in as `memory`. When ON, the history the
+    #                                   Session provider seeds replaces byte-identical repeated
+    #                                   tool results with a compact back-reference (first
+    #                                   occurrence stays full) — no LLM involved. CHANGES WHAT
+    #                                   THE MODEL SEES: an older full result is only the first
+    #                                   occurrence; a model that wants an older detail re-calls
+    #                                   the tool. Cheap half of compaction for bloated histories.
+    :params,                          # LLM generation params: a Hash with
     #                                   temperature/max_tokens/thinking, applied to the chat at
     #                                   stage 5. {} = provider defaults (parity).
-    :model_policy,                    # governance of WHICH models the agent may use (v2, §10):
+    :budget,                          # spend caps per (tenant, agent) over
+    #                                   CALENDAR windows (WS2): { "daily" => int,
+    #                                   "monthly" => int, "soft" => bool, "alert_at" => 0.8 }.
+    #                                   HARD is the default: absent/"soft": false, a turn
+    #                                   arriving at/over the cap fails with Insika::BudgetExceeded
+    #                                   and the envelope quotes `budget_exceeded` + retry_after.
+    #                                   "soft": true crosses the cap and still runs
+    #                                   (one budget_warning event per window + a note in the
+    #                                   context).
+    #                                   Tokens count the billed spend (input+output+cached+
+    #                                   cache_creation). nil/absent = no budget (parity).
+    :reliability,                     # the provider-interaction reliability policy (WS3):
+    #                                   { "retries" => 3, "backoff" => "exponential",
+    #                                   "fallback" => ["gpt-4o-mini", ...],
+    #                                   "circuit_breaker" => { "after" => 10, "within" => 60,
+    #                                   "cooldown" => 300 }, "timeout" => 30 }. Data, never
+    #                                   DSL: retries + exponential backoff on :retryable /
+    #                                   :rate_limited_* failures (never :fatal), mid-turn
+    #                                   rotation across the fallback chain (profile's first,
+    #                                   then the platform's resolved fallbacks), and a circuit
+    #                                   breaker per (tenant, provider/model) that fail-fasts
+    #                                   with circuit_open + retry_after once the window count
+    #                                   trips. nil/absent = the plain single attempt (parity).
+    :alerts,                          # operator alert delivery (WS6): { "webhook" => url }.
+    #                                   When present, the agent's budget_warning /
+    #                                   breaker_open / delivery_failed events are POSTed to
+    #                                   the URL as JSON (outbox + claim, at-most-once).
+    #                                   nil/absent = no webhook (parity).
+    :routes,                          # intent routing (WS4): { "route" => "description" or a
+    #                                   Hash with description/delegate/stuck/message,
+    #                                   "default" => route, "model" => cheap classifier }.
+    #                                   When present, the message is classified BEFORE the
+    #                                   ask with the cheap model; the route lands on the
+    #                                   turn (state.route + :route_classified) and may
+    #                                   delegate to an existing agent or end the turn :stuck
+    #                                   (WS5). nil/absent = no routing (parity).
+    :stuck_signal,                    # the agent may signal it cannot proceed (WS5):
+    #                                   nil/false = OFF (parity — the signal_stuck system
+    #                                   tool is not wired); true = ON (the model may call
+    #                                   signal_stuck, which ends the turn with
+    #                                   `outcome: :stuck` + a final message + a :turn_stuck
+    #                                   event the consumer acts on). Same opt-in as
+    #                                   `memory`. What "stuck" MEANS is the consumer's call
+    #                                   (escalation via CRM/operator), never the engine's.
+    :outputs,                         # generated-media output policy (WS9, saída):
+    #                                   { "image" => { "model" => …, "size" => "1024x1024" },
+    #                                   "tts" => { "model" => "tts-1", "voice" => "alloy",
+    #                                   "format" => "mp3" } }. THE AGENT'S HALF of the
+    #                                   media-output gate — nil/absent = the agent never
+    #                                   generates media (opt-in like `capabilities`, do NOT
+    #                                   "fix" to nil = all). The other half is the CHANNEL'S:
+    #                                   the request must declare it can receive the media
+    #                                   (`channel.capabilities` — "image_output" /
+    #                                   "audio_output"); only with BOTH does the model see
+    #                                   the generate_image/tts tools (the abstraction admits
+    #                                   only what leaks). Generated media rides the turn's
+    #                                   `output_parts` in the envelope, never the answer text.
+    :model_policy,                    # governance of WHICH models the agent may use:
     #                                   { "allow" => [refs] }. nil = NO fence (all models —
     #                                   parity). Enforced on the RESOLVED model (ModelResolver).
-    :guardrails,                      # content-safety config (RFC-0009 §3.3): { input:, output:,
+    :guardrails,                      # content-safety config: { input:, output:,
     #                                   moderator:, strictness: }. OPT-IN like capabilities —
     #                                   nil/absent = the conservative default (Safety::Config:
     #                                   deterministic on, moderator off). Parsed, never a policy.
-    :sandbox,                         # confined-execution config (item 35, §4.6):
+    :sandbox,                         # confined-execution config:
     #                                   { provider: "local"|"docker", root:, timeout:, ...+provider
     #                                   keys }. Declarative provider selection (config-over-code) —
     #                                   consumed by Insika::Sandbox.build. {} = absent (a
     #                                   deployment builds a `local` sandbox by default). It is
     #                                   CONFIG, never a policy — it does not decide security by
     #                                   itself; the FS boundary + approvals do.
-    :refinement,                      # self-improvement config (RFC-0013 §3.8):
+    :refinement,                      # self-improvement config:
     #                                   { mode: "report"|"propose"|"auto_apply", window: {…},
     #                                   files: [allowlist], proposers: [refs], budget: {tokens:},
     #                                   auto_apply_max_edits:, max_findings:, … }. nil/absent =
-    #                                   REPORT-ONLY (phase A writes nothing to the agent, so
+    #                                   REPORT-ONLY (writes nothing to the agent, so
     #                                   reading your own traces needs no opt-in); `propose`
     #                                   and above must be enabled explicitly. It is CONFIG,
     #                                   never a policy — the write allowlist it carries is
     #                                   enforced by the applier, not by this field.
     :capabilities_declared,           # FACTS ABOUT THIS DEPLOYMENT that are not tools
-    #                                   (RFC-0014 §3.5): %w[promotions human_handoff
+    # %w[promotions human_handoff
     #                                   b2b_pricing]. An eval case declares what it
     #                                   `requires` and is SKIPPED — never failed — where
     #                                   the deployment lacks it, which is what makes one
@@ -104,10 +192,72 @@ module Insika
     #                                   (WhatsApp) puts the deliberation in front of a
     #                                   customer; that is the operator's call to make, not a
     #                                   default to inherit.
-    :metadata                         # free-form agent metadata, stable per agent
-    #                                   (from the pack `agent.config.json`). Home of the `store_id`
-    #                                   that becomes turn context (ctx.store_id, Phase 6/D2).
-    #                                   It is NOT a policy — never decides security. {} = absent.
+    :grounding,                     # the pack's grounding policy —
+    #                                   { "mode" => "flag"|"enforce"|"off",
+    #                                   "matcher" => { "sku" => …,
+    #                                   "name_keys" => [...] } }. OPT-IN:
+    #                                   nil/absent = OFF (parity, zero allocations).
+    #                                   Deep-stringified like the other hashes.
+    :metadata,                      # free-form agent metadata, stable per agent
+                                   # (from the pack `agent.config.json`). Home of the `store_id`
+                                   # that becomes turn context (ctx.store_id).
+                                   # It is NOT a policy — never decides security. {} = absent.
+    :briefing_fields,                # the per-session working-state schema this agent
+                                   # keeps and asks for: a flat [String] of
+                                   # field names the pack declares. []/nil/absent = the
+                                   # feature is OFF (no provider output, no tools — visibly
+                                   # removable). Names are engine-owned store keys
+                                   # and tool text, so they are validated against NAME_RE at
+                                   # build time. Data, never a policy: the engine owns the
+                                   # briefing object, the pack owns the fields.
+    :funnel,                         # the outcome funnel declaration — pack
+                                   # data, exactly like budget/reliability:
+                                   # { "stages" => ["greeted", "qualified", "cart", "paid"],
+                                   #   "advance_on" => { "pix_paid" => "paid", … },
+                                   #   "primary" => "paid", "attribution_window" => "72h" }.
+                                   # The ENGINE never hard-codes a stage name: the fold,
+                                   # the doctor and the Studio read this declaration (D1).
+                                   # nil/absent = no funnel (parity — nothing folds).
+                                   # Deep-stringified like the other free-form hashes;
+                                   # shape-validated by FunnelDeclaration, never here (D8).
+    :followup,                       # the follow-up declaration — pack data,
+                                   # exactly like budget/funnel:
+                                   # { "arm" => "schedule",
+                                   #   "policy" => { "quiet_hours" => { "timezone" => "…",
+                                   #       "start" => "21:30", "end" => "09:00" },
+                                   #     "max_frequency" => "2/24h",
+                                   #     "cancel_keywords" => ["não quero mais contato"],
+                                   #     "silence_after_sends" => 3 } }.
+                                   # The engine OWNS the firing, never a policy value (D1);
+                                   # shape-validated by FollowupPolicy, never here (D9).
+                                   # nil/absent = the feature is off (parity).
+                                   # Deep-stringified like the other free-form hashes.
+    :distill,                        # the session-distillation declaration — pack
+                                   # data, exactly like refinement/followup:
+                                   # { "enabled" => bool, "prompt" => "<pack-authored markdown
+                                   #   — what counts as a fact for this store>",
+                                   #   "model" => "<ref — absent = the platform utility_model>",
+                                   #   "idle_hours" => 6, "min_messages" => 3,
+                                   #   "max_proposals" => 10 }.
+                                   # The ENGINE assembles the scope from the session; the
+                                   # model only names facts (D1). nil/absent = the feature is
+                                   # off (parity, byte-identical engine). Shape-validated by
+                                   # the command/engine, never here (the refinement precedent).
+                                   # Deep-stringified like the other free-form hashes.
+    :harvest                         # the gated-harvest declaration — pack data,
+                                   # exactly like refinement/distill:
+                                   # { "enabled" => bool,
+                                   #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
+                                   #                          "note" => "…" } ],
+                                   #   "miner" => { "model" => "<ref — absent = the platform
+                                   #       utility_model>", "window" => { "last_sessions" => N },
+                                   #       "max_proposals" => N, "budget" => { "tokens" => N } },
+                                   #   "idle_hours" => 24, "min_messages" => 3 }.
+                                   # The ENGINE mines (reads sessions, asks the miner, filters
+                                   # through the negative list + grounding), never authors a
+                                   # rule (D4). nil/absent = the loop is off (parity).
+                                   # Shape-validated by the command/engine/doctor, never here.
+                                   # Deep-stringified like the other free-form hashes.
   )
 
   # Reopened class (not a Data.define block): a constant assigned inside
@@ -116,29 +266,36 @@ module Insika
     DEFAULT_LIMITS = {
       turn_timeout: 300, tool_timeout: 60, provider_timeout: 5,
       context_budget: 8_000, max_tool_calls: 50,
+      # consecutive identical (tool, args) calls that trigger the ONE
+      # loop warning; a repeat after it aborts like max_tool_calls. < 2 = off.
+      max_tool_repeat: 3,
       approval_timeout: 3_600, # cap on the wait for human approval (~1h)
-      # Item 30: parallel tool calls. ONE number is both the switch and the cap
+      # parallel tool calls. ONE number is both the switch and the cap
       # (nil/0/1 = serial, the default; N > 1 = at most N tool calls in flight).
       # It sits next to tool_timeout/max_tool_calls because it is the third bound
       # on tool execution. Read through TurnState#tool_concurrency, which also
-      # applies the approval gate (D3).
+      # applies the approval gate.
       tool_concurrency: 1
     }.freeze
 
-    # `model` is OPTIONAL as of v2 (§10): an agent without one resolves the
+    # `model` is OPTIONAL as of v2: an agent without one resolves the
     # platform `default_model` (Settings) at turn start via the ModelResolver.
     def self.build(id:, model: nil, provider: nil, base_prompt: "", prompt_files: [],
                    tools_allow: nil, tools_deny: [], tools_allow_groups: nil, skills: nil,
-                   context_providers: nil, workflows_allow: nil,
+                   skills_eager: nil, context_providers: nil, workflows_allow: nil,
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
                    capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
-                   prompt_caching: nil,
-                   params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
-                   refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {})
+                   prompt_caching: nil, tool_persistence: nil, tool_output_compression: nil,
+                    params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
+                    refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
+                     budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
+                     outputs: nil, briefing_fields: nil, grounding: nil, funnel: nil,
+                     followup: nil, distill: nil, harvest: nil)
       new(
         id: id, model: model, provider: provider, base_prompt: base_prompt,
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
+        skills_eager: skills_eager,
         context_providers: context_providers, workflows_allow: workflows_allow,
         policies: Array(policies), prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
@@ -147,7 +304,8 @@ module Insika
         # readers get a clean [] and the ChatBuilder gate (present? => wire) is stable.
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
         tools_deferred: tools_deferred, memory: memory,
-        prompt_caching: prompt_caching,
+        prompt_caching: prompt_caching, tool_persistence: tool_persistence,
+        tool_output_compression: tool_output_compression,
         # The free-form hashes arrive with symbol keys (internal build) OR string
         # keys (StoredProfileSource JSON round-trip). Normalize to string keys ONCE
         # here — the single front door every profile passes through — so no reader
@@ -161,10 +319,54 @@ module Insika
         # symbol/string mix there would be a silent miss.
         capabilities_declared: Array(capabilities_declared).map(&:to_s),
         edge_stream: Coercion.deep_stringify(edge_stream || {}),
-        metadata: Coercion.deep_stringify(metadata || {})
+        metadata: Coercion.deep_stringify(metadata || {}),
+        budget: Coercion.deep_stringify(budget),
+        reliability: Coercion.deep_stringify(reliability),
+        alerts: Coercion.deep_stringify(alerts),
+        routes: Coercion.deep_stringify(routes),
+        stuck_signal: stuck_signal,
+        outputs: Coercion.deep_stringify(outputs),
+        # Flat [String] — same discipline as capabilities_declared: a
+        # symbol/string mix would be a silent miss in the provider's known-set.
+        briefing_fields: normalize_briefing_fields(briefing_fields),
+        # grounding is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a Grounding per turn by the validator/
+        # enforcer. nil = off (parity).
+        grounding: Coercion.deep_stringify(grounding),
+        # funnel is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a FunnelDeclaration by the fold/doctor/
+        # Studio (shape-validated THERE, never here — D8). nil = no funnel (parity).
+        funnel: Coercion.deep_stringify(funnel),
+        # followup is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a FollowupPolicy by the tool/engine/
+        # doctor/Studio (shape-validated THERE, never here — D9). nil = off (parity).
+        followup: Coercion.deep_stringify(followup),
+        # distill is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the command/engine/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        distill: Coercion.deep_stringify(distill),
+        # harvest is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the command/engine/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        harvest: Coercion.deep_stringify(harvest)
       )
     end
 
+    # nil -> []; strings; trim + drop empties + uniq (stable order); every name
+    # must match ToolDefinition::NAME_RE (\A[a-z][a-z0-9_]*\z) or it is a
+    # ValidationError at build time — the names become tool-description text,
+    # store keys and context-block lines, so "size ok" or "tamanho do cliente"
+    # is refused here, not corrupted later.
+    def self.normalize_briefing_fields(list)
+      names = Array(list).map { |f| f.to_s.strip }.reject(&:empty?).uniq
+      bad = names.reject { |n| ToolDefinition::NAME_RE.match?(n) }
+      unless bad.empty?
+        raise Insika::ValidationError,
+              "briefing_fields must match #{ToolDefinition::NAME_RE.inspect}: #{bad.join(', ')}"
+      end
+      names
+    end
+
     # opt-in for an optional tool = being in the agent's allow list.
     def tool_opted_in?(name)
       Array(tools_allow).include?(name)
@@ -173,8 +375,8 @@ module Insika
     # store_id of the turn context (ctx.store_id): lives in `metadata` (stable
     # per store, comes from the pack). `build` string-keys metadata, so a plain
     # string lookup is enough. nil = absent (the data-tool emits an empty header).
-    # It is NOT achei-specific: `store_id` is a field of the turn-context contract
-    # (§5), generic per project.
+    # It is NOT consumer-specific: `store_id` is a field of the turn-context contract
+    # generic per project.
     def store_id = (metadata || {})["store_id"]
 
     # May this channel (:thinking / :intermediate) cross to the customer? Tolerant
@@ -182,7 +384,7 @@ module Insika
     # of anything else being absent: the safe reading is the default one.
     def stream_public?(channel)
       v = (edge_stream || {})[channel.to_s]
-      [true, "true", "1", "yes", "on"].include?(v)
+      Coercion.truthy?(v)
     end
   end
 end

data/lib/insika/alert_dispatcher.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Insika
+  # Operator alerts to a webhook (WS6): the events `:budget_warning`,
+  # `:breaker_open` and `:delivery_failed` are answered per AGENT — a profile
+  # declaring `alerts: { "webhook" => url }` gets its alerts POSTed there as
+  # JSON. The delivery reuses the outbox + claim mechanism whole
+  # (`ChannelDelivery`): the handler only WRITES the outbox row; the existing
+  # tick sweep and boot recovery claim and POST it, at-most-once with bounded
+  # retry, via a registered `Channels::Webhook`. The engine transports the event
+  # and does not interpret it — a Slack/CRM adapter is the consumer's.
+  #
+  # Started as a child of the turn supervisor (like the tick) in serving mode;
+  # tests drive `handle` directly.
+  class AlertDispatcher
+    ALERT_TYPES = %i[budget_warning breaker_open delivery_failed].freeze
+
+    def initialize(event_stream:, outbox:, channels:, profiles:, task_store: nil, http:)
+      @event_stream = event_stream
+      @outbox = outbox
+      @channels = channels
+      @profiles = profiles
+      @task_store = task_store
+      @http = http
+      @webhook_ids = {} # url -> registered channel id (one webhook per URL)
+      # WS6 (boot recovery): webhook channels are derived from PROFILE config,
+      # not from events. Registering lazily (on the first alert) means a pending
+      # outbox row a crashed process left is swept at boot against an EMPTY
+      # registry and marked failed terminal. Pre-registering every configured
+      # URL at wiring time lets the boot sweep find the channel and deliver.
+      register_all_webhooks
+    end
+
+    # Serving: a long-lived consumer that answers every alert event. Drains on
+    # the supervisor fiber (blocks on the queue — no spin), exactly like the tick.
+    # It subscribes TYPED (only the alert events enter its queue — it answers
+    # payloads a full-traffic stream would otherwise overflow away) and, on an
+    # overflow close, RE-SUBSCRIBES: a consumer that never re-binds is how alerts
+    # stop in silence (WS6).
+    def start(parent:)
+      parent.async do |t|
+        t.annotate("insika-alerts")
+        loop do
+          subscription = @event_stream.subscribe(types: ALERT_TYPES)
+          subscription.each { |event| handle(event) }
+          # the subscription closed (its overflow path) — alerts must not die here
+        end
+      end
+      true
+    end
+
+    # The event -> outbox row. Cheap (one transactional write); the DELIVERY is
+    # the tick's job. Never raises: an alerting failure must not break the turn.
+    def handle(event)
+      type = event.type.to_s.to_sym
+      return unless ALERT_TYPES.include?(type)
+
+      agent = agent_for(event)
+      return if agent.nil?
+
+      profile = @profiles.respond_to?(:fetch) ? @profiles.fetch(agent.to_s) : nil
+      return if profile.nil?
+
+      url = profile&.respond_to?(:alerts) ? profile.alerts&.dig("webhook") : nil
+      return if Coercion.blank?(url)
+
+      record_alert(agent: agent.to_s, url: url.to_s, event: event)
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    # The agent the alert belongs to: the event carries it for the alerts the
+    # engine emits with context (budget_warning / breaker_open); a
+    # delivery_failed resolves its task's command. Guards the loop: a webhook's
+    # OWN delivery failing is not re-alerted.
+    def agent_for(event)
+      case event.type.to_sym
+      when :delivery_failed
+        channel = event.data[:channel]
+        return nil if channel.to_s.start_with?("webhook:") # loop guard
+        agent_for_task(event.meta[:task_id])
+      else
+        event.data[:agent] || agent_for_task(event.meta[:task_id])
+      end
+    end
+
+    def agent_for_task(task_id)
+      return nil if task_id.nil? || @task_store.nil?
+
+      task = @task_store.find(task_id.to_s)
+      command = task&.respond_to?(:command) ? task.command : nil
+      return nil unless command.is_a?(Hash)
+
+      payload = command["payload"] || command[:payload] || {}
+      payload["agent"] || payload[:agent]
+    rescue StandardError
+      nil
+    end
+
+    # The event's durable record, as the CHANNEL would see it. `to` is the
+    # webhook URL; `payload` is the event itself (type/data/meta).
+    def record_alert(agent:, url:, event:)
+      channel = webhook_id(url)
+      @outbox.create(
+        channel: channel, to: url,
+        task_id: event.meta[:task_id], session_id: event.meta[:session_id],
+        payload: { "type" => event.type.to_s, "data" => event.data,
+                   "meta" => event.meta, "agent" => agent }
+      )
+    end
+
+    # One channel per URL, registered so ChannelDelivery.sweep can claim it.
+    def webhook_id(url)
+      @webhook_ids[url] ||= begin
+        id = "webhook:#{Digest::SHA1.hexdigest(url)[0, 8]}"
+        @channels.register(id, Channels::Webhook.new(url, http: @http))
+        id
+      end
+    end
+
+    # Boot face of `webhook_id`: register every configured URL up front (at
+    # wiring time, before the boot recovery's channel sweep runs). The url is
+    # PROFILE data, so it is known before any alert ever fires.
+    def register_all_webhooks
+      profiles = @profiles.respond_to?(:all) ? @profiles.all : []
+      profiles.each do |profile|
+        next unless profile&.respond_to?(:alerts)
+
+        url = profile.alerts&.dig("webhook")
+        webhook_id(url.to_s) unless Coercion.blank?(url)
+      end
+    end
+  end
+end