@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/channels/feishu/invoke-turn.js

@@ -1,20 +1,7 @@
-/**
- * Run one turn (the IO half of canonical Feishu→Agent translation): assemble its inputs — resolve the reply
- * referent (a summon that replies to an earlier message names it only by `parent_id`; the content is
- * NOT in the event, so it is fetched here) and the attachments (vision images inline, files to disk) —
- * and stream `agent.invoke` with the assembled prompt. Split from parse.ts (which is pure) because this
- * half touches the Open API + disk; split from feishu.ts so the factory keeps only wiring and the
- * per-turn lifecycle.
- *
- * Inputs have two tiers. PRIMARY is the summoning message plus the message it explicitly replied to;
- * any load failure there aborts visibly so the Agent never runs without an input the user pointed at.
- * BUFFERED resources come from earlier un-summoned thread/group discussion and degrade per attachment:
- * one expired background file must not block the current ask or hide its still-readable siblings.
- */
-import { SESSION_BUSY_CODE } from "../../agent.js";
 import { log } from "../../log.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
 import { parseContent } from "./parse.js";
-import { codePointPrefix } from "./text.js";
+import { codePointPrefix } from "../text.js";
 /** Appended to the prompt (not the system prompt): the channel renders the reply in a card, and the
  *  card's markdown element is the natural fit for LLM output — steer away from HTML/plain. */
 const MARKDOWN_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card.)";
@@ -84,46 +71,25 @@ async function resolveTurnInputs(t, attachments) {
             log.warn(`${t.label} could not load an earlier (buffered) attachment: ${String(result.reason)}`);
         }
     }
-    const missing = lost + attachments.buffered.skipped;
-    const bufferedNote = missing > 0
-        ? `\n[note: ${missing} attachment(s) from the earlier discussion are not loaded (expired, or older than the most recent few)]`
-        : "";
-    const backgroundImageManifest = backgroundImages.length
-        ? `\n\n[background vision images from earlier discussion — appended after ${imageRefs.length} primary image(s):\n${backgroundImages
-            .map(({ ref }, index) => `- vision image ${imageRefs.length + index + 1}: from ${ref.from}, msg ${ref.messageId}`)
-            .join("\n")}\n]`
-        : "";
+    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.map(({ ref }) => ref));
     const allFiles = [
         ...downloaded,
         ...backgroundFiles.map(({ file, ref }) => ({
             ...file,
-            name: `${file.name} (from ${ref.from}, msg ${ref.messageId}, earlier discussion)`,
+            name: attributedFileName(file.name, ref.from, ref.messageId),
         })),
     ];
-    const manifest = allFiles.length
-        ? `\n\n[attached files — read them with your tools:\n${allFiles.map((file) => `- ${file.name} (${file.size} bytes) → ${file.path}`).join("\n")}\n]`
-        : "";
     const allImages = [...imageRefs, ...backgroundImages.map(({ image }) => image)];
     return {
         images: allImages.length ? allImages : undefined,
-        promptSuffix: `${referentBlock}${bufferedNote}${backgroundImageManifest}${manifest}`,
+        promptSuffix: `${referentBlock}${missingNote}${backgroundImageManifest}${attachedFilesManifest(allFiles)}`,
     };
 }
-// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
-// free, and the loop exits within one delay of the holder finishing. The cap is sized to outlast a real
-// tool-using wake turn (minutes); a holder that runs longer still surfaces the busy error to the user.
-const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
 /**
- * Run one turn: resolve its inputs, then stream agent.invoke. A primary-input failure surfaces as a
- * `failed` event (never a silent drop). `onCompleted` (if given) fires on the `completed` event — the
- * durable-commit point; the caller uses it to remove the turn intent (turn-store L1) at the earliest
- * moment the turn provably lives in the session.
- *
- * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
- * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user sees
- * the "Thinking…" preview while waiting, and only an exhausted wait surfaces the busy failure. Only a
- * FIRST-event busy retries — inputs are already resolved, and a fail-fast reject is the only shape the
- * engine emits it in, so nothing that started is ever re-run.
+ * Run one turn: resolve its inputs, then stream agent.invoke with the shared busy-wait
+ * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
+ * primary-input failure surfaces as a `failed` event (never a silent drop).
  */
 export async function* invokeFeishuTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
     let resolved;
