comisai 1.0.34 → 1.0.37

package/node_modules/@comis/agent/dist/background/completion-runner.js

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Background completion runner: subscribes to background_task:completed and
+ * background_task:failed events from the TypedEventBus and re-enters the
+ * originating agent session with a formatted completion announcement.
+ *
+ * Per-session lock serialization is delegated to the existing session
+ * manager (ComisSessionManager.withSession in packages/agent/src/session/).
+ * The runner does NOT introduce its own queueing -- one turn per completion
+ * event, ordering follows the existing per-session lock.
+ *
+ * Recursion bound: per-task incoming hop count + 1 must stay below
+ * `maxBackgroundHops` (default 3). When the cap is hit, the runner emits
+ * the fallback notification instead of triggering executor.execute().
+ * The hop count is read from `task.origin.backgroundHopCount`
+ * (populated by the originResolver).
+ *
+ * Latency-instrumentation hook: emits `background_task:reentered`
+ * immediately before executor.execute(). Integration tests compute the delta
+ * from `background_task:completed.timestamp` to this event for SLO tracking.
+ *
+ * Failure isolation: each handler is wrapped in suppressError so a single
+ * completion's failure does not tear down the subscription (AGENTS §2.1).
+ *
+ * @module
+ */
+import { randomUUID } from "node:crypto";
+import { suppressError } from "@comis/shared";
+import { parseFormattedSessionKey } from "@comis/core";
+import { formatCompletionAnnouncement } from "./completion-formatter.js";
+/**
+ * Wire the completion runner against an event bus + executor + session store.
+ * Subscriptions are installed synchronously; call shutdown() to remove them.
+ */
+export function createBackgroundCompletionRunner(deps) {
+    const log = deps.logger.child({ submodule: "background-completion-runner" });
+    let stopped = false;
+    let inflight = Promise.resolve();
+    const onCompleted = (data) => {
+        if (stopped)
+            return;
+        const promise = handleEvent(data.taskId, "completed");
+        inflight = inflight.then(() => promise).catch(() => undefined);
+        suppressError(promise, "background completion handler (completed)");
+    };
+    const onFailed = (data) => {
+        if (stopped)
+            return;
+        const promise = handleEvent(data.taskId, "failed");
+        inflight = inflight.then(() => promise).catch(() => undefined);
+        suppressError(promise, "background completion handler (failed)");
+    };
+    deps.eventBus.on("background_task:completed", onCompleted);
+    deps.eventBus.on("background_task:failed", onFailed);
+    async function handleEvent(taskId, kind) {
+        const task = deps.taskManager.getTask(taskId);
+        if (!task) {
+            log.warn({ taskId, kind, hint: "Task disappeared from manager before runner could resolve it; no announcement injected", errorKind: "internal" }, "Background completion: task not in manager");
+            return;
+        }
+        // At-most-once: the dispatcher subscribed BEFORE this runner (see
+        // setup-background-completion-runner.ts) and already transitioned
+        // task.dispatchState. When state is "notified", the dispatcher fired
+        // the user-visible fallback; the runner stays out of the way to
+        // enforce single-owner notification routing (zero spurious outbound).
+        if (task.dispatchState === "notified") {
+            log.debug({
+                taskId,
+                dispatchState: task.dispatchState,
+                // Include originating traceId so operator log streams stay
+                // continuous across the dispatcher / runner boundary.
+                traceId: task.origin?.traceId ?? undefined,
+                hint: "Dispatcher already fired fallback notification (at-most-once)",
+            }, "Background completion runner: skipped (dispatcher fired fallback)");
+            return;
+        }
+        // origin is producer-required (background-task-manager promote()
+        // rejects missing-origin) so we read it directly.
+        const origin = task.origin;
+        // Hop cap. Read incoming hop count from origin (schema field populated
+        // by the originResolver).
+        const nextHopCount = (origin.backgroundHopCount ?? 0) + 1;
+        if (nextHopCount >= deps.maxBackgroundHops) {
+            log.info({
+                taskId,
+                toolName: task.toolName,
+                agentId: origin.agentId,
+                hopCount: nextHopCount,
+                max: deps.maxBackgroundHops,
+                // traceId from origin keeps operator logs threaded.
+                traceId: origin.traceId ?? undefined,
+            }, "Background completion: hop cap reached, falling back to user notification");
+            await fallbackForTask(task.id, origin.agentId, task.toolName, `Background task "${task.toolName}" completed but follow-up was skipped — recursion limit reached. Run again or check the result manually.`);
+            return;
+        }
+        // No active session for this sessionKey in the in-memory store. The
+        // originating session may have ended (user closed the channel) OR may live
+        // in JSONL but not be currently registered. Either way, there is no
+        // streaming channel to inject into, so skip fallback (which would only
+        // produce a WARN from notification-service).
+        const sessionExists = deps.sessionStore.loadByFormattedKey(origin.sessionKey) !== undefined;
+        if (!sessionExists) {
+            log.info({
+                taskId,
+                sessionKey: origin.sessionKey,
+                // traceId from origin so this INFO log line stays threaded with the
+                // originating request's trace stream even though the runner runs in a
+                // background context (the ALS traceId at this point may differ from
+                // origin.traceId).
+                traceId: origin.traceId ?? undefined,
+                hint: "No active in-memory session for this sessionKey; runner will skip re-entry. Task result remains in JSONL for offline review.",
+            }, "Background completion: no active session for re-entry");
+            return;
+        }
+        // Reconstruct the SessionKey object for executor.execute().
+        const parsedKey = parseFormattedSessionKey(origin.sessionKey);
+        if (!parsedKey) {
+            log.warn({
+                taskId,
+                sessionKey: origin.sessionKey,
+                // traceId from origin keeps operator logs threaded.
+                traceId: origin.traceId ?? undefined,
+                hint: "Persisted sessionKey is malformed; cannot route announcement",
+                errorKind: "internal",
+            }, "Background completion: invalid sessionKey");
+            await fallbackForTask(task.id, origin.agentId, task.toolName, `Background task "${task.toolName}" completed (routing failed).`);
+            return;
+        }
+        // Format the announcement (byte-identical trailing instruction).
+        const announcement = formatCompletionAnnouncement(task);
+        // Construct the synthetic NormalizedMessage (hop counter in metadata).
+        const syntheticMsg = {
+            id: randomUUID(),
+            channelId: origin.channelId,
+            channelType: "background_task",
+            senderId: "background-task-runner",
+            text: announcement,
+            timestamp: Date.now(),
+            attachments: [],
+            metadata: {
+                backgroundHopCount: nextHopCount,
+                backgroundTaskId: task.id,
+                toolName: task.toolName,
+                agentId: origin.agentId,
+                traceId: origin.traceId ?? undefined,
+            },
+        };
+        log.debug({
+            taskId,
+            sessionKey: origin.sessionKey,
+            agentId: origin.agentId,
+            toolName: task.toolName,
+            hopCount: nextHopCount,
+            // traceId from origin keeps debug logs threaded.
+            traceId: origin.traceId ?? undefined,
+        }, "Background completion runner: invoking executor");
+        // Emit background_task:reentered immediately before executor.execute().
+        // Integration tests compute p95 latency from
+        // background_task:completed.timestamp to this event's timestamp.
+        // Include traceId from origin so subscribers (and operator log streams)
+        // preserve the originating request's trace across the
+        // background_task:completed → :reentered boundary.
+        deps.eventBus.emit("background_task:reentered", {
+            taskId: task.id,
+            agentId: origin.agentId,
+            sessionKey: origin.sessionKey,
+            hopCount: nextHopCount,
+            traceId: origin.traceId ?? null,
+            timestamp: Date.now(),
+        });
+        // One turn per event. Existing session lock orders concurrent calls.
+        try {
+            await deps.getExecutor(origin.agentId).execute(syntheticMsg, parsedKey, undefined, undefined, origin.agentId);
+        }
+        catch (err) {
+            log.warn({
+                taskId,
+                err,
+                // traceId from origin keeps the WARN line threaded.
+                traceId: origin.traceId ?? undefined,
+                hint: "Executor failed mid-completion turn; subscription remains active",
+                errorKind: "internal",
+            }, "Background completion: executor.execute() rejected");
+        }
+    }
+    /**
+     * Two-phase commit:
+     *
+     * 1. transitionDispatchState(taskId, "notified") — synchronously persists
+     *    `dispatchState = "notified"` to disk (via persistTaskSync inside the
+     *    manager). This MUST run before fallbackNotifyFn so a SIGKILL between
+     *    persist and fire does NOT leak a duplicate on recovery: the at-most-
+     *    once gate at the top of handleEvent (which reads task.dispatchState)
+     *    sees "notified" and skips re-firing. Without this ordering, the gate
+     *    misses and the user receives the notification twice.
+     *
+     * 2. fallbackNotifyFn(...) — actually deliver the user-visible
+     *    notification. May reject (channel offline, rate-limited, etc.); the
+     *    failure is logged at WARN. The persisted state stays at "notified" —
+     *    the user did not see the notification, but the at-most-once contract
+     *    takes precedence over delivery completeness.
+     */
+    async function fallbackForTask(taskId, agentId, toolName, message) {
+        // Phase 1: persist state. transitionDispatchState may return false if
+        // the task disappeared from the manager between handler entry and this
+        // call (e.g., explicit cleanup). In that case there is nothing to gate
+        // on; we still fire so the user sees the completion. The persist is
+        // synchronous so the on-disk state is updated before phase 2.
+        deps.taskManager.transitionDispatchState(taskId, "notified");
+        // Phase 2: fire user-visible notification.
+        try {
+            await deps.fallbackNotifyFn({
+                agentId,
+                message,
+                priority: "normal",
+                origin: "background_task",
+            });
+        }
+        catch (err) {
+            log.warn({ taskId, toolName, agentId, err, hint: "fallbackNotifyFn rejected; user will not see the completion notification for this task. dispatchState already persisted as \"notified\" — no duplicate on recovery.", errorKind: "internal" }, "Background completion: fallbackNotifyFn rejected (post-persist)");
+        }
+    }
+    return {
+        async shutdown() {
+            if (stopped)
+                return;
+            stopped = true;
+            deps.eventBus.off("background_task:completed", onCompleted);
+            deps.eventBus.off("background_task:failed", onFailed);
+            // Wait for any in-flight handler to settle before returning.
+            await inflight;
+        },
+    };
+}

