larkin 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.4
+
+Inbox Audit is now optional and off by default. The Dashboard and CLI support global and per-Agent switches and inspection gaps. Saving a gap updates scheduling without replacing Runtime sessions; editing a gap alone does not enable auditing. Only originally wake-eligible human group/topic work is audited.
+
+Audit reads no longer mark work complete. Agents explicitly confirm a receipt after checking; receipts are scoped to an observation generation, and durable canonical sequence ordering protects newer work from stale completion or deferred registration. Contended registrations are retried durably. Unproven legacy audit-index rows are ignored while ordinary Inbox and conversation history remain intact.
+
+## 0.5.3
+
+External Pi initialization now runs with bounded concurrency and recovers from isolated startup-probe timeouts through the existing retry policy. Shutdown waits for pending initialization and closes late sessions. Generic Runtime and delivery failures show unavailable instead of incompatible, while explicit prerequisite failures and useful provider diagnostics are preserved. Recovery workflow tests wait for delivery consumption and Inbox watermarks to converge and isolate temporary state.
+
 ## 0.5.2
 
 External pi now runs with the user's own Pi home; compaction settings move to the Agent workspace's `.pi/settings.json`; 0.5.0/0.5.1 started external pi with an empty agent dir and saw no logins. Stock pi 0.84.x does not emit `get_state.compactionCapabilities` (that handshake only existed for the bundled build); Larkin accepts the absence and keeps native compaction via the workspace settings file, while a present handshake must still match exactly.

package/README.md

@@ -93,6 +93,21 @@ During setup, choose one of the three externally installed runtimes: Pi (`pi`),
 
 `larkin setup --model <id>` optionally stores a catalog model for that runtime. After setup, use `larkin model` and `larkin runtime` to inspect or switch. For Pi, Larkin talks to your installed `pi --mode rpc`, verifies the RPC handshake and compaction capability contract, and injects its supported extensions through `pi -e` (background subagents and the 60-second foreground bash timeout guard).
 
+### Optional Inbox Audit
+
+Inbox Audit is **off by default**. In the Dashboard, use **Global settings → Inbox 巡检** to configure the switch and inspection gap, or the selected Agent's **Configuration → Inbox 巡检** to override either value. The gap defaults to 15 minutes and supports 1 minute to 24 hours. Saving a gap alone keeps auditing disabled; saved settings survive restart and update later scheduling without replacing the Agent Runtime session.
+
+The same settings are available through the CLI:
+
+```bash
+larkin config inbox-audit global on --interval 15m
+larkin config inbox-audit agent off --agent <App-ID>
+larkin config inbox-audit agent inherit --agent <App-ID> --interval inherit
+larkin config inbox-audit global off
+```
+
+When enabled, audit only revisits originally wake-eligible human group/topic work and does not wake a model for an empty work list. Reading an audit list does not complete it: the managed Agent follows the returned inspection instructions and explicitly confirms the receipt after checking. A failed check remains retryable; newer messages cannot be completed by an older receipt. Old audit-index records without proven eligibility or observation identity are ignored; ordinary Inbox messages and conversation history are preserved.
+
 <details>
 <summary>Windows support and optional autostart</summary>
 

package/dist/agent/agent-cli-capabilities.cjs

