@fastagent-sh/fastagent 0.14.0 → 0.16.0

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/scaffold/channel.ts

@@ -8,8 +8,10 @@ import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
 //      card scope ("Create and update card" — the live preview streams through a card). To answer bare
-//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
-//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
+//      messages in threads the Agent takes part in, and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version. Add a
+//      message-read scope (e.g. `im:message:readonly`) too, so a thread's opening ask can carry the
+//      message it quotes; without it that quote degrades to a marker in the prompt.
 //   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
 //      .env; RECOMMENDED: set an Encrypt Key there and mirror it in FEISHU_ENCRYPT_KEY
 //   4. the event Request URL (https://your.host/feishu) is registered AUTOMATICALLY by
@@ -23,18 +25,17 @@ export default feishuChannel({
   appSecret: process.env.FEISHU_APP_SECRET ?? "",
   verificationToken: process.env.FEISHU_VERIFICATION_TOKEN ?? "", // authenticates inbound events
   encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
-  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
-  // directMessageSession: "continuous",
-  // groupMessageSession: "continuous",
+  // No session modes: a chat is one session and a thread is another, and where the answer goes follows
+  // from that (docs/design/participant-model.md).
   // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
   // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
   // full details always go to the server log regardless.
   onError: (failed) => `⚠️ ${failed.details}`,
   // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
   // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
-  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
-  // threads. Other human group/thread discussion buffers until that place's next answered turn;
-  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
+  // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
+  // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
   // Override to customise explicit routing, reusing the export:
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },

package/dist/channels/feishu/scaffold/feishu-send.ts

@@ -6,7 +6,7 @@ import { defineTool, z } from "@fastagent-sh/fastagent";
 // context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
 // the target chat id. tools/ is auto-discovered.
 
-// Standalone copy of the channel transport's discipline: a timeout so a wedged connection can't hang
+// Embedded copy of the channel transport's discipline: a timeout so a wedged connection can't hang
 // the tool call (and the turn), named errors, and success gated on the body's own code===0.
 // Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
 // fail-fast beats a silently sleeping tool.
@@ -57,9 +57,11 @@ async function tenantToken(): Promise<string> {
 export default defineTool({
   description:
     "Send a message to a Feishu chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. In a chat turn take chatId from the " +
-    "[feishu: chat …] context line; in a scheduled/woken turn (no context line) the chat id must come " +
-    "from your instruction.",
+    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
+    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
+    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
+    "answer (it would post the message twice). chatId comes from the [feishu: chat …] context line in a " +
+    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),

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

@@ -0,0 +1,37 @@
+/** 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 bare replies in the agent's threads and group context buffering. */
+export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
+/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).
+ *  INDEPENDENT of the delivery scope above and of the group posture: the read runs in every chat type
+ *  (a p2p thread's opening ask, any quoted @mention in a group). It is also a softer dependency —
+ *  without it everything still works, and an unreadable quote degrades to a marker in the prompt.
+ *  Bundled into the context-aware request only because that path already needs an approval round; a
+ *  mention-only app wanting referents must add it by hand. */
+export declare const FEISHU_MESSAGE_READ_SCOPE = "im:message:readonly";
+/** A scope the onboarding asks for, plus any BROADER spelling that already satisfies it. One concept,
+ *  so adding a superset means editing the entry — not every call site that tests a scope. */
+export interface FeishuScopeRequest {
+    /** What to add to the app draft when nothing satisfies it. Always counts as satisfying itself. */
+    request: string;
+    /** EXTRA spellings that also count — supersets. Optional; `request` is implicit. Modelled this way
+     *  so a request that can never be satisfied (a list omitting its own `request`) cannot be
+     *  written: onboarding would add the scope, the tenant would grant it, and it would still read as
+     *  missing forever. */
+    supersets?: string[];
+}
+/** Whether `predicate` holds for any spelling that satisfies this request. */
+export declare function scopeSatisfied(entry: FeishuScopeRequest, predicate: (name: string) => boolean): boolean;
+/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already
+ *  do so — checking only the readonly spelling would warn a correctly configured app forever and push
+ *  its author into a redundant approval round. Exported on its own because the serving-time capability
+ *  report asks the same question, and a second mechanism there is what this type exists to prevent. */
+export declare const FEISHU_MESSAGE_READ_REQUEST: FeishuScopeRequest;
+/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. Only the
+ *  delivery scope is required for the context path; the read scope rides along because it shares the
+ *  round and its absence merely degrades quoted messages to a marker. */
+export declare const FEISHU_CONTEXT_ONBOARDING_SCOPES: FeishuScopeRequest[];

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

@@ -0,0 +1,28 @@
+/** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
+export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
+/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).
+ *  INDEPENDENT of the delivery scope above and of the group posture: the read runs in every chat type
+ *  (a p2p thread's opening ask, any quoted @mention in a group). It is also a softer dependency —
+ *  without it everything still works, and an unreadable quote degrades to a marker in the prompt.
+ *  Bundled into the context-aware request only because that path already needs an approval round; a
+ *  mention-only app wanting referents must add it by hand. */
+export const FEISHU_MESSAGE_READ_SCOPE = "im:message:readonly";
+/** Whether `predicate` holds for any spelling that satisfies this request. */
+export function scopeSatisfied(entry, predicate) {
+    return [entry.request, ...(entry.supersets ?? [])].some(predicate);
+}
+/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already
+ *  do so — checking only the readonly spelling would warn a correctly configured app forever and push
+ *  its author into a redundant approval round. Exported on its own because the serving-time capability
+ *  report asks the same question, and a second mechanism there is what this type exists to prevent. */
+export const FEISHU_MESSAGE_READ_REQUEST = {
+    request: FEISHU_MESSAGE_READ_SCOPE,
+    supersets: ["im:message"],
+};
+/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. Only the
+ *  delivery scope is required for the context path; the read scope rides along because it shares the
+ *  round and its absence merely degrades quoted messages to a marker. */
+export const FEISHU_CONTEXT_ONBOARDING_SCOPES = [
+    { request: FEISHU_GROUP_CONTEXT_SCOPE },
+    FEISHU_MESSAGE_READ_REQUEST,
+];

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

@@ -7,6 +7,7 @@ import { verify } from "@octokit/webhooks-methods";
 import { collect } from "../../collect.js";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
+import { beginWork } from "../busy.js";
 import { text } from "../respond.js";
 /** Raw body cap before verification — GitHub caps webhook payloads at 25 MB; reject larger early. */
 const MAX_WEBHOOK_BYTES = 25 << 20;
@@ -17,12 +18,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);
@@ -72,9 +68,22 @@ export function githubChannel({ secret, on }) {
                 const turn = `${event.deliveryId}#${i}`;
                 log.info(`[github] turn start: turn=${turn} session=${session} event=${label}`);
                 const startedAt = Date.now();
-                void collect(agent.invoke({ session }, { text })).then(() => log.info(`[github] turn done: turn=${turn} session=${session} (${Date.now() - startedAt}ms)`), (error) => log.error(`[github] turn failed: turn=${turn} session=${session} (${Date.now() - startedAt}ms): ${String(error)}`));
+                // Post-ACK turns are process-wide in-flight work (busy.ts): a serving surface that must not
+                // idle mid-turn (the AgentCore /ping's HealthyBusy) has no other way to see them — and github
+                // turns have NO replay, so an idle reclaim here loses the review outright.
+                const workDone = beginWork();
+                void collect(agent.invoke({ session }, { text }))
+                    .then(() => log.info(`[github] turn done: turn=${turn} session=${session} (${Date.now() - startedAt}ms)`), (error) => log.error(`[github] turn failed: turn=${turn} session=${session} (${Date.now() - startedAt}ms): ${String(error)}`))
+                    .finally(workDone);
             }
             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.

package/dist/channels/http.js

@@ -6,15 +6,38 @@
  * web stream primitives give cancellation (consumer disconnect → cancel() → iterator.return() →
  * invoke cancellation, SPEC MUST 3), backpressure (pull-based), and the body cap natively.
  *
- * `nodeListener` is the thin node:http adapter for the standalone `fastagent dev/start` server.
+ * `nodeListener` is the thin node:http adapter for the embedded `fastagent dev/start` server.
  */
 import { Readable } from "node:stream";
 import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
 import { text, textHeaders } from "./respond.js";
-/** Request body cap (1 MiB). */
-const MAX_BODY_BYTES = 1 << 20;
+/** 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 const MAX_BODY_BYTES = 1 << 20;
 const encoder = new TextEncoder();
+/** 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 const SSE_HEARTBEAT_MS = 30_000;
+/** 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 function sseHeartbeat(controller) {
+    const encoder = new TextEncoder();
+    const timer = setInterval(() => {
+        try {
+            controller.enqueue(encoder.encode(": ping\n\n"));
+        }
+        catch {
+            clearInterval(timer);
+        }
+    }, SSE_HEARTBEAT_MS);
+    return () => clearInterval(timer);
+}
+/** 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 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.
@@ -37,19 +60,29 @@ export function createInvokeHandler(agent) {
         if (typeof session !== "string" || typeof promptText !== "string") {
             return text('need { "session": string, "text": string }\n', 400);
         }
+        // ^ the request shape INVOKE_EXAMPLE_BODY (below) must keep satisfying.
         // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
         // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
         const iterator = agent.invoke({ session }, { text: promptText })[Symbol.asyncIterator]();
+        // Heartbeats: a QUIET stream (a long tool call, no events) is normal here — remote consumers
+        // distinguish "quiet but alive" from a dead connection by byte arrival, so silence must not
+        // look identical to a black hole (SSE comments are ignored by spec-conforming parsers).
+        let stopHeartbeat = () => { };
         const stream = new ReadableStream({
+            start(controller) {
+                stopHeartbeat = sseHeartbeat(controller);
+            },
             async pull(controller) {
                 const { value, done } = await iterator.next();
                 if (done) {
+                    stopHeartbeat();
                     controller.close();
                     return;
                 }
                 controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
             },
             async cancel() {
+                stopHeartbeat();
                 await iterator.return?.();
             },
         });

package/dist/channels/invoke-turn-kit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
+ * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
+ *
+ *   - {@link streamTurnWithBusyRetry}: the busy-retry loop around `agent.invoke`, with the
+ *     `onCompleted` durable-commit point;
+ *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
+ *     {@link missingAttachmentsNote}, {@link attributedFileName}.
+ *
+ * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
+ * message-scoped Feishu keys, Slack file objects) are real differences.
+ */
+import { type Agent, type AgentEvent, type Prompt } from "../agent.ts";
+/** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
+ *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
+ *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
+ *  always an outside holder — wait for it like a queued turn, instead of erroring at the user. */
+export interface BusyRetry {
+    delayMs: number;
+    maxWaitMs: number;
+}
+export declare const DEFAULT_BUSY_RETRY: BusyRetry;
+/**
+ * Stream one Agent turn with the shared busy-wait. `onCompleted` (if given) fires on the turn's
+ * `completed` event — the durable-commit point: only then does the turn provably live in the session,
+ * so a failure or crash at ANY earlier point leaves the caller's pre-ACK state (turn intent, context
+ * buffer) intact for replay/the next summon. The caller uses it to remove the turn intent AND commit
+ * the context buffer, in that order, so a crash between the two clears cannot replay a
+ * context-stripped turn.
+ *
+ * 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 channel's "Thinking…" placeholder while waiting (the mirror of the scheduler deferring a
+ * wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a FIRST-event
+ * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
+ * is ever re-run.
+ */
+export declare function streamTurnWithBusyRetry(agent: Agent, session: string, prompt: Prompt, options: {
+    label: string;
+    onCompleted?: () => void;
+    busyRetry?: BusyRetry;
+}): AsyncIterable<AgentEvent>;
+/** What the attached-files manifest renders per file: display name, byte size, absolute local path. */
+export interface ManifestFile {
+    name: string;
+    size: number;
+    path: string;
+}
+/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
+ *  Empty input renders nothing. */
+export declare function attachedFilesManifest(files: readonly ManifestFile[]): string;
+/** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),
+ *  the way the fold attributes text lines. */
+export declare function attributedFileName(name: string, from: string, msg?: string | number): string;
+/** The manifest attributing background vision images folded in from the earlier discussion — images
+ *  carry no per-image label inline, so position ("appended after N primary") is the attribution.
+ *  Channels whose image refs carry no attribution (telegram) simply don't render one. */
+export declare function backgroundImagesManifest(primaryCount: number, refs: readonly {
+    from: string;
+    messageId: string;
+}[]): string;
+/** The prompt note counting EVERY background attachment the turn does not carry (load failures +
+ *  cap-skipped) — without it, the model holds fold references it silently cannot open and may
+ *  pretend it read them. Neutral wording (platforms differ on WHY: expired file_ids, deleted files). */
+export declare function missingAttachmentsNote(missing: number): string;

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

@@ -0,0 +1,87 @@
+/**
+ * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
+ * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
+ *
+ *   - {@link streamTurnWithBusyRetry}: the busy-retry loop around `agent.invoke`, with the
+ *     `onCompleted` durable-commit point;
+ *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
+ *     {@link missingAttachmentsNote}, {@link attributedFileName}.
+ *
+ * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
+ * message-scoped Feishu keys, Slack file objects) are real differences.
+ */
+import { SESSION_BUSY_CODE } from "../agent.js";
+import { log } from "../log.js";
+// 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. So the cap is sized to outlast a
+// real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
+// this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
+// turn forever.
+export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
+/**
+ * Stream one Agent turn with the shared busy-wait. `onCompleted` (if given) fires on the turn's
+ * `completed` event — the durable-commit point: only then does the turn provably live in the session,
+ * so a failure or crash at ANY earlier point leaves the caller's pre-ACK state (turn intent, context
+ * buffer) intact for replay/the next summon. The caller uses it to remove the turn intent AND commit
+ * the context buffer, in that order, so a crash between the two clears cannot replay a
+ * context-stripped turn.
+ *
+ * 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 channel's "Thinking…" placeholder while waiting (the mirror of the scheduler deferring a
+ * wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a FIRST-event
+ * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
+ * is ever re-run.
+ */
+export async function* streamTurnWithBusyRetry(agent, session, prompt, options) {
+    const { label, onCompleted, busyRetry = DEFAULT_BUSY_RETRY } = options;
+    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(`${label} session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
+        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
+    }
+}
+/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
+ *  Empty input renders nothing. */
+export function attachedFilesManifest(files) {
+    return files.length
+        ? `\n\n[attached files — read them with your tools:\n${files.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+        : "";
+}
+/** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),
+ *  the way the fold attributes text lines. */
+export function attributedFileName(name, from, msg) {
+    return `${name} (from ${from}${msg !== undefined ? `, msg ${msg}` : ""}, earlier discussion)`;
+}
+/** The manifest attributing background vision images folded in from the earlier discussion — images
+ *  carry no per-image label inline, so position ("appended after N primary") is the attribution.
+ *  Channels whose image refs carry no attribution (telegram) simply don't render one. */
+export function backgroundImagesManifest(primaryCount, refs) {
+    return refs.length
+        ? `\n\n[background vision images from earlier discussion — appended after ${primaryCount} primary image(s):\n${refs
+            .map((ref, index) => `- vision image ${primaryCount + index + 1}: from ${ref.from}, msg ${ref.messageId}`)
+            .join("\n")}\n]`
+        : "";
+}
+/** The prompt note counting EVERY background attachment the turn does not carry (load failures +
+ *  cap-skipped) — without it, the model holds fold references it silently cannot open and may
+ *  pretend it read them. Neutral wording (platforms differ on WHY: expired file_ids, deleted files). */
+export function missingAttachmentsNote(missing) {
+    return missing > 0
+        ? `\n[note: ${missing} attachment(s) from the earlier discussion are not loaded (no longer available, or older than the most recent few)]`
+        : "";
+}

package/dist/channels/lark/lark.d.ts

@@ -3,9 +3,10 @@
  * this module binds it to Lark's cloud profile and exposes natural Lark-branded public names. Lark's
  * weaker control-plane capabilities live in onboarding/registration, not in a fork of the turn engine.
  */
-import type { ChannelModule } from "../../host/node.ts";
-import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute } from "../feishu/feishu.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
+import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, type FeishuWebSocketChannelOptions, defaultFeishuRoute } from "../feishu/feishu.ts";
 export type LarkChannelOptions = FeishuChannelOptions;
+export type LarkWebSocketChannelOptions = FeishuWebSocketChannelOptions;
 export type LarkFailure = FeishuFailure;
 export type LarkMessage = FeishuMessage;
 export type LarkMessageEvent = FeishuMessageEvent;
@@ -13,3 +14,4 @@ export type LarkRoute = FeishuRoute;
 export declare const defaultLarkRoute: typeof defaultFeishuRoute;
 export declare function larkEnvelope(event: LarkMessageEvent): string;
 export declare function larkChannel(opts: LarkChannelOptions): ChannelModule;
+export declare function larkWebSocketChannel(opts: LarkWebSocketChannelOptions): LongConnectionChannelModule;

package/dist/channels/lark/lark.js

@@ -1,5 +1,5 @@
 import { LARK_COMPAT_CLOUD } from "../feishu/cloud.js";
-import { buildFeishuChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
+import { buildFeishuChannel, buildFeishuWebSocketChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
 import { cloudEnvelope } from "../feishu/parse.js";
 export const defaultLarkRoute = defaultFeishuRoute;
 export function larkEnvelope(event) {
@@ -8,3 +8,6 @@ export function larkEnvelope(event) {
 export function larkChannel(opts) {
     return buildFeishuChannel(LARK_COMPAT_CLOUD, opts, larkChannel.name);
 }
+export function larkWebSocketChannel(opts) {
+    return buildFeishuWebSocketChannel(LARK_COMPAT_CLOUD, opts, larkWebSocketChannel.name);
+}