@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/channels/feishu/preview.js

@@ -1,57 +1,37 @@
 /**
- * Canonical Feishu live-preview rendering (also reused by Lark compatibility). The preview is ONE
- * streaming CARD of TWO elements — the volatile `process` block and the append-only `answer` (see
- * card.ts for why the split is the prefix-stability fix) — (create entity → mount it with a
- * reply/send → stream full-text snapshots per element with a strictly increasing `sequence`; the
- * client renders the typewriter effect); on completion the same card is settled in place with the
- * final answer alone (streaming off). Streaming
- * updates ride the cardkit quota (50 QPS per app, 10 QPS per card entity, no edit ceiling) — NOT the
- * 5 QPS per-chat message quota or
- * the 20-edit cap on text messages, which is why the preview is a card and not an edited text message.
+ * Canonical Feishu live-preview rendering (also reused by Lark compatibility). The preview is ONE streaming CARD of
+ * two elements — the volatile `process` block and the append-only `answer` (card.ts explains why the split is the
+ * prefix-stability fix) — streamed as full-text snapshots per element under a strictly increasing `sequence`, then
+ * settled in place with the final answer alone. A queued turn mounts the same card early with its queue status and
+ * execution takes the entity over, so there is no second reply. Streaming rides the cardkit quota, not the 5 QPS
+ * per-chat message quota or the 20-edit cap on text messages — which is why the preview is a card.
  *
- * A queued turn mounts this same card early with its queue status, reply-quoted to that turn's source
- * message; when execution starts the preview takes the entity over in place. This mirrors Telegram's
- * one-message lifecycle without trying to change a text message into a card (which the platform does
- * not support), and keeps multiple queued asks attributable even if their card mounts race visually.
- *
- * Fallback tier (fail visibly, degrade per turn): if the card cannot be created or mounted, the turn
- * runs with a TEXT placeholder and NO live updates (text edits are capped at 20 per message, so the
- * text tier spends them only on terminal writes); if the platform closes streaming mid-turn (idle
- * timeout), the preview freezes and the settle still lands. The final write is authoritative either
- * way, mirroring the telegram preview's terminal-write matrix (completed/failed/abnormal ×
- * settle/delete+send/suppress).
+ * Degrade tiers (fail visibly, per turn): a card that cannot be created or mounted falls back to a TEXT placeholder
+ * with NO live updates; streaming closed mid-turn freezes the preview. The final write is authoritative either way.
  */
 import { setTimeout as sleep } from "node:timers/promises";
+import * as Effect from "effect/Effect";
+import * as Clock from "effect/Clock";
+import { previewPump, renderReply } from "../kit/delivery.js";
+import { portJoin } from "../../effect-port.js";
 import { log } from "../../log.js";
 import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, PROCESS_ELEMENT_ID, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
 import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
-import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../kit/preview-kit.js";
+import { DROPPABLE_FRAME } from "../kit/transport.js";
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../kit/preview-kit.js";
 import { truncateCodePointPrefix, truncateUtf8 } from "../kit/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). */
+/** How often (ms) to push a live-preview snapshot; tool events still flush on the next loop. */
 const STREAM_THROTTLE_MS = 1000;
 /** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
 const THINKING_PREVIEW = 280;
-/** Cap (code points) on the whole process block — thinking tail + tool lines + retry notice. It
- *  redraws wholly on change anyway (it is volatile by nature), so over budget the newest COMPLETE
- *  lines win (see tailLines). ≤1000 points is ≤4 KB UTF-8, which together with the answer's byte cap
- *  stays inside the 30 KB entity budget. */
+/** Cap (code points) on the whole process block — thinking tail + tool lines + retry notice. */
 const PROCESS_MAX_POINTS = 1000;
-/** Cap the live answer 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 answer freezes at its head rather than sliding a
- *  tail window (which would re-type the element every frame). The full answer still lands at settle. */
+/** Cap the live answer to the card budget, PREFIX-STABLE. */
 function capBytes(s, maxBytes) {
     return truncateUtf8(s, maxBytes);
 }
