@sleep2agi/agent-network 2.3.0-preview.17 → 2.3.0-preview.170

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/grok-create-mode.d.ts

@@ -0,0 +1,19 @@
+/** One-line limitation list shown wherever co-presence is offered (CLI help,
+ *  picker, create warning). Keep it one line — it is appended to menus. */
+export declare const GROK_COPRESENCE_EXPERIMENTAL_NOTE_ZH = "\u5B9E\u9A8C\u6027\uFF1A\u4EBA\u5728 TUI \u8F93\u5165\u6846\u6253\u5B57\u65F6\u7F51\u7EDC\u4EFB\u52A1\u4F1A\u6392\u961F\u76F4\u5230\u8D85\u65F6\uFF1Bgrok \u987B\u9489\u5728\u5DF2\u9A8C\u8BC1\u7248\u672C\uFF08\u65B0\u7248\u4F1A\u62D2\u7EDD\u542F\u52A8\uFF09\uFF1BmacOS \u9700\u7279\u6B8A\u5904\u7406\uFF1B\u4E0D\u52A0\u8F7D .agents/skills \u6280\u80FD\u3002\u8981\u7A33\u5B9A\u63A5\u6D3B\u7528\u9ED8\u8BA4\u7684 ACP\u3002";
+export declare const GROK_COPRESENCE_EXPERIMENTAL_NOTE_EN = "Experimental: network tasks queue until timeout while a human is typing in the TUI; grok must be pinned to a verified build (newer builds refuse to start); macOS needs special handling; .agents/skills skills are not loaded. For a stable node use the default ACP mode.";
+export type GrokCreateModeResult = {
+    ok: true;
+    runtime: string | undefined;
+    copresenceRequested: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the runtime string a NEW node is created with.
+ *
+ * Non-Grok runtimes (and an absent runtime) pass through untouched — this
+ * helper only decides between the two Grok lanes.
+ */
+export declare function resolveGrokCreateRuntime(rawRuntime: string | undefined, copresence: unknown): GrokCreateModeResult;

package/dist/src/host-telemetry.d.ts

@@ -0,0 +1,14 @@
+export interface HostTelemetry {
+    hostname: string;
+    ip: string | null;
+    cpu_load_1min: number | null;
+    cpu_cores: number | null;
+    mem_total_gb: number | null;
+    mem_used_gb: number | null;
+    mem_avail_gb: number | null;
+    disk_total_gb: number | null;
+    disk_used_gb: number | null;
+    disk_avail_gb: number | null;
+}
+export declare function getHostTelemetry(): HostTelemetry;
+export declare function _clearHostTelemetryCache(): void;

package/dist/src/hub-health-timeout.d.ts

@@ -0,0 +1,4 @@
+export declare const LOOPBACK_HUB_HEALTH_TIMEOUT_MS = 2000;
+export declare const REMOTE_HUB_HEALTH_TIMEOUT_MS = 10000;
+export declare const HUB_HEALTH_TIMEOUT_ENV = "ANET_HUB_HEALTH_TIMEOUT_MS";
+export declare function hubHealthTimeoutMs(hub: string, env?: NodeJS.ProcessEnv): number;

package/dist/src/hub-server-version.d.ts

@@ -0,0 +1,64 @@
+export declare const COMMHUB_SERVER_PKG = "@sleep2agi/commhub-server";
+export declare const AGENT_NETWORK_PKG = "@sleep2agi/agent-network";
+export type HubReleaseChannel = "latest" | "preview";
+export type HubVersionSource = "explicit" | "registry" | "cache" | "pinned-floor";
+export interface DistTags {
+    latest?: string | null;
+    preview?: string | null;
+}
+export declare function isExactSemver(v: string | null | undefined): boolean;
+/** Semver precedence. Unparseable versions sort lowest. */
+export declare function compareSemver(a: string, b: string): number;
+export declare function resolveHubChannel(input: {
+    anetVersion: string;
+    flag?: string | null;
+    anetDistTags: DistTags | null;
+}): {
+    channel: HubReleaseChannel;
+    reason: string;
+};
+export interface HubVersionDecision {
+    version: string;
+    source: HubVersionSource;
+    channel: HubReleaseChannel | null;
+    /** true when `version` is already present in the local bun install cache. */
+    cached: boolean;
+    /** One-line, human readable "where it came from". */
+    origin: string;
+    /** Must be printed prominently (stderr). */
+    warnings: string[];
+}
+export declare function decideHubServerVersion(input: {
+    explicit?: string | null;
+    channelFlag?: string | null;
+    anetVersion: string;
+    anetDistTags: DistTags | null;
+    serverDistTags: DistTags | null;
+    floor: string;
+    cachedVersions: string[];
+}): HubVersionDecision;
+export type ExecFn = (cmd: string, args: string[]) => string;
+export declare function fetchDistTags(exec: ExecFn, pkg: string): DistTags | null;
+export interface CacheFs {
+    existsSync(p: string): boolean;
+    readdirSync(p: string): string[];
+    readFileSync(p: string): string;
+}
+export declare function bunInstallCacheDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * Versions of commhub-server present in bun's install cache. Bun uses two
+ * layouts (`@sleep2agi/commhub-server@<ver-or-hash>@@@1/` and
+ * `@sleep2agi/commhub-server/<ver-or-hash>@@@1/`); prerelease parts are
+ * hashed in the directory name, so the version is read from package.json.
+ */
+export declare function listCachedServerVersions(cacheDir: string, fs?: CacheFs): string[];
+export declare function resolveHubServerVersion(input: {
+    explicit?: string | null;
+    channelFlag?: string | null;
+    anetVersion: string;
+    floor: string;
+    exec: ExecFn;
+    cacheDir: string;
+    fs?: CacheFs;
+}): HubVersionDecision;
+export declare function formatHubVersionBanner(d: HubVersionDecision): string;

package/dist/src/hub-stop.d.ts

@@ -0,0 +1,74 @@
+export type ProbeName = "proc" | "ss" | "lsof" | "netstat";
+/** null = 这条探针在本机跑不了(没有 /proc、没装 ss …);数组 = 跑了,这些 PID 在监听。 */
+export interface SocketProbeResult {
+    pids: number[];
+    /** 端口确实被监听、但属主 PID 读不到(别的用户的进程)。 */
+    unresolved?: number;
+}
+export interface HubPidRecord {
+    pid: number;
+    port: number;
+    launcher_pid?: number;
+    started_at?: string;
+}
+export interface HubStopProbes {
+    platform: NodeJS.Platform;
+    socket: Partial<Record<ProbeName, (port: number) => SocketProbeResult | null>>;
+    readPidFile: (port: number) => HubPidRecord | null;
+    cmdline: (pid: number) => string | null;
+    alive: (pid: number) => boolean;
+}
+export type CandidateVerdict = "commhub" | "not-commhub" | "cmdline-unreadable";
+export interface Candidate {
+    pid: number;
+    source: ProbeName | "pidfile";
+    cmdline: string | null;
+    verdict: CandidateVerdict;
+}
+export interface HubListenerResolution {
+    port: number;
+    /** 每条探针的结果,按尝试顺序。 */
+    tried: {
+        probe: ProbeName | "pidfile";
+        outcome: string;
+    }[];
+    /** 给出端口归属的那条探针;null = 本机没有一条能跑。 */
+    authority: ProbeName | null;
+    /** 端口被监听但读不到属主 PID 的个数。 */
+    unresolved: number;
+    /** 核实过是 commhub-server 的 PID —— 只有这些会被停。 */
+    hubPids: Candidate[];
+    /** 端口上的其他进程 / cmdline 读不到的进程 —— 拒绝动手。 */
+    refused: Candidate[];
+}
+export declare function probeOrder(platform: NodeJS.Platform): ProbeName[];
+/** cmdline 是不是 commhub-server。只做核实,不用来挑选进程。 */
+export declare function isCommhubServerCmdline(cmdline: string | null | undefined): boolean;
+/** /proc/net/tcp 或 tcp6 文本 → 在 port 上 LISTEN(st=0A)的 socket inode。 */
+export declare function parseProcNetTcp(text: string, port: number): string[];
+/** `ss -Hltnp 'sport = :PORT'` → pids;有行却没有 users:(…) 的算 unresolved。 */
+export declare function parseSsOutput(text: string, port: number): SocketProbeResult;
+/** Windows `netstat -ano`:`TCP 127.0.0.1:9200 0.0.0.0:0 LISTENING 1234`。 */
+export declare function parseNetstatWindows(text: string, port: number): SocketProbeResult;
+/** macOS `netstat -anv -p tcp`:按表头找 pid 列;本地地址形如 `127.0.0.1.9200` / `*.9200`。 */
+export declare function parseNetstatDarwin(text: string, port: number): SocketProbeResult;
+export declare function resolveHubListener(port: number, probes: HubStopProbes): HubListenerResolution;
+export interface StopHubDeps {
+    probes: HubStopProbes;
+    kill: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+    sleep: (ms: number) => Promise<void>;
+    /** /health 是否 ok —— 与探针无关的独立判据。 */
+    healthy: () => Promise<boolean>;
+    log: (line: string) => void;
+    error: (line: string) => void;
+    graceMs?: number;
+}
+export interface StopHubResult {
+    code: 0 | 1;
+    killed: number[];
+    refused: Candidate[];
+}
+export declare function stopHub(port: number, d: StopHubDeps): Promise<StopHubResult>;
+export declare function procNetListeners(port: number, procRoot?: string): SocketProbeResult | null;
+export declare function defaultHubStopProbes(readPidFile: (port: number) => HubPidRecord | null, platform?: NodeJS.Platform): HubStopProbes;
+export declare function readCmdline(pid: number, platform?: NodeJS.Platform): string | null;

package/dist/src/hub-time-display.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 把 hub 的 TEXT 时间戳显示给人看。
+ *
+ * 🔴 原先是**原样打印**:
+ *
+ *     updated:  2026-08-31 00:20:11
+ *
+ * 那是 UTC,**没有任何时区标记**。同一时刻本地是 `08:22:41 CST` ——
+ * 于是一个 **2 分钟前**刚心跳过的节点,在 UTC+8 的用户眼里像是 **8 小时前**的。
+ *
+ * 这不是假想:2026-08-31 我自己就这么读错过一次,据此差点报出「舰队心跳陈旧
+ * 8.3 小时」。**CLI 在主动制造这个误读。**
+ *
+ * 所以显示两样东西:
+ *   - **相对时长**(人真正想知道的那个)
+ *   - 绝对值,并**显式标 UTC**(便于和日志、issue 里的时间对齐)
+ */
+export declare function formatHubTime(raw: unknown, nowMs?: number): string;
+/** 人读的时长。负数(时钟偏差/未来时间)如实说,不折成 0。 */
+export declare function formatAgo(deltaMs: number): string;

package/dist/src/hub-version-skew.d.ts

@@ -0,0 +1,19 @@
+/**
+ * #1595 —— `anet doctor` 原先只印 hub 自报的版本:
+ *
+ *   ✅ CommHub reachable (http://127.0.0.1:9200 v0.9.0-preview.38)
+ *
+ * 读的人**看不到自己这台 CLI 钉的是哪个**。实测(2026-08-31):生产 hub 在
+ * `.38`,而 `anet hub start` 的 `PINNED_SERVER_VERSION` 是 `.44` —— 两个数
+ * 差 6 个版本,而屏幕上只有一个。今天有一整条排查(agent→用户消息为什么
+ * 验不了端到端)就卡在这个差上:`.44` 之前 `send_desktop_message` 是
+ * fire-and-forget 且仍返回 `ok:true`,所以在 `.38` 上拿到的 `ok:true`
+ * 不是「用户看到了」的证据。
+ *
+ * 🔴 **只并排摆出两个数,不判断谁对、不给阈值、不发警告。**
+ *    hub 比 CLI 的 pin 老或新都可能完全合理 —— 连的是别人运维的 hub、
+ *    本机 hub 还没重启、或者故意钉在旧版。给一个猜出来的「应该一致」
+ *    判据,会在这些正常情况下变成误报,而一个会误报的检查第一周就会被关掉。
+ *    让读的人自己看见差在哪,是这一格能诚实做到的全部。
+ */
+export declare function formatHubVersionDetail(hubUrl: string, hubVersion: unknown, pinnedVersion: string): string;

package/dist/src/im/correlation-store.d.ts

@@ -0,0 +1,34 @@
+import type { IMCorrelationStore, IMTaskCorrelation } from "./types";
+export interface JsonIMCorrelationStoreOptions {
+    now?: () => number;
+    /** How long idempotency keys remain valid. Defaults to 24h. */
+    seenTtlMs?: number;
+    /** How long terminal correlations remain queryable. Defaults to 24h. */
+    terminalTtlMs?: number;
+}
+/**
+ * Small durable store for RFC-020 §2.9④ / §4.4 correlation state.
+ *
+ * The first gateway PR needs this as a standalone data structure before the
+ * bridge is rewired: idempotency keys survive process restart, and task replies
+ * can be routed back to their originating IM conversation.
+ */
+export declare class JsonIMCorrelationStore implements IMCorrelationStore {
+    private readonly path;
+    private readonly now;
+    private readonly seenTtlMs;
+    private readonly terminalTtlMs;
+    constructor(path: string, options?: JsonIMCorrelationStoreOptions);
+    hasSeen(idempotencyKey: string): Promise<string | null>;
+    recordSeen(idempotencyKey: string, taskId: string): Promise<void>;
+    getCorrelation(taskId: string): Promise<IMTaskCorrelation | null>;
+    putCorrelation(taskId: string, correlation: IMTaskCorrelation): Promise<void>;
+    updateStatus(taskId: string, status: IMTaskCorrelation["status"]): Promise<void>;
+    gc(now: number): Promise<{
+        removed: number;
+    }>;
+    private isExpired;
+    private load;
+    private save;
+}
+export declare function createJsonIMCorrelationStore(path: string, options?: JsonIMCorrelationStoreOptions): IMCorrelationStore;

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

@@ -1,5 +1,40 @@
+/**
+ * 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;
@@ -7,6 +42,8 @@ export declare class FeishuAdapter implements IMAdapter {
     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,7 @@ 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
@@ -131,4 +169,9 @@ export declare const FEISHU_TEXT_SINGLE_LIMIT = 4000;
  * 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

@@ -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,6 +79,16 @@ 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 {
@@ -101,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
@@ -125,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/hub-upload.d.ts

@@ -1,7 +1,7 @@
 /**
  * RFC-020 §17 — feishu inbound bridge → hub `/api/upload` integration.
  *
- * Vincent 2026-06-30: cross-machine agents (e.g. TM门户运维@toodadev2)
+ * Vincent 2026-06-30: cross-machine agents (e.g. a partner-team node on a partner-team host)
  * 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

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 {};