comisai 1.0.34 → 1.0.37

package/node_modules/@comis/agent/dist/model/operation-model-defaults.d.ts

@@ -12,9 +12,10 @@
  *    (because the old map was Anthropic/OpenAI/Google only).
  *
  * Tier picking: filter to text-capable models with non-zero cost, sort
- * ascending by total cost (input + output), pick 10th-percentile = `fast`,
- * 50th-percentile = `mid`. All-free-models providers (e.g. local Ollama,
- * Z.AI most models) fall back to "first text-capable id" for both slots.
+ * ascending by total cost (input + output), pick top-of-cohort (lex-greatest
+ * within the cost bucket) at the 10th-percentile = `fast`, 50th-percentile =
+ * `mid`. All-free-models providers (e.g. local Ollama, Z.AI most models)
+ * fall back to "first text-capable id" for both slots.
  *
  * @module
  */
@@ -32,7 +33,11 @@ import type { ModelOperationType } from "@comis/core";
  *   3. Filter to non-zero cost (eliminates free/local-only models from
  *      ranking — they won't be reachable in production).
  *   4. Sort ascending by total cost.
- *   5. `fast` = 10th percentile, `mid` = 50th percentile.
+ *   5. `fast` and `mid` are top-of-cohort at the 10th and 50th percentile
+ *      respectively (lex-greatest ID within the cost bucket the percentile
+ *      lands in). Cost ties broken by lex-greatest ID — avoids picking a
+ *      model purely because of catalog iteration order (e.g. 9 Anthropic
+ *      Sonnets all at $18/MTok).
  *   6. If post-filter set is empty (all-free provider), use the first
  *      text-capable model id for both slots.
  *

package/node_modules/@comis/agent/dist/model/operation-model-defaults.js

@@ -13,9 +13,10 @@
  *    (because the old map was Anthropic/OpenAI/Google only).
  *
  * Tier picking: filter to text-capable models with non-zero cost, sort
- * ascending by total cost (input + output), pick 10th-percentile = `fast`,
- * 50th-percentile = `mid`. All-free-models providers (e.g. local Ollama,
- * Z.AI most models) fall back to "first text-capable id" for both slots.
+ * ascending by total cost (input + output), pick top-of-cohort (lex-greatest
+ * within the cost bucket) at the 10th-percentile = `fast`, 50th-percentile =
+ * `mid`. All-free-models providers (e.g. local Ollama, Z.AI most models)
+ * fall back to "first text-capable id" for both slots.
  *
  * @module
  */
@@ -29,6 +30,31 @@ const _nativeProviderSet = new Set(getProviders());
 function totalCost(m) {
     return (m.cost?.input ?? 0) + (m.cost?.output ?? 0);
 }
+/**
+ * Pick the "top of cohort" model from a cost-ascending list.
+ *
+ * Identifies the cost bucket the given percentile lands in, then returns
+ * the lex-greatest ID within that bucket. Lex-greatest is a deterministic
+ * proxy for "newest/highest version" across the providers we ship — for
+ * dated IDs (YYYY-MM-DD, YYMM) and semver-ish IDs (claude-sonnet-4-6 >
+ * claude-sonnet-4-5) the lex order matches recency.
+ *
+ * Why not just take `sortedAsc[idx]`? JavaScript's stable sort preserves
+ * original-array order within a cost-tied block, so the previous algorithm
+ * picked whatever the catalog happened to enumerate first. With 9 priced
+ * Anthropic Sonnets all at $18/MTok, that was `claude-sonnet-4-5` — picked
+ * by accident, not by quality signal.
+ *
+ * Module-internal — not exported.
+ */
+function pickFromCohort(sortedAsc, percentile) {
+    if (sortedAsc.length === 0)
+        return undefined;
+    const idx = Math.min(sortedAsc.length - 1, Math.floor(sortedAsc.length * percentile));
+    const cohortCost = totalCost(sortedAsc[idx]);
+    const cohort = sortedAsc.filter((m) => totalCost(m) === cohortCost);
+    return [...cohort].sort((a, b) => b.id.localeCompare(a.id))[0]?.id;
+}
 /**
  * Resolve cost-tier model defaults for a given native pi-ai provider.
  *
@@ -42,7 +68,11 @@ function totalCost(m) {
  *   3. Filter to non-zero cost (eliminates free/local-only models from
  *      ranking — they won't be reachable in production).
  *   4. Sort ascending by total cost.
- *   5. `fast` = 10th percentile, `mid` = 50th percentile.
+ *   5. `fast` and `mid` are top-of-cohort at the 10th and 50th percentile
+ *      respectively (lex-greatest ID within the cost bucket the percentile
+ *      lands in). Cost ties broken by lex-greatest ID — avoids picking a
+ *      model purely because of catalog iteration order (e.g. 9 Anthropic
+ *      Sonnets all at $18/MTok).
  *   6. If post-filter set is empty (all-free provider), use the first
  *      text-capable model id for both slots.
  *
@@ -67,12 +97,9 @@ export function resolveOperationDefaults(provider) {
         const fallback = textCapable[0]?.id;
         return { fast: fallback, mid: fallback };
     }
-    // Math.min clamp guards single-element arrays (10% of 1 -> 0).
-    const fastIdx = Math.min(priced.length - 1, Math.floor(priced.length * 0.1));
-    const midIdx = Math.min(priced.length - 1, Math.floor(priced.length * 0.5));
     return {
-        fast: priced[fastIdx].id,
-        mid: priced[midIdx].id,
+        fast: pickFromCohort(priced, 0.1),
+        mid: pickFromCohort(priced, 0.5),
     };
 }
 // ---------------------------------------------------------------------------

package/node_modules/@comis/agent/dist/model/resolve-provider-api-key.d.ts

@@ -0,0 +1,48 @@
+/**
+ * resolveProviderApiKey: shared dispatch helper that routes OAuth-eligible
+ * providers through the OAuthTokenManager + AuthStorage.setRuntimeApiKey
+ * side-effect, and non-OAuth providers through the existing authStorage path.
+ *
+ * Single attachment surface for the per-LLM-call OAuth dispatch
+ * hook. Used by PiExecutor.execute() pre-hook (primary LLM call) and the two
+ * compaction getApiKey callbacks in executor-context-engine-setup.ts.
+ *
+ * Return shape is `Promise<string>` (NOT `Result<T,E>`) because the helper
+ * bridges Comis's Result-typed manager with pi-coding-agent's
+ * `AuthStorage.getApiKey` contract; the throw mirrors pi-coding-agent's own
+ * throw-on-failure shape. On OAuthError the helper propagates a thrown Error —
+ * no env-var fallback, no retry, no silent rotation. Outer callers
+ * (PiExecutor.execute, gateway routes) surface the throw to the user via their
+ * existing error-handling path.
+ *
+ * @module
+ */
+import type { AuthStorage } from "@mariozechner/pi-coding-agent";
+import type { PerAgentConfig } from "@comis/core";
+import type { OAuthTokenManager } from "./oauth-token-manager.js";
+/** Dependencies for the resolveProviderApiKey helper. */
+export interface ResolveProviderApiKeyDeps {
+    /** pi-coding-agent AuthStorage instance for non-OAuth providers and the
+     *  runtime-override target on the OAuth path. */
+    authStorage: AuthStorage;
+    /** OAuthTokenManager from auth-provider.ts. When undefined the helper
+     *  defensively falls through to authStorage even for OAuth-eligible
+     *  providers — matches the "OAuth wiring not yet provided" boot path. */
+    oauthManager?: OAuthTokenManager;
+    /** Per-agent config carrying optional `oauthProfiles` map. Forwarded to
+     *  `OAuthTokenManager.getApiKey` as the agentContext argument so the
+     *  manager's resolver chain (agent-config -> lastGood -> first available)
+     *  observes per-agent profile preference on every call. */
+    agentConfig?: PerAgentConfig;
+}
+/**
+ * Resolve the API key for a provider, routing OAuth-eligible providers
+ * through the OAuthTokenManager and writing the resolved token into
+ * pi-coding-agent's runtime-override Map via setRuntimeApiKey.
+ *
+ * @param providerId - The provider id (e.g. "openai-codex", "anthropic").
+ * @param deps - Dispatch dependencies (authStorage, optional oauthManager, optional agentConfig).
+ * @returns The API key string.
+ * @throws Error containing the OAuthError.message when manager.getApiKey returns err().
+ */
+export declare function resolveProviderApiKey(providerId: string, deps: ResolveProviderApiKeyDeps): Promise<string>;

package/node_modules/@comis/agent/dist/model/resolve-provider-api-key.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * resolveProviderApiKey: shared dispatch helper that routes OAuth-eligible
+ * providers through the OAuthTokenManager + AuthStorage.setRuntimeApiKey
+ * side-effect, and non-OAuth providers through the existing authStorage path.
+ *
+ * Single attachment surface for the per-LLM-call OAuth dispatch
+ * hook. Used by PiExecutor.execute() pre-hook (primary LLM call) and the two
+ * compaction getApiKey callbacks in executor-context-engine-setup.ts.
+ *
+ * Return shape is `Promise<string>` (NOT `Result<T,E>`) because the helper
+ * bridges Comis's Result-typed manager with pi-coding-agent's
+ * `AuthStorage.getApiKey` contract; the throw mirrors pi-coding-agent's own
+ * throw-on-failure shape. On OAuthError the helper propagates a thrown Error —
+ * no env-var fallback, no retry, no silent rotation. Outer callers
+ * (PiExecutor.execute, gateway routes) surface the throw to the user via their
+ * existing error-handling path.
+ *
+ * @module
+ */
+import { getOAuthProvider } from "@mariozechner/pi-ai/oauth";
+/**
+ * Resolve the API key for a provider, routing OAuth-eligible providers
+ * through the OAuthTokenManager and writing the resolved token into
+ * pi-coding-agent's runtime-override Map via setRuntimeApiKey.
+ *
+ * @param providerId - The provider id (e.g. "openai-codex", "anthropic").
+ * @param deps - Dispatch dependencies (authStorage, optional oauthManager, optional agentConfig).
+ * @returns The API key string.
+ * @throws Error containing the OAuthError.message when manager.getApiKey returns err().
+ */
+export async function resolveProviderApiKey(providerId, deps) {
+    const oauthProvider = getOAuthProvider(providerId);
+    if (oauthProvider && deps.oauthManager) {
+        const result = await deps.oauthManager.getApiKey(providerId, {
+            oauthProfiles: deps.agentConfig?.oauthProfiles,
+        });
+        if (result.ok) {
+            // setRuntimeApiKey carries the token into pi-coding-agent's outbound
+            // LLM request via the runtime-override priority path — runtime
+            // overrides take HIGHEST priority.
+            deps.authStorage.setRuntimeApiKey(providerId, result.value);
+            return result.value;
+        }
+        // Decide whether to fall back to the plain API-key path. Two conditions
+        // must hold:
+        //   1. The OAuth result is "no credentials anywhere" (NO_CREDENTIALS),
+        //      not a real failure (REFRESH_FAILED, STORE_FAILED, …) which we
+        //      propagate fail-loud.
+        //   2. The agent did NOT explicitly request an OAuth profile via
+        //      `oauthProfiles[providerId]`. An explicit profile request that the
+        //      store cannot satisfy is a real failure — never silently fall back
+        //      to a different key (security keystone).
+        const noCredentials = result.error.code === "NO_CREDENTIALS";
+        const requestedProfile = deps.agentConfig?.oauthProfiles?.[providerId];
+        if (!noCredentials || requestedProfile !== undefined) {
+            // Propagate as throw — outer callers (PiExecutor.execute, gateway
+            // routes) lift the throw into a user-facing error result.
+            throw new Error(result.error.message);
+        }
+        // Fall through to authStorage — providers like anthropic accept both
+        // OAuth and direct API keys; without an OAuth profile, the plain key
+        // (ANTHROPIC_API_KEY etc.) is the valid path.
+    }
+    return (await deps.authStorage.getApiKey(providerId)) ?? "";
+}

package/node_modules/@comis/agent/dist/provider/capabilities.d.ts

@@ -4,7 +4,7 @@
  * Resolution order:
  *   1. DEFAULTS -- complete ProviderCapabilities with safe fallback values
  *   2. PROVIDER_OVERRIDES[normalizeProviderId(provider)] -- built-in overrides
- *      for known providers (12 entries covering Anthropic, OpenAI, Google, Mistral)
+ *      for known providers (8 entries covering Anthropic, OpenAI, Google, Mistral)
  *   3. userOverrides -- user-supplied config from YAML `providers.entries.*.capabilities`
  *
  * Providers NOT in PROVIDER_OVERRIDES (cerebras, groq, xai, etc.) get clean
@@ -35,23 +35,23 @@ export declare function normalizeProviderId(provider: string): string;
 export declare function resolveProviderCapabilities(provider: string, userOverrides?: Partial<ProviderCapabilities>): ProviderCapabilities;
 /**
  * Check if a provider belongs to the Anthropic family.
- * True for: anthropic, anthropic-vertex, amazon-bedrock (and their aliases).
+ * True for: anthropic, amazon-bedrock (and their aliases).
  */
 export declare function isAnthropicFamily(provider: string): boolean;
 /**
  * Check if a provider belongs to the OpenAI family.
- * True for: openai, azure-openai, azure-openai-responses, openai-codex (and their aliases).
+ * True for: openai, azure-openai-responses, openai-codex (and their aliases).
  */
 export declare function isOpenAiFamily(provider: string): boolean;
 /**
  * Check if a provider belongs to the Google family.
- * True for: google, google-gemini-cli, google-antigravity, google-vertex (and their aliases).
+ * True for: google, google-vertex (and their aliases).
  */
 export declare function isGoogleFamily(provider: string): boolean;
 /**
  * Check if a provider is Google AI Studio (api.google.dev, NOT Vertex AI).
  * True for: "google" only (and aliases: "gcp", "gemini").
- * Excludes: google-vertex, google-gemini-cli, google-antigravity.
+ * Excludes: google-vertex.
  *
  * Only Google AI Studio supports the Caches API used by GeminiCacheManager.
  */

package/node_modules/@comis/agent/dist/provider/capabilities.js

@@ -5,7 +5,7 @@
  * Resolution order:
  *   1. DEFAULTS -- complete ProviderCapabilities with safe fallback values
  *   2. PROVIDER_OVERRIDES[normalizeProviderId(provider)] -- built-in overrides
- *      for known providers (12 entries covering Anthropic, OpenAI, Google, Mistral)
+ *      for known providers (8 entries covering Anthropic, OpenAI, Google, Mistral)
  *   3. userOverrides -- user-supplied config from YAML `providers.entries.*.capabilities`
  *
  * Providers NOT in PROVIDER_OVERRIDES (cerebras, groq, xai, etc.) get clean
@@ -27,10 +27,10 @@ export const DEFAULTS = {
 /**
  * Built-in overrides for providers that differ from DEFAULTS.
  *
- * 12 entries covering:
- * - Anthropic family (3): anthropic, anthropic-vertex, amazon-bedrock
- * - OpenAI family (4): openai, azure-openai, azure-openai-responses, openai-codex
- * - Google family (4): google, google-gemini-cli, google-antigravity, google-vertex
+ * 8 entries covering:
+ * - Anthropic family (2): anthropic, amazon-bedrock
+ * - OpenAI family (3): openai, azure-openai-responses, openai-codex
+ * - Google family (2): google, google-vertex
  * - Mistral (1): strict9 tool call ID mode with 7 model hints
  *
  * Providers NOT in this map fall through to DEFAULTS via spread.
@@ -38,17 +38,13 @@ export const DEFAULTS = {
 const PROVIDER_OVERRIDES = {
     // Anthropic family
     "anthropic": { providerFamily: "anthropic", dropThinkingBlockModelHints: ["claude"] },
-    "anthropic-vertex": { providerFamily: "anthropic", dropThinkingBlockModelHints: ["claude"] },
     "amazon-bedrock": { providerFamily: "anthropic", dropThinkingBlockModelHints: ["claude"] },
     // OpenAI family
     "openai": { providerFamily: "openai" },
-    "azure-openai": { providerFamily: "openai" },
     "azure-openai-responses": { providerFamily: "openai" },
     "openai-codex": { providerFamily: "openai" },
     // Google family
     "google": { providerFamily: "google" },
-    "google-gemini-cli": { providerFamily: "google" },
-    "google-antigravity": { providerFamily: "google" },
     "google-vertex": { providerFamily: "google" },
     // Mistral -- strict9 tool call ID normalization
     "mistral": {
@@ -62,24 +58,15 @@ const PROVIDER_OVERRIDES = {
 /**
  * Provider ID alias table. Maps user-friendly shorthand names to canonical
  * provider IDs used in PROVIDER_OVERRIDES.
- *
- * AMBIGUITY NOTE: "vertex" maps to "anthropic-vertex" (Anthropic API via
- * Google Cloud), NOT "google-vertex". Users targeting Google Vertex AI
- * should use "google-vertex" or "gcp-vertex".
  */
 const ALIASES = {
     "aws-bedrock": "amazon-bedrock",
     "bedrock": "amazon-bedrock",
-    "vertex": "anthropic-vertex",
-    "vertex-ai": "anthropic-vertex",
-    "azure": "azure-openai",
     "azure-responses": "azure-openai-responses",
     "codex": "openai-codex",
     "gcp": "google",
     "gcp-vertex": "google-vertex",
     "gemini": "google",
-    "gemini-cli": "google-gemini-cli",
-    "antigravity": "google-antigravity",
     "grok": "xai",
 };
 /**
@@ -109,21 +96,21 @@ export function resolveProviderCapabilities(provider, userOverrides) {
 }
 /**
  * Check if a provider belongs to the Anthropic family.
- * True for: anthropic, anthropic-vertex, amazon-bedrock (and their aliases).
+ * True for: anthropic, amazon-bedrock (and their aliases).
  */
 export function isAnthropicFamily(provider) {
     return resolveProviderCapabilities(provider).providerFamily === "anthropic";
 }
 /**
  * Check if a provider belongs to the OpenAI family.
- * True for: openai, azure-openai, azure-openai-responses, openai-codex (and their aliases).
+ * True for: openai, azure-openai-responses, openai-codex (and their aliases).
  */
 export function isOpenAiFamily(provider) {
     return resolveProviderCapabilities(provider).providerFamily === "openai";
 }
 /**
  * Check if a provider belongs to the Google family.
- * True for: google, google-gemini-cli, google-antigravity, google-vertex (and their aliases).
+ * True for: google, google-vertex (and their aliases).
  */
 export function isGoogleFamily(provider) {
     return resolveProviderCapabilities(provider).providerFamily === "google";
@@ -131,7 +118,7 @@ export function isGoogleFamily(provider) {
 /**
  * Check if a provider is Google AI Studio (api.google.dev, NOT Vertex AI).
  * True for: "google" only (and aliases: "gcp", "gemini").
- * Excludes: google-vertex, google-gemini-cli, google-antigravity.
+ * Excludes: google-vertex.
  *
  * Only Google AI Studio supports the Caches API used by GeminiCacheManager.
  */
@@ -183,7 +170,7 @@ export function validateProviderOverrides(logger) {
                 provider: key,
                 hint: "Provider override exists for unknown pi-ai provider; remove from PROVIDER_OVERRIDES on next bump",
                 errorKind: "config",
-                module: "agent.capabilities",
+                submodule: "capabilities",
             }, "Capability override has no matching pi-ai provider");
         }
     }

package/node_modules/@comis/agent/dist/safety/tool-output-safety.js

@@ -74,15 +74,15 @@ export function sanitizeToolOutput(text, maxChars = DEFAULT_MAX_CHARS, options)
     if (containsTagBlockChars(text)) {
         options?.onTagBlockDetected?.();
     }
-    // Phase 1: Normalize for pattern matching (NFKC + strip zero-width + tag block)
+    // Normalize for pattern matching (NFKC + strip zero-width + tag block)
     let sanitized = normalizeForMatching(text);
-    // Phase 2: Redact injection patterns (on normalized text)
+    // Redact injection patterns (on normalized text)
     for (const pattern of INSTRUCTION_PATTERNS) {
         // Reset lastIndex for sticky/global regexes across multiple calls
         pattern.lastIndex = 0;
         sanitized = sanitized.replace(pattern, "[REDACTED]");
     }
-    // Phase 3: Truncate oversized output
+    // Truncate oversized output
     if (sanitized.length > maxChars) {
         const cutPoint = Math.floor(maxChars * 0.95);
         const lastNewline = sanitized.lastIndexOf("\n", cutPoint);

package/node_modules/@comis/agent/dist/safety/tool-retry-breaker.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool retry circuit breaker: per-tool-signature consecutive failure tracking.
  *
- * Prevents infinite retry loops (like the 48-call yfinance incident) by blocking
+ * Prevents infinite retry loops (the original repro: 48-call MCP-server retry incident) by blocking
  * tool calls after repeated failures and providing actionable LLM guidance with
  * alternative tool suggestions.
  *
@@ -29,6 +29,16 @@ export interface ToolRetryBreakerConfig {
     /** Max consecutive same-error-class failures (any args) before blocking.
      *  Stricter than args-based because same error + different args = stronger stuck signal. */
     maxConsecutiveErrorPatterns?: number;
+    /**
+     * Operator-supplied tool-alternative map. Keys are tool-name prefixes
+     * (e.g., `"mcp__finance-data"`); values are arrays of suggested alternative
+     * tool names. Used in block reasons to guide the LLM toward working tools.
+     *
+     * Defaults to an empty map (no alternatives suggested). The codebase MUST
+     * NOT ship hardcoded MCP server names — operators opt in by populating
+     * this map in their breaker config.
+     */
+    toolAlternatives?: Record<string, readonly string[]>;
 }
 /** Tool retry breaker interface -- tracks per-tool-signature failures. */
 export interface ToolRetryBreaker {

package/node_modules/@comis/agent/dist/safety/tool-retry-breaker.js

@@ -2,7 +2,7 @@
 /**
  * Tool retry circuit breaker: per-tool-signature consecutive failure tracking.
  *
- * Prevents infinite retry loops (like the 48-call yfinance incident) by blocking
+ * Prevents infinite retry loops (the original repro: 48-call MCP-server retry incident) by blocking
  * tool calls after repeated failures and providing actionable LLM guidance with
  * alternative tool suggestions.
  *
@@ -17,16 +17,6 @@
  * @module
  */
 // ---------------------------------------------------------------------------
-// Alternative tool mapping (hardcoded v1)
-// ---------------------------------------------------------------------------
-/**
- * Maps tool name prefixes to alternative tools that can serve similar purposes.
- * Used in block reasons to guide the LLM toward working alternatives.
- */
-const TOOL_ALTERNATIVES = {
-    "mcp__yfinance": ["web_search", "mcp__tavily--tavily-search", "web_fetch"],
-};
-// ---------------------------------------------------------------------------
 // Error tag extraction
 // ---------------------------------------------------------------------------
 /**
@@ -154,17 +144,6 @@ function fingerprint(toolName, args) {
     const sortedArgs = JSON.stringify(Object.fromEntries(Object.entries(args).sort()));
     return `${toolName}::${sortedArgs}`;
 }
-/**
- * Find alternative tools for a given tool name by prefix matching.
- * @returns Array of alternative tool names, empty if none known.
- */
-function findAlternatives(toolName) {
-    for (const [prefix, alts] of Object.entries(TOOL_ALTERNATIVES)) {
-        if (toolName.startsWith(prefix))
-            return alts;
-    }
-    return [];
-}
 /**
  * When tool failures are caused by the macOS sandbox-exec profile denying writes
  * to protected paths (~/.comis/skills/, global node_modules, ~/.gitconfig,
@@ -246,6 +225,7 @@ function buildBlockReason(toolName, count, lastError, alternatives, isToolLevel)
 export function createToolRetryBreaker(config) {
     const { maxConsecutiveFailures, maxToolFailures, suggestAlternatives } = config;
     const maxErrorPatterns = config.maxConsecutiveErrorPatterns ?? 2;
+    const toolAlternatives = config.toolAlternatives ?? {};
     // Per-fingerprint (tool+args) consecutive failure tracking
     const signatureFailures = new Map();
     // Per-tool-name total failure count (across all args)
@@ -254,6 +234,23 @@ export function createToolRetryBreaker(config) {
     const blockedTools = new Set();
     // Per-error-pattern consecutive failure tracking (keyed by `${toolName}::err::${errorTag}`)
     const errorPatternFailures = new Map();
+    /**
+     * Find alternative tools for a given tool name by prefix matching against
+     * `config.toolAlternatives`. Closed-over the factory's `toolAlternatives`
+     * local; defaults to no alternatives when the config field is omitted.
+     * Spread to a fresh mutable array so the readonly-input / mutable-output
+     * contract documented in `ToolRetryVerdict.alternatives?: string[]` is
+     * preserved.
+     *
+     * @returns Array of alternative tool names, empty if no prefix match.
+     */
+    function findAlternatives(toolName) {
+        for (const [prefix, alts] of Object.entries(toolAlternatives)) {
+            if (toolName.startsWith(prefix))
+                return [...alts];
+        }
+        return [];
+    }
     return {
         beforeToolCall(toolName, args) {
             // Check tool-level block first (all args blocked)

package/node_modules/@comis/agent/dist/session/comis-session-manager.d.ts

@@ -30,11 +30,25 @@ export interface ComisSessionManagerDeps {
  * Session metadata written as a companion file alongside the JSONL.
  * The SDK controls the JSONL format, so enrichment data (traceId, runId, session_end)
  * is stored in `_session-metadata.json` next to the `.jsonl` file.
+ *
+ * `traceId` and `runId` are deliberately distinct identifiers:
+ * - `traceId` is the request-scope AsyncLocalStorage value set by
+ *   `runWithContext` at the channel boundary (channels/.../execution-execute.ts).
+ *   The Pino tracing mixin (infra/.../log-fields.ts) injects it into every
+ *   daemon log line, so an operator can grep daemon.log for this exact value
+ *   to find every log entry produced while handling this turn.
+ * - `runId` is the executor-scope UUID minted per `executor.execute()` call
+ *   in pi-executor.ts. It keys cost-tracker / token_usage rows in the
+ *   observability store.
+ *
+ * They are 1:1 in the steady-state interactive path (one inbound message →
+ * one execution), but heartbeat and sub-agent paths can fan out a single
+ * trace into multiple executions.
  */
 export interface SessionMetadata {
-    /** Trace ID for cross-correlating with daemon logs */
+    /** Request-scope trace ID from runWithContext; matches traceId in daemon.log. */
     traceId?: string;
-    /** Execution run ID */
+    /** Executor-scope run ID; keys cost-tracker / token_usage rows. */
     runId?: string;
     /** Session end marker with completion details */
     sessionEnd?: {
@@ -105,7 +119,7 @@ export interface ComisSessionManager {
      */
     writeSessionMetadata(sessionKey: SessionKey, metadata: SessionMetadata): void;
     /**
-     * 260428-iag: Resolve the absolute JSONL session file path for a session key.
+     * Resolve the absolute JSONL session file path for a session key.
      *
      * Thin synchronous wrapper around `sessionKeyToPath(sessionKey, deps.sessionBaseDir)`
      * that exposes the path resolver to the wire-edge diagnostic in pi-event-bridge.

package/node_modules/@comis/agent/dist/session/comis-session-manager.js

@@ -71,7 +71,7 @@ export function createComisSessionManager(deps) {
             }, { retries: 10, retryMinTimeout: 500 });
         },
         getSessionPath(sessionKey) {
-            // 260428-iag wire-edge diagnostic: pure delegation to sessionKeyToPath
+            // wire-edge diagnostic: pure delegation to sessionKeyToPath
             // (which uses safePath internally). No I/O, no logging.
             return sessionKeyToPath(sessionKey, deps.sessionBaseDir);
         },

package/node_modules/@comis/agent/dist/spawn/narrative-caster.d.ts

@@ -34,6 +34,16 @@ export interface CastParams {
     /** Sub-agent session key for reference. */
     sessionKey: string;
 }
+/**
+ * Trailing instruction appended to every announcement.
+ * MUST start with "Inform the user about this completed background task."
+ * for AnnouncementBatcher.stripSystemPrefix() compatibility.
+ *
+ * Exported so packages/agent/src/background/completion-formatter.ts can
+ * reuse the byte-identical string. Do NOT change the string
+ * without updating both consumers AND announcement-batcher.ts:81.
+ */
+export declare const TRAILING_INSTRUCTION = "Inform the user about this completed background task. Summarize the result in your own voice. If no user notification is needed, respond with NO_REPLY.";
 /**
  * Create a NarrativeCaster with the given configuration.
  *

package/node_modules/@comis/agent/dist/spawn/narrative-caster.js

@@ -20,8 +20,12 @@ const MAX_LABEL_LENGTH = 100;
  * Trailing instruction appended to every announcement.
  * MUST start with "Inform the user about this completed background task."
  * for AnnouncementBatcher.stripSystemPrefix() compatibility.
+ *
+ * Exported so packages/agent/src/background/completion-formatter.ts can
+ * reuse the byte-identical string. Do NOT change the string
+ * without updating both consumers AND announcement-batcher.ts:81.
  */
-const TRAILING_INSTRUCTION = "Inform the user about this completed background task. Summarize the result in your own voice. If no user notification is needed, respond with NO_REPLY.";
+export const TRAILING_INSTRUCTION = "Inform the user about this completed background task. Summarize the result in your own voice. If no user notification is needed, respond with NO_REPLY.";
 /** Human-readable names for condensation levels. */
 const LEVEL_NAMES = {
     1: "Passthrough",

package/node_modules/@comis/agent/dist/spawn/pi-mono-adapters.d.ts

@@ -1,5 +1,5 @@
 /**
- * Pi-mono adapter wrappers for sub-agent ephemeral sessions (R-11).
+ * Pi-mono adapter wrappers for sub-agent ephemeral sessions.
  *
  * Provides `createEphemeralComisSessionManager()` — a zero-persistence
  * ComisSessionManager whose `withSession` uses `SessionManager.inMemory()`

package/node_modules/@comis/agent/dist/spawn/pi-mono-adapters.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Pi-mono adapter wrappers for sub-agent ephemeral sessions (R-11).
+ * Pi-mono adapter wrappers for sub-agent ephemeral sessions.
  *
  * Provides `createEphemeralComisSessionManager()` — a zero-persistence
  * ComisSessionManager whose `withSession` uses `SessionManager.inMemory()`
@@ -51,10 +51,10 @@ export function createEphemeralComisSessionManager(cwd) {
             // No-op: no companion file for in-memory sessions
         },
         getSessionPath() {
-            // 260428-iag wire-edge diagnostic: ephemeral sub-agent sessions never
-            // persist a JSONL file, so there is no path to return. Empty string
-            // signals "no persisted file"; the bridge's wire-diff hook short-circuits
-            // when jsonlPath.length === 0.
+            // Wire-edge diagnostic: ephemeral sub-agent sessions never persist a
+            // JSONL file, so there is no path to return. Empty string signals
+            // "no persisted file"; the bridge's wire-diff hook short-circuits when
+            // jsonlPath.length === 0.
             return "";
         },
     };

package/node_modules/@comis/agent/dist/workspace/data-env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Workspace-internal data env resolver.
+ *
+ * Returns environment variables for python/matplotlib subprocesses that
+ * derive ALL paths from `workspaceDir`. Avoids slow pip installs in the
+ * chart hot path and matplotlib Fontconfig errors from a non-writable
+ * default cache dir.
+ *
+ * This file contains no host-env reads. Subprocesses inheriting the
+ * daemon's full environment can pick up host paths (e.g.
+ * `/root/.cache/matplotlib`) that fail under read-only systemd hardening
+ * (`ProtectSystem=strict`) and leak host PATH into the agent's tool
+ * execution.
+ *
+ * matplotlib + python deps install into the agent workspace's `venv/`.
+ * The Dockerfile pre-warms the default workspace's venv at image build
+ * time so first-chart latency drops; subsequent chart calls reuse the
+ * venv. Full Docker image size goes up (acceptable trade-off).
+ *
+ * Mirrors workspace-resolver.ts's safePath + workspaceDir precedent
+ * (no path.join, no host-env reads).
+ *
+ * @module
+ */
+/**
+ * Resolve workspace-internal env vars for python/matplotlib subprocesses.
+ *
+ * The returned record is intended to be MERGED over an existing subprocess
+ * env at the call site (e.g. exec-tool's `{ ...baseEnv, ...resolveDataEnv(...) }`),
+ * so the workspace-internal values win on collision and the host PATH /
+ * cache dirs are not surfaced inside the subprocess.
+ *
+ * @param opts.workspaceDir - Absolute path to the agent workspace.
+ * @returns env-var record suitable for `child_process.spawn(..., { env })`.
+ */
+export declare function resolveDataEnv(opts: {
+    workspaceDir: string;
+}): Record<string, string>;