larkin 0.3.3 → 0.4.2

package/dist/agent/agent-state-store.cjs

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentStateStore = void 0;
+exports.AgentStateStore = exports.ContextOverflowRecoveryError = void 0;
 exports.createAgentStateStore = createAgentStateStore;
 const fs = __importStar(require("node:fs"));
 const crypto = __importStar(require("node:crypto"));
@@ -42,6 +42,7 @@ const root_layout_js_1 = require("../platform/root-layout.cjs");
 const process_state_js_1 = require("../platform/process-state.cjs");
 const secure_metadata_js_1 = require("../platform/secure-metadata.cjs");
 const inbox_projection_js_1 = require("./inbox-projection.cjs");
+const provider_error_classifier_js_1 = require("../runtime/provider-error-classifier.cjs");
 const JSON_KEYS = new Set([
     "agentState", "status", "map", "replyctx", "botIdentity", "senderProfiles", "readReceipts", "pendingReact", "runtimeDeliveries", "inboxState", "freshnessState", "documentComments", "reminders", "interactions",
 ]);
@@ -140,7 +141,9 @@ function normalizeInboxState(value) {
                 continue;
             const row = candidate;
             if (typeof row.target === "string" && row.target && validSequence(row.seq))
-                state.messages[messageId] = { target: row.target, seq: row.seq };
+                state.messages[messageId] = {
+                    target: row.target, seq: row.seq, ...(typeof row.kind === "string" && row.kind ? { kind: row.kind } : {}),
+                };
         }
     }
     if (raw.drafts && typeof raw.drafts === "object" && !Array.isArray(raw.drafts)) {
@@ -195,6 +198,15 @@ function validInboxLockOwner(value) {
         && typeof owner.processStartToken === "string" && !!owner.processStartToken
         && typeof owner.nonce === "string" && /^[0-9a-f-]{36}$/i.test(owner.nonce);
 }
+class ContextOverflowRecoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContextOverflowRecoveryError";
+    }
+}
+exports.ContextOverflowRecoveryError = ContextOverflowRecoveryError;
 class AgentStateStore {
     paths;
     boundary;
@@ -461,13 +473,14 @@ class AgentStateStore {
         if (!value || typeof value !== "object" || Array.isArray(value))
             throw new Error("Inbox envelope must be an object");
         const input = value;
-        const target = typeof input.target === "string" && input.target ? input.target : (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(input);
+        const target = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(input);
         const current = state.targets[target] ?? { latest_received_seq: 0, model_seen_seq: 0 };
         const requested = validSequence(input.target_seq) ? input.target_seq : 0;
         const targetSeq = requested > current.latest_received_seq ? requested : current.latest_received_seq + 1;
         state.targets[target] = { ...current, latest_received_seq: targetSeq };
         if (typeof input.message_id === "string" && input.message_id) {
-            state.messages[input.message_id] = { target, seq: targetSeq };
+            state.messages[input.message_id] = { target, seq: targetSeq,
+                ...(typeof input.kind === "string" && input.kind ? { kind: input.kind } : {}) };
             const messageIds = Object.keys(state.messages);
             for (const stale of messageIds.slice(0, Math.max(0, messageIds.length - 2_048)))
                 delete state.messages[stale];
@@ -475,8 +488,9 @@ class AgentStateStore {
         return { ...input, envelope_version: 2, target, target_seq: targetSeq };
     }
     reconcileInboxRows(rows, state) {
-        return rows.map((row) => {
-            const target = typeof row.target === "string" && row.target ? row.target : (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
+        const targets = rows.map((row) => (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row));
+        return rows.map((row, index) => {
+            const target = targets[index];
             const existing = typeof row.message_id === "string" ? state.messages[row.message_id] : undefined;
             const current = state.targets[target] ?? { latest_received_seq: 0, model_seen_seq: 0 };
             const targetSeq = validSequence(row.target_seq) ? row.target_seq
@@ -484,7 +498,8 @@ class AgentStateStore {
             current.latest_received_seq = Math.max(current.latest_received_seq, targetSeq);
             state.targets[target] = current;
             if (typeof row.message_id === "string" && row.message_id)
-                state.messages[row.message_id] = { target, seq: targetSeq };
+                state.messages[row.message_id] = { target, seq: targetSeq,
+                    ...(typeof row.kind === "string" && row.kind ? { kind: row.kind } : {}) };
             return { ...row, envelope_version: 2, target, target_seq: targetSeq };
         });
     }
@@ -610,23 +625,302 @@ class AgentStateStore {
         else
             append();
     }
-    /** Append a canonical Inbox envelope once by stable message_id under the shared cross-process lock. */
-    appendInboxOnce(value) {
+    /**
+     * Append one canonical Inbox envelope and return the exact normalized object
+     * serialized to disk. Stable message_id dedupe and locator coherence share the
+     * same lock as poll, so HostShell can deliver that very object without a
+     * persistence/delivery split.
+     */
+    appendCanonicalInboxOnce(value) {
         if (!value || typeof value !== "object" || Array.isArray(value))
             throw new Error("Inbox envelope must be an object");
-        const messageId = value.message_id;
+        const input = value;
+        const messageId = input.message_id;
         if (typeof messageId !== "string" || !messageId)
             throw new Error("Inbox envelope requires message_id");
+        const incomingTarget = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(input);
         const file = this.file("inbox");
         return this.withInboxLock(file, () => {
-            if (this.inboxState().messages[messageId])
-                return false;
-            if (this.readNdjson("inbox").some((row) => row.message_id === messageId))
-                return false;
-            this.appendInboxUnlocked(value);
-            return true;
+            const state = this.inboxState();
+            const matching = this.readNdjson("inbox").filter((row) => row.message_id === messageId);
+            if (matching.length > 1)
+                throw new Error("Inbox duplicate message_id has multiple pending canonical rows");
+            if (matching.length === 1) {
+                const existing = matching[0];
+                if ((0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(existing) !== incomingTarget) {
+                    throw new Error("Inbox duplicate message_id conflicts with its canonical target");
+                }
+                if (existing.target_seq !== undefined && !validSequence(existing.target_seq)) {
+                    throw new Error("Inbox duplicate message_id has a malformed canonical sequence");
+                }
+                const known = state.messages[messageId];
+                if (known) {
+                    if (known.target !== incomingTarget)
+                        throw new Error("Inbox message state conflicts with its canonical target");
+                    if (validSequence(existing.target_seq) && existing.target_seq !== known.seq) {
+                        throw new Error("Inbox message state conflicts with its canonical sequence");
+                    }
+                    const targetState = state.targets[known.target];
+                    if (targetState && targetState.model_seen_seq >= known.seq) {
+                        throw new Error("Inbox pending row conflicts with consumed model-seen state");
+                    }
+                }
+                return { status: "duplicate_pending", envelope: existing };
+            }
+            const known = state.messages[messageId];
+            if (known) {
+                if (known.target !== incomingTarget)
+                    throw new Error("Inbox duplicate message_id conflicts with consumed canonical target");
+                const targetState = state.targets[known.target];
+                if (!targetState || targetState.model_seen_seq < known.seq) {
+                    throw new Error("Inbox state references a missing unconsumed canonical row");
+                }
+                return { status: "duplicate_consumed", envelope: null };
+            }
+            return { status: "appended", envelope: this.appendInboxUnlocked(input) };
+        });
+    }
+    /** Append a canonical Inbox envelope once by stable message_id under the shared cross-process lock. */
+    appendInboxOnce(value) {
+        return this.appendCanonicalInboxOnce(value).status === "appended";
+    }
+    /**
+     * Resolve one Runtime delivery solely from canonical Inbox row/state. This is
+     * the single replay resolver used for startup migration and every retry; it
+     * never derives a DM/generic fallback from stale RuntimeInput text.
+     */
+    resolveInboxDeliverySource(messageId) {
+        if (!messageId)
+            return { status: "missing", code: "canonical_inbox_row_missing" };
+        return this.withInboxLock(this.file("inbox"), () => {
+            let rows;
+            try {
+                rows = this.readNdjson("inbox");
+            }
+            catch {
+                return { status: "invalid", code: "canonical_inbox_malformed" };
+            }
+            const matching = rows.filter((row) => row?.message_id === messageId);
+            if (matching.length > 1)
+                return { status: "invalid", code: "duplicate_message_id" };
+            const state = this.inboxState();
+            const known = state.messages[messageId];
+            if (matching.length === 1) {
+                const envelope = matching[0];
+                let target;
+                try {
+                    target = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(envelope);
+                }
+                catch {
+                    return { status: "invalid", code: "canonical_inbox_malformed" };
+                }
+                if (envelope.target_seq !== undefined && !validSequence(envelope.target_seq)) {
+                    return { status: "invalid", code: "canonical_inbox_malformed" };
+                }
+                if (known) {
+                    const targetState = state.targets[known.target];
+                    if (known.target !== target || !validSequence(known.seq)
+                        || (validSequence(envelope.target_seq) && envelope.target_seq !== known.seq)
+                        || Boolean(targetState && targetState.model_seen_seq >= known.seq)) {
+                        return { status: "invalid", code: "inbox_state_conflict" };
+                    }
+                }
+                return { status: "pending", target, envelope };
+            }
+            if (!known)
+                return { status: "missing", code: "canonical_inbox_row_missing" };
+            if (!(0, inbox_projection_js_1.isCanonicalInboxTarget)(known.target) || !validSequence(known.seq)) {
+                return { status: "invalid", code: "inbox_state_conflict" };
+            }
+            const targetState = state.targets[known.target];
+            if (targetState && targetState.model_seen_seq >= known.seq)
+                return { status: "consumed", target: known.target };
+            return { status: "missing", code: "canonical_inbox_row_missing" };
         });
     }
+    /**
+     * Re-arm only the durable deliveries proven to be the context-window incident.
+     * The Inbox bytes are intentionally untouched. An optional synchronous commit
+     * hook lets RuntimeHost swap its in-memory generation while this same lock is
+     * still held. If the hook fails, the ledger is restored before the lock is
+     * released. The callback also receives a guarded rollback for post-callback
+     * commit failures before retry scheduling begins.
+     */
+    rearmContextOverflow(onCommit, expected) {
+        let lockActive = true;
+        try {
+            return this.withInboxTransaction(() => {
+                let rows;
+                try {
+                    rows = this.readNdjson("inbox");
+                }
+                catch {
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox is malformed");
+                }
+                if (rows.length === 0)
+                    throw new ContextOverflowRecoveryError("inbox_empty", "canonical Inbox backlog is empty");
+                const messageIds = new Set();
+                for (const row of rows) {
+                    try {
+                        (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
+                    }
+                    catch {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox contains a malformed row");
+                    }
+                    if (typeof row.message_id !== "string" || !row.message_id) {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox row has no message identity");
+                    }
+                    if (messageIds.has(row.message_id))
+                        throw new ContextOverflowRecoveryError("duplicate_message_id", "canonical Inbox contains duplicate message identities");
+                    messageIds.add(row.message_id);
+                }
+                const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (!Array.isArray(ledger.records))
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "Runtime delivery ledger is malformed");
+                const ledgerRecords = ledger.records;
+                const matches = new Map();
+                const deliveryIds = new Set();
+                const inputIds = new Set();
+                for (const candidate of ledger.records) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        continue;
+                    if (typeof record.deliveryId !== "string" || !record.deliveryId)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a matching Runtime delivery record has no delivery identity");
+                    if (!record.input || typeof record.input !== "object" || Array.isArray(record.input)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has no Runtime input identity");
+                    }
+                    const input = record.input;
+                    if (typeof input.inputId !== "string" || !input.inputId.trim()
+                        || typeof input.deliveryId !== "string" || input.deliveryId !== record.deliveryId) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has malformed input identity");
+                    }
+                    if (matches.has(record.messageId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a canonical Inbox row maps to multiple delivery records");
+                    if (deliveryIds.has(record.deliveryId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "matching Runtime delivery records share a delivery identity");
+                    if (inputIds.has(input.inputId))
+                        throw new ContextOverflowRecoveryError("duplicate_input_id", "matching Runtime delivery records share an input identity");
+                    deliveryIds.add(record.deliveryId);
+                    inputIds.add(input.inputId);
+                    matches.set(record.messageId, record);
+                }
+                if (expected?.messageId && !messageIds.has(expected.messageId)) {
+                    throw new ContextOverflowRecoveryError("delivery_missing", "the expected context-overflow message is not in canonical Inbox");
+                }
+                if (expected?.messageId) {
+                    const expectedRecord = matches.get(expected.messageId);
+                    if (!expectedRecord || (expected.deliveryId && expectedRecord.deliveryId !== expected.deliveryId)
+                        || (expected.inputId && expectedRecord.input.inputId !== expected.inputId)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "the expected context-overflow delivery identity changed");
+                    }
+                }
+                for (const messageId of messageIds) {
+                    const record = matches.get(messageId);
+                    if (!record)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a canonical Inbox row has no Runtime delivery record");
+                    if (record.status !== "error" || record.retryable === true) {
+                        throw new ContextOverflowRecoveryError("delivery_not_terminal", "a canonical Inbox row is not backed by a non-retryable terminal Runtime error");
+                    }
+                    const reasonCategory = (0, provider_error_classifier_js_1.classifyStrictProviderError)((0, provider_error_classifier_js_1.buildStrictProviderErrorInput)({
+                        reason: record.reason, errorCategory: record.errorCategory,
+                    }));
+                    if (record.retryable !== false || reasonCategory !== "context_window"
+                        || (record.errorCategory !== undefined && record.errorCategory !== "context_window")) {
+                        throw new ContextOverflowRecoveryError("delivery_not_context_window", "a Runtime delivery error is not classified as context_window");
+                    }
+                }
+                for (const candidate of ledgerRecords) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.deliveryId === "string" && deliveryIds.has(record.deliveryId)
+                        && (typeof record.messageId !== "string" || !messageIds.has(record.messageId))) {
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a matching delivery identity is also used by an unrelated Runtime delivery record");
+                    }
+                }
+                const updatedAt = new Date().toISOString();
+                const records = ledgerRecords.map((candidate) => {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        return candidate;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        return candidate;
+                    return { ...record, status: "pending", retryable: true, updatedAt,
+                        reason: "context-window recovery rearmed the retained Inbox delivery" };
+                });
+                const committedLedger = { ...ledger, records };
+                let restored = false;
+                const restoreUnlocked = () => {
+                    if (restored)
+                        return;
+                    const current = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                    if (!Array.isArray(current.records))
+                        throw new Error("Runtime delivery rollback found a malformed ledger");
+                    const originalMatching = ledgerRecords.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return typeof record.messageId === "string" && messageIds.has(record.messageId);
+                    });
+                    const originalDeliveryIds = new Set(originalMatching.flatMap((candidate) => {
+                        const deliveryId = candidate.deliveryId;
+                        return typeof deliveryId === "string" ? [deliveryId] : [];
+                    }));
+                    const currentMatching = current.records.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return (typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                            || (typeof record.messageId === "string" && messageIds.has(record.messageId));
+                    });
+                    const matchingRestored = currentMatching.length === originalMatching.length
+                        && currentMatching.every((candidate, index) => JSON.stringify(candidate) === JSON.stringify(originalMatching[index]));
+                    if (!matchingRestored) {
+                        const unrelated = current.records.filter((candidate) => {
+                            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                                return true;
+                            const record = candidate;
+                            return !((typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                                || (typeof record.messageId === "string" && messageIds.has(record.messageId)));
+                        });
+                        const restoredRecords = [...unrelated];
+                        for (const candidate of originalMatching) {
+                            const originalIndex = ledgerRecords.indexOf(candidate);
+                            restoredRecords.splice(Math.min(originalIndex, restoredRecords.length), 0, candidate);
+                        }
+                        this.writeJson("runtimeDeliveries", { ...current, records: restoredRecords });
+                    }
+                    restored = true;
+                };
+                const rollback = () => {
+                    if (lockActive)
+                        restoreUnlocked();
+                    else
+                        this.withInboxTransaction(restoreUnlocked);
+                };
+                try {
+                    this.writeJson("runtimeDeliveries", committedLedger);
+                    onCommit?.([...messageIds], rollback);
+                }
+                catch (error) {
+                    try {
+                        rollback();
+                    }
+                    catch {
+                        throw new Error("context-window recovery ledger rollback failed");
+                    }
+                    throw error;
+                }
+                return { rearmedCount: messageIds.size, remainingPendingCount: rows.length };
+            });
+        }
+        finally {
+            lockActive = false;
+        }
+    }
     /**
      * Recoverably bridge an outbox wake into the canonical Inbox. A durable
      * Runtime ledger is authoritative after the Inbox has been drained, so a
@@ -638,6 +932,7 @@ class AgentStateStore {
         const messageId = value.message_id;
         if (typeof messageId !== "string" || !messageId)
             throw new Error("Inbox envelope requires message_id");
+        (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(value);
         const file = this.file("inbox");
         return this.withInboxLock(file, () => {
             const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
@@ -686,6 +981,9 @@ class AgentStateStore {
      * this transaction is active waits and becomes part of the next batch.
      */
     pollInbox(options = {}) {
+        if (options.target && !(0, inbox_projection_js_1.isCanonicalInboxTarget)(options.target)) {
+            throw new Error(`Invalid canonical Inbox poll target ${JSON.stringify(options.target)}`);
+        }
         const file = this.file("inbox");
         return this.withInboxLock(file, () => {
             let rawRows;
@@ -704,7 +1002,7 @@ class AgentStateStore {
             const envelopes = [];
             const remaining = [];
             for (const row of rows) {
-                const selectedTarget = typeof row.target === "string" ? row.target : (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
+                const selectedTarget = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
                 if (envelopes.length < limit && (!options.target || options.target === selectedTarget))
                     envelopes.push(row);
                 else
@@ -713,7 +1011,7 @@ class AgentStateStore {
             const pendingCount = remaining.reduce((count, row) => {
                 if (!options.target)
                     return count + 1;
-                const rowTarget = typeof row.target === "string" ? row.target : (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
+                const rowTarget = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
                 return count + (rowTarget === options.target ? 1 : 0);
             }, 0);
             if (!envelopes.length)
@@ -747,7 +1045,7 @@ class AgentStateStore {
             }
             let seenThroughSeq = null;
             for (const envelope of envelopes) {
-                const target = String(envelope.target || (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(envelope));
+                const target = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(envelope);
                 const targetSeq = Number(envelope.target_seq);
                 const targetState = state.targets[target] ?? { latest_received_seq: targetSeq, model_seen_seq: 0 };
                 if (validSequence(targetSeq)) {
@@ -768,11 +1066,12 @@ class AgentStateStore {
     resolveInboxMessageTarget(messageId) {
         return this.withInboxLock(this.file("inbox"), () => {
             const state = this.inboxState();
-            const known = state.messages[messageId]?.target;
+            const known = state.messages[messageId];
             if (known)
-                return known;
+                return (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)({ message_id: messageId, target: known.target,
+                    ...(known.kind ? { kind: known.kind } : {}) });
             const row = this.readNdjson("inbox").find((candidate) => candidate.message_id === messageId);
-            return row ? (typeof row.target === "string" ? row.target : (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row)) : null;
+            return row ? (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row) : null;
         });
     }
     listInboxDrafts() {