comisai 1.0.41 → 1.0.44

package/node_modules/@comis/observability/dist/cache-trace/stream-fn-wrapper.js

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: pi-ai StreamFn boundary — re-throws synchronous next() exception (contract violation) after recording model:after audit trail; the executor catches the throw at the streamFn invocation site.
+/**
+ * `buildCacheTraceWrapper` — StreamFn wrapper factory.
+ *
+ * Closure factory that emits TWO cache-trace events per LLM call:
+ *
+ *   1. `stream:context` (pre-call) — message + system digests +
+ *      provider/modelId. The pre-call event is the message-content
+ *      fingerprint for downstream replay/diff tools.
+ *
+ *   2. `model:after` (post-call) — cache-token attribution parsed from
+ *      the StreamFn return value's `usage` block. The pi-ai
+ *      `AssistantMessage` exposes `usage.cacheRead` and `usage.cacheWrite`
+ *      (canonical pi-ai shape); we project them onto the cache-trace
+ *      schema's `cacheReadInputTokens` / `cacheCreationInputTokens`
+ *      (Anthropic-style envelope names — matches the EventBus bridge's
+ *      `observability:token_usage` payload shape).
+ *
+ * Provider-shape narrowing is defensive: when `usage` is absent or
+ * the numeric fields aren't numbers, the `model:after` event still
+ * emits but without the token fields. The post-call event is the
+ * audit trail; missing token data does NOT skip the emit.
+ *
+ * StreamFn error contract (per pi-agent-core types.d.ts):
+ *   - Must not throw or return a rejected promise for model/runtime
+ *     failures.
+ *   - Failures are encoded in the returned stream via a final
+ *     AssistantMessage with `stopReason: "error" | "aborted"` and
+ *     `errorMessage`.
+ *
+ * The wrapper therefore relies on the stream's `.result()` Promise
+ * (which never rejects per the contract) to fire `model:after` — we
+ * project `result.errorMessage` onto the event when stopReason
+ * indicates failure. If `next()` itself throws synchronously (a
+ * contract violation, but defensive), we record `error` on the
+ * model:after event and re-throw so the executor sees the failure.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { stableStringify } from "../shared/stable-stringify.js";
+function sha256(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+/**
+ * Self-bounding cap on the sampled id arrays. Kept strictly BELOW the
+ * cache-trace 64-item array cap (`PAYLOAD_BOUNDS.maxArrayLength`) so the
+ * sampled `toolUseIds` / `toolResultIds` arrays NEVER trip the limiter and
+ * get replaced by an opaque `{ __bounded__: … }` sentinel. The full picture
+ * survives in the count fields (`toolUseCount` / `toolResultCount` /
+ * `pairedToolResultCount`) which are plain integers and cannot vanish under
+ * the bound — so the pairing/orphan invariant the descriptor feeds holds at
+ * ANY turn size, including large parallel-tool fan-outs. WR-01 (Phase 126).
+ */
+const MAX_SAMPLED_IDS = 32;
+function asString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+/**
+ * Walk the assembled provider array and derive its shape descriptor.
+ *
+ * Handles both in-repo content-block conventions defensively:
+ *   - assistant tool calls: `{ type: "tool_use", id }` OR
+ *     `{ type: "toolCall", id | toolCallId }`;
+ *   - tool results: `{ type: "tool_result", tool_use_id | toolCallId }` /
+ *     `{ type: "toolResult", toolCallId }` content blocks, AND the canonical
+ *     pi-ai top-level `{ role: "toolResult", toolCallId }` message.
+ *
+ * The pairing assertion (every toolResultId has a matching toolUseId) is what
+ * the provider-boundary harness rides. The descriptor records a SAMPLE of the
+ * ids (capped at `MAX_SAMPLED_IDS`, below the 64-item payload bound) plus the
+ * TRUE counts (`toolUseCount` / `toolResultCount`) and a precomputed
+ * `pairedToolResultCount` — so the gate asserts on integer counts that survive
+ * the bound rather than reading through a possibly-truncated array.
+ */
+function computeAssembledShape(messages, messageRoles) {
+    const blockKindCounts = {};
+    const toolUseIds = [];
+    const toolResultIds = [];
+    for (const message of messages) {
+        const role = asString(message.role);
+        // Top-level toolResult message (pi-ai ToolResultMessage): the result is
+        // the whole message, keyed by `toolCallId` — there is no content block.
+        if (role === "toolResult") {
+            const tcid = asString(message.toolCallId);
+            if (tcid !== undefined)
+                toolResultIds.push(tcid);
+        }
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            const kind = asString(block.type) ?? "other";
+            blockKindCounts[kind] = (blockKindCounts[kind] ?? 0) + 1;
+            if (kind === "tool_use" || kind === "toolCall") {
+                const id = asString(block.id) ??
+                    asString(block.toolCallId);
+                if (id !== undefined)
+                    toolUseIds.push(id);
+            }
+            else if (kind === "tool_result" || kind === "toolResult") {
+                const id = asString(block.tool_use_id) ??
+                    asString(block.toolCallId);
+                if (id !== undefined)
+                    toolResultIds.push(id);
+            }
+        }
+    }
+    // Pairing/orphan signal computed over the FULL id sets BEFORE sampling, so
+    // the count never depends on the sampled arrays surviving the 64-item cap.
+    // (WR-01: large fan-outs used to defeat the array-based pairing check.)
+    const toolUseIdSet = new Set(toolUseIds);
+    const pairedToolResultCount = toolResultIds.reduce((n, rid) => (toolUseIdSet.has(rid) ? n + 1 : n), 0);
+    return {
+        totalCount: messages.length,
+        blockKindCounts,
+        hasToolResult: toolResultIds.length > 0 || messageRoles.includes("toolResult"),
+        // Sample the id arrays at the source so the limiter never replaces them
+        // with an opaque sentinel; the true totals live in the count fields.
+        toolUseIds: toolUseIds.slice(0, MAX_SAMPLED_IDS),
+        toolResultIds: toolResultIds.slice(0, MAX_SAMPLED_IDS),
+        toolUseCount: toolUseIds.length,
+        toolResultCount: toolResultIds.length,
+        pairedToolResultCount,
+        idsTruncated: toolUseIds.length > MAX_SAMPLED_IDS || toolResultIds.length > MAX_SAMPLED_IDS,
+    };
+}
+/**
+ * Build a StreamFn wrapper that records `stream:context` BEFORE the
+ * call and `model:after` AFTER the call (when the stream's final
+ * result resolves).
+ *
+ * @param trace - the per-session recorder (must be non-null; consumers
+ *                should not call this when `createCacheTrace` returned
+ *                null).
+ */
+export function buildCacheTraceWrapper(trace) {
+    return function cacheTraceWrapper(next) {
+        return ((model, context, options) => {
+            const messages = Array.isArray(context.messages) ? context.messages : [];
+            const messageFingerprints = messages.map((m) => sha256(stableStringify(m)));
+            const messagesDigest = sha256(messageFingerprints.join("|"));
+            const systemPromptText = typeof context.systemPrompt === "string"
+                ? context.systemPrompt
+                : stableStringify(context.systemPrompt ?? "");
+            const systemDigest = sha256(systemPromptText);
+            const messageRoles = messages.map((m) => {
+                const role = m.role;
+                return typeof role === "string" ? role : "unknown";
+            });
+            const preCallPayload = {
+                messageCount: messages.length,
+                messageRoles,
+                messageFingerprints,
+                messagesDigest,
+                systemDigest,
+            };
+            // O2: the SMALL assembled-array shape descriptor (counts/flags + tool
+            // id pairing). Emitted OUTSIDE the includeMessages guard so it is
+            // present even when the full messages array is gated off — it is not a
+            // body dump, so it survives the 32 KB sanitizeForPersistence bound.
+            preCallPayload.assembledShape = computeAssembledShape(messages, messageRoles);
+            if (trace.includeMessages) {
+                preCallPayload.messages = messages;
+            }
+            if (trace.includeSystem) {
+                preCallPayload.system = context.systemPrompt;
+            }
+            // model.provider / model.id are part of the pi-ai Model contract,
+            // but we narrow defensively for test stubs.
+            const modelProvider = model.provider;
+            const modelId = model.id;
+            if (typeof modelProvider === "string")
+                preCallPayload.provider = modelProvider;
+            if (typeof modelId === "string")
+                preCallPayload.modelId = modelId;
+            // Emit `model:before` directly from the wrapper instead of
+            // round-tripping through a new EventBus event. The model context
+            // (provider, modelId) and digest fingerprints are already in
+            // scope here — an EventBus round-trip would carry the same data
+            // through one more hop with no observable benefit. The
+            // `model:before` stage gives operators a forensic "about to call
+            // <model> with <digests>" record for cache-hit diagnosis, ordered
+            // BEFORE the `stream:context` emit.
+            const modelBeforePayload = {};
+            if (typeof modelProvider === "string")
+                modelBeforePayload.provider = modelProvider;
+            if (typeof modelId === "string")
+                modelBeforePayload.modelId = modelId;
+            if (preCallPayload.messagesDigest !== undefined) {
+                modelBeforePayload.messagesDigest = preCallPayload.messagesDigest;
+            }
+            if (preCallPayload.systemDigest !== undefined) {
+                modelBeforePayload.systemDigest = preCallPayload.systemDigest;
+            }
+            trace.recordStage("model:before", modelBeforePayload);
+            trace.recordStage("stream:context", preCallPayload);
+            // Delegate to the next link. The pi-ai StreamFn contract says
+            // failures are encoded in the returned stream (final AssistantMessage
+            // with stopReason: "error" | "aborted") — next() should not throw
+            // for model/runtime failures. We still wrap in try/catch defensively
+            // for contract violations.
+            let returned;
+            try {
+                returned = next(model, context, options);
+            }
+            catch (e) {
+                // Synchronous throw from next — contract violation but defensively
+                // record model:after with the error and re-throw.
+                const err = e instanceof Error ? e : new Error(String(e));
+                trace.recordStage("model:after", {
+                    messagesDigest,
+                    systemDigest,
+                    error: err.message,
+                });
+                throw err;
+            }
+            // Project the stream's final result onto a model:after event.
+            // The pi-ai AssistantMessageEventStream's .result() Promise
+            // resolves to an AssistantMessage carrying `usage` (cacheRead +
+            // cacheWrite per pi-ai types.d.ts:Usage). We splat onto the
+            // Anthropic-style envelope names the cache-trace schema uses.
+            //
+            // The result handler does NOT block the caller — they receive
+            // the stream synchronously and iterate at their own pace. Our
+            // .result() consumption is concurrent and idempotent against the
+            // caller's iteration (EventStream resolves result() from end()
+            // independently of iteration progress).
+            const handleResolved = (raw) => {
+                const post = {
+                    messagesDigest, // re-emit for correlation with the pre-call line
+                    systemDigest,
+                };
+                const usage = raw?.usage;
+                if (usage !== undefined && usage !== null && typeof usage === "object") {
+                    // pi-ai canonical shape: usage.cacheRead, usage.cacheWrite.
+                    // Provider variants may name them cacheReadInputTokens /
+                    // cacheCreationInputTokens (Anthropic) — accept either,
+                    // project onto the cache-trace schema's envelope names.
+                    const u = usage;
+                    const read = typeof u.cacheReadInputTokens === "number"
+                        ? u.cacheReadInputTokens
+                        : typeof u.cacheRead === "number"
+                            ? u.cacheRead
+                            : undefined;
+                    const write = typeof u.cacheCreationInputTokens === "number"
+                        ? u.cacheCreationInputTokens
+                        : typeof u.cacheWrite === "number"
+                            ? u.cacheWrite
+                            : undefined;
+                    if (read !== undefined)
+                        post.cacheReadInputTokens = read;
+                    if (write !== undefined)
+                        post.cacheCreationInputTokens = write;
+                }
+                // Surface a stream-encoded error on the model:after event so
+                // failed calls produce an audit trail.
+                const stopReason = raw?.stopReason;
+                const errorMessage = raw?.errorMessage;
+                if (typeof errorMessage === "string" &&
+                    (stopReason === "error" || stopReason === "aborted")) {
+                    post.error = errorMessage;
+                }
+                trace.recordStage("model:after", post);
+            };
+            const consumeResult = (ret) => {
+                const r = ret;
+                if (typeof r?.result === "function") {
+                    r.result().then(handleResolved, (err) => {
+                        // Per pi-ai contract .result() should not reject; defensive
+                        // emit if it does.
+                        const e = err instanceof Error ? err : new Error(String(err));
+                        trace.recordStage("model:after", {
+                            messagesDigest,
+                            systemDigest,
+                            error: e.message,
+                        });
+                    });
+                }
+                else {
+                    // Test stub or non-stream return: project usage directly
+                    // from the returned value. The test fixture in
+                    // stream-fn-wrapper.test.ts uses this branch.
+                    handleResolved(ret);
+                }
+            };
+            // The StreamFn type union includes Promise<…> — if next() returned
+            // a Promise, await it before consuming .result().
+            if (returned !== null &&
+                typeof returned === "object" &&
+                typeof returned.then === "function") {
+                returned.then(consumeResult, () => {
+                    trace.recordStage("model:after", {
+                        messagesDigest,
+                        systemDigest,
+                        error: "stream-fn-promise-rejected",
+                    });
+                });
+            }
+            else {
+                consumeResult(returned);
+            }
+            return returned;
+        });
+    };
+}

