open-multi-agent-kit 0.90.8 → 0.91.0

package/dist/core/session-file-persistence.js

@@ -0,0 +1,106 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { atomicRewriteFileSync } from "./atomic-session-file.js";
+import { createSessionRevisionToken } from "./compaction/transaction.js";
+import { readDurableFileSnapshot, sameDurableFileGeneration, writeExclusiveFileDurablySync, } from "./durable-file-io.js";
+import { readSessionFileDurableMetadata, sessionFileHasCompleteTail } from "./session-file-head.js";
+export class SessionManagerStaleWriteError extends Error {
+    constructor(message = "Session file changed since this manager accepted its durable head") {
+        super(message);
+        this.name = "SessionManagerStaleWriteError";
+    }
+}
+export function quarantineSessionTrailingFragment(filePath) {
+    if (sessionFileHasCompleteTail(filePath))
+        return { report: null, snapshot: null };
+    if (statSync(filePath).nlink > 1)
+        throw new Error("Session quarantine refused for a target with more than one hard link");
+    const snapshot = readDurableFileSnapshot(filePath);
+    if (!snapshot)
+        return { report: null, snapshot: null };
+    let lastNewline = -1;
+    for (let index = snapshot.bytes.byteLength - 1; index >= 0; index -= 1) {
+        if (snapshot.bytes[index] === 0x0a) {
+            lastNewline = index;
+            break;
+        }
+    }
+    const completePrefixByteCount = lastNewline + 1;
+    const fragment = snapshot.bytes.subarray(completePrefixByteCount);
+    const quarantinePath = `${filePath}.quarantine-${randomUUID()}`;
+    writeExclusiveFileDurablySync(quarantinePath, fragment);
+    const current = readDurableFileSnapshot(filePath);
+    if (!current ||
+        !sameDurableFileGeneration(snapshot.generation, current.generation) ||
+        Buffer.compare(snapshot.bytes, current.bytes) !== 0) {
+        throw new SessionManagerStaleWriteError();
+    }
+    atomicRewriteFileSync(filePath, snapshot.bytes.subarray(0, completePrefixByteCount));
+    return {
+        report: Object.freeze({
+            artifact: "session",
+            path: filePath,
+            quarantinePath,
+            byteCount: fragment.byteLength,
+            completePrefixByteCount,
+        }),
+        snapshot: readDurableFileSnapshot(filePath),
+    };
+}
+export function sessionDurableHeadFromSnapshot(snapshot, activeLeafId, entries) {
+    const header = entries[0];
+    if (!header || header.type !== "session" || typeof header.id !== "string")
+        return null;
+    let recordCount = 0;
+    for (const byte of snapshot.bytes) {
+        if (byte === 0x0a)
+            recordCount += 1;
+    }
+    const lastEntry = entries.at(-1);
+    const lastEntryId = lastEntry && lastEntry.type !== "session" && typeof lastEntry.id === "string" ? lastEntry.id : null;
+    return Object.freeze({
+        revision: createSessionRevisionToken({
+            sessionId: header.id,
+            completeBytes: snapshot.bytes.byteLength,
+            recordCount,
+            leafId: activeLeafId,
+            lastEntryId,
+            completePrefixSha256: createHash("sha256").update(snapshot.bytes).digest("hex"),
+            fileIdentity: { dev: snapshot.generation.dev, ino: snapshot.generation.ino },
+        }),
+        generation: snapshot.generation,
+    });
+}
+export function sessionDurableHeadFromFile(filePath, activeLeafId, entries) {
+    if (!existsSync(filePath))
+        return null;
+    const header = entries[0];
+    if (!header || header.type !== "session" || typeof header.id !== "string")
+        return null;
+    const metadata = readSessionFileDurableMetadata(filePath);
+    const lastEntry = entries.at(-1);
+    const lastEntryId = lastEntry && lastEntry.type !== "session" && typeof lastEntry.id === "string" ? lastEntry.id : null;
+    return Object.freeze({
+        revision: createSessionRevisionToken({
+            sessionId: header.id,
+            completeBytes: metadata.completeBytes,
+            recordCount: metadata.recordCount,
+            leafId: activeLeafId,
+            lastEntryId,
+            completePrefixSha256: metadata.completePrefixSha256,
+            fileIdentity: { dev: metadata.generation.dev, ino: metadata.generation.ino },
+        }),
+        generation: metadata.generation,
+    });
+}
+export function sameDurableSessionHead(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    return (left.revision.sessionId === right.revision.sessionId &&
+        left.revision.completeBytes === right.revision.completeBytes &&
+        left.revision.recordCount === right.revision.recordCount &&
+        left.revision.lastEntryId === right.revision.lastEntryId &&
+        left.revision.completePrefixSha256 === right.revision.completePrefixSha256 &&
+        sameDurableFileGeneration(left.generation, right.generation));
+}
+//# sourceMappingURL=session-file-persistence.js.map

