@sleep2agi/agent-network 2.3.0-preview.4 → 2.3.0-preview.40

package/dist/src/dashboard-managed-process.d.ts

@@ -0,0 +1,35 @@
+export type DashboardLaunchSource = "npx" | "global";
+export interface DashboardLaunchRecord {
+    schema: 1;
+    port: number;
+    listener_pid: number;
+    listener_birth: string;
+    source: DashboardLaunchSource;
+    source_key: string;
+    recorded_at: string;
+}
+export type DashboardListenerDecision = {
+    action: "start";
+} | {
+    action: "already_running";
+    pid: number;
+} | {
+    action: "terminate_owned_stale";
+    pid: number;
+    reason: "unhealthy" | "version_changed";
+} | {
+    action: "refuse";
+    reason: string;
+};
+export declare function isDashboardProcessCommand(command: string): boolean;
+export declare function decideDashboardListener(input: {
+    port: number;
+    listenerPids: number[];
+    record: DashboardLaunchRecord | null;
+    listenerBirth: string | null;
+    listenerCommand: string | null;
+    desiredSource: DashboardLaunchSource;
+    desiredSourceKey: string;
+    healthy: boolean;
+}): DashboardListenerDecision;
+export declare function parseDashboardLaunchRecord(value: unknown): DashboardLaunchRecord | null;

package/dist/src/environ-alias.d.ts

@@ -0,0 +1,14 @@
+/** Parse the environ blob (NUL-separated key=val) and return the
+ *  COMMHUB_ALIAS value if present, else null. Exported for testing. */
+export declare function parseEnvironAlias(environBlob: string): string | null;
+/** Read /proc/<pid>/environ and return the COMMHUB_ALIAS value.
+ *  Any file-read error (not-a-Linux, permission denied, race with
+ *  process exit) returns null — caller must not fail-closed on that
+ *  (the process is stale/gone/inaccessible, not our problem). */
+export declare function readEnvironAlias(pid: number): string | null;
+/** Scan /proc for pids whose COMMHUB_ALIAS env matches any of the
+ *  target aliases. Linux-only (procfs); returns null on non-Linux or
+ *  when /proc is unreadable — caller MUST fail-closed on null per
+ *  the same #180 R2 fail-closed contract as findNodeProcessesByAlias.
+ *  Self-pid + init (PID 1) are excluded. */
+export declare function findEnvironAliasMatches(aliases: Iterable<string>, selfPid: number): number[] | null;

package/dist/src/grok-attach-client.d.ts

