larkin 0.5.2 → 0.5.4

package/dist/agent/missed-outbound-scan.cjs

@@ -33,29 +33,35 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_INBOX_AUDIT_TARGETS = exports.INBOX_AUDIT_LEGACY_MIGRATION_NON_GOAL = void 0;
+exports.MAX_INBOX_AUDIT_REGISTRY_ROWS = exports.MAX_INBOX_AUDIT_REGISTRY_BYTES = exports.MAX_INBOX_AUDIT_TARGETS = exports.INBOX_AUDIT_LEGACY_MIGRATION_NON_GOAL = void 0;
 exports.inboxAuditRegistryFile = inboxAuditRegistryFile;
+exports.inboxAuditRetryFile = inboxAuditRetryFile;
 exports.observeInboxAuditTarget = observeInboxAuditTarget;
+exports.enqueueInboxAuditTargetRetry = enqueueInboxAuditTargetRetry;
+exports.discardInboxAuditTargetRetry = discardInboxAuditTargetRetry;
+exports.reconcileInboxAuditTargetRetries = reconcileInboxAuditTargetRetries;
+exports.hasPendingInboxAuditTargets = hasPendingInboxAuditTargets;
 exports.readInboxAuditTargets = readInboxAuditTargets;
+exports.completeInboxAuditTarget = completeInboxAuditTarget;
+const crypto = __importStar(require("node:crypto"));
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-/**
- * #169's host-owned heartbeat no longer creates per-target missed-outbound loops.
- * Pre-v0.4.21 records have no unique ownership marker and can collide exactly
- * with user reminders, so existing indistinguishable loops are never migrated
- * or deleted automatically.
- */
+const process_state_js_1 = require("../platform/process-state.cjs");
+/** Historical reminder loops are deliberately unrelated to this bounded audit registry. */
 exports.INBOX_AUDIT_LEGACY_MIGRATION_NON_GOAL = "New versions no longer create missed-outbound loops; existing indistinguishable historical loops are not migrated or deleted automatically.";
-// Audits return every retained target. Storage remains bounded so a heartbeat
-// cannot accumulate an unbounded work list.
 exports.MAX_INBOX_AUDIT_TARGETS = 96;
 const MAX_STORED_TARGETS = exports.MAX_INBOX_AUDIT_TARGETS;
+exports.MAX_INBOX_AUDIT_REGISTRY_BYTES = 64 * 1024;
+exports.MAX_INBOX_AUDIT_REGISTRY_ROWS = exports.MAX_INBOX_AUDIT_TARGETS;
+const LOCK_WAIT_MS = 5_000;
+const LOCK_RETRY_MS = 25;
 const CHAT = /^oc_[A-Za-z0-9]+$/;
 const THREAD = /^omt_[A-Za-z0-9]+$/;
 const ANCHOR = /^om_[A-Za-z0-9_-]+$/;
-function inboxAuditRegistryFile(larkinHome) {
-    return path.join(larkinHome, "inbox-audit.json");
-}
+const GENERATION = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const OUTCOMES = new Set(["no-finding", "handled"]);
+function inboxAuditRegistryFile(larkinHome) { return path.join(larkinHome, "inbox-audit.json"); }
+function inboxAuditRetryFile(larkinHome) { return path.join(larkinHome, "inbox-audit-retry.json"); }
 function parseTarget(event) {
     const chatId = String(event.chat_id || "");
     const threadId = event.thread_id ? String(event.thread_id) : "";
@@ -64,70 +70,336 @@ function parseTarget(event) {
         return null;
     return { target: threadId ? `thread:${chatId}:${threadId}` : `chat:${chatId}`, anchor };
 }
+function emptyRegistry() { return { version: 4, targets: [] }; }
+function assertSafeExistingFile(file, label) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`${label} is not a regular file`);
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            throw new Error(`${label} is not owned by the current user`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function prepareRegistryDirectory(file) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("inbox audit registry directory is unsafe");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error("inbox audit registry directory is not owned by the current user");
+}
 function load(file) {
-    let value;
+    let fd;
+    let bytes;
     try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
+        assertSafeExistingFile(file, "inbox audit registry");
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error("inbox audit registry is not a regular file");
+        const buffer = Buffer.alloc(exports.MAX_INBOX_AUDIT_REGISTRY_BYTES + 1);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const read = fs.readSync(fd, buffer, offset, buffer.length - offset, offset);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        if (offset > exports.MAX_INBOX_AUDIT_REGISTRY_BYTES)
+            throw new Error("inbox audit registry exceeds the bounded byte limit");
+        bytes = buffer.subarray(0, offset);
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return { version: 1, targets: [] };
+            return emptyRegistry();
         throw error;
     }