package/dist/core/session-file-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-file-persistence.js","sourceRoot":"","sources":["../../src/core/session-file-persistence.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { existsSync, statSync } from \"node:fs\";\nimport { atomicRewriteFileSync } from \"./atomic-session-file.ts\";\nimport { createSessionRevisionToken, type SessionRevisionToken } from \"./compaction/transaction.ts\";\nimport {\n\ttype DurableFileSnapshot,\n\treadDurableFileSnapshot,\n\tsameDurableFileGeneration,\n\twriteExclusiveFileDurablySync,\n} from \"./durable-file-io.ts\";\nimport { readSessionFileDurableMetadata, sessionFileHasCompleteTail } from \"./session-file-head.ts\";\n\nexport interface SessionQuarantineReport {\n\treadonly artifact: \"session\";\n\treadonly path: string;\n\treadonly quarantinePath: string;\n\treadonly byteCount: number;\n\treadonly completePrefixByteCount: number;\n}\n\nexport class SessionManagerStaleWriteError extends Error {\n\tconstructor(message = \"Session file changed since this manager accepted its durable head\") {\n\t\tsuper(message);\n\t\tthis.name = \"SessionManagerStaleWriteError\";\n\t}\n}\n\nexport type SessionDurableHead = {\n\treadonly revision: SessionRevisionToken;\n\treadonly generation: DurableFileSnapshot[\"generation\"];\n};\n\ntype FileEntryIdentity = {\n\treadonly type: string;\n\treadonly id?: unknown;\n};\n\ntype SessionQuarantineResult = {\n\treadonly report: SessionQuarantineReport | null;\n\treadonly snapshot: DurableFileSnapshot | null;\n};\n\nexport function quarantineSessionTrailingFragment(filePath: string): SessionQuarantineResult {\n\tif (sessionFileHasCompleteTail(filePath)) return { report: null, snapshot: null };\n\tif (statSync(filePath).nlink > 1)\n\t\tthrow new Error(\"Session quarantine refused for a target with more than one hard link\");\n\tconst snapshot = readDurableFileSnapshot(filePath);\n\tif (!snapshot) return { report: null, snapshot: null };\n\tlet lastNewline = -1;\n\tfor (let index = snapshot.bytes.byteLength - 1; index >= 0; index -= 1) {\n\t\tif (snapshot.bytes[index] === 0x0a) {\n\t\t\tlastNewline = index;\n\t\t\tbreak;\n\t\t}\n\t}\n\tconst completePrefixByteCount = lastNewline + 1;\n\tconst fragment = snapshot.bytes.subarray(completePrefixByteCount);\n\tconst quarantinePath = `${filePath}.quarantine-${randomUUID()}`;\n\twriteExclusiveFileDurablySync(quarantinePath, fragment);\n\tconst current = readDurableFileSnapshot(filePath);\n\tif (\n\t\t!current ||\n\t\t!sameDurableFileGeneration(snapshot.generation, current.generation) ||\n\t\tBuffer.compare(snapshot.bytes, current.bytes) !== 0\n\t) {\n\t\tthrow new SessionManagerStaleWriteError();\n\t}\n\tatomicRewriteFileSync(filePath, snapshot.bytes.subarray(0, completePrefixByteCount));\n\treturn {\n\t\treport: Object.freeze({\n\t\t\tartifact: \"session\",\n\t\t\tpath: filePath,\n\t\t\tquarantinePath,\n\t\t\tbyteCount: fragment.byteLength,\n\t\t\tcompletePrefixByteCount,\n\t\t}),\n\t\tsnapshot: readDurableFileSnapshot(filePath),\n\t};\n}\n\nexport function sessionDurableHeadFromSnapshot(\n\tsnapshot: DurableFileSnapshot,\n\tactiveLeafId: string | null,\n\tentries: readonly FileEntryIdentity[],\n): SessionDurableHead | null {\n\tconst header = entries[0];\n\tif (!header || header.type !== \"session\" || typeof header.id !== \"string\") return null;\n\tlet recordCount = 0;\n\tfor (const byte of snapshot.bytes) {\n\t\tif (byte === 0x0a) recordCount += 1;\n\t}\n\tconst lastEntry = entries.at(-1);\n\tconst lastEntryId =\n\t\tlastEntry && lastEntry.type !== \"session\" && typeof lastEntry.id === \"string\" ? lastEntry.id : null;\n\treturn Object.freeze({\n\t\trevision: createSessionRevisionToken({\n\t\t\tsessionId: header.id,\n\t\t\tcompleteBytes: snapshot.bytes.byteLength,\n\t\t\trecordCount,\n\t\t\tleafId: activeLeafId,\n\t\t\tlastEntryId,\n\t\t\tcompletePrefixSha256: createHash(\"sha256\").update(snapshot.bytes).digest(\"hex\"),\n\t\t\tfileIdentity: { dev: snapshot.generation.dev, ino: snapshot.generation.ino },\n\t\t}),\n\t\tgeneration: snapshot.generation,\n\t});\n}\n\nexport function sessionDurableHeadFromFile(\n\tfilePath: string,\n\tactiveLeafId: string | null,\n\tentries: readonly FileEntryIdentity[],\n): SessionDurableHead | null {\n\tif (!existsSync(filePath)) return null;\n\tconst header = entries[0];\n\tif (!header || header.type !== \"session\" || typeof header.id !== \"string\") return null;\n\tconst metadata = readSessionFileDurableMetadata(filePath);\n\tconst lastEntry = entries.at(-1);\n\tconst lastEntryId =\n\t\tlastEntry && lastEntry.type !== \"session\" && typeof lastEntry.id === \"string\" ? lastEntry.id : null;\n\treturn Object.freeze({\n\t\trevision: createSessionRevisionToken({\n\t\t\tsessionId: header.id,\n\t\t\tcompleteBytes: metadata.completeBytes,\n\t\t\trecordCount: metadata.recordCount,\n\t\t\tleafId: activeLeafId,\n\t\t\tlastEntryId,\n\t\t\tcompletePrefixSha256: metadata.completePrefixSha256,\n\t\t\tfileIdentity: { dev: metadata.generation.dev, ino: metadata.generation.ino },\n\t\t}),\n\t\tgeneration: metadata.generation,\n\t});\n}\n\nexport function sameDurableSessionHead(left: SessionDurableHead | null, right: SessionDurableHead | null): boolean {\n\tif (left === null || right === null) return left === right;\n\treturn (\n\t\tleft.revision.sessionId === right.revision.sessionId &&\n\t\tleft.revision.completeBytes === right.revision.completeBytes &&\n\t\tleft.revision.recordCount === right.revision.recordCount &&\n\t\tleft.revision.lastEntryId === right.revision.lastEntryId &&\n\t\tleft.revision.completePrefixSha256 === right.revision.completePrefixSha256 &&\n\t\tsameDurableFileGeneration(left.generation, right.generation)\n\t);\n}\n"]}

package/dist/core/session-integrity.d.ts

@@ -0,0 +1,43 @@
+import { type AgentMessage, type TranscriptIntegrityReport } from "omk-agent-core";
+import { type SessionEntry, type SessionHeader } from "./session-manager.ts";
+export type SessionIntegrityReasonCode = "trailing_fragment" | "invalid_utf8" | "malformed_json" | "missing_header" | "invalid_header" | "unsupported_header" | "multiple_header" | "late_header" | "invalid_entry" | "unsupported_entry" | "duplicate_entry_id" | "missing_parent" | "self_cycle" | "parent_cycle" | "active_leaf_missing" | "compaction_first_kept_not_ancestor" | "active_branch_context_invalid" | "transcript_missing_result" | "transcript_duplicate_result" | "transcript_orphan_result" | "transcript_duplicate_call_id" | "transcript_interleaved_non_result";
+export interface SessionIntegrityFinding {
+    readonly reason: SessionIntegrityReasonCode;
+    readonly line?: number;
+    readonly entryId?: string;
+    readonly parentId?: string;
+    readonly cycleEntryIds?: readonly string[];
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+}
+export interface SessionByteDigest {
+    readonly byteCount: number;
+    readonly sha256: string;
+}
+export interface SessionCompletePrefix extends SessionByteDigest {
+    readonly lineCount: number;
+}
+export interface SessionIntegrityReport {
+    readonly ok: boolean;
+    readonly source: SessionByteDigest;
+    readonly completePrefix: SessionCompletePrefix;
+    readonly trailingFragment: SessionByteDigest | null;
+    readonly header: Readonly<SessionHeader> | null;
+    /** Valid session entries in their original complete-line order. */
+    readonly entries: readonly Readonly<SessionEntry>[];
+    readonly activeLeafId: string | null;
+    readonly activeBranch: readonly Readonly<SessionEntry>[];
+    readonly activeMessages: readonly AgentMessage[];
+    readonly transcript: Readonly<TranscriptIntegrityReport> | null;
+    readonly findings: readonly SessionIntegrityFinding[];
+}
+export interface InspectSessionIntegrityOptions {
+    /** `undefined` selects the last complete entry; `null` selects the empty branch. */
+    readonly activeLeafId?: string | null;
+}
+/**
+ * Inspect the exact complete-line prefix of a session JSONL byte sequence.
+ * Newline-free final bytes are reported as a fragment and are never parsed.
+ */
+export declare function inspectSessionIntegrity(bytes: Uint8Array, options?: InspectSessionIntegrityOptions): SessionIntegrityReport;
+//# sourceMappingURL=session-integrity.d.ts.map

