@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/lib/types/host/services/lark-inbox/inbox-store.js

@@ -0,0 +1,124 @@
+/** SQLite cursor/dedup index over the durable daily JSONL queue. */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { envelopeToLine, inboxFilePath } from "../../../core/lark-inbox/queue.js";
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_STALE_TIMEOUT_MS = 300_000;
+export class InboxStore {
+    db;
+    rootDir;
+    maxAttempts;
+    staleTimeoutMs;
+    closed = false;
+    constructor(db, options) {
+        this.db = db;
+        this.rootDir = options.rootDir;
+        this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.staleTimeoutMs = options.staleTimeoutMs ?? DEFAULT_STALE_TIMEOUT_MS;
+    }
+    static open(options) {
+        let db;
+        try {
+            mkdirSync(options.rootDir, { recursive: true, mode: 0o700 });
+            db = new DatabaseSync(join(options.rootDir, 'inbox.sqlite'));
+            db.exec(`CREATE TABLE IF NOT EXISTS inbox_events (
+        event_id TEXT PRIMARY KEY,
+        file TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        attempts INTEGER NOT NULL DEFAULT 0,
+        received_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        payload TEXT NOT NULL
+      )`);
+            db.exec('CREATE INDEX IF NOT EXISTS idx_inbox_events_claim ON inbox_events(status, received_at)');
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`lark-inbox: failed to open inbox store at "${options.rootDir}": node:sqlite requires Node >= 22.13 or a DSH Host runtime with node:sqlite support. ${detail}`);
+        }
+        return new InboxStore(db, options);
+    }
+    append(envelope) {
+        const now = Date.now();
+        const file = inboxFilePath(this.rootDir, envelope.eventType, now);
+        const line = envelopeToLine(envelope);
+        const result = this.db.prepare(`INSERT OR IGNORE INTO inbox_events
+      (event_id, file, status, attempts, received_at, updated_at, payload)
+      VALUES (?, ?, 'pending', 0, ?, ?, ?)`)
+            .run(envelope.eventId, file, now, now, line);
+        if (Number(result.changes) === 0)
+            return 'duplicate';
+        try {
+            mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+            appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+        }
+        catch (error) {
+            this.db.prepare('DELETE FROM inbox_events WHERE event_id = ?').run(envelope.eventId);
+            throw error;
+        }
+        return 'appended';
+    }
+    peek(limit = 1) {
+        const rows = this.db.prepare(`SELECT event_id, file, status, attempts, payload
+      FROM inbox_events WHERE status = 'pending'
+      ORDER BY received_at ASC, rowid ASC LIMIT ?`).all(limit);
+        return rows.map(row => this.rowToItem(row));
+    }
+    pop() {
+        const row = this.db.prepare(`SELECT event_id, file, attempts, payload
+      FROM inbox_events WHERE status = 'pending'
+      ORDER BY received_at ASC, rowid ASC LIMIT 1`).get();
+        if (!row)
+            return null;
+        const eventId = String(row.event_id);
+        const attempts = Number(row.attempts) + 1;
+        this.db.prepare(`UPDATE inbox_events SET status = 'processing', attempts = attempts + 1, updated_at = ?
+      WHERE event_id = ?`).run(Date.now(), eventId);
+        return { envelope: JSON.parse(String(row.payload)), status: 'processing', attempts, file: String(row.file) };
+    }
+    ack(eventId) {
+        this.db.prepare(`UPDATE inbox_events SET status = 'done', updated_at = ?
+      WHERE event_id = ? AND status = 'processing'`).run(Date.now(), eventId);
+    }
+    nack(eventId) {
+        const row = this.db.prepare(`SELECT attempts FROM inbox_events
+      WHERE event_id = ? AND status = 'processing'`).get(eventId);
+        if (!row)
+            return;
+        const nextStatus = Number(row.attempts) >= this.maxAttempts ? 'dead' : 'pending';
+        this.db.prepare('UPDATE inbox_events SET status = ?, updated_at = ? WHERE event_id = ?')
+            .run(nextStatus, Date.now(), eventId);
+    }
+    recoverStale() {
+        const threshold = Date.now() - this.staleTimeoutMs;
+        const result = this.db.prepare(`UPDATE inbox_events SET status = 'pending', updated_at = ?
+      WHERE status = 'processing' AND updated_at < ?`).run(Date.now(), threshold);
+        return Number(result.changes);
+    }
+    stats() {
+        const rows = this.db.prepare('SELECT status, COUNT(*) AS cnt FROM inbox_events GROUP BY status')
+            .all();
+        const counts = { pending: 0, processing: 0, done: 0, dead: 0 };
+        for (const row of rows) {
+            const status = String(row.status);
+            if (status in counts)
+                counts[status] = Number(row.cnt);
+        }
+        return { ...counts, total: counts.pending + counts.processing + counts.done + counts.dead };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.db.close();
+    }
+    rowToItem(row) {
+        return {
+            envelope: JSON.parse(String(row.payload)),
+            status: row.status === 'processing' ? 'processing' : 'pending',
+            attempts: Number(row.attempts),
+            file: String(row.file),
+        };
+    }
+}