@@ -135,23 +101,5 @@ export async function* invokeFeishuTurn(agent, session, text, transport, attachm
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
-    const deadline = Date.now() + busyRetry.maxWaitMs;
-    for (;;) {
-        let retryBusy = false;
-        let first = true;
-        for await (const e of agent.invoke({ session }, prompt)) {
-            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
-                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
-                break;
-            }
-            first = false;
-            if (e.type === "completed")
-                onCompleted?.(); // the turn is durably in the session — commit point
-            yield e;
-        }
-        if (!retryBusy)
-            return;
-        log.info(`${transport.label} session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
-        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
-    }
+    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
 }

package/dist/channels/feishu/model.d.ts

@@ -76,7 +76,7 @@ export type FeishuResourceKind = "image" | "file" | "audio" | "video";
  * A resource locator. User-sent resources are scoped by BOTH their carrying message id and resource
  * key; a bare file_key/image_key is insufficient for the message-resource download API.
  */
-export interface FeishuResourceRef {
+interface FeishuResourceRef {
     kind: FeishuResourceKind;
     messageId: string;
     key: string;
@@ -95,3 +95,4 @@ export interface NormalizedFeishuMessage {
         resources: FeishuResourceRef[];
     };
 }
+export {};

package/dist/channels/feishu/normalize.d.ts

@@ -4,7 +4,7 @@
  * converts resource keys into message-scoped locators before the turn engine sees them.
  */
 import type { FeishuMessage, FeishuMessageEvent, FeishuResourceKind, NormalizedFeishuMessage } from "./model.ts";
-export interface DecodedFeishuResource {
+interface DecodedFeishuResource {
     kind: FeishuResourceKind;
     key: string;
     name?: string;
@@ -20,3 +20,4 @@ export interface DecodedFeishuContent {
 export declare function decodeFeishuContent(message: Pick<FeishuMessage, "message_type" | "content" | "mentions">): DecodedFeishuContent;
 /** Normalize one verified message event. Returns null only when its required identity is absent. */
 export declare function normalizeFeishuMessage(event: FeishuMessageEvent): NormalizedFeishuMessage | null;
+export {};

package/dist/channels/feishu/owned-threads.d.ts

@@ -1,11 +1,7 @@
-export interface OwnedFeishuThread {
-    rootId: string;
-    chatId: string;
-    createdAt: number;
-}
-export interface OwnedFeishuThreads {
+interface OwnedFeishuThreads {
     has(chatId: string, rootId: string): boolean;
     /** Idempotent, synchronous, pre-ACK persistence. A failed write throws so the platform redelivers. */
     add(chatId: string, rootId: string): void;
 }
 export declare function createOwnedFeishuThreads(path: string, label: string, now?: () => number): OwnedFeishuThreads;
+export {};

package/dist/channels/feishu/parse.d.ts

@@ -9,7 +9,7 @@ import type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, Fei
 export type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender };
 /** Legacy compatibility shape returned by {@link parseContent}. New internal code consumes normalized
  * resource refs, which retain resource kind + carrying message id. */
-export interface FeishuAttachmentRef {
+interface FeishuAttachmentRef {
     key: string;
     name?: string;
 }

package/dist/channels/feishu/preview.d.ts

@@ -1,12 +1,9 @@
 import type { AgentEvent } from "../../agent.ts";
 import { type FeishuApi, type FeishuTarget } from "./feishu-api.ts";
-/** A terminal failure, as the channel hands it to `onError`. */
-export interface FeishuFailure {
-    details: string;
-    retryable: boolean;
-}
-/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
-export declare function defaultErrorMessage(failed: FeishuFailure): string;
+import { type ChannelFailure, defaultErrorMessage } from "../preview-kit.ts";
+/** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
+export type FeishuFailure = ChannelFailure;
+export { defaultErrorMessage };
 /** A visible preview mounted into the chat. Exported only for the channel wiring: a queued turn mounts
  * one before execution, then hands the exact entity/message to {@link streamFeishuReply} for takeover. */
 export type MountedFeishuPreview = {

package/dist/channels/feishu/preview.js

@@ -23,41 +23,16 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
 import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
 import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
-import { truncateCodePointPrefix, truncateCodePointSuffix, truncateUtf8 } from "./text.js";
-/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
-export function defaultErrorMessage(failed) {
-    return failed.retryable ? "⚠️ Temporary problem — please try again." : "⚠️ Sorry, something went wrong.";
-}
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
+import { truncateUtf8 } from "../text.js";
+export { defaultErrorMessage };
 /** How often (ms) to push a live-preview snapshot; tool events still flush on the next loop. Cardkit
  *  allows 10 QPS per card entity (50 per app), but one snapshot a second reads smoothly (the client
  *  animates between snapshots).
  *  Doubles as the answer-preview aging window (see answerView). */
 const STREAM_THROTTLE_MS = 1000;
-/** Max length of a tool's arg preview in the live view. */
-const TOOL_ARG_MAX = 48;
 /** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
 const THINKING_PREVIEW = 280;
-/** The placeholder shown before any reasoning/tool/text arrives. */
-const THINKING_PLACEHOLDER = "💭 Thinking…";
-/** One-line, truncated: collapse whitespace so a multi-line command/arg stays on one line. */
-function clip(s) {
-    const one = s.replace(/\s+/g, " ").trim();
-    return truncateCodePointPrefix(one, TOOL_ARG_MAX);
-}
-/**
- * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
- * rather than just `🔧 read`. Generic (the channel knows no tool schemas): show the salient value — the
- * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
- */
-function summarizeArgs(args) {
-    if (args === null || typeof args !== "object" || Array.isArray(args))
-        return clip(String(args));
-    const values = Object.values(args);
-    const primary = values.find((v) => typeof v === "string" || typeof v === "number");
-    if (primary !== undefined)
-        return clip(String(primary));
-    return values.length > 0 ? clip(JSON.stringify(args)) : "";
-}
 /** Cap a live view to the card budget, PREFIX-STABLE: the streaming client animates only when the old
  *  text is a prefix of the new, so an over-budget view freezes at its head rather than sliding a tail
  *  window (which would redraw the whole card every frame). The full answer still lands at settle. */
@@ -174,35 +149,16 @@ export async function settleFeishuPreview(api, target, preview, text) {
  * than recalling it and posting another reply.
  */
 export async function streamFeishuReply(events, api, target, formatError, initialPreview, label = "[feishu]") {
-    const tools = [];
-    const toolIndexById = new Map();
-    let thinking = "";
-    let answer = "";
-    let answerPreviewSince;
-    const mark = { running: "…", ok: "✓", error: "✗" };
-    const toolView = () => tools.map((t) => `🔧 ${t.label} ${mark[t.status]}`).join("\n");
-    // Reasoning is process, not the answer: shown (capped to its tail) in the live preview only, never
-    // in the settled final card (which is `answer` alone).
-    const thinkingView = () => {
-        const t = thinking.replace(/\s+/g, " ").trim();
-        if (t === "")
-            return "";
-        return `💭 ${truncateCodePointSuffix(t, THINKING_PREVIEW)}`;
-    };
-    // The answer is hidden until its first delta has aged one STREAM_THROTTLE_MS: the pump's leading-edge
-    // flush would otherwise turn the very first content delta (often a lone character) into its own frame
-    // — the short-reply flicker. Aging is anchored at delta ARRIVAL (set in the event loop, not here) so
-    // an in-flight update can't skew the clock; a turn completing within the window settles directly.
-    const answerView = () => {
-        if (answer.trim() === "" || answerPreviewSince === undefined)
-            return "";
-        return Date.now() - answerPreviewSince >= STREAM_THROTTLE_MS ? answer : "";
-    };
+    // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
+    // policy, the card-budget cap, and delivery below.
+    const turn = createTurnView();
     const view = () => {
-        const v = [thinkingView(), toolView(), answerView()]
-            .filter((s) => s.trim() !== "")
-            .join("\n\n")
-            .trim();
+        const v = composeTurnBody([
+            thinkingLine(turn, THINKING_PREVIEW),
+            toolLines(turn),
+            turn.retrying ? RETRY_NOTICE : "",
+            revealedAnswer(turn, STREAM_THROTTLE_MS),
+        ]);
         return capBytes(v === "" ? THINKING_PLACEHOLDER : v, CARD_MARKDOWN_MAX_BYTES);
     };
     // The live preview is ONE message: either the queue card/text handed in by the wiring, or a preview
@@ -243,105 +199,31 @@ export async function streamFeishuReply(events, api, target, formatError, initia
             throw e;
         }
     };
-    // ── Live-preview pump: a SINGLE serialized writer. ──────────────────────────────────────────
-    // Events mutate state (thinking / tools / answer) and mark the preview dirty; the pump pushes the
-    // LATEST view() with at most ONE update in flight, paced by a throttle. One-in-flight also guarantees
-    // the card's strictly-increasing `sequence` lands in order (no concurrent frames).
-    let dirty = false;
-    let pumping = false;
-    let stopped = false;
-    let previewErrLogged = false;
-    let pumpDone;
-    let wakeThrottle; // set while the pump is mid-throttle; finish() cuts it short
-    const runPump = async () => {
-        pumping = true;
-        try {
-            while (dirty && !stopped) {
-                dirty = false;
-                try {
-                    await flushPreview();
-                }
-                catch (e) {
-                    // Best-effort preview (the final write is authoritative), but a failing update must be visible —
-                    // log once per turn so a never-rendering preview is diagnosable, not silent.
-                    if (!previewErrLogged) {
-                        previewErrLogged = true;
-                        log.warn(`${label} live preview failed (final reply still sends): ${String(e)}`);
-                    }
-                }
-                if (dirty && !stopped) {
-                    // Pace + coalesce a burst into one snapshot. Interruptible: finish() cuts this short so the
-                    // final write is not delayed by up to STREAM_THROTTLE_MS after the turn completes.
-                    await new Promise((resolve) => {
-                        const t = setTimeout(resolve, STREAM_THROTTLE_MS);
-                        wakeThrottle = () => {
-                            clearTimeout(t);
-                            resolve();
-                        };
-                    });
-                    wakeThrottle = undefined;
-                }
-            }
-        }
-        finally {
-            pumping = false;
-        }
-    };
-    // Mark the preview dirty and ensure the single writer is running (an update already in flight picks
-    // up the new state on its next loop). Synchronous — callers never await a network write.
-    const touch = () => {
-        dirty = true;
-        if (!pumping)
-            pumpDone = runPump();
-    };
+    // The shared single-writer pump (preview-kit) serializes snapshots to the one preview — which also
+    // guarantees the card's strictly-increasing `sequence` lands in order (no concurrent frames).
+    const { touch, finish } = createPreviewPump({
+        flush: flushPreview,
+        throttleMs: STREAM_THROTTLE_MS,
+        onError: (e) => log.warn(`${label} live preview failed (final reply still sends): ${String(e)}`),
+    });
     touch(); // mount the "💭 Thinking…" preview immediately
-    // Stop the pump and await any in-flight update, so the final write below is strictly the LAST one to
-    // the preview (no stale frame landing after the answer).
-    const finish = async () => {
-        stopped = true;
-        wakeThrottle?.(); // cut an in-flight throttle so the final write is not delayed up to STREAM_THROTTLE_MS
-        await pumpDone?.catch(() => { });
-    };
     /** Terminal write, whatever tier the preview reached. */
     const settle = async (text) => {
         await finalize(api, target, preview, text, nextSeq);
     };
     try {
         for await (const e of events) {
-            if (e.type === "text") {
-                answer += e.delta;
-                if (answerPreviewSince === undefined && answer.trim() !== "")
-                    answerPreviewSince = Date.now();
-                touch();
-            }
-            else if (e.type === "thinking") {
-                thinking += e.delta;
-                touch();
-            }
-            else if (e.type === "tool_started") {
-                const arg = summarizeArgs(e.args);
-                toolIndexById.set(e.id, tools.length);
-                tools.push({ label: arg ? `${e.name} ${arg}` : e.name, status: "running" });
-                touch();
-            }
-            else if (e.type === "tool_ended") {
-                const i = toolIndexById.get(e.id);
-                const t = i === undefined ? undefined : tools[i];
-                if (t)
-                    t.status = e.isError ? "error" : "ok";
-                touch();
-            }
-            else if (e.type === "completed") {
+            if (e.type === "completed") {
                 await finish();
                 // Settle the preview into the final answer; the persisted card is the answer alone — the
                 // process (thinking/tools) was preview-only. Mark finalized BEFORE delivering: the terminal was
                 // reached, so a delivery failure here is a plain failure, not an "abnormal exit" (which would
                 // wrongly fire the finally's neutral-notice fallback = double delivery + wrong text).
                 finalized = true;
-                await settle(answer.trim() !== "" ? answer : "(no reply)");
+                await settle(turn.answer.trim() !== "" ? turn.answer : "(no reply)");
                 return;
             }
-            else if (e.type === "failed") {
+            if (e.type === "failed") {
                 await finish();
                 // Two audiences: the chat (customer-facing — formatError, neutral by default) and the operator
                 // log (dev-facing — the full details, via the throw below + the handler's catch). Same terminal
@@ -361,6 +243,8 @@ export async function streamFeishuReply(events, api, target, formatError, initia
                 }
                 throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);
             }
+            if (applyTurnEvent(turn, e))
+                touch();
         }
         throw new Error("stream ended without a terminal event"); // violates SPEC MUST 1
     }

package/dist/channels/feishu/register-app.d.ts

@@ -21,7 +21,7 @@
  * encoding (JSON → gzip → base64url) follow the official SDKs (provenance: node-sdk
  * scene/registration); item names unknown to the platform catalog are silently dropped by the page.
  */
-export interface FeishuAppAddons {
+interface FeishuAppAddons {
     scopes?: {
         tenant?: string[];
         user?: string[];
@@ -68,3 +68,4 @@ export interface RegisteredFeishuApp {
  * abort, or a transport failure — every rejection is a plain Error whose message says what to do.
  */
 export declare function registerFeishuApp(options: RegisterFeishuAppOptions): Promise<RegisteredFeishuApp>;
+export {};

package/dist/channels/feishu/register-webhook.d.ts

@@ -7,7 +7,7 @@ import { type FeishuCloudKind } from "./cloud.ts";
  *
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
-export interface FeishuManualRegistration {
+interface FeishuManualRegistration {
     consoleUrl: string;
     requestUrl: string;
 }
@@ -20,3 +20,4 @@ export interface RegisterFeishuWebhookOptions {
     onManualRegistration?: (info: FeishuManualRegistration) => void;
 }
 export declare function registerFeishuWebhook(baseUrl: string, kind: FeishuCloudKind, opts?: RegisterFeishuWebhookOptions): Promise<RegistrationOutcome>;
+export {};

package/dist/channels/feishu/setup-mode.d.ts

@@ -0,0 +1,8 @@
+/** Feishu/Lark app-level event subscription choice used by onboarding and scaffolding. */
+export type FeishuSubscriptionMode = "webhook" | "websocket";
+/** Onboarding choice for group visibility. `context` needs the tenant-wide group-message scope; the
+ * runtime remains capability-driven because the platform, not channel source, decides which events
+ * are delivered. */
+export type FeishuGroupBehavior = "context" | "mentions";
+/** The sensitive tenant scope behind both managed-thread bare replies and group context buffering. */
+export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";

package/dist/channels/feishu/setup-mode.js

@@ -0,0 +1,2 @@
+/** The sensitive tenant scope behind both managed-thread bare replies and group context buffering. */
+export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";

package/dist/channels/feishu/ws-ingress.d.ts

@@ -0,0 +1,28 @@
+import type { LongConnection } from "../../host/node.ts";
+import type { FeishuCloudKind } from "./cloud.ts";
+import type { FeishuMessageEvent } from "./parse.ts";
+interface FeishuWsClient {
+    start(): Promise<void>;
+    close(): void;
+}
+interface FeishuWsClientCallbacks {
+    onReady(): void;
+    onError(error: Error): void;
+    onReconnecting(): void;
+    onReconnected(): void;
+    onEvent(event: FeishuMessageEvent): void | Promise<void>;
+}
+export type CreateFeishuWsClient = (callbacks: FeishuWsClientCallbacks) => FeishuWsClient | Promise<FeishuWsClient>;
+export interface FeishuWsConnectionOptions {
+    kind: FeishuCloudKind;
+    appId: string;
+    appSecret: string;
+    domain: string;
+    onEvent(event: FeishuMessageEvent): void | Promise<void>;
+    /** Internal SDK seam for deterministic tests. */
+    createClient?: CreateFeishuWsClient;
+}
+/** Open Feishu/Lark's official-SDK WebSocket connection. The SDK ACKs only after `onEvent` settles;
+ * a persistence throw therefore becomes a 500 response frame and the platform re-pushes the event. */
+export declare function connectFeishuWs(options: FeishuWsConnectionOptions, signal: AbortSignal): LongConnection;
+export {};

package/dist/channels/feishu/ws-ingress.js

@@ -0,0 +1,136 @@
+import { log } from "../../log.js";
+function sdkLogger(label) {
+    return {
+        error: (...parts) => log.error(`${label} ${parts.map(String).join(" ")}`),
+        warn: (...parts) => log.warn(`${label} ${parts.map(String).join(" ")}`),
+        info: (...parts) => log.info(`${label} ${parts.map(String).join(" ")}`),
+        debug: (...parts) => log.debug(`${label} ${parts.map(String).join(" ")}`),
+        trace: (...parts) => log.debug(`${label} ${parts.map(String).join(" ")}`),
+    };
+}
+async function productionClient(options, callbacks) {
+    // Webhook-only users stay on the lightweight fetch path; load the proprietary-protocol SDK only
+    // when a WebSocket connection is actually opened.
+    const { EventDispatcher, LoggerLevel, WSClient } = await import("@larksuiteoapi/node-sdk");
+    const label = `[${options.kind}:ws]`;
+    const logger = sdkLogger(label);
+    const eventDispatcher = new EventDispatcher({ logger, loggerLevel: LoggerLevel.warn }).register({
+        "im.message.receive_v1": callbacks.onEvent,
+    });
+    const client = new WSClient({
+        appId: options.appId,
+        appSecret: options.appSecret,
+        domain: options.domain,
+        logger,
+        loggerLevel: LoggerLevel.warn,
+        autoReconnect: true,
+        source: "fastagent",
+        handshakeTimeoutMs: 15_000,
+        onReady: callbacks.onReady,
+        onError: callbacks.onError,
+        onReconnecting: callbacks.onReconnecting,
+        onReconnected: callbacks.onReconnected,
+    });
+    return {
+        start: () => client.start({ eventDispatcher }),
+        close: () => client.close(),
+    };
+}
+/** Open Feishu/Lark's official-SDK WebSocket connection. The SDK ACKs only after `onEvent` settles;
+ * a persistence throw therefore becomes a 500 response frame and the platform re-pushes the event. */
+export function connectFeishuWs(options, signal) {
+    const label = `[${options.kind}:ws]`;
+    // The SDK only logs + returns for this case (no onError), which would leave readiness pending forever.
+    if (!/^cli_[0-9a-fA-F]{16}$/.test(options.appId)) {
+        throw new Error(`${options.kind} websocket requires an App ID shaped like cli_<16 hex characters>`);
+    }
+    let readySettled = false;
+    let closedSettled = false;
+    let resolveReady;
+    let rejectReady;
+    let resolveClosed;
+    let rejectClosed;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    const closed = new Promise((resolve, reject) => {
+        resolveClosed = resolve;
+        rejectClosed = reject;
+    });
+    const fail = (error) => {
+        if (signal.aborted || closedSettled)
+            return;
+        // Settle-then-close: closedSettled first makes a close()-triggered SDK callback re-entry a no-op.
+        closedSettled = true;
+        // Terminal failure must release the transport here: the abort listener's close() no-ops once
+        // closedSettled is set, and only close() destroys SDK-held resources (e.g. its cache sweep timer).
+        if (client)
+            closeClient(client);
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (!readySettled) {
+            readySettled = true;
+            rejectReady(failure);
+        }
+        rejectClosed(failure);
+    };
+    const createClient = options.createClient ?? ((callbacks) => productionClient(options, callbacks));
+    let client;
+    const callbacks = {
+        onReady() {
+            if (readySettled || signal.aborted)
+                return;
+            readySettled = true;
+            log.info(`${label} connected`);
+            resolveReady();
+        },
+        onError(error) {
+            fail(new Error(`${error.message} — check that Events & Callbacks uses long connection and the published app version includes im.message.receive_v1`));
+        },
+        onReconnecting() {
+            if (!signal.aborted)
+                log.warn(`${label} disconnected — reconnecting…`);
+        },
+        onReconnected() {
+            if (!signal.aborted)
+                log.info(`${label} reconnected`);
+        },
+        onEvent: options.onEvent,
+    };
+    const closeClient = (target) => {
+        try {
+            target.close();
+        }
+        catch (error) {
+            log.warn(`${label} close failed: ${String(error)}`);
+        }
+    };
+    const close = () => {
+        if (closedSettled)
+            return;
+        closedSettled = true; // before closeClient, so a callback re-entry from close() is a no-op
+        if (client)
+            closeClient(client);
+        if (!readySettled) {
+            // Abort before the first connection: `ready` still settles, and resolution here means
+            // cancellation, not readiness (the LongConnection contract; serve skips ready-side effects).
+            readySettled = true;
+            resolveReady();
+        }
+        resolveClosed();
+    };
+    if (signal.aborted) {
+        close();
+        return { ready, closed };
+    }
+    signal.addEventListener("abort", close, { once: true });
+    void Promise.resolve(createClient(callbacks)).then((created) => {
+        client = created;
+        if (signal.aborted || closedSettled) {
+            closeClient(created);
+            return;
+        }
+        void created.start().catch(fail);
+    }, fail);
+    return { ready, closed };
+}

package/dist/channels/github/github.js

@@ -17,12 +17,7 @@ const MAX_WEBHOOK_BYTES = 25 << 20;
  * `(ctx) => ({ "POST /gh": githubChannel(opts)(ctx)["POST /webhook"]! })`.
  */
 export function githubChannel({ secret, on }) {
-    // A non-empty secret is mandatory: verify() against an empty key accepts a signature anyone can
-    // compute, so an unset secret must fail at construction, never silently run forgeable.
-    if (!secret) {
-        throw new Error("githubChannel requires a non-empty secret (the GitHub webhook secret, e.g. GITHUB_WEBHOOK_SECRET)");
-    }
-    return ({ agent }) => ({
+    const channel = ({ agent }) => ({
         "POST /webhook": async (req) => {
             if (req.method !== "POST")
                 return text("POST only\n", 405);
@@ -77,4 +72,11 @@ export function githubChannel({ secret, on }) {
             return new Response(null, { status: 202 });
         },
     });
+    return (ctx) => {
+        // Validate at activation so deploy may inspect the module shape before secrets are provisioned.
+        if (!secret) {
+            throw new Error("githubChannel requires a non-empty secret (the GitHub webhook secret, e.g. GITHUB_WEBHOOK_SECRET)");
+        }
+        return channel(ctx);
+    };
 }

package/dist/channels/http.d.ts

@@ -1,5 +1,19 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Agent } from "../agent.ts";
+/** Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's
+ *  dispatch imports it), so the two caps cannot drift apart. */
+export declare const MAX_BODY_BYTES: number;
+/** SSE comment-heartbeat interval, shared by every SSE surface (the control events route imports
+ *  it, and the remote client sizes its dead-connection watchdog as a multiple of it). */
+export declare const SSE_HEARTBEAT_MS = 30000;
+/** The emitting half of the heartbeat contract (the client watchdog is the other): starts the
+ *  `: ping` comment interval on an SSE stream controller and returns its stop function — ONE
+ *  implementation for every SSE surface, so the emission side cannot regress on one route while
+ *  the shared client watchdog keeps assuming it. Self-stops if the controller is already closed. */
+export declare function sseHeartbeat(controller: ReadableStreamDefaultController<Uint8Array>): () => void;
+/** A valid example request body for the invoke handler — lives HERE, next to the shape check it must
+ *  satisfy, so the CLI's "try it" hint can't drift from the protocol. */
+export declare const INVOKE_EXAMPLE_BODY = "{\"session\":\"dev\",\"text\":\"hello\"}";
 /**
  * Fetch-shaped invoke handler. Mount it at any route in the host app; it accepts POST only.
  * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.