package/node_modules/@comis/agent/dist/background/index.d.ts

@@ -3,9 +3,18 @@
  *
  * @module
  */
-export type { BackgroundTask, BackgroundTaskStatus, PersistedTaskState } from "./background-task-types.js";
+export type { BackgroundTask, BackgroundTaskStatus, BackgroundSessionState, PersistedTaskState, } from "./background-task-types.js";
+export type { BackgroundTaskNotificationPolicy as BackgroundTaskNotificationPolicyType } from "./background-task-types.js";
+export type { BackgroundTaskOrigin } from "@comis/core";
 export { persistTaskSync, loadTask, recoverTasks, removeTaskFile, TASK_DIR_NAME, } from "./background-task-persistence.js";
 export { createBackgroundTaskManager, } from "./background-task-manager.js";
 export type { BackgroundTaskManager, BackgroundTaskManagerOpts, NotifyFn, } from "./background-task-manager.js";
 export { wrapToolForAutoBackground, } from "./auto-background-middleware.js";
 export type { ToolDefinition, } from "./auto-background-middleware.js";
+export { formatCompletionAnnouncement, TRAILING_INSTRUCTION } from "./completion-formatter.js";
+export { createBackgroundCompletionRunner } from "./completion-runner.js";
+export type { BackgroundCompletionRunner, BackgroundCompletionRunnerDeps, RunnerSessionStore, } from "./completion-runner.js";
+export { createCompletionDispatcher, STATES, BackgroundTaskNotificationPolicy, } from "./completion-dispatcher.js";
+export type { CompletionDispatcher, CompletionDispatcherDeps, DispatcherSessionStore, DispatcherTaskManager, } from "./completion-dispatcher.js";
+export { createBackgroundSessionResolver } from "./session-resolver.js";
+export type { ActiveSessionKey, BackgroundSessionResolver, BackgroundSessionResolverDeps, } from "./session-resolver.js";