package/lib/types/host/services/lark-inbox/index.d.ts

@@ -0,0 +1,26 @@
+/** Authoritative pre-merge Lark inbox host behavior, adapted to web-all ownership. */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, LARK_INBOX_SETTINGS_NAMESPACE, type LarkInboxConfig } from './config.ts';
+import { LarkGateway, type GatewaySdk } from './gateway.ts';
+import { InboxStore } from './inbox-store.ts';
+import { makeLarkWizardRoutes } from './host-routes.ts';
+import { LarkWizard, type SpawnFn } from './wizard.ts';
+export declare const LARK_API_PREFIX = "/api/dsh-lark-inbox";
+export declare const LARK_INBOX_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-lark-inbox \u63D2\u4EF6\uFF08\u98DE\u4E66/Lark \u673A\u5668\u4EBA\u6D88\u606F\u6536\u4EF6\u7BB1\uFF09\uFF1A\u98DE\u4E66 bot \u4EE5 WebSocket \u957F\u8FDE\u63A5\u6536\u5230\u7684\u6D88\u606F\u5E42\u7B49\u5199\u5165\u672C\u5730 JSONL \u961F\u5217\uFF08$DSH_HOME/lark-inbox\uFF0C\u6309\u65E5\u8F6E\u8F6C\uFF0CSQLite \u7D22\u5F15\u53BB\u91CD\u4E0E\u6E38\u6807\uFF09\u3002\u53EF\u7528\u5DE5\u5177\uFF1Alark_inbox_peek\uFF08\u67E5\u770B\u5F85\u5904\u7406\u6D88\u606F\uFF09\u3001lark_inbox_pop\uFF08\u53D6\u51FA\u6700\u65E7\u4E00\u6761\u5E76\u9501\u5B9A\uFF09\u3001lark_inbox_ack\uFF08\u786E\u8BA4\u5B8C\u6210 ok=true\uFF0C\u6216\u9000\u56DE\u91CD\u8BD5 ok=false\uFF0C\u8D85\u6B21\u8F6C\u6B7B\u4FE1\uFF09\u3002\u7528\u6237\u63D0\u5230\u300C\u98DE\u4E66\u673A\u5668\u4EBA\u6D88\u606F / lark-inbox / \u98DE\u4E66\u6536\u4EF6\u7BB1\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\u3002";
+export interface LarkInboxServiceDeps {
+    dshHome?: string;
+    env?: NodeJS.ProcessEnv;
+    gatewaySdk?: GatewaySdk;
+    wizardSpawn?: SpawnFn;
+    wizardQrDir?: string;
+    createStore?: (options: {
+        rootDir: string;
+        maxAttempts: number;
+        staleTimeoutMs: number;
+    }) => InboxStore;
+    createGateway?: (options: ConstructorParameters<typeof LarkGateway>[0]) => Pick<LarkGateway, 'start' | 'stop' | 'isRunning'>;
+}
+/** Register tools, live runtime, announcement, and exact old wizard routes. */
+export declare function register(ctx: Context, base?: LarkInboxConfig, deps?: LarkInboxServiceDeps): () => void;
+export { Config, LARK_INBOX_SETTINGS_NAMESPACE, InboxStore, LarkGateway, LarkWizard, makeLarkWizardRoutes };
+//# sourceMappingURL=index.d.ts.map

