@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/channels/discover.d.ts

@@ -1,54 +1,33 @@
 import type { ChannelContext, LongConnection, Routes } from "../channel.ts";
 import { type ModuleLoadFailure } from "../loader.ts";
-/** A dropped route: two channels claim the same key. Surfaced, never silent. */
+import { type DeclaredSecret } from "../declared-secrets.ts";
+/** A dropped route: two channels claim the same key. */
 export interface ChannelCollision {
     route: string;
     source: string;
 }
-/** A long-connection module bound to the same context route factories receive. Internal serving shape. */
+/** A long-connection module bound to the same context route factories receive. */
 export interface LoadedLongConnectionChannel {
     name: string;
     connect(signal: AbortSignal): LongConnection;
 }
-/**
- * HOW A CHANNEL IS REACHED — the authored structural fact, and the ONE shape it travels in.
- *
- * A webhook channel is reached at a URL someone must set; a long-connection channel dials out, so
- * there is no URL and setting one breaks it (Telegram answers `getUpdates` with 409 once a webhook
- * exists). Everything downstream — which secrets to carry, what the runbook says, what `--run` and
- * `--tunnel` register — is a question about THIS.
- *
- * It is one list because it used to be three (`channels` + `routeChannels` + `longConnectionChannels`,
- * two of them including custom channels and one not), and every consumer re-derived the answer from
- * whichever pair it happened to hold. Two deploys shipped a webhook for a long-connection channel
- * that way. A list of pairs cannot be recombined wrongly, and a consumer that needs a subset asks for
- * it here rather than trusting its caller to have filtered.
- */
+/** HOW A CHANNEL IS REACHED — the authored structural fact, and the ONE shape it travels in. */
 export type ChannelIngress = "webhook" | "long-connection";
-/** One channel a directory declares, with the ingress its module shape says it has. `name` is the
- *  basename, which is a {@link ChannelKind} for the first-party ones and anything for a custom one. */
+/** One channel a directory declares, with the ingress its module shape says it has. */
 export interface DeclaredChannel {
     name: string;
     ingress: ChannelIngress;
 }
-/** Declared channels from basenames that share one ingress: the serving surface's mounted route list
- *  (a long-connection channel mounts no HTTP route, so every route IS a webhook channel), and fixtures. */
+/** Declared channels from basenames that share one ingress. */
 export declare function declaredChannels(names: readonly string[], ingress?: ChannelIngress): DeclaredChannel[];
-/**
- * Import channel files without mounting route factories or opening connections. Deployment needs only
- * the authored structural fact: function exports are webhook channels; `{ connect() }` exports are
- * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
- */
+/** Import channel files without mounting route factories or opening connections. */
 export declare function inspectChannels(dir: string): Promise<{
     channels: DeclaredChannel[];
+    /** What each channel declared through {@link defineChannel}, BY CHANNEL NAME — the only way a
+     *  CUSTOM channel's credentials can reach a deploy, since nothing else here can name them. */
+    secrets: Map<string, DeclaredSecret[]>;
     failures: ModuleLoadFailure[];
 }>;
-/**
- * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing. A symlinked channels directory must remain inside the agent dir.
- */
-export declare function discoverChannelFiles(dir: string): Promise<string[]>;
-/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
 export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<{
     routes: Routes;
     longConnections: LoadedLongConnectionChannel[];

package/dist/channels/discover.js

@@ -1,13 +1,9 @@
-/**
- * Channel discovery (the N axis, filesystem form). A channel file default-exports either the existing
- * route factory `(ctx) => Routes`, or an explicit long-connection module `{ name, connect(ctx, signal) }`.
- *
- * Engine-neutral, and living here rather than under `engines/` because of it: reading `channels/*.ts`
- * is the Channel contract plus a directory, with no engine in sight.
- */
+/** Channel discovery (the N axis, filesystem form). */
 import { isAbsolute, join } from "node:path";
 import { assertRouteKey, routeKeysConflict } from "./serve.js";
-import { loadModuleDir, moduleInventory } from "../loader.js";
+import { loadModuleDir } from "../loader.js";
+import { readSecretDeclaration } from "../declared-secrets.js";
+import { gateSecrets } from "../secrets-gate.js";
 import { assertInsideAgentDir } from "../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
@@ -17,47 +13,38 @@ function validateLongConnectionModule(value, label) {
         throw new Error(`${label}: long-connection channel name must be a non-empty string`);
     }
 }