package/node_modules/@comis/agent/dist/background/index.js

@@ -7,3 +7,7 @@
 export { persistTaskSync, loadTask, recoverTasks, removeTaskFile, TASK_DIR_NAME, } from "./background-task-persistence.js";
 export { createBackgroundTaskManager, } from "./background-task-manager.js";
 export { wrapToolForAutoBackground, } from "./auto-background-middleware.js";
+export { formatCompletionAnnouncement, TRAILING_INSTRUCTION } from "./completion-formatter.js";
+export { createBackgroundCompletionRunner } from "./completion-runner.js";
+export { createCompletionDispatcher, STATES, BackgroundTaskNotificationPolicy, } from "./completion-dispatcher.js";
+export { createBackgroundSessionResolver } from "./session-resolver.js";

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

@@ -0,0 +1,85 @@
+/**
+ * BackgroundSessionResolver: composite-key wrapper around ActiveRunRegistry.
+ *
+ * The underlying `activeRunRegistry.has(sessionKey)` and `.get(sessionKey)`
+ * take a single formatted-key string. That string would collapse two
+ * distinct sessions for the same `channelId` across different agents (or
+ * different channelTypes) into one bucket — a latent multi-agent /
+ * multi-channel correctness bug.
+ *
+ * This resolver makes the composite key explicit at every public call site:
+ * `(agentId, channelType, channelId)`. It internally composes the formatted
+ * key via `formatSessionKey` from `@comis/core` and delegates to the
+ * underlying registry.
+ *
+ * Runtime semantics do not change at the registry layer — what changes is
+ * the lookup-key signature surfaced to production callers. No production
+ * code outside *.test.ts should retain a single-arg `.has(...)` or
+ * `.get(...)` on `activeRunRegistry`.
+ *
+ * @module
+ */
+import type { ActiveRunRegistry, RunHandle } from "../executor/active-run-registry.js";
+/**
+ * Composite key for active-session lookup.
+ *
+ * The three fields uniquely identify a session at the inbound-routing layer:
+ *   - `agentId`     — distinguishes per-agent isolation (multi-agent safety)
+ *   - `channelType` — distinguishes platform (telegram vs discord vs slack)
+ *   - `channelId`   — platform-specific chat / peer / group identifier
+ *
+ * The resolver internally composes a `SessionKey` and formats it via
+ * `formatSessionKey` so the underlying registry's string-keyed Map is
+ * addressed deterministically.
+ */
+export interface ActiveSessionKey {
+    agentId: string;
+    channelType: string;
+    channelId: string;
+}
+/**
+ * Public-facing resolver returned by `createBackgroundSessionResolver`.
+ *
+ * The resolver exposes ONLY composite-key methods. There is no single-arg
+ * fallback — production callers MUST thread `(agentId, channelType,
+ * channelId)` end-to-end.
+ */
+export interface BackgroundSessionResolver {
+    /**
+     * Look up the RunHandle for an active session.
+     *
+     * @param key - Composite key (agentId, channelType, channelId).
+     * @returns The RunHandle if a session is registered, otherwise undefined.
+     * @throws  Error when any composite-key field is empty / falsy
+     *          (programming error, parity with manager.promote's
+     *          empty-string guards in background-task-manager.ts:96-107).
+     */
+    resolveActiveSession(key: ActiveSessionKey): RunHandle | undefined;
+    /**
+     * Check whether a session is registered for the composite key.
+     *
+     * @param key - Composite key (agentId, channelType, channelId).
+     * @returns true iff a RunHandle is registered, false otherwise.
+     * @throws  Error when any composite-key field is empty / falsy.
+     */
+    hasActiveSession(key: ActiveSessionKey): boolean;
+}
+/**
+ * Dependencies required by the resolver.
+ *
+ * Only the registry is needed today — the resolver is a pure-function
+ * wrapper. No logger / event-bus injection (CLAUDE.md: NO logging in
+ * pure-function helpers).
+ */
+export interface BackgroundSessionResolverDeps {
+    activeRunRegistry: ActiveRunRegistry;
+}
+/**
+ * Create a BackgroundSessionResolver wrapping an ActiveRunRegistry.
+ *
+ * Public-facing methods accept ONLY the composite key (agentId,
+ * channelType, channelId) — no single-arg fallback. Production callers
+ * no longer reach into `activeRunRegistry.has(...)` / `.get(...)`
+ * directly.
+ */
+export declare function createBackgroundSessionResolver(deps: BackgroundSessionResolverDeps): BackgroundSessionResolver;

