comisai 1.0.36 → 1.0.37

package/node_modules/@comis/agent/dist/executor/capability-index-context.js

@@ -0,0 +1,329 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-turn capability-index renderer.
+ *
+ * Renders the `## Capabilities` block for the dynamic preamble. Lives
+ * post-deferral in the executor lifecycle; consumes a `ToolCapabilityPort`
+ * for cluster/skill resolution and an `ExcludeDeferralResult` for active
+ * vs deferred tool partitioning.
+ *
+ * Pure-function builder: no logger, no IO, no `Result` envelope, no mutable
+ * module state beyond frozen module-level constants. Mirrors the shape of
+ * `buildDeferredToolsContext` in `tool-deferral.ts`.
+ *
+ * IMPORTANT -- cache fence:
+ * This module is consumed ONLY by `executor-tool-assembly.ts`. It MUST NOT
+ * be imported by `prompt-assembly.ts` -- the static prompt cache prefix MUST
+ * stay byte-identical when the skill registry reloads between turns.
+ * An architecture-grep enforces this invariant.
+ *
+ * @module
+ */
+import { extractMcpServerName } from "@comis/shared";
+import { TOOL_ORDER } from "../bootstrap/sections/tool-descriptions.js";
+import { CHARS_PER_TOKEN_RATIO } from "../context-engine/constants.js";
+// ---------------------------------------------------------------------------
+// Module-level frozen sentinel + constants
+// ---------------------------------------------------------------------------
+/**
+ * Frozen empty result. Returned when the gate is off or when all three
+ * surface counts are zero. Identity-stable so callers can do cheap reference
+ * equality checks if useful.
+ */
+const EMPTY = Object.freeze({
+    text: "",
+    capabilityIndexTokens: 0,
+    clusterCount: 0,
+    activeToolCount: 0,
+    deferredToolCount: 0,
+    promptSkillCount: 0,
+});
+/**
+ * Active-tool count threshold above which all per-cluster name lists are
+ * dropped (cluster headers + `(N tools)` counts remain).
+ * Constant in v1.1; revisit only if telemetry shows fleets clustering near it.
+ */
+const ELISION_THRESHOLD = 32;
+/**
+ * Maximum names rendered per server (active MCP) or per skill cluster
+ * before `+N more` truncation.
+ */
+const PER_GROUP_NAME_CAP = 8;
+// ---------------------------------------------------------------------------
+// Reserved cluster IDs
+//
+// Inlined as string literals at the three fallback sites instead of named
+// constants -- the IDs are part of the user-visible config schema in
+// `packages/core/src/config/schema-tooling.ts`. Renaming them is intentionally
+// not supported -- the cluster ID itself is fixed.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Public renderer
+// ---------------------------------------------------------------------------
+/**
+ * Build the per-turn capability-index render result.
+ *
+ * Behavior:
+ *  - Gate respect: returns {@link EMPTY} when `port.isCapabilityIndexEnabled()` is false.
+ *  - Empty-input fast path: returns {@link EMPTY} when all three surface counts are zero.
+ *  - Cluster bucketing: builtins -> `getBuiltinCluster()` (or `"other-tools"`),
+ *    MCP -> `getMcpServerHint().cluster` (or `"external-integrations"`),
+ *    skills -> `skill.cluster` (or `"prompt-skills"`).
+ *  - Orphan-drop: deferred MCP tools whose server is not in the live
+ *    `getConnectedMcpServers()` snapshot are dropped silently.
+ *  - Sort: `(priority asc, clusterId asc)` for clusters; `TOOL_ORDER` for
+ *    builtins (alphabetical fallback for unknowns); alphabetical for MCP
+ *    servers and skills.
+ *  - Per-group cap: 8 names + `+N more`.
+ *  - >32 elision: drop ALL per-cluster name lists; keep headers + counts only.
+ *  - Forbidden-literal discipline: the rendered text names neither the
+ *    client-side discovery tool nor the server-side tool search regex tool.
+ *    The deferred-tools preamble bullet uses the mechanism-neutral
+ *    `"discovery mechanism available in your active toolspace"` wording.
+ *    An architecture-grep enforces the file-level invariant.
+ *
+ * Restart-required note: `tooling.capabilityIndex.enabled` requires a daemon
+ * restart to take effect. The renderer respects the port's reported value at
+ * render time but does not enforce the restart constraint.
+ *
+ * @param deferralResult - Output of `applyToolDeferral` (active + deferred tool partition).
+ * @param port - The capability port (gate flag, cluster/skill resolution, live runtime view).
+ * @returns Frozen {@link CapabilityIndexRenderResult}; identity-stable {@link EMPTY} for the no-op path.
+ */
+export function buildCapabilityIndexContext(deferralResult, port) {
+    // Gate (restart-required).
+    if (!port.isCapabilityIndexEnabled())
+        return EMPTY;
+    // Snapshot the live runtime view ONCE per render. Re-querying the port
+    // mid-render would risk inconsistent state if a server connect/disconnect
+    // happens between two reads.
+    const connectedServers = new Set(port.getConnectedMcpServers());
+    const visibleSkills = port.getPromptSkillCapabilities();
+    // Bucket every input source into a clusterId -> ClusterRender map.
+    const clusterMap = new Map();
+    // Active builtin / non-MCP tools.
+    for (const tool of deferralResult.activeTools) {
+        if (extractMcpServerName(tool.name) !== undefined)
+            continue;
+        const clusterId = port.getBuiltinCluster(tool.name) ?? "other-tools";
+        const cluster = ensureCluster(clusterMap, clusterId, port);
+        cluster.builtins.push(tool.name);
+    }
+    // Active MCP tools. Group by server within their cluster.
+    for (const tool of deferralResult.activeTools) {
+        const server = extractMcpServerName(tool.name);
+        if (server === undefined)
+            continue;
+        const clusterId = port.getMcpServerHint(server)?.cluster ?? "external-integrations";
+        const cluster = ensureCluster(clusterMap, clusterId, port);
+        const bucket = ensureServerBucket(cluster, server);
+        bucket.activeTools.push(tool.name);
+    }
+    // Deferred MCP tools (with orphan-drop). Non-MCP deferred entries are
+    // dropped entirely -- a header-only shell would be misleading because the
+    // renderer cannot teach what to do with a non-MCP deferred name.
+    let deferredToolCount = 0;
+    for (const entry of deferralResult.deferredEntries) {
+        const server = extractMcpServerName(entry.name);
+        if (server === undefined)
+            continue;
+        if (!connectedServers.has(server))
+            continue; // orphan-drop
+        const clusterId = port.getMcpServerHint(server)?.cluster ?? "external-integrations";
+        const cluster = ensureCluster(clusterMap, clusterId, port);
+        const bucket = ensureServerBucket(cluster, server);
+        bucket.deferredCount += 1;
+        deferredToolCount += 1;
+    }
+    // Visible prompt skills. The port has already merged
+    // operator > comis.capability > fallback; we only resolve cluster.
+    for (const skill of visibleSkills) {
+        const clusterId = skill.cluster ?? "prompt-skills";
+        const cluster = ensureCluster(clusterMap, clusterId, port);
+        cluster.skills.push(skill);
+    }
+    // Compute totals.
+    let activeToolCount = 0;
+    for (const cluster of clusterMap.values()) {
+        activeToolCount += cluster.builtins.length;
+        for (const bucket of cluster.mcpServers.values()) {
+            activeToolCount += bucket.activeTools.length;
+        }
+    }
+    // Empty-input fast path.
+    if (activeToolCount + deferredToolCount + visibleSkills.length === 0) {
+        return EMPTY;
+    }
+    // Sort clusters: (priority asc, clusterId asc).
+    const orderedClusters = [...clusterMap.values()].sort((a, b) => a.config.priority - b.config.priority || a.id.localeCompare(b.id));
+    // Determine elision: when total active exceeds 32, drop all per-cluster
+    // name lists (cluster headers + `(N tools)` counts remain).
+    const eliminateNameLists = activeToolCount > ELISION_THRESHOLD;
+    // Render the text envelope.
+    const lines = [];
+    lines.push("## Capabilities");
+    lines.push("");
+    lines.push("Map the task to one of these connected capabilities before using exec to install libraries.");
+    lines.push("");
+    lines.push("- Active tools: callable now.");
+    lines.push("- Deferred tools: connected, but load them through the discovery mechanism available in your active toolspace before invoking them.");
+    lines.push("- Prompt skills: available instructions/workflows; use the existing skill-loading mechanism when the task matches.");
+    for (const cluster of orderedClusters) {
+        lines.push("");
+        lines.push(`### ${cluster.config.label}`);
+        if (cluster.config.preferOverInstalls) {
+            lines.push("Prefer connected tools and available skills over installing equivalent libraries.");
+        }
+        if (eliminateNameLists) {
+            // Headers + count-only.
+            const tools = cluster.builtins.length + sumActiveServerTools(cluster);
+            lines.push(`(${tools} tools)`);
+            const deferredHere = sumDeferredServerTools(cluster);
+            if (deferredHere > 0) {
+                lines.push(`(${deferredHere} deferred tools)`);
+            }
+            if (cluster.skills.length > 0) {
+                lines.push(`(${cluster.skills.length} skills)`);
+            }
+            continue;
+        }
+        appendClusterBody(lines, cluster);
+    }
+    const text = lines.join("\n");
+    const clusterCount = orderedClusters.length;
+    return Object.freeze({
+        text,
+        capabilityIndexTokens: Math.ceil(text.length / CHARS_PER_TOKEN_RATIO),
+        clusterCount,
+        activeToolCount,
+        deferredToolCount,
+        promptSkillCount: visibleSkills.length,
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal helpers (file-scoped; not exported)
+// ---------------------------------------------------------------------------
+/**
+ * Lookup-or-create a {@link ClusterRender} bucket for a cluster ID. The
+ * cluster's {@link ClusterConfig} resolves through the port; missing config
+ * for a non-reserved ID falls back to a synthesized default labelled by the
+ * cluster ID itself. The wiring layer emits a WARN for missing configs; the
+ * renderer only renders.
+ */
+function ensureCluster(map, clusterId, port) {
+    const existing = map.get(clusterId);
+    if (existing)
+        return existing;
+    const config = port.getClusterConfig(clusterId) ?? synthesizeClusterConfig(clusterId);
+    const cluster = {
+        id: clusterId,
+        config,
+        builtins: [],
+        mcpServers: new Map(),
+        skills: [],
+    };
+    map.set(clusterId, cluster);
+    return cluster;
+}
+/**
+ * Synthesize a {@link ClusterConfig} for a cluster ID the port does not
+ * recognize. This keeps the renderer total pure -- it never throws on
+ * misconfiguration. The wiring layer owns the WARN path; here we render
+ * with the cluster ID as both label and a sentinel `9999` priority (sorts
+ * last) and `preferOverInstalls: false`.
+ */
+function synthesizeClusterConfig(clusterId) {
+    return Object.freeze({
+        label: clusterId,
+        priority: 9999,
+        preferOverInstalls: false,
+    });
+}
+function ensureServerBucket(cluster, server) {
+    const existing = cluster.mcpServers.get(server);
+    if (existing)
+        return existing;
+    const bucket = { activeTools: [], deferredCount: 0 };
+    cluster.mcpServers.set(server, bucket);
+    return bucket;
+}
+function sumActiveServerTools(cluster) {
+    let total = 0;
+    for (const bucket of cluster.mcpServers.values())
+        total += bucket.activeTools.length;
+    return total;
+}
+function sumDeferredServerTools(cluster) {
+    let total = 0;
+    for (const bucket of cluster.mcpServers.values())
+        total += bucket.deferredCount;
+    return total;
+}
+/**
+ * Sort builtin/non-MCP tool names within a cluster: known names follow
+ * {@link TOOL_ORDER}; unknown names fall through to alphabetical via
+ * `localeCompare`.
+ */
+function sortBuiltinsInCluster(builtins) {
+    const orderIndex = (name) => {
+        const idx = TOOL_ORDER.indexOf(name);
+        return idx === -1 ? Number.MAX_SAFE_INTEGER : idx;
+    };
+    return builtins.slice().sort((a, b) => {
+        const diff = orderIndex(a) - orderIndex(b);
+        if (diff !== 0)
+            return diff;
+        return a.localeCompare(b);
+    });
+}
+/**
+ * Append the body of a single cluster (after its `### Label` heading and
+ * optional callout have already been pushed) to the line buffer. Renders:
+ *   1. Builtin/non-MCP tool names (TOOL_ORDER sort, alphabetical fallback).
+ *   2. MCP servers alphabetical, each with capped `+N more` tool list and
+ *      optional `(N deferred)` suffix when deferred entries exist.
+ *   3. Prompt skills alphabetical, capped at 8 + `+N more`.
+ *
+ * Elision is handled by the caller (skip this body, emit count-only lines
+ * instead).
+ */
+function appendClusterBody(lines, cluster) {
+    if (cluster.builtins.length > 0) {
+        const sorted = sortBuiltinsInCluster(cluster.builtins);
+        lines.push(`- ${sorted.join(", ")}`);
+    }
+    const sortedServers = [...cluster.mcpServers.entries()].sort(([a], [b]) => a.localeCompare(b));
+    for (const [server, bucket] of sortedServers) {
+        const sortedTools = bucket.activeTools.slice().sort((a, b) => a.localeCompare(b));
+        const shortNames = sortedTools.map((full) => stripServerPrefix(full, server));
+        const head = shortNames.slice(0, PER_GROUP_NAME_CAP);
+        const overflow = shortNames.length - head.length;
+        const namesPart = head.length === 0
+            ? ""
+            : `: ${head.join(", ")}${overflow > 0 ? `, +${overflow} more` : ""}`;
+        const deferredPart = bucket.deferredCount > 0
+            ? ` (${bucket.deferredCount} deferred)`
+            : "";
+        lines.push(`- [${server}] (${bucket.activeTools.length} tools${deferredPart})${namesPart}`);
+    }
+    if (cluster.skills.length > 0) {
+        const sortedSkills = cluster.skills
+            .slice()
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const head = sortedSkills.slice(0, PER_GROUP_NAME_CAP);
+        const overflow = sortedSkills.length - head.length;
+        const names = head.map((s) => s.name).join(", ");
+        const overflowText = overflow > 0 ? `, +${overflow} more` : "";
+        lines.push(`- skills: ${names}${overflowText}`);
+    }
+}
+/**
+ * Strip the `mcp__<server>--` prefix from a sanitized MCP tool name so the
+ * cluster body shows compact short names. Falls back to the full name if
+ * the prefix does not match (defensive -- the upstream parser already
+ * validated the shape).
+ */
+function stripServerPrefix(toolName, server) {
+    const prefix = `mcp__${server}--`;
+    return toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName;
+}

package/node_modules/@comis/agent/dist/executor/drain-helper.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Inline-consumption drain seams.
+ *
+ * The drain trigger lives at the BRIDGE call site (`tool_execution_end` for
+ * `message` send/reply/attach) -- NOT in pi-executor.ts. The helpers in
+ * this module are what the bridge invokes:
+ *
+ *   - markRead(key):     mark inbound messages for the composite key as read.
+ *                        Reads tool context via `tryGetContext()` so the
+ *                        function does NOT take a passed-in deps object.
+ *                        No-op outside an AsyncLocalStorage scope.
+ *
+ *   - markConsumed(key): mark inbound messages for the composite key as
+ *                        consumed by the agent's response. Same context
+ *                        contract as markRead.
+ *
+ *   - drainAt(key):      orchestrator. Runs markRead + markConsumed under
+ *                        a per-composite-key single-tick inflight gate
+ *                        (`drainInflightByKey: Map<string, Promise<void>>`).
+ *                        Concurrent calls for the same composite key
+ *                        return immediately; concurrent calls for
+ *                        DIFFERENT composite keys (different agentId /
+ *                        channelType / channelId) drain independently.
+ *                        Failures are non-fatal: suppressError +
+ *                        structured WARN log. The drainInflightByKey state
+ *                        is owned by the bridge (BridgeMetricsState) so
+ *                        the bridge threads it into drainAt at each call
+ *                        site.
+ *
+ * The actual inline-consumption queue does not exist as a concrete data
+ * structure today -- this module provides the structural seam. Future
+ * work plugs queue/state into `tryGetContext()` so markRead / markConsumed
+ * read it without re-threading through every caller. Today the helpers
+ * are observability-only stubs that log at DEBUG when context is present
+ * and fall through silently when outside any request scope.
+ *
+ * This module lives in `packages/agent/src/executor/` (not in the bridge)
+ * so executor-post-execution.ts can re-export the helpers for source-grep
+ * tests, while the bridge imports from here directly. This avoids a
+ * circular import (executor-post-execution -> pi-executor -> bridge ->
+ * executor-post-execution).
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+/**
+ * Composite drain key uniquely identifies the inline-consumption queue
+ * partition for a single (agent, channel, channel-id) triple.
+ *
+ * Same shape as `BackgroundSessionResolver.ActiveSessionKey` so a single
+ * triple is reusable across the bridge / resolver / drain surface.
+ */
+export interface DrainKey {
+    agentId: string;
+    channelType: string;
+    channelId: string;
+}
+/**
+ * State container for the per-composite-key drain inflight gate.
+ *
+ * Owned by the bridge (`BridgeMetricsState.drainInflightByKey`) and
+ * threaded into `drainAt` at each call site. A `Map` (rather than a single
+ * `drainInflight: Promise`) is required so concurrent drains for DIFFERENT
+ * composite keys can run independently (multi-agent isolation).
+ */
+export interface DrainInflightState {
+    drainInflightByKey: Map<string, Promise<void>>;
+}
+/**
+ * Format a composite drain key into a deterministic string used as the
+ * inflight-gate Map key. Mirrors the resolver's composite-key shape so the
+ * gate keys are interchangeable with resolver keys (no parallel formatting
+ * surfaces to drift).
+ */
+export declare function formatDrainKey(key: DrainKey): string;
+/**
+ * Mark inbound messages for the composite drain key as read.
+ *
+ * Reads tool context via `tryGetContext()` -- when called outside any
+ * AsyncLocalStorage scope (test fixture, sub-agent path), this is a silent
+ * no-op. Otherwise emits a DEBUG-level observability log so operators can
+ * correlate drain activity with ALS context propagation.
+ *
+ * @param key - Composite drain key (agentId, channelType, channelId).
+ * @param logger - Logger for the (rare) DEBUG observability path.
+ */
+export declare function markRead(key: DrainKey, logger: ComisLogger): void;
+/**
+ * Mark inbound messages for the composite drain key as consumed.
+ *
+ * Same context contract as `markRead`. No-op outside AsyncLocalStorage
+ * scope.
+ *
+ * @param key - Composite drain key (agentId, channelType, channelId).
+ * @param logger - Logger for the (rare) DEBUG observability path.
+ */
+export declare function markConsumed(key: DrainKey, logger: ComisLogger): void;
+/**
+ * drainAt: composite-keyed inline-consumption drain with single-tick gate.
+ *
+ * Invoked by the bridge on `tool_execution_end` for successful
+ * `message(send|reply|attach)` calls. Runs `markRead` + `markConsumed`
+ * under a per-composite-key inflight gate so:
+ *   - Concurrent drains for the SAME composite key return immediately
+ *     (lock-safe drain).
+ *   - Concurrent drains for DIFFERENT composite keys (different
+ *     agentId / channelType / channelId) run independently (multi-agent
+ *     isolation).
+ *
+ * Failures are non-fatal: a per-event `.catch(...)` logs WARN with `hint`
+ * + `errorKind`, and the outer `suppressError` ensures the bridge's
+ * `tool_execution_end` propagation is never aborted by drain misbehavior.
+ *
+ * Map-entry cleanup (`.delete(formatted)` in `.finally(...)`) is required
+ * to prevent unbounded growth across long-running sessions; the entry is
+ * removed within one event-loop tick of the drain promise settling.
+ *
+ * @param key - Composite drain key (agentId, channelType, channelId).
+ * @param state - Bridge-owned inflight-gate Map (drainInflightByKey).
+ * @param logger - Logger for the WARN failure log + DEBUG observability.
+ */
+export declare function drainAt(key: DrainKey, state: DrainInflightState, logger: ComisLogger): void;

package/node_modules/@comis/agent/dist/executor/drain-helper.js

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Inline-consumption drain seams.
+ *
+ * The drain trigger lives at the BRIDGE call site (`tool_execution_end` for
+ * `message` send/reply/attach) -- NOT in pi-executor.ts. The helpers in
+ * this module are what the bridge invokes:
+ *
+ *   - markRead(key):     mark inbound messages for the composite key as read.
+ *                        Reads tool context via `tryGetContext()` so the
+ *                        function does NOT take a passed-in deps object.
+ *                        No-op outside an AsyncLocalStorage scope.
+ *
+ *   - markConsumed(key): mark inbound messages for the composite key as
+ *                        consumed by the agent's response. Same context
+ *                        contract as markRead.
+ *
+ *   - drainAt(key):      orchestrator. Runs markRead + markConsumed under
+ *                        a per-composite-key single-tick inflight gate
+ *                        (`drainInflightByKey: Map<string, Promise<void>>`).
+ *                        Concurrent calls for the same composite key
+ *                        return immediately; concurrent calls for
+ *                        DIFFERENT composite keys (different agentId /
+ *                        channelType / channelId) drain independently.
+ *                        Failures are non-fatal: suppressError +
+ *                        structured WARN log. The drainInflightByKey state
+ *                        is owned by the bridge (BridgeMetricsState) so
+ *                        the bridge threads it into drainAt at each call
+ *                        site.
+ *
+ * The actual inline-consumption queue does not exist as a concrete data
+ * structure today -- this module provides the structural seam. Future
+ * work plugs queue/state into `tryGetContext()` so markRead / markConsumed
+ * read it without re-threading through every caller. Today the helpers
+ * are observability-only stubs that log at DEBUG when context is present
+ * and fall through silently when outside any request scope.
+ *
+ * This module lives in `packages/agent/src/executor/` (not in the bridge)
+ * so executor-post-execution.ts can re-export the helpers for source-grep
+ * tests, while the bridge imports from here directly. This avoids a
+ * circular import (executor-post-execution -> pi-executor -> bridge ->
+ * executor-post-execution).
+ *
+ * @module
+ */
+import { tryGetContext } from "@comis/core";
+import { suppressError } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Format a composite drain key into a deterministic string used as the
+ * inflight-gate Map key. Mirrors the resolver's composite-key shape so the
+ * gate keys are interchangeable with resolver keys (no parallel formatting
+ * surfaces to drift).
+ */
+export function formatDrainKey(key) {
+    return `${key.agentId}:${key.channelType}:${key.channelId}`;
+}
+/**
+ * Mark inbound messages for the composite drain key as read.
+ *
+ * Reads tool context via `tryGetContext()` -- when called outside any
+ * AsyncLocalStorage scope (test fixture, sub-agent path), this is a silent
+ * no-op. Otherwise emits a DEBUG-level observability log so operators can
+ * correlate drain activity with ALS context propagation.
+ *
+ * @param key - Composite drain key (agentId, channelType, channelId).
+ * @param logger - Logger for the (rare) DEBUG observability path.
+ */
+export function markRead(key, logger) {
+    const ctx = tryGetContext();
+    if (!ctx) {
+        // No AsyncLocalStorage scope: markRead is a no-op outside a request-
+        // scoped context. The bridge's `drainAt` is invoked from inside the
+        // request scope, but tests / sub-agent paths may invoke directly.
+        return;
+    }
+    // Future: read the inline-consumption queue partition for `key` from
+    // `ctx` and flip status. Today: structural seam + observability.
+    logger.debug({
+        submodule: "drain.markRead",
+        agentId: key.agentId,
+        channelType: key.channelType,
+        channelId: key.channelId,
+        traceId: ctx.traceId,
+    }, "markRead");
+}
+/**
+ * Mark inbound messages for the composite drain key as consumed.
+ *
+ * Same context contract as `markRead`. No-op outside AsyncLocalStorage
+ * scope.
+ *
+ * @param key - Composite drain key (agentId, channelType, channelId).
+ * @param logger - Logger for the (rare) DEBUG observability path.
+ */
+export function markConsumed(key, logger) {
+    const ctx = tryGetContext();
+    if (!ctx) {
+        return;
+    }
+    logger.debug({
+        submodule: "drain.markConsumed",
+        agentId: key.agentId,
+        channelType: key.channelType,
+        channelId: key.channelId,
+        traceId: ctx.traceId,
+    }, "markConsumed");
+}
+/**
+ * Run a single drain pass for the composite key.
+ *
+ * Calls `markRead` + `markConsumed` sequentially. Both helpers no-op
+ * outside an AsyncLocalStorage scope, so this function is safe to invoke
+ * from the bridge's event handler without wrapping in `runWithContext`.
+ */
+async function runOneDrainPass(key, logger) {
+    markRead(key, logger);
+    markConsumed(key, logger);
+}
+/**
+ * drainAt: composite-keyed inline-consumption drain with single-tick gate.
+ *
+ * Invoked by the bridge on `tool_execution_end` for successful
+ * `message(send|reply|attach)` calls. Runs `markRead` + `markConsumed`
+ * under a per-composite-key inflight gate so:
+ *   - Concurrent drains for the SAME composite key return immediately
+ *     (lock-safe drain).
+ *   - Concurrent drains for DIFFERENT composite keys (different
+ *     agentId / channelType / channelId) run independently (multi-agent
+ *     isolation).
+ *
+ * Failures are non-fatal: a per-event `.catch(...)` logs WARN with `hint`
+ * + `errorKind`, and the outer `suppressError` ensures the bridge's
+ * `tool_execution_end` propagation is never aborted by drain misbehavior.
+ *
+ * Map-entry cleanup (`.delete(formatted)` in `.finally(...)`) is required
+ * to prevent unbounded growth across long-running sessions; the entry is
+ * removed within one event-loop tick of the drain promise settling.
+ *
+ * @param key - Composite drain key (agentId, channelType, channelId).
+ * @param state - Bridge-owned inflight-gate Map (drainInflightByKey).
+ * @param logger - Logger for the WARN failure log + DEBUG observability.
+ */
+export function drainAt(key, state, logger) {
+    const formatted = formatDrainKey(key);
+    if (state.drainInflightByKey.has(formatted)) {
+        // Single-tick gate: a drain is already in flight for this composite
+        // key; second concurrent call returns immediately.
+        return;
+    }
+    const draining = runOneDrainPass(key, logger)
+        .catch((err) => {
+        logger.warn({
+            submodule: "drain.drainAt",
+            agentId: key.agentId,
+            channelType: key.channelType,
+            channelId: key.channelId,
+            err,
+            hint: "drainAt failed; will retry on next tool_execution_end. Investigate when this fires repeatedly without recovery.",
+            errorKind: "internal",
+        }, "drainAt failed");
+    })
+        .finally(() => {
+        state.drainInflightByKey.delete(formatted);
+    });
+    state.drainInflightByKey.set(formatted, draining);
+    // Belt-and-braces: outer suppressError ensures the bridge's
+    // tool_execution_end propagation is NEVER aborted by drain misbehavior
+    // (fire-and-forget contract).
+    suppressError(draining, "drain at bridge call site (B15)");
+}

package/node_modules/@comis/agent/dist/executor/error-classifier.js

@@ -13,9 +13,9 @@ import { isSignedReplayError } from "./signed-replay-detector.js";
 const ERROR_PATTERNS = [
     // Billing / credits
     {
-        test: /credit balance is too low|billing|purchase credits|insufficient.?funds|payment.?required/i,
+        test: /credit balance is too low|billing|purchase credits|insufficient.?funds|payment.?required|usage.?limits?|regain.?access|spend.?(cap|limit)/i,
         category: "credit_exhausted",
-        userMessage: "The AI service is currently unavailable due to a billing issue. Please notify the system administrator.",
+        userMessage: "The AI service is currently unavailable due to a billing or usage-cap issue. Please notify the system administrator.",
         retryable: false,
     },
     // Rate limiting (429)