dsh-lcx-codex 0.4.3 → 0.5.0-pre.1

package/lib/native-checkpoint.js

@@ -1,9 +1,23 @@
 // @ts-check
 import { isCompactCheckpointSource } from "@deepseek-ai/dsh-compaction";
-import { SessionSeq, } from "@deepseek-ai/dsh-session";
+import { projectToolUpdates, } from "@deepseek-ai/dsh-llm";
 import { baseURLFingerprint, routeCompatible } from "./route.js";
 import { persistNativeImageReferences, responseInputItems } from "./dsh-responses.js";
 import { estimateBudgetItem, modelVisibleBudgetView, portableBudgetError, portableTokenCeiling, } from "./token-budget.js";
+function sessionQueryUnavailable(cause) {
+    return Object.assign(new Error("LCX checkpoint history requires the DSH session query service", { cause }), { code: "LCX_SESSION_QUERY_UNAVAILABLE" });
+}
+async function observeEvents(ctx, session) {
+    const query = ctx.get("sessionQuery");
+    if (!query)
+        throw sessionQueryUnavailable();
+    try {
+        return await query.observeSession(session.id, { projectionMode: "none" });
+    }
+    catch (cause) {
+        throw sessionQueryUnavailable(cause);
+    }
+}
 /**
  * @typedef {object} NativeCheckpointBase
  * @property {string} compactionId
@@ -41,6 +55,7 @@ import { estimateBudgetItem, modelVisibleBudgetView, portableBudgetError, portab
 /** @typedef {{ session: Session, route: RouteIdentity, result: NativeCompactionResult, input?: unknown[], ephemeralPreludeItemCount?: number, imageMap?: unknown, retentionOptions?: RetentionOptions }} CreateCheckpointOptions */
 /** @typedef {Error & { code?: string }} LcxError */
 export const NATIVE_BLOCK_TYPE = "lcx-native-compaction-v5";
+const MIGRATED_NATIVE_BLOCK_PREFIX = "plugin:lcx-native-compaction-";
 export const NATIVE_BLOCK_VERSION = 5;
 export const RETAINED_MESSAGE_TOKEN_BUDGET = 64_000;
 export const ASSISTANT_RETENTION_TOKEN_RESERVE = 24_000;
@@ -267,38 +282,51 @@ export function compactCheckpointId(message) {
 }
 /** Reject reserved checkpoint markers without interpreting unsupported formats or opening sidecars. */
 export function assertSupportedCheckpointMessage(message) {
+    // Legacy marker-only messages had no DSH checkpoint source. A marker quoted
+    // inside ordinary content (for example a tool's source-file excerpt) is data.
+    const legacyMarkerOnly = message.role === "user" && message.content.length === 1 &&
+        message.content[0]?.type === "text" &&
+        /^\[dsh-lcx-codex-[^\]\r\n]*checkpoint:[^\]\r\n]*\]$/iu.test(message.content[0].text.trim());
     for (const block of message.content) {
-        if (block.type.startsWith("lcx-native-compaction-") && block.type !== NATIVE_BLOCK_TYPE ||
-            block.type === "text" && /\[dsh-lcx-codex-[^\]\r\n]*checkpoint:/iu.test(block.text))
+        if ((block.type.startsWith("lcx-native-compaction-") && block.type !== NATIVE_BLOCK_TYPE) ||
+            block.type.startsWith(MIGRATED_NATIVE_BLOCK_PREFIX) ||
+            block.type === "text" && (legacyMarkerOnly ||
+                compactCheckpointId(message) !== undefined && /\[dsh-lcx-codex-[^\]\r\n]*checkpoint:/iu.test(block.text)))
             throw Object.assign(new Error("Unsupported LCX checkpoint format; start a new session"), {
                 code: "LCX_CHECKPOINT_UNSUPPORTED",
             });
     }
 }