package/lib/types/host/services/lark-inbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/lark-inbox/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAItF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,OAAO,EAAE,MAAM,EAAE,6BAA6B,EAAsD,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7I,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAGvD,OAAO,EAAE,UAAU,EAA0B,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAG9E,eAAO,MAAM,eAAe,wBAAwB,CAAA;AAGpD,eAAO,MAAM,mBAAmB,64BAAuR,CAAA;AAEvT,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,KAAK,UAAU,CAAA;IACvG,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAA;CAC7H;AA2BD,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,eAAoB,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,IAAI,CA6E9G;AAED,OAAO,EAAE,MAAM,EAAE,6BAA6B,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAA"}

package/lib/types/host/services/lark-inbox/index.js

@@ -0,0 +1,135 @@
+/** Authoritative pre-merge Lark inbox host behavior, adapted to web-all ownership. */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { familyNamespace, updateFamilyNamespace } from "../family-config.js";
+import { gateEvent } from "../../../core/lark-inbox/gating.js";
+import { toEnvelope } from "../../../core/lark-inbox/queue.js";
+import { Config, LARK_INBOX_SETTINGS_NAMESPACE, effectiveConfig, resolveAppSecret, resolveQueueDir } from "./config.js";
+import { LarkGateway } from "./gateway.js";
+import { InboxStore } from "./inbox-store.js";
+import { makeLarkWizardRoutes } from "./host-routes.js";
+import { accessTrustOf } from "../access-trust/index.js";
+import { registerInboxTools } from "./tools.js";
+import { LarkWizard, writeWithConflictRetry } from "./wizard.js";
+import { registerResources } from "../resources.js";
+export const LARK_API_PREFIX = '/api/dsh-lark-inbox';
+const SECTION_ORDER = 210;
+export const LARK_INBOX_GUIDANCE = '本机已安装 dsh-lark-inbox 插件（飞书/Lark 机器人消息收件箱）：飞书 bot 以 WebSocket 长连接收到的消息幂等写入本地 JSONL 队列（$DSH_HOME/lark-inbox，按日轮转，SQLite 索引去重与游标）。可用工具：lark_inbox_peek（查看待处理消息）、lark_inbox_pop（取出最旧一条并锁定）、lark_inbox_ack（确认完成 ok=true，或退回重试 ok=false，超次转死信）。用户提到「飞书机器人消息 / lark-inbox / 飞书收件箱」时即指本插件。';
+function readSenderType(event) {
+    const source = typeof event === 'object' && event !== null ? event : {};
+    const inner = typeof source.event === 'object' && source.event !== null ? source.event : source;
+    const sender = inner.sender;
+    const type = typeof sender === 'object' && sender !== null ? sender.sender_type : undefined;
+    return typeof type === 'string' && type.length > 0 ? type : 'user';
+}
+function gatingConfig(config) {
+    return { requireMentionInGroup: config.requireMentionInGroup, allowedOpenIds: config.allowedOpenIds, dropAppMessages: config.dropAppMessages };
+}
+function dshHome(env) {
+    const raw = env.DSH_HOME?.trim();
+    if (!raw)
+        return join(homedir(), '.dsh');
+    if (raw === '~')
+        return homedir();
+    if (raw.startsWith('~/'))
+        return join(homedir(), raw.slice(2));
+    return raw;
+}
+function liveConfig(ctx, fallback) {
+    void ctx;
+    return familyNamespace(LARK_INBOX_SETTINGS_NAMESPACE) ?? fallback;
+}
+/** Register tools, live runtime, announcement, and exact old wizard routes. */
+export function register(ctx, base = {}, deps = {}) {
+    const log = ctx.logger('lark-inbox');
+    const env = deps.env ?? process.env;
+    let activeStore;
+    let disposeRuntime;
+    let disposeSection;
+    let current = () => liveConfig(ctx, base);
+    return registerResources(own => {
+        own(registerInboxTools(ctx, () => activeStore));
+        own(() => { disposeSection?.(); });
+        own(() => { disposeRuntime?.(); });
+        const sync = () => {
+            disposeRuntime?.();
+            disposeRuntime = undefined;
+            disposeSection?.();
+            disposeSection = undefined;
+            const active = effectiveConfig(current());
+            if (!active.enabled)
+                return;
+            let appSecret;
+            try {
+                appSecret = resolveAppSecret(active, env);
+            }
+            catch (error) {
+                log.warn('dsh-lark-inbox: %s', error instanceof Error ? error.message : String(error));
+                return;
+            }
+            const appId = active.appId.trim();
+            if (appId === '') {
+                log.warn('dsh-lark-inbox: 未配置 appId，网关未启动；请在设置里填写 appId');
+                return;
+            }
+            const store = (deps.createStore ?? (options => InboxStore.open(options)))({
+                rootDir: resolveQueueDir(active, deps.dshHome ?? dshHome(env)),
+                maxAttempts: active.maxAttempts,
+                staleTimeoutMs: active.staleTimeoutMs,
+            });
+            activeStore = store;
+            const gatewayOptions = {
+                appId, appSecret, domain: active.domain, sdk: deps.gatewaySdk,
+                log: (level, message) => level === 'info' ? log.info(message) : level === 'warn' ? log.warn(message) : log.error(message),
+                onEvent: (event, meta) => {
+                    try {
+                        const envelope = toEnvelope(event, { mentionBot: meta.mentionBot });
+                        const input = { chatType: envelope.chatType, senderType: readSenderType(event), senderOpenId: envelope.senderOpenId, mentionBot: meta.mentionBot };
+                        const decision = gateEvent(input, gatingConfig(active));
+                        if (!decision.accept) {
+                            log.warn('dsh-lark-inbox: 丢弃飞书事件 %s：%s', envelope.eventId, decision.reason);
+                            return;
+                        }
+                        store.append(envelope);
+                    }
+                    catch (error) {
+                        log.error('dsh-lark-inbox: 处理飞书事件失败：%s', error instanceof Error ? error.message : String(error));
+                    }
+                },
+            };
+            let gateway;
+            disposeRuntime = () => {
+                void gateway?.stop().catch(error => log.error('dsh-lark-inbox: 网关关闭失败：%s', error instanceof Error ? error.message : String(error)));
+                try {
+                    store.close();
+                }
+                catch (error) {
+                    log.error('dsh-lark-inbox: 队列关闭失败：%s', error instanceof Error ? error.message : String(error));
+                }
+                if (activeStore === store)
+                    activeStore = undefined;
+            };
+            gateway = (deps.createGateway ?? (options => new LarkGateway(options)))(gatewayOptions);
+            void gateway.start().catch(error => log.error('dsh-lark-inbox: 网关启动失败：%s', error instanceof Error ? error.message : String(error)));
+            if (active.announceToAgent) {
+                disposeSection = ctx.systemPrompt.section({ name: 'plugin:lark-inbox', order: SECTION_ORDER, text: LARK_INBOX_GUIDANCE });
+            }
+        };
+        // The settings document is read/written through the family namespace pair
+        // (familyNamespace + updateFamilyNamespace); DSH 0.2's settings service has
+        // neither `get` nor `installSection`, so the old compat branch was a no-op.
+        const wizard = new LarkWizard({
+            qrDir: deps.wizardQrDir,
+            spawn: deps.wizardSpawn,
+            settingsWrite: async (patch) => {
+                await writeWithConflictRetry(() => updateFamilyNamespace(ctx, LARK_INBOX_SETTINGS_NAMESPACE, patch));
+            },
+            log: (level, message) => level === 'info' ? log.info(message) : level === 'warn' ? log.warn(message) : log.error(message),
+        });
+        own(() => { void wizard.cancel().catch(() => undefined); });
+        for (const route of makeLarkWizardRoutes(wizard, accessTrustOf(ctx).isTrusted, () => effectiveConfig(current()).enabled))
+            own(ctx.webServer.register(route));
+        sync();
+    });
+}
+export { Config, LARK_INBOX_SETTINGS_NAMESPACE, InboxStore, LarkGateway, LarkWizard, makeLarkWizardRoutes };