package/node_modules/@comis/agent/dist/background/session-resolver.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * BackgroundSessionResolver: composite-key wrapper around ActiveRunRegistry.
+ *
+ * The underlying `activeRunRegistry.has(sessionKey)` and `.get(sessionKey)`
+ * take a single formatted-key string. That string would collapse two
+ * distinct sessions for the same `channelId` across different agents (or
+ * different channelTypes) into one bucket — a latent multi-agent /
+ * multi-channel correctness bug.
+ *
+ * This resolver makes the composite key explicit at every public call site:
+ * `(agentId, channelType, channelId)`. It internally composes the formatted
+ * key via `formatSessionKey` from `@comis/core` and delegates to the
+ * underlying registry.
+ *
+ * Runtime semantics do not change at the registry layer — what changes is
+ * the lookup-key signature surfaced to production callers. No production
+ * code outside *.test.ts should retain a single-arg `.has(...)` or
+ * `.get(...)` on `activeRunRegistry`.
+ *
+ * @module
+ */
+import { formatSessionKey } from "@comis/core";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Compose the formatted session-key string from a composite key.
+ *
+ * Mirrors the shape that production session-managers use when registering
+ * handles: `formatSessionKey({tenantId: agentId, channelId:
+ * "${channelType}:${channelId}", userId: channelId})`. The output is a
+ * deterministic colon-delimited string that round-trips through
+ * `parseFormattedSessionKey` (the channelType prefix on channelId is
+ * stable across format/parse).
+ *
+ * The triple is REQUIRED — empty fields are a programming error
+ * (parity with the empty-string guard in
+ * `background-task-manager.ts:promote()`).
+ */
+function formatComposite(key) {
+    if (!key.agentId || !key.channelType || !key.channelId) {
+        throw new Error(`BackgroundSessionResolver: composite key requires non-empty agentId, channelType, channelId; got ${JSON.stringify(key)}`);
+    }
+    return formatSessionKey({
+        tenantId: key.agentId,
+        channelId: `${key.channelType}:${key.channelId}`,
+        userId: key.channelId,
+    });
+}
+/**
+ * Create a BackgroundSessionResolver wrapping an ActiveRunRegistry.
+ *
+ * Public-facing methods accept ONLY the composite key (agentId,
+ * channelType, channelId) — no single-arg fallback. Production callers
+ * no longer reach into `activeRunRegistry.has(...)` / `.get(...)`
+ * directly.
+ */
+export function createBackgroundSessionResolver(deps) {
+    // Local alias: the resolver IS the abstraction over the underlying
+    // single-arg registry. We rename to `registry` so source-grep tooling
+    // (`activeRunRegistry.has|get(`) does not flag this file as a callsite
+    // to migrate -- the resolver IS the migration target. Invariant:
+    // *production callers* of `activeRunRegistry` go through this resolver;
+    // the resolver itself remains the sole consumer of the underlying
+    // single-arg surface.
+    const registry = deps.activeRunRegistry;
+    return {
+        resolveActiveSession(key) {
+            const formatted = formatComposite(key);
+            return registry.get(formatted);
+        },
+        hasActiveSession(key) {
+            const formatted = formatComposite(key);
+            return registry.has(formatted);
+        },
+    };
+}

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