-    if (value?.version !== 1 || !Array.isArray(value.targets))
-        return { version: 1, targets: [] };
-    return { version: 1, targets: value.targets.flatMap((row) => {
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+    const value = JSON.parse(bytes.toString("utf8"));
+    // v1 had no wake provenance; v2 had no durable observation generation.
+    // Neither can safely issue a completion receipt after this lifecycle upgrade.
+    if (value?.version !== 4 || !Array.isArray(value.targets))
+        return emptyRegistry();
+    if (value.targets.length > exports.MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        throw new Error("inbox audit registry exceeds the bounded row limit");
+    return { version: 4, targets: value.targets.flatMap((row) => {
             if (!row || typeof row !== "object")
                 return [];
             const candidate = row;
             if (typeof candidate.target !== "string" || typeof candidate.anchor !== "string")
                 return [];
+            const parts = candidate.target.split(":");
             const parsed = parseTarget({
-                chat_id: candidate.target.startsWith("chat:") ? candidate.target.slice(5) : candidate.target.split(":")[1],
-                thread_id: candidate.target.startsWith("thread:") ? candidate.target.split(":")[2] : null,
+                chat_id: candidate.target.startsWith("chat:") ? candidate.target.slice(5) : parts[1],
+                thread_id: candidate.target.startsWith("thread:") ? parts[2] : null,
                 message_id: candidate.anchor,
             });
-            return typeof candidate.agent_id === "string" && candidate.agent_id && parsed && candidate.target === parsed.target
-                && typeof candidate.observed_at === "string" && Number.isFinite(Date.parse(candidate.observed_at))
-                ? [{ agent_id: candidate.agent_id, ...parsed, observed_at: candidate.observed_at }] : [];
+            const status = candidate.status === "completed" ? "completed" : candidate.status === "pending" ? "pending" : null;
+            if (!status || typeof candidate.agent_id !== "string" || !candidate.agent_id || typeof candidate.generation !== "string" || !GENERATION.test(candidate.generation) || !parsed || candidate.target !== parsed.target
+                || !Number.isSafeInteger(candidate.source_seq) || Number(candidate.source_seq) < 1
+                || typeof candidate.observed_at !== "string" || !Number.isFinite(Date.parse(candidate.observed_at)))
+                return [];
+            const completed_at = typeof candidate.completed_at === "string" && Number.isFinite(Date.parse(candidate.completed_at)) ? candidate.completed_at : undefined;
+            const completed_anchor = typeof candidate.completed_anchor === "string" && ANCHOR.test(candidate.completed_anchor) ? candidate.completed_anchor : undefined;
+            const completed_outcome = OUTCOMES.has(String(candidate.completed_outcome)) ? candidate.completed_outcome : undefined;
+            return [{ agent_id: candidate.agent_id, generation: candidate.generation, ...parsed, source_seq: Number(candidate.source_seq), observed_at: candidate.observed_at, status,
+                    ...(completed_at ? { completed_at } : {}), ...(completed_anchor ? { completed_anchor } : {}),
+                    ...(completed_outcome ? { completed_outcome } : {}) }];
         }) };
 }
 function save(file, registry) {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
-    fs.writeFileSync(temporary, `${JSON.stringify(registry)}\n`, { mode: 0o600 });
-    fs.renameSync(temporary, file);
-    fs.chmodSync(file, 0o600);
+    if (registry.targets.length > exports.MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        throw new Error("inbox audit registry exceeds the bounded row limit");
+    const serialized = `${JSON.stringify(registry)}\n`;
+    if (Buffer.byteLength(serialized) > exports.MAX_INBOX_AUDIT_REGISTRY_BYTES)
+        throw new Error("inbox audit registry exceeds the bounded byte limit");
+    prepareRegistryDirectory(file);
+    assertSafeExistingFile(file, "inbox audit registry");
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    try {
+        fs.writeFileSync(fd, serialized);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function emptyRetryJournal() { return { version: 2, targets: [] }; }
+function loadRetryJournal(file) {
+    let value;
+    try {
+        assertSafeExistingFile(file, "inbox audit retry journal");
+        const stat = fs.statSync(file);
+        if (stat.size > exports.MAX_INBOX_AUDIT_REGISTRY_BYTES)
+            throw new Error("inbox audit retry journal exceeds the bounded byte limit");
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyRetryJournal();
+        throw error;
+    }
+    const raw = value;
+    if (raw.version !== 2 || !Array.isArray(raw.targets) || raw.targets.length > exports.MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        return emptyRetryJournal();
+    return { version: 2, targets: raw.targets.flatMap((candidate) => {
+            if (!candidate || typeof candidate !== "object")
+                return [];
+            const row = candidate;
+            const parsed = parseTarget({ chat_id: row.chat_id, thread_id: row.thread_id, message_id: row.anchor });
+            if (typeof row.agent_id !== "string" || !row.agent_id || typeof row.target !== "string" || !parsed || parsed.target !== row.target
+                || typeof row.chat_id !== "string" || (row.thread_id !== null && typeof row.thread_id !== "string")
+                || !Number.isSafeInteger(row.source_seq) || Number(row.source_seq) < 1
+                || typeof row.queued_at !== "string" || !Number.isFinite(Date.parse(row.queued_at)))
+                return [];
+            return [{ agent_id: row.agent_id, target: row.target, anchor: parsed.anchor, chat_id: row.chat_id, thread_id: row.thread_id ?? null, source_seq: Number(row.source_seq), queued_at: row.queued_at }];
+        }) };
+}
+function saveRetryJournal(file, journal) {
+    if (journal.targets.length > exports.MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        throw new Error("inbox audit retry journal exceeds the bounded row limit");
+    const serialized = `${JSON.stringify(journal)}\n`;
+    if (Buffer.byteLength(serialized) > exports.MAX_INBOX_AUDIT_REGISTRY_BYTES)
+        throw new Error("inbox audit retry journal exceeds the bounded byte limit");
+    prepareRegistryDirectory(file);
+    assertSafeExistingFile(file, "inbox audit retry journal");
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    try {
+        fs.writeFileSync(fd, serialized);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function sleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+/** Serialize Host observers and CLI completion without replacing a newer registry snapshot. */
+function withAuditLock(file, operation) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    const lockFile = `${file}.mutation-lock`;
+    prepareRegistryDirectory(file);
+    while (Date.now() <= deadline) {
+        let lock;
+        try {
+            assertSafeExistingFile(lockFile, "inbox audit mutation lock");
+            lock = (0, process_state_js_1.acquireProcessLock)(lockFile, path.basename(process.execPath), { malformedGraceMs: 1_000 });
+            return operation();
+        }
+        catch (error) {
+            if (lock || !/lock 已被|无法取得 lock|正在创建|暂不能接管|并发重试耗尽/.test(error instanceof Error ? error.message : String(error)))
+                throw error;
+            sleep(LOCK_RETRY_MS);
+        }
+        finally {
+            lock?.release();
+        }
+    }
+    throw new Error("inbox audit registry busy: bounded lock contention");
+}
+function mutate(file, operation) {
+    return withAuditLock(file, () => {
+        const registry = load(file);
+        const result = operation(registry);
+        save(file, registry);
+        return result;
+    });
+}
+function mutateRetryJournal(file, operation) {
+    return withAuditLock(file, () => {
+        const journal = loadRetryJournal(file);
+        const result = operation(journal);
+        saveRetryJournal(file, journal);
+        return result;
+    });
+}
+function revision(row) {
+    return `sha256:${crypto.createHash("sha256").update(JSON.stringify({
+        v: 2, agent_id: row.agent_id, target: row.target, anchor: row.anchor, generation: row.generation, status: row.status,
+    })).digest("hex")}`;
+}
+function receipt(row) {
+    const payload = { v: 1, agent_id: row.agent_id, target: row.target, anchor: row.anchor, revision: revision(row) };
+    return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function parseReceipt(value) {
+    try {
+        const raw = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        if (raw.v !== 1 || typeof raw.agent_id !== "string" || !raw.agent_id || typeof raw.target !== "string" || typeof raw.anchor !== "string"
+            || typeof raw.revision !== "string" || !raw.revision.startsWith("sha256:"))
+            return null;
+        const parts = raw.target.split(":");
+        const parsed = parseTarget({ chat_id: raw.target.startsWith("chat:") ? raw.target.slice(5) : parts[1], thread_id: raw.target.startsWith("thread:") ? parts[2] : null, message_id: raw.anchor });
+        return parsed?.target === raw.target ? raw : null;
+    }
+    catch {
+        return null;
+    }
 }
-/** Record only an authoritative human group/topic source; DMs and bots are ignored. */
 function observeInboxAuditTarget(file, agentId, event, now = new Date()) {
-    if (event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
+    if (event.wake !== true || event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
         return false;
     const parsed = parseTarget(event);
-    if (!parsed)
+    const sourceSeq = typeof event.source_seq === "number" ? event.source_seq : Number.NaN;
+    if (!parsed || !Number.isSafeInteger(sourceSeq) || sourceSeq < 1)
+        return false;
+    return mutate(file, (registry) => {
+        const existing = registry.targets.find((row) => row.agent_id === agentId && row.target === parsed.target);
+        if (existing && sourceSeq <= existing.source_seq)
+            return false;
+        registry.targets = registry.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
+        registry.targets.unshift({ agent_id: agentId, generation: crypto.randomUUID(), ...parsed, source_seq: sourceSeq, observed_at: now.toISOString(), status: "pending" });
+        registry.targets = registry.targets.slice(0, MAX_STORED_TARGETS);
+        return true;
+    });
+}
+/** Durable recovery intent, recorded only after the same original wake gate. */
+function enqueueInboxAuditTargetRetry(file, agentId, event, now = new Date()) {
+    if (event.wake !== true || event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
         return false;
-    const registry = load(file);
-    const observed_at = now.toISOString();
-    registry.targets = registry.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
-    registry.targets.unshift({ agent_id: agentId, ...parsed, observed_at });
-    registry.targets = registry.targets.slice(0, MAX_STORED_TARGETS);
-    save(file, registry);
-    return true;
-}
-function instruction(target) {
-    const history = target.target.startsWith("thread:")
-        ? "Use larkin im +threads-messages-list for this exact thread."
-        : "Use larkin im +chat-messages-list for this exact chat.";
-    return `${history} If a real missed outbound finding requires a response, use the existing guarded larkin im reply path anchored at ${target.anchor}; otherwise stay silent.`;
-}
-/** Content-free, bounded audit work list consumed by the Agent CLI. */
+    const parsed = parseTarget(event);
+    const sourceSeq = typeof event.source_seq === "number" ? event.source_seq : Number.NaN;
+    if (!parsed || !Number.isSafeInteger(sourceSeq) || sourceSeq < 1)
+        return false;
+    return mutateRetryJournal(file, (journal) => {
+        const existing = journal.targets.find((row) => row.agent_id === agentId && row.target === parsed.target);
+        if (existing && sourceSeq <= existing.source_seq)
+            return false;
+        journal.targets = journal.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
+        journal.targets.unshift({ agent_id: agentId, ...parsed, source_seq: sourceSeq, chat_id: String(event.chat_id), thread_id: event.thread_id ? String(event.thread_id) : null, queued_at: now.toISOString() });
+        journal.targets = journal.targets.slice(0, MAX_STORED_TARGETS);
+        return true;
+    });
+}
+/** Remove only the exact recovered/newer target so a late retry cannot erase a new anchor. */
+function discardInboxAuditTargetRetry(file, agentId, event) {
+    const parsed = parseTarget(event);
+    if (!parsed)
+        return;
+    mutateRetryJournal(file, (journal) => { journal.targets = journal.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target || row.source_seq > Number(event.source_seq ?? 0)); });
+}
+/** Replay persisted, already-authorized observer intents. Failures remain durable for a later bounded retry/startup. */
+function reconcileInboxAuditTargetRetries(registryFile, retryFile, agentId) {
+    const rows = loadRetryJournal(retryFile).targets.filter((row) => !agentId || row.agent_id === agentId);
+    let recovered = 0;
+    for (const row of rows) {
+        try {
+            observeInboxAuditTarget(registryFile, row.agent_id, { chat_id: row.chat_id, chat_type: "group", thread_id: row.thread_id, message_id: row.anchor, source_seq: row.source_seq, wake: true, _sender_is_bot: false, _scan_authority: true });
+            discardInboxAuditTargetRetry(retryFile, row.agent_id, { chat_id: row.chat_id, thread_id: row.thread_id, message_id: row.anchor, source_seq: row.source_seq });
+            recovered += 1;
+        }
+        catch {
+            break;
+        }
+    }
+    return { recovered, remaining: loadRetryJournal(retryFile).targets.filter((row) => !agentId || row.agent_id === agentId).length };
+}
+function instruction(target, receiptValue) {
+    const history = target.target.startsWith("thread:") ? "Use larkin im +threads-messages-list for this exact thread." : "Use larkin im +chat-messages-list for this exact chat.";
+    return `${history} Inspect first. When finished, run larkin inbox audit complete --receipt ${receiptValue} --outcome <no-finding|handled> --json. If a real finding needs a response, use the guarded reply path anchored at ${target.anchor}; otherwise stay silent.`;
+}
+function pendingRows(file, agentId) {
+    return load(file).targets.filter((row) => row.agent_id === agentId && row.status === "pending").sort((left, right) => right.observed_at.localeCompare(left.observed_at));
+}
+function hasPendingInboxAuditTargets(file, agentId) { return pendingRows(file, agentId).length > 0; }
+/** Public read is intentionally completion-free: a caller crash leaves the target pending. */
 function readInboxAuditTargets(file, agentId) {
-    const rows = load(file).targets.filter((row) => row.agent_id === agentId)
-        .sort((left, right) => right.observed_at.localeCompare(left.observed_at));
-    return {
-        version: 1,
-        targets: rows.slice(0, exports.MAX_INBOX_AUDIT_TARGETS).map(({ agent_id: _agentId, ...target }) => ({ ...target, instruction: instruction(target) })),
-        has_more: rows.length > exports.MAX_INBOX_AUDIT_TARGETS,
-        no_finding: "stay_silent",
-    };
+    const rows = pendingRows(file, agentId);
+    return { version: 4, targets: rows.slice(0, exports.MAX_INBOX_AUDIT_TARGETS).map((row) => {
+            const target = { target: row.target, anchor: row.anchor, observed_at: row.observed_at, source_seq: row.source_seq };
+            const receiptValue = receipt(row);
+            return { ...target, revision: revision(row), receipt: receiptValue, instruction: instruction(target, receiptValue) };
+        }), has_more: rows.length > exports.MAX_INBOX_AUDIT_TARGETS, no_finding: "stay_silent" };
+}
+function completeInboxAuditTarget(file, agentId, receiptValue, outcome, now = new Date()) {
+    if (!OUTCOMES.has(outcome))
+        return { completed: false, reason: "invalid_outcome" };
+    const decoded = parseReceipt(receiptValue);
+    if (!decoded || decoded.agent_id !== agentId)
+        return { completed: false, reason: "invalid_receipt" };
+    return mutate(file, (registry) => {
+        const row = registry.targets.find((candidate) => candidate.agent_id === decoded.agent_id && candidate.target === decoded.target);
+        if (!row || row.anchor !== decoded.anchor)
+            return { completed: false, reason: "stale" };
+        if (row.status === "completed")
+            return { completed: false, reason: "already_completed" };
+        if (revision(row) !== decoded.revision)
+            return { completed: false, reason: "stale" };
+        row.status = "completed";
+        row.completed_at = now.toISOString();
+        row.completed_anchor = row.anchor;
+        row.completed_outcome = outcome;
+        return { completed: true, reason: "completed" };
+    });
 }