larkin 0.2.70

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

@@ -0,0 +1,923 @@
+import * as fs from "node:fs";
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { TargetRootLayout } from "../platform/root-layout.mjs";
+import { acquireProcessLock, inspectProcess } from "../platform/process-state.mjs";
+import { targetKeyOfInboxEnvelope } from "./inbox-projection.mjs";
+const JSON_KEYS = new Set([
+    "agentState", "status", "map", "replyctx", "botIdentity", "senderProfiles", "readReceipts", "pendingReact", "runtimeDeliveries", "inboxState", "freshnessState", "documentComments", "reminders", "interactions",
+]);
+const NDJSON_KEYS = new Set(["conversation", "inbox"]);
+const INBOX_LOCK_TIMEOUT_MS = 2_000;
+const INBOX_MALFORMED_LOCK_GRACE_MS = 5_000;
+const INBOX_LOCK_OWNER_FILE = "owner.json";
+function lstatIfExists(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function rejectSymlink(file) {
+    if (lstatIfExists(file)?.isSymbolicLink())
+        throw new Error(`state path must not be a symlink: ${file}`);
+}
+function mkdirSecure(dir, boundary) {
+    const relative = path.relative(boundary, dir);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`state path escapes boundary: ${dir}`);
+    rejectSymlink(boundary);
+    fs.mkdirSync(boundary, { recursive: true, mode: 0o700 });
+    let cursor = boundary;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, segment);
+        rejectSymlink(cursor);
+        try {
+            fs.mkdirSync(cursor, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        rejectSymlink(cursor);
+        if (!fs.statSync(cursor).isDirectory())
+            throw new Error(`state path is not a directory: ${cursor}`);
+    }
+}
+function validateExistingPath(file, boundary) {
+    const relative = path.relative(boundary, file);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`state path escapes boundary: ${file}`);
+    let cursor = boundary;
+    const boundaryStat = lstatIfExists(cursor);
+    if (!boundaryStat)
+        return;
+    if (boundaryStat.isSymbolicLink())
+        throw new Error(`state path must not be a symlink: ${cursor}`);
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, segment);
+        const stat = lstatIfExists(cursor);
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink())
+            throw new Error(`state path must not be a symlink: ${cursor}`);
+    }
+}
+function stringifyJson(value, pretty) {
+    const text = JSON.stringify(value, null, pretty ? 2 : undefined);
+    if (text === undefined)
+        throw new Error("state value must be JSON serializable");
+    return text;
+}
+function sleepSync(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function emptyInboxState() {
+    return { version: 2, targets: {}, messages: {}, drafts: {}, intents: {} };
+}
+function validSequence(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function normalizeInboxState(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return emptyInboxState();
+    const raw = value;
+    const state = emptyInboxState();
+    if (raw.targets && typeof raw.targets === "object" && !Array.isArray(raw.targets)) {
+        for (const [target, candidate] of Object.entries(raw.targets)) {
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                continue;
+            const row = candidate;
+            const latest = validSequence(row.latest_received_seq) ? row.latest_received_seq : 0;
+            const seen = validSequence(row.model_seen_seq) ? Math.min(row.model_seen_seq, latest) : 0;
+            state.targets[target] = { latest_received_seq: latest, model_seen_seq: seen };
+        }
+    }
+    if (raw.messages && typeof raw.messages === "object" && !Array.isArray(raw.messages)) {
+        for (const [messageId, candidate] of Object.entries(raw.messages)) {
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                continue;
+            const row = candidate;
+            if (typeof row.target === "string" && row.target && validSequence(row.seq))
+                state.messages[messageId] = { target: row.target, seq: row.seq };
+        }
+    }
+    if (raw.drafts && typeof raw.drafts === "object" && !Array.isArray(raw.drafts)) {
+        for (const [draftId, candidate] of Object.entries(raw.drafts)) {
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                continue;
+            const draft = candidate;
+            if (draft.draft_id === draftId && typeof draft.target === "string" && Array.isArray(draft.argv)
+                && draft.argv.every((argument) => typeof argument === "string") && ["held", "sending", "sent", "abandoned"].includes(draft.status)) {
+                const normalized = { ...draft, argv: [...draft.argv] };
+                if (normalized.status === "sending" && (typeof normalized.intent_id !== "string" || !normalized.intent_id
+                    || !Number.isSafeInteger(normalized.intent_model_seen_seq) || Number(normalized.intent_model_seen_seq) < 0
+                    || typeof normalized.sending_at !== "string" || !normalized.sending_at)) {
+                    normalized.status = "held";
+                    delete normalized.intent_id;
+                    delete normalized.intent_model_seen_seq;
+                    delete normalized.sending_at;
+                }
+                state.drafts[draftId] = normalized;
+            }
+        }
+    }
+    if (raw.intents && typeof raw.intents === "object" && !Array.isArray(raw.intents)) {
+        for (const [intentId, candidate] of Object.entries(raw.intents)) {
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                continue;
+            const intent = candidate;
+            if (intent.intent_id === intentId && typeof intent.target === "string" && !!intent.target
+                && Array.isArray(intent.argv) && intent.argv.every((argument) => typeof argument === "string")
+                && Number.isSafeInteger(intent.latest_received_seq) && intent.latest_received_seq >= 0
+                && Number.isSafeInteger(intent.model_seen_seq) && intent.model_seen_seq >= 0
+                && typeof intent.committed_at === "string" && !!intent.committed_at
+                && (intent.draft_id === undefined || typeof intent.draft_id === "string")) {
+                state.intents[intentId] = { ...intent, argv: [...intent.argv] };
+            }
+        }
+    }
+    return state;
+}
+function newInboxLockOwner(inspect) {
+    const inspected = inspect(process.pid);
+    if (!inspected.ok || !inspected.startToken) {
+        throw new Error(`无法读取 Inbox lock owner 身份：${inspected.reason || "metadata incomplete"}`);
+    }
+    return { version: 1, pid: process.pid, processStartToken: inspected.startToken, nonce: crypto.randomUUID() };
+}
+function validInboxLockOwner(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const owner = value;
+    return owner.version === 1 && Number.isSafeInteger(owner.pid) && Number(owner.pid) > 0
+        && typeof owner.processStartToken === "string" && !!owner.processStartToken
+        && typeof owner.nonce === "string" && /^[0-9a-f-]{36}$/i.test(owner.nonce);
+}
+export class AgentStateStore {
+    paths;
+    boundary;
+    inspect;
+    constructor(layout, agentId, dependencies = {}) {
+        this.paths = layout.agentStatePaths(agentId);
+        this.boundary = path.join(layout.root, "state");
+        this.inspect = dependencies.inspectProcess ?? inspectProcess;
+    }
+    file(key) {
+        if (!JSON_KEYS.has(key) && !NDJSON_KEYS.has(key))
+            throw new Error(`unknown Agent state key: ${key}`);
+        const file = this.paths[key];
+        const relative = path.relative(this.paths.root, file);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+            throw new Error(`state file escapes Agent root: ${file}`);
+        return file;
+    }
+    prepare(file) {
+        mkdirSecure(this.paths.root, this.boundary);
+        rejectSymlink(file);
+    }
+    readInboxLockOwner(lockDir) {
+        const ownerFile = path.join(lockDir, INBOX_LOCK_OWNER_FILE);
+        let fd = null;
+        try {
+            fd = fs.openSync(ownerFile, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || (typeof process.getuid === "function" && stat.uid !== process.getuid()) || (stat.mode & 0o077) !== 0) {
+                throw new Error(`Inbox lock owner 文件不安全：${ownerFile}`);
+            }
+            const value = JSON.parse(fs.readFileSync(fd, "utf8"));
+            return validInboxLockOwner(value) ? value : null;
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error instanceof SyntaxError)
+                return null;
+            throw error;
+        }
+        finally {
+            if (fd !== null)
+                fs.closeSync(fd);
+        }
+    }
+    inboxLockState(lockDir) {
+        const owner = this.readInboxLockOwner(lockDir);
+        if (!owner) {
+            const stat = lstatIfExists(lockDir);
+            if (!stat)
+                return "reclaimable";
+            const age = Date.now() - stat.mtimeMs;
+            return age >= INBOX_MALFORMED_LOCK_GRACE_MS ? "reclaimable" : "unknown";
+        }
+        const inspected = this.inspect(owner.pid);
+        if (!inspected.ok)
+            return inspected.dead ? "reclaimable" : "unknown";
+        if (!inspected.startToken)
+            return "unknown";
+        return inspected.startToken === owner.processStartToken ? "active" : "reclaimable";
+    }
+    removeInboxLockIfOwned(lockDir, owner) {
+        const current = this.readInboxLockOwner(lockDir);
+        if (!current || current.pid !== owner.pid || current.nonce !== owner.nonce
+            || current.processStartToken !== owner.processStartToken)
+            return;
+        fs.unlinkSync(path.join(lockDir, INBOX_LOCK_OWNER_FILE));
+        fs.rmdirSync(lockDir);
+    }
+    tryReclaimInboxLock(lockDir) {
+        const reclaimFile = `${lockDir}.reclaim`;
+        rejectSymlink(reclaimFile);
+        let reclaim;
+        try {
+            reclaim = acquireProcessLock(reclaimFile, path.basename(process.execPath), {
+                malformedGraceMs: INBOX_MALFORMED_LOCK_GRACE_MS,
+            });
+        }
+        catch (error) {
+            if (/lock 已被|无法取得 lock|正在创建|暂不能接管/.test(error instanceof Error ? error.message : String(error)))
+                return false;
+            throw error;
+        }
+        try {
+            let stat;
+            try {
+                stat = fs.lstatSync(lockDir);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return true;
+                throw error;
+            }
+            if (!stat.isDirectory() || stat.isSymbolicLink()
+                || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+                throw new Error(`invalid inbox lock path: ${lockDir}`);
+            }
+            if (this.inboxLockState(lockDir) !== "reclaimable")
+                return false;
+            let entries;
+            try {
+                entries = fs.readdirSync(lockDir);
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    if (!lstatIfExists(lockDir))
+                        return true;
+                    return false;
+                }
+                throw error;
+            }
+            if (entries.some((entry) => entry !== INBOX_LOCK_OWNER_FILE)) {
+                throw new Error(`Inbox lock 包含未知内容，拒绝回收：${lockDir}`);
+            }
+            if (entries.includes(INBOX_LOCK_OWNER_FILE)) {
+                const ownerFile = path.join(lockDir, INBOX_LOCK_OWNER_FILE);
+                const ownerStat = lstatIfExists(ownerFile);
+                if (!ownerStat) {
+                    if (!lstatIfExists(lockDir))
+                        return true;
+                    return false;
+                }
+                if (!ownerStat.isFile() || ownerStat.isSymbolicLink())
+                    throw new Error(`Inbox lock owner 路径无效：${lockDir}`);
+                try {
+                    fs.unlinkSync(ownerFile);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        if (!lstatIfExists(lockDir))
+                            return true;
+                        return false;
+                    }
+                    throw error;
+                }
+            }
+            try {
+                fs.rmdirSync(lockDir);
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    if (!lstatIfExists(lockDir))
+                        return true;
+                    return false;
+                }
+                throw error;
+            }
+            return true;
+        }
+        finally {
+            reclaim.release();
+        }
+    }
+    withInboxLock(file, operation) {
+        this.prepare(file);
+        const lockDir = `${file}.lock`;
+        const relative = path.relative(this.paths.root, lockDir);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error(`inbox lock escapes Agent root: ${lockDir}`);
+        }
+        const reclaimFile = `${lockDir}.reclaim`;
+        const deadline = Date.now() + INBOX_LOCK_TIMEOUT_MS;
+        const owner = newInboxLockOwner(this.inspect);
+        let acquired = false;
+        for (;;) {
+            rejectSymlink(lockDir);
+            rejectSymlink(reclaimFile);
+            const reclaimStat = lstatIfExists(reclaimFile);
+            if (reclaimStat) {
+                if (!reclaimStat.isFile() || (typeof process.getuid === "function" && reclaimStat.uid !== process.getuid())) {
+                    throw new Error(`invalid inbox reclaim lock path: ${reclaimFile}`);
+                }
+                this.tryReclaimInboxLock(lockDir);
+                if (lstatIfExists(reclaimFile)) {
+                    if (Date.now() >= deadline)
+                        throw new Error("Inbox 锁等待超时");
+                    sleepSync(50);
+                    continue;
+                }
+            }
+            try {
+                fs.mkdirSync(lockDir, { mode: 0o700 });
+                const stat = fs.lstatSync(lockDir);
+                if (!stat.isDirectory() || stat.isSymbolicLink() ||
+                    (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+                    throw new Error(`inbox lock is not an owned directory: ${lockDir}`);
+                }
+                const ownerFile = path.join(lockDir, INBOX_LOCK_OWNER_FILE);
+                const fd = fs.openSync(ownerFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+                try {
+                    fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`);
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                if (lstatIfExists(reclaimFile)) {
+                    this.removeInboxLockIfOwned(lockDir, owner);
+                    throw Object.assign(new Error("Inbox lock 正在回收"), { code: "EEXIST" });
+                }
+                const current = this.readInboxLockOwner(lockDir);
+                if (!current || current.nonce !== owner.nonce || current.pid !== owner.pid) {
+                    throw new Error("Inbox lock owner 发布后不一致");
+                }
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const stat = lstatIfExists(lockDir);
+                if (stat) {
+                    if (stat.isSymbolicLink() || !stat.isDirectory())
+                        throw new Error(`invalid inbox lock path: ${lockDir}`);
+                    if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+                        throw new Error(`inbox lock is not owned by current user: ${lockDir}`);
+                    }
+                    if (this.inboxLockState(lockDir) === "reclaimable" && this.tryReclaimInboxLock(lockDir))
+                        continue;
+                }
+                if (Date.now() >= deadline)
+                    throw new Error("Inbox 锁等待超时");
+                sleepSync(50);
+            }
+        }
+        try {
+            return operation();
+        }
+        finally {
+            if (acquired)
+                this.removeInboxLockIfOwned(lockDir, owner);
+        }
+    }
+    /** Share the canonical Inbox/delivery-state transaction boundary with RuntimeHost. */
+    withInboxTransaction(operation) {
+        return this.withInboxLock(this.file("inbox"), operation);
+    }
+    inboxState() {
+        return normalizeInboxState(this.readJson("inboxState", emptyInboxState()));
+    }
+    readFreshnessCursor(target, generation = "external") {
+        const state = this.readJson("freshnessState", { version: 1, cursors: {} });
+        if (state.version !== 1 || !state.cursors || typeof state.cursors !== "object" || Array.isArray(state.cursors))
+            return null;
+        const record = state.cursors[target];
+        if (!record || typeof record !== "object" || Array.isArray(record))
+            return null;
+        const row = record;
+        return row.generation === generation && row.cursor !== undefined ? row.cursor : null;
+    }
+    mergeFreshnessCursor(target, cursor, merge, generation = "external") {
+        return this.mutateJson("freshnessState", { version: 1, cursors: {} }, (state) => {
+            if (state.version !== 1 || !state.cursors || typeof state.cursors !== "object" || Array.isArray(state.cursors)) {
+                state.version = 1;
+                state.cursors = {};
+            }
+            const previous = state.cursors[target];
+            const next = merge(previous?.generation === generation ? previous.cursor : null, cursor);
+            state.cursors[target] = { generation, cursor: next };
+            return next;
+        });
+    }
+    normalizeInboxEnvelope(value, state) {
+        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 : 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 };
+            const messageIds = Object.keys(state.messages);
+            for (const stale of messageIds.slice(0, Math.max(0, messageIds.length - 2_048)))
+                delete state.messages[stale];
+        }
+        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 : targetKeyOfInboxEnvelope(row);
+            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
+                : existing?.target === target ? existing.seq : current.latest_received_seq + 1;
+            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 };
+            return { ...row, envelope_version: 2, target, target_seq: targetSeq };
+        });
+    }
+    appendInboxUnlocked(value) {
+        const file = this.file("inbox");
+        const state = this.inboxState();
+        const envelope = this.normalizeInboxEnvelope(value, state);
+        this.prepare(file);
+        const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, 0o600);
+        try {
+            fs.writeFileSync(fd, `${stringifyJson(envelope, false)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.chmodSync(file, 0o600);
+        this.writeJson("inboxState", state);
+        return envelope;
+    }
+    replaceInboxUnlocked(rows) {
+        const file = this.file("inbox");
+        this.prepare(file);
+        const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_TRUNC | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, 0o600);
+        try {
+            const text = rows.length ? `${rows.map((row) => stringifyJson(row, false)).join("\n")}\n` : "";
+            fs.writeFileSync(fd, text);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.chmodSync(file, 0o600);
+    }
+    readText(file) {
+        validateExistingPath(file, this.boundary);
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+                throw new Error(`state path is not an owned regular file: ${file}`);
+            }
+            return fs.readFileSync(fd, "utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    readJson(key, fallback) {
+        if (!JSON_KEYS.has(key))
+            throw new Error(`unknown JSON state key: ${key}`);
+        const file = this.file(key);
+        try {
+            return JSON.parse(this.readText(file));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return fallback;
+            throw error;
+        }
+    }
+    writeJson(key, value) {
+        if (!JSON_KEYS.has(key))
+            throw new Error(`unknown JSON state key: ${key}`);
+        const file = this.file(key);
+        this.prepare(file);
+        const temporary = path.join(this.paths.root, `.${path.basename(file)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+        let fd;
+        try {
+            fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            fs.writeFileSync(fd, `${stringifyJson(value, true)}\n`);
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
+            rejectSymlink(file);
+            fs.renameSync(temporary, file);
+            fs.chmodSync(file, 0o600);
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+    /** Serialize a read-modify-write transaction for one JSON state file across Host and Agent CLI processes. */
+    mutateJson(key, fallback, operation) {
+        const file = this.file(key);
+        return this.withInboxLock(file, () => {
+            const value = this.readJson(key, fallback);
+            const result = operation(value);
+            this.writeJson(key, value);
+            return result;
+        });
+    }
+    appendNdjson(key, value) {
+        if (!NDJSON_KEYS.has(key))
+            throw new Error(`unknown NDJSON state key: ${key}`);
+        const file = this.file(key);
+        const append = () => {
+            if (key === "inbox") {
+                this.appendInboxUnlocked(value);
+                return;
+            }
+            this.prepare(file);
+            const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, 0o600);
+            try {
+                fs.writeFileSync(fd, `${stringifyJson(value, false)}\n`);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.chmodSync(file, 0o600);
+        };
+        if (key === "inbox")
+            this.withInboxLock(file, append);
+        else
+            append();
+    }
+    /** Append a canonical Inbox envelope once by stable message_id under the shared cross-process lock. */
+    appendInboxOnce(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Inbox envelope must be an object");
+        const messageId = value.message_id;
+        if (typeof messageId !== "string" || !messageId)
+            throw new Error("Inbox envelope requires message_id");
+        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;
+        });
+    }
+    /**
+     * Recoverably bridge an outbox wake into the canonical Inbox. A durable
+     * Runtime ledger is authoritative after the Inbox has been drained, so a
+     * post-delivery crash cannot re-append the same synthetic wake on restart.
+     */
+    prepareInboxDelivery(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Inbox envelope must be an object");
+        const messageId = value.message_id;
+        if (typeof messageId !== "string" || !messageId)
+            throw new Error("Inbox envelope requires message_id");
+        const file = this.file("inbox");
+        return this.withInboxLock(file, () => {
+            const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+            if (!Array.isArray(ledger.records))
+                throw new Error("runtime-deliveries.json records 必须是数组");
+            const delivery = ledger.records.find((candidate) => candidate && typeof candidate === "object"
+                && !Array.isArray(candidate) && candidate.messageId === messageId);
+            if (delivery?.status === "consumed")
+                return "consumed";
+            if (["pending", "submitting", "accepted"].includes(String(delivery?.status || "")))
+                return "active";
+            if (delivery?.status === "error")
+                return "terminal_error";
+            if (this.readNdjson("inbox").some((row) => row.message_id === messageId))
+                return "present";
+            this.appendInboxUnlocked(value);
+            return "appended";
+        });
+    }
+    readNdjson(key) {
+        if (!NDJSON_KEYS.has(key))
+            throw new Error(`unknown NDJSON state key: ${key}`);
+        const file = this.file(key);
+        let text;
+        try {
+            text = this.readText(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        return text.split("\n").filter(Boolean).map((line, index) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch (error) {
+                throw new Error(`invalid NDJSON at ${file}:${index + 1}: ${error.message}`);
+            }
+        });
+    }
+    /**
+     * Atomically parse and drain the current Inbox batch relative to all
+     * AgentStateStore Inbox appenders. Parsing completes before truncation, so a
+     * malformed batch is left byte-for-byte intact. An appender arriving while
+     * this transaction is active waits and becomes part of the next batch.
+     */
+    pollInbox(options = {}) {
+        const file = this.file("inbox");
+        return this.withInboxLock(file, () => {
+            let rawRows;
+            try {
+                rawRows = this.readNdjson("inbox");
+            }
+            catch (error) {
+                throw error;
+            }
+            options.afterRead?.();
+            const state = this.inboxState();
+            const rows = this.reconcileInboxRows(rawRows, state);
+            const limit = options.limit === undefined ? 100 : options.limit;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new Error("inbox poll --limit 必须是 1..100 的整数");
+            const envelopes = [];
+            const remaining = [];
+            for (const row of rows) {
+                const selectedTarget = typeof row.target === "string" ? row.target : targetKeyOfInboxEnvelope(row);
+                if (envelopes.length < limit && (!options.target || options.target === selectedTarget))
+                    envelopes.push(row);
+                else
+                    remaining.push(row);
+            }
+            const pendingCount = remaining.reduce((count, row) => {
+                if (!options.target)
+                    return count + 1;
+                const rowTarget = typeof row.target === "string" ? row.target : targetKeyOfInboxEnvelope(row);
+                return count + (rowTarget === options.target ? 1 : 0);
+            }, 0);
+            if (!envelopes.length)
+                return { envelopes, consumedDeliveryIds: [], seenThroughSeq: null, pendingCount };
+            const messageIds = new Set(envelopes.flatMap((row) => {
+                if (!row || typeof row !== "object")
+                    return [];
+                const messageId = row.message_id;
+                return typeof messageId === "string" && messageId ? [messageId] : [];
+            }));
+            const consumedDeliveryIds = [];
+            if (messageIds.size) {
+                const deliveries = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (!Array.isArray(deliveries.records))
+                    throw new Error("runtime-deliveries.json records 必须是数组");
+                let changed = false;
+                const updatedAt = new Date((options.now ?? Date.now)()).toISOString();
+                const records = deliveries.records.map((rawRecord) => {
+                    if (!rawRecord || typeof rawRecord !== "object" || Array.isArray(rawRecord))
+                        return rawRecord;
+                    const record = rawRecord;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId) || record.status === "consumed")
+                        return rawRecord;
+                    changed = true;
+                    if (typeof record.deliveryId === "string")
+                        consumedDeliveryIds.push(record.deliveryId);
+                    return { ...record, status: "consumed", updatedAt };
+                });
+                if (changed)
+                    this.writeJson("runtimeDeliveries", { ...deliveries, records });
+            }
+            let seenThroughSeq = null;
+            for (const envelope of envelopes) {
+                const target = String(envelope.target || targetKeyOfInboxEnvelope(envelope));
+                const targetSeq = Number(envelope.target_seq);
+                const targetState = state.targets[target] ?? { latest_received_seq: targetSeq, model_seen_seq: 0 };
+                if (validSequence(targetSeq)) {
+                    targetState.latest_received_seq = Math.max(targetState.latest_received_seq, targetSeq);
+                    targetState.model_seen_seq = Math.max(targetState.model_seen_seq, targetSeq);
+                    seenThroughSeq = seenThroughSeq === null ? targetSeq : Math.max(seenThroughSeq, targetSeq);
+                }
+                state.targets[target] = targetState;
+            }
+            this.replaceInboxUnlocked(remaining);
+            this.writeJson("inboxState", state);
+            return { envelopes, consumedDeliveryIds, seenThroughSeq, pendingCount };
+        });
+    }
+    drainInbox(hooks = {}) {
+        return this.pollInbox(hooks).envelopes;
+    }
+    resolveInboxMessageTarget(messageId) {
+        return this.withInboxLock(this.file("inbox"), () => {
+            const state = this.inboxState();
+            const known = state.messages[messageId]?.target;
+            if (known)
+                return known;
+            const row = this.readNdjson("inbox").find((candidate) => candidate.message_id === messageId);
+            return row ? (typeof row.target === "string" ? row.target : targetKeyOfInboxEnvelope(row)) : null;
+        });
+    }
+    listInboxDrafts() {
+        return this.withInboxLock(this.file("inbox"), () => Object.values(this.inboxState().drafts)
+            .filter((draft) => draft.status === "held" || draft.status === "sending")
+            .sort((left, right) => left.created_at.localeCompare(right.created_at)));
+    }
+    readInboxDraft(draftId) {
+        return this.withInboxLock(this.file("inbox"), () => this.inboxState().drafts[draftId] ?? null);
+    }
+    setInboxDraftStatus(draftId, status, now = Date.now()) {
+        return this.withInboxLock(this.file("inbox"), () => {
+            const state = this.inboxState();
+            const draft = state.drafts[draftId];
+            if (!draft)
+                throw new Error(`draft 不存在：${draftId}`);
+            if (draft.status === "sending")
+                throw new Error(`draft ${draftId} 正在发送，too late to abandon；可重试 send 以同一幂等键恢复`);
+            if (draft.status !== "held")
+                throw new Error(`draft ${draftId} 已是 ${draft.status}`);
+            const updated = { ...draft, status, updated_at: new Date(now).toISOString() };
+            state.drafts[draftId] = updated;
+            this.writeJson("inboxState", state);
+            return updated;
+        });
+    }
+    inboxTargetIsFresh(target) {
+        return this.withInboxLock(this.file("inbox"), () => {
+            const state = this.inboxState();
+            const targetState = state.targets[target] ?? { latest_received_seq: 0, model_seen_seq: 0 };
+            return targetState.latest_received_seq <= targetState.model_seen_seq;
+        });
+    }
+    withFreshnessGate(input, perform) {
+        const file = this.file("inbox");
+        const preflight = this.withInboxLock(file, () => {
+            const state = this.inboxState();
+            const rows = this.reconcileInboxRows(this.readNdjson("inbox"), state);
+            const pendingLatest = rows.filter((row) => row.target === input.target)
+                .reduce((latest, row) => validSequence(row.target_seq) ? Math.max(latest, row.target_seq) : latest, 0);
+            const target = state.targets[input.target] ?? { latest_received_seq: pendingLatest, model_seen_seq: 0 };
+            target.latest_received_seq = Math.max(target.latest_received_seq, pendingLatest);
+            state.targets[input.target] = target;
+            const draftFingerprint = crypto.createHash("sha256").update(JSON.stringify([input.target, input.argv])).digest("hex");
+            let commitDraft;
+            if (input.commitDraftId) {
+                if (!input.providerSucceeded)
+                    throw new Error("commitDraftId requires providerSucceeded");
+                const draft = state.drafts[input.commitDraftId];
+                if (!draft || (draft.status !== "held" && draft.status !== "sending") || draft.target !== input.target
+                    || JSON.stringify(draft.argv) !== JSON.stringify(input.argv)) {
+                    throw new Error(`held/sending draft 与 freshness intent 不匹配：${input.commitDraftId}`);
+                }
+                commitDraft = draft;
+                if (draft.status === "sending") {
+                    const intentId = draft.intent_id;
+                    const existingIntent = state.intents[intentId];
+                    state.intents[intentId] = existingIntent ?? {
+                        intent_id: intentId, target: input.target, argv: [...input.argv],
+                        latest_received_seq: draft.intent_model_seen_seq, model_seen_seq: draft.intent_model_seen_seq,
+                        committed_at: draft.sending_at, draft_id: draft.draft_id,
+                    };
+                    this.writeJson("inboxState", state);
+                    return { status: "ready", intentId, commitDraftId: draft.draft_id };
+                }
+            }
+            if (target.latest_received_seq > target.model_seen_seq) {
+                let draftId = commitDraft?.draft_id ?? `draft_${draftFingerprint.slice(0, 24)}`;
+                const at = new Date(input.now ?? Date.now()).toISOString();
+                let existing = state.drafts[draftId];
+                if (!commitDraft && existing && existing.status !== "held") {
+                    const boundaryFingerprint = crypto.createHash("sha256")
+                        .update(JSON.stringify([input.target, input.argv, target.latest_received_seq])).digest("hex");
+                    draftId = `draft_${boundaryFingerprint.slice(0, 24)}`;
+                    existing = state.drafts[draftId];
+                }
+                const draft = existing?.status === "held" ? {
+                    ...existing, held_at_seq: target.latest_received_seq, updated_at: at,
+                } : {
+                    draft_id: draftId, target: input.target, argv: [...input.argv], status: "held",
+                    held_at_seq: target.latest_received_seq, created_at: at, updated_at: at,
+                };
+                state.drafts[draftId] = draft;
+                this.writeJson("inboxState", state);
+                return { status: "held", target: input.target, latest_received_seq: target.latest_received_seq,
+                    model_seen_seq: target.model_seen_seq, draft };
+            }
+            const fingerprint = crypto.createHash("sha256")
+                .update(JSON.stringify([input.target, input.argv, target.model_seen_seq])).digest("hex");
+            const intentId = `larkin-${fingerprint.slice(0, 32)}`;
+            const commitDraftId = commitDraft?.draft_id;
+            const committedAt = new Date(input.now ?? Date.now()).toISOString();
+            if (commitDraft) {
+                state.drafts[commitDraft.draft_id] = {
+                    ...commitDraft, status: "sending", intent_id: intentId,
+                    intent_model_seen_seq: target.model_seen_seq, sending_at: committedAt, updated_at: committedAt,
+                };
+            }
+            const existingIntent = state.intents[intentId];
+            state.intents[intentId] = existingIntent ? {
+                ...existingIntent, ...(commitDraftId ? { draft_id: commitDraftId } : {}),
+            } : {
+                intent_id: intentId,
+                target: input.target,
+                argv: [...input.argv],
+                latest_received_seq: target.latest_received_seq,
+                model_seen_seq: target.model_seen_seq,
+                committed_at: committedAt,
+                ...(commitDraftId ? { draft_id: commitDraftId } : {}),
+            };
+            const intentIds = Object.keys(state.intents)
+                .sort((left, right) => state.intents[left].committed_at.localeCompare(state.intents[right].committed_at));
+            for (const stale of intentIds.slice(0, Math.max(0, intentIds.length - 2_048)))
+                delete state.intents[stale];
+            this.writeJson("inboxState", state);
+            return { status: "ready", intentId, commitDraftId };
+        });
+        if (preflight.status === "held")
+            return preflight;
+        // Provider/network work starts only after the durable intent commit has
+        // released the Inbox lock. That commit is the local receive boundary.
+        const finalizeDraft = (succeeded) => {
+            if (!preflight.commitDraftId)
+                return;
+            this.withInboxLock(file, () => {
+                const state = this.inboxState();
+                const draft = state.drafts[preflight.commitDraftId];
+                if (succeeded && draft?.status === "sent" && draft.intent_id === preflight.intentId)
+                    return;
+                if (!draft || draft.status !== "sending" || draft.intent_id !== preflight.intentId
+                    || draft.target !== input.target || JSON.stringify(draft.argv) !== JSON.stringify(input.argv)) {
+                    throw new Error(`held draft finalize 状态不一致：${preflight.commitDraftId}`);
+                }
+                const updatedAt = new Date(input.now ?? Date.now()).toISOString();
+                if (succeeded)
+                    state.drafts[draft.draft_id] = { ...draft, status: "sent", updated_at: updatedAt };
+                else {
+                    const latest = state.targets[draft.target]?.latest_received_seq ?? draft.held_at_seq;
+                    const { intent_id: _intentId, intent_model_seen_seq: _boundary, sending_at: _sendingAt, ...retryable } = draft;
+                    state.drafts[draft.draft_id] = {
+                        ...retryable, status: "held", held_at_seq: Math.max(draft.held_at_seq, latest), updated_at: updatedAt,
+                    };
+                }
+                this.writeJson("inboxState", state);
+            });
+        };
+        let result;
+        try {
+            result = perform(preflight.intentId);
+        }
+        catch (error) {
+            finalizeDraft(false);
+            throw error;
+        }
+        finalizeDraft(Boolean(input.providerSucceeded?.(result)));
+        return { status: "ready", target: input.target, intentId: preflight.intentId, result };
+    }
+    /**
+     * Legacy explicit clear operation. New Inbox consumers must use pollInbox so
+     * a concurrent cooperating append cannot be truncated.
+     */
+    clearNdjson(key) {
+        if (!NDJSON_KEYS.has(key))
+            throw new Error(`unknown NDJSON state key: ${key}`);
+        const file = this.file(key);
+        validateExistingPath(file, this.boundary);
+        const existing = lstatIfExists(file);
+        if (!existing)
+            return;
+        this.prepare(file);
+        const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW);
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+                throw new Error(`state path is not an owned regular file: ${file}`);
+            }
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.chmodSync(file, 0o600);
+    }
+}
+export function createAgentStateStore(root, agentId, dependencies = {}) {
+    return new AgentStateStore(TargetRootLayout.fromConfigDir(root), agentId, dependencies);
+}