package/lib/types/host/services/lark-inbox/tools.d.ts

@@ -0,0 +1,7 @@
+/** Agent tools for consuming the local inbox queue. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { InboxStore } from './inbox-store.ts';
+export declare function createInboxTools(getStore: () => InboxStore | undefined): ToolDefinition[];
+export declare function registerInboxTools(ctx: Context, getStore: () => InboxStore | undefined): () => void;
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/host/services/lark-inbox/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/lark-inbox/tools.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC9F,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAoC7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,UAAU,GAAG,SAAS,GAAG,cAAc,EAAE,CA6EzF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,IAAI,CAInG"}

package/lib/types/host/services/lark-inbox/tools.js

@@ -0,0 +1,119 @@
+/** Agent tools for consuming the local inbox queue. */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { registerResources } from "../resources.js";
+const NOT_RUNNING = 'dsh-lark-inbox 未运行：请在设置里配置 appId/appSecret 并启用插件';
+const ACK_STATUSES = ['done', 'pending', 'dead', 'not-found'];
+function clampLimit(limit) {
+    const value = limit ?? 10;
+    return Number.isFinite(value) ? Math.min(50, Math.max(1, Math.trunc(value))) : 10;
+}
+function preview(item) {
+    const envelope = item.envelope;
+    return {
+        eventId: envelope.eventId,
+        receivedAt: envelope.receivedAt,
+        chatType: envelope.chatType ?? '',
+        senderOpenId: envelope.senderOpenId ?? '',
+        messageType: envelope.messageType ?? '',
+        contentPreview: envelope.content.slice(0, 300),
+    };
+}
+function popped(item) {
+    const envelope = item.envelope;
+    return {
+        eventId: envelope.eventId,
+        receivedAt: envelope.receivedAt,
+        chatType: envelope.chatType ?? '',
+        senderOpenId: envelope.senderOpenId ?? '',
+        messageType: envelope.messageType ?? '',
+        content: envelope.content,
+        messageId: envelope.messageId ?? '',
+    };
+}
+export function createInboxTools(getStore) {
+    return [
+        defineTool({
+            name: 'lark_inbox_peek',
+            description: 'List pending Feishu/Lark bot messages without locking them. Returns queue pending/processing/dead counters, or an error when the inbox is disabled or unconfigured.',
+            parameters: { limit: { type: 'integer', default: 10, description: 'Maximum pending messages (clamped to 1..50).' } },
+            output: {
+                schema: {
+                    type: 'object', additionalProperties: false, properties: {
+                        items: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+                                    eventId: { type: 'string', required: true }, receivedAt: { type: 'string', required: true },
+                                    chatType: { type: 'string', required: true }, senderOpenId: { type: 'string', required: true },
+                                    messageType: { type: 'string', required: true }, contentPreview: { type: 'string', required: true },
+                                } } },
+                        pending: { type: 'integer' }, processing: { type: 'integer' }, dead: { type: 'integer' }, error: { type: 'string' },
+                    },
+                },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            async execute(args) {
+                const store = getStore();
+                if (!store)
+                    return { error: NOT_RUNNING };
+                const stats = store.stats();
+                return { items: store.peek(clampLimit(args.limit)).map(preview), pending: stats.pending, processing: stats.processing, dead: stats.dead };
+            },
+            presentCall(args) { return { card: 'generic', title: 'Peek lark inbox', kind: 'read', rawInput: args }; },
+        }),
+        defineTool({
+            name: 'lark_inbox_pop',
+            description: 'Claim the oldest pending Feishu/Lark message into processing. You must settle its eventId with lark_inbox_ack; stale claims are recovered before each pop.',
+            parameters: {},
+            output: {
+                schema: { type: 'object', additionalProperties: false, properties: {
+                        item: { oneOf: [
+                                { type: 'object', additionalProperties: false, properties: {
+                                        eventId: { type: 'string', required: true }, receivedAt: { type: 'string', required: true },
+                                        chatType: { type: 'string', required: true }, senderOpenId: { type: 'string', required: true },
+                                        messageType: { type: 'string', required: true }, content: { type: 'string', required: true }, messageId: { type: 'string', required: true },
+                                    } },
+                                { type: 'null' },
+                            ] }, pending: { type: 'integer' }, error: { type: 'string' },
+                    } },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            async execute() {
+                const store = getStore();
+                if (!store)
+                    return { error: NOT_RUNNING };
+                store.recoverStale();
+                const item = store.pop();
+                return { item: item === null ? null : popped(item), pending: store.stats().pending };
+            },
+            presentCall(args) { return { card: 'generic', title: 'Pop next lark inbox message', kind: 'read', rawInput: args }; },
+        }),
+        defineTool({
+            name: 'lark_inbox_ack',
+            description: 'Settle a message claimed by lark_inbox_pop. ok=true marks done; ok=false retries it or moves it to dead after maxAttempts.',
+            parameters: {
+                event_id: { type: 'string', required: true, description: 'eventId returned by peek or pop.' },
+                ok: { type: 'boolean', required: true, description: 'true to finish, false to retry.' },
+                note: { type: 'string', description: 'Optional non-persisted decision note.' },
+            },
+            output: {
+                schema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: ACK_STATUSES }, error: { type: 'string' } } },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            async execute(args) {
+                const store = getStore();
+                if (!store)
+                    return { error: NOT_RUNNING };
+                const raw = args.ok ? store.ack(args.event_id) : store.nack(args.event_id);
+                const status = typeof raw === 'string' && ACK_STATUSES.includes(raw)
+                    ? raw
+                    : args.ok ? 'done' : 'pending';
+                return { status };
+            },
+            presentCall(args) { return { card: 'generic', title: 'Acknowledge lark inbox message', kind: 'read', rawInput: args }; },
+        }),
+    ];
+}
+export function registerInboxTools(ctx, getStore) {
+    return registerResources(own => {
+        for (const tool of createInboxTools(getStore))
+            own(ctx.tools.register(tool));
+    });
+}