@@ -34,6 +34,7 @@ export function buildMessagingSection(toolNames, isMinimal, channelContext) {
         '- `[System Message]` blocks are internal context. If one reports completed work and asks for a user update, rewrite it in your normal assistant voice. Never forward raw system message text to users.',
         "- Never use shell execution, code execution, or file tools to send messages. Use only the messaging tools.",
         "- Do NOT use message(action=send) for progress updates, debug output, or placeholder text. The user sees every send as a phone notification. Work silently; deliver the result.",
+        "- Do NOT narrate intent before calling a tool. Avoid prefacing tool calls with phrases like \"I'll do X now…\" or \"Let me run Y…\" — invoke the tool directly. Pre-tool-text creates user-visible promises the agent may not be able to fulfill if the tool gets backgrounded.",
         "- Use `fetch` to read recent messages from a channel before responding to context you missed.",
         "- The `delete` action requires confirmation and cannot be undone.",
     ];

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

@@ -20,7 +20,7 @@
 import { getToolMetadata } from "@comis/core";
 import { getProviders } from "@mariozechner/pi-ai";
 // ---------------------------------------------------------------------------
-// Layer 1D (260430-vwt) -- live native-catalog provider list
+// Live native-catalog provider list
 //
 // Computed once at module load time. Used by the providers_manage TOOL_GUIDE
 // "Built-in vs Custom Provider Check" block below so the text reflects