-/** @param {Session | null | undefined} session */
-export function activeCompactionId(session) {
+/** The active transaction is read from one immutable query observation. */
+export async function activeCompactionId(ctx, session) {
     if (!session)
         return undefined;
     /** @type {Set<string>} */ const ended = new Set();
-    const events = session.snapshotEvents();
-    for (let index = events.length - 1; index >= 0; index -= 1) {
-        const event = events[index];
-        if (!event)
-            continue;
-        if (event.type === "compaction/end")
-            ended.add(String(event.data.compactionId));
-        if (event.type === "compaction/start" &&
-            !ended.has(String(event.data.compactionId)))
-            return String(event.data.compactionId);
+    const lease = await observeEvents(ctx, session);
+    try {
+        const events = lease.events;
+        for (let index = events.length - 1; index >= 0; index -= 1) {
+            const event = events[index];
+            if (!event)
+                continue;
+            if (event.type === "compaction/end")
+                ended.add(String(event.data.compactionId));
+            if (event.type === "compaction/start" &&
+                !ended.has(String(event.data.compactionId)))
+                return String(event.data.compactionId);
+        }
+        return undefined;
+    }
+    finally {
+        lease[Symbol.dispose]();
     }
-    return undefined;
 }
 /**
  * @param {CreateCheckpointOptions} options
- * @returns {NativeCheckpointV5}
+ * @returns {Promise<NativeCheckpointV5>}
  */
-export function createNativeCheckpointBlock({ session, route, result, input = [], ephemeralPreludeItemCount = 0, imageMap, retentionOptions = {}, }) {
-    const compactionId = activeCompactionId(session);
+export async function createNativeCheckpointBlock({ ctx, session, route, result, input = [], ephemeralPreludeItemCount = 0, imageMap, retentionOptions = {}, }) {
+    const compactionId = await activeCompactionId(ctx, session);
     if (!compactionId) {
         const error = new Error("Native compaction could not correlate the active DSH compaction transaction");
         error.code = "LCX_COMPACTION_ID_UNAVAILABLE";
@@ -350,19 +378,25 @@ export function nativeCheckpointChunks(block, usage) {
 /**
  * @param {Session | null | undefined} session
  * @param {string | null | undefined} compactionId
- * @returns {CompactionSummaryEvent | undefined}
+ * @returns {Promise<CompactionSummaryEvent | undefined>}
  */
-export function compactionSummaryEvent(session, compactionId) {
+export async function compactionSummaryEvent(ctx, session, compactionId) {
     if (!session || !compactionId)
         return undefined;
-    const events = session.snapshotEvents();
-    for (let index = events.length - 1; index >= 0; index -= 1) {
-        const event = events[index];
-        if (event?.type === "compaction/summary" &&
-            String(event.data.compactionId) === compactionId)
-            return event;
+    const lease = await observeEvents(ctx, session);
+    try {
+        const events = lease.events;
+        for (let index = events.length - 1; index >= 0; index -= 1) {
+            const event = events[index];
+            if (event?.type === "compaction/summary" &&
+                String(event.data.compactionId) === compactionId)
+                return event;
+        }
+        return undefined;
+    }
+    finally {
+        lease[Symbol.dispose]();
     }
-    return undefined;
 }
 /**
  * rawOutput elements remain untrusted until stateFromSummaryEvent validates them.
@@ -378,11 +412,20 @@ function nativeBlockFromSummary(event) {
     const raw = event?.data.rawOutput;
     if (!raw)
         return undefined;
-    for (const value of raw)
+    assertNoMigratedNativeBlock(raw);
+    for (const value of raw) {
         if (isNativeCheckpointCandidate(value))
             return value;
+    }
     return undefined;
 }
+function assertNoMigratedNativeBlock(raw) {
+    if (raw?.some(value => isObject(value) && typeof value.type === "string" &&
+        value.type.startsWith(MIGRATED_NATIVE_BLOCK_PREFIX)))
+        throw Object.assign(new Error("Unsupported LCX checkpoint format; start a new session"), {
+            code: "LCX_CHECKPOINT_UNSUPPORTED",
+        });
+}
 /** @param {unknown} value */
 function validateCount(value) {
     return (value === undefined ||
@@ -465,14 +508,18 @@ export function stateFromSummaryEvent(event) {
  * @param {Session} session
  * @param {Message} message
  */
-export function checkpointStateForMessage(session, message) {
+export function checkpointStateForMessage(ctx, session, message) {
     assertSupportedCheckpointMessage(message);
     const id = compactCheckpointId(message);
     if (!id)
         return undefined;
-    const event = compactionSummaryEvent(session, id);
+    return checkpointStateForMessageAsync(ctx, session, id);
+}
+async function checkpointStateForMessageAsync(ctx, session, id) {
+    const event = await compactionSummaryEvent(ctx, session, id);
     const state = stateFromSummaryEvent(event);
-    const hasNativeBlock = event?.data.rawOutput?.some(value => isObject(value) && typeof value.type === "string" && value.type.startsWith("lcx-native-compaction-"));
+    const hasNativeBlock = event?.data.rawOutput?.some(value => isObject(value) && typeof value.type === "string" &&
+        (value.type.startsWith("lcx-native-compaction-") || value.type.startsWith(MIGRATED_NATIVE_BLOCK_PREFIX)));
     if (hasNativeBlock && !state)
         throw Object.assign(new Error("Unsupported or invalid LCX checkpoint; start a new session"), { code: "LCX_CHECKPOINT_UNSUPPORTED" });
     return state;
@@ -485,16 +532,55 @@ export function checkpointStateForMessage(session, message) {
 export function stateRouteCompatible(state, route, ctx) {
     return routeCompatible(state, route, ctx);
 }
+const DSH_PROJECTION_UNAVAILABLE_PREFIX = 'session message projection "';
+const DSH_PROJECTION_UNAVAILABLE_SUFFIX = '" was removed or replaced; restore the session with its owning plugin';
+/**
+ * DSH 0.1.6 attaches no error code or subclass to this failure and exposes no
+ * public inventory of required or active projections, so message shape is the
+ * only available signal. Both classes fail closed, so a misclassification
+ * costs precision in the error code, not correctness.
+ * @param {unknown} cause
+ */
+function isMissingOrReplacedProjectionError(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    const { message } = cause;
+    if (!message.startsWith(DSH_PROJECTION_UNAVAILABLE_PREFIX) ||
+        !message.endsWith(DSH_PROJECTION_UNAVAILABLE_SUFFIX))
+        return false;
+    const projectionType = message.slice(DSH_PROJECTION_UNAVAILABLE_PREFIX.length, message.length - DSH_PROJECTION_UNAVAILABLE_SUFFIX.length);
+    return projectionType.length > 0;
+}
+function checkpointHistoryReadError(cause) {
+    return Object.assign(new Error("Unsupported or invalid LCX checkpoint history; start a new session", {
+        cause,
+    }), { code: "LCX_CHECKPOINT_UNSUPPORTED" });
+}
 /**
+ * DSH 0.1.6 derives a message only while every `SessionMessageProjection` the
+ * durable log committed is still registered; an absent or replaced owner throws
+ * instead of yielding pre-projection content. Reconstructing the shadowed
+ * transcript without that owner would resurrect content a durable decision
+ * (for example `image/offload`) removed, so this is a checkpoint
+ * incompatibility rather than a recoverable read.
  * @param {Session} session
  * @param {number} seq
  * @returns {Message | undefined}
  */
-function eventMessage(session, seq) {
+function eventMessage(session, events, seq) {
     if (!Number.isSafeInteger(seq) || seq < 0)
-        return undefined;
-    const event = session.eventAt(SessionSeq(seq));
-    return event ? (session.deriveEventMessage(event) ?? undefined) : undefined;
+        throw checkpointHistoryReadError(new Error("Portable checkpoint history contains an invalid event sequence"));
+    try {
+        const event = events[seq];
+        if (!event)
+            throw new Error(`Portable checkpoint history is missing event at seq ${seq}`);
+        return session.deriveEventMessage(event) ?? undefined;
+    }
+    catch (cause) {
+        if (isMissingOrReplacedProjectionError(cause))
+            throw Object.assign(new Error("Session history requires a message projection this runtime does not provide; restore the owning plugin to reuse this checkpoint", { cause }), { code: "LCX_CHECKPOINT_PROJECTION_UNAVAILABLE" });
+        throw checkpointHistoryReadError(cause);
+    }
 }
 /** @param {Message} message */
 function estimateChars(message) {
@@ -509,50 +595,60 @@ function estimateChars(message) {
 /**
  * @param {Session} session
  * @param {string} compactionId
- * @returns {Message[]}
+ * @returns {Promise<Message[]>}
  */
-function expandedCheckpointMessages(session, compactionId) {
-    const summaries = new Map();
-    for (const event of session.snapshotEvents())
-        if (event.type === "compaction/summary")
-            summaries.set(String(event.data.compactionId), event);
-    const active = new Set();
-    const stack = [];
-    const enter = (id) => {
-        const summary = summaries.get(id);
-        if (active.has(id) || !summary)
-            throw Object.assign(new Error("Portable checkpoint history is cyclic or incomplete"), { code: "LCX_CHECKPOINT_UNSUPPORTED" });
-        active.add(id);
-        stack.push({ id, seqs: summary.data.shadowedSeqs, index: 0 });
-    };
-    // Walk the DSH event graph iteratively so repeated compaction has no depth cutoff.
-    const result = [];
-    enter(compactionId);
-    while (stack.length) {
-        const frame = stack[stack.length - 1];
-        if (frame.index === frame.seqs.length) {
-            active.delete(frame.id);
-            stack.pop();
-            continue;
+async function expandedCheckpointMessages(ctx, session, compactionId) {
+    const lease = await observeEvents(ctx, session);
+    try {
+        const events = lease.events;
+        const summaries = new Map();
+        for (const event of events)
+            if (event.type === "compaction/summary")
+                summaries.set(String(event.data.compactionId), event);
+        const active = new Set();
+        const stack = [];
+        const enter = (id) => {
+            const summary = summaries.get(id);
+            if (active.has(id) || !summary)
+                throw Object.assign(new Error("Portable checkpoint history is cyclic or incomplete"), { code: "LCX_CHECKPOINT_UNSUPPORTED" });
+            assertNoMigratedNativeBlock(summary.data.rawOutput);
+            active.add(id);
+            stack.push({ id, seqs: summary.data.shadowedSeqs, index: 0 });
+        };
+        // Walk the DSH event graph iteratively so repeated compaction has no depth cutoff.
+        const result = [];
+        enter(compactionId);
+        while (stack.length) {
+            const frame = stack[stack.length - 1];
+            if (frame.index === frame.seqs.length) {
+                active.delete(frame.id);
+                stack.pop();
+                continue;
+            }
+            const message = eventMessage(session, events, frame.seqs[frame.index++]);
+            if (!message)
+                continue;
+            assertSupportedCheckpointMessage(message);
+            const nested = compactCheckpointId(message);
+            if (nested)
+                enter(nested);
+            else
+                result.push(structuredClone(message));
         }
-        const message = eventMessage(session, frame.seqs[frame.index++]);
-        if (!message)
-            continue;
-        const nested = compactCheckpointId(message);
-        if (nested)
-            enter(nested);
-        else
-            result.push(structuredClone(message));
+        // Same projection DSH applies for routes without toolUpdate (Decision 6).
+        return projectToolUpdates(result, undefined, undefined, undefined).messages;
+    }
+    finally {
+        lease[Symbol.dispose]();
     }
-    return result;
 }
 /**
  * @param {Session} session
  * @param {string} compactionId
- * @returns {Message[]}
+ * @returns {Promise<Message[]>}
  */
-export function shadowedMessagesForCheckpoint(session, compactionId) {
-    return expandedCheckpointMessages(session, compactionId);
+export async function shadowedMessagesForCheckpoint(ctx, session, compactionId) {
+    return expandedCheckpointMessages(ctx, session, compactionId);
 }
 /**
  * @param {readonly Message[]} messages
@@ -579,11 +675,7 @@ function groupMessages(messages) {
             const next = messages[cursor];
             if (!next)
                 break;
-            const results = next.role === "user"
-                ? next.content
-                    .filter((block) => block.type === "tool-result")
-                    .map((block) => String(block.toolCallId))
-                : [];
+            const results = next.role === "tool" ? [String(next.toolCallId)] : [];
             if (results.length === 0)
                 break;
             group.push(next);
@@ -601,9 +693,9 @@ function groupMessages(messages) {
  * @param {Session} session
  * @param {string} compactionId
  * @param {{ maxChars?: number }} [options]
- * @returns {Message[]}
+ * @returns {Promise<Message[]>}
  */
-export function portableMessagesForCheckpoint(session, compactionId, options = {}) {
+export async function portableMessagesForCheckpoint(ctx, session, compactionId, options = {}) {
     const configuredMaxChars = options.maxChars;
     const maxChars = typeof configuredMaxChars === "number" &&
         Number.isSafeInteger(configuredMaxChars) &&
@@ -611,7 +703,7 @@ export function portableMessagesForCheckpoint(session, compactionId, options = {
         ? configuredMaxChars
         : 80_000;
     const maxTokens = portableTokenCeiling(maxChars) ?? 1;
-    const expanded = shadowedMessagesForCheckpoint(session, compactionId);
+    const expanded = await shadowedMessagesForCheckpoint(ctx, session, compactionId);
     if (expanded.length === 0)
         return [];
     const groups = groupMessages(expanded);