@excitedjs/feishu-channel 0.0.1 → 0.2.0-alpha.g2b7e2d09fbdc

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 excitedjs
+
+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,29 +1,64 @@
 # @excitedjs/feishu-channel
 
-The **dreamux-side channel layer**: stateful orchestration on top of
-[`@excitedjs/feishu-transport`](../feishu-transport).
+The built-in Feishu **`ChannelProvider`** for [Dreamux](../../dreamux) — the
+package behind the `builtin:feishu` provider reference. It implements the
+neutral `@excitedjs/dreamux-types` channel contract on top of
+[`@excitedjs/feishu-transport`](../feishu-transport), which stays the sole owner
+of the Lark SDK.
 
-> **Status: PR0 scaffold.** No business logic yet. See
-> [issue #25](https://github.com/excitedjs/dreamux/issues/25).
+`@excitedjs/dreamux` depends on this package by default and resolves
+`builtin:feishu` to it, so the Feishu channel ships out of the box.
 
-## Scope (when filled in by later PRs)
+## What it owns
 
-- **① Filter** — @-mention gate (`isBotAddressed`) + access gate (allowlist),
-  orchestrating the core's pure `gate()`.
-- **② Map + forward** — conversation→Codex-thread mapping (`conversationKey` →
-  thread) and forwarding inbound to the engine / outbound back to Feishu.
+- The live Feishu channel **session** (bot start/close) above raw Lark JSAPI
+  calls.
+- **Access / trust** behavior: the @-mention/allowlist gate and the chat-bots
+  store, read and written under a host-supplied state directory.
+- **Inbound normalization**: turning Feishu events into agent-facing channel
+  results, including the `<channel source="feishu" …>` envelope and
+  `<attachment>` blocks.
+- **Attachment handling**: downloading inbound attachments after the host access
+  gate allows delivery, plus cache layout, path sanitization, permissions, and
+  honest fallback references when a resource is not downloaded.
+- The Feishu MCP **tool backing**: the `reply` / `react` / `list_chat_bots`
+  tool parsing and handlers.
 
-This is dreamux's counterpart of claudemux's proxy/daemon. The two are
-symmetric but **never depend on each other** — both depend only on
-`@excitedjs/feishu-transport`. The engine (`DispatcherRuntime`) stays in
-`@excitedjs/dreamux` and implements this layer's `InboundSink` / `OutboundPort`
-interfaces, so there is no dependency cycle.
+## What it does not own
+
+- It never imports `@excitedjs/dreamux` core, and never imports the Lark SDK
+  directly — platform calls go through `@excitedjs/feishu-transport`. Both
+  boundaries are enforced by `tests/import-boundary.test.ts`.
+- Dispatcher lifecycle, agent/Codex process supervision, routing, binding state,
+  authorization, Team lifecycle, and the Feishu MCP **server descriptor** /
+  admin-method routing stay in `@excitedjs/dreamux`. The host supplies the bot
+  secret / app id and the state / cache directories; the package reconstructs no
+  Dreamux host layout or path contract.
+
+## Public API
+
+- `createFeishuChannelProvider()` plus the default-exported provider factory —
+  builds the neutral `ChannelProvider` the generic channel loader registers for
+  `builtin:feishu`. Its `createSession` returns a contract-valid `ChannelSession`
+  (`reply` / `react` / `resolveTarget` / `tools` / `handleTool` /
+  `messageBelongsToTarget`).
+- The session class plus the gate, chat-bots store, message formatter, MCP tool
+  parser, and bot helpers, used by the core adapter that drives the production
+  host-shaped session path.
+
+> Production note: `@excitedjs/dreamux` drives this package through a thin
+> core-owned adapter that uses the richer host-shaped session API (a
+> result-returning inbound submitter the reaction ledger keys off). The neutral
+> `ChannelSession.start(routes)` path is real and contract-tested, but is not the
+> production wiring today. See
+> [`.agents/decisions/npm-package-split-and-channel-targets.md`](../../../.agents/decisions/npm-package-split-and-channel-targets.md).
 
 ## Build / test
 
-Built via rush in topological order (core first):
+Built and tested via rush in topological order (dependencies first):
 
 ```sh
 node common/scripts/install-run-rush.js update
-node common/scripts/install-run-rush.js build
+node common/scripts/install-run-rush.js build --to @excitedjs/feishu-channel
+node common/scripts/install-run-rush.js test --to @excitedjs/feishu-channel
 ```

package/dist/bot.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The `FeishuBot` adapter — one per Dispatcher (D3: 1 Dispatcher = 1 Bot).
+ *
+ * Since issue #25 PR1 this is a thin adapter over `@excitedjs/feishu-transport`
+ * (the shared platform-I/O core): all Feishu SDK I/O — the inbound WebSocket,
+ * markdown→card render, content parse, the outbound message API — lives in the
+ * core, the single importer of `@larksuiteoapi/node-sdk`. This file only shapes
+ * the core's surface into the `FeishuBot` interface the server already wires:
+ *   - `start(routes)` takes one handler per Feishu event type (issue #62 seam):
+ *     `onMessage` for `im.message.receive_v1` (normalized via the core's
+ *     `parseInbound` into a `FeishuInboundEvent`) and an optional
+ *     `onBotMemberAdded` for `im.chat.member.bot.added_v1`. Each route awaits
+ *     its handler, so the server gates and submits accepted inbound before the
+ *     SDK acks.
+ *   - `send(target, text)` delegates to the core transport, preserving reply
+ *     threading / @-back metadata from the in-memory inbound batch.
+ *   - `botOpenId` surfaces the core transport's `selfId`.
+ *
+ * Tests inject a `FakeFeishuBot` via `createFakeFeishuBot()` instead of opening
+ * a live connection.
+ */
+import { type FeishuBotMemberAddedEvent, type FeishuMessageResourceFetcher, type FeishuMessageResourceRequest, type FeishuMessageResourceResponse, type FeishuTransport, type InboundResource, type Mention, type OutboundTarget, type TransportLogger } from '@excitedjs/feishu-transport';
+import type { FeishuInviteMembersInput, FeishuInviteMembersResult } from '@excitedjs/feishu-transport';
+export type { FeishuInviteMembersInput, FeishuInviteMembersResult, } from '@excitedjs/feishu-transport';
+export interface FeishuInboundEvent {
+    messageId: string;
+    chatId: string;
+    chatType: string;
+    senderId: string;
+    /**
+     * The sender's `union_id`, when Feishu provides it. Diagnostic only — it is
+     * surfaced in inbound-drop logs to help tell "same bot, different app-scoped
+     * open_id" apart from "different entity", and is never used for access
+     * gating. Absent when Feishu omits it.
+     */
+    senderUnionId?: string;
+    senderType: string;
+    /**
+     * Best-effort display name seam for future enrichers. Feishu
+     * im.message.receive_v1 does not provide this in the native event envelope,
+     * so the normal value is intentionally an empty string.
+     */
+    senderName: string;
+    messageType: string;
+    /** Raw JSON-encoded content as Feishu delivered it. */
+    rawContent: string;
+    /** Parsed text after the core's content flattening / mention substitution. */
+    parsedText: string;
+    /** Structured Feishu resources discovered in the message content. */
+    resources?: InboundResource[];
+    mentions: Mention[];
+    createTime: string;
+    /** The full original Feishu event payload (for storage / audit). */
+    raw: unknown;
+}
+export type InboundHandler = (event: FeishuInboundEvent) => void | Promise<void>;
+export type BotMemberAddedHandler = (event: FeishuBotMemberAddedEvent) => void | Promise<void>;
+/**
+ * The typed event-route seam (issue #62 Phase 1). `start` takes one handler per
+ * Feishu event type instead of a single message handler, so a new event type is
+ * wired by adding a field here and a transport route, without growing branches
+ * in `Server`. This is a small typed seam, not yet a generic
+ * `eventType -> handler` registry; if a third event type lands, promote this to
+ * a map. Each route still awaits its handler before the SDK acks
+ * (queue-before-ACK).
+ */
+export interface FeishuInboundRoutes {
+    /** `im.message.receive_v1` — a chat message. */
+    onMessage: InboundHandler;
+    /** `im.chat.member.bot.added_v1` — the bot was added to a chat. Optional. */
+    onBotMemberAdded?: BotMemberAddedHandler;
+}
+export interface FeishuSendResult {
+    /** message_id of each card sent, in order. Empty if Feishu omitted ids. */
+    messageIds: string[];
+}
+export interface FeishuBot extends FeishuMessageResourceFetcher {
+    readonly appId: string;
+    readonly botOpenId: string | undefined;
+    start(routes: FeishuInboundRoutes): Promise<void>;
+    send(target: OutboundTarget, text: string): Promise<FeishuSendResult>;
+    inviteMembers(input: FeishuInviteMembersInput): Promise<FeishuInviteMembersResult>;
+    addReaction(messageId: string, emoji: string): Promise<string>;
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
+    fetchMessageResource(request: FeishuMessageResourceRequest): Promise<FeishuMessageResourceResponse>;
+    close(): Promise<void>;
+}
+export interface CreateBotOptions {
+    appId: string;
+    appSecret: string;
+    /**
+     * Structured logger for the underlying transport's own diagnostics (Lark SDK
+     * logging, WebSocket connection lifecycle, best-effort fetch/close failures).
+     * Forwarded verbatim to `createFeishuTransport`. Omit to keep the transport's
+     * historical stderr behavior. The server injects the dispatcher's
+     * per-dispatcher channel logger here so connection/SDK lines land in
+     * `logs/feishu-channel/<id>.log` alongside the host's own channel decisions.
+     */
+    logger?: TransportLogger;
+}
+export interface CreateFeishuBotDeps {
+    createTransport?: (opts: CreateBotOptions) => FeishuTransport;
+}
+export interface ChannelOutboundTarget {
+    /** Stable channel-local conversation id. */
+    conversationId: string;
+    /** Optional channel-local source message to thread under. */
+    replyTo?: string;
+    /** Optional channel-local participants to bring into the reply. */
+    mentionUsers?: string[];
+    /** Optional host/runtime routing hint, opaque to the channel adapter. */
+    conversationKey?: string;
+}
+export declare function createFeishuBot(opts: CreateBotOptions, deps?: CreateFeishuBotDeps): FeishuBot;
+export declare function channelOutboundToFeishuTarget(target: ChannelOutboundTarget): OutboundTarget;
+export interface FakeFeishuBot extends FeishuBot {
+    readonly sentMessages: Array<{
+        chatId: string;
+        target: OutboundTarget;
+        text: string;
+        messageIds: string[];
+    }>;
+    readonly reactions: Array<{
+        messageId: string;
+        emoji: string;
+        reactionId: string;
+    }>;
+    readonly removedReactions: Array<{
+        messageId: string;
+        reactionId: string;
+    }>;
+    /** Combined add/remove timeline, in call order (tests assert ordering). */
+    readonly reactionOps: Array<{
+        op: 'add';
+        messageId: string;
+        emoji: string;
+        reactionId: string;
+    } | {
+        op: 'remove';
+        messageId: string;
+        reactionId: string;
+    }>;
+    inject(event: FeishuInboundEvent): Promise<void>;
+    injectBotMemberAdded(event: FeishuBotMemberAddedEvent): Promise<void>;
+    setSendError(err: Error | null): void;
+    setReactionError(err: Error | null): void;
+    setRemoveReactionError(err: Error | null): void;
+    setMessageResource(fileKey: string, resource: FeishuMessageResourceResponse | Error | null): void;
+}
+export declare function createFakeFeishuBot(appId?: string): FakeFeishuBot;
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}

package/dist/bot.js

@@ -0,0 +1,276 @@
+/**
+ * The `FeishuBot` adapter — one per Dispatcher (D3: 1 Dispatcher = 1 Bot).
+ *
+ * Since issue #25 PR1 this is a thin adapter over `@excitedjs/feishu-transport`
+ * (the shared platform-I/O core): all Feishu SDK I/O — the inbound WebSocket,
+ * markdown→card render, content parse, the outbound message API — lives in the
+ * core, the single importer of `@larksuiteoapi/node-sdk`. This file only shapes
+ * the core's surface into the `FeishuBot` interface the server already wires:
+ *   - `start(routes)` takes one handler per Feishu event type (issue #62 seam):
+ *     `onMessage` for `im.message.receive_v1` (normalized via the core's
+ *     `parseInbound` into a `FeishuInboundEvent`) and an optional
+ *     `onBotMemberAdded` for `im.chat.member.bot.added_v1`. Each route awaits
+ *     its handler, so the server gates and submits accepted inbound before the
+ *     SDK acks.
+ *   - `send(target, text)` delegates to the core transport, preserving reply
+ *     threading / @-back metadata from the in-memory inbound batch.
+ *   - `botOpenId` surfaces the core transport's `selfId`.
+ *
+ * Tests inject a `FakeFeishuBot` via `createFakeFeishuBot()` instead of opening
+ * a live connection.
+ */
+import { BOT_MEMBER_ADDED_EVENT_TYPE, createFeishuTransport, narrowMetaFromEvent, normalizeBotMemberAddedEvent, parseInbound, toChannelInbound, } from '@excitedjs/feishu-transport';
+/** The Feishu event_type carrying inbound chat messages. */
+const IM_MESSAGE_EVENT_TYPE = 'im.message.receive_v1';
+export function createFeishuBot(opts, deps = {}) {
+    const transport = deps.createTransport?.(opts) ??
+        createFeishuTransport({
+            appId: opts.appId,
+            appSecret: opts.appSecret,
+        }, 
+        // Forward the host's logger so the transport's own SDK / connection
+        // diagnostics fold into the per-dispatcher channel log. `undefined` keeps
+        // the transport's default stderr behavior, so always passing the option
+        // object is safe and keeps the real wiring path explicit.
+        { logger: opts.logger });
+    return {
+        get appId() {
+            return transport.appId;
+        },
+        get botOpenId() {
+            return transport.selfId;
+        },
+        async start(routes) {
+            // The core opens the WebSocket and awaits each route handler before the
+            // SDK acks; awaiting here keeps gate/submission work before ACK.
+            // `start` rejects if the connection does not come up, so the server's
+            // try/catch can fail the dispatcher loudly rather than leave it dark.
+            const table = {
+                [IM_MESSAGE_EVENT_TYPE]: async (raw) => {
+                    const event = normalizeInboundEvent(raw);
+                    if (event === null)
+                        return;
+                    await routes.onMessage(event);
+                },
+            };
+            if (routes.onBotMemberAdded !== undefined) {
+                const onBotMemberAdded = routes.onBotMemberAdded;
+                table[BOT_MEMBER_ADDED_EVENT_TYPE] = async (raw) => {
+                    const event = normalizeBotMemberAddedEvent(raw);
+                    if (event === null)
+                        return;
+                    await onBotMemberAdded(event);
+                };
+            }
+            await transport.start(table);
+        },
+        async send(target, text) {
+            const { messageIds } = await transport.send(target, text);
+            return { messageIds };
+        },
+        inviteMembers(input) {
+            return transport.inviteMembers(input);
+        },
+        addReaction(messageId, emoji) {
+            return transport.addReaction(messageId, emoji);
+        },
+        removeReaction(messageId, reactionId) {
+            return transport.removeReaction(messageId, reactionId);
+        },
+        fetchMessageResource(request) {
+            return transport.fetchMessageResource(request);
+        },
+        close() {
+            return transport.close();
+        },
+    };
+}
+export function channelOutboundToFeishuTarget(target) {
+    return {
+        chatId: target.conversationId,
+        ...(target.replyTo !== undefined
+            ? { replyToMessageId: target.replyTo }
+            : {}),
+        ...(target.mentionUsers !== undefined
+            ? { mentionUserIds: target.mentionUsers }
+            : {}),
+        ...(target.conversationKey !== undefined
+            ? { conversationKey: target.conversationKey }
+            : {}),
+    };
+}
+/**
+ * Reshape a raw `im.message.receive_v1` payload into a `FeishuInboundEvent`,
+ * using the core's `parseInbound` + `narrowMetaFromEvent` + `toChannelInbound`
+ * for content flattening and event-envelope metadata. Returns `null` for a
+ * payload missing the message_id or chat_id that make it routable.
+ */
+function normalizeInboundEvent(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const root = raw;
+    const event = (root['event'] ?? root);
+    const message = (event['message'] ?? {});
+    const messageType = message['message_type'] ?? '';
+    const rawContent = message['content'] ?? '';
+    const mentions = message['mentions'] ?? [];
+    const parsed = parseInbound({
+        message_type: messageType,
+        content: rawContent,
+        mentions,
+    });
+    const payload = toChannelInbound({
+        ...parsed,
+        meta: narrowMetaFromEvent(raw),
+    });
+    const messageId = payload.meta['message_id'] ?? '';
+    const chatId = payload.meta['chat_id'] ?? '';
+    const chatType = payload.meta['chat_type'] ?? '';
+    const senderId = payload.meta['sender_id'] ?? '';
+    const senderUnionId = payload.meta['sender_union_id'] ?? '';
+    const senderType = payload.meta['sender_type'] ?? '';
+    const createTime = payload.meta['create_time'] ?? '';
+    const senderName = extractSenderName(raw);
+    if (messageId === '' || chatId === '')
+        return null;
+    return {
+        messageId,
+        chatId,
+        chatType,
+        senderId,
+        ...(senderUnionId !== '' ? { senderUnionId } : {}),
+        senderType,
+        senderName,
+        messageType,
+        rawContent,
+        parsedText: payload.text,
+        resources: parsed.resources ?? [],
+        mentions,
+        createTime,
+        raw,
+    };
+}
+function extractSenderName(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return '';
+    const root = raw;
+    const event = asRecord(root['event']) ?? root;
+    const sender = asRecord(event['sender']);
+    if (sender === undefined)
+        return '';
+    return firstString(sender['sender_name'], sender['display_name'], sender['name'], sender['user_name']);
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string')
+            return value;
+    }
+    return '';
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function createFakeFeishuBot(appId = 'fake-bot') {
+    const sent = [];
+    let routes = null;
+    let nextMessageId = 1;
+    let nextReactionId = 1;
+    let sendError = null;
+    let reactionError = null;
+    let removeReactionError = null;
+    const messageResources = new Map();
+    const openId = `fake-open-id-${appId}`;
+    const reactions = [];
+    const removedReactions = [];
+    const reactionOps = [];
+    return {
+        appId,
+        get botOpenId() {
+            return openId;
+        },
+        async start(r) {
+            routes = r;
+        },
+        async send(target, text) {
+            if (sendError !== null) {
+                throw sendError;
+            }
+            const id = `message-fake-${nextMessageId++}`;
+            sent.push({ chatId: target.chatId, target, text, messageIds: [id] });
+            return { messageIds: [id] };
+        },
+        async inviteMembers(input) {
+            return { addedOpenIds: input.userOpenIds };
+        },
+        async addReaction(messageId, emoji) {
+            if (reactionError !== null) {
+                throw reactionError;
+            }
+            const reactionId = `reaction-fake-${nextReactionId++}`;
+            reactions.push({ messageId, emoji, reactionId });
+            reactionOps.push({ op: 'add', messageId, emoji, reactionId });
+            return reactionId;
+        },
+        async removeReaction(messageId, reactionId) {
+            if (removeReactionError !== null) {
+                throw removeReactionError;
+            }
+            removedReactions.push({ messageId, reactionId });
+            reactionOps.push({ op: 'remove', messageId, reactionId });
+        },
+        async fetchMessageResource(request) {
+            const resource = messageResources.get(request.fileKey);
+            if (resource === undefined) {
+                throw new Error(`no fake Feishu resource for key ${request.fileKey}`);
+            }
+            if (resource instanceof Error)
+                throw resource;
+            return resource;
+        },
+        async close() {
+            routes = null;
+        },
+        get sentMessages() {
+            return sent;
+        },
+        get reactions() {
+            return reactions;
+        },
+        get removedReactions() {
+            return removedReactions;
+        },
+        get reactionOps() {
+            return reactionOps;
+        },
+        async inject(event) {
+            if (routes === null)
+                throw new Error('fake bot not started');
+            await routes.onMessage(event);
+        },
+        async injectBotMemberAdded(event) {
+            if (routes === null)
+                throw new Error('fake bot not started');
+            await routes.onBotMemberAdded?.(event);
+        },
+        setSendError(err) {
+            sendError = err;
+        },
+        setReactionError(err) {
+            reactionError = err;
+        },
+        setRemoveReactionError(err) {
+            removeReactionError = err;
+        },
+        setMessageResource(fileKey, resource) {
+            if (resource === null) {
+                messageResources.delete(fileKey);
+            }
+            else {
+                messageResources.set(fileKey, resource);
+            }
+        },
+    };
+}
+//# sourceMappingURL=bot.js.map

package/dist/bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.js","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}