package/dist/core/session-integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-integrity.d.ts","sourceRoot":"","sources":["../../src/core/session-integrity.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,YAAY,EAGjB,KAAK,yBAAyB,EAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAGN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,0BAA0B,GACnC,mBAAmB,GACnB,cAAc,GACd,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,iBAAiB,GACjB,aAAa,GACb,eAAe,GACf,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,qBAAqB,GACrB,oCAAoC,GACpC,+BAA+B,GAC/B,2BAA2B,GAC3B,6BAA6B,GAC7B,0BAA0B,GAC1B,8BAA8B,GAC9B,mCAAmC,CAAC;AAEvC,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IAChD,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;IACzD,QAAQ,CAAC,cAAc,EAAE,SAAS,YAAY,EAAE,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GAAG,IAAI,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,8BAA8B;IAC9C,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAmSD;;;GAGG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,8BAAmC,GAC1C,sBAAsB,CA8LxB","sourcesContent":["import { createHash } from \"node:crypto\";\nimport {\n\ttype AgentMessage,\n\tinspectTranscriptIntegrity,\n\ttype TranscriptIntegrityIssueKind,\n\ttype TranscriptIntegrityReport,\n} from \"omk-agent-core\";\nimport {\n\tbuildSessionContext,\n\tCURRENT_SESSION_VERSION,\n\ttype SessionEntry,\n\ttype SessionHeader,\n} from \"./session-manager.ts\";\n\nexport type SessionIntegrityReasonCode =\n\t| \"trailing_fragment\"\n\t| \"invalid_utf8\"\n\t| \"malformed_json\"\n\t| \"missing_header\"\n\t| \"invalid_header\"\n\t| \"unsupported_header\"\n\t| \"multiple_header\"\n\t| \"late_header\"\n\t| \"invalid_entry\"\n\t| \"unsupported_entry\"\n\t| \"duplicate_entry_id\"\n\t| \"missing_parent\"\n\t| \"self_cycle\"\n\t| \"parent_cycle\"\n\t| \"active_leaf_missing\"\n\t| \"compaction_first_kept_not_ancestor\"\n\t| \"active_branch_context_invalid\"\n\t| \"transcript_missing_result\"\n\t| \"transcript_duplicate_result\"\n\t| \"transcript_orphan_result\"\n\t| \"transcript_duplicate_call_id\"\n\t| \"transcript_interleaved_non_result\";\n\nexport interface SessionIntegrityFinding {\n\treadonly reason: SessionIntegrityReasonCode;\n\treadonly line?: number;\n\treadonly entryId?: string;\n\treadonly parentId?: string;\n\treadonly cycleEntryIds?: readonly string[];\n\treadonly toolCallId?: string;\n\treadonly toolName?: string;\n}\n\nexport interface SessionByteDigest {\n\treadonly byteCount: number;\n\treadonly sha256: string;\n}\n\nexport interface SessionCompletePrefix extends SessionByteDigest {\n\treadonly lineCount: number;\n}\n\nexport interface SessionIntegrityReport {\n\treadonly ok: boolean;\n\treadonly source: SessionByteDigest;\n\treadonly completePrefix: SessionCompletePrefix;\n\treadonly trailingFragment: SessionByteDigest | null;\n\treadonly header: Readonly<SessionHeader> | null;\n\t/** Valid session entries in their original complete-line order. */\n\treadonly entries: readonly Readonly<SessionEntry>[];\n\treadonly activeLeafId: string | null;\n\treadonly activeBranch: readonly Readonly<SessionEntry>[];\n\treadonly activeMessages: readonly AgentMessage[];\n\treadonly transcript: Readonly<TranscriptIntegrityReport> | null;\n\treadonly findings: readonly SessionIntegrityFinding[];\n}\n\nexport interface InspectSessionIntegrityOptions {\n\t/** `undefined` selects the last complete entry; `null` selects the empty branch. */\n\treadonly activeLeafId?: string | null;\n}\n\ninterface ParsedRecord {\n\treadonly line: number;\n\treadonly value: unknown;\n}\n\ninterface ParsedEntry {\n\treadonly line: number;\n\treadonly entry: SessionEntry;\n}\n\nconst SUPPORTED_ENTRY_TYPES = new Set([\n\t\"message\",\n\t\"thinking_level_change\",\n\t\"model_change\",\n\t\"compaction\",\n\t\"branch_summary\",\n\t\"custom\",\n\t\"custom_message\",\n\t\"label\",\n\t\"session_info\",\n]);\n\nfunction sha256(bytes: Uint8Array): string {\n\treturn createHash(\"sha256\").update(bytes).digest(\"hex\");\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction nonEmptyString(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0;\n}\n\nfunction finiteNonNegativeNumber(value: unknown): value is number {\n\treturn typeof value === \"number\" && Number.isFinite(value) && value >= 0;\n}\n\nfunction validEntryTimestamp(value: unknown): value is string {\n\tif (!nonEmptyString(value)) return false;\n\tconst timestamp = new Date(value).getTime();\n\treturn Number.isFinite(timestamp) && timestamp >= 0;\n}\n\nfunction deepFreeze<T>(value: T): T {\n\tif (typeof value !== \"object\" || value === null || Object.isFrozen(value)) return value;\n\tfor (const child of Object.values(value)) deepFreeze(child);\n\treturn Object.freeze(value);\n}\n\nfunction addFinding(findings: SessionIntegrityFinding[], finding: SessionIntegrityFinding): void {\n\tfindings.push(Object.freeze(finding));\n}\n\nfunction validHeader(value: Record<string, unknown>, line: number, findings: SessionIntegrityFinding[]): boolean {\n\tif (value.version !== CURRENT_SESSION_VERSION) {\n\t\taddFinding(findings, { reason: \"unsupported_header\", line });\n\t\treturn false;\n\t}\n\tif (\n\t\t!nonEmptyString(value.id) ||\n\t\t!nonEmptyString(value.timestamp) ||\n\t\t!nonEmptyString(value.cwd) ||\n\t\t(value.parentSession !== undefined && typeof value.parentSession !== \"string\")\n\t) {\n\t\taddFinding(findings, { reason: \"invalid_header\", line });\n\t\treturn false;\n\t}\n\treturn true;\n}\n\nfunction validTextContent(value: unknown): boolean {\n\treturn (\n\t\tisRecord(value) &&\n\t\tvalue.type === \"text\" &&\n\t\ttypeof value.text === \"string\" &&\n\t\t(value.textSignature === undefined || typeof value.textSignature === \"string\")\n\t);\n}\n\nfunction validImageContent(value: unknown): boolean {\n\treturn (\n\t\tisRecord(value) && value.type === \"image\" && typeof value.data === \"string\" && typeof value.mimeType === \"string\"\n\t);\n}\n\nfunction validThinkingContent(value: unknown): boolean {\n\treturn (\n\t\tisRecord(value) &&\n\t\tvalue.type === \"thinking\" &&\n\t\ttypeof value.thinking === \"string\" &&\n\t\t(value.thinkingSignature === undefined || typeof value.thinkingSignature === \"string\") &&\n\t\t(value.redacted === undefined || typeof value.redacted === \"boolean\")\n\t);\n}\n\nfunction validToolCall(value: unknown): boolean {\n\treturn (\n\t\tisRecord(value) &&\n\t\tvalue.type === \"toolCall\" &&\n\t\tnonEmptyString(value.id) &&\n\t\tnonEmptyString(value.name) &&\n\t\tisRecord(value.arguments) &&\n\t\t(value.thoughtSignature === undefined || typeof value.thoughtSignature === \"string\")\n\t);\n}\n\nfunction validUserContent(value: unknown): boolean {\n\treturn (\n\t\ttypeof value === \"string\" ||\n\t\t(Array.isArray(value) && value.every((block) => validTextContent(block) || validImageContent(block)))\n\t);\n}\n\nfunction validUsage(value: unknown): boolean {\n\tif (!isRecord(value) || !isRecord(value.cost)) return false;\n\tconst cost = value.cost;\n\treturn (\n\t\t[\"input\", \"output\", \"cacheRead\", \"cacheWrite\", \"totalTokens\"].every((key) =>\n\t\t\tfiniteNonNegativeNumber(value[key]),\n\t\t) && [\"input\", \"output\", \"cacheRead\", \"cacheWrite\", \"total\"].every((key) => finiteNonNegativeNumber(cost[key]))\n\t);\n}\n\nfunction validDiagnostic(value: unknown): boolean {\n\tif (!isRecord(value) || typeof value.type !== \"string\" || !finiteNonNegativeNumber(value.timestamp)) return false;\n\tif (value.details !== undefined && !isRecord(value.details)) return false;\n\tif (value.error === undefined) return true;\n\tif (!isRecord(value.error) || typeof value.error.message !== \"string\") return false;\n\treturn (\n\t\t(value.error.name === undefined || typeof value.error.name === \"string\") &&\n\t\t(value.error.stack === undefined || typeof value.error.stack === \"string\") &&\n\t\t(value.error.code === undefined || typeof value.error.code === \"string\" || typeof value.error.code === \"number\")\n\t);\n}\n\nfunction validAgentMessage(value: unknown): value is AgentMessage {\n\tif (!isRecord(value) || !finiteNonNegativeNumber(value.timestamp)) return false;\n\tswitch (value.role) {\n\t\tcase \"user\":\n\t\t\treturn validUserContent(value.content);\n\t\tcase \"assistant\":\n\t\t\treturn (\n\t\t\t\tArray.isArray(value.content) &&\n\t\t\t\tvalue.content.every(\n\t\t\t\t\t(block) => validTextContent(block) || validThinkingContent(block) || validToolCall(block),\n\t\t\t\t) &&\n\t\t\t\tnonEmptyString(value.api) &&\n\t\t\t\tnonEmptyString(value.provider) &&\n\t\t\t\tnonEmptyString(value.model) &&\n\t\t\t\t(value.responseModel === undefined || typeof value.responseModel === \"string\") &&\n\t\t\t\t(value.responseId === undefined || typeof value.responseId === \"string\") &&\n\t\t\t\t(value.diagnostics === undefined ||\n\t\t\t\t\t(Array.isArray(value.diagnostics) && value.diagnostics.every(validDiagnostic))) &&\n\t\t\t\tvalidUsage(value.usage) &&\n\t\t\t\t(value.stopReason === \"stop\" ||\n\t\t\t\t\tvalue.stopReason === \"length\" ||\n\t\t\t\t\tvalue.stopReason === \"toolUse\" ||\n\t\t\t\t\tvalue.stopReason === \"error\" ||\n\t\t\t\t\tvalue.stopReason === \"aborted\") &&\n\t\t\t\t(value.errorMessage === undefined || typeof value.errorMessage === \"string\")\n\t\t\t);\n\t\tcase \"toolResult\":\n\t\t\treturn (\n\t\t\t\tnonEmptyString(value.toolCallId) &&\n\t\t\t\tnonEmptyString(value.toolName) &&\n\t\t\t\tArray.isArray(value.content) &&\n\t\t\t\tvalue.content.every((block) => validTextContent(block) || validImageContent(block)) &&\n\t\t\t\ttypeof value.isError === \"boolean\"\n\t\t\t);\n\t\tcase \"bashExecution\":\n\t\t\treturn (\n\t\t\t\ttypeof value.command === \"string\" &&\n\t\t\t\ttypeof value.output === \"string\" &&\n\t\t\t\t(value.exitCode === undefined || finiteNonNegativeNumber(value.exitCode)) &&\n\t\t\t\ttypeof value.cancelled === \"boolean\" &&\n\t\t\t\ttypeof value.truncated === \"boolean\" &&\n\t\t\t\t(value.fullOutputPath === undefined || typeof value.fullOutputPath === \"string\") &&\n\t\t\t\t(value.excludeFromContext === undefined || typeof value.excludeFromContext === \"boolean\")\n\t\t\t);\n\t\tcase \"custom\":\n\t\t\treturn (\n\t\t\t\tnonEmptyString(value.customType) && validUserContent(value.content) && typeof value.display === \"boolean\"\n\t\t\t);\n\t\tcase \"branchSummary\":\n\t\t\treturn typeof value.summary === \"string\" && nonEmptyString(value.fromId);\n\t\tcase \"compactionSummary\":\n\t\t\treturn typeof value.summary === \"string\" && finiteNonNegativeNumber(value.tokensBefore);\n\t\tdefault:\n\t\t\treturn false;\n\t}\n}\n\nfunction validEntryShape(value: Record<string, unknown>): value is Record<string, unknown> & SessionEntry {\n\tif (\n\t\t!nonEmptyString(value.type) ||\n\t\t!SUPPORTED_ENTRY_TYPES.has(value.type) ||\n\t\t!nonEmptyString(value.id) ||\n\t\t(value.parentId !== null && !nonEmptyString(value.parentId)) ||\n\t\t!validEntryTimestamp(value.timestamp)\n\t) {\n\t\treturn false;\n\t}\n\n\tswitch (value.type) {\n\t\tcase \"message\":\n\t\t\treturn validAgentMessage(value.message);\n\t\tcase \"thinking_level_change\":\n\t\t\treturn typeof value.thinkingLevel === \"string\";\n\t\tcase \"model_change\":\n\t\t\treturn nonEmptyString(value.provider) && nonEmptyString(value.modelId);\n\t\tcase \"compaction\":\n\t\t\treturn (\n\t\t\t\ttypeof value.summary === \"string\" &&\n\t\t\t\tnonEmptyString(value.firstKeptEntryId) &&\n\t\t\t\tfiniteNonNegativeNumber(value.tokensBefore)\n\t\t\t);\n\t\tcase \"branch_summary\":\n\t\t\treturn nonEmptyString(value.fromId) && typeof value.summary === \"string\";\n\t\tcase \"custom\":\n\t\t\treturn nonEmptyString(value.customType);\n\t\tcase \"custom_message\":\n\t\t\treturn (\n\t\t\t\tnonEmptyString(value.customType) && validUserContent(value.content) && typeof value.display === \"boolean\"\n\t\t\t);\n\t\tcase \"label\":\n\t\t\treturn nonEmptyString(value.targetId) && (value.label === undefined || typeof value.label === \"string\");\n\t\tcase \"session_info\":\n\t\t\treturn value.name === undefined || typeof value.name === \"string\";\n\t\tdefault:\n\t\t\treturn false;\n\t}\n}\n\nfunction transcriptFindingReason(kind: TranscriptIntegrityIssueKind): SessionIntegrityReasonCode {\n\tswitch (kind) {\n\t\tcase \"missing_result\":\n\t\t\treturn \"transcript_missing_result\";\n\t\tcase \"duplicate_result\":\n\t\t\treturn \"transcript_duplicate_result\";\n\t\tcase \"orphan_result\":\n\t\t\treturn \"transcript_orphan_result\";\n\t\tcase \"duplicate_call_id\":\n\t\t\treturn \"transcript_duplicate_call_id\";\n\t\tcase \"interleaved_non_result\":\n\t\t\treturn \"transcript_interleaved_non_result\";\n\t}\n}\n\nfunction findCycles(\n\tentries: readonly ParsedEntry[],\n\tbyId: ReadonlyMap<string, SessionEntry>,\n): SessionIntegrityFinding[] {\n\tconst findings: SessionIntegrityFinding[] = [];\n\tconst finished = new Set<string>();\n\n\tfor (const { entry } of entries) {\n\t\tif (finished.has(entry.id)) continue;\n\t\tconst path: string[] = [];\n\t\tconst pathIndex = new Map<string, number>();\n\t\tlet current: SessionEntry | undefined = byId.get(entry.id);\n\n\t\twhile (current && !finished.has(current.id)) {\n\t\t\tconst seenAt = pathIndex.get(current.id);\n\t\t\tif (seenAt !== undefined) {\n\t\t\t\tconst cycleEntryIds = path.slice(seenAt);\n\t\t\t\taddFinding(findings, {\n\t\t\t\t\treason: cycleEntryIds.length === 1 ? \"self_cycle\" : \"parent_cycle\",\n\t\t\t\t\tentryId: cycleEntryIds[0],\n\t\t\t\t\tcycleEntryIds: Object.freeze(cycleEntryIds),\n\t\t\t\t});\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tpathIndex.set(current.id, path.length);\n\t\t\tpath.push(current.id);\n\t\t\tcurrent = current.parentId === null ? undefined : byId.get(current.parentId);\n\t\t}\n\t\tfor (const id of path) finished.add(id);\n\t}\n\treturn findings;\n}\n\nfunction freezeTranscript(report: TranscriptIntegrityReport): Readonly<TranscriptIntegrityReport> {\n\treturn Object.freeze({\n\t\tok: report.ok,\n\t\tissues: Object.freeze(report.issues.map((issue) => Object.freeze({ ...issue }))),\n\t});\n}\n\n/**\n * Inspect the exact complete-line prefix of a session JSONL byte sequence.\n * Newline-free final bytes are reported as a fragment and are never parsed.\n */\nexport function inspectSessionIntegrity(\n\tbytes: Uint8Array,\n\toptions: InspectSessionIntegrityOptions = {},\n): SessionIntegrityReport {\n\tconst findings: SessionIntegrityFinding[] = [];\n\tlet lastNewline = -1;\n\tfor (let index = bytes.byteLength - 1; index >= 0; index--) {\n\t\tif (bytes[index] === 0x0a) {\n\t\t\tlastNewline = index;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tconst completeByteCount = lastNewline + 1;\n\tconst completeBytes = bytes.subarray(0, completeByteCount);\n\tconst fragmentBytes = bytes.subarray(completeByteCount);\n\tconst source = Object.freeze({ byteCount: bytes.byteLength, sha256: sha256(bytes) });\n\tconst trailingFragment =\n\t\tfragmentBytes.byteLength === 0\n\t\t\t? null\n\t\t\t: Object.freeze({ byteCount: fragmentBytes.byteLength, sha256: sha256(fragmentBytes) });\n\tif (trailingFragment) addFinding(findings, { reason: \"trailing_fragment\" });\n\n\tconst records: ParsedRecord[] = [];\n\tlet lineCount = 0;\n\tif (completeBytes.byteLength > 0) {\n\t\tlet text: string | undefined;\n\t\ttry {\n\t\t\ttext = new TextDecoder(\"utf-8\", { fatal: true }).decode(completeBytes);\n\t\t} catch {\n\t\t\taddFinding(findings, { reason: \"invalid_utf8\" });\n\t\t}\n\t\tif (text !== undefined) {\n\t\t\tconst lines = text.slice(0, -1).split(\"\\n\");\n\t\t\tlineCount = lines.length;\n\t\t\tfor (let index = 0; index < lines.length; index++) {\n\t\t\t\tconst lineNumber = index + 1;\n\t\t\t\tconst line = lines[index];\n\t\t\t\tif (line.trim().length === 0) {\n\t\t\t\t\taddFinding(findings, { reason: \"malformed_json\", line: lineNumber });\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\trecords.push({ line: lineNumber, value: JSON.parse(line) });\n\t\t\t\t} catch {\n\t\t\t\t\taddFinding(findings, { reason: \"malformed_json\", line: lineNumber });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tconst headerRecords = records.filter(\n\t\t(record): record is ParsedRecord & { value: Record<string, unknown> } =>\n\t\t\tisRecord(record.value) && record.value.type === \"session\",\n\t);\n\tconst firstRecord = records.find((record) => record.line === 1);\n\tlet header: SessionHeader | null = null;\n\tif (!firstRecord || !isRecord(firstRecord.value) || firstRecord.value.type !== \"session\") {\n\t\taddFinding(findings, { reason: \"missing_header\", line: 1 });\n\t} else if (validHeader(firstRecord.value, 1, findings)) {\n\t\theader = firstRecord.value as unknown as SessionHeader;\n\t}\n\tif (headerRecords.length > 1) {\n\t\taddFinding(findings, { reason: \"multiple_header\", line: headerRecords[1].line });\n\t}\n\tfor (const record of headerRecords) {\n\t\tif (record.line !== 1) {\n\t\t\taddFinding(findings, { reason: \"late_header\", line: record.line });\n\t\t\tif (record.value.version !== CURRENT_SESSION_VERSION) {\n\t\t\t\taddFinding(findings, { reason: \"unsupported_header\", line: record.line });\n\t\t\t}\n\t\t}\n\t}\n\n\tconst parsedEntries: ParsedEntry[] = [];\n\tfor (const record of records) {\n\t\tif (isRecord(record.value) && record.value.type === \"session\") continue;\n\t\tif (!isRecord(record.value)) {\n\t\t\taddFinding(findings, { reason: \"invalid_entry\", line: record.line });\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof record.value.type === \"string\" && !SUPPORTED_ENTRY_TYPES.has(record.value.type)) {\n\t\t\taddFinding(findings, { reason: \"unsupported_entry\", line: record.line });\n\t\t\tcontinue;\n\t\t}\n\t\tif (!validEntryShape(record.value)) {\n\t\t\taddFinding(findings, {\n\t\t\t\treason: \"invalid_entry\",\n\t\t\t\tline: record.line,\n\t\t\t\t...(typeof record.value.id === \"string\" ? { entryId: record.value.id } : {}),\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tparsedEntries.push({ line: record.line, entry: record.value });\n\t}\n\n\tconst byId = new Map<string, SessionEntry>();\n\tfor (const parsed of parsedEntries) {\n\t\tif (byId.has(parsed.entry.id)) {\n\t\t\taddFinding(findings, {\n\t\t\t\treason: \"duplicate_entry_id\",\n\t\t\t\tline: parsed.line,\n\t\t\t\tentryId: parsed.entry.id,\n\t\t\t});\n\t\t} else {\n\t\t\tbyId.set(parsed.entry.id, parsed.entry);\n\t\t}\n\t}\n\tfor (const parsed of parsedEntries) {\n\t\tconst { entry } = parsed;\n\t\tif (entry.parentId !== null && !byId.has(entry.parentId)) {\n\t\t\taddFinding(findings, {\n\t\t\t\treason: \"missing_parent\",\n\t\t\t\tline: parsed.line,\n\t\t\t\tentryId: entry.id,\n\t\t\t\tparentId: entry.parentId,\n\t\t\t});\n\t\t}\n\t}\n\tfor (const cycle of findCycles(parsedEntries, byId)) findings.push(cycle);\n\n\tconst selectedLeaf =\n\t\toptions.activeLeafId === undefined ? (parsedEntries.at(-1)?.entry.id ?? null) : options.activeLeafId;\n\tlet activeBranch: SessionEntry[] = [];\n\tlet activeMessages: AgentMessage[] = [];\n\tlet transcript: Readonly<TranscriptIntegrityReport> | null = null;\n\tconst hasStructuralBlocker = findings.some((finding) => finding.reason !== \"trailing_fragment\");\n\n\tif (selectedLeaf !== null && !byId.has(selectedLeaf)) {\n\t\taddFinding(findings, { reason: \"active_leaf_missing\", entryId: selectedLeaf });\n\t} else if (!hasStructuralBlocker) {\n\t\tif (selectedLeaf !== null) {\n\t\t\tlet current = byId.get(selectedLeaf);\n\t\t\twhile (current) {\n\t\t\t\tactiveBranch.unshift(current);\n\t\t\t\tcurrent = current.parentId === null ? undefined : byId.get(current.parentId);\n\t\t\t}\n\t\t}\n\t\tconst ancestorIds = new Set<string>();\n\t\tfor (const entry of activeBranch) {\n\t\t\tif (entry.type === \"compaction\" && !ancestorIds.has(entry.firstKeptEntryId)) {\n\t\t\t\taddFinding(findings, {\n\t\t\t\t\treason: \"compaction_first_kept_not_ancestor\",\n\t\t\t\t\tentryId: entry.id,\n\t\t\t\t});\n\t\t\t}\n\t\t\tancestorIds.add(entry.id);\n\t\t}\n\t\tif (!findings.some((finding) => finding.reason === \"compaction_first_kept_not_ancestor\")) {\n\t\t\ttry {\n\t\t\t\tactiveMessages = buildSessionContext(\n\t\t\t\t\tparsedEntries.map((parsed) => parsed.entry),\n\t\t\t\t\tselectedLeaf,\n\t\t\t\t\tbyId,\n\t\t\t\t).messages;\n\t\t\t\tconst inspected = inspectTranscriptIntegrity(activeMessages);\n\t\t\t\ttranscript = freezeTranscript(inspected);\n\t\t\t\tfor (const issue of inspected.issues) {\n\t\t\t\t\taddFinding(findings, {\n\t\t\t\t\t\treason: transcriptFindingReason(issue.kind),\n\t\t\t\t\t\ttoolCallId: issue.toolCallId,\n\t\t\t\t\t\t...(issue.toolName === undefined ? {} : { toolName: issue.toolName }),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\taddFinding(findings, { reason: \"active_branch_context_invalid\", entryId: selectedLeaf ?? undefined });\n\t\t\t\tactiveBranch = [];\n\t\t\t\tactiveMessages = [];\n\t\t\t\ttranscript = null;\n\t\t\t}\n\t\t}\n\t}\n\n\tconst frozenEntries = Object.freeze(parsedEntries.map((parsed) => deepFreeze(parsed.entry)));\n\tconst frozenBranch = Object.freeze(activeBranch.map((entry) => deepFreeze(entry)));\n\tconst frozenMessages = Object.freeze(activeMessages.map((message) => deepFreeze(message)));\n\treturn Object.freeze({\n\t\tok: findings.length === 0,\n\t\tsource,\n\t\tcompletePrefix: Object.freeze({\n\t\t\tbyteCount: completeByteCount,\n\t\t\tsha256: sha256(completeBytes),\n\t\t\tlineCount,\n\t\t}),\n\t\ttrailingFragment,\n\t\theader: header === null ? null : deepFreeze(header),\n\t\tentries: frozenEntries,\n\t\tactiveLeafId: selectedLeaf,\n\t\tactiveBranch: frozenBranch,\n\t\tactiveMessages: frozenMessages,\n\t\ttranscript,\n\t\tfindings: Object.freeze(findings),\n\t});\n}\n"]}

