dsh-lark-agent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-larkbot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+<img src="https://raw.githubusercontent.com/Nirvana-Jie/dsh-larkbot/main/assets/plugin-icon.png" width="80" align="right" alt="dsh-larkbot icon">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-larkbot
+
+[中文](https://github.com/Nirvana-Jie/dsh-larkbot/blob/main/README_zh.md)
+
+[![npm version](https://img.shields.io/npm/v/dsh-lark-agent)](https://www.npmjs.com/package/dsh-lark-agent)
+
+**Reach your [DeepSeek Harness](https://www.deepseek.com/harness/) assistant from Feishu / Lark when you're away from your computer.**
+
+dsh-larkbot (npm package [`dsh-lark-agent`](https://www.npmjs.com/package/dsh-lark-agent)) adds a Feishu / Lark private chat to a running DeepSeek Harness: hand off tasks, talk through plans, and pick up earlier topics from your phone. Feishu gets its own sessions and never takes over chats already open in the desktop app or on the web.
+
+[![dsh-larkbot illustrated walkthrough (Feishu chat redrawn with demo data, not a screen recording): from the Harness settings page into a Feishu private chat that returns chart and form cards](https://raw.githubusercontent.com/Nirvana-Jie/dsh-larkbot/main/assets/readme/intro.gif)](https://github.com/Nirvana-Jie/dsh-larkbot/blob/main/assets/readme/intro.mp4)
+
+## Install / Update
+
+Before you start:
+
+- DeepSeek Harness is running, can chat, and has a default model selected: PC App `0.2.1-rc.2`, or Web / `dsh` CLI `0.1.1-rc.2`.
+- The official Lark CLI is installed on the same machine **before** you enable the plugin (needs Node.js / npm):
+
+  ```sh
+  npm install -g @larksuite/cli@1.0.98
+  lark-cli --version
+  ```
+
+  Don't run `lark-cli config init` or `lark-cli auth login`: the plugin creates its own dedicated CLI profile when you scan, and `config init` can overwrite existing profiles.
+
+### Install on the DeepSeek Harness desktop app
+
+In the sidebar, open **插件 → 添加插件** (Plugins → Add plugin), enter `dsh-lark-agent`, click **安装** (Install), then **立即启用** (Enable now). Restart if the app asks.
+
+<img src="https://raw.githubusercontent.com/Nirvana-Jie/dsh-larkbot/main/assets/readme/desktop-install-02.jpg" width="720" alt="The Add plugin dialog in the DeepSeek Harness desktop app">
+
+### Install with the `dsh` CLI
+
+[`dsh plugin`](https://www.npmjs.com/package/@deepseek-ai/dsh) runs pnpm, so pnpm must be on your PATH:
+
+```sh
+dsh plugin --profile web add dsh-lark-agent --allow-build=protobufjs
+```
+
+Then restart `dsh web`.
+
+> [!NOTE]
+> `--allow-build=protobufjs` lets a dependency of the Lark SDK run its install script. Without it, pnpm 11 stops with `ERR_PNPM_IGNORED_BUILDS` and dsh does not enable the plugin. If that already happened, run:
+>
+> ```sh
+> dsh plugin --profile web approve-builds '!protobufjs'
+> ```
+>
+> The `!` skips that optional script (it only prints a version hint) and lets dsh finish enabling the plugin. Then restart `dsh web`.
+
+### Update
+
+1. On the Feishu settings page, click **暂停连接** (pause) and back up as described in [Upgrade](https://github.com/Nirvana-Jie/dsh-larkbot/blob/main/DEVELOPMENT.md#升级).
+2. Desktop app: the Add plugin dialog says third-party plugins must be uninstalled before a new version is installed, so uninstall `dsh-lark-agent` on the Plugins page and add it again (this in-app upgrade hasn't been tested end to end yet; an earlier source build is listed as `dsh-larkbot`). CLI: run `dsh plugin --profile web update dsh-lark-agent@latest`, then restart `dsh web`.
+3. Click **恢复连接** (resume) and check that the bot replies.
+
+## Connect Feishu
+
+Button labels are quoted in Chinese, as they appear, with an English gloss.
+
+1. Open the Feishu settings page — desktop app: **设置 → 内置插件 → 飞书** (Settings → Built-in plugins → Feishu); web: **设置 → 插件 → 飞书** (Settings → Plugins → Feishu) — and click **扫码创建并连接** (scan to create and connect).
+2. Scan the QR code with your own Feishu account and approve. If your organization requires admin approval, click **重新检查** (check again) once it is approved.
+3. Click **打开飞书私聊** (open private chat) and, from the account that scanned, send the pairing word (`DSH-…`, valid for 10 minutes) as a plain-text message on its own, exactly as shown. If asked, confirm with **这是我，完成连接** (this is me).
+4. When the page shows **已连接** (connected), send the bot a message.
+
+The Feishu entry works only while the host is online: not when the app is closed, the web host is stopped, or the computer sleeps.
+
+## What it can do
+
+| In Feishu, you… | The assistant… |
+| --- | --- |
+| Send a request | Shows a `Typing` reaction while it works (on by default for new bots), then replies in segments |
+| Say "lead with the conclusion from now on" | Remembers the preference |
+| Keep chatting, or use `/sessions`, `/new` | Continues the topic, returns to an earlier one, or starts fresh |
+| Ask for a bar chart of some numbers | Replies with a native Feishu chart card |
+| Ask it to let you pick between options first | Sends a form card and continues once you submit |
+| Ask for an architecture diagram or a report | Creates a Feishu doc (with a whiteboard for diagrams) shared read-only with you alone; in App `0.2.1-rc.2`, opening that Feishu session in the app also shows a local preview |
+| Use `/model`, `/thinking` | Switches between the host's configured models and thinking depth |
+
+By default it answers only your own private chat. Sessions and memory stay on the computer running Harness; messages pass through Feishu and your model provider.
+
+## Good to know
+
+- **More docs**: commands, privacy, upgrades, the chat bottom menu, team deployment and troubleshooting are in [DEVELOPMENT.md](https://github.com/Nirvana-Jie/dsh-larkbot/blob/main/DEVELOPMENT.md) (Chinese).
+- **Compatibility**: verified with PC App `0.2.1-rc.2` and `dsh` CLI / Web `0.1.1-rc.2`; other versions, platforms and tenants are not yet verified.
+- **Language**: the settings page, the bot's built-in messages (`/help`, status text, card buttons, bottom menu) and the intro video are in Chinese.
+
+## License
+
+[MIT](https://github.com/Nirvana-Jie/dsh-larkbot/blob/main/LICENSE). DeepSeek and Feishu / Lark brand assets belong to their owners and are not covered by the MIT license; this is an independent open-source plugin, not an official product.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: im-larkbot
+      name: dsh-lark-agent
+      config:
+        configFile: ''

package/dist/artifact-publisher.d.ts

@@ -0,0 +1,28 @@
+import { type PlatformRunner } from './onboarding/lark-platform.js';
+import { type PublishedArtifact, type SavedArtifact } from './artifacts.js';
+export interface ArtifactPublisher {
+    preflight(diagram: boolean, signal: AbortSignal): Promise<void>;
+    publish(artifact: SavedArtifact, ownerId: string, signal: AbortSignal, recordDocument: (id: string) => Promise<void>): Promise<PublishedArtifact>;
+    verify(remote: PublishedArtifact, ownerId: string, signal: AbortSignal): Promise<void>;
+}
+/** Only controlled, private outputs are published. Neither model data nor public API callers choose an endpoint or an audience. */
+export declare class LarkArtifactPublisher implements ArtifactPublisher {
+    private readonly profile;
+    private readonly botOpenId;
+    private readonly run;
+    private brand;
+    private appId?;
+    constructor(profile: string, botOpenId: string, options?: {
+        executable?: string;
+        run?: PlatformRunner;
+    });
+    private json;
+    private api;
+    preflight(diagram: boolean, signal: AbortSignal): Promise<void>;
+    private loadIdentity;
+    private access;
+    verify(remote: PublishedArtifact, ownerId: string, signal: AbortSignal): Promise<void>;
+    publish(saved: SavedArtifact, ownerId: string, signal: AbortSignal, recordDocument: (id: string) => Promise<void>): Promise<PublishedArtifact>;
+    private existingDiagram;
+    private preview;
+}

package/dist/artifact-publisher.js

@@ -0,0 +1,246 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { commandRunner } from './onboarding/lark-platform.js';
+import { diagramMermaid, plainRecord, presentationDraft, PresentationError } from './presentation.js';
+import { publishedArtifact } from './artifacts.js';
+import { documentScopesReady } from './rich-scopes.js';
+const TOKEN = /^[A-Za-z0-9_-]{1,128}$/;
+const PRIVATE_PERMISSIONS = { external_access_entity: 'closed', link_share_entity: 'closed',
+    manage_collaborator_entity: 'collaborator_full_access', share_entity: 'same_tenant',
+    security_entity: 'only_full_access', copy_entity: 'only_full_access', comment_entity: 'anyone_can_edit' };
+const failed = () => new PresentationError('云端作品尚未确认完成，已保留本地内容。请勿重复创建；可在本机检查作品状态。');
+function token(value) { if (typeof value !== 'string' || !TOKEN.test(value))
+    throw failed(); return value; }
+function elements(value) { return [{ text_run: { content: value } }]; }
+function textBlock(value, heading = false) { return heading ? { block_type: 4, heading2: { elements: elements(value) } } : { block_type: 2, text: { elements: elements(value) } }; }
+/** Only controlled, private outputs are published. Neither model data nor public API callers choose an endpoint or an audience. */
+export class LarkArtifactPublisher {
+    profile;
+    botOpenId;
+    run;
+    brand = 'feishu';
+    appId;
+    constructor(profile, botOpenId, options = {}) {
+        this.profile = profile;
+        this.botOpenId = botOpenId;
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(profile) || !/^ou_[A-Za-z0-9_-]{1,128}$/.test(botOpenId))
+            throw failed();
+        // A bot lease cannot be released until cancelled publisher children actually close.
+        this.run = options.run ?? commandRunner(options.executable ?? 'lark-cli', 30_000, 1_048_576, true);
+    }
+    async json(args, signal, stdin, cwd) {
+        signal.throwIfAborted();
+        try {
+            const result = plainRecord(JSON.parse(await this.run(['--profile', this.profile, ...args, '--as', 'bot', '--format', 'json'], { signal, stdin, cwd })));
+            signal.throwIfAborted();
+            if (result.ok !== true || result.identity !== 'bot' || result.dry_run === true)
+                throw failed();
+            return plainRecord(result.data);
+        }
+        catch {
+            if (signal.aborted)
+                signal.throwIfAborted();
+            throw failed();
+        }
+    }
+    api(method, path, signal, data, params) {
+        return this.json(['api', method, path, ...(params ? ['--params', JSON.stringify(params)] : []), ...(data ? ['--data', '-'] : [])], signal, data ? JSON.stringify(data) : undefined);
+    }
+    async preflight(diagram, signal) {
+        const scopes = await this.api('GET', '/open-apis/application/v6/scopes', signal);
+        if (!Array.isArray(scopes.scopes) || scopes.scopes.length > 3000)
+            throw failed();
+        const granted = scopes.scopes.map(plainRecord).filter(scope => scope.grant_status === 1).map(scope => scope.scope_name).filter((name) => typeof name === 'string');
+        if (!documentScopesReady(granted, diagram))
+            throw new PresentationError('这个机器人的文档权限尚未就绪。请在 dsh 设置 → 飞书中点击“补充默认权限”，扫码确认后再点这张卡片。内容已保存在本地。');
+        await this.loadIdentity(signal);
+    }
+    async loadIdentity(signal) {
+        // This metadata command does not read secrets or change the default profile.
+        const profiles = JSON.parse(await this.run(['profile', 'list'], { signal }));
+        if (!Array.isArray(profiles))
+            throw failed();
+        const selected = profiles.map(plainRecord).find(profile => profile.name === this.profile);
+        if (!selected || !['feishu', 'lark'].includes(selected.brand)
+            || typeof selected.appId !== 'string' || !/^cli_[A-Za-z0-9_-]{1,128}$/.test(selected.appId))
+            throw failed();
+        this.brand = selected.brand;
+        this.appId = selected.appId;
+    }
+    async access(documentId, ownerId, signal, ownerMayBeMissing = false) {
+        const permissions = await this.api('GET', `/open-apis/drive/v2/permissions/${token(documentId)}/public`, signal, undefined, { type: 'docx' });
+        const settings = plainRecord(permissions.permission_public);
+        if (Object.entries(PRIVATE_PERMISSIONS).some(([key, value]) => settings[key] !== value))
+            throw failed();
+        const members = await this.api('GET', `/open-apis/drive/v1/permissions/${documentId}/members`, signal, undefined, { type: 'docx', fields: 'type' });
+        if (!Array.isArray(members.items) || members.items.length > 2 || members.has_more === true)
+            throw failed();
+        let foundOwner = false;
+        for (const value of members.items) {
+            const member = plainRecord(value);
+            // Bot-created root documents list their owning application by appid, not the IM bot's open_id.
+            if (this.appId && member.member_type === 'appid' && member.member_id === this.appId && member.perm === 'full_access')
+                continue;
+            if (member.member_type !== 'openid')
+                throw failed();
+            if (member.member_id === this.botOpenId && member.perm === 'full_access')
+                continue;
+            if (ownerId && member.member_id === ownerId && member.perm === 'view' && member.type === 'user' && !foundOwner) {
+                foundOwner = true;
+                continue;
+            }
+            throw failed();
+        }
+        if (ownerId && !foundOwner && !ownerMayBeMissing)
+            throw failed();
+        return foundOwner;
+    }
+    async verify(remote, ownerId, signal) {
+        if (!/^ou_[A-Za-z0-9_-]{1,128}$/.test(ownerId) || ownerId === this.botOpenId)
+            throw failed();
+        await this.loadIdentity(signal);
+        await this.access(publishedArtifact(remote).documentId, ownerId, signal);
+    }
+    async publish(saved, ownerId, signal, recordDocument) {
+        if (!/^ou_[A-Za-z0-9_-]{1,128}$/.test(ownerId) || ownerId === this.botOpenId || saved.publication !== 'publishing')
+            throw failed();
+        const draft = presentationDraft(saved.draft);
+        if (draft.kind !== 'report' && draft.kind !== 'diagram')
+            throw failed();
+        signal.throwIfAborted();
+        if (!this.appId)
+            await this.loadIdentity(signal);
+        const children = [textBlock(draft.title, true), textBlock(draft.summary), ...(draft.kind === 'diagram'
+                ? [{ block_type: 43, board: { align: 2 } }]
+                : draft.content.sections.flatMap(section => [textBlock(section.heading, true), textBlock(section.body)]))];
+        // No sensitive title or content leaves this machine before private ACLs have been verified.
+        let documentId;
+        let existingChildren;
+        if (saved.pendingDocumentId) {
+            documentId = token(saved.pendingDocumentId);
+            // Reconcile only the exact controlled snapshot; never append to partially written or edited content.
+            const blocks = await this.api('GET', `/open-apis/docx/v1/documents/${documentId}/blocks`, signal, undefined, { page_size: 50 });
+            if (blocks.has_more === true || !Array.isArray(blocks.items) || !blocks.items.length)
+                throw failed();
+            const root = plainRecord(blocks.items[0]);
+            if (root.block_id !== documentId || root.block_type !== 1 || (root.children !== undefined && !Array.isArray(root.children)))
+                throw failed();
+            if (blocks.items.length > 1) {
+                if (!Array.isArray(root.children) || root.children.length !== children.length || blocks.items.length !== children.length + 1)
+                    throw failed();
+                existingChildren = root.children.map(id => plainRecord(blocks.items.find(value => plainRecord(value).block_id === id)));
+                for (const [i, block] of existingChildren.entries()) {
+                    const expected = children[i];
+                    if (block.block_type !== expected.block_type || (Array.isArray(block.children) && block.children.length))
+                        throw failed();
+                    if (block.block_type !== 43) {
+                        const field = block.block_type === 4 ? 'heading2' : 'text', elements = plainRecord(block[field]).elements;
+                        const expectedText = plainRecord(expected[field]).elements[0].text_run.content;
+                        if (!Array.isArray(elements) || elements.length !== 1 || plainRecord(plainRecord(elements[0]).text_run).content !== expectedText)
+                            throw failed();
+                    }
+                }
+            }
+            else if (Array.isArray(root.children) && root.children.length)
+                throw failed();
+        }
+        else {
+            const created = await this.api('POST', '/open-apis/docx/v1/documents', signal, { title: 'dsh 的作品' });
+            documentId = token(plainRecord(created.document).document_id);
+            await recordDocument(documentId);
+            await this.api('PATCH', `/open-apis/drive/v2/permissions/${documentId}/public`, signal, PRIVATE_PERMISSIONS, { type: 'docx' });
+        }
+        const alreadyGranted = await this.access(documentId, saved.pendingDocumentId ? ownerId : undefined, signal, true);
+        const stable = (stage) => createHash('sha256').update(`${saved.id}:${stage}`).digest('hex').slice(0, 40);
+        // Text runs are inert. Do not use DocxXML/Markdown importers that may fetch URLs or @files.
+        const written = existingChildren ? { children: existingChildren } : await this.api('POST', `/open-apis/docx/v1/documents/${documentId}/blocks/${documentId}/children`, signal, { children, index: -1 }, { client_token: stable('blocks'), document_revision_id: -1 });
+        if (!Array.isArray(written.children) || written.children.length !== children.length)
+            throw failed();
+        let boardId, imageKey;
+        if (draft.kind === 'diagram') {
+            const board = written.children.map(plainRecord).find(block => block.block_type === 43);
+            boardId = token(plainRecord(board?.board).token);
+            if (!existingChildren || !await this.existingDiagram(boardId, draft.content, signal)) {
+                const imported = await this.json(['whiteboard', '+update', '--whiteboard-token', boardId,
+                    '--input_format', 'mermaid', '--source', '-', '--idempotent-token', stable('diagram')], signal, diagramMermaid(draft.content));
+                // Whiteboard node IDs are coordinates such as "t1:2", unlike document/board resource tokens.
+                if (typeof imported.created_node_id !== 'string' || !/^[A-Za-z0-9_:-]{1,128}$/.test(imported.created_node_id))
+                    throw failed();
+            }
+            // Preview is cosmetic; failure must not create a second document or block an otherwise verified link.
+            try {
+                imageKey = await this.preview(boardId, signal);
+            }
+            catch {
+                signal.throwIfAborted();
+            }
+        }
+        if (!alreadyGranted)
+            await this.api('POST', `/open-apis/drive/v1/permissions/${documentId}/members`, signal, { member_type: 'openid', member_id: ownerId, perm: 'view', type: 'user' }, { type: 'docx' });
+        await this.access(documentId, ownerId, signal);
+        return publishedArtifact({ documentId, url: `https://www.${this.brand === 'lark' ? 'larksuite.com' : 'feishu.cn'}/docx/${documentId}`,
+            ...(boardId ? { boardId } : {}), ...(imageKey ? { imageKey } : {}) });
+    }
+    async existingDiagram(boardId, diagram, signal) {
+        const data = await this.api('GET', `/open-apis/board/v1/whiteboards/${boardId}/nodes`, signal);
+        if (!Array.isArray(data.nodes) || data.has_more === true)
+            throw failed();
+        if (!data.nodes.length)
+            return false;
+        const nodes = data.nodes.map(plainRecord), sections = nodes.filter(node => node.type === 'section');
+        if (sections.length !== 1 || nodes.length !== 1 + diagram.nodes.length + diagram.edges.length)
+            throw failed();
+        const section = sections[0], syntax = plainRecord(section.syntax);
+        if (syntax.syntax_type !== 2 || syntax.code !== diagramMermaid(diagram))
+            throw failed();
+        const shapes = nodes.filter(node => node.type === 'composite_shape'), labels = new Map();
+        for (const shape of shapes) {
+            const label = plainRecord(shape.text).text;
+            if (typeof label !== 'string' || typeof shape.id !== 'string' || shape.parent_id !== section.id || labels.has(shape.id))
+                throw failed();
+            labels.set(shape.id, label);
+        }
+        const same = (a, b) => JSON.stringify(a.sort()) === JSON.stringify(b.sort());
+        if (!same([...labels.values()], diagram.nodes.map(node => node.label)))
+            throw failed();
+        const edges = nodes.filter(node => node.type === 'connector').map(node => {
+            if (node.parent_id !== section.id)
+                throw failed();
+            const connector = plainRecord(node.connector), from = labels.get(plainRecord(connector.start_object).id), to = labels.get(plainRecord(connector.end_object).id);
+            const captions = connector.captions === undefined ? [] : plainRecord(connector.captions).data;
+            if (!from || !to || !Array.isArray(captions) || captions.length > 1)
+                throw failed();
+            const label = captions.length ? plainRecord(captions[0]).text : '';
+            if (typeof label !== 'string')
+                throw failed();
+            return JSON.stringify([from, to, label]);
+        });
+        if (!same(edges, diagram.edges.map(edge => JSON.stringify([diagram.nodes.find(node => node.id === edge.from).label, diagram.nodes.find(node => node.id === edge.to).label, edge.label ?? '']))))
+            throw failed();
+        return true;
+    }
+    async preview(boardId, signal) {
+        const directory = await mkdtemp(join(tmpdir(), 'dsh-board-preview-'));
+        try {
+            await this.json(['api', 'GET', `/open-apis/board/v1/whiteboards/${boardId}/download_as_image`, '--output', 'preview.bin'], signal, undefined, directory);
+            const file = join(directory, 'preview.bin'), info = await stat(file);
+            if (!info.isFile() || info.size < 24 || info.size > 5 * 1024 * 1024)
+                return;
+            const image = await readFile(file);
+            // Only accept PNG with bounded dimensions here. SVG is never evaluated, and other formats keep a link-only card.
+            if (!image.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) || image.toString('ascii', 12, 16) !== 'IHDR'
+                || image.readUInt32BE(16) > 6000 || image.readUInt32BE(20) > 6000 || !image.readUInt32BE(16) || !image.readUInt32BE(20))
+                return;
+            const uploaded = await this.json(['api', 'POST', '/open-apis/im/v1/images', '--data', '{"image_type":"message"}', '--file', 'image=preview.bin'], signal, undefined, directory);
+            if (typeof uploaded.image_key !== 'string' || !/^img_[A-Za-z0-9_-]{1,200}$/.test(uploaded.image_key))
+                return;
+            return uploaded.image_key;
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=artifact-publisher.js.map

package/dist/artifacts.d.ts

@@ -0,0 +1,44 @@
+import { type PresentationDraft } from './presentation.js';
+export interface ArtifactContext {
+    ownerKey: string;
+    conversationKey: string;
+    sessionId: string;
+}
+export interface PublishedArtifact {
+    documentId: string;
+    boardId?: string;
+    url: string;
+    imageKey?: string;
+}
+export interface SavedArtifact extends ArtifactContext {
+    id: string;
+    rootId: string;
+    createdAt: number;
+    draft: PresentationDraft;
+    publication: 'local' | 'publishing' | 'ready' | 'uncertain';
+    remote?: PublishedArtifact;
+    /** Safe recovery evidence; never shown as a link until the ACL is verified. */
+    pendingDocumentId?: string;
+    submitted?: boolean;
+}
+export declare function publishedArtifact(value: unknown): PublishedArtifact;
+/** Owned by the bot state lock. Snapshots and publication claims survive restart; paths and secrets never enter this file. */
+export declare class ArtifactStore {
+    private readonly directory;
+    private rows;
+    private tail;
+    private uncertain;
+    private constructor();
+    static open(directory: string): Promise<ArtifactStore>;
+    private write;
+    list(ctx: ArtifactContext): Promise<SavedArtifact[]>;
+    get(ctx: ArtifactContext, id: string): Promise<SavedArtifact | undefined>;
+    add(ctx: ArtifactContext, requestId: string, draftValue: PresentationDraft): Promise<SavedArtifact>;
+    claimPublish(ctx: ArtifactContext, id: string): Promise<SavedArtifact>;
+    publication(ctx: ArtifactContext, id: string, update: {
+        documentId?: string;
+        remote?: PublishedArtifact;
+        uncertain?: boolean;
+    }): Promise<void>;
+    submit(ctx: ArtifactContext, id: string, input: unknown): Promise<string>;
+}