comisai 1.0.44 → 1.0.46

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

@@ -46,8 +46,9 @@ export interface PostExecutionBridgeResult {
     toolCallHistory?: string[];
     finishReason?: ExecutionResult["finishReason"];
     lastActiveToolName?: string;
-    /** The last LLM error message the bridge captured (HR-01 mid-turn path) —
-     *  Issue-6 reads the `[cause: …]` tag from it when errorContext is absent. */
+    /** The last LLM error message the bridge captured on the mid-turn path —
+     *  the context-exhausted reply reads the `[cause: …]` tag from it when
+     *  errorContext is absent. */
     lastLlmErrorMessage?: string;
     failedToolCalls?: number;
     failedTools?: string[];
@@ -61,9 +62,9 @@ export interface PostExecutionBridgeResult {
     /** Estimated 1h TTL cache write tokens from TTL split data. */
     cacheWrite1hTokens?: number;
     /** Session-cumulative total cost across all turns (USD). */
-    sessionCostUsd?: number;
-    /** Per-tool execution results carrying the classified errorKind (Plan 01) —
-     *  the rollup's failure source for toolStats + topErrorKinds (D5/F1). */
+    executionCostUsd?: number;
+    /** Per-tool execution results carrying the classified errorKind —
+     *  the rollup's failure source for toolStats + topErrorKinds. */
     toolExecResults?: Array<{
         toolName: string;
         success: boolean;
@@ -71,12 +72,12 @@ export interface PostExecutionBridgeResult {
         errorText?: string;
         errorKind?: ErrorKind;
     }>;
-    /** How many times a tool circuit breaker opened this session (Plan 01). */
+    /** How many times a tool circuit breaker opened this session. */
     breakerTripCount?: number;
-    /** Turn count for the session:summary event (Plan 02/F2). */
+    /** Turn count for the session:summary event. */
     turnCount?: number;
     /**
-     * The SDK-normalized stop reason of the session's FINAL turn (QT3). The bridge
+     * The SDK-normalized stop reason of the session's FINAL turn. The bridge
      * captures `AssistantMessage.stopReason` at EVERY `turn_end`
      * (pi-event-bridge.ts), so the value carried here is the TERMINAL one. Its
      * union is `"stop" | "length" | "toolUse" | "error" | "aborted"` (pi-ai) — a
@@ -87,7 +88,7 @@ export interface PostExecutionBridgeResult {
      */
     lastStopReason?: string;
     /** Session-cumulative cache savings across all turns (USD). */
-    sessionCacheSavedUsd?: number;
+    executionCacheSavedUsd?: number;
     /** Thinking tokens from SDK reasoningTokens field. */
     thinkingTokens?: number;
     /** Number of pre-LLM-call hash-assertion walks performed (one per turn_start). */
@@ -109,7 +110,7 @@ export interface PostExecutionBridgeResult {
      *  Conditionally emitted on the Execution-complete log when > 0 — mirrors
      *  the per-event `costCorrection` breadcrumb gate in pi-event-bridge.ts. */
     totalCostCorrectionDeltaUsd?: number;
-    /** R2 (Phase 153): abort-redirect message set at bridge abort sites
+    /** Abort-redirect message set at bridge abort sites
      *  (max_steps, budget_exceeded, loop_detected, …). When present and the
      *  turn did not finish with "stop", post-execution replaces the response
      *  so a weak executive never free-associates after an abort. Mirrors
@@ -142,8 +143,8 @@ export interface PostExecutionParams {
     };
     config: PerAgentConfig;
     msg: NormalizedMessage;
-    /** USER.md preferred language (DET-02 tier-2), threaded from prompt assembly.
-     *  Consumed by the degraded-reply resolver (GEN-02, wired in 181-03). */
+    /** USER.md preferred language, threaded from prompt assembly. Consumed by
+     *  the degraded-reply resolver (priority: config > USER.md > inbound script). */
     userMdLanguage?: string;
     sessionKey: SessionKey;
     formattedKey: string;
@@ -161,11 +162,11 @@ export interface PostExecutionParams {
         id: string;
         content: string;
     }>;
-    /** ATTR-02: the per-turn skill ids attributed by ATTR-01 (skillNames whose
+    /** The per-turn skill ids attributed by the bridge (skillNames whose
      *  frozen `<location>` a `read` matched), read back from the bridge's named
      *  carrier. When non-empty, postExecution emits the counts/ids-only
-     *  `memory:skill_used` write-back (the daemon Plan 07 consumes it). Absent /
-     *  empty ⇒ no emit (byte-identical to pre-patch). Ids only — never bodies. */
+     *  `memory:skill_used` write-back (the daemon's learning subscriber consumes
+     *  it). Absent / empty ⇒ no emit. Ids only — never bodies. */
     usedSkillIds?: ReadonlyArray<string>;
     bridge: PostExecutionBridge;
     unsubscribe: () => void;
@@ -200,13 +201,13 @@ export interface PostExecutionParams {
     geminiCachedTokens: number;
     capabilityClass: CapabilityClass | undefined;
     /**
-     * SUMW-02: the turn's budget window — computeTokenBudgetForProfile().windowTokens
+     * The turn's budget window — computeTokenBudgetForProfile().windowTokens
      * = min(reconciled contextWindow, capability class cap). MUST be computed
      * UPSTREAM (pi-executor threads it off the tool-assembly result): this module
      * has no real ModelProfile (only a synthetic scaffold profile), so it can never
      * re-derive the value. Threaded into BOTH LCD after-turn triggers as the
      * REQUIRED utilization denominator — a captured number, dispose-safe on the
-     * deferred (C4) path by construction.
+     * deferred path by construction.
      */
     budgetWindowTokens: number;
     /**
@@ -236,22 +237,22 @@ export interface PostExecutionParams {
         eventBus: TypedEventBus;
         logger: ComisLogger;
         memoryPort?: MemoryPort;
-        /** Optional LCD context store (Phase 128 dag-mode write-path, A1). Present
+        /** Optional LCD context store (the dag-mode write-path). Present
          *  ⇒ the turn's NEW messages are ingested at afterTurn; absent ⇒ skipped
          *  cleanly. TYPE-only core port (the agent↛memory cut). */
         contextStore?: ContextStorePort;
         /** Tenant id for the LCD ingest scope. Threaded from PiExecutorDeps.tenantId
-         *  at the call site so the scope's SECURITY column is never empty
-         *  (T-128-08). Falls back to the session key tenant when absent. */
+         *  at the call site so the scope's SECURITY column is never empty.
+         *  Falls back to the session key tenant when absent. */
         tenantId?: string;
-        /** Getter for the leaf-summarizer deps (Phase 129, C1). Present ⇒ the
+        /** Getter for the leaf-summarizer deps. Present ⇒ the
          *  afterTurn leaf pass is wired live (over threshold ⇒ a leaf summary is
          *  persisted); absent ⇒ the pass is gated off cleanly. Sourced from the
          *  context-engine setup's getCompactionDeps-style getters; TYPE-only (the
          *  agent↛memory cut — the LLM call lives behind the injected summarizer).
-         *  Accepts an optional `modelSnapshot`: the DEFERRED (C4) path passes a model
+         *  Accepts an optional `modelSnapshot`: the DEFERRED path passes a model
          *  identity captured BEFORE `session.dispose()` so a detached pass never
-         *  re-reads a torn-down `session.agent.state` (WR-04). */
+         *  re-reads a torn-down `session.agent.state`. */
         getSummarizerDeps?: (modelSnapshot?: CompactionModelSnapshot) => LeafSummarizerDeps;
         activeRunRegistry?: ActiveRunRegistry;
         embeddingEnqueue?: (entryId: string, content: string) => void;
@@ -312,12 +313,13 @@ export interface StorePairedConversationMemoryArgs {
 /**
  * Persist a paired-conversation memory through the secret-egress firewall.
  *
- * SECURITY (FIX 1): the paired-conversation write is the highest-volume memory
- * path (every qualifying turn) and was the ONLY agent-visible memory write that
- * bypassed `validateMemoryWrite`. A user who pasted a secret into chat had it
- * written VERBATIM to the `memories` table AND embedded into the vector index —
- * recallable across sessions — even though the explicit `memory_store` tool
- * refuses it (cosmetic for data-at-rest). The DERIVED-memory writes
+ * SECURITY: the paired-conversation write is the highest-volume memory
+ * path (every qualifying turn); without this guard it would be the only
+ * agent-visible memory write that bypasses `validateMemoryWrite`. A user who
+ * pasted a secret into chat would have it written VERBATIM to the `memories`
+ * table AND embedded into the vector index — recallable across sessions — even
+ * though the explicit `memory_store` tool refuses it (cosmetic for
+ * data-at-rest). The DERIVED-memory writes
  * (user-representation, consolidation) all run `validateMemoryWrite`
  * FIRST; this helper applies the SAME guard to the paired write for parity.
  *
@@ -375,39 +377,35 @@ export declare function shouldRunLcdStorePasses(config: {
  * SINGLE SOURCE OF TRUTH for the run's terminal classification: the rollup's
  * `degraded` flag (session-health-rollup.ts) is derived from the value this map
  * yields (degraded := mapped endReason !== "success"), so `endReason` and
- * `degraded` are computed from the SAME table and cannot diverge (Phase 152
- * CR-01/WR-01). Exported so the chokepoint maps once and the unit tests can
+ * `degraded` are computed from the SAME table and cannot diverge.
+ * Exported so the chokepoint maps once and the unit tests can
  * enumerate the finishReason union against it.
  *
  * Every KNOWN, in-union `ExecutionResult.finishReason` is listed EXPLICITLY —
- * including `loop_detected` (turn-loop-detector abort) and `session_reset`,
- * which reach the rollup verbatim and previously relied on the `?? "error"`
- * fallthrough (WR-02). The fallthrough is now reserved for its stated purpose:
+ * including `loop_detected` (turn-loop-detector abort) and `session_reset`.
+ * The `?? "error"` fallthrough is reserved for its stated purpose:
  * a defensive bucket for UNKNOWN provider strings we haven't classified yet,
  * not a silent home for classified in-union reasons. Module-level so the
  * post-execution path doesn't reallocate it on every turn.
  *
- * NOTE: the endReason union's "timeout" literal — dead since the union was
- * written — is ALIVE as of LAT-04 (Phase 177): the `prompt_timeout` entry
- * below is its ONLY source. The WR-02 test that pinned its unreachability
- * became a positive pin (prompt_timeout → "timeout", sole source): the
- * negative pin existed to prevent ACCIDENTAL re-introduction; this mapping
- * is the deliberate one.
- *
- * QT2/QT3 — NAMED degradation causes (Glass Box degradation detectors). The
- * taxonomy used to FLATTEN context-exhaustion into the generic "error" bucket,
- * so obs.explain / obs.fleet.health could not tell a context-exhausted session
- * from a tool crash. The two related context-exhaustion finish reasons —
+ * NOTE: the `prompt_timeout` entry below is the ONLY source of the endReason
+ * union's "timeout" literal — a test pins that no other mapping produces it,
+ * so the named cause stays deliberate rather than accidental.
+ *
+ * NAMED degradation causes: flattening context-exhaustion into the generic
+ * "error" bucket would leave obs.explain / obs.fleet.health unable to tell a
+ * context-exhausted session from a tool crash. The two related
+ * context-exhaustion finish reasons —
  * `context_exhausted` (the bridge's hard context-window-guard abort,
  * bridge-safety-controls.ts) and `context_loop` (the loop-on-exhaustion abort) —
- * now FOLD into ONE named cause `"context_exhausted"`. `output_starved` (the
- * chokepoint promotes a terminal output-cap truncation, QT3) is its own named
+ * FOLD into ONE named cause `"context_exhausted"`. `output_starved` (the
+ * chokepoint promotes a terminal output-cap truncation) is its own named
  * cause `"output_starved"`. Both are degraded by construction (≠ "success", so
  * session-health-rollup's CLEAN_END_REASONS derives degraded:true unchanged).
  */
 export declare const END_REASON_MAP: Record<string, NonNullable<SessionMetadata["sessionEnd"]>["endReason"]>;
 /**
- * QT3 — promote a PATHOLOGICAL terminal output truncation to the named cause.
+ * Promote a PATHOLOGICAL terminal output truncation to the named cause.
  *
  * Returns `"output_starved"` IFF the run would OTHERWISE end clean
  * (`stop`/`end_turn` → `success`) AND the session's FINAL turn stopped at the
@@ -415,7 +413,7 @@ export declare const END_REASON_MAP: Record<string, NonNullable<SessionMetadata[
  * returns `effectiveFinishReason` UNCHANGED.
  *
  * This is deliberately conservative — the hard rule is "do not flag healthy
- * sessions" (the spike's load-bearing guard):
+ * sessions" (the load-bearing guard):
  *   - It fires ONLY on a CLEAN would-be terminal. A run that already settled on
  *     a non-clean cause (tool errors, budget, breaker, context_exhausted, error)
  *     keeps that upstream cause — the truncation is not the headline there.
@@ -434,15 +432,14 @@ export declare const END_REASON_MAP: Record<string, NonNullable<SessionMetadata[
  */
 export declare function promoteOutputStarved(effectiveFinishReason: string, lastStopReason: string | undefined): string;
 /**
- * Issue-4 (small-model e2e 2026-06-12) — promote a narrate-without-emit
- * terminal to the named cause `narration_stall`.
+ * Promote a narrate-without-emit terminal to the named cause `narration_stall`.
  *
  * Fires IFF the run would OTHERWISE end clean (`stop`/`end_turn`) AND the
  * narrate-nudge FIRED for this turn but did NOT recover a real answer — the
  * delivered response is still mid-task narration ("Now let me run the
- * tool:") with no tool call behind it. Such a turn was previously recorded
- * `degraded:false, endReason:success` (the soft false-clean: live session
- * uc4-uc5-35). Mirrors {@link promoteOutputStarved}'s conservative shape:
+ * tool:") with no tool call behind it. Without this promotion such a turn
+ * records `degraded:false, endReason:success` — a soft false-clean.
+ * Mirrors {@link promoteOutputStarved}'s conservative shape:
  * an already-non-clean cause always wins, and a recovered (or never-fired)
  * nudge changes nothing.
  *
@@ -477,25 +474,25 @@ export declare function buildSessionEndMetadata(args: {
     totalTokens: number;
     executionId: string;
     traceId: string | undefined;
-    /** T1.4 (F5): the formatted session key, stored so the metadata can drive `comis explain`. */
+    /** The formatted session key, stored so the metadata can drive `comis explain`. */
     sessionKey: string;
     clock: ClockPort;
-    /** F1 health rollup (D5) — the 5 fields spread onto sessionEnd. Computed once
+    /** The health rollup — the 5 fields spread onto sessionEnd. Computed once
      *  at the chokepoint via buildSessionHealthRollup so this builder stays pure. */
     rollup: SessionHealthRollup;
 }): SessionMetadata;
 /**
- * F2 emit: announce `session:summary` on the eventBus once per execution.
+ * Announce `session:summary` on the eventBus once per execution.
  *
  * The payload carries ids + counts + typed flags PLUS `topErrorKinds` and
- * `source` (Phase 159 A1/A2 — OQ1 reversed): both are threaded into the
+ * `source`: both are threaded into the
  * persisted `obs_diagnostics` row so the fleet aggregate
  * (`aggregateSessionsInWindow`) can read them without opening per-session
  * `_session-metadata.json`. Production emits the constant `source: "runtime"`;
  * a synthetic/test row is produced by a caller injecting `source: "test"`.
  * Fire-and-forget by contract: the eventBus is SYNCHRONOUS, so a throwing
- * in-process listener would otherwise abort the caller's teardown (OQ3). The
- * try/catch here is the sanctioned telemetry guard (mirrors the `:983`
+ * in-process listener would otherwise abort the caller's teardown. The
+ * try/catch here is the sanctioned telemetry guard (mirrors the
  * `writeSessionMetadata` guard) — a telemetry failure must never break execution.
  */
 export declare function emitSessionSummary(deps: {
@@ -509,12 +506,12 @@ export declare function emitSessionSummary(deps: {
     rollup: SessionHealthRollup;
     /** The mapped endReason (named degradation cause) — the SAME value derived
      *  once at the chokepoint via END_REASON_MAP and co-persisted on sessionEnd.
-     *  Carried so the row feeds the fleet `degradedByCause` aggregate (QT2/QT3). */
+     *  Carried so the row feeds the fleet `degradedByCause` aggregate. */
     endReason: string;
     clock: ClockPort;
 }): void;
 /**
- * WR-04 lifetime guard for the DEFERRED (C4) compaction path.
+ * Lifetime guard for the DEFERRED compaction path.
  *
  * The deferred leaf/condense passes are enqueued DETACHED onto the per-conversation
  * serializer and can run AFTER `postExecution` returns + `session.dispose()` tears
@@ -545,7 +542,7 @@ export declare function emitSessionSummary(deps: {
  */
 export declare function snapshotSummarizerDepsForDefer(getSummarizerDeps: ((modelSnapshot?: CompactionModelSnapshot) => LeafSummarizerDeps) | undefined): ((modelSnapshot?: CompactionModelSnapshot) => LeafSummarizerDeps) | undefined;
 /**
- * Classify failed tools into the subset that was NOT recovered this turn (HR-01).
+ * Classify failed tools into the subset that was NOT recovered this turn.
  *
  * A tool failure is "recovered" when the SAME tool name also has a successful
  * execution in `toolExecResults` for this turn — e.g. the model retried after a
@@ -556,8 +553,8 @@ export declare function snapshotSummarizerDepsForDefer(getSummarizerDeps: ((mode
  * an error" because the notice keyed off raw failedTools.
  *
  * Safe fallback: when `toolExecResults` is absent/empty (success record not
- * plumbed on some path) every failed tool is reported as unrecovered — i.e. the
- * pre-HR-01 behavior, so this never HIDES a genuine unrecovered failure.
+ * plumbed on some path) every failed tool is reported as unrecovered —
+ * so this never HIDES a genuine unrecovered failure.
  *
  * Observability is unaffected: effectiveFinishReason / logs / fleet rollup still
  * record the failure. Only the user-facing reply is gated.
@@ -576,10 +573,10 @@ export declare function unrecoveredFailedToolNames(failedTools: string[], toolEx
  * Surfaced on the execution bookend (`recoveredTools`) so an operator reading
  * `failedTools:["write"]` + `completed_with_tool_errors` can tell a SELF-HEALED
  * turn from a terminally-degraded one without diffing the raw per-call
- * `toolExecResults`. This does NOT change the degraded classification: by the
- * HR-01 design effectiveFinishReason / the rollup STILL record the failure (the
- * tool DID error); this only makes the recovery VISIBLE. (hermes-usecases
- * obs-loop 2026-06-25.) Pure; deduped; empty when nothing was recovered.
+ * `toolExecResults`. This does NOT change the degraded classification: by
+ * design effectiveFinishReason / the rollup STILL record the failure (the
+ * tool DID error); this only makes the recovery VISIBLE.
+ * Pure; deduped; empty when nothing was recovered.
  */
 export declare function recoveredFailedToolNames(failedTools: string[], toolExecResults?: Array<{
     toolName: string;