package/dist/core/session-integrity.js

@@ -0,0 +1,420 @@
+import { createHash } from "node:crypto";
+import { inspectTranscriptIntegrity, } from "omk-agent-core";
+import { buildSessionContext, CURRENT_SESSION_VERSION, } from "./session-manager.js";
+const SUPPORTED_ENTRY_TYPES = new Set([
+    "message",
+    "thinking_level_change",
+    "model_change",
+    "compaction",
+    "branch_summary",
+    "custom",
+    "custom_message",
+    "label",
+    "session_info",
+]);
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function finiteNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function validEntryTimestamp(value) {
+    if (!nonEmptyString(value))
+        return false;
+    const timestamp = new Date(value).getTime();
+    return Number.isFinite(timestamp) && timestamp >= 0;
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+}
+function addFinding(findings, finding) {
+    findings.push(Object.freeze(finding));
+}
+function validHeader(value, line, findings) {
+    if (value.version !== CURRENT_SESSION_VERSION) {
+        addFinding(findings, { reason: "unsupported_header", line });
+        return false;
+    }
+    if (!nonEmptyString(value.id) ||
+        !nonEmptyString(value.timestamp) ||
+        !nonEmptyString(value.cwd) ||
+        (value.parentSession !== undefined && typeof value.parentSession !== "string")) {
+        addFinding(findings, { reason: "invalid_header", line });
+        return false;
+    }
+    return true;
+}
+function validTextContent(value) {
+    return (isRecord(value) &&
+        value.type === "text" &&
+        typeof value.text === "string" &&
+        (value.textSignature === undefined || typeof value.textSignature === "string"));
+}
+function validImageContent(value) {
+    return (isRecord(value) && value.type === "image" && typeof value.data === "string" && typeof value.mimeType === "string");
+}
+function validThinkingContent(value) {
+    return (isRecord(value) &&
+        value.type === "thinking" &&
+        typeof value.thinking === "string" &&
+        (value.thinkingSignature === undefined || typeof value.thinkingSignature === "string") &&
+        (value.redacted === undefined || typeof value.redacted === "boolean"));
+}
+function validToolCall(value) {
+    return (isRecord(value) &&
+        value.type === "toolCall" &&
+        nonEmptyString(value.id) &&
+        nonEmptyString(value.name) &&
+        isRecord(value.arguments) &&
+        (value.thoughtSignature === undefined || typeof value.thoughtSignature === "string"));
+}
+function validUserContent(value) {
+    return (typeof value === "string" ||
+        (Array.isArray(value) && value.every((block) => validTextContent(block) || validImageContent(block))));
+}
+function validUsage(value) {
+    if (!isRecord(value) || !isRecord(value.cost))
+        return false;
+    const cost = value.cost;
+    return (["input", "output", "cacheRead", "cacheWrite", "totalTokens"].every((key) => finiteNonNegativeNumber(value[key])) && ["input", "output", "cacheRead", "cacheWrite", "total"].every((key) => finiteNonNegativeNumber(cost[key])));
+}
+function validDiagnostic(value) {
+    if (!isRecord(value) || typeof value.type !== "string" || !finiteNonNegativeNumber(value.timestamp))
+        return false;
+    if (value.details !== undefined && !isRecord(value.details))
+        return false;
+    if (value.error === undefined)
+        return true;
+    if (!isRecord(value.error) || typeof value.error.message !== "string")
+        return false;
+    return ((value.error.name === undefined || typeof value.error.name === "string") &&
+        (value.error.stack === undefined || typeof value.error.stack === "string") &&
+        (value.error.code === undefined || typeof value.error.code === "string" || typeof value.error.code === "number"));
+}
+function validAgentMessage(value) {
+    if (!isRecord(value) || !finiteNonNegativeNumber(value.timestamp))
+        return false;
+    switch (value.role) {
+        case "user":
+            return validUserContent(value.content);
+        case "assistant":
+            return (Array.isArray(value.content) &&
+                value.content.every((block) => validTextContent(block) || validThinkingContent(block) || validToolCall(block)) &&
+                nonEmptyString(value.api) &&
+                nonEmptyString(value.provider) &&
+                nonEmptyString(value.model) &&
+                (value.responseModel === undefined || typeof value.responseModel === "string") &&
+                (value.responseId === undefined || typeof value.responseId === "string") &&
+                (value.diagnostics === undefined ||
+                    (Array.isArray(value.diagnostics) && value.diagnostics.every(validDiagnostic))) &&
+                validUsage(value.usage) &&
+                (value.stopReason === "stop" ||
+                    value.stopReason === "length" ||
+                    value.stopReason === "toolUse" ||
+                    value.stopReason === "error" ||
+                    value.stopReason === "aborted") &&
+                (value.errorMessage === undefined || typeof value.errorMessage === "string"));
+        case "toolResult":
+            return (nonEmptyString(value.toolCallId) &&
+                nonEmptyString(value.toolName) &&
+                Array.isArray(value.content) &&
+                value.content.every((block) => validTextContent(block) || validImageContent(block)) &&
+                typeof value.isError === "boolean");
+        case "bashExecution":
+            return (typeof value.command === "string" &&
+                typeof value.output === "string" &&
+                (value.exitCode === undefined || finiteNonNegativeNumber(value.exitCode)) &&
+                typeof value.cancelled === "boolean" &&
+                typeof value.truncated === "boolean" &&
+                (value.fullOutputPath === undefined || typeof value.fullOutputPath === "string") &&
+                (value.excludeFromContext === undefined || typeof value.excludeFromContext === "boolean"));
+        case "custom":
+            return (nonEmptyString(value.customType) && validUserContent(value.content) && typeof value.display === "boolean");
+        case "branchSummary":
+            return typeof value.summary === "string" && nonEmptyString(value.fromId);
+        case "compactionSummary":
+            return typeof value.summary === "string" && finiteNonNegativeNumber(value.tokensBefore);
+        default:
+            return false;
+    }
+}
+function validEntryShape(value) {
+    if (!nonEmptyString(value.type) ||
+        !SUPPORTED_ENTRY_TYPES.has(value.type) ||
+        !nonEmptyString(value.id) ||
+        (value.parentId !== null && !nonEmptyString(value.parentId)) ||
+        !validEntryTimestamp(value.timestamp)) {
+        return false;
+    }
+    switch (value.type) {
+        case "message":
+            return validAgentMessage(value.message);
+        case "thinking_level_change":
+            return typeof value.thinkingLevel === "string";
+        case "model_change":
+            return nonEmptyString(value.provider) && nonEmptyString(value.modelId);
+        case "compaction":
+            return (typeof value.summary === "string" &&
+                nonEmptyString(value.firstKeptEntryId) &&
+                finiteNonNegativeNumber(value.tokensBefore));
+        case "branch_summary":
+            return nonEmptyString(value.fromId) && typeof value.summary === "string";
+        case "custom":
+            return nonEmptyString(value.customType);
+        case "custom_message":
+            return (nonEmptyString(value.customType) && validUserContent(value.content) && typeof value.display === "boolean");
+        case "label":
+            return nonEmptyString(value.targetId) && (value.label === undefined || typeof value.label === "string");
+        case "session_info":
+            return value.name === undefined || typeof value.name === "string";
+        default:
+            return false;
+    }
+}
+function transcriptFindingReason(kind) {
+    switch (kind) {
+        case "missing_result":
+            return "transcript_missing_result";
+        case "duplicate_result":
+            return "transcript_duplicate_result";
+        case "orphan_result":
+            return "transcript_orphan_result";
+        case "duplicate_call_id":
+            return "transcript_duplicate_call_id";
+        case "interleaved_non_result":
+            return "transcript_interleaved_non_result";
+    }
+}
+function findCycles(entries, byId) {
+    const findings = [];
+    const finished = new Set();
+    for (const { entry } of entries) {
+        if (finished.has(entry.id))
+            continue;
+        const path = [];
+        const pathIndex = new Map();
+        let current = byId.get(entry.id);
+        while (current && !finished.has(current.id)) {
+            const seenAt = pathIndex.get(current.id);
+            if (seenAt !== undefined) {
+                const cycleEntryIds = path.slice(seenAt);
+                addFinding(findings, {
+                    reason: cycleEntryIds.length === 1 ? "self_cycle" : "parent_cycle",
+                    entryId: cycleEntryIds[0],
+                    cycleEntryIds: Object.freeze(cycleEntryIds),
+                });
+                break;
+            }
+            pathIndex.set(current.id, path.length);
+            path.push(current.id);
+            current = current.parentId === null ? undefined : byId.get(current.parentId);
+        }
+        for (const id of path)
+            finished.add(id);
+    }
+    return findings;
+}
+function freezeTranscript(report) {
+    return Object.freeze({
+        ok: report.ok,
+        issues: Object.freeze(report.issues.map((issue) => Object.freeze({ ...issue }))),
+    });
+}
+/**
+ * Inspect the exact complete-line prefix of a session JSONL byte sequence.
+ * Newline-free final bytes are reported as a fragment and are never parsed.
+ */
+export function inspectSessionIntegrity(bytes, options = {}) {
+    const findings = [];
+    let lastNewline = -1;
+    for (let index = bytes.byteLength - 1; index >= 0; index--) {
+        if (bytes[index] === 0x0a) {
+            lastNewline = index;
+            break;
+        }
+    }
+    const completeByteCount = lastNewline + 1;
+    const completeBytes = bytes.subarray(0, completeByteCount);
+    const fragmentBytes = bytes.subarray(completeByteCount);
+    const source = Object.freeze({ byteCount: bytes.byteLength, sha256: sha256(bytes) });
+    const trailingFragment = fragmentBytes.byteLength === 0
+        ? null
+        : Object.freeze({ byteCount: fragmentBytes.byteLength, sha256: sha256(fragmentBytes) });
+    if (trailingFragment)
+        addFinding(findings, { reason: "trailing_fragment" });
+    const records = [];
+    let lineCount = 0;
+    if (completeBytes.byteLength > 0) {
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(completeBytes);
+        }
+        catch {
+            addFinding(findings, { reason: "invalid_utf8" });
+        }
+        if (text !== undefined) {
+            const lines = text.slice(0, -1).split("\n");
+            lineCount = lines.length;
+            for (let index = 0; index < lines.length; index++) {
+                const lineNumber = index + 1;
+                const line = lines[index];
+                if (line.trim().length === 0) {
+                    addFinding(findings, { reason: "malformed_json", line: lineNumber });
+                    continue;
+                }
+                try {
+                    records.push({ line: lineNumber, value: JSON.parse(line) });
+                }
+                catch {
+                    addFinding(findings, { reason: "malformed_json", line: lineNumber });
+                }
+            }
+        }
+    }
+    const headerRecords = records.filter((record) => isRecord(record.value) && record.value.type === "session");
+    const firstRecord = records.find((record) => record.line === 1);
+    let header = null;
+    if (!firstRecord || !isRecord(firstRecord.value) || firstRecord.value.type !== "session") {
+        addFinding(findings, { reason: "missing_header", line: 1 });
+    }
+    else if (validHeader(firstRecord.value, 1, findings)) {
+        header = firstRecord.value;
+    }
+    if (headerRecords.length > 1) {
+        addFinding(findings, { reason: "multiple_header", line: headerRecords[1].line });
+    }
+    for (const record of headerRecords) {
+        if (record.line !== 1) {
+            addFinding(findings, { reason: "late_header", line: record.line });
+            if (record.value.version !== CURRENT_SESSION_VERSION) {
+                addFinding(findings, { reason: "unsupported_header", line: record.line });
+            }
+        }
+    }
+    const parsedEntries = [];
+    for (const record of records) {
+        if (isRecord(record.value) && record.value.type === "session")
+            continue;
+        if (!isRecord(record.value)) {
+            addFinding(findings, { reason: "invalid_entry", line: record.line });
+            continue;
+        }
+        if (typeof record.value.type === "string" && !SUPPORTED_ENTRY_TYPES.has(record.value.type)) {
+            addFinding(findings, { reason: "unsupported_entry", line: record.line });
+            continue;
+        }
+        if (!validEntryShape(record.value)) {
+            addFinding(findings, {
+                reason: "invalid_entry",
+                line: record.line,
+                ...(typeof record.value.id === "string" ? { entryId: record.value.id } : {}),
+            });
+            continue;
+        }
+        parsedEntries.push({ line: record.line, entry: record.value });
+    }
+    const byId = new Map();
+    for (const parsed of parsedEntries) {
+        if (byId.has(parsed.entry.id)) {
+            addFinding(findings, {
+                reason: "duplicate_entry_id",
+                line: parsed.line,
+                entryId: parsed.entry.id,
+            });
+        }
+        else {
+            byId.set(parsed.entry.id, parsed.entry);
+        }
+    }
+    for (const parsed of parsedEntries) {
+        const { entry } = parsed;
+        if (entry.parentId !== null && !byId.has(entry.parentId)) {
+            addFinding(findings, {
+                reason: "missing_parent",
+                line: parsed.line,
+                entryId: entry.id,
+                parentId: entry.parentId,
+            });
+        }
+    }
+    for (const cycle of findCycles(parsedEntries, byId))
+        findings.push(cycle);
+    const selectedLeaf = options.activeLeafId === undefined ? (parsedEntries.at(-1)?.entry.id ?? null) : options.activeLeafId;
+    let activeBranch = [];
+    let activeMessages = [];
+    let transcript = null;
+    const hasStructuralBlocker = findings.some((finding) => finding.reason !== "trailing_fragment");
+    if (selectedLeaf !== null && !byId.has(selectedLeaf)) {
+        addFinding(findings, { reason: "active_leaf_missing", entryId: selectedLeaf });
+    }
+    else if (!hasStructuralBlocker) {
+        if (selectedLeaf !== null) {
+            let current = byId.get(selectedLeaf);
+            while (current) {
+                activeBranch.unshift(current);
+                current = current.parentId === null ? undefined : byId.get(current.parentId);
+            }
+        }
+        const ancestorIds = new Set();
+        for (const entry of activeBranch) {
+            if (entry.type === "compaction" && !ancestorIds.has(entry.firstKeptEntryId)) {
+                addFinding(findings, {
+                    reason: "compaction_first_kept_not_ancestor",
+                    entryId: entry.id,
+                });
+            }
+            ancestorIds.add(entry.id);
+        }
+        if (!findings.some((finding) => finding.reason === "compaction_first_kept_not_ancestor")) {
+            try {
+                activeMessages = buildSessionContext(parsedEntries.map((parsed) => parsed.entry), selectedLeaf, byId).messages;
+                const inspected = inspectTranscriptIntegrity(activeMessages);
+                transcript = freezeTranscript(inspected);
+                for (const issue of inspected.issues) {
+                    addFinding(findings, {
+                        reason: transcriptFindingReason(issue.kind),
+                        toolCallId: issue.toolCallId,
+                        ...(issue.toolName === undefined ? {} : { toolName: issue.toolName }),
+                    });
+                }
+            }
+            catch {
+                addFinding(findings, { reason: "active_branch_context_invalid", entryId: selectedLeaf ?? undefined });
+                activeBranch = [];
+                activeMessages = [];
+                transcript = null;
+            }
+        }
+    }
+    const frozenEntries = Object.freeze(parsedEntries.map((parsed) => deepFreeze(parsed.entry)));
+    const frozenBranch = Object.freeze(activeBranch.map((entry) => deepFreeze(entry)));
+    const frozenMessages = Object.freeze(activeMessages.map((message) => deepFreeze(message)));
+    return Object.freeze({
+        ok: findings.length === 0,
+        source,
+        completePrefix: Object.freeze({
+            byteCount: completeByteCount,
+            sha256: sha256(completeBytes),
+            lineCount,
+        }),
+        trailingFragment,
+        header: header === null ? null : deepFreeze(header),
+        entries: frozenEntries,
+        activeLeafId: selectedLeaf,
+        activeBranch: frozenBranch,
+        activeMessages: frozenMessages,
+        transcript,
+        findings: Object.freeze(findings),
+    });
+}
+//# sourceMappingURL=session-integrity.js.map