@sleep2agi/agent-network 2.3.0-preview.8 → 2.3.0-preview.80

package/dist/src/im/feishu/bridge.d.ts

@@ -2,22 +2,36 @@
  * RFC-020 §2.5 / RFC-002 §2.2 — Feishu bridge worker.
  *
  * Entry point spawned by agent-node when a node profile has `channels.feishu`
- * enabled. Per Vincent 2026-06-24 decision, the first-cut is the simplified
- * "agent-node direct bridge" model, not the full commhub-gateway:
+ * enabled. This worker owns the FeishuAdapter and its WSClient connection.
  *
- *   - This worker owns the FeishuAdapter and its WSClient connection.
- *   - Inbound IM event → access whitelist gate → forward to agent-node's main
- *     `think()` via parent IPC.
- *   - think() result → adapter.send() back to the originating conversation.
+ * 🔴 There are TWO outbound paths, and which one runs is decided at line ~445:
  *
- * Differences vs RFC-020 §2.5 full commhub-gateway path:
+ *     const client = commhubClient ?? createEnvCommHubClient();
+ *     if (client) return createCommHubEventHandler(...);   // (A)
+ *     if (typeof process.send === "function") ...          // (B)
+ *
+ *   (A) CommHub task dispatch — **the default on any real node.**
+ *       `createEnvCommHubClient()` returns null only when neither COMMHUB_URL
+ *       nor ANET_HUB_URL is set, and every provisioned node has one. Replies
+ *       carry `in_reply_to`, and the correlation store tracks task status.
+ *   (B) parent IPC → agent-node's `think()` — the fallback when there is no
+ *       hub URL in env (standalone / test harness).
+ *
+ *   Both paths end at adapter.send() back to the originating conversation.
+ *
+ * 🔴 This block used to say the opposite —— verbatim:
+ *       "IM messages do NOT pass through commhub task dispatch."
+ *   That was true of the 2026-06-24 first cut, and stayed in the file after
+ *   the commhub path landed (#1252, merged 2026-08-27). It is the first thing
+ *   anyone reads in this file, so it mis-answered the question "does Feishu go
+ *   through CommHub" for at least one reader before being caught. If you change
+ *   which path is default, change these lines in the same commit.
+ *
+ * Still true of both paths (unchanged from the first cut):
  *   - No separate gateway ntok_ / dedicated commhub alias.
- *   - IM messages do NOT pass through commhub task dispatch.
- *   - Feishu messages do NOT appear in Dashboard topology / Chat.
  *
- * The full §2.9 path (meta_json columns, SSE passthrough, persisted
- * IMCorrelationStore) lands as the follow-up PR after this demo ships
- * — tracked in #182.
+ * The remaining §2.9 work (meta_json columns, SSE passthrough, Dashboard
+ * topology / Chat visibility for Feishu conversations) is tracked in #182.
  *
  * Milestones:
  *   M1: worker entry scaffold.
@@ -29,8 +43,29 @@
  *   M4: agent-node spawn integration (fork(this) wired by agent-node).
  *   M5: group @bot trigger refinement, image up/down, Docker smoke.
  */
-import type { NormalizedIMEvent } from "../types.js";
+import type { IMCorrelationStore, NormalizedIMEvent } from "../types.js";
 import { FeishuAdapter } from "./adapter.js";
+export type IMBridgeCommHubInboxMessage = {
+    id: string;
+    type?: string;
+    content: string;
+    from_session?: string;
+    in_reply_to?: string;
+    meta?: unknown;
+};
+export interface IMBridgeCommHubClient {
+    sendTask(args: {
+        alias: string;
+        task: string;
+        priority?: "high" | "normal" | "low";
+        ttlSeconds?: number;
+        meta?: unknown;
+    }): Promise<{
+        taskId: string;
+    }>;
+    getInbox(alias: string): Promise<IMBridgeCommHubInboxMessage[]>;
+    ackInbox(alias: string, messageId: string): Promise<void>;
+}
 export interface FeishuBridgeOptions {
     /** Absolute path to `.anet/nodes/<node>/channels/feishu/`. */
     channelDir: string;
@@ -44,11 +79,28 @@ export interface FeishuBridgeOptions {
      *   - stderr logger otherwise (standalone smoke debugging).
      */
     onEvent?: (event: NormalizedIMEvent) => Promise<void>;
+    /** Fatal WS failure after initial readiness (for worker lifecycle ownership). */
+    onTerminalError?: (error: Error) => void;
+    /** Persistent task/message correlation state. Defaults to channelDir/state.json. */
+    correlationStore?: IMCorrelationStore;
+    /** CommHub task transport. Defaults to COMMHUB_URL/COMMHUB_TOKEN when available. */
+    commhubClient?: IMBridgeCommHubClient;
+    /** Poll interval for CommHub replies. Defaults to 1500ms. */
+    commhubPollMs?: number;
+    /** 出站传输模式。省略时按 ANET_FEISHU_BRIDGE_MODE,再省略则 "direct"。 */
+    bridgeMode?: FeishuBridgeMode;
 }
 /** Bridge → parent: inbound IM event ready for think(). */
 export interface BridgeIncomingEnvelope {
     type: "event";
     event: NormalizedIMEvent;
+    /** Canonical outbound directory for this conversation (RFC-020 §15.1).
+     *  Single source of truth — the agent-node injects this verbatim into
+     *  the system prompt's "save files here" instruction, and the bridge
+     *  whitelist accepts files only under this directory. Computed by the
+     *  bridge from `event.conversation.conversationId` + `adapter
+     *  .connectionName`. Trailing slash included. */
+    outboundDir?: string;
 }
 /** Parent → bridge: agent reply text for a previously-forwarded event. */
 export interface BridgeReplyEnvelope {
@@ -94,6 +146,24 @@ export type WithRateLimitHandle = {
         floodKeyCount: number;
     };
 };
+/**
+ * 出站传输模式。**显式声明,不靠环境变量在场与否去猜。**
+ *
+ *   direct  — parent IPC → agent-node 的 think()。**默认。**
+ *             2026-06-24 的第一版路径,飞书消息不进 CommHub 任务分发,
+ *             也不出现在 Dashboard 拓扑 / Chat 里。
+ *   commhub — 入站事件变成一个 CommHub task,回复带 in_reply_to,
+ *             correlation store 跟踪状态。**必须显式打开。**
+ *
+ * 🔴 为什么要显式:在此之前是 `commhubClient ?? createEnvCommHubClient()` ——
+ * 有 COMMHUB_URL 就走 commhub、没有就悄悄回落 IPC。两条路径的可观测性、
+ * Dashboard 可见性、失败语义完全不同,而**运维看不出自己在哪条上**,
+ * 文件头注释也因此和代码说了相反的话长达一次发布。
+ */
+export type FeishuBridgeMode = "commhub" | "direct";
+export declare const DEFAULT_FEISHU_BRIDGE_MODE: FeishuBridgeMode;
+/** 解析模式。优先级:显式入参 > 环境变量 > 默认。非法值直接抛,不静默取默认。 */
+export declare function resolveFeishuBridgeMode(explicit?: FeishuBridgeMode, env?: NodeJS.ProcessEnv): FeishuBridgeMode;
 /**
  * IPC handler — forwards inbound events to the parent agent-node and routes
  * the parent's reply back to Feishu via the adapter. The parent contract is
@@ -118,7 +188,8 @@ export type WithRateLimitHandle = {
  *     the agent-node.log (closes the prior silent-success blindspot).
  */
 /** @internal exported for test harness; not intended for production callers. */
-export declare function createIPCEventHandler(adapter: FeishuAdapter, ttlMs: number, ackPlaceholder: boolean): (event: NormalizedIMEvent) => Promise<void>;
+export declare function createIPCEventHandler(adapter: FeishuAdapter, ttlMs: number, ackPlaceholder: boolean, correlationStore?: IMCorrelationStore): (event: NormalizedIMEvent) => Promise<void>;
+export declare function createCommHubEventHandler(nodeAlias: string, adapter: FeishuAdapter, ttlMs: number, ackPlaceholder: boolean, correlationStore: IMCorrelationStore | undefined, commhubClient: IMBridgeCommHubClient, pollMs?: number): (event: NormalizedIMEvent) => Promise<void>;
 export { FeishuAdapter } from "./adapter.js";
 export { loadFeishuChannelConfig } from "./config.js";
 export type { FeishuAccessList, FeishuChannelConfig, FeishuChannelEnv, } from "./config.js";

package/dist/src/im/feishu/config.d.ts

@@ -8,6 +8,31 @@ export interface FeishuAccessList {
     /** Feishu chat_ids the bot is permitted to listen in. */
     allowChats: string[];
 }
+/**
+ * Outbound text-reply rendering mode (RFC-020 §16). Controls how
+ * `adapter.send` handles a text/markdown payload that doesn't already
+ * carry an `imagePath` / `files[]` (those upload routes are unaffected).
+ *
+ *  - "plain" (DEFAULT): always send `msg_type:text`. Bot replies are
+ *    fully copy-pasteable in Feishu; long replies are chunked into
+ *    multiple text messages instead of being PNG-rendered. This is the
+ *    correct default for issue/code/CLI bot replies where users want
+ *    to grab the text. Vincent 2026-06-30 explicit ask: "issue 发文字".
+ *
+ *  - "card": short markdown (bold, list, link, inline code) goes via
+ *    schema 1.0 interactive card with `markdown` element — text stays
+ *    copy-friendly + gets bolds/bullets styled. Heading/table/long
+ *    fall back to plain text (no PNG). Suited to operators who want
+ *    light formatting without losing copy.
+ *
+ *  - "auto": preserve the pre-2026-06-30 behavior — markdown with
+ *    headings / tables / >2000 chars is rendered to PNG via headless
+ *    chromium (#329 path), short markdown goes to schema 1.0 card,
+ *    plain text goes to msg_type:text. Highest fidelity at the cost
+ *    of copy-paste. Opt-in for operators who genuinely need rendered
+ *    tables / heading hierarchy in chat.
+ */
+export type OutboundRenderMode = "plain" | "card" | "auto";
 export interface FeishuChannelConfig {
     appId: string;
     appSecret: string;
@@ -20,6 +45,12 @@ export interface FeishuChannelConfig {
     auditRaw: boolean;
     /** Per-task timeout in ms; default 5 min (RFC-020 §4.5). */
     taskTimeoutMs: number;
+    /**
+     * RFC-020 §16 outbound rendering mode for text replies. Default `"plain"`.
+     * See `OutboundRenderMode` for per-mode semantics. Channels that omit
+     * the field get `"plain"` — Vincent's "issue 发文字" default.
+     */
+    outboundRender: OutboundRenderMode;
     /**
      * Absolute path to the channel directory. The adapter writes downloaded
      * inbound media to `<channelDir>/media/` (M5c). Populated by the loader so

package/dist/src/im/feishu/hub-upload.d.ts

@@ -0,0 +1,88 @@
+/**
+ * RFC-020 §17 — feishu inbound bridge → hub `/api/upload` integration.
+ *
+ * Vincent 2026-06-30: cross-machine agents (e.g. TM门户运维@toodadev2)
+ * delegated by the feishu-local bot can't read inbound attachments
+ * because the only thing they get is a host-local path that doesn't
+ * exist on the receiver's filesystem. #351 already wired agent-node's
+ * receiver to prefer `file_id` and pull via `GET /api/files/<id>` when
+ * present. This module is the SENDER half: the feishu bridge uploads
+ * each downloaded inbound file to the hub via `POST /api/upload`,
+ * gets back a `file_id`, and propagates it alongside the local path.
+ *
+ * Failure mode (load-bearing): every failure path returns `null` and
+ * the caller falls back to path-only. The bridge MUST NOT crash because
+ * the hub is down / overloaded / refused a 12 MiB cap. Single-host
+ * `agent-node` Read still works on the local path; only cross-host
+ * delegation degrades, no regression vs the pre-fix baseline.
+ *
+ * Concurrency cap: a single feishu message can carry many images; bursts
+ * to /api/upload would hammer the hub rate limit (60/hour per token).
+ * `uploadFilesToHubConcurrent` caps in-flight requests at `concurrency`
+ * (default 4) so a 20-image message takes 5 sequential rounds instead
+ * of 20 simultaneous open sockets + a likely rate-limit denial.
+ */
+/**
+ * Hub upload limit, mirrors `server/src/uploads.ts:MAX_UPLOAD_BYTES`.
+ * Anything bigger is skipped at the bridge — the hub would 413 anyway.
+ */
+export declare const HUB_UPLOAD_LIMIT_BYTES: number;
+/** Default in-flight cap for `uploadFilesToHubConcurrent`. */
+export declare const DEFAULT_UPLOAD_CONCURRENCY = 4;
+/**
+ * One file uploaded to the hub. `mime` and `size` are from the local
+ * filesystem read; `file_id` and `path` come from the hub's response.
+ *
+ * `file_id` is the canonical cross-machine handle — receiving agent
+ * resolves to bytes via `GET /api/files/<file_id>`. `path` is the
+ * hub-machine-local absolute path the hub stored to; on the sender
+ * side it's purely informational (we already have the source file).
+ */
+export interface HubUploadResult {
+    file_id: string;
+    path?: string;
+    mime?: string;
+    size?: number;
+    name?: string;
+}
+export interface HubUploadOpts {
+    /** Hub base URL, no trailing slash. Defaults to env. */
+    hubUrl: string;
+    /** Bearer token (ntok_ / utok_ / atok_). Defaults to env. */
+    authToken: string;
+    /** Optional MIME hint; sniffed by filename ext otherwise. */
+    mime?: string;
+    /** Optional override filename (defaults to basename(path)). */
+    name?: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Upload one local file to `${hubUrl}/api/upload`. Returns the file
+ * descriptor on success, or `null` on any failure (caller falls back
+ * to path-only).
+ *
+ *  - File must exist + be ≤ 12 MiB. Larger → skipped silently with
+ *    a stderr warn; caller gets `null` and ships path-only.
+ *  - Auth via `Authorization: Bearer <token>`.
+ *  - `Content-Length` header is set by `fetch` when given a Blob body;
+ *    the hub validates it before consuming bytes.
+ *  - Multipart body with a single `file` field. The hub server
+ *    reads `form.get("file")` and stores under a new file_id.
+ *  - Any network error / non-2xx / malformed JSON response → null.
+ */
+export declare function uploadToHub(filePath: string, opts: HubUploadOpts): Promise<HubUploadResult | null>;
+/**
+ * Upload many files to the hub with a bounded concurrency window.
+ * Returns one result per input path, preserving order. A failed
+ * upload appears as `null` at that slot — caller composes path-only
+ * descriptors for those.
+ *
+ * Why this matters: one feishu post can carry an arbitrary number of
+ * images. Naive `Promise.all(paths.map(uploadToHub))` would open N
+ * simultaneous HTTPS sockets to the hub AND blow past the 60/hour
+ * per-token rate limit on a single message with >60 images. A
+ * concurrency cap of 4 means N/4 sequential rounds, predictable
+ * load, no head-of-line blocking on the agent's reply.
+ */
+export declare function uploadFilesToHubConcurrent(filePaths: string[], opts: HubUploadOpts, concurrency?: number): Promise<(HubUploadResult | null)[]>;

package/dist/src/im/feishu/outbound-marker.d.ts

@@ -0,0 +1,140 @@
+/**
+ * RFC-020 §15 — agent→bridge outbound file protocol.
+ *
+ * 2026-06-29 Vincent UAT: agent generated a PDF via reportlab + wrote it
+ * to `/work/feishu-attachments/<conv>/x.pdf`, then in text asked Vincent
+ * "I'm not sure if the system will auto-attach this — try another way?"
+ * The bridge has `adapter.send({files})` since #329, but no protocol
+ * told the agent how to signal "dispatch this file to the user".
+ *
+ * Convention: in its final reply, the agent emits one
+ *
+ *     [[send-file:/abs/path]]
+ *
+ * marker per file (one per line, end of reply). The bridge:
+ *
+ *   1. extracts every `[[send-file:...]]` token,
+ *   2. strips them from the user-visible text,
+ *   3. validates each path against an allowed-outbound-root whitelist
+ *      (`/work/feishu-attachments/<conn>/<chat>/` — same per-conversation
+ *      directory the LLM has Write access to under Layer B),
+ *   4. checks the file exists, is non-empty, and ≤ 30 MB (Feishu file_v1
+ *      upper bound),
+ *   5. magic-byte sniffs to choose `image_key` vs `file_key` upload route,
+ *   6. dispatches each file via `adapter.send({files:[...]})`,
+ *   7. emits a friendly fallback if validation fails — never the raw error.
+ *
+ * Pure module — no I/O, no IM SDK calls. The parser returns the cleaned
+ * text + a structured list of file requests; bridge.ts is responsible
+ * for filesystem checks and dispatching.
+ */
+/**
+ * One outbound-file request parsed from an agent reply.
+ *
+ *  - `raw`: the bytes between `[[send-file:` and `]]`, before any
+ *    normalization. Kept for stderr forensic.
+ *  - `normalized`: lexical-normalized absolute path (quote-strip, `..`
+ *    collapse, `//` collapse, `./` resolution against cwd). The
+ *    `validatedAbsolute` field is set later by the bridge after the
+ *    realpath / whitelist / exists check.
+ */
+export interface OutboundFileRequest {
+    raw: string;
+    normalized: string;
+}
+export interface MarkerParseResult {
+    /** Reply text with all `[[send-file:...]]` markers removed + adjacent
+     *  whitespace collapsed. May be empty (file-only reply). */
+    cleanedText: string;
+    /** Files in source order. Caller-side validation happens after. */
+    files: OutboundFileRequest[];
+}
+/**
+ * Lexically normalize a path token from the marker. NOT a full
+ * symlink/realpath resolver — bridge does that after this returns.
+ *
+ *  - Trim leading / trailing whitespace.
+ *  - Strip one layer of matching quotes (`"/x"` / `'/x'` → `/x`).
+ *  - `.` and `..` segments collapse via `path.posix.normalize`.
+ *  - Repeated `/` collapse.
+ *
+ * Returns an absolute path or the empty string if the input cannot be
+ * interpreted as an absolute path token (caller drops empties).
+ */
+export declare function normalizeMarkerPath(raw: string): string;
+/**
+ * Parse an agent reply into cleaned text + outbound-file requests.
+ *
+ * Empty / null input returns `{cleanedText: "", files: []}` so callers
+ * can safely pipe through without defensive checks.
+ *
+ * Marker-only reply (no surrounding text) returns `cleanedText: ""` —
+ * caller should NOT send an empty text message in that case; they only
+ * dispatch the files.
+ *
+ * Multiple markers on one reply are all captured. Adjacent whitespace
+ * around stripped markers is collapsed (no double blank lines).
+ */
+export declare function parseOutboundMarkers(reply: string | null | undefined): MarkerParseResult;
+export { OUTBOUND_ROOT, feishuConvKey, feishuOutboundDir } from "./outbound-paths.js";
+/**
+ * Validate a normalized absolute path against the per-conversation
+ * whitelist + size + existence checks. Returns null on success or a
+ * Chinese user-friendly reason on failure (the same string can be
+ * surfaced as a fallback text reply when ALL files fail validation).
+ *
+ * Filesystem-touching — bridge calls this AFTER `parseOutboundMarkers`.
+ *
+ * Two API shapes accepted (overload):
+ *
+ *   1. **Preferred**: caller passes `expectedDir` — the precomputed
+ *      `/work/feishu-attachments/<connectionName>/<convKey>/` value
+ *      from `feishuOutboundDir`. This guarantees what the agent was
+ *      TOLD to use (via cli.ts prompt injection) matches what we
+ *      ACCEPT here — no second algorithm.
+ *
+ *   2. **Legacy**: caller passes `connectionName` + `convKey`. We
+ *      compute the prefix here via the same helper. Kept for the
+ *      single-arg unit-test ergonomics + backwards-compat (the old
+ *      bridge wire-up shape).
+ *
+ * Params:
+ *   - p: normalized absolute path candidate
+ *   - expectedDir: precomputed whitelist directory (trailing `/`)
+ *     OR
+ *   - convKey + connectionName: legacy two-piece form
+ *   - statFn: optional override for tests (defaults to fs.statSync)
+ *   - realpathFn: optional override for tests (defaults to fs.realpathSync)
+ *
+ * The whitelist check uses literal `.startsWith(expectedDir)` — the
+ * trailing slash on `expectedDir` ensures `oc_abc/` doesn't accept
+ * paths under `oc_abc_evil/`.
+ */
+export interface ValidateOpts {
+    p: string;
+    /** Precomputed prefix (with trailing `/`). Preferred over convKey+connectionName. */
+    expectedDir?: string;
+    convKey?: string;
+    connectionName?: string;
+    statFn?: (p: string) => {
+        size: number;
+    };
+    realpathFn?: (p: string) => string;
+}
+export declare function validateOutboundPath(opts: ValidateOpts): string | null;
+/**
+ * Magic-byte sniffer — picks `image` vs `file` upload route. Reads the
+ * first 16 bytes only; safe to call before commitment. Returns:
+ *
+ *   - "image" when the bytes are a PNG / JPG / GIF / WebP / BMP signature
+ *     (Feishu image_v1 supports these natively, with chat inline render).
+ *   - "file" otherwise (PDF, TXT, audio, video, archive, …).
+ *
+ * Caller supplies a Buffer (bridge reads via fs.openSync + readSync).
+ */
+export declare function sniffFileKind(buf: Buffer): "image" | "file";
+/**
+ * User-facing fallback message when ALL marker validations fail and the
+ * stripped text is empty (would leave the user with no reply at all).
+ */
+export declare const ALL_FILES_FAILED_FALLBACK = "[\u6587\u4EF6\u9644\u4EF6\u53D1\u9001\u5931\u8D25] \u6211\u51C6\u5907\u597D\u4E86\u6587\u4EF6\u4F46\u5206\u53D1\u65F6\u51FA\u4E86\u95EE\u9898\u2014\u2014\u7A0D\u540E\u518D\u8BD5\u6216\u6362\u79CD\u65B9\u5F0F\u3002";

package/dist/src/im/feishu/outbound-paths.d.ts

@@ -0,0 +1,50 @@
+/**
+ * RFC-020 §15.1 — feishu outbound/attachment path helpers (SHARED).
+ *
+ * Single source of truth for `/work/feishu-attachments/<conn>/<convKey>/`
+ * naming. Used by:
+ *
+ *   - `adapter.ts` inbound `downloadImage` (subdir for received images),
+ *   - `bridge.ts` outbound marker whitelist (where the agent may write),
+ *   - `worker.ts` outbound envelope (the concrete path injected into the
+ *     agent's prompt, so what we tell the agent matches what we accept).
+ *
+ * 2026-06-29 Vincent UAT: prior to this module, the inbound downloader
+ * used `conversationId.replace(/[^a-zA-Z0-9_-]/g, "_")` and the outbound
+ * bridge whitelist used `sender.id` for DMs / `chatId` for groups. The
+ * two algorithms diverged — agent learned the inbound oc_<chat>/ layout
+ * from incoming attachments, then wrote outbound files to the same
+ * oc_<chat>/ subdir, but the bridge required ou_<userid>/. Every PDF
+ * generated by the bot was rejected. This module unifies on
+ * `conversationId` (the open_chat_id assigned by Feishu — present for
+ * DMs and groups equally).
+ */
+/**
+ * Sanitize a raw Feishu conversation id (`oc_<hex>` / occasionally
+ * `om_<id>` for DMs) into a filesystem-safe segment. Identical to the
+ * adapter.ts inbound download path policy — DO NOT CHANGE without also
+ * migrating any on-disk attachments under the old key.
+ *
+ * The regex strips anything outside `[A-Za-z0-9_-]`, replacing with `_`.
+ * Falsy / non-string input returns the empty string; caller is
+ * responsible for substituting a fallback (the empty key would resolve
+ * to `/work/feishu-attachments/<conn>//` which the path-prefix
+ * whitelist rejects cleanly).
+ */
+export declare function feishuConvKey(rawId: string | undefined | null): string;
+/**
+ * Compute the canonical per-conversation directory for outbound file
+ * dispatch + inbound attachment downloads. Trailing slash included so
+ * `.startsWith(...)` whitelist checks are unambiguous about the
+ * conversation boundary (no `oc_abc` matching `oc_abc_x`).
+ *
+ * Example:
+ *   feishuOutboundDir("feishu-local", "oc_9a7eedbba275a87999f7ee2cfb10f4cb")
+ *   → "/work/feishu-attachments/feishu-local/oc_9a7eedbba275a87999f7ee2cfb10f4cb/"
+ */
+export declare function feishuOutboundDir(connectionName: string, rawConvId: string | undefined | null): string;
+/**
+ * The fixed prefix root used as a sanity check by the marker validator.
+ * Useful for tests + for `validateOutboundPath` defense-in-depth.
+ */
+export declare const OUTBOUND_ROOT = "/work/feishu-attachments";

package/dist/src/im/feishu/outbound-route.d.ts

@@ -0,0 +1,62 @@
+/**
+ * RFC-020 §16.1 — feishu outbound route decision (pure helper).
+ *
+ * Single source of truth for the `adapter.send` decision tree that
+ * picks among text / interactive card / image (rendered PNG) / file /
+ * imagePath outputs. Extracted into a pure module so the production
+ * call site AND the unit tests can bind the same function — previously
+ * the test mirrored the decision tree in a sibling `pickRoute` helper,
+ * which would drift silently if the production tree changed.
+ *
+ * Inputs are the minimal data the decision needs:
+ *
+ *   - `text` / `imagePath` / `files` — payload from `NormalizedIMMessage`
+ *   - `forceTextOnly` — caption-mode hint (RFC-020 §15.2)
+ *   - `mode` — channel-config `outboundRender` (`"plain"` / `"card"` /
+ *     `"auto"`, RFC-020 §16)
+ *
+ * Outputs the chosen `route` plus a short `reason` string for log /
+ * debug. The CALLER (adapter.send) actually performs the upload /
+ * render side-effects keyed on the route — this function does no I/O.
+ *
+ * Behavior contract (mirrors adapter.send line-for-line, locked by
+ * `feishu-outbound-render-mode.test.ts`):
+ *
+ *   1. `imagePath` set → `image_upload`
+ *   2. `files[0].path` set → `file_upload`
+ *   3. `forceTextOnly` true → `text`
+ *   4. mode "plain" → `text` (always)
+ *   5. mode "card" → `card_short_md` iff `looksLikeMarkdown(text)` AND
+ *      NOT `shouldRenderAsImage(text)`; else `text`
+ *   6. mode "auto" → `image_render` iff `shouldRenderAsImage(text)`;
+ *      else `card_short_md` iff `looksLikeMarkdown(text)`; else `text`
+ *   7. unknown mode (defensive default-default) → `text`
+ *
+ * The production switch in adapter.send may add the actual upload /
+ * render / lark API calls keyed on the route, but the route itself
+ * is decided HERE. To change the decision, change this file.
+ */
+export type OutboundRoute = "image_upload" | "file_upload" | "text" | "card_short_md" | "image_render";
+export interface RouteInput {
+    text?: string;
+    imagePath?: string;
+    files?: {
+        name: string;
+        path?: string;
+    }[];
+    forceTextOnly?: boolean;
+    /** `outboundRender` from the channel config. Defaults to "plain" when
+     *  absent so a caller that doesn't read the config still gets the
+     *  "Vincent default" behavior. */
+    mode?: "plain" | "card" | "auto";
+}
+export interface RouteDecision {
+    route: OutboundRoute;
+    reason: string;
+}
+/**
+ * Decide the outbound route for a `NormalizedIMMessage` (or a subset
+ * of its fields). Pure — no I/O, no SDK calls; safe to call from tests
+ * directly.
+ */
+export declare function resolveOutboundRoute(input: RouteInput): RouteDecision;

package/dist/src/im/feishu/worker-lifecycle.d.ts

@@ -0,0 +1,13 @@
+interface WorkerProcessBoundary {
+    stderr: {
+        write(message: string): unknown;
+    };
+    exit(code: number): unknown;
+}
+/**
+ * A terminal WS error means this worker no longer owns a live ingress path.
+ * Exit non-zero so the parent/supervisor cannot continue advertising it as
+ * healthy. Kept separate from worker.ts so the real exit contract is testable.
+ */
+export declare function exitFeishuWorker(error: Error, boundary?: WorkerProcessBoundary): void;
+export {};