comisai 1.0.24 → 1.0.26

package/node_modules/@comis/agent/dist/bridge/thinking-block-hash-invariant.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Thinking-block hash invariant -- diagnostic instrumentation only.
+ *
+ * Observed problem: Anthropic 400 `messages.N.content.M: thinking/redacted_thinking
+ * blocks cannot be modified` errors keep firing in production even after the
+ * surrogate-guard, drift-scrubber, and signed-replay-detector layers shipped
+ * (260425-rvm), and even after the immutable-section redirect (260425-t40).
+ * Trace `c7b91328-9dc5-4618-9ae8-ca207b4b93df` on 2026-04-28 hit a 400 ~2.2s
+ * after `turn_end` -- meaning *some other layer* mutates a signed thinking
+ * block between the assistant turn and the next replay. We don't know which.
+ *
+ * This module is the diagnostic. At each `turn_end` with signed thinking
+ * blocks, the bridge captures a SHA-256 hash of every thinking block. Before
+ * the next assistant-message resend, the bridge recomputes the hashes and
+ * asserts they match the captured snapshots. On mismatch, ONE structured
+ * ERROR log fires per mutated index with enough context to pinpoint the
+ * offending layer (responseId, blockIndex, old/new hash, first-32-chars of
+ * old/new text, signature length before/after).
+ *
+ * Behavior contract (enforced by tests + source-shape grep):
+ * - NEVER throws. Every code path returns normally; logger errors are
+ *   swallowed because we don't want the diagnostic itself to abort agent flow.
+ * - NEVER mutates inputs. Pure read; only output is the structured log.
+ * - NEVER alters request flow. The mismatch is observable signal only --
+ *   Anthropic's 400 still surfaces through the existing error path
+ *   (signed-replay-detector -> executor-prompt-runner). Bug A behavior fix
+ *   is a separate quick task gated on what this diagnostic reveals.
+ *
+ * Logging surface follows CLAUDE.md canonical Pino fields:
+ * - object-first signature: `error({...fields}, "msg")`
+ * - `module: "agent.bridge.hash-invariant"`
+ * - `errorKind: "internal"` (classification per AGENTS.md §2.1)
+ * - `hint`: actionable next step for the on-call diagnoser
+ * - `responseId`, `blockIndex`, `oldHash`, `newHash`,
+ *   `oldText.firstChars`, `newText.firstChars`, `oldSigLen`, `newSigLen`
+ *
+ * Privacy / threat note: `oldText.firstChars` and `newText.firstChars` are
+ * 32-char prefixes of `block.thinking`. Anthropic redacts thinking text
+ * upstream when it would leak credentials, and Comis layers (surrogate guard,
+ * drift scrubber) further sanitize before any persistence. The hash itself is
+ * one-way and non-credential-bearing. Pino's redaction config is a safety net.
+ *
+ * @module
+ */
+/** A captured snapshot of one thinking block's hash + diagnostic prefix. */
+export interface ThinkingBlockHash {
+    /** Position within the thinking-only stream (skips text/tool/redacted blocks). */
+    blockIndex: number;
+    /** SHA-256 hex digest of `(type | thinking | thinkingSignature | redacted)`. */
+    hash: string;
+    /** First 32 chars of `thinking` -- diagnostic on mismatch only. */
+    textFirstChars: string;
+    /** Length of `thinkingSignature` -- diagnostic, never the value. */
+    sigLen: number;
+}
+/** Logger surface required by `assertThinkingBlocksUnchanged`. */
+export interface AssertDeps {
+    logger: {
+        error: (obj: Record<string, unknown>, msg: string) => void;
+    };
+}
+/** Result shape returned by `assertThinkingBlocksUnchanged`. Counters surface
+ *  what the helper observed on this call so callers can emit telemetry without
+ *  re-walking the inputs. Fields are computed even when the helper is a no-op
+ *  (empty prior). */
+export interface AssertResult {
+    /** Number of `prior` entries we walked (equals `prior.length` when prior is
+     *  an array; 0 when prior was empty/non-array). */
+    candidatesChecked: number;
+    /** Number of structured ERROR logs emitted on this call (1 per missing
+     *  index + 1 per hash-mismatch index). */
+    mismatchesLogged: number;
+    /** True iff at least one prior `blockIndex` had a corresponding entry in
+     *  `current`, regardless of whether the hashes matched. False when current
+     *  was empty/non-array OR every prior index was missing. */
+    anyResponseIdMatched: boolean;
+}
+/**
+ * Compute SHA-256 hashes for every `type:"thinking"` block in `content`.
+ *
+ * Mirrors signature-surrogate-guard's exclusion rule: skips non-thinking
+ * blocks AND skips blocks where `redacted === true` (no readable text). The
+ * resulting `blockIndex` field counts position WITHIN the thinking-only
+ * stream, so callers can compare positionally even when the surrounding mix
+ * of text/tool blocks varies between turns.
+ *
+ * Pure: never mutates input, never throws. Returns an empty array when
+ * `content` is empty or contains no thinking blocks.
+ */
+export declare function computeThinkingBlockHashes(content: ReadonlyArray<Record<string, unknown>> | undefined | null): ThinkingBlockHash[];
+/**
+ * Compare prior captured hashes against the current shape of `content`.
+ *
+ * Logs ONE structured ERROR per mismatched index. When `prior` is empty,
+ * this is a no-op (no hashes were captured for this responseId, so there's
+ * nothing to verify). When `current` has fewer thinking blocks than `prior`,
+ * each missing index is reported with `newHash:null`, `newText.firstChars:""`,
+ * `newSigLen:0`.
+ *
+ * Never throws. Never mutates `prior` or `current`.
+ */
+export declare function assertThinkingBlocksUnchanged(prior: ReadonlyArray<ThinkingBlockHash>, current: ReadonlyArray<Record<string, unknown>> | undefined | null, responseId: string | undefined, deps: AssertDeps): AssertResult;
+/** Logger surface required by `restoreCanonicalThinkingBlocks`. Both methods
+ *  optional; the helper is a silent no-op when omitted. */
+export interface RestoreDeps {
+    logger?: {
+        info: (obj: Record<string, unknown>, msg: string) => void;
+        warn: (obj: Record<string, unknown>, msg: string) => void;
+    };
+}
+/** Result shape returned by `restoreCanonicalThinkingBlocks`. */
+export interface RestoreResult {
+    /** SAME reference as input when no swap happened, otherwise a new top-level array. */
+    messages: unknown[];
+    /** Total number of thinking blocks replaced across all messages. */
+    restoredCount: number;
+    /** Distinct responseIds that had at least one swap, in walk order. */
+    affectedResponseIds: string[];
+}
+/**
+ * Replace mutated thinking blocks with their canonical snapshot, in-memory only.
+ *
+ * Pure: never mutates input arrays or block objects. Idempotent: when canonical
+ * matches in-memory exactly, returns `{ messages: <same ref>, restoredCount: 0,
+ * affectedResponseIds: [] }`. On at least one swap, returns a NEW top-level
+ * array AND a NEW content array on each affected message.
+ *
+ * Replaces ONLY blocks where BOTH `current[i].type === "thinking"` AND
+ * `canonical[i].type === "thinking"` AND `current[i].redacted !== true` AND
+ * `canonical[i].redacted !== true`. Text blocks, tool_use, tool_result,
+ * redacted_thinking, and any block where positional types disagree are passed
+ * through unchanged.
+ *
+ * Skips messages where `role !== "assistant"`, where `responseId` is not a
+ * string, or where the canonical store has no entry for that responseId.
+ *
+ * Never throws. On any unexpected error during the walk (e.g. malformed
+ * canonical entry whose getter throws), the entire result is `{ messages:
+ * <input ref>, restoredCount: 0, affectedResponseIds: [] }` and ONE WARN log
+ * fires with `module: RESTORE_MODULE_FIELD, errorKind: "internal"`.
+ */
+export declare function restoreCanonicalThinkingBlocks(messages: ReadonlyArray<unknown> | undefined | null, canonicalStore: ReadonlyMap<string, ReadonlyArray<unknown>>, deps?: RestoreDeps): RestoreResult;
+export declare const WIRE_DIFF_HINT_FILE_MISSING: string;
+export declare const WIRE_DIFF_HINT_NOT_FOUND: string;
+export declare const WIRE_DIFF_HINT_INTERNAL: string;
+/** A single divergent block found by `diffThinkingBlocksAgainstPersisted`. */
+export interface PersistedDiffEntry {
+    /** Position within the thinking-only stream (matches computeThinkingBlockHashes blockIndex). */
+    blockIndex: number;
+    /** SHA-256 hash of the persisted (canonical) block. */
+    persistedHash: string;
+    /** SHA-256 hash of the in-memory block, or null when the block is missing entirely. */
+    inMemoryHash: string | null;
+    /** First 32 chars of persisted thinking text. */
+    persistedText: {
+        firstChars: string;
+    };
+    /** First 32 chars of in-memory thinking text; empty string when block missing. */
+    inMemoryText: {
+        firstChars: string;
+    };
+    /** Length of the persisted thinkingSignature. */
+    persistedSigLen: number;
+    /** Length of the in-memory thinkingSignature; 0 when block missing. */
+    inMemorySigLen: number;
+}
+/** Logger + readFile dependency injection for `diffThinkingBlocksAgainstPersisted`.
+ *
+ *  Both fields optional. When `readFile` is omitted, the module-level
+ *  `node:fs/promises` readFile is used. When `logger` is omitted, the helper
+ *  silently skips all log calls (used by tests + by silent-failure paths). */
+export interface DiffDeps {
+    logger?: {
+        warn: (obj: Record<string, unknown>, msg: string) => void;
+        error?: (obj: Record<string, unknown>, msg: string) => void;
+    };
+    /** Inject for test isolation. Returns the JSONL file contents as a UTF-8 string. */
+    readFile?: (path: string, encoding: "utf-8") => Promise<string>;
+}
+/**
+ * Diff in-memory thinking blocks against the persisted JSONL canonical.
+ *
+ * Reads the persisted JSONL session file, locates the FIRST assistant message
+ * matching `responseId`, and compares its content (canonical, written from
+ * Anthropic's stream at receipt time) against `inMemoryContent` using the
+ * existing `computeThinkingBlockHashes` primitive.
+ *
+ * Returns an array of `PersistedDiffEntry` -- one per divergent thinking
+ * block. When everything matches positionally, returns `[]`. When in-memory
+ * has fewer thinking blocks than persisted, each missing index produces an
+ * entry with `inMemoryHash: null`, empty `inMemoryText.firstChars`, and
+ * `inMemorySigLen: 0`.
+ *
+ * Behavior contract:
+ * - NEVER throws. Read errors, parse errors, or responseId-not-found degrade
+ *   to ONE WARN log + `[]`.
+ * - When TWO assistant messages share the same responseId in the JSONL,
+ *   uses the FIRST match (matches the bridge's "trust the first persisted
+ *   state" semantic).
+ * - Malformed lines (invalid JSON) are skipped silently; scanning continues.
+ *
+ * @param inMemoryContent - The in-memory content array of the assistant
+ *   message (the same shape pi-ai is about to serialize).
+ * @param responseId - The responseId of the assistant message to look up.
+ * @param jsonlPath - Resolved absolute path to the JSONL session file. Path
+ *   composition is the caller's responsibility (this helper does no
+ *   safePath / sessionKey routing).
+ * @param deps - Optional logger + readFile injection.
+ */
+export declare function diffThinkingBlocksAgainstPersisted(inMemoryContent: ReadonlyArray<Record<string, unknown>> | undefined | null, responseId: string, jsonlPath: string, deps?: DiffDeps): Promise<PersistedDiffEntry[]>;