@@ -32,7 +32,7 @@ function agentCliPromptCapabilities(executable = "larkin") {
     const commands = Object.entries(exports.AGENT_CLI_CAPABILITIES.commands).flatMap(([group, operations]) => operations.map((operation) => ({
         command: `${group} ${operation}`,
         purpose: group === "inbox" ? (operation === "check" ? "Read pending target summaries without consuming messages."
-            : operation === "audit" ? "Read bounded observed group/topic audit targets and instructions."
+            : operation === "audit" ? "Read bounded observed group/topic audit targets; inspect first, then explicitly confirm the returned receipt."
                 : "Poll full messages and direct-ack the returned batch.") :
             group === "comment" ? "Reply once to the exact cloud-document comment bound by a polled Inbox message id." :
                 group === "reminder" ? "Manage this Agent's durable reminders." :

package/dist/agent/agent-cli-capabilities.mjs

@@ -24,7 +24,7 @@ export function agentCliPromptCapabilities(executable = "larkin") {
     const commands = Object.entries(AGENT_CLI_CAPABILITIES.commands).flatMap(([group, operations]) => operations.map((operation) => ({
         command: `${group} ${operation}`,
         purpose: group === "inbox" ? (operation === "check" ? "Read pending target summaries without consuming messages."
-            : operation === "audit" ? "Read bounded observed group/topic audit targets and instructions."
+            : operation === "audit" ? "Read bounded observed group/topic audit targets; inspect first, then explicitly confirm the returned receipt."
                 : "Poll full messages and direct-ack the returned batch.") :
             group === "comment" ? "Reply once to the exact cloud-document comment bound by a polled Inbox message id." :
                 group === "reminder" ? "Manage this Agent's durable reminders." :

package/dist/agent/config-cli-contract.cjs

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONFIG_CLI_VALUES = exports.CONFIG_CLI_USAGE = exports.CONFIG_CLI_OPERATIONS = void 0;
-exports.CONFIG_CLI_OPERATIONS = Object.freeze(["show", "runtime", "model", "effort", "mention", "apply"]);
+exports.CONFIG_CLI_OPERATIONS = Object.freeze(["show", "runtime", "model", "effort", "mention", "inbox-audit", "apply"]);
 exports.CONFIG_CLI_USAGE = Object.freeze([
     "larkin config show [--agent <App ID>] [--chat <oc_id>] [--json]",
     "larkin config runtime <runtime> [--model <model>] [--agent <App ID>]",
@@ -10,6 +10,8 @@ exports.CONFIG_CLI_USAGE = Object.freeze([
     "larkin config mention global <require|free>",
     "larkin config mention agent <inherit|require|free> [--agent <App ID>]",
     "larkin config mention chat <oc_id> <inherit|require|free> [--agent <App ID>]",
+    "larkin config inbox-audit global <on|off> [--interval <15m|1h>]",
+    "larkin config inbox-audit agent <inherit|on|off> [--agent <App ID>] [--interval <15m|inherit>]",
     "larkin config apply [--agent <App ID>]",
 ]);
 exports.CONFIG_CLI_VALUES = Object.freeze({

package/dist/agent/config-cli-contract.mjs

@@ -1,4 +1,4 @@
-export const CONFIG_CLI_OPERATIONS = Object.freeze(["show", "runtime", "model", "effort", "mention", "apply"]);
+export const CONFIG_CLI_OPERATIONS = Object.freeze(["show", "runtime", "model", "effort", "mention", "inbox-audit", "apply"]);
 export const CONFIG_CLI_USAGE = Object.freeze([
     "larkin config show [--agent <App ID>] [--chat <oc_id>] [--json]",
     "larkin config runtime <runtime> [--model <model>] [--agent <App ID>]",
@@ -7,6 +7,8 @@ export const CONFIG_CLI_USAGE = Object.freeze([
     "larkin config mention global <require|free>",
     "larkin config mention agent <inherit|require|free> [--agent <App ID>]",
     "larkin config mention chat <oc_id> <inherit|require|free> [--agent <App ID>]",
+    "larkin config inbox-audit global <on|off> [--interval <15m|1h>]",
+    "larkin config inbox-audit agent <inherit|on|off> [--agent <App ID>] [--interval <15m|inherit>]",
     "larkin config apply [--agent <App ID>]",
 ]);
 export const CONFIG_CLI_VALUES = Object.freeze({

package/dist/agent/inbox-audit-heartbeat.cjs

@@ -1,62 +1,182 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InboxAuditHeartbeat = exports.INBOX_AUDIT_CADENCE_MS = void 0;
+exports.InboxAuditHeartbeat = exports.MAX_INBOX_AUDIT_DIAGNOSTIC_CHARS = exports.INBOX_AUDIT_CADENCE_MS = void 0;
+exports.boundedInboxAuditDiagnostic = boundedInboxAuditDiagnostic;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const inbox_projection_js_1 = require("./inbox-projection.cjs");
 exports.INBOX_AUDIT_CADENCE_MS = 15 * 60_000;
-/** One Host-owned timer fans a targetless internal wake to each active Agent. */
+exports.MAX_INBOX_AUDIT_DIAGNOSTIC_CHARS = 120;
+function boundedInboxAuditDiagnostic(error) {
+    const max = exports.MAX_INBOX_AUDIT_DIAGNOSTIC_CHARS;
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code.slice(0, max) : "";
+    const raw = error instanceof Error ? error.message : String(error);
+    const text = String(raw).slice(0, max).replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+    return [code, text].filter(Boolean).join(" ").slice(0, max);
+}
+function safeIntervalMs(intervalMs) {
+    if (!Number.isSafeInteger(intervalMs) || intervalMs < 1)
+        throw new Error("inbox audit cadence must be a positive integer");
+    return intervalMs;
+}
+/** A Host-owned, config-file-reactive single timer per enabled Agent. */
 class InboxAuditHeartbeat {
     options;
-    timer = null;
+    timers = new Map();
+    generations = new Map();
     running = false;
     sequence = 0;
-    cadenceMs;
+    watcher = null;
+    refreshTimer = null;
     constructor(options) {
         this.options = options;
-        this.cadenceMs = options.cadenceMs ?? exports.INBOX_AUDIT_CADENCE_MS;
-        if (!Number.isSafeInteger(this.cadenceMs) || this.cadenceMs < 1)
-            throw new Error("inbox audit cadence must be a positive integer");
+        for (const agent of options.agents)
+            safeIntervalMs(options.schedule(agent).intervalMs);
     }
     start() {
         if (this.running)
             return;
         this.running = true;
-        this.schedule();
+        for (const agent of this.options.agents)
+            this.reschedule(agent);
+        this.watchConfig();
     }
     stop() {
         this.running = false;
-        if (this.timer)
-            (this.options.clearTimer ?? clearTimeout)(this.timer);
-        this.timer = null;
+        const clearTimer = this.options.clearTimer ?? clearTimeout;
+        for (const timer of this.timers.values())
+            clearTimer(timer);
+        this.timers.clear();
+        if (this.refreshTimer)
+            clearTimer(this.refreshTimer);
+        this.refreshTimer = null;
+        this.watcher?.close();
+        this.watcher = null;
+    }
+    /** Safe for a Host config watcher or a direct in-process config mutation hook. */
+    refresh() {
+        if (!this.running)
+            return;
+        for (const agent of this.options.agents)
+            this.reschedule(agent);
     }
-    schedule() {
-        if (!this.running || this.timer)
+    watchConfig() {
+        if (!this.options.configFile || this.watcher)
             return;
-        this.timer = (this.options.setTimer ?? setTimeout)(() => {
-            this.timer = null;
-            return this.fire().finally(() => { if (this.running)
-                this.schedule(); });
-        }, this.cadenceMs);
-        this.timer.unref?.();
+        const file = path.resolve(this.options.configFile);
+        const parent = path.dirname(file);
+        const basename = path.basename(file);
+        try {
+            this.watcher = (this.options.watch ?? fs.watch)(parent, (_event, changed) => {
+                if (changed && String(changed) !== basename)
+                    return;
+                this.scheduleRefresh();
+            });
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit config watch failed: ${boundedInboxAuditDiagnostic(error)}`);
+        }
     }
-    async fire() {
+    scheduleRefresh() {
+        if (!this.running || this.refreshTimer)
+            return;
+        this.refreshTimer = (this.options.setTimer ?? setTimeout)(() => {
+            this.refreshTimer = null;
+            this.refresh();
+        }, 30);
+        this.refreshTimer.unref?.();
+    }
+    reschedule(agent) {
+        const clearTimer = this.options.clearTimer ?? clearTimeout;
+        const prior = this.timers.get(agent.agentId);
+        if (prior)
+            clearTimer(prior);
+        this.timers.delete(agent.agentId);
+        const generation = (this.generations.get(agent.agentId) ?? 0) + 1;
+        this.generations.set(agent.agentId, generation);
+        let schedule;
+        try {
+            schedule = this.options.schedule(agent);
+            safeIntervalMs(schedule.intervalMs);
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit schedule failed agent=${agent.agentId}: ${boundedInboxAuditDiagnostic(error)}`);
+            return;
+        }
+        // Disabled means no future audit timer or model wake at all.
+        if (!schedule.enabled || !this.running)
+            return;
+        let timer;
+        timer = (this.options.setTimer ?? setTimeout)(() => {
+            // A cancelled callback can still be queued. It must not remove the
+            // replacement timer installed by a newer config revision.
+            if (this.timers.get(agent.agentId) === timer)
+                this.timers.delete(agent.agentId);
+            void this.fire(agent, generation).finally(() => {
+                if (this.running && this.generations.get(agent.agentId) === generation)
+                    this.reschedule(agent);
+            });
+        }, schedule.intervalMs);
+        timer.unref?.();
+        this.timers.set(agent.agentId, timer);
+    }
+    async fire(agent, generation) {
+        if (this.generations.get(agent.agentId) !== generation)
+            return;
+        try {
+            const schedule = this.options.schedule(agent);
+            if (!schedule.enabled || !this.options.shouldDispatch(agent))
+                return;
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit schedule failed agent=${agent.agentId}: ${boundedInboxAuditDiagnostic(error)}`);
+            return;
+        }
         const now = this.options.now ?? Date.now;
-        for (const agent of this.options.agents) {
-            const message_id = `rem_inbox_audit_${now()}_${++this.sequence}_${agent.agentId}`;
-            const envelope = {
-                kind: "reminder",
-                message_id,
-                target: inbox_projection_js_1.RUNTIME_REMINDER_TARGET,
-                wake: true,
-                content: "Internal inbox audit wake. Poll runtime:reminder, then run larkin inbox audit --json. No finding stays silent.",
-            };
-            try {
-                const appended = this.options.stateStore(agent).appendCanonicalInboxOnce(envelope);
-                if (appended.status === "appended")
-                    await this.options.runtimeHost.deliver(agent.agentId, appended.envelope);
-            }
-            catch (error) {
-                this.options.log?.(`inbox audit heartbeat failed agent=${agent.agentId}: ${error instanceof Error ? error.message : String(error)}`);
-            }
+        const message_id = `rem_inbox_audit_${now()}_${++this.sequence}_${agent.agentId}`;
+        const envelope = { kind: "reminder", message_id, target: inbox_projection_js_1.RUNTIME_REMINDER_TARGET, wake: true,
+            content: "Internal inbox audit wake. Poll runtime:reminder, then run larkin inbox audit --json. Inspect first and explicitly complete its receipt; no finding stays silent." };
+        try {
+            const appended = this.options.stateStore(agent).appendCanonicalInboxOnce(envelope);
+            if (appended.status === "appended")
+                await this.options.runtimeHost.deliver(agent.agentId, appended.envelope);
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit heartbeat failed agent=${agent.agentId}: ${boundedInboxAuditDiagnostic(error)}`);
         }
     }
 }

package/dist/agent/inbox-audit-heartbeat.mjs

@@ -1,59 +1,145 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { RUNTIME_REMINDER_TARGET } from "./inbox-projection.mjs";
 export const INBOX_AUDIT_CADENCE_MS = 15 * 60_000;
-/** One Host-owned timer fans a targetless internal wake to each active Agent. */
+export const MAX_INBOX_AUDIT_DIAGNOSTIC_CHARS = 120;
+export function boundedInboxAuditDiagnostic(error) {
+    const max = MAX_INBOX_AUDIT_DIAGNOSTIC_CHARS;
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code.slice(0, max) : "";
+    const raw = error instanceof Error ? error.message : String(error);
+    const text = String(raw).slice(0, max).replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+    return [code, text].filter(Boolean).join(" ").slice(0, max);
+}
+function safeIntervalMs(intervalMs) {
+    if (!Number.isSafeInteger(intervalMs) || intervalMs < 1)
+        throw new Error("inbox audit cadence must be a positive integer");
+    return intervalMs;
+}
+/** A Host-owned, config-file-reactive single timer per enabled Agent. */
 export class InboxAuditHeartbeat {
     options;
-    timer = null;
+    timers = new Map();
+    generations = new Map();
     running = false;
     sequence = 0;
-    cadenceMs;
+    watcher = null;
+    refreshTimer = null;
     constructor(options) {
         this.options = options;
-        this.cadenceMs = options.cadenceMs ?? INBOX_AUDIT_CADENCE_MS;
-        if (!Number.isSafeInteger(this.cadenceMs) || this.cadenceMs < 1)
-            throw new Error("inbox audit cadence must be a positive integer");
+        for (const agent of options.agents)
+            safeIntervalMs(options.schedule(agent).intervalMs);
     }
     start() {
         if (this.running)
             return;
         this.running = true;
-        this.schedule();
+        for (const agent of this.options.agents)
+            this.reschedule(agent);
+        this.watchConfig();
     }
     stop() {
         this.running = false;
-        if (this.timer)
-            (this.options.clearTimer ?? clearTimeout)(this.timer);
-        this.timer = null;
+        const clearTimer = this.options.clearTimer ?? clearTimeout;
+        for (const timer of this.timers.values())
+            clearTimer(timer);
+        this.timers.clear();
+        if (this.refreshTimer)
+            clearTimer(this.refreshTimer);
+        this.refreshTimer = null;
+        this.watcher?.close();
+        this.watcher = null;
+    }
+    /** Safe for a Host config watcher or a direct in-process config mutation hook. */
+    refresh() {
+        if (!this.running)
+            return;
+        for (const agent of this.options.agents)
+            this.reschedule(agent);
+    }
+    watchConfig() {
+        if (!this.options.configFile || this.watcher)
+            return;
+        const file = path.resolve(this.options.configFile);
+        const parent = path.dirname(file);
+        const basename = path.basename(file);
+        try {
+            this.watcher = (this.options.watch ?? fs.watch)(parent, (_event, changed) => {
+                if (changed && String(changed) !== basename)
+                    return;
+                this.scheduleRefresh();
+            });
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit config watch failed: ${boundedInboxAuditDiagnostic(error)}`);
+        }
+    }
+    scheduleRefresh() {
+        if (!this.running || this.refreshTimer)
+            return;
+        this.refreshTimer = (this.options.setTimer ?? setTimeout)(() => {
+            this.refreshTimer = null;
+            this.refresh();
+        }, 30);
+        this.refreshTimer.unref?.();
     }
-    schedule() {
-        if (!this.running || this.timer)
+    reschedule(agent) {
+        const clearTimer = this.options.clearTimer ?? clearTimeout;
+        const prior = this.timers.get(agent.agentId);
+        if (prior)
+            clearTimer(prior);
+        this.timers.delete(agent.agentId);
+        const generation = (this.generations.get(agent.agentId) ?? 0) + 1;
+        this.generations.set(agent.agentId, generation);
+        let schedule;
+        try {
+            schedule = this.options.schedule(agent);
+            safeIntervalMs(schedule.intervalMs);
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit schedule failed agent=${agent.agentId}: ${boundedInboxAuditDiagnostic(error)}`);
             return;
-        this.timer = (this.options.setTimer ?? setTimeout)(() => {
-            this.timer = null;
-            return this.fire().finally(() => { if (this.running)
-                this.schedule(); });
-        }, this.cadenceMs);
-        this.timer.unref?.();
+        }
+        // Disabled means no future audit timer or model wake at all.
+        if (!schedule.enabled || !this.running)
+            return;
+        let timer;
+        timer = (this.options.setTimer ?? setTimeout)(() => {
+            // A cancelled callback can still be queued. It must not remove the
+            // replacement timer installed by a newer config revision.
+            if (this.timers.get(agent.agentId) === timer)
+                this.timers.delete(agent.agentId);
+            void this.fire(agent, generation).finally(() => {
+                if (this.running && this.generations.get(agent.agentId) === generation)
+                    this.reschedule(agent);
+            });
+        }, schedule.intervalMs);
+        timer.unref?.();
+        this.timers.set(agent.agentId, timer);
     }
-    async fire() {
+    async fire(agent, generation) {
+        if (this.generations.get(agent.agentId) !== generation)
+            return;
+        try {
+            const schedule = this.options.schedule(agent);
+            if (!schedule.enabled || !this.options.shouldDispatch(agent))
+                return;
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit schedule failed agent=${agent.agentId}: ${boundedInboxAuditDiagnostic(error)}`);
+            return;
+        }
         const now = this.options.now ?? Date.now;
-        for (const agent of this.options.agents) {
-            const message_id = `rem_inbox_audit_${now()}_${++this.sequence}_${agent.agentId}`;
-            const envelope = {
-                kind: "reminder",
-                message_id,
-                target: RUNTIME_REMINDER_TARGET,
-                wake: true,
-                content: "Internal inbox audit wake. Poll runtime:reminder, then run larkin inbox audit --json. No finding stays silent.",
-            };
-            try {
-                const appended = this.options.stateStore(agent).appendCanonicalInboxOnce(envelope);
-                if (appended.status === "appended")
-                    await this.options.runtimeHost.deliver(agent.agentId, appended.envelope);
-            }
-            catch (error) {
-                this.options.log?.(`inbox audit heartbeat failed agent=${agent.agentId}: ${error instanceof Error ? error.message : String(error)}`);
-            }
+        const message_id = `rem_inbox_audit_${now()}_${++this.sequence}_${agent.agentId}`;
+        const envelope = { kind: "reminder", message_id, target: RUNTIME_REMINDER_TARGET, wake: true,
+            content: "Internal inbox audit wake. Poll runtime:reminder, then run larkin inbox audit --json. Inspect first and explicitly complete its receipt; no finding stays silent." };
+        try {
+            const appended = this.options.stateStore(agent).appendCanonicalInboxOnce(envelope);
+            if (appended.status === "appended")
+                await this.options.runtimeHost.deliver(agent.agentId, appended.envelope);
+        }
+        catch (error) {
+            this.options.log?.(`inbox audit heartbeat failed agent=${agent.agentId}: ${boundedInboxAuditDiagnostic(error)}`);
         }
     }
 }