larkin 0.2.70

package/dist/feishu/im-freshness-adapter.mjs

@@ -0,0 +1,89 @@
+function integerMillis(value) {
+    if (typeof value !== "string" || !/^[0-9]+$/.test(value))
+        return null;
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return null;
+    }
+}
+export function messageRevisionTime(message) {
+    const created = integerMillis(message.create_time);
+    const updated = message.update_time === undefined || message.update_time === "" ? created : integerMillis(message.update_time);
+    if (created === null || updated === null)
+        throw new Error(`malformed Feishu IM revision for ${message.message_id || "unknown message"}`);
+    return created > updated ? created : updated;
+}
+export function feishuImTarget(value) {
+    const thread = /^thread:([^:]+):(.+)$/.exec(value);
+    if (thread)
+        return { provider: "feishu.im", resourceKind: "thread", resourceId: `${thread[1]}/${thread[2]}` };
+    const chat = /^chat:(.+)$/.exec(value);
+    if (chat)
+        return { provider: "feishu.im", resourceKind: "chat", resourceId: chat[1] };
+    throw new Error(`unsupported Feishu IM freshness target: ${value}`);
+}
+export function serializeFeishuImTarget(target) {
+    return `${target.provider}/${target.resourceKind}/${target.resourceId}`;
+}
+function normalizedMessages(snapshot) {
+    if (!snapshot || !Array.isArray(snapshot.messages))
+        throw new Error("malformed Feishu IM history payload: messages must be an array");
+    return snapshot.messages.map((message) => {
+        if (!message || typeof message !== "object" || typeof message.message_id !== "string" || !message.message_id) {
+            throw new Error("malformed Feishu IM history payload: message_id is required");
+        }
+        return { ...message, revision: messageRevisionTime(message) };
+    });
+}
+export const feishuImFreshnessAdapter = {
+    cursor(snapshot) {
+        const messages = normalizedMessages(snapshot);
+        if (!messages.length)
+            return null;
+        const revision = messages.reduce((maximum, message) => message.revision > maximum ? message.revision : maximum, 0n);
+        return {
+            schema: 1,
+            revisionTime: revision.toString(),
+            messageIds: [...new Set(messages.filter((message) => message.revision === revision).map((message) => message.message_id))].sort(),
+        };
+    },
+    compare(seen, current) {
+        if (!current)
+            return seen ? "gap" : "fresh";
+        if (!seen)
+            return "conflict";
+        const seenTime = integerMillis(seen.revisionTime);
+        const currentTime = integerMillis(current.revisionTime);
+        if (seen.schema !== 1 || seenTime === null || currentTime === null)
+            return "gap";
+        if (currentTime < seenTime)
+            return "gap";
+        if (currentTime > seenTime)
+            return "conflict";
+        return current.messageIds.every((id) => seen.messageIds.includes(id)) ? "fresh" : "conflict";
+    },
+    unseen(seen, snapshot) {
+        const messages = normalizedMessages(snapshot);
+        if (!seen)
+            return messages.map(({ revision: _revision, ...message }) => message);
+        const seenTime = integerMillis(seen.revisionTime);
+        if (seenTime === null)
+            return messages.map(({ revision: _revision, ...message }) => message);
+        return messages.filter((message) => message.revision > seenTime
+            || (message.revision === seenTime && !seen.messageIds.includes(message.message_id)))
+            .map(({ revision: _revision, ...message }) => message);
+    },
+};
+export function mergeFeishuImCursor(left, right) {
+    if (!left)
+        return { ...right, messageIds: [...right.messageIds] };
+    const leftTime = BigInt(left.revisionTime);
+    const rightTime = BigInt(right.revisionTime);
+    if (rightTime < leftTime)
+        return left;
+    if (rightTime > leftTime)
+        return { ...right, messageIds: [...right.messageIds] };
+    return { schema: 1, revisionTime: left.revisionTime, messageIds: [...new Set([...left.messageIds, ...right.messageIds])].sort() };
+}

package/dist/feishu/interaction-orchestrator.cjs

