@sleep2agi/agent-network 2.3.0-preview.1 → 2.3.0-preview.100

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