comisai 1.0.25 → 1.0.26

package/node_modules/@comis/agent/dist/bootstrap/sections/tool-descriptions.js

@@ -53,7 +53,6 @@ export const TOOL_SUMMARIES = {
     pipeline: "Execute multi-node DAG workflow pipelines",
     session_status: "Show agent status and usage",
     session_search: "Search full session transcript history",
-    agents_list: "List all available agent IDs",
     // Platform
     cron: "Manage cron jobs and reminders",
     gateway: "Read or patch system config",
@@ -81,6 +80,7 @@ export const TOOL_SUMMARIES = {
     channels_manage: "Manage channel adapter status (admin)",
     tokens_manage: "Manage gateway API tokens (admin)",
     models_manage: "List models and test availability",
+    providers_manage: "Manage LLM provider endpoints (admin)",
     skills_manage: "Manage skill registry entries (admin)",
     mcp_manage: "Manage MCP server connections (admin)",
     heartbeat_manage: "Manage agent heartbeat schedules (admin)",
@@ -117,8 +117,7 @@ export const LEAN_TOOL_DESCRIPTIONS = {
         return `Send, reply, react, edit, delete, fetch messages on ${ch}. For inter-session messaging, use sessions_send.`;
     },
     // ----- Sessions -----
-    // Confusable pair: sessions_list / agents_list
-    sessions_list: "List active sessions with filters. For available agent IDs, use agents_list.",
+    sessions_list: "List active sessions with filters. For available agent IDs, use agents_manage({action:'list'}).",
     sessions_history: "Fetch conversation history for another session or sub-agent.",
     // Confusable pair: sessions_send / message
     sessions_send: "Send message to another session. For chat channel messages, use message.",
@@ -128,8 +127,6 @@ export const LEAN_TOOL_DESCRIPTIONS = {
     session_status: "Show agent status card: usage, model, steps. Optional per-session model override.",
     // Confusable pair: session_search / memory_search
     session_search: "Search full session transcript including evicted content. For stored facts, use memory_search.",
-    // Confusable pair: agents_list / sessions_list
-    agents_list: "List available agent IDs for spawning. For active sessions, use sessions_list.",
     // ----- Platform -----
     cron: "Manage cron jobs, scheduled tasks, and reminders.",
     gateway: "Read/patch config, restart gateway, check status.",
@@ -151,7 +148,7 @@ export const LEAN_TOOL_DESCRIPTIONS = {
     ctx_recall: "Recall evicted context entries by semantic query.",
     // ----- Privileged / Supervisor (dynamic: admin suffix) -----
     agents_manage: (ctx) => {
-        const base = "Manage agent fleet: create, get, update, delete, suspend, resume.";
+        const base = "Manage agent fleet: list, create, get, update, delete, suspend, resume. For batch creation, pass workspace.role/identity inline to skip the 2-step write flow.";
         return ctx.trustLevel === "admin" ? base : base + " Admin required.";
     },
     obs_query: (ctx) => {
@@ -177,6 +174,10 @@ export const LEAN_TOOL_DESCRIPTIONS = {
         return ctx.trustLevel === "admin" ? base : base + " Admin required.";
     },
     models_manage: "List available models and test provider availability.",
+    providers_manage: (ctx) => {
+        const base = "Manage LLM providers: list, get, create, update, delete, enable, disable.";
+        return ctx.trustLevel === "admin" ? base : base + " Admin required.";
+    },
     skills_manage: (ctx) => {
         const base = "Manage skill registry: list, reload, enable, disable skills.";
         return ctx.trustLevel === "admin" ? base : base + " Admin required.";
@@ -206,7 +207,7 @@ export const TOOL_ORDER = [
     // Middle (low-frequency): platform actions, privileged, context, media
     "discord_action", "telegram_action", "slack_action", "whatsapp_action",
     "agents_manage", "obs_query", "sessions_manage", "memory_manage",
-    "channels_manage", "tokens_manage", "models_manage", "skills_manage", "mcp_manage", "heartbeat_manage",
+    "channels_manage", "tokens_manage", "models_manage", "providers_manage", "skills_manage", "mcp_manage", "heartbeat_manage",
     "ctx_search", "ctx_inspect", "ctx_expand", "ctx_recall",
     "image_analyze", "tts_synthesize", "transcribe_audio", "describe_video", "extract_document",
     "browser", "gateway",
@@ -215,7 +216,7 @@ export const TOOL_ORDER = [
     "memory_store", "memory_get",
     "web_fetch",
     "sessions_list", "sessions_history", "sessions_send", "sessions_spawn",
-    "subagents", "pipeline", "session_status", "session_search", "agents_list",
+    "subagents", "pipeline", "session_status", "session_search",
     "cron", "process",
     "discover_tools",
 ];
@@ -230,7 +231,28 @@ export const TOOL_ORDER = [
  * Not all tools need guides -- most are self-explanatory from their lean description.
  */
 export const TOOL_GUIDES = {
-    agents_manage: `## Workspace Customization Guide
+    agents_manage: `## Single-call creation (PREFERRED for batch fleet creation)
+For batch creation (multiple agents in one turn) and any case where you already know the agent's role and identity, use the SINGLE-CALL form. This collapses the previous 3-call workflow (create + 2× write) into 1 call per agent — critical when creating fleets of 5+ agents in parallel.
+
+agents_manage({action:"create", agent_id, config:{
+  name, model, provider, maxSteps,
+  workspace:{
+    profile:"full"|"specialist",
+    role:"...persona, role, behavioral guidelines, domain conventions...",      // inline ROLE.md content (max 16384 chars)
+    identity:"...name, creature, vibe, emoji, ethos..."                          // inline IDENTITY.md content (max 4096 chars)
+  },
+  skills?:{...}
+}})
+
+The daemon writes ROLE.md and IDENTITY.md atomically as part of create. The tool result reports inlineWritesResult; on success the next-step contract says "No further setup needed — agent is operationally ready" and you SKIP the write() roundtrip entirely.
+
+## Two-step creation flow (FALLBACK)
+Use this only when role/identity cannot be inlined (e.g. content discovered after create, multi-step interactive design):
+Step 1 — call agents_manage({action:"create", agent_id, config:{name, model, provider, maxSteps, workspace?:{profile:"full"|"specialist"}, skills?:{...}}}). Only those fields are accepted; the schema is z.strictObject so unknown keys are rejected. Do NOT pass persona/role/description/prompt/instructions in create config when omitting the inline form.
+Step 2 — call write({path: "~/.comis/workspace-{agent_id}/ROLE.md", content: "...persona/role/behavioral guidance..."}) to set the agent's role and identity. Use IDENTITY.md for name/creature/vibe/emoji.
+
+Workspace.profile values: "full" or "specialist" ONLY. No "none", "minimal", "compact", or other values.
+## Workspace Customization Guide
 Each agent gets a workspace at ~/.comis/workspace-{agentId}/ with these files:
 IDENTITY.md (CRITICAL): Set Name, Creature, Vibe, Emoji. A filled Name auto-skips onboarding.
 ROLE.md (CRITICAL): Agent role, behavioral guidelines, domain conventions.
@@ -247,7 +269,103 @@ All built-in tools ENABLED by default (except browser). Do NOT disable tools unl
 maxSteps default: 50. Do NOT set below 20.
 ## Batch Creation
 Present a plan to the user before creating agents in batch.
-Multiple agents can be created in one turn. Customize ALL workspace files for each agent after creation.`,
+Multiple agents can be created in one turn. Customize ALL workspace files for each agent after creation — or use single-call creation above to inline ROLE.md/IDENTITY.md and skip the post-create writes entirely.`,
+    providers_manage: `## Provider Configuration Guide
+
+### Built-in vs Custom Provider Check (MANDATORY first step)
+Before creating a custom provider, check if the model already exists in the built-in catalog. Built-in providers (anthropic, google, openai, groq, mistral, deepseek, cerebras, xai, openrouter) already have their models registered — creating a redundant custom entry is wrong and will be ignored. Use models_manage({ action: "list" }) to see available built-in models.
+
+If the model IS built-in: skip provider creation. Just store the API key (gateway env_set) and switch the agent directly.
+If the model is NOT built-in: you need a custom provider. Proceed to the steps below, but first gather ALL required configuration.
+
+### Information Gathering for Custom Providers
+When creating a non-built-in provider, you MUST have: (1) the API base URL, (2) the exact model ID string, (3) the API protocol type. If the user did not supply all three:
+1. Use web_search to look up the provider's API documentation (search for "<provider name> API base URL" or "<provider name> API docs").
+2. If web search finds the information, use it to fill in the missing fields.
+3. If web search does NOT find the information, ask the user to supply the missing fields before proceeding. Do NOT guess or invent URLs.
+
+### Credential Workflow
+API keys are NEVER stored in provider config. Always use this two-step process:
+1. Store the API key: gateway({ action: "env_set", env_key: "<KEY_NAME>", env_value: "<key>" })
+2. Create the provider: providers_manage({ action: "create", provider_id: "<name>", config: { type: "openai", baseUrl: "<url>", apiKeyName: "<KEY_NAME>", models: [{ id: "<model>" }] } })
+
+For local providers (Ollama, LM Studio, vLLM) that don't need API keys, omit apiKeyName.
+
+### After Creating a Provider
+Switch an agent to use the new provider:
+  agents_manage({ action: "update", agent_id: "<id>", config: { provider: "<provider_id>", model: "<model_id>" } })
+
+### Switching an Agent's Provider or Model
+To switch an agent to a different provider/model, call agents_manage update with the new pair:
+  agents_manage({ action: "update", agent_id: "<id>", config: { provider: "<provider_id>", model: "<model_id>" } })
+
+\`agents.*.model\` and \`agents.*.provider\` are listed in MUTABLE_CONFIG_OVERRIDES, so the immutability guard does not block the patch.
+
+**Two preconditions the LLM MUST verify before issuing the update:**
+  1. The target provider exists as a \`providers.entries.<provider_id>\` key. If it does not, call providers_manage create FIRST (and gateway env_set for the API key if needed). Patching an agent to a provider that has no entry resolves under the wrong provider family at the next session — the original bug.
+  2. The model id matches a \`models[].id\` in that provider entry (or is a built-in known to the pi-ai catalog for that provider type). Otherwise \`registry.find(provider, model)\` returns undefined and the next session falls back with a "Model not found" message.
+
+**Timing — the change is NOT hot-applied to the active session.**
+agents_manage update writes through persistToConfig WITHOUT a hot-update callback, which triggers a SIGUSR2 daemon restart (2-second debounce). The new provider/model takes effect on the next session, not the currently-running prompt. Tell the user the switch is queued and will take effect after the daemon settles.
+
+### Configuring Model Failover
+After creating providers, configure automatic failover so the agent recovers from provider outages without user intervention:
+  agents_manage({ action: "update", agent_id: "<id>", config: { modelFailover: { fallbackModels: [{ provider: "<fallback_provider>", modelId: "<fallback_model>" }] } } })
+
+Failover order: primary model > cache-aware short retry (same model) > auth key rotation (same provider) > fallback models in order. Each fallback entry is a { provider, modelId } pair referencing a configured provider.
+
+### Adding vs Replacing a Fallback (read-modify-write)
+\`fallbackModels\` and \`authProfiles\` are **replaced wholesale** on update — the array you send becomes the complete new state. Scalar fields (cooldownInitialMs, maxAttempts, etc.) are deep-merged and preserved.
+
+When the user asks to **add** a fallback to an agent (vs. replace the whole chain), do this:
+  1. agents_manage({ action: "get", agent_id: "<id>" }) > read existing config.modelFailover.fallbackModels
+  2. Append the new { provider, modelId } entry to that array (preserving order)
+  3. agents_manage({ action: "update", agent_id: "<id>", config: { modelFailover: { fallbackModels: [...existing, ...new] } } })
+
+Same pattern applies to authProfiles. Skipping the read step silently drops previously-configured fallbacks. When the user says "set" / "use" / "switch fallback to X", a direct overwrite is correct; when they say "add" / "also" / "in addition", read first.
+
+To add auth key rotation for rate-limited providers (multiple API keys for the same provider):
+  1. Store additional keys: gateway({ action: "env_set", env_key: "ANTHROPIC_API_KEY_2", env_value: "<key>" })
+  2. Configure auth profiles: agents_manage({ action: "update", agent_id: "<id>", config: { modelFailover: { authProfiles: [{ keyName: "ANTHROPIC_API_KEY_2", provider: "anthropic" }] } } })
+
+### Provider Types
+The "type" field selects the SDK code path (API protocol). Common values:
+- **openai** — Any OpenAI-compatible endpoint: NVIDIA NIM, Groq, Together, Fireworks, Perplexity, DeepSeek, vLLM, LM Studio, llama.cpp, or any custom endpoint
+- **anthropic** — Anthropic Claude API
+- **google** — Google Gemini API
+- **ollama** — Local Ollama server
+- **mistral** — Mistral AI API
+- **groq** — Groq API (also works with type "openai")
+- **together** — Together AI API
+- **deepseek** — DeepSeek API (also works with type "openai")
+- **cerebras** — Cerebras API
+- **xai** — xAI Grok API
+- **openrouter** — OpenRouter multi-provider gateway
+
+When in doubt, use type "openai" with a custom baseUrl — most third-party and self-hosted providers speak the OpenAI API format.
+
+### Local Providers (no API key)
+For local inference servers, set baseUrl to the local endpoint and omit apiKeyName:
+  providers_manage({ action: "create", provider_id: "local-ollama", config: { type: "ollama", baseUrl: "http://localhost:11434", models: [{ id: "llama3.3" }] } })
+
+### Models
+Only the model "id" is required. All other fields (name, contextWindow, maxTokens, reasoning, input) are optional and will be filled with defaults.
+
+### Adding vs Replacing a Model (read-modify-write)
+\`models\` is **replaced wholesale** on update — the array you send becomes the complete new state. To **add** a model to an existing provider (vs. replace the whole list):
+  1. providers_manage({ action: "get", provider_id: "<id>" }) > read existing config.models
+  2. Append the new { id: "<new-model>" } entry to that array (preserving order)
+  3. providers_manage({ action: "update", provider_id: "<id>", config: { models: [...existing, {id: "<new-model>"}] } })
+
+When the user says "add" / "also" / "in addition", read first. When they say "set" / "replace" / "use only", a direct overwrite is correct. Same pattern as agents_manage's modelFailover.fallbackModels.
+
+\`headers\` follows a different rule: it is **shallow-merged per key**, so adding one custom header does NOT erase others — direct \`{ headers: { "X-New": "v" } }\` updates work without read-modify-write.
+
+### Clearing a Field
+\`persistToConfig\` cannot remove keys via patch — only set or replace. To clear an apiKeyName (e.g., to convert a cloud provider to keyless), the recipe is: disable > delete > recreate without apiKeyName. Direct YAML edits also work for operators with shell access.
+
+### Fleet-Wide Operations
+providers_manage and agents_manage operate on one entity at a time. For fleet-wide provider/model/failover changes: (1) create new provider(s) first, (2) agents_manage list to discover agents, (3) agents_manage update x N in parallel (one call per agent in the same turn). Group agents by model tier for tiered failover (e.g. opus agents get different fallbacks than sonnet agents).`,
     pipeline: `## Pipeline Usage Guide
 Use 'define' action first to validate graph structure before save/execute.
 CRITICAL: A node receives ONLY the outputs from nodes listed in its depends_on. This is the sole data flow mechanism -- there is no shared state. For fan-in, list ALL required upstream sources in each consumer's depends_on. If node C needs outputs from both A and B, set depends_on: ["A", "B"] -- depending only on an intermediate node that consumed A and B does NOT propagate their outputs.
@@ -476,10 +594,12 @@ calling a gated action will pause execution until the operator approves or denie
 - memory_manage: delete, flush
 - channels_manage: enable, disable, restart
 - tokens_manage: create, revoke, rotate
+- providers_manage: create, delete
 
 **Read-only (no approval needed):**
 - obs_query: all actions (diagnostics, billing, traces, activity)
 - models_manage: all actions (list models, test availability)
+- providers_manage: list, get, update, enable, disable, set_default, test
 - agents_manage: get, update, suspend, resume
 - sessions_manage: export, compact
 - memory_manage: stats, browse, export

package/node_modules/@comis/agent/dist/bootstrap/sections/tooling-sections.d.ts

@@ -32,7 +32,7 @@ export declare function buildCompactedOutputRecoverySection(isMinimal: boolean):
  * @param deferred - When true, returns empty (content delivered via JIT tool result injection).
  */
 export declare function buildCodingFallbackSection(toolNames: string[], isMinimal: boolean, deferred?: boolean): string[];
-/** The 10 privileged/supervisor tool names. */
+/** The 11 privileged/supervisor tool names. */
 export declare const PRIVILEGED_TOOL_NAMES: string[];
 /**
  * Build the Privileged Tools & Approval Gate section.

package/node_modules/@comis/agent/dist/bootstrap/sections/tooling-sections.js

@@ -200,10 +200,10 @@ export function buildCodingFallbackSection(toolNames, isMinimal, deferred) {
 // ---------------------------------------------------------------------------
 // 5b. Privileged Tools & Approval Gate (skip if minimal or no privileged tools)
 // ---------------------------------------------------------------------------
-/** The 10 privileged/supervisor tool names. */
+/** The 11 privileged/supervisor tool names. */
 export const PRIVILEGED_TOOL_NAMES = [
     "agents_manage", "obs_query", "sessions_manage", "memory_manage",
-    "channels_manage", "tokens_manage", "models_manage",
+    "channels_manage", "tokens_manage", "models_manage", "providers_manage",
     "skills_manage", "mcp_manage", "heartbeat_manage",
 ];
 /**
@@ -328,6 +328,7 @@ export function buildPrivilegedToolsSection(toolNames, isMinimal, deferred) {
         "- memory_manage: delete, flush",
         "- channels_manage: enable, disable, restart",
         "- tokens_manage: create, revoke, rotate",
+        "- providers_manage: create, delete",
         "",
         "**Read-only (no approval needed):**",
         "- obs_query: all actions (diagnostics, billing, traces, activity)",
@@ -337,6 +338,7 @@ export function buildPrivilegedToolsSection(toolNames, isMinimal, deferred) {
         "- memory_manage: stats, browse, export",
         "- channels_manage: list, get",
         "- tokens_manage: list",
+        "- providers_manage: list, get, update, enable, disable",
         "",
         "### Approval Gate Behavior",
         "",
@@ -358,6 +360,11 @@ export function buildPrivilegedToolsSection(toolNames, isMinimal, deferred) {
         "- **Reset vs delete session**: Reset clears messages but keeps the session identity (good for \"start fresh\"). Delete archives the transcript and removes the session entirely.",
         "- **Memory delete vs flush**: Delete removes specific entries by ID (surgical). Flush removes all entries for a scope (nuclear -- use with caution, requires approval).",
         "- **Token rotation**: Prefer rotate over revoke+create -- rotation is atomic and prevents downtime.",
+        "- **Built-in first**: Before creating a custom provider, check if the model is already built-in (models_manage list). Built-in providers (anthropic, google, openai, groq, mistral, deepseek, cerebras, xai, openrouter) need only an API key — no custom provider entry. Only create a custom provider for models NOT in the built-in catalog.",
+        "- **Provider then agent**: When adding a custom (non-built-in) provider, first create the provider entry (providers_manage create), store the API key if needed (gateway env_set -- skip for keyless providers like Ollama), then switch the agent (agents_manage update). Never set an agent's model to a name that has no matching provider. If you lack the provider's base URL or model ID, use web_search to find it; if that fails, ask the user.",
+        "- **Failover chain**: After creating multiple providers, configure automatic model failover on the agent (agents_manage update with modelFailover.fallbackModels). Each fallback entry is a {provider, modelId} pair referencing a configured provider. Failover order: primary > cache-aware retry > auth key rotation > fallback models in order. Never add a fallback model whose provider does not exist.",
+        "- **Add vs replace fallback**: modelFailover.fallbackModels and authProfiles are REPLACED wholesale on update (scalar fields deep-merge; arrays do not). When the user says 'add' / 'also' / 'in addition', call agents_manage get FIRST to read the current array, append, then update with the full list. When the user says 'set' / 'use' / 'switch to', overwrite directly.",
+        "- **Fleet-wide changes**: providers_manage and agents_manage operate on one entity at a time. For fleet-wide provider/model/failover changes: (1) create new provider(s) first, (2) agents_manage list to discover agents, (3) agents_manage update x N in parallel (one call per agent in the same turn). Group agents by model tier for tiered failover (e.g. opus agents get different fallbacks than sonnet agents).",
     ];
     return lines;
 }

package/node_modules/@comis/agent/dist/bridge/bridge-metrics.d.ts

@@ -10,6 +10,7 @@
  */
 import type { ExecutionResult } from "../executor/types.js";
 import type { ContextUsageData } from "../safety/context-window-guard.js";
+import type { ThinkingBlockHash } from "./thinking-block-hash-invariant.js";
 /** Internal metrics state managed by the bridge. */
 export interface BridgeMetricsState {
     totalInputTokens: number;
@@ -56,6 +57,13 @@ export interface BridgeMetricsState {
     sessionCumulativeCacheSavedUsd: number;
     totalThinkingTokens: number;
     budgetWarningEmitted: boolean;
+    thinkingBlockHashes: Map<string, ThinkingBlockHash[]>;
+    /** 260428-hoy: Canonical (pre-mutation) snapshot of each assistant message's
+     *  full content array, captured at stream close in lockstep with thinkingBlockHashes.
+     *  Keyed by responseId; capped at 32 with FIFO eviction in lockstep with the
+     *  hash store. Used by the pre-LLM-call restoration pass to heal cross-turn
+     *  mutation of signed thinking blocks before pi-ai serializes the next request. */
+    thinkingBlockCanonical: Map<string, ReadonlyArray<unknown>>;
 }
 /**
  * Create a fresh metrics state with all counters zeroed.

package/node_modules/@comis/agent/dist/bridge/bridge-metrics.js

@@ -51,6 +51,8 @@ export function createBridgeMetrics() {
         sessionCumulativeCacheSavedUsd: 0,
         totalThinkingTokens: 0,
         budgetWarningEmitted: false,
+        thinkingBlockHashes: new Map(),
+        thinkingBlockCanonical: new Map(),
     };
 }
 /**

package/node_modules/@comis/agent/dist/bridge/pi-event-bridge.d.ts

@@ -20,6 +20,7 @@ import type { ProviderHealthMonitor } from "../safety/provider-health-monitor.js
 import type { ContextWindowGuard, ContextUsageData } from "../safety/context-window-guard.js";
 import type { ExecutionResult } from "../executor/types.js";
 import type { ExecutionPlan } from "../planner/types.js";
+import { type ThinkingBlockHash } from "./thinking-block-hash-invariant.js";
 /** Per-call TTL split estimate, populated by requestBodyInjector's onPayload.
  *  Shared mutable object — written by the stream wrapper, read by the bridge. */
 export interface TtlSplitEstimate {
@@ -126,6 +127,24 @@ export interface PiEventBridgeDeps {
      *  on each API call, read by the bridge on turn_end for per-TTL cost calculation.
      *  The bridge normalizes these estimates against the actual SDK-reported cacheWriteTokens. */
     ttlSplit?: TtlSplitEstimate;
+    /** 260428-hoy pre-call hook: invoked once per `turn_start` event, BEFORE
+     *  pi-ai serializes the next request. The closure (defined in pi-executor)
+     *  walks `session.agent.state.messages`, asserts the cross-turn
+     *  hash-invariant per assistant message with a stored hash entry (logs
+     *  ERROR on mutation), then runs the canonical-restore helper against the
+     *  canonical store (heals any mutation in-place by writing the result
+     *  back to `session.agent.state.messages`). The return value is unused by
+     *  the bridge -- the side effect is the heal write-back. Optional: when
+     *  omitted, both the diagnostic and the heal are silently disabled
+     *  (e.g., unit tests that don't drive a full agent session). */
+    getSessionMessages?: () => ReadonlyArray<unknown> | undefined;
+    /** 260428-iag wire-edge diagnostic: returns the absolute path to the
+     *  per-session JSONL on disk. The bridge invokes this only when the LLM
+     *  error path detects the signed-replay rejection signature, then
+     *  diff'd against the persisted canonical to surface mutation that
+     *  occurred AFTER the bridge's restoration hook. Optional — when
+     *  omitted, the wire-edge diagnostic is a silent no-op. */
+    getSessionJsonlPath?: () => string | null;
 }
 /** Estimated cost payload for a timed-out API request. */
 export interface GhostCostEstimate {
@@ -167,6 +186,16 @@ export interface PiEventBridgeResult {
     };
     /** Accumulate estimated cost from a timed-out API request. */
     addGhostCost: (estimated: GhostCostEstimate) => void;
+    /** 260428-hoy: ReadonlyMap views of the per-responseId hash store and
+     *  canonical-snapshot store, both populated at stream-close in lockstep.
+     *  The executor's pre-LLM-call closure reads both stores to drive the
+     *  hash-invariant assertion plus the canonical restore helper. Returns
+     *  ReadonlyMap views to preserve internal-state encapsulation -- the
+     *  underlying `m` object is never exported. */
+    getThinkingBlockStores: () => {
+        hashes: ReadonlyMap<string, ReadonlyArray<ThinkingBlockHash>>;
+        canonical: ReadonlyMap<string, ReadonlyArray<unknown>>;
+    };
 }
 export { sanitizeToolArgs, extractErrorText } from "./bridge-event-handlers.js";
 /**

package/node_modules/@comis/agent/dist/bridge/pi-event-bridge.js

@@ -20,6 +20,7 @@ import { extractPlanFromResponse } from "../planner/plan-extractor.js";
 import { extractMcpServerName, classifyMcpErrorType, sanitizeToolArgs, extractErrorText } from "./bridge-event-handlers.js";
 import { createBridgeMetrics, buildBridgeResult } from "./bridge-metrics.js";
 import { checkStepLimit, emitStepLimitAbort, checkBudgetLimit, emitBudgetAbort, checkBudgetTrajectory, checkContextWindow, emitContextAbort, checkCircuitBreaker, emitCircuitBreakerAbort } from "./bridge-safety-controls.js";
+import { computeThinkingBlockHashes, diffThinkingBlocksAgainstPersisted, WIRE_DIFF_HINT_FILE_MISSING, WIRE_DIFF_HINT_NOT_FOUND, } from "./thinking-block-hash-invariant.js";
 // Re-export helper functions for backward compatibility with existing imports
 export { sanitizeToolArgs, extractErrorText } from "./bridge-event-handlers.js";
 // ---------------------------------------------------------------------------
@@ -217,6 +218,88 @@ export function createPiEventBridge(deps) {
                     break;
                 }
                 // -----------------------------------------------------------------
+                // LLM turn about to start (pre-serialize hook for assert+restore)
+                // -----------------------------------------------------------------
+                case "turn_start": {
+                    // 260428-hoy: Run the executor-supplied pre-call closure once per
+                    // turn, before pi-ai reads `session.agent.state.messages` to
+                    // serialize the next API request. The closure performs the
+                    // assert-then-restore pass over the live transcript and writes the
+                    // healed array back into session state when at least one swap
+                    // happens, so the bytes Anthropic sees match the canonical
+                    // stream-close snapshot. The closure swallows its own throws; the
+                    // wrapper here is belt-and-braces.
+                    //
+                    // 260428-j0v: ALWAYS emit ONE INFO log carrying the counters the
+                    // bridge can derive — even when the closure is unwired or returns
+                    // undefined / no candidates. This closes the silent-success
+                    // ambiguity observed on trace c5680133 where ZERO agent.bridge.*
+                    // events appeared despite the helpers having shipped.
+                    //
+                    // Counters are computed by the bridge's own walk of the messages
+                    // returned by the closure (or empty when unwired) so the executor
+                    // closure stays untouched. `mismatchesLogged` and `restoredCount`
+                    // are derived from positional hash diffs — they equal the work the
+                    // closure's helpers actually emit/heal.
+                    const hashStoreSize = m.thinkingBlockHashes.size;
+                    const canonicalStoreSize = m.thinkingBlockCanonical.size;
+                    let candidatesChecked = 0;
+                    let mismatchesLogged = 0;
+                    let anyResponseIdMatched = false;
+                    if (deps.getSessionMessages) {
+                        let liveBeforeClosure;
+                        try {
+                            liveBeforeClosure = deps.getSessionMessages();
+                        }
+                        catch {
+                            // Pre-call hook must NEVER abort agent flow.
+                            liveBeforeClosure = undefined;
+                        }
+                        if (Array.isArray(liveBeforeClosure)) {
+                            for (const msg of liveBeforeClosure) {
+                                if (!msg || typeof msg !== "object")
+                                    continue;
+                                const sm = msg;
+                                if (sm.role !== "assistant")
+                                    continue;
+                                if (typeof sm.responseId !== "string")
+                                    continue;
+                                const prior = m.thinkingBlockHashes.get(sm.responseId);
+                                if (!prior)
+                                    continue;
+                                candidatesChecked++;
+                                anyResponseIdMatched = true;
+                                const currentBlocks = Array.isArray(sm.content)
+                                    ? sm.content
+                                    : [];
+                                const currentHashes = computeThinkingBlockHashes(currentBlocks);
+                                const byIndex = new Map();
+                                for (const h of currentHashes)
+                                    byIndex.set(h.blockIndex, h);
+                                for (const old of prior) {
+                                    const now = byIndex.get(old.blockIndex);
+                                    if (!now || now.hash !== old.hash)
+                                        mismatchesLogged++;
+                                }
+                            }
+                        }
+                    }
+                    // restoredCount equals mismatchesLogged in the current symmetric
+                    // implementation; surfaced as a separate field so future asymmetric
+                    // assert/restore semantics are observable.
+                    const restoredCount = mismatchesLogged;
+                    deps.logger.info({
+                        module: "agent.bridge.hash-invariant",
+                        candidatesChecked,
+                        mismatchesLogged,
+                        restoredCount,
+                        anyResponseIdMatched,
+                        hashStoreSize,
+                        canonicalStoreSize,
+                    }, "Pre-call assertion ran");
+                    break;
+                }
+                // -----------------------------------------------------------------
                 // LLM turn completed
                 // -----------------------------------------------------------------
                 case "turn_end": {
@@ -253,6 +336,41 @@ export function createPiEventBridge(deps) {
                                     thinkingLen: typeof b.thinking === "string" ? b.thinking.length : 0,
                                 })),
                             }, "Assistant message block accounting at stream close");
+                            // Bug A diagnostic + 260428-hoy heal: capture hashes AND a
+                            // canonical (pre-mutation) snapshot of the full content array,
+                            // keyed by responseId, in lockstep across both stores. The
+                            // hash store powers the assertion ERROR log (mutation
+                            // diagnostic); the canonical store powers the pre-call
+                            // restore pass that heals cross-turn mutation before the next
+                            // API serialize. Both stores are FIFO-evicted at 32 entries
+                            // in lockstep so they always share the same keyset.
+                            if (typeof responseIdForLog === "string") {
+                                const hashes = computeThinkingBlockHashes(blocks);
+                                if (hashes.length > 0) {
+                                    while (m.thinkingBlockHashes.size >= 32) {
+                                        const oldestKey = m.thinkingBlockHashes.keys().next().value;
+                                        if (oldestKey === undefined)
+                                            break;
+                                        m.thinkingBlockHashes.delete(oldestKey);
+                                        m.thinkingBlockCanonical.delete(oldestKey);
+                                    }
+                                    m.thinkingBlockHashes.set(responseIdForLog, hashes);
+                                    // 260428-hoy: capture canonical (pre-mutation) full
+                                    // content array so the pre-LLM-call restore pass can heal
+                                    // any cross-turn mutation before pi-ai serializes the
+                                    // next request. structuredClone is a Node 22 global; the
+                                    // try/catch is defensive against rare exotic input shapes.
+                                    try {
+                                        const canonical = Object.freeze(structuredClone(blocks));
+                                        m.thinkingBlockCanonical.set(responseIdForLog, canonical);
+                                    }
+                                    catch {
+                                        // Canonical capture failure is non-fatal: the hash store
+                                        // still fires the assertion diagnostic on resend; only
+                                        // the heal step degrades to no-op for this responseId.
+                                    }
+                                }
+                            }
                         }
                     }
                     // Compute LLM latency: turn wallclock minus tool execution time
@@ -580,7 +698,6 @@ export function createPiEventBridge(deps) {
                                     request: (deps.sepMessageText ?? "").slice(0, 200),
                                     steps,
                                     completedCount: 0,
-                                    nudged: false,
                                     createdAtMs: Date.now(),
                                 };
                                 deps.executionPlan.current = plan;
@@ -741,6 +858,122 @@ export function createPiEventBridge(deps) {
                         hint: "Check LLM provider status",
                         errorKind: "dependency",
                     }, "LLM call returned error");
+                    // 260428-iag wire-edge diagnostic: when the LLM error matches the
+                    // Anthropic signed-replay rejection signature ("thinking blocks ...
+                    // cannot be modified"), diff the in-memory content against the
+                    // persisted JSONL canonical and emit one ERROR per divergent block.
+                    // Fully async / fire-and-forget — never blocks the existing error
+                    // path. Silent no-op when the signature doesn't match or when
+                    // either getSessionMessages / getSessionJsonlPath is unwired.
+                    //
+                    // 260428-j0v: ALWAYS emit ONE dispatch-decision INFO log carrying
+                    // boolean flags that explain WHY the wire-diff dispatch was or was
+                    // not entered (regex match, candidate count, callback presence) —
+                    // even when regexMatched is false or callbacks are unwired. When
+                    // the dispatch IS entered, emit a second dispatch-completion INFO
+                    // after the async candidates loop completes.
+                    //
+                    // The signature regex matches Anthropic's actual 400 message:
+                    // "messages.N.content.M: thinking blocks cannot be modified"
+                    // and the redacted_thinking variant. Both `thinking|redacted_thinking`
+                    // AND `modif|cannot` must be present to avoid false positives on
+                    // unrelated 400s (rate limits, auth, schema errors).
+                    {
+                        const errMsg = m.lastLlmErrorMessage;
+                        const regexMatched = typeof errMsg === "string" &&
+                            /thinking|redacted_thinking/.test(errMsg) &&
+                            /modif|cannot/.test(errMsg);
+                        const liveForDecision = deps.getSessionMessages?.();
+                        const jsonlPathForDecision = deps.getSessionJsonlPath?.();
+                        const candidates = [];
+                        if (Array.isArray(liveForDecision)) {
+                            for (let i = liveForDecision.length - 1; i >= 0 && candidates.length < 3; i--) {
+                                // eslint-disable-next-line security/detect-object-injection -- numeric loop index
+                                const msg = liveForDecision[i];
+                                if (!msg || typeof msg !== "object")
+                                    continue;
+                                if (msg.role !== "assistant")
+                                    continue;
+                                if (typeof msg.responseId !== "string")
+                                    continue;
+                                if (!Array.isArray(msg.content))
+                                    continue;
+                                const blocks = msg.content;
+                                const hasSigned = blocks.some((b) => b.type === "thinking" &&
+                                    typeof b.thinkingSignature === "string" &&
+                                    b.thinkingSignature.length > 0 &&
+                                    b.redacted !== true);
+                                if (!hasSigned)
+                                    continue;
+                                candidates.push({ responseId: msg.responseId, content: blocks });
+                            }
+                        }
+                        const jsonlPathPresent = typeof jsonlPathForDecision === "string" && jsonlPathForDecision.length > 0;
+                        deps.logger.info({
+                            module: "agent.bridge.wire-diff",
+                            regexMatched,
+                            candidatesFound: candidates.length,
+                            jsonlPathPresent,
+                            getSessionMessagesPresent: typeof deps.getSessionMessages === "function",
+                            getSessionJsonlPathPresent: typeof deps.getSessionJsonlPath === "function",
+                        }, "Wire-edge diff dispatch decision");
+                        if (regexMatched && jsonlPathPresent && candidates.length > 0) {
+                            const capturedJsonlPath = jsonlPathForDecision;
+                            // Async non-blocking dispatch -- never blocks the error path.
+                            void Promise.resolve().then(async () => {
+                                let candidatesProcessed = 0;
+                                let totalDivergences = 0;
+                                let persistedNotFound = 0;
+                                let fileReadErrors = 0;
+                                // Wrapped logger forwards to deps.logger AND counts the
+                                // helper's WARN outcomes by hint-constant identity (no regex).
+                                const countingLogger = {
+                                    warn: (obj, msg) => {
+                                        deps.logger.warn(obj, msg);
+                                        if (obj.hint === WIRE_DIFF_HINT_FILE_MISSING)
+                                            fileReadErrors++;
+                                        else if (obj.hint === WIRE_DIFF_HINT_NOT_FOUND)
+                                            persistedNotFound++;
+                                    },
+                                };
+                                try {
+                                    for (const c of candidates) {
+                                        candidatesProcessed++;
+                                        const entries = await diffThinkingBlocksAgainstPersisted(c.content, c.responseId, capturedJsonlPath, { logger: countingLogger });
+                                        totalDivergences += entries.length;
+                                        for (const entry of entries) {
+                                            deps.logger.error({
+                                                module: "agent.bridge.wire-diff",
+                                                responseId: c.responseId,
+                                                blockIndex: entry.blockIndex,
+                                                persistedHash: entry.persistedHash,
+                                                inMemoryHash: entry.inMemoryHash,
+                                                persistedText: entry.persistedText,
+                                                inMemoryText: entry.inMemoryText,
+                                                persistedSigLen: entry.persistedSigLen,
+                                                inMemorySigLen: entry.inMemorySigLen,
+                                                errorKind: "internal",
+                                                hint: "Mutation occurred between bridge restoration hook and " +
+                                                    "pi-ai serialization — likely inside pi-ai or its dependencies",
+                                            }, "Wire-edge thinking-block divergence vs persisted JSONL");
+                                        }
+                                    }
+                                }
+                                catch {
+                                    // Diagnostic must NEVER abort the error path.
+                                }
+                                // ALWAYS emit the completion INFO, even on totalDivergences=0
+                                // or when every helper call hit a read error.
+                                deps.logger.info({
+                                    module: "agent.bridge.wire-diff",
+                                    candidatesProcessed,
+                                    totalDivergences,
+                                    persistedNotFound,
+                                    fileReadErrors,
+                                }, "Wire-edge diff dispatch complete");
+                            });
+                        }
+                    }
                     deps.circuitBreaker.recordFailure();
                     deps.providerHealth?.recordFailure(deps.provider, deps.agentId);
                     // If circuit breaker just opened, abort mid-execution
@@ -772,5 +1005,12 @@ export function createPiEventBridge(deps) {
         m.ghostCostUsd += estimated.costUsd;
         m.timedOutRequests += 1;
     };
-    return { listener, getResult, addGhostCost };
+    // 260428-hoy: typed ReadonlyMap accessor for the executor's pre-call
+    // closure. Returns views over the live maps -- the executor never receives
+    // the mutable `m` object itself.
+    const getThinkingBlockStores = () => ({
+        hashes: m.thinkingBlockHashes,
+        canonical: m.thinkingBlockCanonical,
+    });
+    return { listener, getResult, addGhostCost, getThinkingBlockStores };
 }