-/** Tail-select COMPLETE lines within a code-point budget — the process block's cap. The block's
- *  lines are semantic units (a `🔧` tool call, the `💭` peek, the `⏳` notice): cutting mid-line
- *  would orphan a marker or tear a label, so elision happens only at line boundaries, newest lines
- *  kept, with a leading `…` line marking what was dropped. The in-line guard cannot trigger with the
- *  bounded renderers (a thinking tail ≤ ~283 points, a tool line ≤ ~135) — it exists so a future
- *  unbounded line degrades to a head-preserving cut instead of an empty block. */
+/** Tail-select COMPLETE lines within a code-point budget — the process block's cap. */
 function tailLines(text, maxPoints) {
     if (Array.from(text).length <= maxPoints)
         return text;
@@ -70,13 +50,7 @@ function tailLines(text, maxPoints) {
         return truncateCodePointPrefix(lines.at(-1) ?? "", maxPoints);
     return `…\n${kept.join("\n")}`;
 }
-/**
- * The terminal-write POLICY: resolve the preview into `text`. One card → settle it in place (final
- * markdown, streaming off); an over-budget answer settles the card with its first chunk and sends the
- * rest as follow-up messages. A failed settle falls back to delete + fresh send, so no "Thinking…" card
- * is left pinned above the answer. Text tier → ONE edit into the final text (or delete + fresh sends
- * when it doesn't fit). No preview → fresh send. EMPTY text = "say nothing" → just delete the preview.
- */
+/** The terminal-write POLICY: resolve the preview into `text`. */
 async function finalize(api, target, preview, text, seq) {
     if (text.trim() === "") {
         if (preview.kind !== "none")
@@ -94,11 +68,7 @@ async function finalize(api, target, preview, text, seq) {
             // Settle failed (card expired / rejected) — fall through to delete + fresh send below.
         }
         if (settled) {
-            // Threaded continuations must keep reply_in_thread; top-level group replies (target.replyInThread
-            // unset — a custom route, or an ask outside a thread) intentionally avoid repeating the quote on
-            // every chunk. sendText owns the same distinction for its own chunking.
-            // A continuation failure propagates: the card is already authoritative, so deleting it and sending
-            // the full answer again would deterministically duplicate every continuation that already landed.
+            // Threaded continuations must keep reply_in_thread.
             const continuationTarget = target.replyInThread ? target : { chatId: target.chatId };
             for (const chunk of rest)
                 await api.sendText(continuationTarget, chunk);
@@ -121,10 +91,8 @@ async function finalize(api, target, preview, text, seq) {
     await api.sendText(target, text);
 }
 /**
- * Mount one preview message: preferably a streaming card entity (`initial` seeds the process element;
- * the answer element starts empty), with a static text message as the visible fallback. Queue feedback
- * and ordinary turn startup share this constructor so a queued card has exactly the same shape the
- * stream pump expects to take over later.
+ * Mount one preview message: preferably a streaming card entity (`initial` seeds the process element; the answer
+ * element starts empty), with a static text message as the visible fallback.
  */
 export async function mountFeishuPreview(api, target, initial, label = "[feishu]") {
     try {
@@ -134,10 +102,7 @@ export async function mountFeishuPreview(api, target, initial, label = "[feishu]
             ? api.replyMessage(target.replyTo, "interactive", content, { replyInThread: target.replyInThread })
             : api.sendMessage(target.chatId, "interactive", content);
         let messageId;
-        // Field-observed: the mount can reject a JUST-minted card id (code 230099 / "cardid is invalid")
-        // — the entity is not yet visible to the IM side (eventual consistency between cardkit and IM).
-        // That specific rejection gets a short backoff and another try before degrading; anything else
-        // degrades immediately.
+        // Field-observed: the mount can reject a JUST-minted card id (code 230099 / "cardid is invalid").
         for (let attempt = 1;; attempt++) {
             try {
                 messageId = await mountOnce();
@@ -155,8 +120,8 @@ export async function mountFeishuPreview(api, target, initial, label = "[feishu]
         return { kind: "card", cardId, messageId };
     }
     catch (e) {
-        // Card tier failed — degrade to a text placeholder with NO live updates (the text tier's 20-edit
-        // cap is spent on terminal writes only). Visible: the operator learns why the preview is static.
+        // Card tier failed — degrade to a text placeholder with NO live updates (the text tier's 20-edit cap is spent on
+        // terminal writes only).
         log.warn(`${label} streaming card unavailable — live preview degrades to a static placeholder: ${String(e)}`);
         const messageId = target.replyTo !== undefined
             ? await api.replyMessage(target.replyTo, "text", JSON.stringify({ text: initial }), {
@@ -168,163 +133,99 @@ export async function mountFeishuPreview(api, target, initial, label = "[feishu]
         return { kind: "text", messageId };
     }
 }
-/** Settle an already-mounted queue preview without starting an Agent stream (the poison/defer paths).
- * Card and text tiers both change in place; only a missing/failed preview sends a fresh message. */
+/**
+ * Settle a preview without starting an Agent stream: a queue/poison/defer notice, or a recovered answer whose own
+ * preview died with the run that produced it (`undefined` — then it is one fresh message).
+ */
 export async function settleFeishuPreview(api, target, preview, text) {
     let sequence = 0;
     await finalize(api, target, preview ?? { kind: "none" }, text, () => ++sequence);
 }
 /**
- * Consume one turn's event stream into a Feishu-compatible chat, live (see the module header for the preview
- * model). Preview updates are best-effort (logged once if they fail); the final write is authoritative
- * and surfaces a real failure (bad credentials, etc.). `initialPreview`, when present, is the queued
- * turn's already-mounted card/text message: the pump and terminal write mutate that same message rather
- * than recalling it and posting another reply.
+ * Consume one turn's event stream into a Feishu-compatible chat, live.
  */
-export async function streamFeishuReply(events, api, target, formatError, initialPreview, label = "[feishu]") {
-    // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
-    // policy, the card-budget caps, and delivery below. The card is TWO elements (card.ts): the process
-    // block's head changes every frame (sliding thinking tail, `…`→`✓` flips), so it must never share
-    // an element with the answer — the client would re-type the whole card from the divergence point
-    // once a second. Each view feeds its own element; only the changed one is written.
-    const turn = createTurnView();
-    const processView = () => {
-        const v = composeTurnBody([
-            thinkingLine(turn, THINKING_PREVIEW),
-            toolLines(turn),
-            turn.retrying ? RETRY_NOTICE : "",
-        ]);
-        if (v !== "")
-            return tailLines(v, PROCESS_MAX_POINTS);
-        // No process content: the placeholder covers only the silence BEFORE the answer reveals — once
-        // the answer is streaming, an empty block goes (stays) empty; "Thinking…" pinned above a live
-        // answer would misstate the phase. The empty frame is a real write: it clears a mounted
-        // placeholder. (The block cannot otherwise flicker: thinking and tools only grow — only the
-        // retry notice toggles, and its empty state resolves through this same rule.)
-        return revealedAnswer(turn, STREAM_THROTTLE_MS).trim() === "" ? THINKING_PLACEHOLDER : "";
-    };
-    const answerView = () => capBytes(revealedAnswer(turn, STREAM_THROTTLE_MS), CARD_MARKDOWN_MAX_BYTES);
-    // The live preview is ONE message: either the queue card/text handed in by the wiring, or a preview
-    // mounted lazily on this turn's first flush. `sequence` must increase strictly per card — the single-
-    // writer pump guarantees it by construction. A queue card has had no updates yet, so sequence starts
-    // at zero in both paths.
-    let preview = initialPreview ?? { kind: "none" };
-    let setupAttempted = initialPreview !== undefined;
-    let sequence = 0;
-    const nextSeq = () => ++sequence;
-    let streamDead = false; // the platform closed streaming (idle timeout) — freeze the live view
-    let finalized = false; // a terminal write (completed/failed) ran — the finally skips its orphan cleanup
-    let lastProcess = "";
-    let lastAnswer = "";
-    const flushPreview = async () => {
-        const process = processView();
-        if (!setupAttempted) {
-            setupAttempted = true;
-            // The mount seeds the process element with the current view; the answer element starts empty
-            // (card.ts), so the first answer snapshot is a clean prefix extension.
-            preview = await mountFeishuPreview(api, target, process, label);
-            lastProcess = process;
-            return;
-        }
-        if (preview.kind !== "card" || streamDead)
-            return; // text tier / dead stream: frozen until the terminal write
-        try {
-            // `last*` advances BEFORE each write: a frame that fails for a non-streaming reason is logged
-            // once (the pump's onError) and not re-sent until its content actually changes. An EMPTY
-            // process frame is written like any other — it is the placeholder being cleared (processView).
-            if (process !== lastProcess) {
+export function feishuReply(events, api, target, formatError, initialPreview, label = "[feishu]", onAnswered) {
+    return Effect.gen(function* () {
+        const clock = yield* Clock.Clock;
+        const now = () => clock.currentTimeMillisUnsafe();
+        // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal policy, the
+        // card-budget caps, and delivery below.
+        const turn = createTurnView();
+        const processView = () => {
+            const v = composeTurnBody([
+                thinkingLine(turn, THINKING_PREVIEW),
+                toolLines(turn),
+                turn.retrying ? RETRY_NOTICE : "",
+            ]);
+            if (v !== "")
+                return tailLines(v, PROCESS_MAX_POINTS);
+            // No process content: the placeholder covers only the silence BEFORE the answer reveals.
+            return revealedAnswer(turn, STREAM_THROTTLE_MS, now()).trim() === "" ? THINKING_PLACEHOLDER : "";
+        };
+        const answerView = () => capBytes(revealedAnswer(turn, STREAM_THROTTLE_MS, now()), CARD_MARKDOWN_MAX_BYTES);
+        // The live preview is ONE message: either the queue card/text handed in by the wiring, or a preview mounted
+        // lazily on this turn's first flush.
+        let preview = initialPreview ?? { kind: "none" };
+        let setupAttempted = initialPreview !== undefined;
+        let sequence = 0;
+        const nextSeq = () => ++sequence;
+        let streamDead = false; // the platform closed streaming (idle timeout) — freeze the live view
+        let lastProcess = "";
+        let lastAnswer = "";
+        const flushPreview = async () => {
+            const process = processView();
+            if (!setupAttempted) {
+                setupAttempted = true;
+                // The mount seeds the process element with the current view; the answer element starts empty (card.ts), so
+                // the first answer snapshot is a clean prefix extension.
+                preview = await mountFeishuPreview(api, target, process, label);
                 lastProcess = process;
-                await api.updateCardElement(preview.cardId, PROCESS_ELEMENT_ID, process, nextSeq());
-            }
-            const answer = answerView();
-            // Never write an empty answer snapshot — the element is born empty and the answer only grows.
-            if (answer !== "" && answer !== lastAnswer) {
-                lastAnswer = answer;
-                await api.updateCardElement(preview.cardId, ANSWER_ELEMENT_ID, answer, nextSeq());
-            }
-        }
-        catch (e) {
-            if (isCardStreamingClosed(e)) {
-                // The platform closed streaming (idle timeout). Freeze the live view; the settle write replaces
-                // the whole entity (streaming off) and still lands.
-                streamDead = true;
-                log.warn(`${label} card streaming closed mid-turn — preview frozen; the final answer still lands`);
-                return;
-            }
-            throw e;
-        }
-    };
-    // 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
-    /** 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 === "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(turn.answer.trim() !== "" ? turn.answer : "(no reply)");
                 return;
             }
-            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
-                // write as completed; an empty notice deletes the preview (suppress = no residue). Best-effort —
-                // we throw below regardless.
-                finalized = true;
-                {
-                    const msg = formatError({
-                        details: e.details,
-                        retryable: e.retryable,
-                        ...(e.code !== undefined ? { code: e.code } : {}),
-                    }) ?? "";
-                    try {
-                        await settle(msg);
-                    }
-                    catch (deliveryError) {
-                        // Preserve the Agent failure as the primary error below, but keep the broken final hop in
-                        // the operator-visible chain — otherwise the log falsely implies the user saw the notice.
-                        log.error(`${label} failed to deliver the agent-failure notice: ${String(deliveryError)}`);
-                    }
-                }
-                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
-    }
-    finally {
-        await finish();
-        // Abnormal exit (stream ended without a terminal, the generator threw, or the consumer abandoned):
-        // no terminal write ran. Show the SAME neutral notice a `failed` event would — the preview may show
-        // real partial work, so don't delete it silently, and don't leave the user in silence. A suppressing
-        // onError still collapses to a delete (finalize on empty text).
-        if (!finalized) {
-            // retryable:false — an abnormal end (no terminal / a throw) is of UNKNOWN retryability, so use the
-            // neutral "something went wrong" default rather than promising "try again" that may not help.
-            const notice = formatError({ details: "the turn ended without completing", retryable: false }) ?? "";
+            if (preview.kind !== "card" || streamDead)
+                return; // text tier / dead stream: frozen until the terminal write
             try {
-                await settle(notice);
+                // `last*` advances BEFORE each write: a frame that fails for a non-streaming reason is logged once (the
+                // pump's onError) and not re-sent until its content actually changes.
+                const answer = answerView();
+                // Never write an empty answer snapshot — the element is born empty and the answer only grows.
+                if (answer !== "" && answer !== lastAnswer) {
+                    lastAnswer = answer;
+                    await api.updateCardElement(preview.cardId, ANSWER_ELEMENT_ID, answer, nextSeq(), DROPPABLE_FRAME);
+                }
+                if (process !== lastProcess) {
+                    lastProcess = process;
+                    await api.updateCardElement(preview.cardId, PROCESS_ELEMENT_ID, process, nextSeq(), DROPPABLE_FRAME);
+                }
             }
-            catch (deliveryError) {
-                // The stream's original throw remains primary; this explicit line records that the user-facing
-                // terminal notice failed too instead of silently breaking the responsibility chain.
-                log.error(`${label} failed to deliver the abnormal-turn notice: ${String(deliveryError)}`);
+            catch (e) {
+                if (isCardStreamingClosed(e)) {
+                    // The platform closed streaming (idle timeout).
+                    streamDead = true;
+                    log.warn(`${label} card streaming closed mid-turn — preview frozen; the final answer still lands`);
+                    return;
+                }
+                throw e;
             }
-        }
-    }
+        };
+        // The scoped single writer keeps card sequences ordered through the terminal update.
+        const { touch, finish } = yield* previewPump({
+            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
+        yield* renderReply(events, {
+            label,
+            finish,
+            formatError,
+            onEvent: (event) => {
+                if (applyTurnEvent(turn, event, now()))
+                    touch();
+            },
+            answer: () => (turn.answer.trim() !== "" ? turn.answer : "(no reply)"),
+            ...(onAnswered ? { onAnswered } : {}),
+            settle: (text) => portJoin(() => finalize(api, target, preview, text, nextSeq)),
+        });
+    });
 }

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

@@ -1,25 +1,13 @@
 /**
- * One-click app creation ("scan to create") — the OAuth 2.0 Device Authorization Grant (RFC 8628)
- * flow the platform provides for agent apps: `begin` returns a one-time verification URL the user
- * opens in Feishu/Lark and confirms (the platform pre-configures the agent app template: bot
- * capability, messaging scopes, event subscriptions); polling returns the new app's credentials.
- *
- * Hand-rolled on fetch, no SDK: the wire protocol is two form-encoded POSTs to the accounts endpoint
- * plus RFC 8628's polling error dance — shared verbatim by all four official SDKs (node/python/java/go),
- * which makes it a de-facto stable surface even though only the SDKs document it. Provenance:
- * larksuite/node-sdk `scene/registration` (registerApp). If the platform ever moves this behind
- * something non-trivial (signed payloads, websockets), adopt the official SDK instead of chasing it —
- * the same tripwire as feishu-api.ts.
- *
- * The scanning user's tenant decides the brand: a Lark-tenant user flips polling to the Lark accounts
- * domain mid-flow (`tenant_brand: "lark"`), and the result carries the brand so the caller can point
- * everything else (API origin) at the right cloud.
+ * One-click app creation ("scan to create") — the OAuth 2.0 Device Authorization Grant (RFC 8628) flow the platform
+ * provides for agent apps: `begin` returns a one-time verification URL the user opens in Feishu/Lark and confirms,
+ * then polling returns the new app's credentials. Hand-rolled on fetch because the wire protocol (two form-encoded
+ * POSTs plus RFC 8628's polling error dance) is shared verbatim by all four official SDKs; if the platform ever moves
+ * it behind something non-trivial, adopt the official SDK rather than chasing it.
  */
 /**
- * Additive app config carried on the confirm-page URL (`addons` query param): extra scopes/events
- * merged ON TOP of the platform's agent template — base permissions can never be removed. Shape and
- * 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.
+ * Additive app config carried on the confirm-page URL (`addons` query param): extra scopes/events merged ON TOP of the
+ * platform's agent template.
  */
 interface FeishuAppAddons {
     scopes?: {
@@ -48,7 +36,6 @@ export interface RegisterFeishuAppOptions {
         url: string;
         expiresInS: number;
     }) => void;
-    /** Cancel the polling. */
     signal?: AbortSignal;
     /** Accounts origins, for tests. */
     accountsBaseUrl?: string;
@@ -63,9 +50,7 @@ export interface RegisteredFeishuApp {
     openId?: string;
 }
 /**
- * Run the scan-to-create flow (module header): begin → hand the verification URL to the caller →
- * poll until the user confirms. Resolves with the new app's credentials; rejects on denial, expiry,
- * abort, or a transport failure — every rejection is a plain Error whose message says what to do.
+ * Run the scan-to-create flow: begin → hand the verification URL to the caller → poll until the user confirms.
  */
 export declare function registerFeishuApp(options: RegisterFeishuAppOptions): Promise<RegisteredFeishuApp>;
 export {};

package/dist/channels/feishu/register-app.js

@@ -1,19 +1,9 @@
 /**
- * One-click app creation ("scan to create") — the OAuth 2.0 Device Authorization Grant (RFC 8628)
- * flow the platform provides for agent apps: `begin` returns a one-time verification URL the user
- * opens in Feishu/Lark and confirms (the platform pre-configures the agent app template: bot
- * capability, messaging scopes, event subscriptions); polling returns the new app's credentials.
- *
- * Hand-rolled on fetch, no SDK: the wire protocol is two form-encoded POSTs to the accounts endpoint
- * plus RFC 8628's polling error dance — shared verbatim by all four official SDKs (node/python/java/go),
- * which makes it a de-facto stable surface even though only the SDKs document it. Provenance:
- * larksuite/node-sdk `scene/registration` (registerApp). If the platform ever moves this behind
- * something non-trivial (signed payloads, websockets), adopt the official SDK instead of chasing it —
- * the same tripwire as feishu-api.ts.
- *
- * The scanning user's tenant decides the brand: a Lark-tenant user flips polling to the Lark accounts
- * domain mid-flow (`tenant_brand: "lark"`), and the result carries the brand so the caller can point
- * everything else (API origin) at the right cloud.
+ * One-click app creation ("scan to create") — the OAuth 2.0 Device Authorization Grant (RFC 8628) flow the platform
+ * provides for agent apps: `begin` returns a one-time verification URL the user opens in Feishu/Lark and confirms,
+ * then polling returns the new app's credentials. Hand-rolled on fetch because the wire protocol (two form-encoded
+ * POSTs plus RFC 8628's polling error dance) is shared verbatim by all four official SDKs; if the platform ever moves
+ * it behind something non-trivial, adopt the official SDK rather than chasing it.
  */
 import { gzipSync } from "node:zlib";
 /** Feishu accounts endpoint (the flow starts here for every user; a Lark-tenant scan switches over). */
@@ -32,8 +22,7 @@ function encodeAddons(addons) {
 }
 /** RFC 8628 device-flow states whose non-2xx JSON bodies belong to the polling state machine. */
 const DEVICE_FLOW_ERRORS = new Set(["authorization_pending", "slow_down", "access_denied", "expired_token"]);
-/** One registration POST (form-encoded). RFC 8628 delivers polling states (authorization_pending,
- *  slow_down, …) as HTTP 400 with a JSON body — those parse as data, not as transport failures. */
+/** One registration POST (form-encoded). */
 async function post(baseUrl, params) {
     let res;
     let raw;
@@ -67,9 +56,7 @@ async function post(baseUrl, params) {
 /** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers. */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
- * Run the scan-to-create flow (module header): begin → hand the verification URL to the caller →
- * poll until the user confirms. Resolves with the new app's credentials; rejects on denial, expiry,
- * abort, or a transport failure — every rejection is a plain Error whose message says what to do.
+ * Run the scan-to-create flow: begin → hand the verification URL to the caller → poll until the user confirms.
  */
 export async function registerFeishuApp(options) {
     const feishuBase = options.accountsBaseUrl ?? FEISHU_ACCOUNTS;

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

@@ -1,13 +1,6 @@
 import { type RegistrationOutcome } from "../registration.ts";
 import { type FeishuCloudKind } from "./cloud.ts";
-/**
- * Register `<baseUrl>/<kind>` as the app's event Request URL (webhook mode). Missing credentials print
- * the manual instruction instead of failing. `opts` carries the attempt budget — `--tunnel` takes the
- * default, `deploy --run` passes `DEPLOY_REGISTRATION_ATTEMPTS` (a host starts slower than a tunnel) —
- * plus `apiBase`, which is a test's fake platform (production derives it from the kind).
- *
- * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
- */
+/** Register `<baseUrl>/<kind>` as the app's event Request URL (webhook mode). */
 interface FeishuManualRegistration {
     consoleUrl: string;
     requestUrl: string;
@@ -16,7 +9,7 @@ export interface RegisterFeishuWebhookOptions {
     attempts?: number;
     retryMs?: number;
     apiBase?: string;
-    /** Manual fallback after a definitive config error or exhausted retries. Local dev opens this App. */
+    /** Manual fallback after a definitive config error or exhausted retries. */
     onManualRegistration?: (info: FeishuManualRegistration) => void;
 }
 export declare function registerFeishuWebhook(baseUrl: string, kind: FeishuCloudKind, opts?: RegisterFeishuWebhookOptions): Promise<RegistrationOutcome>;

package/dist/channels/feishu/register-webhook.js

@@ -1,24 +1,6 @@
 /**
- * Feishu/Lark event-URL registration — the platform-domain step both `--tunnel` (dev, tunnel.ts) and
- * `deploy … --run` (the host runners' post-deploy step) invoke, once per mounted kind. What
- * "registering feishu/lark" means lives here, beside the engine it serves; it reads the same .env
- * credentials the channel of that kind uses (`FEISHU_*` / `LARK_*`).
- *
- * Mechanism: the application-v7 config PATCH (`updateEventSubscription`) flips the app's event
- * subscription to webhook mode and points it at `<baseUrl>/<kind>`. Two properties make this the full
- * telegram-setWebhook parity: the platform applies a request-URL change IMMEDIATELY (no version
- * publish), and it VERIFIES the URL with a url_verification challenge during the PATCH — which makes
- * the PATCH its own readiness probe, retried below. (It used to poll `<baseUrl>/health` from here
- * first; that asked whether THIS machine could reach a freshly minted hostname, which is routinely
- * false for a minute or more while the platform reaches it fine — #421.) Requires the
- * `application:application:patch` scope (field-tested: `self_manage` does NOT cover this PATCH) —
- * `add feishu` requests it at creation via addons; without it the PATCH fails visibly and the manual
- * console instruction is printed.
- *
- * CLOUD LAG: the application-v7 config API exists on open.feishu.cn but (as of 2026-07) is NOT
- * deployed on open.larksuite.com — the route 404s there. The registrar still attempts it (the day the
- * platform ships it, registration starts working with no change here) and names the real cause in the
- * fallback instead of blaming the app's scopes.
+ * Feishu/Lark event-URL registration — the platform-domain step both `--tunnel` (dev, tunnel.ts) and `deploy … --run`
+ * (the host runners' post-deploy step) invoke, once per mounted kind.
  */
 import { log } from "../../log.js";
 import { retryWhile } from "../registration.js";
@@ -52,10 +34,7 @@ export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
             log.warn(`[fastagent] ${kind}: could not open Events & Callbacks: ${String(callbackError)}`);
         }
     };
-    // The PATCH is the probe (same lesson as the token bootstrap): the platform verifies request_url
-    // with a challenge DURING the call, so its 210042 "request_url validation failed" is the readiness
-    // signal and is retried with backoff, alongside transient network errors. Only a permanent config
-    // error (missing scope, app under review, the intl 404) is reported once with the manual path.
+    // The PATCH is the probe (same lesson as the token bootstrap).
     try {
         await retryWhile(() => api.updateEventSubscription(appId, { subscriptionType: "webhook", requestUrl }), isTransientFeishuRegistrationError, {
             attempts: opts.attempts,
@@ -63,25 +42,22 @@ export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
             onRetry: ({ attempt, attempts }) => log.info(`[fastagent] ${kind}: the platform cannot verify ${requestUrl} yet (attempt ${attempt}/${attempts}); retrying…`),
         });
         log.info(`[fastagent] ${kind}: event Request URL registered → ${requestUrl}`);
-        // Field-tested: a URL change applies immediately, but the MODE flip (the template's long
-        // connection → webhook) only takes effect when a version is published — the dispatcher serves
-        // the published snapshot, and version publishing has no open API. One console click, once.
+        // Field-tested: a URL change applies immediately, but the MODE flip (the template's long connection → webhook)
+        // only takes effect when a version is published.
         log.info(`[fastagent] ${kind}: if messages do not arrive, publish a version (one click, prompted) — the switch to webhook mode takes effect on publish: ${versionUrl}`);
         return "registered";
     }
     catch (e) {
-        // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is
-        // live on open.feishu.cn but not yet on open.larksuite.com. Name that — "check your scopes"
-        // would send the operator hunting for a problem they cannot fix. It stays WARN: on that cloud the
-        // manual path is the known norm, not an exceptional failure.
+        // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is live on
+        // open.feishu.cn but not yet on open.larksuite.com.
         if (isFeishuConfigApiMissing(e)) {
             log.warn(`[fastagent] ${kind}: this cloud (${apiBase}) returned HTTP 404 for the app-config API — ` +
                 `manual registration is required`);
             manualRegistration();
             return "manual"; // that cloud has no config API — the manual path is the norm there
         }
-        // Exhausted retries end in the same state as a permanent config error (event URL not registered,
-        // manual action required) — report at the same level.
+        // Exhausted retries end in the same state as a permanent config error (event URL not registered, manual action
+        // required) — report at the same level.
         log.error(isTransientFeishuRegistrationError(e)
             ? `[fastagent] ${kind}: the platform could not verify ${requestUrl} after retries — manual registration is required`
             : `[fastagent] ${kind}: could not register the event URL (${String(e)}). ` +