package/node_modules/@comis/observability/dist/cache-trace/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Cache-trace event v1 schema — closed-union stages + Zod envelope.
+ *
+ * The cache-trace is a per-session JSONL sidecar capturing
+ * cache-relevant lifecycle stages for a single agent turn. Each event is
+ * one JSONL line; the file is bounded (`maxFileBytes`) and the writer
+ * gracefully degrades on write failures (the queued writer chassis).
+ *
+ * Closed enum invariant: `CACHE_TRACE_STAGES` is a literal `as const`
+ * tuple so consumers can enumerate it at test time and the Zod schema's
+ * `stage` field rejects unknown stages at parse time.
+ *
+ * Comis improvements over the legacy 16-char-digest cache-trace-writer
+ * (which lived in `packages/agent/src/executor/stream-wrappers`):
+ *   - `traceSchema: "comis-cache-trace"` + `schemaVersion: 1` — explicit
+ *     parser fence; downstream replay/diff tooling can reject foreign
+ *     artifacts.
+ *   - Full 64-char `messagesDigest` + `systemDigest` via
+ *     `stableStringify` (`shared/stable-stringify.ts`) instead of the
+ *     legacy 16-char truncated SHA-256.
+ *   - Per-stage events emitted at lifecycle boundaries — not a single
+ *     point at the LLM call.
+ *   - `cacheReadInputTokens` + `cacheCreationInputTokens` attached to
+ *     `session:after` via the EventBus bridge subscription (the values
+ *     do not physically exist before `observability:token_usage` fires —
+ *     pi-event-bridge.ts:993-1021).
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Closed enum of cache-trace stages.
+ *
+ * Order: lifecycle-relevant (session.* → prompt → model → context → tool
+ * → session.after → control-plane sentinel).
+ * v1 shape established 2026-05-19; rewritten 2026-05-21 to match shipped code; append-only rule applies from 2026-05-21 forward.
+ *
+ * The trailing `cache_trace.write_failures` is a control-plane sentinel
+ * (not an application stage) emitted by the runtime on first queued
+ * writer rejection (inline) AND by `flushAndClose` (summary) when the
+ * underlying queued writer reports per-line append failures. Mirrors
+ * trajectory's `trace.truncated` + `trace.write_failures` precedent
+ * (both inside `TRAJECTORY_EVENT_TYPES`).
+ *
+ * Per-stage inline `// emitted by …` comments document the producer
+ * call site for each stage. Adding a new stage requires (1) appending
+ * to this literal, (2) writing the producer wiring, and (3) updating
+ * the inline comment with the producer location — the comments are
+ * load-bearing documentation for the architecture tests (see
+ * `cache-trace-stages-known.test.ts`) that walk `recordStage(<literal>, …)`
+ * call sites and enforce the closed union.
+ */
+export declare const CACHE_TRACE_STAGES: readonly ["session:start", "session:end", "prompt:before", "prompt:after", "model:before", "model:after", "stream:context", "tool:before", "tool:after", "session:after", "cache_trace.write_failures"];
+/** Closed string union of cache-trace stage names. */
+export type CacheTraceStage = (typeof CACHE_TRACE_STAGES)[number];
+/**
+ * Cache-trace event — one record per JSONL line.
+ *
+ * Required envelope fields: `traceSchema`, `schemaVersion`, `stage`,
+ * `ts`, `seq`, `agentId`, `sessionId`, `traceId`. `traceId` is the
+ * canonical correlation key (the canonical correlation triple) — every
+ * cache-trace event ships with one so downstream
+ * replay/diff/analysis tools can join across multiple JSONL streams
+ * (trajectory, cache-trace, audit log) by traceId.
+ *
+ * The 5 optional envelope fields (`runId`, `sessionKey`, `tenantId`,
+ * `workspaceDir`, `modelApi`) complete the envelope conformance contract
+ * — present when the executor passes them through, omitted otherwise.
+ * Each is `string | undefined` except `modelApi` which is
+ * `string | null | undefined` (the design explicitly allows null for
+ * the "no model API discriminator" case).
+ *
+ * The token-attribution fields (`cacheReadInputTokens`,
+ * `cacheCreationInputTokens`) attach to `session:after` (aggregated
+ * across the session via the EventBus bridge) AND to `model:after`
+ * (per-call snapshot from the StreamFn return value).
+ *
+ * `data` carries control-plane sentinel data (used by
+ * `cache_trace.write_failures` to surface queued-writer rejection
+ * metadata). Application stages do not populate `data`.
+ */
+export declare const CacheTraceEventSchema: z.ZodObject<{
+    traceSchema: z.ZodLiteral<"comis-cache-trace">;
+    schemaVersion: z.ZodLiteral<1>;
+    stage: z.ZodEnum<{
+        "session:start": "session:start";
+        "session:end": "session:end";
+        "prompt:before": "prompt:before";
+        "prompt:after": "prompt:after";
+        "model:before": "model:before";
+        "model:after": "model:after";
+        "stream:context": "stream:context";
+        "tool:before": "tool:before";
+        "tool:after": "tool:after";
+        "session:after": "session:after";
+        "cache_trace.write_failures": "cache_trace.write_failures";
+    }>;
+    ts: z.ZodString;
+    seq: z.ZodNumber;
+    agentId: z.ZodString;
+    sessionId: z.ZodString;
+    traceId: z.ZodString;
+    runId: z.ZodOptional<z.ZodString>;
+    sessionKey: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    workspaceDir: z.ZodOptional<z.ZodString>;
+    modelApi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider: z.ZodOptional<z.ZodString>;
+    modelId: z.ZodOptional<z.ZodString>;
+    messages: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    messageCount: z.ZodOptional<z.ZodNumber>;
+    messageRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    assembledShape: z.ZodOptional<z.ZodObject<{
+        totalCount: z.ZodNumber;
+        blockKindCounts: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        hasToolResult: z.ZodBoolean;
+        toolUseIds: z.ZodArray<z.ZodString>;
+        toolResultIds: z.ZodArray<z.ZodString>;
+        toolUseCount: z.ZodNumber;
+        toolResultCount: z.ZodNumber;
+        pairedToolResultCount: z.ZodNumber;
+        idsTruncated: z.ZodBoolean;
+    }, z.core.$strip>>;
+    messageFingerprints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    messagesDigest: z.ZodOptional<z.ZodString>;
+    system: z.ZodOptional<z.ZodUnknown>;
+    systemDigest: z.ZodOptional<z.ZodString>;
+    cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** Inferred event type — kept in sync with the schema via the test invariant. */
+export type CacheTraceEvent = z.infer<typeof CacheTraceEventSchema>;

package/node_modules/@comis/observability/dist/cache-trace/types.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Cache-trace event v1 schema — closed-union stages + Zod envelope.
+ *
+ * The cache-trace is a per-session JSONL sidecar capturing
+ * cache-relevant lifecycle stages for a single agent turn. Each event is
+ * one JSONL line; the file is bounded (`maxFileBytes`) and the writer
+ * gracefully degrades on write failures (the queued writer chassis).
+ *
+ * Closed enum invariant: `CACHE_TRACE_STAGES` is a literal `as const`
+ * tuple so consumers can enumerate it at test time and the Zod schema's
+ * `stage` field rejects unknown stages at parse time.
+ *
+ * Comis improvements over the legacy 16-char-digest cache-trace-writer
+ * (which lived in `packages/agent/src/executor/stream-wrappers`):
+ *   - `traceSchema: "comis-cache-trace"` + `schemaVersion: 1` — explicit
+ *     parser fence; downstream replay/diff tooling can reject foreign
+ *     artifacts.
+ *   - Full 64-char `messagesDigest` + `systemDigest` via
+ *     `stableStringify` (`shared/stable-stringify.ts`) instead of the
+ *     legacy 16-char truncated SHA-256.
+ *   - Per-stage events emitted at lifecycle boundaries — not a single
+ *     point at the LLM call.
+ *   - `cacheReadInputTokens` + `cacheCreationInputTokens` attached to
+ *     `session:after` via the EventBus bridge subscription (the values
+ *     do not physically exist before `observability:token_usage` fires —
+ *     pi-event-bridge.ts:993-1021).
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Closed enum of cache-trace stages.
+ *
+ * Order: lifecycle-relevant (session.* → prompt → model → context → tool
+ * → session.after → control-plane sentinel).
+ * v1 shape established 2026-05-19; rewritten 2026-05-21 to match shipped code; append-only rule applies from 2026-05-21 forward.
+ *
+ * The trailing `cache_trace.write_failures` is a control-plane sentinel
+ * (not an application stage) emitted by the runtime on first queued
+ * writer rejection (inline) AND by `flushAndClose` (summary) when the
+ * underlying queued writer reports per-line append failures. Mirrors
+ * trajectory's `trace.truncated` + `trace.write_failures` precedent
+ * (both inside `TRAJECTORY_EVENT_TYPES`).
+ *
+ * Per-stage inline `// emitted by …` comments document the producer
+ * call site for each stage. Adding a new stage requires (1) appending
+ * to this literal, (2) writing the producer wiring, and (3) updating
+ * the inline comment with the producer location — the comments are
+ * load-bearing documentation for the architecture tests (see
+ * `cache-trace-stages-known.test.ts`) that walk `recordStage(<literal>, …)`
+ * call sites and enforce the closed union.
+ */
+export const CACHE_TRACE_STAGES = [
+    "session:start", // emitted by event-bus-bridge from session:started
+    "session:end", // emitted by event-bus-bridge from session:ended
+    "prompt:before", // emitted by event-bus-bridge from prompt:submitted (digest-cache pre-state read)
+    "prompt:after", // emitted by event-bus-bridge from prompt:submitted (digest-cache post-state read)
+    "model:before", // emitted by buildCacheTraceWrapper just before stream-fn delegation (stream-fn-wrapper.ts)
+    "model:after", // emitted by buildCacheTraceWrapper post-call (stream-fn-wrapper.ts)
+    "stream:context", // emitted by buildCacheTraceWrapper pre-call (stream-fn-wrapper.ts)
+    "tool:before", // emitted by event-bus-bridge from tool:started
+    "tool:after", // emitted by event-bus-bridge from tool:executed
+    "session:after", // emitted by pi-executor at turn end + terminal emit in flushAndClose
+    "cache_trace.write_failures", // control-plane sentinel — inline + flushAndClose summary
+];
+/**
+ * Cache-trace event — one record per JSONL line.
+ *
+ * Required envelope fields: `traceSchema`, `schemaVersion`, `stage`,
+ * `ts`, `seq`, `agentId`, `sessionId`, `traceId`. `traceId` is the
+ * canonical correlation key (the canonical correlation triple) — every
+ * cache-trace event ships with one so downstream
+ * replay/diff/analysis tools can join across multiple JSONL streams
+ * (trajectory, cache-trace, audit log) by traceId.
+ *
+ * The 5 optional envelope fields (`runId`, `sessionKey`, `tenantId`,
+ * `workspaceDir`, `modelApi`) complete the envelope conformance contract
+ * — present when the executor passes them through, omitted otherwise.
+ * Each is `string | undefined` except `modelApi` which is
+ * `string | null | undefined` (the design explicitly allows null for
+ * the "no model API discriminator" case).
+ *
+ * The token-attribution fields (`cacheReadInputTokens`,
+ * `cacheCreationInputTokens`) attach to `session:after` (aggregated
+ * across the session via the EventBus bridge) AND to `model:after`
+ * (per-call snapshot from the StreamFn return value).
+ *
+ * `data` carries control-plane sentinel data (used by
+ * `cache_trace.write_failures` to surface queued-writer rejection
+ * metadata). Application stages do not populate `data`.
+ */
+export const CacheTraceEventSchema = z.object({
+    traceSchema: z.literal("comis-cache-trace"),
+    schemaVersion: z.literal(1),
+    stage: z.enum(CACHE_TRACE_STAGES),
+    ts: z.string(), // ISO-8601
+    seq: z.number().int().nonnegative(),
+    agentId: z.string(),
+    sessionId: z.string(),
+    // §7.2 canonical correlation key — required. Auto-derived from the
+    // AsyncLocalStorage RequestContext when present, falling back to
+    // sessionId.
+    traceId: z.string(),
+    // §7.2 envelope fields — optional; the executor wires what's reachable.
+    runId: z.string().optional(),
+    sessionKey: z.string().optional(),
+    tenantId: z.string().optional(),
+    workspaceDir: z.string().optional(),
+    modelApi: z.string().nullable().optional(),
+    provider: z.string().optional(),
+    modelId: z.string().optional(),
+    // Message / system payloads (gated by includeMessages / includeSystem).
+    messages: z.array(z.unknown()).optional(),
+    messageCount: z.number().int().nonnegative().optional(),
+    messageRoles: z.array(z.string()).optional(),
+    // O2 (Phase 126): a SMALL assembled-array shape descriptor — per-message
+    // block-kind counts + a `hasToolResult` flag + tool_use/tool_result
+    // id-pairing summary. It lets a test assert tool_use<->tool_result pairing
+    // + array growth WITHOUT shipping the full `messages` array, so it is
+    // present even when includeMessages is OFF. Counts/flags + opaque
+    // toolCallId strings ONLY — never block bodies — so it stays well under the
+    // 32 KB bound and rides sanitizeForPersistence unchanged (it is NOT added
+    // to the exempt set). The permanent provider-boundary regression gate
+    // asserts against this (see provider-boundary-harness.test.ts).
+    //
+    // WR-01 (Phase 126): the `toolUseIds` / `toolResultIds` arrays are a SAMPLE
+    // (capped at MAX_SAMPLED_IDS, below the 64-item array bound) so the limiter
+    // never replaces them with an opaque sentinel on large tool fan-outs. The
+    // authoritative pairing/growth signal lives in the integer count fields
+    // (`toolUseCount` / `toolResultCount` / `pairedToolResultCount`), which
+    // cannot vanish under the bound; `idsTruncated` flags when the arrays are a
+    // partial sample.
+    assembledShape: z
+        .object({
+        totalCount: z.number().int().nonnegative(),
+        blockKindCounts: z.record(z.string(), z.number().int().nonnegative()),
+        hasToolResult: z.boolean(),
+        toolUseIds: z.array(z.string()),
+        toolResultIds: z.array(z.string()),
+        toolUseCount: z.number().int().nonnegative(),
+        toolResultCount: z.number().int().nonnegative(),
+        pairedToolResultCount: z.number().int().nonnegative(),
+        idsTruncated: z.boolean(),
+    })
+        .optional(),
+    messageFingerprints: z.array(z.string()).optional(),
+    messagesDigest: z.string().optional(),
+    system: z.unknown().optional(),
+    systemDigest: z.string().optional(),
+    // Token attribution. `session:after` aggregates across the session via
+    // the EventBus bridge stash; `model:after` carries the per-call snapshot
+    // from the StreamFn return value's usage block.
+    cacheReadInputTokens: z.number().int().nonnegative().optional(),
+    cacheCreationInputTokens: z.number().int().nonnegative().optional(),
+    // Sentinel data (cache_trace.write_failures only).
+    data: z.unknown().optional(),
+});