comisai 1.0.34 → 1.0.37

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)

package/node_modules/@comis/agent/dist/executor/executor-context-engine-setup.d.ts

@@ -17,6 +17,7 @@ import { type ContextEngine } from "../context-engine/index.js";
 import type { TokenAnchor } from "../context-engine/types.js";
 import type { DiscoveryTracker } from "./discovery-tracker.js";
 import type { ExecutionOverrides } from "./types.js";
+import type { OAuthTokenManager } from "../model/oauth-token-manager.js";
 /** Subset of PiExecutorDeps used by context engine setup. */
 export interface ContextEngineSetupDeps {
     logger: ComisLogger;
@@ -28,6 +29,12 @@ export interface ContextEngineSetupDeps {
     getPromptSkillsXml?: () => string;
     contextStore?: import("@comis/memory").ContextStore;
     db?: unknown;
+    /**
+     * Optional OAuth token manager. When provided, compaction LLM
+     * calls route through resolveProviderApiKey for OAuth-eligible providers,
+     * with fallthrough to authStorage for non-OAuth providers.
+     */
+    oauthManager?: OAuthTokenManager;
 }
 /** Parameters for context engine creation. */
 export interface ContextEngineSetupParams {
@@ -80,6 +87,15 @@ export interface ContextEngineSetupResult {
     contextEngine: ContextEngine;
     /** Getter for accumulated transformContext duration in ms */
     getContextEngineDurationMs: () => number;
+    /** Per-execute signature-replay scrub counters. `signatureScrubs`
+     *  bumps once per non-empty scrubber emission; `signatureScrubsToolCallsAffected`
+     *  accumulates the toolCallsAffected field across emissions. Surfaced to
+     *  executor-post-execution.ts so the bookend "Execution complete" INFO log
+     *  carries the per-execute total instead of the per-event INFO emissions. */
+    getSignatureScrubCounters: () => {
+        signatureScrubs: number;
+        signatureScrubsToolCallsAffected: number;
+    };
 }
 /**
  * Create and wire the context engine for a single execution.

package/node_modules/@comis/agent/dist/executor/executor-context-engine-setup.js

@@ -16,6 +16,7 @@ import { ContextEngineConfigSchema, safePath, } from "@comis/core";
 import { createContextEngine } from "../context-engine/index.js";
 import { CHARS_PER_TOKEN_RATIO } from "../context-engine/constants.js";
 import { resolveOperationModel, resolveProviderFamily } from "../model/operation-model-resolver.js";
+import { resolveProviderApiKey } from "../model/resolve-provider-api-key.js";
 import { getBreakpointIndex, getBreakpointIndexMapSize, getSessionLatches, } from "./executor-session-state.js";
 import { shouldDropSignedFields } from "./replay-drift-detector.js";
 import { readFileSync } from "node:fs";
@@ -47,7 +48,7 @@ export function setupContextEngine(params) {
     // consistent decision (cleaner + scrubber must agree). The closure reads
     // the latest model identity each time (handles cycleModel mid-execute).
     // Returns the identity/idle drift only — the kvl tool-defs dimension was
-    // removed in 260428-lm6 in favor of the unconditional latest-message
+    // removed in favor of the unconditional latest-message
     // preserving scrub in signature-replay-scrubber.
     let memoizedDrift;
     const computeDriftIfNeeded = () => {
@@ -85,6 +86,12 @@ export function setupContextEngine(params) {
             return memoizedDrift;
         }
     };
+    // Per-execute counters for the signature-replay scrubber. Live
+    // for the lifetime of this setupContextEngine() call (one per execute()),
+    // so no reset is needed — the closure goes out of scope at execute end and
+    // a fresh setup creates fresh zeroed counters for the next execute.
+    let signatureScrubs = 0;
+    let signatureScrubsToolCallsAffected = 0;
     const contextEngine = createContextEngine(contextEngineConfig, {
         logger: deps.logger,
         eventBus: deps.eventBus,
@@ -110,6 +117,17 @@ export function setupContextEngine(params) {
         getSystemTokensEstimate: getCachedSystemTokensEstimate,
         // G-09: Notify cache break detector when observation masking modifies content
         onContentModified: () => cacheBreakDetector.notifyContentModification(formattedKey),
+        // Accumulate signature-replay scrub counts per-execute. Only
+        // counts emissions that actually scrubbed something (zero-touch turns
+        // are filtered out — they're not a "scrub" in the post-incident-visibility
+        // sense). Sums toolCallsAffected so the bookend "Execution complete" log
+        // carries the post-incident-visibility metric.
+        onSignatureReplayScrubbed: (stats) => {
+            if (stats.scrubbedAssistantMessages > 0) {
+                signatureScrubs++;
+                signatureScrubsToolCallsAffected += stats.toolCallsAffected;
+            }
+        },
         // Provide API-grounded token anchor to context engine pipeline
         getTokenAnchor,
         // Reset anchor when compaction replaces the message array
@@ -146,9 +164,16 @@ export function setupContextEngine(params) {
                     reasoning: model?.reasoning ?? false,
                 };
             },
-            getApiKey: async () => {
-                return (await deps.authStorage.getApiKey(config.provider)) ?? "";
-            },
+            // Route compaction's primary getApiKey through the shared
+            // dispatch helper so OAuth-eligible providers refresh through
+            // OAuthTokenManager + setRuntimeApiKey on every call. Non-OAuth
+            // providers (anthropic, openai, etc.) still fall through to
+            // authStorage.getApiKey unchanged.
+            getApiKey: async () => resolveProviderApiKey(config.provider, {
+                authStorage: deps.authStorage,
+                oauthManager: deps.oauthManager,
+                agentConfig: config,
+            }),
             // Resolve compaction model via 5-level priority chain
             // contextEngineOverrides removed -- invocationOverride path eliminated
             //   Path 1: operationModels.compaction (operator config) -> explicit_config (Level 2)
@@ -171,7 +196,17 @@ export function setupContextEngine(params) {
                             return {
                                 overrideModel: {
                                     model: compactionModel,
-                                    getApiKey: async () => (await deps.authStorage.getApiKey(compactionResolution.provider)) ?? "",
+                                    // Route the override-model getApiKey through
+                                    // the shared dispatch helper. Each callsite passes
+                                    // its OWN providerId — config.provider above for the
+                                    // primary, compactionResolution.provider here for the
+                                    // override — both correctly resolve the right OAuth
+                                    // profile via agentConfig.oauthProfiles[providerId].
+                                    getApiKey: async () => resolveProviderApiKey(compactionResolution.provider, {
+                                        authStorage: deps.authStorage,
+                                        oauthManager: deps.oauthManager,
+                                        agentConfig: config,
+                                    }),
                                 },
                             };
                         }
@@ -314,5 +349,11 @@ export function setupContextEngine(params) {
     return {
         contextEngine,
         getContextEngineDurationMs: () => contextEngineDurationMs,
+        // Expose per-execute signature-replay scrub counters so the
+        // bookend "Execution complete" INFO log can roll them up.
+        getSignatureScrubCounters: () => ({
+            signatureScrubs,
+            signatureScrubsToolCallsAffected,
+        }),
     };
 }

package/node_modules/@comis/agent/dist/executor/executor-post-execution.d.ts

@@ -16,8 +16,9 @@ import type { AgentSession } from "@mariozechner/pi-coding-agent";
 import type { CacheRetention } from "@mariozechner/pi-ai";
 import { type SessionKey, type NormalizedMessage, type PerAgentConfig, type TypedEventBus, type MemoryPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
+import { drainAt, markRead, markConsumed, formatDrainKey, type DrainKey, type DrainInflightState } from "./drain-helper.js";
 import type { ActiveRunRegistry } from "./active-run-registry.js";
-import type { ComisSessionManager } from "../session/comis-session-manager.js";
+import type { ComisSessionManager, SessionMetadata } from "../session/comis-session-manager.js";
 import type { ExecutionResult, ExecutionOverrides } from "./types.js";
 import type { ExecutionPlan } from "../planner/types.js";
 import type { ContextEngine } from "../context-engine/index.js";
@@ -53,16 +54,40 @@ export interface PostExecutionBridgeResult {
     cacheWrite5mTokens?: number;
     /** Estimated 1h TTL cache write tokens from TTL split data. */
     cacheWrite1hTokens?: number;
-    /** 1.3: Session-cumulative total cost across all turns (USD). */
+    /** Session-cumulative total cost across all turns (USD). */
     sessionCostUsd?: number;
-    /** 1.3: Session-cumulative cache savings across all turns (USD). */
+    /** Session-cumulative cache savings across all turns (USD). */
     sessionCacheSavedUsd?: number;
-    /** 1.5: Thinking tokens from SDK reasoningTokens field. */
+    /** Thinking tokens from SDK reasoningTokens field. */
     thinkingTokens?: number;
+    /** Number of pre-LLM-call hash-assertion walks performed (one per turn_start). */
+    hashAssertionsRan?: number;
+    /** Total cross-turn thinking-block hash mismatches surfaced across all walks. */
+    hashAssertionMismatches?: number;
+    /** Bridge-side mirror of the scrub counter (carried through buildBridgeResult
+     *  for symmetry — the canonical per-execute total comes from
+     *  ceSetup.getSignatureScrubCounters() since the scrubber doesn't write to
+     *  bridge metrics; included on this interface so consumers reading the
+     *  bridge-result shape get a coherent type). */
+    signatureScrubs?: number;
+    signatureScrubsToolCallsAffected?: number;
 }
 /** Bridge interface used by post-execution. */
 export interface PostExecutionBridge {
     getResult(): PostExecutionBridgeResult;
+    /**
+     * Expose the bridge-owned drain inflight gate so postExecution can fire
+     * an end-of-turn backstop `drainAt(...)`. The bridge already drains on
+     * `tool_execution_end` for `message` actions (inline-consumption); the
+     * end-of-turn backstop closes the residual race for turns that never
+     * invoked the `message` tool but still need the inline-consumption
+     * queue flipped (NO_REPLY-only turns, sentinel passes, etc.).
+     *
+     * Both call sites share the SAME composite key gate map so concurrent
+     * drains for the same `(agentId, channelType, channelId)` triple
+     * collapse to a single in-flight Promise.
+     */
+    getDrainState(): DrainInflightState;
 }
 /** Parameters for postExecution(). */
 export interface PostExecutionParams {
@@ -75,6 +100,9 @@ export interface PostExecutionParams {
     msg: NormalizedMessage;
     sessionKey: SessionKey;
     formattedKey: string;
+    /** Resolver-aligned key for activeRunRegistry.deregister. Must match the
+     *  formula used at the corresponding register call site. */
+    resolverRegisterKey: string;
     agentId: string | undefined;
     executionStartMs: number;
     executionId: string;
@@ -86,6 +114,10 @@ export interface PostExecutionParams {
     };
     ceSetup: {
         getContextEngineDurationMs(): number;
+        getSignatureScrubCounters(): {
+            signatureScrubs: number;
+            signatureScrubsToolCallsAffected: number;
+        };
     };
     streamSetup: {
         capturedRetention?: {
@@ -108,6 +140,21 @@ export interface PostExecutionParams {
     geminiCacheHit: boolean;
     geminiCachedTokens: number;
     modelTier: string | undefined;
+    /**
+     * Provider used for this execution. Sourced from `resolvedModel.provider` in
+     * pi-executor when available; falls back to `config.provider` when the
+     * misconfig silent-fallback path triggers (resolvedModel undefined). The
+     * fallback value records operator INTENT — the actual provider chosen by
+     * pi-coding-agent's silent-fallback logic is opaque at this layer, and intent
+     * is the more useful signal for operator-side cache-hit-rate segmentation.
+     */
+    provider: string;
+    /**
+     * Provider family derived from `resolveProviderCapabilities(provider).providerFamily`.
+     * One of "anthropic" | "openai" | "google" | "default". Pre-computed at the
+     * call site (pi-executor) so this module stays free of capability-cascade dependencies.
+     */
+    providerFamily: string;
     deferralResult: {
         deferredCount: number;
     };
@@ -152,6 +199,33 @@ export declare function shouldStorePairedMemory(userText: string, agentResponse:
 export declare function isDuplicatePairedMemory(content: string, agentId: string): boolean;
 /** Reset the paired-memory dedup cache. Exported for unit tests. */
 export declare function resetPairedMemoryDedupForTests(): void;
+/**
+ * Build the SessionMetadata payload written to `_session-metadata.json` at the
+ * end of an execution.
+ *
+ * `traceId` and `runId` are deliberately distinct:
+ * - `traceId` is the request-scope AsyncLocalStorage value set by
+ *   `runWithContext` at the channel boundary (execution-execute.ts) and injected
+ *   into every daemon log line by the Pino tracing mixin. Operators grep
+ *   daemon.log for this exact value. Pass `tryGetContext()?.traceId` here.
+ * - `runId` is the executor-scope UUID minted in pi-executor.ts per
+ *   `executor.execute()` call. It keys cost-tracker / token_usage rows.
+ *
+ * They happen to be 1:1 in the steady-state interactive path (one inbound
+ * message → one execution), but the schema treats them as distinct because
+ * heartbeat / sub-agent paths can fan out one trace into multiple executions.
+ *
+ * Pure: no I/O, no side effects. The fire-and-forget try/catch around
+ * `writeSessionMetadata` lives at the call site.
+ */
+export declare function buildSessionEndMetadata(args: {
+    finishReason: string;
+    durationMs: number;
+    totalTokens: number;
+    executionId: string;
+    traceId: string | undefined;
+}): SessionMetadata;
+export { drainAt, markRead, markConsumed, formatDrainKey, type DrainKey, type DrainInflightState, };
 /**
  * Run post-execution cleanup for a PiExecutor turn.
  *