open-multi-agent-kit 0.78.0

package/dist/replay/replay-engine.js

@@ -0,0 +1,265 @@
+/**
+ * ReplayEngine — restores and replays a run's full execution timeline.
+ *
+ * Reads context capsules, evidence results, and decision traces to reconstruct
+ * the exact sequence of events: provider selection, context delivery,
+ * evidence gates, and repair decisions.
+ */
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { createManifestBuilder } from "./manifest-builder.js";
+import { getRunPath } from "../util/run-store.js";
+import { style, status, label } from "../util/theme.js";
+export async function replayRun(runId, options = {}) {
+    const builder = createManifestBuilder({ runsDir: options.runsDir });
+    const validation = await builder.validate(runId);
+    if (!validation.valid) {
+        console.error(status.error(`Run ${runId} is not replayable:`));
+        for (const err of validation.errors)
+            console.error(`  ${style.red("✕")} ${err}`);
+        process.exit(1);
+    }
+    const manifest = await builder.build(runId);
+    // Filter nodes if requested
+    let nodes = manifest.nodes;
+    if (options.nodeId) {
+        nodes = nodes.filter((n) => n.nodeId === options.nodeId);
+        if (nodes.length === 0) {
+            console.error(status.error(`Node ${options.nodeId} not found in run ${runId}`));
+            process.exit(1);
+        }
+    }
+    // Filter attempts if requested
+    if (options.attemptId) {
+        const targetAttempt = manifest.nodes
+            .flatMap((n) => n.attempts)
+            .find((a) => a.attemptId === options.attemptId);
+        if (!targetAttempt) {
+            console.error(status.error(`Attempt ${options.attemptId} not found in run ${runId}`));
+            process.exit(1);
+        }
+        const parentNode = manifest.nodes.find((n) => n.attempts.some((a) => a.attemptId === options.attemptId));
+        if (parentNode) {
+            nodes = [{
+                    ...parentNode,
+                    attempts: parentNode.attempts.filter((a) => a.attemptId === options.attemptId),
+                }];
+        }
+    }
+    // Build timeline
+    const timeline = await buildTimeline(runId, nodes, options);
+    if (options.json) {
+        console.log(JSON.stringify({ runId, manifest, timeline }, null, 2));
+        return;
+    }
+    renderReplay(runId, manifest, nodes, timeline, options);
+}
+async function buildTimeline(runId, nodes, options) {
+    const events = [];
+    // Load evidence and decisions
+    const evidenceEntries = await loadEvidenceEntries(runId, options.runsDir);
+    const allDecisions = await loadDecisions(runId, options.runsDir);
+    events.push({ at: "", kind: "start", payload: { runId } });
+    for (const node of nodes) {
+        for (const attempt of node.attempts) {
+            events.push({
+                at: attempt.startedAt,
+                kind: "attempt",
+                nodeId: node.nodeId,
+                attemptId: attempt.attemptId,
+                payload: { runtime: attempt.runtime, model: attempt.model, provider: attempt.provider },
+            });
+            // Context capsule event
+            if (options.context) {
+                const capsule = await loadContextCapsule(runId, node.nodeId, attempt.attemptId, options.runsDir);
+                if (capsule) {
+                    events.push({
+                        at: attempt.startedAt,
+                        kind: "context",
+                        nodeId: node.nodeId,
+                        attemptId: attempt.attemptId,
+                        payload: capsule,
+                    });
+                }
+            }
+            // Decisions for this attempt
+            const attemptDecisions = allDecisions.filter((d) => d.attemptId === attempt.attemptId || (d.nodeId === node.nodeId && !d.attemptId));
+            for (const d of attemptDecisions) {
+                const isRepair = d.component === "repair-policy";
+                if (options.decisions || (options.repair && isRepair)) {
+                    events.push({
+                        at: d.at,
+                        kind: isRepair ? "repair" : "decision",
+                        nodeId: node.nodeId,
+                        attemptId: attempt.attemptId,
+                        payload: d,
+                    });
+                }
+            }
+            // Evidence for this attempt
+            if (options.evidence) {
+                const attemptEvidence = evidenceEntries.filter((e) => e.attemptId === attempt.attemptId && e.nodeId === node.nodeId);
+                for (const ev of attemptEvidence) {
+                    events.push({
+                        at: ev.timestamp ?? attempt.endedAt ?? attempt.startedAt,
+                        kind: "evidence",
+                        nodeId: node.nodeId,
+                        attemptId: attempt.attemptId,
+                        payload: ev,
+                    });
+                }
+            }
+            events.push({
+                at: attempt.endedAt ?? attempt.startedAt,
+                kind: "end",
+                nodeId: node.nodeId,
+                attemptId: attempt.attemptId,
+                payload: { status: attempt.status, error: attempt.error, latencyMs: attempt.latencyMs },
+            });
+        }
+    }
+    // Sort by time, stable for same timestamps
+    events.sort((a, b) => {
+        const ta = a.at || "";
+        const tb = b.at || "";
+        if (ta !== tb)
+            return ta.localeCompare(tb);
+        const order = ["start", "attempt", "context", "decision", "repair", "evidence", "end"];
+        return order.indexOf(a.kind) - order.indexOf(b.kind);
+    });
+    return events;
+}
+function renderReplay(runId, manifest, nodes, timeline, _options) {
+    console.log(style.purpleBold(`▶ Replay — ${runId}`));
+    console.log(label("OMK Version", manifest.omkVersion));
+    console.log(label("Started", manifest.startedAt));
+    if (manifest.completedAt)
+        console.log(label("Completed", manifest.completedAt));
+    console.log(label("DAG Hash", manifest.dagHash));
+    console.log("");
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    for (const event of timeline) {
+        switch (event.kind) {
+            case "start": {
+                console.log(style.gray("┌─ Run started"));
+                break;
+            }
+            case "attempt": {
+                const p = event.payload;
+                const providerInfo = p.provider ? ` via ${style.cream(p.provider)}` : "";
+                const modelInfo = p.model ? ` (${p.model})` : "";
+                console.log(`\n  ${style.purpleBold("▸")} ${style.creamBold(event.nodeId ?? "")} ${style.gray(event.attemptId ?? "")}`);
+                console.log(`    ${style.gray("Runtime:")} ${p.runtime}${modelInfo}${providerInfo}`);
+                break;
+            }
+            case "context": {
+                const capsule = event.payload;
+                const tokens = capsule._snapshot?.estimatedTokens ?? 0;
+                const fileCount = capsule.relevantFiles?.length ?? 0;
+                const memCount = capsule.graphMemory?.length ?? 0;
+                console.log(`    ${style.gray("Context:")} ${tokens} tokens, ${fileCount} files, ${memCount} memory facts`);
+                if (capsule.budget) {
+                    console.log(`      ${style.gray("Budget:")} ${capsule.budget.maxInputTokens} max-input, ${capsule.budget.compression} compression`);
+                }
+                if (capsule.goal) {
+                    const goalPreview = capsule.goal.slice(0, 80).replace(/\n/g, " ");
+                    console.log(`      ${style.gray("Goal:")} ${goalPreview}${capsule.goal.length > 80 ? "…" : ""}`);
+                }
+                break;
+            }
+            case "decision": {
+                const d = event.payload;
+                const scores = d.scores ? ` ${style.gray(JSON.stringify(d.scores))}` : "";
+                console.log(`    ${style.gray("Decision:")} [${style.purple(d.component)}] ${d.outputDecision}${scores}`);
+                console.log(`      ${style.gray(d.reason)}`);
+                break;
+            }
+            case "repair": {
+                const d = event.payload;
+                console.log(`    ${style.orange("Repair:")} [${style.purple(d.component)}] ${d.outputDecision}`);
+                console.log(`      ${style.gray(d.reason)}`);
+                break;
+            }
+            case "evidence": {
+                const ev = event.payload;
+                const icon = ev.passed ? style.mint("✓") : style.red("✕");
+                console.log(`    ${icon} ${style.gray("Evidence:")} ${ev.gate}`);
+                if (ev.message)
+                    console.log(`      ${style.gray(ev.message)}`);
+                if (ev.ref)
+                    console.log(`      ${style.gray("Ref: " + ev.ref)}`);
+                break;
+            }
+            case "end": {
+                const p = event.payload;
+                const icon = p.status === "success" ? style.mint("✓") : style.red("✕");
+                const latency = p.latencyMs ? ` ${formatMs(p.latencyMs)}` : "";
+                console.log(`    ${icon} ${style.gray("Result:")} ${p.status}${latency}`);
+                if (p.error)
+                    console.log(`      ${style.red(p.error)}`);
+                const node = nodeMap.get(event.nodeId ?? "");
+                if (node && node.attempts[node.attempts.length - 1]?.attemptId === event.attemptId) {
+                    console.log(`  ${style.gray("└─ Node " + event.nodeId + " complete")}`);
+                }
+                break;
+            }
+        }
+    }
+    // Summary
+    console.log("");
+    console.log(style.purpleBold("Replay Summary"));
+    console.log(`  Nodes:    ${nodes.length}`);
+    console.log(`  Attempts: ${nodes.reduce((s, n) => s + n.attempts.length, 0)}`);
+    console.log(`  Success:  ${style.mint(String(nodes.filter((n) => n.finalStatus === "success").length))}`);
+    console.log(`  Failed:   ${style.red(String(nodes.filter((n) => n.finalStatus === "failed").length))}`);
+}
+async function loadEvidenceEntries(runId, runsDir) {
+    const dir = getRunPath(runId, undefined, runsDir);
+    const path = join(dir, "evidence.jsonl");
+    try {
+        const content = await readFile(path, "utf-8");
+        return content
+            .trim()
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+async function loadDecisions(runId, runsDir) {
+    const dir = getRunPath(runId, undefined, runsDir);
+    const path = join(dir, "decisions.jsonl");
+    try {
+        const content = await readFile(path, "utf-8");
+        return content
+            .trim()
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+async function loadContextCapsule(runId, nodeId, attemptId, runsDir) {
+    const dir = getRunPath(runId, undefined, runsDir);
+    const path = join(dir, "context-capsules", `${nodeId}-${attemptId}.json`);
+    try {
+        const content = await readFile(path, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function formatMs(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const m = Math.floor(ms / 60_000);
+    const s = Math.floor((ms % 60_000) / 1000);
+    return `${m}m${s}s`;
+}

package/dist/runtime/adapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * RuntimeAdapter — provider-routing interface.
+ *
+ * Used by the provider routing layer (src/providers/) to select candidate
+ * runtimes, check health, and dispatch AgentRunRequests.
+ *
+ * It is stricter than AgentRuntime: runNode operates on AgentRunRequest,
+ * and health()/supports()/runNode() are all mandatory.
+ *
+ * For the internal runtime implementation interface, see
+ * src/runtime/agent-runtime.ts (AgentRuntime).
+ */
+import type { RuntimeId, RuntimeKind, RuntimeAuthority, RuntimeCapabilities, RuntimeHealth } from "./contracts/shared.js";
+export type { RuntimeId, RuntimeKind, RuntimeAuthority, RuntimeCapabilities, RuntimeHealth };
+export interface AgentRunRequest {
+    runId: string;
+    nodeId: string;
+    role: string;
+    taskType: string;
+    goalDigest: string;
+    contextCapsule: unknown;
+    worktree: {
+        root: string;
+        isolated: boolean;
+        branch?: string;
+    };
+    authority: {
+        mode: "authority" | "executor" | "proposal" | "advisory" | "veto";
+        allowed: RuntimeAuthority[];
+    };
+    routing: {
+        preferredRuntime?: RuntimeId;
+        candidateRuntimes: RuntimeId[];
+        fallbackChain: RuntimeId[];
+        reason?: string;
+    };
+    constraints: {
+        timeoutMs?: number;
+        maxTokens?: number;
+        requireEvidence: boolean;
+        allowNetwork: boolean;
+        allowShell: boolean;
+        allowFileWrite: boolean;
+        allowMcp: boolean;
+    };
+}
+export interface AgentRunResult {
+    success: boolean;
+    exitCode?: number;
+    stdout: string;
+    stderr: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RuntimeAdapter {
+    id: RuntimeId;
+    displayName: string;
+    kind: RuntimeKind;
+    priority: number;
+    capabilities: RuntimeCapabilities;
+    health(): Promise<RuntimeHealth>;
+    supports(request: AgentRunRequest): boolean;
+    runNode(request: AgentRunRequest, signal?: AbortSignal): Promise<AgentRunResult>;
+}
+export interface RuntimeRouteDecision {
+    selectedRuntime: RuntimeId;
+    candidateRuntimes: RuntimeId[];
+    fallbackChain: RuntimeId[];
+    authorityMode: "authority" | "executor" | "proposal" | "advisory" | "veto";
+    reason: string;
+    confidence: number;
+    rejected?: Array<{
+        runtimeId: RuntimeId;
+        reason: string;
+    }>;
+}
+export declare function isRuntimeId(value: unknown): value is RuntimeId;
+export declare function isRuntimeAdapter(value: unknown): value is RuntimeAdapter;

package/dist/runtime/adapter.js

@@ -0,0 +1,28 @@
+/**
+ * RuntimeAdapter — provider-routing interface.
+ *
+ * Used by the provider routing layer (src/providers/) to select candidate
+ * runtimes, check health, and dispatch AgentRunRequests.
+ *
+ * It is stricter than AgentRuntime: runNode operates on AgentRunRequest,
+ * and health()/supports()/runNode() are all mandatory.
+ *
+ * For the internal runtime implementation interface, see
+ * src/runtime/agent-runtime.ts (AgentRuntime).
+ */
+export function isRuntimeId(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export function isRuntimeAdapter(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const r = value;
+    return (typeof r.id === "string" &&
+        typeof r.displayName === "string" &&
+        typeof r.priority === "number" &&
+        typeof r.capabilities === "object" &&
+        r.capabilities !== null &&
+        typeof r.health === "function" &&
+        typeof r.supports === "function" &&
+        typeof r.runNode === "function");
+}

package/dist/runtime/agent-runtime.d.ts

@@ -0,0 +1,123 @@
+/**
+ * AgentRuntime — interface for runtime implementations.
+ *
+ * Each runtime wraps a specific Kimi/provider invocation mode.
+ */
+import type { TaskResult } from "../contracts/orchestration.js";
+import type { ContextCapsule } from "./context-capsule.js";
+import type { RuntimeCapabilities as SharedRuntimeCapabilities, RuntimeHealth as SharedRuntimeHealth, RuntimeId, RuntimeKind } from "./contracts/shared.js";
+export type { RuntimeAuthority, RuntimeId, RuntimeKind } from "./contracts/shared.js";
+export interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+}
+export interface ToolCallRecord {
+    readonly name: string;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly durationMs: number;
+    readonly success: boolean;
+    /** SHA-256 hash from AuditRecord for dedup/correlation */
+    readonly auditHash?: string;
+    /** Whether secrets were redacted by governance */
+    readonly redacted?: boolean;
+    /** Path to evidence artifact file (.omk/runs/<runId>/artifacts/mcp/<auditId>.json) */
+    readonly evidenceRef?: string;
+}
+export interface AgentRunResult {
+    readonly success: boolean;
+    readonly exitCode?: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly tokenUsage?: TokenUsage;
+    readonly toolCalls?: readonly ToolCallRecord[];
+}
+export interface RuntimeCapabilities extends SharedRuntimeCapabilities {
+    readonly toolCalling?: boolean;
+    readonly streaming?: boolean;
+    readonly maxTokens?: number;
+    readonly live?: boolean;
+    readonly advisory?: boolean;
+    readonly dryRun?: boolean;
+}
+export type RuntimeHealth = SharedRuntimeHealth;
+export interface ToolManifestEntry {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: unknown;
+    readonly readOnly?: boolean;
+    readonly parallelSafe?: boolean;
+    readonly stormExempt?: boolean;
+    readonly skipRetentionSave?: boolean;
+}
+export interface ToolManifest {
+    readonly available: readonly ToolManifestEntry[];
+    readonly mcpServers?: readonly string[];
+    readonly skills?: readonly string[];
+    readonly hooks?: readonly string[];
+}
+export interface AgentContext {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly role?: string;
+    readonly goal?: string;
+    readonly system?: string;
+    readonly files?: readonly string[];
+    readonly memory?: ReadonlyArray<{
+        key: string;
+        source: string;
+        summary: string;
+    }>;
+    readonly goalContext?: unknown;
+    readonly workerManifest?: unknown;
+    readonly abortSignal?: AbortSignal;
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly providerModel?: string;
+    readonly risk?: string;
+    readonly approvalPolicy?: string;
+    readonly sandboxMode?: string;
+    readonly onOutput?: (text: string) => void;
+}
+export interface ProviderPolicy {
+    readonly strategy: "priority-first" | "cost-first" | "latency-first" | "manual" | string;
+    readonly preferredProviders: readonly string[];
+    readonly fallbackChain: readonly string[];
+    readonly maxCost?: number;
+    readonly maxLatencyMs?: number;
+}
+export interface CapabilityManifest extends RuntimeCapabilities {
+    readonly structuredOutput?: boolean;
+}
+export interface AgentTask {
+    readonly prompt: string;
+    readonly context: AgentContext;
+    readonly tools: ToolManifest;
+    readonly providerPolicy: ProviderPolicy;
+    readonly capabilities: CapabilityManifest;
+}
+export interface AgentResult {
+    readonly output: string;
+    readonly exitCode: number;
+    readonly metadata?: Record<string, unknown>;
+    readonly thinking?: string;
+    readonly tokenUsage?: TokenUsage;
+    readonly toolCalls?: readonly ToolCallRecord[];
+}
+export interface AgentRuntime {
+    readonly id: RuntimeId;
+    readonly providerId?: string;
+    readonly displayName?: string;
+    readonly kind?: RuntimeKind;
+    readonly legacy?: boolean;
+    readonly runtimeMode?: string;
+    readonly priority: number;
+    readonly capabilities?: RuntimeCapabilities;
+    supports(capsule: ContextCapsule): boolean;
+    health?(): Promise<RuntimeHealth>;
+    runNode(capsule: ContextCapsule, signal: AbortSignal): Promise<AgentRunResult>;
+    execute?(task: AgentTask): Promise<AgentResult>;
+}
+export declare function toTaskResult(result: AgentRunResult): TaskResult;

package/dist/runtime/agent-runtime.js

@@ -0,0 +1,18 @@
+/**
+ * AgentRuntime — interface for runtime implementations.
+ *
+ * Each runtime wraps a specific Kimi/provider invocation mode.
+ */
+export function toTaskResult(result) {
+    return {
+        success: result.success,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        metadata: {
+            ...result.metadata,
+            ...(result.tokenUsage != null && { tokenUsage: result.tokenUsage }),
+            ...(result.toolCalls != null && result.toolCalls.length > 0 && { toolCalls: result.toolCalls }),
+        },
+    };
+}

package/dist/runtime/cache-stable-session.d.ts

@@ -0,0 +1,55 @@
+import { type OmkToolPrefixSpec } from "./tool-registry-contract.js";
+export interface ImmutablePrefixInput {
+    readonly systemPrompt: string;
+    readonly toolSpecs?: readonly OmkToolPrefixSpec[];
+    readonly fewShots?: readonly string[];
+    readonly pinnedMemory?: readonly string[];
+}
+export interface ImmutablePrefixHashes {
+    readonly systemPromptHash: string;
+    readonly toolSpecsHash: string;
+    readonly fewShotsHash: string;
+    readonly pinnedMemoryHash: string;
+    readonly prefixHash: string;
+}
+export interface ImmutablePrefix {
+    readonly schemaVersion: 1;
+    readonly systemPrompt: string;
+    readonly toolSpecs: readonly OmkToolPrefixSpec[];
+    readonly fewShots: readonly string[];
+    readonly pinnedMemory: readonly string[];
+    readonly hashes: ImmutablePrefixHashes;
+}
+export type AppendOnlyLogRole = "user" | "assistant" | "tool" | "system";
+export interface AppendOnlyLogEntry {
+    readonly role: AppendOnlyLogRole;
+    readonly content: string;
+    readonly createdAt?: string;
+    readonly name?: string;
+}
+export interface VolatileScratch {
+    readonly notes?: readonly string[];
+    readonly planState?: unknown;
+    readonly diagnostics?: readonly CacheDiagnostic[];
+}
+export type CacheDiagnosticLevel = "info" | "warning";
+export type CacheDiagnosticCode = "prefix_initialized" | "prefix_changed" | "system_prompt_changed" | "tool_specs_changed" | "few_shots_changed" | "pinned_memory_changed" | "scratch_reset";
+export interface CacheDiagnostic {
+    readonly level: CacheDiagnosticLevel;
+    readonly code: CacheDiagnosticCode;
+    readonly message: string;
+    readonly previousHash?: string;
+    readonly currentHash?: string;
+}
+export interface OmkSessionState {
+    readonly schemaVersion: 1;
+    readonly prefix: ImmutablePrefix;
+    readonly log: readonly AppendOnlyLogEntry[];
+    readonly scratch: VolatileScratch;
+    readonly diagnostics: readonly CacheDiagnostic[];
+}
+export declare function buildImmutablePrefix(input: ImmutablePrefixInput): ImmutablePrefix;
+export declare function createOmkSessionState(input: ImmutablePrefixInput): OmkSessionState;
+export declare function appendLogEntry(state: OmkSessionState, entry: AppendOnlyLogEntry): OmkSessionState;
+export declare function resetScratch(state: OmkSessionState, scratch?: VolatileScratch): OmkSessionState;
+export declare function diffImmutablePrefix(previous: ImmutablePrefix, next: ImmutablePrefix): CacheDiagnostic[];

package/dist/runtime/cache-stable-session.js

@@ -0,0 +1,108 @@
+import { sortToolPrefixSpecs, } from "./tool-registry-contract.js";
+import { sha256Hex, stableJsonStringify } from "./stable-json.js";
+export function buildImmutablePrefix(input) {
+    const systemPrompt = normalizeStableText(input.systemPrompt);
+    const toolSpecs = sortToolPrefixSpecs(input.toolSpecs ?? []);
+    const fewShots = normalizeStableTextList(input.fewShots ?? []);
+    const pinnedMemory = normalizeStableTextList(input.pinnedMemory ?? []);
+    const systemPromptHash = sha256Hex(systemPrompt);
+    const toolSpecsHash = sha256Hex(stableJsonStringify(toolSpecs));
+    const fewShotsHash = sha256Hex(stableJsonStringify(fewShots));
+    const pinnedMemoryHash = sha256Hex(stableJsonStringify(pinnedMemory));
+    const prefixHash = sha256Hex(stableJsonStringify({
+        schemaVersion: 1,
+        systemPrompt,
+        toolSpecs,
+        fewShots,
+        pinnedMemory,
+    }));
+    return {
+        schemaVersion: 1,
+        systemPrompt,
+        toolSpecs,
+        fewShots,
+        pinnedMemory,
+        hashes: {
+            systemPromptHash,
+            toolSpecsHash,
+            fewShotsHash,
+            pinnedMemoryHash,
+            prefixHash,
+        },
+    };
+}
+export function createOmkSessionState(input) {
+    const prefix = buildImmutablePrefix(input);
+    const diagnostic = {
+        level: "info",
+        code: "prefix_initialized",
+        message: "Cache-stable immutable prefix initialized.",
+        currentHash: prefix.hashes.prefixHash,
+    };
+    return {
+        schemaVersion: 1,
+        prefix,
+        log: [],
+        scratch: {},
+        diagnostics: [diagnostic],
+    };
+}
+export function appendLogEntry(state, entry) {
+    return {
+        ...state,
+        log: [...state.log, normalizeLogEntry(entry)],
+    };
+}
+export function resetScratch(state, scratch = {}) {
+    const diagnostic = {
+        level: "info",
+        code: "scratch_reset",
+        message: "Volatile scratch reset without mutating immutable prefix.",
+        currentHash: state.prefix.hashes.prefixHash,
+    };
+    return {
+        ...state,
+        scratch,
+        diagnostics: [...state.diagnostics, diagnostic],
+    };
+}
+export function diffImmutablePrefix(previous, next) {
+    const diagnostics = [];
+    if (previous.hashes.prefixHash !== next.hashes.prefixHash) {
+        diagnostics.push({
+            level: "warning",
+            code: "prefix_changed",
+            message: "Immutable prefix hash changed; provider prefix cache should be invalidated.",
+            previousHash: previous.hashes.prefixHash,
+            currentHash: next.hashes.prefixHash,
+        });
+    }
+    pushHashDiff(diagnostics, "system_prompt_changed", "System prompt changed.", previous.hashes.systemPromptHash, next.hashes.systemPromptHash);
+    pushHashDiff(diagnostics, "tool_specs_changed", "Tool specs changed.", previous.hashes.toolSpecsHash, next.hashes.toolSpecsHash);
+    pushHashDiff(diagnostics, "few_shots_changed", "Few-shot prefix changed.", previous.hashes.fewShotsHash, next.hashes.fewShotsHash);
+    pushHashDiff(diagnostics, "pinned_memory_changed", "Pinned memory prefix changed.", previous.hashes.pinnedMemoryHash, next.hashes.pinnedMemoryHash);
+    return diagnostics;
+}
+function normalizeStableText(value) {
+    return value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function normalizeStableTextList(values) {
+    return values.map((value) => normalizeStableText(value));
+}
+function normalizeLogEntry(entry) {
+    return {
+        ...entry,
+        content: normalizeStableText(entry.content),
+    };
+}
+function pushHashDiff(diagnostics, code, message, previousHash, currentHash) {
+    if (previousHash === currentHash)
+        return;
+    diagnostics.push({
+        level: "warning",
+        code,
+        message,
+        previousHash,
+        currentHash,
+    });
+}