-/** Declared channels from basenames that share one ingress: the serving surface's mounted route list
- *  (a long-connection channel mounts no HTTP route, so every route IS a webhook channel), and fixtures. */
+/** Declared channels from basenames that share one ingress. */
 export function declaredChannels(names, ingress = "webhook") {
     return names.map((name) => ({ name, ingress }));
 }
-/**
- * Import channel files without mounting route factories or opening connections. Deployment needs only
- * the authored structural fact: function exports are webhook channels; `{ connect() }` exports are
- * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
- */
+/** Import channel files without mounting route factories or opening connections. */
 export async function inspectChannels(dir) {
     await assertInsideAgentDir(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const channels = [];
+    const secrets = new Map();
     for (const { name, label, file, mod } of modules) {
         try {
+            const declaration = readSecretDeclaration(mod.default, label);
+            if (declaration.error !== undefined)
+                throw new Error(declaration.error);
             if (typeof mod.default === "function") {
                 channels.push({ name, ingress: "webhook" });
-                continue;
             }
-            if (longConnectionModule(mod.default)) {
+            else if (longConnectionModule(mod.default)) {
                 validateLongConnectionModule(mod.default, label);
                 channels.push({ name, ingress: "long-connection" });
-                continue;
             }
-            throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
+            else {
+                throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
+            }
+            secrets.set(name, declaration.secrets);
         }
         catch (error) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { channels, failures };
-}
-/**
- * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing. A symlinked channels directory must remain inside the agent dir.
- */
-export async function discoverChannelFiles(dir) {
-    await assertInsideAgentDir(dir, "channels");
-    const entries = await moduleInventory(join(dir, "channels"));
-    return entries.map((entry) => entry.name);
+    return { channels, secrets, failures };
 }
 function validateRoutes(value, label) {
     if (value === null || typeof value !== "object" || value instanceof Map) {
@@ -75,7 +62,6 @@ function validateRoutes(value, label) {
     }
     return routes;
 }
-/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
 export async function loadChannels(dir, ctx) {
     if (!isAbsolute(ctx.stateRoot)) {
         throw new Error(`ChannelContext.stateRoot must be absolute, got "${ctx.stateRoot}"`);
@@ -86,7 +72,21 @@ export async function loadChannels(dir, ctx) {
     const longConnections = [];
     const routeChannels = [];
     const collisions = [];
-    for (const { name, label, file, mod } of modules) {
+    // Collected from the channels that actually MOUNTED, GATED at the end of the function: this is a
+    // serving path, so an unset declared value must stop it (a channel built from an empty credential
+    // is the failure the declaration exists to prevent — a webhook that accepts forged updates, a bot
+    // that cannot reply), while `inspectChannels` — the reporting reader — only collects. A channel
+    // that failed to mount does not gate: its own failure is the report the author needs.
+    const declaredSecrets = new Map();
+    const declaring = modules.flatMap((entry) => {
+        const declaration = readSecretDeclaration(entry.mod.default, entry.label);
+        if (declaration.error !== undefined) {
+            failures.push({ label: entry.label, file: entry.file, message: declaration.error });
+            return [];
+        }
+        return [{ ...entry, secrets: declaration.secrets }];
+    });
+    for (const { name, label, file, mod, secrets } of declaring) {
         try {
             if (longConnectionModule(mod.default)) {
                 validateLongConnectionModule(mod.default, label);
@@ -95,6 +95,7 @@ export async function loadChannels(dir, ctx) {
                     name: channel.name,
                     connect: (signal) => channel.connect(ctx, signal),
                 });
+                declaredSecrets.set(name, secrets);
                 continue;
             }
             if (typeof mod.default !== "function") {
@@ -117,10 +118,15 @@ export async function loadChannels(dir, ctx) {
                 routes[route] = handler;
             }
             routeChannels.push(name);
+            declaredSecrets.set(name, secrets);
         }
         catch (error) {
             failures.push({ label, file, message: error.message });
         }
     }
+    // Gated LAST, after the loop has said what it found (the gate reports those failures before it
+    // refuses — src/secrets-gate.ts, decision 2). Binding a module ahead of the gate costs nothing: a
+    // route factory builds handlers; nothing listens or dials until the caller mounts what this returns.
+    gateSecrets({ declared: declaredSecrets, failures });
     return { routes, longConnections, routeChannels, collisions, failures };
 }

package/dist/channels/feishu/bootstrap-token.d.ts

@@ -18,11 +18,9 @@ export interface FeishuBootstrapTokenOptions {
     } | undefined>;
     /** Budget for the whole capture (the challenge normally lands within the PATCH round-trip). */
     timeoutMs?: number;
-    /** PATCH attempts × delay — the PATCH is the one and only readiness probe (see below). */
+    /** PATCH attempts × delay — the PATCH is the one and only readiness probe. */
     patchAttempts?: number;
     patchRetryMs?: number;
-    /** Retry classifier. Default: retry every PATCH failure (Feishu edge warm-up compatibility).
-     * Lark onboarding rejects a definitive config-route 404 immediately so it can fall back by hand. */
     shouldRetryPatch?: (error: unknown) => boolean;
     /** Progress hooks: production prints the assigned URL/retries; tests keep transport IO injected. */
     onTunnelReady?: (url: string) => void;
@@ -33,10 +31,5 @@ export interface FeishuBootstrapTokenOptions {
         retryMs: number;
     }) => void;
 }
-/**
- * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
- * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
- * degrades to the manual console instruction.
- */
 export declare function bootstrapFeishuVerificationToken(options: FeishuBootstrapTokenOptions): Promise<string>;
 export {};

package/dist/channels/feishu/bootstrap-token.js

@@ -1,30 +1,15 @@
 /**
- * Verification-Token bootstrap — the token has NO read API (field-tested 2026-07: the v6 app detail
- * never returns `encryption`, and the v7 config route only supports PATCH). The platform's only
- * programmatic delivery is the `url_verification` challenge it POSTs to the request URL while an
- * event-subscription PATCH is verified — the challenge body carries `token`, the app's Verification
- * Token. So `add feishu`'s create flow finishes the job by: standing up a throwaway local responder,
- * exposing it on an ephemeral quick tunnel, PATCHing the app's event subscription at it, capturing
- * the token from the challenge, and tearing everything down. `dev --tunnel` / `deploy … --run`
- * re-PATCH the request URL onto the real server later (the token is app-level and survives that).
- *
- * Security: the serving path keeps its strict non-empty-token requirement — no bootstrap mode there.
- * The throwaway URL is random (unguessable), lives for seconds, and only the FIRST challenge is
- * accepted, immediately after our own credential-authenticated PATCH.
+ * Verification-Token bootstrap — the token has NO read API (field-tested 2026-07: the v6 app detail never returns
+ * `encryption`, and the v7 config route only supports PATCH).
  */
 import { createServer } from "node:http";
-/**
- * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
- * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
- * degrades to the manual console instruction.
- */
 export async function bootstrapFeishuVerificationToken(options) {
     let capturedToken;
     const token = new Promise((resolve) => {
         capturedToken = resolve;
     });
-    // The throwaway responder: answers /health (diagnostics) and the url_verification challenge
-    // (echo `challenge` back), capturing `token` from the FIRST challenge only.
+    // The throwaway responder: answers /health (diagnostics) and the url_verification challenge (echo `challenge`
+    // back), capturing `token` from the FIRST challenge only.
     const server = createServer((req, res) => {
         if (req.method === "GET") {
             res.end("ok");
@@ -46,7 +31,7 @@ export async function bootstrapFeishuVerificationToken(options) {
                 }
             }
             catch {
-                /* not the challenge — fall through to the empty ACK */
+                // not the challenge — fall through to the empty ACK
             }
             res.end("{}");
         });
@@ -59,9 +44,8 @@ export async function bootstrapFeishuVerificationToken(options) {
         if (!tunnel)
             throw new Error("no tunnel came up (is cloudflared installed?)");
         options.onTunnelReady?.(tunnel.url);
-        // Do NOT health-poll the edge here: "can WE reach it" says nothing about platform→edge, the path
-        // the challenge uses (field-tested: local negative-DNS caching failed while that path worked).
-        // PATCH immediately; it is the real probe because success requires the challenge round-trip.
+        // Do NOT health-poll the edge here: "can WE reach it" says nothing about platform→edge, the path the challenge
+        // uses (field-tested: local negative-DNS caching failed while that path worked).
         const attempts = options.patchAttempts ?? 8;
         for (let attempt = 1;; attempt++) {
             try {

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

@@ -1,21 +1,6 @@
 /**
- * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
- * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
- * the card DSL is data-in → string-out and testable without the pump.
- *
- * The streaming card is TWO markdown elements: `process` (the volatile block — thinking tail, tool
- * lines, retry notice) and `answer` (append-only). The pump PUTs full-text snapshots per element
- * (feishu-api.ts `updateCardElement`) and the client renders the typewriter effect. The split is the
- * prefix-stability rule made structural: the client animates an element's update only when the old
- * text is a PREFIX of the new — otherwise it re-types everything after the first divergent character.
- * The process block's head changes every frame (a sliding thinking tail, `…`→`✓` status flips), so
- * sharing one element with the answer re-typed the whole card once a second; two elements confine the
- * churn to the small process block and keep the answer's typewriter smooth. Settling replaces the
- * whole entity (`updateCard`) with the answer element alone, `streaming_mode` off — one write flips
- * content and mode together and drops the process block.
- *
- * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
- * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled final card,
+ * and the message content that mounts a card entity into a chat.
  */
 /** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export declare const ANSWER_ELEMENT_ID = "answer";
@@ -24,20 +9,21 @@ export declare const PROCESS_ELEMENT_ID = "process";
 /** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
 export declare const CARD_MARKDOWN_MAX_BYTES: number;
 /**
- * The answer's first line as plain text — what the chat list and the push notification show for the
- * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
- * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
- * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
- * emphasis/heading/list markers removed.
+ * The answer's first line as plain text — what the chat list and the push notification show for the settled card
+ * (`config.summary.content`).
  */
 export declare function cardSummary(markdown: string): string;
-/** The live-preview card entity: streaming on, the process element seeded with the placeholder/queue
- *  status and the answer element seeded EMPTY (the platform accepts an empty markdown element; it
- *  renders zero-height until the first answer snapshot lands as a clean prefix extension of ""). */
+/**
+ * The live-preview card entity: streaming on, the process element seeded with the placeholder/queue status and the
+ * answer element seeded EMPTY (the platform accepts an empty markdown element; it renders zero-height until the first
+ * answer snapshot lands as a clean prefix extension of "").
+ */
 export declare function streamingCardJson(initialProcess: string): string;
-/** The settled card: final markdown alone (the process block was preview-only), streaming off (stops
- *  the client's streaming affordance), plus the answer-derived summary so the chat list / notification
- *  shows the reply, not "[Card]". */
+/**
+ * The settled card: final markdown alone (the process block was preview-only), streaming off (stops the client's
+ * streaming affordance), plus the answer-derived summary so the chat list / notification shows the reply, not
+ * "[Card]".
+ */
 export declare function finalCardJson(markdown: string): string;
 /** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
 export declare function cardEntityContent(cardId: string): string;

package/dist/channels/feishu/card.js

@@ -1,21 +1,6 @@
 /**
- * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
- * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
- * the card DSL is data-in → string-out and testable without the pump.
- *
- * The streaming card is TWO markdown elements: `process` (the volatile block — thinking tail, tool
- * lines, retry notice) and `answer` (append-only). The pump PUTs full-text snapshots per element
- * (feishu-api.ts `updateCardElement`) and the client renders the typewriter effect. The split is the
- * prefix-stability rule made structural: the client animates an element's update only when the old
- * text is a PREFIX of the new — otherwise it re-types everything after the first divergent character.
- * The process block's head changes every frame (a sliding thinking tail, `…`→`✓` status flips), so
- * sharing one element with the answer re-typed the whole card once a second; two elements confine the
- * churn to the small process block and keep the answer's typewriter smooth. Settling replaces the
- * whole entity (`updateCard`) with the answer element alone, `streaming_mode` off — one write flips
- * content and mode together and drops the process block.
- *
- * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
- * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled final card,
+ * and the message content that mounts a card entity into a chat.
  */
 import { truncateCodePointPrefix } from "../kit/text.js";
 /** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
@@ -27,11 +12,8 @@ export const CARD_MARKDOWN_MAX_BYTES = 20 * 1024;
 /** Character budget for the settled card's summary (the chat-list / push-notification preview). */
 const SUMMARY_MAX_CHARS = 60;
 /**
- * The answer's first line as plain text — what the chat list and the push notification show for the
- * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
- * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
- * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
- * emphasis/heading/list markers removed.
+ * The answer's first line as plain text — what the chat list and the push notification show for the settled card
+ * (`config.summary.content`).
  */
 export function cardSummary(markdown) {
     const line = markdown
@@ -52,25 +34,29 @@ function cardJson(elements, streaming, summary) {
         config: {
             streaming_mode: streaming,
             update_multi: true,
-            // Only the settled card sets a summary — while streaming, the platform's default (a localized
-            // "[Generating…]") is better than any fixed text we could pin.
+            // Only the settled card sets a summary — while streaming, the platform's default (a localized "[Generating…]")
+            // is better than any fixed text we could pin.
             ...(summary ? { summary: { content: summary } } : {}),
         },
         body: { elements },
     });
 }
-/** The live-preview card entity: streaming on, the process element seeded with the placeholder/queue
- *  status and the answer element seeded EMPTY (the platform accepts an empty markdown element; it
- *  renders zero-height until the first answer snapshot lands as a clean prefix extension of ""). */
+/**
+ * The live-preview card entity: streaming on, the process element seeded with the placeholder/queue status and the
+ * answer element seeded EMPTY (the platform accepts an empty markdown element; it renders zero-height until the first
+ * answer snapshot lands as a clean prefix extension of "").
+ */
 export function streamingCardJson(initialProcess) {
     return cardJson([
         { tag: "markdown", content: initialProcess, element_id: PROCESS_ELEMENT_ID },
         { tag: "markdown", content: "", element_id: ANSWER_ELEMENT_ID },
     ], true);
 }
-/** The settled card: final markdown alone (the process block was preview-only), streaming off (stops
- *  the client's streaming affordance), plus the answer-derived summary so the chat list / notification
- *  shows the reply, not "[Card]". */
+/**
+ * The settled card: final markdown alone (the process block was preview-only), streaming off (stops the client's
+ * streaming affordance), plus the answer-derived summary so the chat list / notification shows the reply, not
+ * "[Card]".
+ */
 export function finalCardJson(markdown) {
     return cardJson([{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }], false, cardSummary(markdown));
 }

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

@@ -1,8 +1,4 @@
-/**
- * Feishu is the canonical implementation. Lark international speaks the same protocol but trails the
- * primary cloud in control-plane capabilities, so it binds the Feishu engine through this explicit
- * compatibility profile instead of becoming the engine's naming/design center.
- */
+/** Feishu is the canonical implementation. */
 export type FeishuCloudKind = "feishu" | "lark";
 export interface FeishuCloudProfile {
     kind: FeishuCloudKind;

package/dist/channels/feishu/context-buffer.d.ts

@@ -1,9 +1,4 @@
-/**
- * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
- * ../kit/context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
- * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
- * concrete thread root) and folded into the next answered turn in that place.
- */
+/** Feishu/Lark's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts). */
 import { type ContextBuffer } from "../kit/context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {
@@ -23,25 +18,11 @@ export interface FeishuBufferEntry {
 export interface FeishuBufferedRef extends FeishuBufferedResource {
     from: string;
 }
-/**
- * The place a message belongs to: the main chat, or a thread within it. Keyed by `thread_id`, the
- * platform's own identity for a side conversation — NOT `root_id`, which tracks the reply chain and
- * can differ between messages of one thread (which would split a thread's context across buckets).
- * A quoted reply outside a thread carries a root but is main-chat discussion, so it buckets there.
- *
- * Its own namespace, deliberately: this names a BUCKET of undelivered text, while `parse.ts`'s
- * `placeKey` names a SESSION. Nothing here claims anything about that session — unlike thread
- * participation, which asserts "the agent answered into this memory" and is therefore keyed by the
- * session itself. Re-keying either one leaves the other correct, and converging them now would strand
- * live buckets for no gain (Slack keeps its own shape for the same reason).
- */
+/** The place a message belongs to: the main chat, or a thread within it. */
 export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "threadId">): string;
-/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+/** One-line, bounded background text. */
 export declare function feishuBufferText(text: string): string;
-/**
- * Select the most recent background resources, excluding resources already primary on this turn. A
- * resource is message-scoped in Feishu/Lark, so identity is `message_id + key`, never the bare key.
- */
+/** Select the most recent background resources, excluding resources already primary on this turn. */
 export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferEntry[], primary: {
     files: FeishuBufferedResource[];
     images: FeishuBufferedResource[];

package/dist/channels/feishu/context-buffer.js

@@ -1,10 +1,5 @@
-/**
- * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
- * ../kit/context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
- * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
- * concrete thread root) and folded into the next answered turn in that place.
- */
-import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
+/** Feishu/Lark's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts). */
+import { capBufferedRefs, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
 import { truncateCodePointPrefix } from "../kit/text.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
@@ -12,32 +7,18 @@ function bufferLine(entry) {
         .join(", ");
     return `${entry.sender} (${meta}): ${entry.body}`;
 }
-/**
- * The place a message belongs to: the main chat, or a thread within it. Keyed by `thread_id`, the
- * platform's own identity for a side conversation — NOT `root_id`, which tracks the reply chain and
- * can differ between messages of one thread (which would split a thread's context across buckets).
- * A quoted reply outside a thread carries a root but is main-chat discussion, so it buckets there.
- *
- * Its own namespace, deliberately: this names a BUCKET of undelivered text, while `parse.ts`'s
- * `placeKey` names a SESSION. Nothing here claims anything about that session — unlike thread
- * participation, which asserts "the agent answered into this memory" and is therefore keyed by the
- * session itself. Re-keying either one leaves the other correct, and converging them now would strand
- * live buckets for no gain (Slack keeps its own shape for the same reason).
- */
+/** The place a message belongs to: the main chat, or a thread within it. */
 export function feishuBufferPlaceKey(conversation) {
     return conversation.threadId ? `${conversation.chatId}:thread:${conversation.threadId}` : conversation.chatId;
 }
-/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+/** One-line, bounded background text. */
 export function feishuBufferText(text) {
     return truncateCodePointPrefix(text.replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
 }
 function resourceIdentity(resource) {
     return `${resource.messageId}\u0000${resource.key}`;
 }
-/**
- * Select the most recent background resources, excluding resources already primary on this turn. A
- * resource is message-scoped in Feishu/Lark, so identity is `message_id + key`, never the bare key.
- */
+/** Select the most recent background resources, excluding resources already primary on this turn. */
 export function collectFeishuBufferedAttachments(consumed, primary) {
     const refs = (pick, primaryRefs) => {
         const excluded = new Set(primaryRefs.map(resourceIdentity));
@@ -54,13 +35,9 @@ export function collectFeishuBufferedAttachments(consumed, primary) {
         }
         return out;
     };
-    const files = refs((entry) => entry.files, primary.files);
-    const images = refs((entry) => entry.images, primary.images);
-    return {
-        files: files.slice(-BUFFER_ATTACH_MAX),
-        images: images.slice(-BUFFER_ATTACH_MAX),
-        skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) + Math.max(0, images.length - BUFFER_ATTACH_MAX),
-    };
+    const files = capBufferedRefs(refs((entry) => entry.files, primary.files));
+    const images = capBufferedRefs(refs((entry) => entry.images, primary.images));
+    return { files: files.kept, images: images.kept, skipped: files.skipped + images.skipped };
 }
 function isResource(value) {
     const resource = value;

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

@@ -1,9 +1,14 @@
-/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed
- * input or invalid padding. AES-CBC is not authenticated, so a wrong key is not mathematically
- * guaranteed to fail padding; the caller verifies signed events before decrypting and JSON-parses every
- * plaintext envelope, turning wrong-key garbage into a 4xx rather than a silent drop. */
+/**
+ * Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string; throws on malformed input or invalid
+ * padding. AES-CBC is NOT authenticated, so a wrong key is not mathematically guaranteed to fail padding: the caller
+ * must verify a signed event BEFORE decrypting it, and JSON-parse every plaintext envelope afterwards, so wrong-key
+ * garbage becomes a 4xx rather than a silent drop.
+ */
 export declare function decryptEvent(encryptKey: string, encryptB64: string): string;
-/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+/**
+ * The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. `rawBody` is
+ * the VERBATIM request body (the encrypted form) — the digest is over bytes, so a re-serialization never matches.
+ */
 export declare function eventSignature(encryptKey: string, timestamp: string, nonce: string, rawBody: string): string;
 /** Whether a request's signature headers verify against the raw body (constant-time). */
 export declare function verifySignature(encryptKey: string, headers: {

package/dist/channels/feishu/crypto.js

@@ -1,25 +1,15 @@
 /**
- * Canonical Feishu webhook security (reused by Lark compatibility) — PURE: AES event decryption and request
- * signature, exactly as the open platform defines them. When an Encrypt Key is configured in the
- * developer console, every event arrives as `{"encrypt": "<base64>"}` with signature headers; without
- * one, events arrive in plaintext and carry only the verification token in the body. feishu.ts owns the
- * fail-closed policy (which checks run when); this module owns the math.
- *
- *  - Decryption: AES-256-CBC. The key is sha256(encryptKey); the base64 payload is IV (16 bytes) ‖
- *    ciphertext; the plaintext is the event JSON (PKCS#7 padding handled by the cipher).
- *  - Signature: `X-Lark-Signature = sha256(timestamp + nonce + encryptKey + rawBody)` hex, where
- *    rawBody is the VERBATIM request body (the encrypted form) — computed over bytes, so the caller
- *    must pass the raw text, never a re-serialization.
- *
- * Comparisons are constant-time (timingSafeEqual) so neither the signature check nor the verification-
- * token check leaks a timing signal.
+ * Canonical Feishu webhook security (reused by Lark compatibility) — PURE: AES event decryption and request signature,
+ * exactly as the open platform defines them.
  */
 import { createDecipheriv, createHash } from "node:crypto";
 import { secretEquals } from "../secret.js";
-/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed
- * input or invalid padding. AES-CBC is not authenticated, so a wrong key is not mathematically
- * guaranteed to fail padding; the caller verifies signed events before decrypting and JSON-parses every
- * plaintext envelope, turning wrong-key garbage into a 4xx rather than a silent drop. */
+/**
+ * Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string; throws on malformed input or invalid
+ * padding. AES-CBC is NOT authenticated, so a wrong key is not mathematically guaranteed to fail padding: the caller
+ * must verify a signed event BEFORE decrypting it, and JSON-parse every plaintext envelope afterwards, so wrong-key
+ * garbage becomes a 4xx rather than a silent drop.
+ */
 export function decryptEvent(encryptKey, encryptB64) {
     const key = createHash("sha256").update(encryptKey, "utf8").digest();
     const buf = Buffer.from(encryptB64, "base64");
@@ -28,7 +18,10 @@ export function decryptEvent(encryptKey, encryptB64) {
     const decipher = createDecipheriv("aes-256-cbc", key, buf.subarray(0, 16));
     return Buffer.concat([decipher.update(buf.subarray(16)), decipher.final()]).toString("utf8");
 }
-/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+/**
+ * The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. `rawBody` is
+ * the VERBATIM request body (the encrypted form) — the digest is over bytes, so a re-serialization never matches.
+ */
 export function eventSignature(encryptKey, timestamp, nonce, rawBody) {
     return createHash("sha256").update(`${timestamp}${nonce}${encryptKey}${rawBody}`, "utf8").digest("hex");
 }

package/dist/channels/feishu/feishu-api.d.ts

@@ -1,5 +1,6 @@
 import type { ImageRef } from "../../agent.ts";
 import type { FeishuCloudKind } from "./cloud.ts";
+import type { CallOptions } from "../kit/transport.ts";
 /** Where a reply goes: a chat, optionally quote-replying a message inside a platform thread. */
 export interface FeishuTarget {
     chatId: string;
@@ -118,7 +119,7 @@ export interface FeishuApi {
     /** Create a card entity (card JSON 2.0). Returns its card_id. */
     createCard(cardJson: string): Promise<string>;
     /** Stream-update a card element's text (full-content snapshot + strictly increasing sequence). */
-    updateCardElement(cardId: string, elementId: string, content: string, sequence: number): Promise<void>;
+    updateCardElement(cardId: string, elementId: string, content: string, sequence: number, opts?: CallOptions): Promise<void>;
     /** Replace a card entity's content (the settle write; also flips streaming_mode off via the JSON). */
     updateCard(cardId: string, cardJson: string, sequence: number): Promise<void>;
 }