@@ -0,0 +1,279 @@
+"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.HostInteractionOrchestrator = void 0;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const interaction_state_machine_js_1 = require("../agent/interaction-state-machine.cjs");
+const ReminderStore = __importStar(require("../agent/reminder-store.cjs"));
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function rawEventId(raw) {
+    if (!isRecord(raw))
+        return null;
+    const header = isRecord(raw.header) ? raw.header : null;
+    const event = isRecord(raw.event) ? raw.event : null;
+    for (const value of [raw.event_id, header?.event_id, event?.event_id])
+        if (typeof value === "string" && value)
+            return value;
+    return null;
+}
+function interactionRef(event) {
+    if (!isRecord(event.action.value) || typeof event.action.value.interaction_ref !== "string")
+        throw new Error("card action is not a Larkin interaction");
+    return event.action.value.interaction_ref;
+}
+function interactionVersion(event) {
+    if (!isRecord(event.action.value) || !Number.isSafeInteger(event.action.value.interaction_version))
+        throw new Error("card action interaction_version is missing");
+    return Number(event.action.value.interaction_version);
+}
+class HostInteractionOrchestrator {
+    options;
+    log;
+    now;
+    watchers = new Map();
+    syncAgents = new Map();
+    flushInFlight = new Map();
+    syncTimer = null;
+    syncActive = false;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? (() => { });
+        this.now = options.now ?? Date.now;
+    }
+    machine(agent) {
+        return new interaction_state_machine_js_1.InteractionStateMachine({ stateStore: this.options.stateStore(agent), agentId: agent.agentId, now: this.now });
+    }
+    callbackId(event) {
+        const eventId = rawEventId(event.raw);
+        if (!eventId)
+            throw new Error("card callback event_id is missing; enable includeRawEvent and retry");
+        return `card:${eventId}`;
+    }
+    runReminderEffect(agent, run, effect, deadline) {
+        if (deadline - this.now() < 500)
+            return { status: "timed_out", summary: "reminder.schedule skipped because the Reflex deadline was exhausted", data: { category: "reflex_deadline" } };
+        try {
+            const file = this.options.stateStore(agent).paths.reminders;
+            const reminderId = `int_${(0, node_crypto_1.createHash)("sha256").update(run.run_id).digest("hex").slice(0, 24)}`;
+            const current = this.now();
+            const fireAt = effect.args.fire_at ? Date.parse(effect.args.fire_at) : current + Number(effect.args.delay_seconds) * 1_000;
+            const reminder = ReminderStore.mutate(file, (store) => {
+                const existing = store.reminders.find((candidate) => candidate.reminderId === reminderId);
+                if (existing)
+                    return existing;
+                const created = {
+                    reminderId,
+                    ownerAgentId: agent.agentId,
+                    title: effect.args.title,
+                    fireAt: ReminderStore.nowIso(fireAt),
+                    firedAt: null,
+                    createdAt: ReminderStore.nowIso(current),
+                    status: "scheduled",
+                    msgRef: run.message_id,
+                    msgPermalink: null,
+                    repeat: null,
+                    tz: null,
+                    channel: run.chat_id,
+                    payload: { source: "interaction", run_id: run.run_id },
+                    version: 1,
+                    events: [],
+                };
+                ReminderStore.appendEvent(created, "scheduled", "interaction", run.run_id, created.fireAt, current);
+                store.reminders.push(created);
+                return created;
+            }, Math.max(1, Math.min(350, deadline - this.now() - 100)));
+            return { status: "succeeded", summary: "reminder.schedule completed", data: { reminder_id: reminder.reminderId, fire_at: reminder.fireAt } };
+        }
+        catch (error) {
+            const timedOut = this.now() >= deadline || /锁等待超时/.test(errorMessage(error));
+            return timedOut
+                ? { status: "timed_out", summary: "reminder.schedule did not complete within the Reflex deadline", data: { category: "reflex_deadline" } }
+                : { status: "uncertain", summary: "reminder.schedule could not confirm its durable result; inspect before retrying", data: { category: "reminder_schedule_uncertain" } };
+        }
+    }
+    async handleCardAction(agent, event) {
+        const deadline = this.now() + 2_700;
+        const machine = this.machine(agent);
+        try {
+            const claimed = machine.claim({
+                interaction_ref: interactionRef(event),
+                expected_version: interactionVersion(event),
+                callback_id: this.callbackId(event),
+                operator_open_id: event.operator.openId,
+                chat_id: event.chatId,
+                message_id: event.messageId,
+            });
+            let run = claimed.run;
+            if (run.reflex.status === "pending") {
+                const effect = claimed.definition.actions[run.action_id].reflex.effect;
+                const result = effect
+                    ? this.runReminderEffect(agent, run, effect, deadline)
+                    : { status: "succeeded", summary: "default Reflex accepted the action", data: {} };
+                run = machine.recordReflex(run.run_id, result);
+            }
+            void this.flushPending(agent).catch((error) => this.log(`interaction 异步投递失败 agent=${agent.name}: ${errorMessage(error)}`));
+            const latest = machine.get({ run_id: run.run_id });
+            const effectFailed = ["failed", "uncertain", "timed_out"].includes(run.reflex.status);
+            return {
+                toast: {
+                    type: effectFailed ? "warning" : "info",
+                    content: effectFailed ? "快速操作结果尚未确认，Agent 已接管；当前不代表业务完成。" : "已受理，Agent 正在处理，完成后会更新卡片。",
+                },
+                card: { type: "raw", data: latest.card },
+            };
+        }
+        catch (error) {
+            this.log(`interaction callback 拒绝 agent=${agent.name}: ${errorMessage(error)}`);
+            const reason = errorMessage(error);
+            const safeReason = /expired|not allowed|already has an active run|transition limit|reference is invalid|event_id is missing|version is stale|interaction_version is missing/.test(reason)
+                ? reason : "interaction service is temporarily unavailable";
+            return { toast: { type: "error", content: `无法受理：${safeReason}` } };
+        }
+    }
+    async flushPending(agent) {
+        const existing = this.flushInFlight.get(agent.agentId);
+        if (existing)
+            return existing;
+        const attempt = this.performFlush(agent);
+        this.flushInFlight.set(agent.agentId, attempt);
+        try {
+            await attempt;
+        }
+        finally {
+            if (this.flushInFlight.get(agent.agentId) === attempt)
+                this.flushInFlight.delete(agent.agentId);
+        }
+    }
+    async performFlush(agent) {
+        const machine = this.machine(agent);
+        const maintenance = machine.pendingMaintenance();
+        if (maintenance.interrupted_reflex)
+            machine.recoverInterruptedReflexes();
+        if (maintenance.timed_out_run)
+            machine.expireTimedOutRuns();
+        for (let pass = 0; pass < 4; pass += 1) {
+            const pending = machine.pendingOutbox();
+            if (!pending.length)
+                break;
+            let hadFailure = false;
+            for (const item of pending) {
+                try {
+                    if (item.kind === "agent_wake") {
+                        const envelope = item.payload;
+                        const preparation = this.options.stateStore(agent).prepareInboxDelivery(envelope);
+                        if (preparation !== "consumed") {
+                            const receipt = await this.options.deliveryTarget.deliver(agent.agentId, envelope);
+                            if (!receipt || !["accepted", "duplicate", "deferred"].includes(String(receipt.status))) {
+                                throw new Error(`Runtime delivery returned ${String(receipt?.status || "unknown")}: ${String(receipt?.reason || "no reason")}`);
+                            }
+                            this.options.afterRuntimeDelivery?.();
+                        }
+                        machine.markOutbox(item.outbox_id, { delivered: true });
+                    }
+                    else {
+                        const channel = this.options.channelFor(agent);
+                        if (!channel)
+                            throw new Error("card channel is not connected");
+                        const projection = machine.prepareProjection(item.outbox_id);
+                        if (!projection)
+                            continue;
+                        try {
+                            await channel.updateCard(projection.message_id, projection.card);
+                            machine.completeProjection(item.outbox_id, projection.desired_version, { delivered: true });
+                        }
+                        catch (error) {
+                            machine.completeProjection(item.outbox_id, projection.desired_version, { delivered: false, error: errorMessage(error) });
+                            throw error;
+                        }
+                    }
+                }
+                catch (error) {
+                    hadFailure = true;
+                    if (item.kind === "agent_wake")
+                        machine.markOutbox(item.outbox_id, { delivered: false, error: errorMessage(error) });
+                    this.log(`interaction outbox 保留重试 agent=${agent.name} kind=${item.kind}: ${errorMessage(error)}`);
+                }
+            }
+            if (hadFailure)
+                break;
+        }
+    }
+    startSync() {
+        if (this.syncTimer)
+            return;
+        this.syncActive = true;
+        for (const agent of this.options.agents)
+            this.syncAgent(agent);
+        this.syncTimer = (this.options.setInterval ?? setInterval)(() => {
+            for (const agent of this.syncAgents.values())
+                void this.flushPending(agent);
+        }, 30_000);
+        this.syncTimer.unref?.();
+    }
+    syncAgent(agent) {
+        this.syncAgents.set(agent.agentId, agent);
+        if (!this.syncActive)
+            return;
+        if (agent.stateDir && !this.watchers.has(agent.agentId)) {
+            try {
+                const watcher = (this.options.watch ?? fs.watch)(agent.stateDir, (_event, filename) => {
+                    const current = this.syncAgents.get(agent.agentId);
+                    if (filename === "interactions.json" && current)
+                        void this.flushPending(current);
+                });
+                this.watchers.set(agent.agentId, watcher);
+            }
+            catch (error) {
+                this.log(`interaction watch 失败 agent=${agent.name}: ${errorMessage(error)}`);
+            }
+        }
+        void this.flushPending(agent);
+    }
+    stopSync() {
+        if (this.syncTimer)
+            clearInterval(this.syncTimer);
+        this.syncTimer = null;
+        this.syncActive = false;
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+        this.syncAgents.clear();
+    }
+}
+exports.HostInteractionOrchestrator = HostInteractionOrchestrator;