@@ -325,7 +325,7 @@ If the model IS built-in: skip provider creation. After credential pre-check pas
 If the model is NOT built-in: you need a custom provider. Proceed to the steps below, but first gather ALL required configuration.
 
 ### Choosing the \`type\` Field (POST AUTO-PROMOTE FLOW)
-After Layer 1C of the catalog-driven providers redesign, the \`type\` field follows two distinct rules depending on the provider name:
+For catalog-driven providers, the \`type\` field follows two distinct rules depending on the provider name:
 - **If \`provider_id\` matches a built-in name** (use models_manage list_providers to verify): OMIT \`type\` entirely from the create config. The daemon auto-promotes \`type\` to the native catalog name when \`provider_id\` matches a native entry AND no custom \`baseUrl\` is supplied. Setting \`type:"openai"\` for a built-in name still works (auto-promoted), but omitting it is cleaner.
 - **If \`provider_id\` is a custom OpenAI-compatible proxy** (NVIDIA NIM, Together, Fireworks, etc.) NOT in the native catalog: set \`type:"openai"\` (or whatever wire-format API matches). Auto-promotion does not fire for non-catalog names.
 - **If \`baseUrl\` differs from the native catalog URL** for a built-in name: this signals you want the OpenAI-passthrough shape (custom proxy that masquerades as the built-in). Auto-promotion is suppressed; the entry stays as \`type:"openai"\`.
@@ -357,7 +357,7 @@ To switch an agent to a different provider/model, call agents_manage update with
 **Three 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.
-  3. **Credential pre-check passed** (see top of this guide). The target provider's apiKeyName is non-empty AND \`gateway env_list filter:"<PROVIDER>*"\` confirmed the named secret exists in env. Skipping this step is the bug that causes "No API key found" failures at the next chat turn — verified production repro on 2026-05-01.
+  3. **Credential pre-check passed** (see top of this guide). The target provider's apiKeyName is non-empty AND \`gateway env_list filter:"<PROVIDER>*"\` confirmed the named secret exists in env. Skipping this step is the bug that causes "No API key found" failures at the next chat turn.
 
 **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.

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

@@ -4,8 +4,36 @@
  */
 /** Model size tier — determines prompt verbosity for tool descriptions. */
 export type ModelTier = "small" | "medium" | "large";
-export declare function buildToolingSection(toolNames: string[], _modelTier: ModelTier, toolSummaries?: Record<string, string>): string[];
-export declare function buildToolCallStyleSection(isMinimal: boolean, toolNames?: string[]): string[];
+/**
+ * Build the static `## Available Tools` block (legacy path, gate-off) OR a
+ * single residual one-liner pointing the model at the per-turn `## Capabilities`
+ * block (gate-on path).
+ *
+ * @param capabilityIndexEnabled - When `true`, emits ONLY the residual
+ *   one-liner. When `false` or undefined, emits the legacy flat block
+ *   BYTE-IDENTICALLY to the pre-feature baseline. The two paths are MUTUALLY
+ *   EXCLUSIVE.
+ *
+ *   Restart-required: this gate selects between two cached system-prompt
+ *   shapes; toggling at runtime is forbidden. Operator-facing constraint is
+ *   documented in config docs.
+ */
+export declare function buildToolingSection(toolNames: string[], _modelTier: ModelTier, toolSummaries?: Record<string, string>, capabilityIndexEnabled?: boolean): string[];
+/**
+ * Build the static "## Tool Call Style" section with conditional coding guidelines.
+ *
+ * @param capabilityIndexEnabled - When `true`, AND when `exec` is in
+ *   `toolNames`, the rendered output includes the dual-gated "Tool-first
+ *   principle" bullet immediately before the existing Python-virtualenv rule.
+ *   When `false` or `undefined`, the bullet is omitted; the existing venv
+ *   rule emits unchanged when `exec` is present.
+ *
+ *   Restart-required: the gate value flows from `tooling.capabilityIndex.enabled`
+ *   via `AssemblerParams.capabilityIndexEnabled`, populated at the prompt
+ *   assembly site from `port.isCapabilityIndexEnabled()`. The value is
+ *   config-derived and stable per session — SAFE inside the cache fence.
+ */
+export declare function buildToolCallStyleSection(isMinimal: boolean, toolNames?: string[], capabilityIndexEnabled?: boolean): string[];
 /** Tool names that trigger the confirmation flow / self-update gating section. */
 export declare const CONFIRMATION_TOOL_NAMES: string[];
 /**

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

@@ -5,9 +5,36 @@
  */
 import { TOOL_SUMMARIES, TOOL_ORDER } from "./tool-descriptions.js";
 import { getProviders } from "@mariozechner/pi-ai";