@@ -0,0 +1,115 @@
+import type { Duplex } from "node:stream";
+export declare const GROK_ATTACH_PROTOCOL = "anet-grok-copresence-attach";
+export declare const GROK_ATTACH_PROTOCOL_VERSION = 1;
+export declare const GROK_ATTACH_DEFAULT_MAX_FRAME_BYTES: number;
+export declare const GROK_ATTACH_DEFAULT_MAX_BUFFER_BYTES: number;
+export declare const GROK_ATTACH_DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+export declare const GROK_ATTACH_DEFAULT_CLOSE_TIMEOUT_MS = 1000;
+export type GrokAttachJsonValue = null | boolean | number | string | GrokAttachJsonValue[] | {
+    [key: string]: GrokAttachJsonValue;
+};
+export interface GrokAttachHelloFrame {
+    type: "hello";
+    protocol: typeof GROK_ATTACH_PROTOCOL;
+    version: typeof GROK_ATTACH_PROTOCOL_VERSION;
+    alias: string;
+    sessionId: string;
+    [key: string]: unknown;
+}
+export interface GrokAttachOutputFrame {
+    type: "output";
+    data: string;
+    encoding: "base64";
+}
+export interface GrokAttachStatusFrame {
+    type: "status";
+    status: GrokAttachJsonValue;
+}
+export interface GrokAttachErrorFrame {
+    type: "error";
+    code: string;
+    message: string;
+    fatal: boolean;
+}
+export interface GrokAttachDetachFrame {
+    type: "detach";
+}
+export type GrokAttachServerFrame = GrokAttachHelloFrame | GrokAttachOutputFrame | GrokAttachStatusFrame | GrokAttachErrorFrame | GrokAttachDetachFrame;
+export interface GrokAttachInputFrame {
+    type: "input";
+    data: string;
+    encoding: "base64";
+}
+export interface GrokAttachResizeFrame {
+    type: "resize";
+    cols: number;
+    rows: number;
+}
+export type GrokAttachClientFrame = GrokAttachInputFrame | GrokAttachResizeFrame | GrokAttachDetachFrame;
+export interface GrokAttachInputSource {
+    on(event: "data", listener: (chunk: unknown) => void): unknown;
+    on(event: "end", listener: () => void): unknown;
+    off?(event: "data" | "end", listener: (...args: any[]) => void): unknown;
+    removeListener?(event: "data" | "end", listener: (...args: any[]) => void): unknown;
+    pause?(): unknown;
+    resume?(): unknown;
+}
+export interface GrokAttachOutputSink {
+    write(chunk: Uint8Array): boolean | void;
+    columns?: number;
+    rows?: number;
+    once?(event: "drain", listener: () => void): unknown;
+}
+export interface GrokAttachSignalSource {
+    on(event: "SIGWINCH", listener: () => void): unknown;
+    off?(event: "SIGWINCH", listener: () => void): unknown;
+    removeListener?(event: "SIGWINCH", listener: () => void): unknown;
+}
+export interface GrokAttachSocketStat {
+    uid: number;
+    isSocket(): boolean;
+    isSymbolicLink(): boolean;
+}
+export interface GrokAttachDependencies {
+    lstat?: (socketPath: string) => Promise<GrokAttachSocketStat>;
+    getuid?: () => number | undefined;
+    connect?: (socketPath: string) => Duplex;
+}
+export interface GrokAttachClientOptions {
+    socketPath: string;
+    input: GrokAttachInputSource;
+    output: GrokAttachOutputSink;
+    signalSource?: GrokAttachSignalSource;
+    terminalSize?: () => {
+        cols: number | undefined;
+        rows: number | undefined;
+    };
+    maxFrameBytes?: number;
+    maxBufferBytes?: number;
+    handshakeTimeoutMs?: number;
+    closeTimeoutMs?: number;
+    detachOnInputEnd?: boolean;
+    onHello?: (frame: GrokAttachHelloFrame) => void;
+    onStatus?: (frame: GrokAttachStatusFrame) => void;
+    onError?: (error: Error, frame?: GrokAttachErrorFrame) => void;
+    onDetach?: (frame: GrokAttachDetachFrame) => void;
+    dependencies?: GrokAttachDependencies;
+}
+export type GrokAttachCloseReason = "local-detach" | "input-end" | "remote-detach" | "socket-close" | "socket-error" | "protocol-error";
+export interface GrokAttachCloseInfo {
+    reason: GrokAttachCloseReason;
+    error?: Error;
+}
+export interface GrokAttachSession {
+    readonly socketPath: string;
+    readonly closed: Promise<GrokAttachCloseInfo>;
+    detach(): void;
+    resize(cols?: number, rows?: number): void;
+}
+export declare class GrokAttachRemoteError extends Error {
+    readonly code: string;
+    readonly fatal: boolean;
+    constructor(frame: GrokAttachErrorFrame);
+}
+export declare function validateGrokAttachSocket(socketPath: string, dependencies?: GrokAttachDependencies): Promise<void>;
+export declare function connectGrokAttach(options: GrokAttachClientOptions): Promise<GrokAttachSession>;

package/dist/src/grok-copresence-disclosure.d.ts

@@ -0,0 +1,11 @@
+export type GrokCopresenceSessionDisclosure = "configured" | "new" | "resume";
+export type GrokCopresenceDisclosure = {
+    profile: "commhub-only" | "x-search" | "repo-read" | "invalid";
+    lines: readonly string[];
+};
+/**
+ * Describe only the exact tool profiles accepted by the pinned Grok TUI
+ * runtime. This is deliberately exact: a near-miss must never be presented as
+ * either reviewed capability set.
+ */
+export declare function grokCopresenceDisclosure(tools: unknown, session?: GrokCopresenceSessionDisclosure): GrokCopresenceDisclosure;