package/dist/feishu/interaction-orchestrator.mjs

@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { InteractionStateMachine } from "../agent/interaction-state-machine.mjs";
+import * as ReminderStore from "../agent/reminder-store.mjs";
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function rawEventId(raw) {
+    if (!isRecord(raw))
+        return null;
+    const header = isRecord(raw.header) ? raw.header : null;
+    const event = isRecord(raw.event) ? raw.event : null;
+    for (const value of [raw.event_id, header?.event_id, event?.event_id])
+        if (typeof value === "string" && value)
+            return value;
+    return null;
+}
+function interactionRef(event) {
+    if (!isRecord(event.action.value) || typeof event.action.value.interaction_ref !== "string")
+        throw new Error("card action is not a Larkin interaction");
+    return event.action.value.interaction_ref;
+}
+function interactionVersion(event) {
+    if (!isRecord(event.action.value) || !Number.isSafeInteger(event.action.value.interaction_version))
+        throw new Error("card action interaction_version is missing");
+    return Number(event.action.value.interaction_version);
+}
+export class HostInteractionOrchestrator {
+    options;
+    log;
+    now;
+    watchers = new Map();
+    syncAgents = new Map();
+    flushInFlight = new Map();
+    syncTimer = null;
+    syncActive = false;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? (() => { });
+        this.now = options.now ?? Date.now;
+    }
+    machine(agent) {
+        return new InteractionStateMachine({ stateStore: this.options.stateStore(agent), agentId: agent.agentId, now: this.now });
+    }
+    callbackId(event) {
+        const eventId = rawEventId(event.raw);
+        if (!eventId)
+            throw new Error("card callback event_id is missing; enable includeRawEvent and retry");
+        return `card:${eventId}`;
+    }
+    runReminderEffect(agent, run, effect, deadline) {
+        if (deadline - this.now() < 500)
+            return { status: "timed_out", summary: "reminder.schedule skipped because the Reflex deadline was exhausted", data: { category: "reflex_deadline" } };
+        try {
+            const file = this.options.stateStore(agent).paths.reminders;
+            const reminderId = `int_${createHash("sha256").update(run.run_id).digest("hex").slice(0, 24)}`;
+            const current = this.now();
+            const fireAt = effect.args.fire_at ? Date.parse(effect.args.fire_at) : current + Number(effect.args.delay_seconds) * 1_000;
+            const reminder = ReminderStore.mutate(file, (store) => {
+                const existing = store.reminders.find((candidate) => candidate.reminderId === reminderId);
+                if (existing)
+                    return existing;
+                const created = {
+                    reminderId,
+                    ownerAgentId: agent.agentId,
+                    title: effect.args.title,
+                    fireAt: ReminderStore.nowIso(fireAt),
+                    firedAt: null,
+                    createdAt: ReminderStore.nowIso(current),
+                    status: "scheduled",
+                    msgRef: run.message_id,
+                    msgPermalink: null,
+                    repeat: null,
+                    tz: null,
+                    channel: run.chat_id,
+                    payload: { source: "interaction", run_id: run.run_id },
+                    version: 1,
+                    events: [],
+                };
+                ReminderStore.appendEvent(created, "scheduled", "interaction", run.run_id, created.fireAt, current);
+                store.reminders.push(created);
+                return created;
+            }, Math.max(1, Math.min(350, deadline - this.now() - 100)));
+            return { status: "succeeded", summary: "reminder.schedule completed", data: { reminder_id: reminder.reminderId, fire_at: reminder.fireAt } };
+        }
+        catch (error) {
+            const timedOut = this.now() >= deadline || /锁等待超时/.test(errorMessage(error));
+            return timedOut
+                ? { status: "timed_out", summary: "reminder.schedule did not complete within the Reflex deadline", data: { category: "reflex_deadline" } }
+                : { status: "uncertain", summary: "reminder.schedule could not confirm its durable result; inspect before retrying", data: { category: "reminder_schedule_uncertain" } };
+        }
+    }
+    async handleCardAction(agent, event) {
+        const deadline = this.now() + 2_700;
+        const machine = this.machine(agent);
+        try {
+            const claimed = machine.claim({
+                interaction_ref: interactionRef(event),
+                expected_version: interactionVersion(event),
+                callback_id: this.callbackId(event),
+                operator_open_id: event.operator.openId,
+                chat_id: event.chatId,
+                message_id: event.messageId,
+            });
+            let run = claimed.run;
+            if (run.reflex.status === "pending") {
+                const effect = claimed.definition.actions[run.action_id].reflex.effect;
+                const result = effect
+                    ? this.runReminderEffect(agent, run, effect, deadline)
+                    : { status: "succeeded", summary: "default Reflex accepted the action", data: {} };
+                run = machine.recordReflex(run.run_id, result);
+            }
+            void this.flushPending(agent).catch((error) => this.log(`interaction 异步投递失败 agent=${agent.name}: ${errorMessage(error)}`));
+            const latest = machine.get({ run_id: run.run_id });
+            const effectFailed = ["failed", "uncertain", "timed_out"].includes(run.reflex.status);
+            return {
+                toast: {
+                    type: effectFailed ? "warning" : "info",
+                    content: effectFailed ? "快速操作结果尚未确认，Agent 已接管；当前不代表业务完成。" : "已受理，Agent 正在处理，完成后会更新卡片。",
+                },
+                card: { type: "raw", data: latest.card },
+            };
+        }
+        catch (error) {
+            this.log(`interaction callback 拒绝 agent=${agent.name}: ${errorMessage(error)}`);
+            const reason = errorMessage(error);
+            const safeReason = /expired|not allowed|already has an active run|transition limit|reference is invalid|event_id is missing|version is stale|interaction_version is missing/.test(reason)
+                ? reason : "interaction service is temporarily unavailable";
+            return { toast: { type: "error", content: `无法受理：${safeReason}` } };
+        }
+    }
+    async flushPending(agent) {
+        const existing = this.flushInFlight.get(agent.agentId);
+        if (existing)
+            return existing;
+        const attempt = this.performFlush(agent);
+        this.flushInFlight.set(agent.agentId, attempt);
+        try {
+            await attempt;
+        }
+        finally {
+            if (this.flushInFlight.get(agent.agentId) === attempt)
+                this.flushInFlight.delete(agent.agentId);
+        }
+    }
+    async performFlush(agent) {
+        const machine = this.machine(agent);
+        const maintenance = machine.pendingMaintenance();
+        if (maintenance.interrupted_reflex)
+            machine.recoverInterruptedReflexes();
+        if (maintenance.timed_out_run)
+            machine.expireTimedOutRuns();
+        for (let pass = 0; pass < 4; pass += 1) {
+            const pending = machine.pendingOutbox();
+            if (!pending.length)
+                break;
+            let hadFailure = false;
+            for (const item of pending) {
+                try {
+                    if (item.kind === "agent_wake") {
+                        const envelope = item.payload;
+                        const preparation = this.options.stateStore(agent).prepareInboxDelivery(envelope);
+                        if (preparation !== "consumed") {
+                            const receipt = await this.options.deliveryTarget.deliver(agent.agentId, envelope);
+                            if (!receipt || !["accepted", "duplicate", "deferred"].includes(String(receipt.status))) {
+                                throw new Error(`Runtime delivery returned ${String(receipt?.status || "unknown")}: ${String(receipt?.reason || "no reason")}`);
+                            }
+                            this.options.afterRuntimeDelivery?.();
+                        }
+                        machine.markOutbox(item.outbox_id, { delivered: true });
+                    }
+                    else {
+                        const channel = this.options.channelFor(agent);
+                        if (!channel)
+                            throw new Error("card channel is not connected");
+                        const projection = machine.prepareProjection(item.outbox_id);
+                        if (!projection)
+                            continue;
+                        try {
+                            await channel.updateCard(projection.message_id, projection.card);
+                            machine.completeProjection(item.outbox_id, projection.desired_version, { delivered: true });
+                        }
+                        catch (error) {
+                            machine.completeProjection(item.outbox_id, projection.desired_version, { delivered: false, error: errorMessage(error) });
+                            throw error;
+                        }
+                    }
+                }
+                catch (error) {
+                    hadFailure = true;
+                    if (item.kind === "agent_wake")
+                        machine.markOutbox(item.outbox_id, { delivered: false, error: errorMessage(error) });
+                    this.log(`interaction outbox 保留重试 agent=${agent.name} kind=${item.kind}: ${errorMessage(error)}`);
+                }
+            }
+            if (hadFailure)
+                break;
+        }
+    }
+    startSync() {
+        if (this.syncTimer)
+            return;
+        this.syncActive = true;
+        for (const agent of this.options.agents)
+            this.syncAgent(agent);
+        this.syncTimer = (this.options.setInterval ?? setInterval)(() => {
+            for (const agent of this.syncAgents.values())
+                void this.flushPending(agent);
+        }, 30_000);
+        this.syncTimer.unref?.();
+    }
+    syncAgent(agent) {
+        this.syncAgents.set(agent.agentId, agent);
+        if (!this.syncActive)
+            return;
+        if (agent.stateDir && !this.watchers.has(agent.agentId)) {
+            try {
+                const watcher = (this.options.watch ?? fs.watch)(agent.stateDir, (_event, filename) => {
+                    const current = this.syncAgents.get(agent.agentId);
+                    if (filename === "interactions.json" && current)
+                        void this.flushPending(current);
+                });
+                this.watchers.set(agent.agentId, watcher);
+            }
+            catch (error) {
+                this.log(`interaction watch 失败 agent=${agent.name}: ${errorMessage(error)}`);
+            }
+        }
+        void this.flushPending(agent);
+    }
+    stopSync() {
+        if (this.syncTimer)
+            clearInterval(this.syncTimer);
+        this.syncTimer = null;
+        this.syncActive = false;
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+        this.syncAgents.clear();
+    }
+}