-export function buildToolingSection(toolNames, _modelTier, toolSummaries) {
+/**
+ * Build the static `## Available Tools` block (legacy path, gate-off) OR a
+ * single residual one-liner pointing the model at the per-turn `## Capabilities`
+ * block (gate-on path).
+ *
+ * @param capabilityIndexEnabled - When `true`, emits ONLY the residual
+ *   one-liner. When `false` or undefined, emits the legacy flat block
+ *   BYTE-IDENTICALLY to the pre-feature baseline. The two paths are MUTUALLY
+ *   EXCLUSIVE.
+ *
+ *   Restart-required: this gate selects between two cached system-prompt
+ *   shapes; toggling at runtime is forbidden. Operator-facing constraint is
+ *   documented in config docs.
+ */
+export function buildToolingSection(toolNames, _modelTier, toolSummaries, capabilityIndexEnabled) {
     if (toolNames.length === 0)
         return [];
+    // Gate-on path: residual one-liner only. The per-turn `## Capabilities`
+    // block is rendered into the dynamic preamble by `executor-prompt-runner.ts`.
+    // The wording below is normative.
+    if (capabilityIndexEnabled === true) {
+        return [
+            "When this turn includes a `Capabilities` context, refer to it for grouped tool guidance " +
+                "before invoking tools or running installs. Tool schemas in your active toolspace are " +
+                "authoritative for parameter shapes.",
+        ];
+    }
+    // Gate-off path: legacy flat block BYTE-IDENTICAL to pre-feature baseline.
+    // DO NOT modify the body below — the byte-identity assertion in
+    // tooling-sections.test.ts depends on this shape staying exact.
     const summaries = { ...TOOL_SUMMARIES, ...toolSummaries };
     const ordered = TOOL_ORDER.filter((t) => toolNames.includes(t));
     const extras = toolNames.filter((t) => !TOOL_ORDER.includes(t)).sort();
@@ -23,7 +50,21 @@ export function buildToolingSection(toolNames, _modelTier, toolSummaries) {
 // ---------------------------------------------------------------------------
 // 4. Tool Call Style (skip if minimal)
 // ---------------------------------------------------------------------------
-export function buildToolCallStyleSection(isMinimal, toolNames = []) {
+/**
+ * Build the static "## Tool Call Style" section with conditional coding guidelines.
+ *
+ * @param capabilityIndexEnabled - When `true`, AND when `exec` is in
+ *   `toolNames`, the rendered output includes the dual-gated "Tool-first
+ *   principle" bullet immediately before the existing Python-virtualenv rule.
+ *   When `false` or `undefined`, the bullet is omitted; the existing venv
+ *   rule emits unchanged when `exec` is present.
+ *
+ *   Restart-required: the gate value flows from `tooling.capabilityIndex.enabled`
+ *   via `AssemblerParams.capabilityIndexEnabled`, populated at the prompt
+ *   assembly site from `port.isCapabilityIndexEnabled()`. The value is
+ *   config-derived and stable per session — SAFE inside the cache fence.
+ */
+export function buildToolCallStyleSection(isMinimal, toolNames = [], capabilityIndexEnabled) {
     if (isMinimal)
         return [];
     const lines = [
@@ -64,6 +105,14 @@ export function buildToolCallStyleSection(isMinimal, toolNames = []) {
         guidelines.push("- Show file paths clearly when working with files.");
     }
     if (has("exec")) {
+        // Dual-gated counterweight to the venv rule below. The bullet precedes
+        // the venv rule because the first read sets the default; the second is
+        // the install fallback. Restart-required: capabilityIndexEnabled flows
+        // from `tooling.capabilityIndex.enabled` via AssemblerParams →
+        // SECTIONS["tool-call-style"].
+        if (capabilityIndexEnabled === true) {
+            guidelines.push("- **Tool-first principle.** When this turn includes a `Capabilities` context and the task can be satisfied by a connected tool or available skill, prefer that capability over installing a Python or Node package. Use installs only for capabilities not covered by active tools, deferred tools, or visible prompt skills.");
+        }
         guidelines.push("- **Python projects:** Always create a virtualenv per project (`python3 -m venv .venv`). "
             + "Install packages into the project venv (`source .venv/bin/activate && pip install ...`). "
             + "Never use `--break-system-packages` — it pollutes the system Python. "

package/node_modules/@comis/agent/dist/bootstrap/system-prompt-assembler.d.ts

@@ -79,6 +79,28 @@ export interface AssemblerParams {
     excludeBootstrapFromContext?: boolean;
     /** Workspace profile controlling platform instruction verbosity ('full' or 'specialist'). */
     workspaceProfile?: "full" | "specialist";
+    /**
+     * Capability index gate.
+     *
+     * When `true`, `buildToolingSection` emits the residual one-liner instead
+     * of the legacy `## Available Tools` flat block; the per-turn
+     * `## Capabilities` block is rendered into the dynamic preamble in
+     * `executor-prompt-runner.ts`.
+     * When `false` or `undefined`, the static prompt is byte-identical to
+     * the pre-feature baseline.
+     *
+     * RESTART-REQUIRED: this flag selects between two cached system-prompt
+     * shapes. Daemon wiring documents the operator-facing constraint.
+     *
+     * SAFE INSIDE THE CACHE FENCE: this value is config-derived
+     * (operator-only, restart-required) and stable across all turns of a
+     * session. Plumbing it through `assemblerParams` does NOT create a
+     * cache-thrash regression. Live-runtime accessors
+     * (getPromptSkillCapabilities, getConnectedMcpServers) are forbidden
+     * inside this interface and enforced by an architecture-grep test.
+     * Adding a config-derived flag to the cache fence is safe.
+     */
+    capabilityIndexEnabled?: boolean;
     /** Whether Silent Execution Planner (SEP) is enabled for this agent. */
     sepEnabled?: boolean;
 }

package/node_modules/@comis/agent/dist/bootstrap/system-prompt-assembler.js

@@ -82,8 +82,8 @@ export const SECTIONS = [
     { id: "safety", includeIn: MODES_ALL, build: (p, m) => buildSafetySection(m === "minimal") },
     { id: "language", includeIn: MODES_ALL, build: (p) => buildLanguageSection(p.userLanguage) },
     // --- Semi-stable body: operational-kept sections (MODES_ALL -- builders self-filter for minimal) ---
-    { id: "tooling", includeIn: MODES_ALL, build: (p, m) => buildToolingSection(p.toolNames ?? [], m === "minimal" ? "small" : "large", p.toolSummaries) },
-    { id: "tool-call-style", includeIn: MODES_ALL, build: (p, m) => buildToolCallStyleSection(m === "minimal", p.toolNames ?? []) },
+    { id: "tooling", includeIn: MODES_ALL, build: (p, m) => buildToolingSection(p.toolNames ?? [], m === "minimal" ? "small" : "large", p.toolSummaries, p.capabilityIndexEnabled) },
+    { id: "tool-call-style", includeIn: MODES_ALL, build: (p, m) => buildToolCallStyleSection(m === "minimal", p.toolNames ?? [], p.capabilityIndexEnabled) },
     // --- Operational-stripped sections (MODES_FULL_MIN -- dropped in "operational") ---
     { id: "self-update", includeIn: MODES_FULL_MIN, build: (p, m) => buildSelfUpdateGatingSection(p.toolNames ?? [], m === "minimal", true) },
     { id: "config-secret", includeIn: MODES_FULL_MIN, build: (p, m) => buildConfigSecretIntegritySection(p.toolNames ?? [], m === "minimal") },

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

@@ -10,11 +10,7 @@
  *
  * @module
  */
-/**
- * Extract the MCP server name from a sanitized tool name.
- * Format: `mcp__serverName--toolName`. Returns undefined for non-MCP tools.
- */
-export declare function extractMcpServerName(toolName: string): string | undefined;
+export { extractMcpServerName } from "@comis/shared";
 /**
  * Classify an MCP error message into a category for observability.
  */