@fastagent-sh/fastagent 0.13.0 → 0.15.0

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.

package/dist/channels/http.js

@@ -12,9 +12,32 @@ 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);
+}

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

@@ -1,3 +1,4 @@
+import type { FeishuGroupBehavior, FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
 /**
  * Guided Lark-international onboarding. The intl cloud cannot complete the BOUND scan-to-create flow,
  * so a new/partial setup opens its unbound one-click launcher and collects one App-scoped credential
@@ -17,7 +18,7 @@ export interface LarkOnboardIO {
         hidden?: boolean;
     }): Promise<string | undefined>;
 }
-export interface LarkBootstrapResult {
+interface LarkBootstrapResult {
     /** Challenge-captured token: the PATCH also switched Subscription mode to webhook. */
     token?: string;
     /** Present only for a definitive config-route 404; tells the user why the manual path is active. */
@@ -26,14 +27,17 @@ export interface LarkBootstrapResult {
 export interface LarkOnboardOptions {
     /** Existing active .env values. A complete credential pair is reused (and still validated). */
     existing?: Readonly<Record<string, string | undefined>>;
+    ingress?: FeishuSubscriptionMode;
+    groupBehavior?: FeishuGroupBehavior;
     verifyCredentials(appId: string, appSecret: string): Promise<void>;
-    bootstrapWebhook(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
+    bootstrapWebhook?(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
 }
-export interface LarkOnboardCredentials extends Record<string, string> {
+export interface LarkOnboardCredentials {
     LARK_APP_ID: string;
     LARK_APP_SECRET: string;
-    LARK_VERIFICATION_TOKEN: string;
+    LARK_VERIFICATION_TOKEN?: string;
 }
 /** Open the stable app console and collect everything the runtime needs. Cancellation is a visible
  * failure: the scaffold remains and `add lark` is deliberately re-runnable to resume onboarding. */
 export declare function onboardLarkApp(io: LarkOnboardIO, opts: LarkOnboardOptions): Promise<LarkOnboardCredentials>;
+export {};

package/dist/channels/lark/onboard.js

@@ -39,7 +39,15 @@ export async function onboardLarkApp(io, opts) {
     const eventSecurityUrl = larkEventSecurityUrl(appId);
     io.note(`App ID / Secret verified. Opening Events & Callbacks → Security: ${eventSecurityUrl}`);
     io.openUrl(eventSecurityUrl);
+    if (opts.ingress === "websocket") {
+        io.note(opts.groupBehavior === "mentions"
+            ? "Choose long connection, subscribe im.message.receive_v1, then create + publish an app version. No Verification Token or Request URL is needed."
+            : "Choose long connection and subscribe im.message.receive_v1, but do not publish yet — context-aware group permission setup follows. No Verification Token or Request URL is needed.");
+        return { LARK_APP_ID: appId, LARK_APP_SECRET: appSecret };
+    }
     io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
+    if (!opts.bootstrapWebhook)
+        throw new Error("Lark webhook onboarding requires bootstrapWebhook");
     const bootstrap = await opts.bootstrapWebhook(appId, appSecret);
     if (bootstrap.token) {
         io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");

package/dist/channels/lark/scaffold/channel.ts

@@ -7,7 +7,9 @@ import { larkChannel } from "@fastagent-sh/fastagent/lark";
 //   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
 //   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)
+//      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.
 //   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 LARK_ENCRYPT_KEY
 //   4. run `fastagent dev --tunnel`: it attempts to switch Subscription mode to webhook + register
@@ -19,14 +21,19 @@ export default larkChannel({
   appSecret: process.env.LARK_APP_SECRET ?? "",
   verificationToken: process.env.LARK_VERIFICATION_TOKEN ?? "", // authenticates inbound events
   encryptKey: process.env.LARK_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",
   // 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 defaultLarkRoute:
-  // p2p chats always answer, groups only on an @mention of this bot (matched by open_id, resolved at
-  // startup). Override to customise, reusing the export:
+  // 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.
+  // Override to customise explicit routing, reusing the export:
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
 });

package/dist/channels/preview-kit.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Channel-neutral live-preview pieces shared by every messaging channel's preview renderer
+ * (telegram/preview.ts, feishu/preview.ts, slack/preview.ts): the turn-view REDUCER (the one
+ * event → view-state machine every renderer consumes), its line renderers, the terminal-failure
+ * shape a channel hands to its `onError`, the customer-facing wording for it, and the serialized
+ * single-writer pump. DELIVERY stays per-platform — message edits vs streaming cards vs chat.update,
+ * pacing constants, reveal timing, and terminal-write policies are real platform differences — but
+ * everything platform-independent lives here, so a new event type or a wording change lands in ONE
+ * place instead of one hunk per channel.
+ */
+import type { AgentEvent } from "../agent.ts";
+/** A terminal failure, as a channel hands it to its `onError`. */
+export interface ChannelFailure {
+    details: string;
+    retryable: boolean;
+}
+/** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
+ *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").
+ *  The non-retryable branch keeps the "something went wrong" phrase deliberately — it is neutral (we only
+ *  know a boolean, never the specific limitation) and shared verbatim across channels. */
+export declare function defaultErrorMessage(failed: ChannelFailure): string;
+/** Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying`
+ *  event): neutral, no leaked internals — the reason stays in operator logs. */
+export declare const RETRY_NOTICE = "\u23F3 Temporary problem \u2014 retrying\u2026";
+/** The placeholder shown before any reasoning/tool/text arrives. */
+export declare const THINKING_PLACEHOLDER = "\uD83D\uDCAD Thinking\u2026";
+/** One tool call's line in the live view. */
+interface ToolLine {
+    label: string;
+    status: "running" | "ok" | "error";
+}
+/**
+ * The channel-neutral view STATE of one in-flight turn. Renderers own everything after this state:
+ * when to reveal the young answer (age vs timer), how to format (HTML / card markdown / mrkdwn),
+ * and how to deliver frames. Terminal events are deliberately NOT view state — completed/failed
+ * resolve the preview into a final write, which is each platform's terminal-write policy.
+ */
+export interface TurnView {
+    thinking: string;
+    tools: ToolLine[];
+    /** tool-call id → its line, for `tool_ended` status flips (bookkeeping; renderers read `tools`). */
+    toolById: Map<string, ToolLine>;
+    answer: string;
+    /** Arrival time of the first non-empty answer delta; age-based reveal policies read it. */
+    answerSince?: number;
+    /** An advisory retry backoff is in progress (closed again by any subsequent progress event). */
+    retrying: boolean;
+}
+export declare function createTurnView(): TurnView;
+/**
+ * Apply one event to the view state. Returns true when the view changed (the caller repaints).
+ * This is the ONE place the shared view rules live: tool labels are humanized with a compact arg
+ * summary, and any progress event closes an open retry notice (a stale "retrying" line must never
+ * outlive actual progress). Terminal events only close the notice — they are the caller's business.
+ */
+export declare function applyTurnEvent(view: TurnView, e: AgentEvent): boolean;
+/** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
+export declare function toolLines(view: TurnView): string;
+/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe.
+ *  Process, not the answer — renderers show it live only, never in the persisted final message. */
+export declare function thinkingLine(view: TurnView, maxTail: number): string;
+/**
+ * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one
+ * throttle window (`ageMs` — each platform passes its own pacing constant). The pump's leading-edge
+ * flush would otherwise turn the very first content delta (often a lone character or unbalanced
+ * markup) into its own frame — the short-reply flicker (placeholder → "O" → "OK."). Aging is
+ * anchored at delta ARRIVAL (`answerSince`, set by the reducer) so an in-flight write can't skew the
+ * clock, and there is deliberately NO timer at the boundary: a young answer surfaces on the next
+ * content-driven pass, so a turn completing within the window delivers the final answer only.
+ */
+export declare function revealedAnswer(view: TurnView, ageMs: number): string;
+/** Compose body parts (thinking/tools/retry/answer) into one frame: skip empties, blank-line joins. */
+export declare function composeTurnBody(parts: readonly string[]): string;
+/**
+ * The serialized live-preview writer shared by the edit/snapshot renderers (telegram, feishu).
+ * Events mark the view dirty; the pump repaints to the LATEST view with at most ONE write in
+ * flight, paced by `throttleMs`. One-in-flight is the whole point: concurrent writes can land out
+ * of order — an older frame over a newer one is the "shows 3-4 steps, blanks, re-fills" flicker —
+ * so a single writer keeps frames monotonic (and makes feishu's strictly-increasing card `sequence`
+ * correct by construction). NOT used by slack-classic: its pacing lives inside the flush (the 3s
+ * chat.update rate slot), not at the frame boundary.
+ */
+export interface PreviewPump {
+    /** Mark the view dirty and ensure the single writer runs (an in-flight write picks the new state
+     *  up on its next loop). Synchronous — callers never await a network write. */
+    touch(): void;
+    /** Stop the pump, cut an in-flight throttle short, and await any in-flight write — so the
+     *  caller's terminal write is strictly the LAST one (no stale frame landing after the answer). */
+    finish(): Promise<void>;
+}
+export declare function createPreviewPump(opts: {
+    /** Write the LATEST view. Best-effort — the terminal write is authoritative. */
+    flush: () => Promise<void>;
+    /** Pace + coalesce a burst into one write; finish() interrupts a throttle in progress. */
+    throttleMs: number;
+    /** Called for the FIRST failing flush only (the pump keeps running): a never-rendering preview
+     *  must be diagnosable, not silent — and not a log flood. */
+    onError: (error: unknown) => void;
+}): PreviewPump;
+/**
+ * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool
+ * does rather than expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue",
+ * not "mcp__github__create_issue"). Deliberately generic and engine-neutral: it only reshapes the
+ * identifier string — it never invents semantics and never exposes arguments. An `mcp__server__tool`
+ * identifier becomes `server: tool`; any other identifier has its separators normalized to spaces and
+ * its first letter capitalized.
+ */
+export declare function humanizeToolName(name: string): string;
+export {};