package/dist/feishu/lark-passthrough.mjs

@@ -0,0 +1,70 @@
+// larkin 顶级 lark-cli 命令组直通决策（larkin im … == lark-cli im …）：封装转发不改写语义，
+// 唯一硬边界是身份/凭证（Owner 定，2026-07-17，见 coding-context larkin.cli-prompt-alignment plan）。
+// 能力边界交给飞书权限体系（bot scope、群成员身份、文档协作者），壳不做命令级裁剪；
+// 不可逆操作靠版本化 Runtime standing prompt 的行为约定治理。
+import { resolveRuntimeAuthority } from "../platform/config.mjs";
+export const PASSTHROUGH_USAGE = "用法：larkin <lark-cli 命令组…> [--agent <App ID>]，如 larkin im +chat-list --json（语法与 lark-cli 一致）";
+const IDENTITY = "身份边界";
+export function assessPassthrough(argv, runtimeEnv = {}) {
+    const rest = [...argv];
+    let runtimeAgentId;
+    try {
+        runtimeAgentId = resolveRuntimeAuthority(runtimeEnv);
+    }
+    catch (error) {
+        return { ok: false, reason: `${IDENTITY}：${error instanceof Error ? error.message : String(error)}` };
+    }
+    let explicitAgent = null;
+    const agentFlags = rest.reduce((indexes, argument, index) => {
+        if (argument === "--agent")
+            indexes.push(index);
+        return indexes;
+    }, []);
+    if (agentFlags.length > 1) {
+        return { ok: false, reason: `--agent 只能指定一次。${PASSTHROUGH_USAGE}` };
+    }
+    const agentFlag = agentFlags[0] ?? -1;
+    if (agentFlag >= 0) {
+        if (runtimeAgentId) {
+            return { ok: false, reason: `${IDENTITY}：当前 Agent 的机器人身份已由 Runtime authority marker 锁定，不允许使用 --agent 选择身份。` };
+        }
+        if (!rest[agentFlag + 1])
+            return { ok: false, reason: `--agent 需要 App ID。${PASSTHROUGH_USAGE}` };
+        explicitAgent = rest[agentFlag + 1];
+        rest.splice(agentFlag, 2);
+    }
+    if (!rest.length)
+        return { ok: false, reason: `缺少 lark-cli 参数。${PASSTHROUGH_USAGE}` };
+    for (let index = 0; index < rest.length; index += 1) {
+        const argument = rest[index];
+        if ((argument === "--as" && rest[index + 1] === "user") || argument === "--as=user") {
+            return { ok: false, reason: `${IDENTITY}：larkin agent 只能以自己的机器人身份调用 lark-cli，不允许 --as user。` };
+        }
+        if (argument === "--profile" || argument.startsWith("--profile=")) {
+            return { ok: false, reason: `${IDENTITY}：profile 由 larkin 按当前 agent 锁定，不接受手动指定；换 agent 用 --agent <App ID>。` };
+        }
+        if (argument === "--config-dir" || argument.startsWith("--config-dir=")) {
+            return { ok: false, reason: `${IDENTITY}：lark-cli 配置目录由 larkin 锁定，不接受覆盖。` };
+        }
+    }
+    const subcommand = rest.find((argument) => !argument.startsWith("-"));
+    // lark-cli 的 CLI 管理族操作共享凭证库与安装本体，属身份基础设施，不是飞书能力。
+    if (subcommand && ["auth", "config", "profile", "update"].includes(subcommand)) {
+        return { ok: false, reason: `${IDENTITY}：lark-cli 凭证与配置管理（${subcommand}）不走 larkin；机器人凭证由 larkin setup 负责。` };
+    }
+    // event 会用同一 bot 凭证另开长连接，可能抢走 Runtime Host 的事件流（Owner 定，2026-07-17）。
+    if (subcommand === "event") {
+        return { ok: false, reason: "运行时保护：lark-cli event 会与 Runtime Host 争抢同一机器人的事件流；实时消息请用 inbox check（canonical Inbox）。" };
+    }
+    // 纯用户身份域：机器人没有邮箱/考勤/OKR 实体，直通必失败（Owner 定，2026-07-17）。
+    if (subcommand && ["mail", "attendance", "okr"].includes(subcommand)) {
+        return { ok: false, reason: `能力边界：${subcommand} 是用户身份域，机器人身份没有对应实体，larkin 不转发。` };
+    }
+    return { ok: true, argv: applyArgvTweaks(rest), explicitAgent };
+}
+export const ARGV_TWEAKS = {};
+export function applyArgvTweaks(argv) {
+    const key = argv.filter((argument) => !argument.startsWith("-")).slice(0, 2).join(" ");
+    const tweak = ARGV_TWEAKS[key];
+    return tweak ? tweak([...argv]) : argv;
+}