package/dist/src/grok-copresence-profile.d.ts

@@ -0,0 +1,65 @@
+export declare const GROK_UNIX_SOCKET_PATH_MAX_BYTES = 100;
+export declare const GROK_COPRESENCE_CAPABILITY_MARKER = "ANET_CAPABILITY_GROK_COPRESENCE_V2";
+export declare const GROK_PREVIEW_RESOLVER_INHERITED_ENV_KEYS: readonly ["PATH", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE", "TZ"];
+export declare const GROK_AGENT_NODE_INHERITED_ENV_KEYS: readonly ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "SHELL", "USER", "LOGNAME", "TERM", "COLORTERM", "NO_COLOR"];
+export declare const GROK_AGENT_NODE_OPTIONAL_ENV_KEYS: readonly ["GROK_BINARY", "GROK_HOME", "FLOCK_BINARY", "SETPRIV_BINARY", "UNSHARE_BINARY", "GROK_CLI_TIMEOUT_MS", "GROK_HANDSHAKE_TIMEOUT_MS", "LOG_LEVEL", "ANET_GOAL_TICK_MS", "COMMHUB_MAX_GOALS_PER_NODE"];
+/** Exact environment for the long-lived agent-node parent of the Grok TUI. */
+export declare function buildGrokAgentNodeEnv(parentEnv: NodeJS.ProcessEnv): Record<string, string>;
+export declare function grokPreviewResolverConfigPaths(home: string): {
+    directory: string;
+    userConfig: string;
+    globalConfig: string;
+};
+/**
+ * npm rejects loading the same file as both user and global config. Prepare
+ * two distinct, empty, owner-only files without following a final symlink so
+ * the resolver cannot inherit a user's ordinary npmrc credentials.
+ */
+export declare function prepareGrokPreviewResolverConfigs(home: string): void;
+/** Exact environment for the short-lived npm resolver and capability probe. */
+export declare function buildGrokPreviewResolverEnv(parentEnv: NodeJS.ProcessEnv, home: string): Record<string, string>;
+/** Old headless-only agent-node builds already advertised grok-build-cli. */
+export declare function agentNodeHelpSupportsGrokCopresence(help: string): boolean;
+export interface GrokCopresenceProfileFields {
+    grokCopresence: boolean;
+    grokLeaderSocket?: string;
+    grokAttachSocket?: string;
+}
+export interface GrokSocketPathOptions {
+    cwd?: string;
+    home?: string;
+    xdgRuntimeDir?: string;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Allocate deterministic Unix socket paths without creating anything.
+ *
+ * Grok's workspace sandbox does not admit an otherwise owner-controlled
+ * XDG_RUNTIME_DIR such as /run/user/<uid>. Keep the primary sockets under the
+ * node's owner-bound state home, which the runtime already admits, and use a
+ * short private tmp path only when the Unix socket length limit requires it.
+ * The runtime owns directory creation and permissions; `anet node create`
+ * only persists the identity of the two sockets.
+ */
+export declare function grokCopresenceSocketPaths(nodeId: string, options?: GrokSocketPathOptions): {
+    leaderSocket: string;
+    attachSocket: string;
+};
+export type GrokAttachTarget = {
+    ok: true;
+    socketPath: string;
+} | {
+    ok: false;
+    reason: "not_grok_build_cli" | "headless" | "missing_attach_socket";
+};
+/**
+ * `anet grok attach` eligibility. The CLI is the only human join path;
+ * this is the shipped decision so tests can drive it without a TTY.
+ */
+export declare function resolveGrokAttachTarget(input: {
+    runtime: string;
+    grokCopresence?: unknown;
+    grokAttachSocket?: unknown;
+}): GrokAttachTarget;
+export declare function grokBuildCliCreationFields(runtime: string, nodeId: string, headless?: boolean, options?: GrokSocketPathOptions): GrokCopresenceProfileFields | Record<string, never>;

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

@@ -1,12 +1,49 @@
+/**
+ * RFC-020 §3.1 — Feishu (Lark) adapter for the IM compatibility layer.
+ *
+ * Uses `@larksuiteoapi/node-sdk` in WebSocket long-connection mode (WSClient).
+ * No public IP / no domain verification / no webhook signature decryption —
+ * the three biggest 飞书 接入 risks all live in the HTTP event-callback path,
+ * not in WSClient mode.
+ *
+ * Milestones:
+ *   M1: contract scaffold.
+ *   M2 (this file): WSClient init + EventDispatcher for `im.message.receive_v1`
+ *                   + event normalization + access whitelist gate + audit log.
+ *   M3: outbound `im.message.create` (text), edit support (≤20/msg).
+ *   M5: image upload / download (`im.image.create` / `im.messageResource.get`)
+ *       + group @bot detection refined to match the bot's own open_id.
+ */
+import * as lark from "@larksuiteoapi/node-sdk";
 import type { IMAdapter, IMAdapterHealth, IMChannelConfig, IMConversationRef, IMIngressMode, NormalizedIMEvent, NormalizedIMMessage } from "../types.js";
 type OnEventHandler = (event: NormalizedIMEvent) => Promise<void>;
+export type FeishuWsClientLike = Pick<lark.WSClient, "start" | "close">;
+export type FeishuWsClientFactory = (params: ConstructorParameters<typeof lark.WSClient>[0]) => FeishuWsClientLike;
+type FeishuInboundHandler = (rawEvent: unknown) => Promise<unknown>;
+export interface FeishuEventDispatcherLike {
+    register(handlers: Record<string, FeishuInboundHandler>): unknown;
+}
+export interface FeishuAdapterOptions {
+    /** @internal Avoids real bot-info HTTP calls in lifecycle tests. */
+    createClient?: (params: ConstructorParameters<typeof lark.Client>[0]) => lark.Client;
+    /** @internal Test seam; production uses the pinned Lark SDK WSClient. */
+    createWsClient?: FeishuWsClientFactory;
+    /** @internal Test seam; production uses the pinned Lark SDK dispatcher. */
+    createEventDispatcher?: () => FeishuEventDispatcherLike;
+    /** Independent outer bound in case the SDK promise/callback path stalls. */
+    wsReadyTimeoutMs?: number;
+    /** Called once when an already-ready socket exhausts reconnect attempts. */
+    onTerminalError?: (error: Error) => void;
+}
 export declare class FeishuAdapter implements IMAdapter {
     readonly platform = "feishu";
     readonly ingressMode: IMIngressMode;
     private feishuConfig;
-    private connectionName;
+    private connectionName_;
     private client;
     private wsClient;
+    private lifecycleGeneration;
+    private readonly options;
     /**
      * The bot's own open_id, resolved at init() via /open-apis/bot/v3/info.
      * Used to detect real @bot mentions (vs any mention) in group messages.
@@ -17,6 +54,24 @@ export declare class FeishuAdapter implements IMAdapter {
     /** Where to persist downloaded inbound media (M5c). */
     private mediaDir;
     private health_;
+    constructor(options?: FeishuAdapterOptions);
+    /**
+     * Snapshot of the current `access.allowFrom` list (from access.json).
+     * Used by the bridge's rate-limiter to exempt operator-vouched explicit
+     * sender ids from the DM flood limit (2026-06-29: Vincent's multi-turn
+     * heavy work was tripping the 3-msg/60s DM limit; explicit-listed
+     * users are already operator-trusted via the access whitelist, no
+     * need to also flood-limit them). Returns `[]` before `init()`. The
+     * wildcard `["*"]` allowlist does NOT count as "explicit" — that's
+     * the public-channel shape and still needs flood protection.
+     */
+    getAllowFrom(): readonly string[];
+    /**
+     * Read-only accessor used by bridge to resolve per-connection paths
+     * (RFC-020 §15 outbound-marker validation needs the connection name
+     * to build the allowed per-conversation directory prefix).
+     */
+    get connectionName(): string;
     init(config: IMChannelConfig): Promise<void>;
     start(onEvent: OnEventHandler): Promise<void>;
     stop(): Promise<void>;
@@ -26,4 +81,97 @@ export declare class FeishuAdapter implements IMAdapter {
     edit(_target: IMConversationRef, messageId: string, message: NormalizedIMMessage): Promise<void>;
     health(): IMAdapterHealth;
 }
+/**
+ * Heuristic — does this text look like it contains markdown syntax that
+ * Feishu's plain-text `msg_type:"text"` would render as literal source?
+ * Catches the patterns Vincent's heavy work produces: tables (`|...|`
+ * + separator row), fenced code blocks (`` ``` ``), ATX headings (`#`),
+ * bold/italic (`**text**` / `*text*`), unordered/ordered lists, inline
+ * code (`` `code` ``), markdown links (`[label](url)`).
+ *
+ * Returns true for at least one match; the adapter then upgrades to
+ * `msg_type:"interactive"` with a `markdown` element. Returns false for
+ * plain prose so the text path stays untouched (no perf cost, no
+ * behavior change for non-markdown replies).
+ *
+ * Conservative — single-character matches (e.g., a `|` in prose, one
+ * `*` for emphasis-of-one-word that Feishu would render OK as text)
+ * are NOT enough to trigger. We want false-positives < false-negatives
+ * (a false-positive upgrade renders fine; a false-negative shows raw
+ * `|` and `**`).
+ */
+export declare function looksLikeMarkdown(text: string): boolean;
+/**
+ * Parse Feishu `message_type: "post"` content into plain text. Post
+ * content is a nested structure:
+ *
+ *   { title?: string,
+ *     content: Array<Array<{ tag: "text"|"img"|"a"|"at"|"emotion", ... }>>
+ *   }
+ *
+ * Each top-level array entry is a paragraph; each paragraph is an array
+ * of typed segments. We flatten by:
+ *   - prepending title (if present) as `<title>\n\n`
+ *   - joining paragraphs with `\n\n`
+ *   - joining segments within a paragraph in order
+ *   - tag=text → emit segment.text as-is
+ *   - tag=a    → emit `[label](href)` (markdown link)
+ *   - tag=at   → emit `@user_name` (fallback to `@<user_id>` if no name)
+ *   - tag=img  → emit `[图片]` placeholder (actual download via maybeAttachImages)
+ *   - tag=emotion → emit `[emoji]`
+ *   - unknown tag → skip
+ *
+ * @internal exported for unit tests.
+ */
+export declare function parsePostContent(rawJson: string): string;
+/**
+ * Walk a Feishu `post` content JSON and collect all `image_key` values
+ * from `tag: "img"` segments. Used by `maybeAttachImages` to schedule
+ * downloads for every image in a 图文混排 message.
+ *
+ * @internal exported for unit tests.
+ */
+export declare function extractPostImageKeys(rawJson: string): string[];
+/**
+ * Sanitize a Feishu-supplied `file_name` so it's safe to append to a
+ * filesystem path. Strips `/`, `\`, `..`, control characters, and NUL
+ * bytes. Empty / all-stripped input falls back to a placeholder that
+ * uses the message id, so a hostile client can never write outside the
+ * conversation's `<mediaDir>/<convKey>/` directory.
+ *
+ * NOT a full display-safety pass — the LLM still sees the sanitized
+ * bytes and shouldn't render them as HTML/etc. That's a Layer above.
+ */
+export declare function sanitizeFileName(raw: string, fallback: string): string;
+/**
+ * Feishu text-message practical chunk threshold (RFC-020 §16).
+ *
+ * The official `im.message.create`/`reply` content limit for
+ * `msg_type:text` is ~30 KB JSON-encoded (`{"text":"..."}`), comfortably
+ * under what any reasonable bot reply produces. We chunk below that
+ * limit at 4000 CHARACTERS — gives a roomy safety margin for multi-byte
+ * UTF-8 and lets us split at paragraph boundaries cleanly. Chosen
+ * conservatively after Vincent 2026-06-30 ask "issue 发文字" (i.e.
+ * never silently fall back to PNG for "long" plain-text replies — they
+ * just chunk into multiple messages).
+ *
+ * Single-message ceiling, NOT a per-second rate limit (that's separate;
+ * RFC-020 §4.4).
+ */
+export declare const FEISHU_TEXT_SINGLE_LIMIT = 4000;
+/**
+ * Split a long text into chunks ≤ `maxChars`. Tries paragraph boundaries
+ * (`\n\n`), then line boundaries (`\n`), then word boundaries (space),
+ * then hard byte split. Output preserves the original text content
+ * (sum of chunks == original, modulo the boundary character that gets
+ * consumed by the split).
+ *
+ * If the input is already short enough, returns a single-element array.
+ */
+export declare function splitTextForFeishu(text: string, maxChars: number): string[];
+/**
+ * Lark errors may echo request/config values. Keep worker logs actionable while
+ * ensuring credentials and multiline payloads never cross the process boundary.
+ */
+export declare function sanitizeFeishuWsError(rawError: unknown, appId: string, appSecret: string): Error;
 export {};

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

@@ -44,11 +44,20 @@ 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;
 }
 /** 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 {

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/markdown-image-renderer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RFC-020 §14 — markdown → image rendering for Feishu replies.
+ *
+ * Vincent 2026-06-29 path: Feishu's `markdown` card element doesn't
+ * render ATX headings or GFM tables (preview.7 caught only bold / list
+ * / link). Rather than partially support a moving subset of card
+ * elements, we render structured markdown to a PNG via headless
+ * chromium and send it through Feishu's image API (`im:resource:upload`
+ * scope). Pixel-perfect fidelity, zero schema fragility, text-not-
+ * copyable accepted as the tradeoff for "actually renders".
+ *
+ * Hybrid route (decided in adapter.send):
+ *   - plain text (no markdown markers)        → msg_type:"text"
+ *   - markdown WITHOUT heading / table / long → msg_type:"interactive" (schema 1.0 card with `markdown` element — keeps copy/paste for short bold/list/link replies; preview.7 path)
+ *   - markdown WITH heading / table / long    → THIS PATH (msg_type:"image" with rendered PNG)
+ *
+ * Renderer choice: `puppeteer-core` (no bundled chromium) + system
+ * chromium (apt install in Docker). Rationale:
+ *  - Pure-JS canvas-layout libraries (node-canvas, @napi-rs/canvas)
+ *    cost 4-6h of manual paragraph wrapping + table cell measurement
+ *    + Chinese width metrics; chromium does this natively.
+ *  - puppeteer-core (5MB) + system chromium (~100MB) is smaller than
+ *    full puppeteer (170MB) which bundles its own chromium.
+ *  - Headless screenshot ~500ms after warmup. Bot's heavy turn is 20-
+ *    70s; rendering cost is in the noise.
+ *
+ * Chromium reuse: we keep a single browser instance hot across
+ * renderings to avoid the ~2-3s cold-start per call. Auto-close on
+ * idle is a follow-up — agent-node worker lifetime is bounded.
+ */
+import { Buffer } from "node:buffer";
+/**
+ * Close the shared browser. Called from adapter.stop() during graceful
+ * worker shutdown. Subsequent render calls re-launch.
+ */
+export declare function closeBrowser(): Promise<void>;
+/**
+ * Render markdown text to a PNG buffer.
+ *
+ * Width is fixed at 800px (IM-friendly); height auto-fits content via
+ * `fullPage:true`. Returns the raw PNG bytes — caller hands them to
+ * `lark.im.image.create({image: Readable.from(buffer)})`.
+ *
+ * Throws on chromium launch failure or page navigation failure.
+ * Caller is responsible for fallback (e.g., send the raw text as a
+ * code block in the schema 1.0 card path).
+ */
+export declare function renderMarkdownToPng(text: string): Promise<Buffer>;
+/**
+ * Decide whether `renderMarkdownToPng` should be invoked for this reply
+ * text, vs. falling back to msg_type:"text" / msg_type:"interactive"
+ * (schema 1.0 card). Locked by 通信龙 3f70044c — trigger image when:
+ *   - text contains a markdown table (Feishu card can't render)
+ *   - text contains an ATX heading (Feishu card can't render)
+ *   - text length > 2000 chars (image is better than scrollable text wall)
+ *
+ * Returns false for short prose, single-line plain text, and short
+ * markdown lists / bold / link / inline-code which DO render fine in
+ * the schema 1.0 `markdown` card element.
+ */
+export declare function shouldRenderAsImage(text: string): boolean;