package/dist/chat-bots-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-dispatcher peer-bot awareness/trust store.
+ *
+ * Two sets are tracked separately, per chat_id, and they must never be
+ * conflated (issue #62 hard contract):
+ *
+ *   - `known`   — bots passively observed sending messages in an authorized
+ *                 chat. Awareness only; observing a bot NEVER grants it trust.
+ *   - `trusted` — bots introduced by an allowlisted sender running `/introduce`.
+ *                 The gate consults this set (and only this set) when deciding
+ *                 whether a peer bot's group message may be delivered.
+ *
+ * `baseline` bookkeeping records `im.chat.member.bot.added_v1` events so the
+ * host can later inject a one-shot "bots in this group" context; it is
+ * idempotent by Feishu event id. (The one-shot context injection itself is a
+ * follow-up; this store keeps the durable bookkeeping the contract needs.)
+ *
+ * One JSON file per dispatcher, keyed by chat_id, so no chat_id ever has to be
+ * sanitized into a path segment. Owner-only (0600); writes are atomic.
+ */
+export interface ChatBotsEntry {
+    /** Passively observed peer-bot open_ids — awareness only, never trust. */
+    known: string[];
+    /** Introduced peer-bot open_ids — the gate's trust set for this chat. */
+    trusted: string[];
+    /** Best-effort open_id → display name map for known/trusted bots. */
+    names: Record<string, string>;
+    /**
+     * Set when this chat has pending discovery context to inject once (a bot was
+     * added, or an `/introduce` newly trusted a bot). Consumed by the next
+     * delivered group message; see `pendingBaseline` / `clearBaselineIfCurrent`.
+     */
+    needsBaseline: boolean;
+    /**
+     * Monotonic counter bumped every time `needsBaseline` is (re)set. The deliver
+     * path snapshots it before enqueue and only clears the flag if it is still
+     * current, so a newer `/introduce` / bot-added event arriving mid-enqueue is
+     * not clobbered by a stale clear (issue #69, generation-safe one-shot clear).
+     */
+    baselineGeneration: number;
+    /** Recent bot-added event ids, for idempotent member-event handling. */
+    seenEventIds: string[];
+}
+export interface ChatBotsState {
+    version: 1;
+    chats: Record<string, ChatBotsEntry>;
+}
+export interface PeerBot {
+    openId: string;
+    name?: string;
+}
+/** The pending one-shot discovery context for one chat (issue #69). */
+export interface PendingBaseline {
+    /** Whether this chat has discovery context waiting to be injected. */
+    needsBaseline: boolean;
+    /** Snapshot of the entry's generation, for a generation-safe clear. */
+    generation: number;
+    /** The chat's trusted peer bots (open_id + best-effort name). */
+    trusted: PeerBot[];
+}
+/** Known and trusted peer bots for one chat, for the `list_chat_bots` tool. */
+export interface ChatBotsListing {
+    known: PeerBot[];
+    trusted: PeerBot[];
+}
+export declare function defaultChatBotsState(): ChatBotsState;
+/**
+ * Load the store. Unlike the access store, a corrupt or unreadable chat-bots
+ * file is not security-critical — it only affects peer-bot discovery — so a
+ * load failure degrades to an empty store rather than throwing.
+ */
+export declare function loadChatBots(stateDir: string): Promise<ChatBotsState>;
+export declare function saveChatBots(stateDir: string, state: ChatBotsState): Promise<void>;
+/** Record a passively observed peer bot as *known* (awareness only). */
+export declare function observeKnownBot(stateDir: string, chatId: string, bot: PeerBot): Promise<void>;
+/**
+ * Record peer bots introduced by an allowlisted `/introduce` as *trusted*.
+ * Trusted bots are also known. Returns the open_ids newly added to trust.
+ */
+export declare function trustIntroducedBots(stateDir: string, chatId: string, bots: PeerBot[]): Promise<string[]>;
+/**
+ * The chat's pending one-shot discovery context, snapshotted for a
+ * generation-safe clear (issue #69). The deliver path reads this before
+ * enqueue, injects the trusted bots when `needsBaseline`, and clears via
+ * `clearBaselineIfCurrent` only after a successful submission.
+ */
+export declare function pendingBaseline(stateDir: string, chatId: string): Promise<PendingBaseline>;
+/**
+ * Clear the pending-context flag only if the chat's generation still matches
+ * the snapshot taken before enqueue. A newer `/introduce` / bot-added event
+ * that arrived mid-enqueue bumps the generation, so this no-ops rather than
+ * dropping the newer pending context (issue #69).
+ */
+export declare function clearBaselineIfCurrent(stateDir: string, chatId: string, generation: number): Promise<void>;
+/** Known and trusted peer bots for one chat (the `list_chat_bots` tool). */
+export declare function listChatBots(stateDir: string, chatId: string): Promise<ChatBotsListing>;
+/** The trust set the gate consults for one chat. */
+export declare function trustedBotIds(stateDir: string, chatId: string): Promise<Set<string>>;
+/**
+ * Record an `im.chat.member.bot.added_v1` event: mark the chat as needing a
+ * baseline injection. Idempotent by event id — a redelivered event is a no-op.
+ * Returns true when the event was newly recorded.
+ */
+export declare function recordBotAdded(stateDir: string, chatId: string, eventId: string): Promise<boolean>;
+//# sourceMappingURL=chat-bots-store.d.ts.map