package/lib/types/host/services/lark-inbox/wizard.d.ts

@@ -0,0 +1,62 @@
+/** Host-side lark-cli credential wizard. */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+export declare class WizardSettingsUnavailableError extends Error {
+    readonly code = "WIZARD_SETTINGS_UNAVAILABLE";
+    constructor();
+}
+export type WizardPhase = {
+    phase: 'idle';
+} | {
+    phase: 'awaiting-browser';
+    mode: 'new';
+    verificationUrl: string;
+    qrFilePath: string | null;
+} | {
+    phase: 'awaiting-secret';
+    mode: 'bind';
+    appId: string;
+    consoleUrl: string;
+} | {
+    phase: 'done';
+    appId: string;
+    needsSecretPaste: boolean;
+} | {
+    phase: 'failed';
+    error: string;
+};
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export interface LarkWizardOptions {
+    settingsWrite(patch: {
+        appId?: string;
+        appSecret?: string;
+    }): Promise<void>;
+    log?(level: 'info' | 'warn' | 'error', message: string): void;
+    larkCli?: string;
+    qrDir?: string;
+    spawn?: SpawnFn;
+}
+export declare function writeWithConflictRetry(write: () => Promise<void>): Promise<void>;
+export declare class LarkWizard {
+    private readonly options;
+    private readonly cli;
+    private readonly qrDir;
+    private readonly spawn;
+    private readonly log;
+    private current;
+    private child;
+    constructor(options: LarkWizardOptions);
+    state(): WizardPhase;
+    startNew(): Promise<{
+        verificationUrl: string;
+        qrFilePath: string | null;
+    }>;
+    startBind(appId: string): {
+        consoleUrl: string;
+    };
+    finishBind(appSecret: string): Promise<void>;
+    cancel(): Promise<void>;
+    private generateQr;
+    private completeInit;
+    private configShowAppId;
+}
+//# sourceMappingURL=wizard.d.ts.map

package/lib/types/host/services/lark-inbox/wizard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/lark-inbox/wizard.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAE5C,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAK7F,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,iCAAgC;;CAK9C;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,KAAK,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9F;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAA;AAEvG,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3E,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAyBD,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtF;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuC;IAC3D,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,KAAK,CAA0B;gBAE3B,OAAO,EAAE,iBAAiB;IAQtC,KAAK,IAAI,WAAW;IAEd,QAAQ,IAAI,OAAO,CAAC;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAmCjF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAM1C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B,OAAO,CAAC,UAAU;YAQJ,YAAY;IAwB1B,OAAO,CAAC,eAAe;CAmBxB"}