@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/README.md

@@ -36,7 +36,7 @@ FastAgent is the missing bridge from local agent directory to live service.
 ## Features
 
 - **Vibe first — a directory is an agent.** Point FastAgent at the `AGENTS.md` + `skills/` you already vibed in a coding agent. Markdown instructions, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite.
-- **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, an HTTP/SSE endpoint, or your own adapter — verified webhooks, streaming replies, group-aware.
+- **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, a Feishu or Lark bot, an HTTP/SSE endpoint, or your own adapter: verified webhooks, streaming replies, group-aware.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
 - **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
 - **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels. Durable ingress remains yours.
@@ -145,7 +145,7 @@ const agent = createPiAgent({
 | [Embedding](https://fastagent.sh/docs/embedding/) | Use FastAgent as a library inside your own app |
 | [Channels](https://fastagent.sh/docs/channels/) | Add webhook/bot channels |
 | [Deploy](https://fastagent.sh/docs/deploy/) | Ship the directory to Fly, Railway, or any Docker host |
-| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
+| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) / [Slack](https://fastagent.sh/docs/slack/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
 | [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
 | [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
 | [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
@@ -194,7 +194,7 @@ FastAgent is pre-1.0. The stable design center is the Agent Handler contract in
 
 The neutral contract leaves room for capabilities that are not complete product features yet:
 
-- **Durable execution** — Telegram accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
+- **Durable execution**: Telegram, Slack, and Feishu/Lark accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
 - **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
 - **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.

package/dist/agent.d.ts

@@ -39,6 +39,17 @@ export type AgentEvent = {
     isError: boolean;
     content: Json;
 }
+/** Advisory, non-terminal (engines MAY emit it): a transient internal failure scheduled a retry
+ *  with backoff — the turn is still alive. Explains a quiet gap that would otherwise read as a
+ *  hang; deliberately unclosed — the next event is its closure. Terminal consumers ignore it
+ *  (SPEC MUST 4). */
+ | {
+    type: "retrying";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: string;
+}
 /** Terminal: success. `data` is attached only when the engine produces a structured result. */
  | {
     type: "completed";
@@ -62,6 +73,15 @@ export type AgentEvent = {
  * not a public cross-engine mandate.
  */
 export declare const SESSION_BUSY_CODE = "session_busy";
+/**
+ * The `failed.code` set when a run was DELIBERATELY stopped — a control-plane abort, or any
+ * harness-level abort the engine attributes (`stopReason: "aborted"`) — rather than failing on its
+ * own. Channels can render cancellation distinctly from an error, and MUST treat it as a settled
+ * outcome — durable turn-intent cleanup included — so a deliberate stop is never replayed as a
+ * fresh turn on restart. Exported as a constant for the same reason as {@link SESSION_BUSY_CODE}:
+ * a consumer that must branch on it should not string-match.
+ */
+export declare const ABORTED_CODE = "aborted";
 /**
  * One turn = one invoke, returning a single async event stream. The stream MUST terminate with
  * exactly one of completed / failed, or be cancelled by the caller (no terminal event). Any

package/dist/agent.js

@@ -12,3 +12,12 @@
  * not a public cross-engine mandate.
  */
 export const SESSION_BUSY_CODE = "session_busy";
+/**
+ * The `failed.code` set when a run was DELIBERATELY stopped — a control-plane abort, or any
+ * harness-level abort the engine attributes (`stopReason: "aborted"`) — rather than failing on its
+ * own. Channels can render cancellation distinctly from an error, and MUST treat it as a settled
+ * outcome — durable turn-intent cleanup included — so a deliberate stop is never replayed as a
+ * fresh turn on restart. Exported as a constant for the same reason as {@link SESSION_BUSY_CODE}:
+ * a consumer that must branch on it should not string-match.
+ */
+export const ABORTED_CODE = "aborted";

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

@@ -0,0 +1,30 @@
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded
+ *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
+ *  group posting many attachments between summons. Skipped ones must be counted into the prompt
+ *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
+ *  each channel's attachment collector caps against this. */
+export declare const BUFFER_ATTACH_MAX = 3;
+export interface ContextBuffer<E> {
+    /** Record an un-summoned message. Persists BEFORE returning (pre-ACK; see the module header). */
+    push(placeKey: string, entry: E): void;
+    /** Render the fold text and snapshot the consumed entries (see the module header's consume protocol). */
+    peek(placeKey: string): {
+        text: string;
+        consumed: E[];
+    };
+    /** Remove exactly `consumed` (by identity) — call on the turn's `completed` event, when the folded
+     *  discussion provably lives in the durable session. Consumes entries WHOLE, including ones whose
+     *  attachments failed to load or were cap-skipped: their text is in the session (keeping them would
+     *  re-fold duplicate text), and the prompt note said what is missing; re-post an attachment to use
+     *  it. Post-ACK: a failed write is logged, never thrown (it must not abort the turn's delivery). */
+    commit(placeKey: string, consumed: E[]): void;
+}
+export declare function createContextBuffer<E>(options: {
+    path: string;
+    /** Log label, e.g. "[telegram]". */
+    label: string;
+    /** Shape validator for one persisted entry (the IO boundary — see the module header). */
+    isEntry: (value: unknown) => value is E;
+    /** One fold line for an entry — ALSO the eviction cost basis. */
+    line: (entry: E) => string;
+}): ContextBuffer<E>;

package/dist/channels/context-buffer.js

@@ -0,0 +1,98 @@
+/**
+ * Generic durable context buffer — the SHARED mechanics behind each stateful channel's
+ * "un-summoned group discussion" module (telegram/feishu/slack `context-buffer.ts`): recent
+ * un-summoned messages per conversation "place", kept under a char budget and folded into the next
+ * answered turn in that place, so a summoned agent has the discussion it didn't see turn-by-turn.
+ *
+ * Channel-neutral and generic over the entry shape (like ../turn-store.ts): the channel supplies its
+ * entry type, the shape validator (state files are an IO boundary — valid JSON of the WRONG shape
+ * must degrade exactly like a corrupt file: warn + empty, never flow in as trusted data), the
+ * fold-line renderer, and its log label. What stays per channel: the entry type itself, place-key
+ * derivation, and buffered-attachment selection (platform resource shapes are real differences).
+ *
+ * DURABLE, with the consume protocol every channel inherits:
+ *  - `push` persists synchronously BEFORE the transport ACK (an ACKed delivery is not redelivered,
+ *    so ACK-then-persist would be a silent-loss window): a throw becomes the webhook's 500 and the
+ *    platform redelivers once the disk recovers — staged on a copy and rolled back on a failed
+ *    write, so the redelivery does not double-append the entry already in memory.
+ *  - `peek` renders WITHOUT clearing and snapshots exactly which entries it consumed.
+ *  - `commit` removes only that snapshot, by object identity, on the turn's `completed` — so a
+ *    failure or crash before `completed` leaves the discussion intact for the next summon, and a
+ *    message that arrives while the turn runs survives for the next answered turn (a whole-bucket
+ *    delete would lose it).
+ */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+/** Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded
+ *  the OLDEST un-summoned messages are dropped (not a time window: a quiet group keeps its
+ *  sparse-but-relevant lines, a busy burst is capped). The `line` renderer is the eviction cost
+ *  basis: the budget must price what the fold actually renders, or it would systematically overrun. */
+const BUFFER_MAX_CHARS = 4000;
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded
+ *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
+ *  group posting many attachments between summons. Skipped ones must be counted into the prompt
+ *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
+ *  each channel's attachment collector caps against this. */
+export const BUFFER_ATTACH_MAX = 3;
+export function createContextBuffer(options) {
+    const { path, label, isEntry, line } = options;
+    const load = () => {
+        const raw = loadStateFile(path);
+        if (raw === undefined)
+            return new Map();
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.values(raw).every((entries) => Array.isArray(entries) && entries.every(isEntry))) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`${label} unexpected shape in ${path} — starting with an empty context buffer`);
+        return new Map();
+    };
+    const buffers = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
+    return {
+        push(placeKey, entry) {
+            const previous = buffers.get(placeKey);
+            const entries = previous ? [...previous] : [];
+            entries.push(entry);
+            let total = entries.reduce((sum, candidate) => sum + line(candidate).length + 1, 0);
+            while (entries.length > 1 && total > BUFFER_MAX_CHARS) {
+                const dropped = entries.shift();
+                if (dropped)
+                    total -= line(dropped).length + 1;
+            }
+            buffers.set(placeKey, entries);
+            try {
+                persist();
+            }
+            catch (error) {
+                if (previous)
+                    buffers.set(placeKey, previous);
+                else
+                    buffers.delete(placeKey);
+                throw error;
+            }
+        },
+        peek(placeKey) {
+            const entries = buffers.get(placeKey) ?? [];
+            return { text: entries.map(line).join("\n"), consumed: [...entries] };
+        },
+        commit(placeKey, consumed) {
+            const entries = buffers.get(placeKey);
+            if (!entries)
+                return;
+            const remaining = entries.filter((entry) => !consumed.includes(entry));
+            if (remaining.length === 0)
+                buffers.delete(placeKey);
+            else
+                buffers.set(placeKey, remaining);
+            try {
+                persist();
+            }
+            catch (error) {
+                log.error(`${label} context-buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(error)}`);
+            }
+        },
+    };
+}

package/dist/channels/control.d.ts

@@ -0,0 +1,28 @@
+import { type SessionControl, type SessionEvent } from "../session.ts";
+import type { Agent } from "../agent.ts";
+import type { Routes } from "../host/node.ts";
+/** The SSE payload: one control-plane event in its transport envelope. */
+export interface WireEvent {
+    sessionId: string;
+    /** Serving-process incarnation (per `controlRoutes` call). A change means the server restarted:
+     *  live continuity is gone — run the reconnect steps (entries cursor + state). */
+    epoch: string;
+    /** Per-connection monotonic counter. A gap means events were lost in transit on THIS connection. */
+    seq: number;
+    event: SessionEvent;
+}
+export interface ControlRoutesOptions {
+    /** Shared bearer secret, required on every route. Never optional: an unauthenticated
+     *  remote-control endpoint must not be constructible by omission. */
+    token: string;
+    /** The DATA plane over the wire: when provided, `POST /control/invoke` mounts the standard
+     *  invoke handler behind the same bearer token — a remote client (Web panel, desktop app,
+     *  `attach`) can START runs regardless of which channels occupy `/invoke`. Same contract, same
+     *  SSE event stream; disconnecting the response cancels the run (SPEC cancellation). */
+    agent?: Agent;
+}
+/**
+ * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ */
+export declare function controlRoutes(control: SessionControl, options: ControlRoutesOptions): Routes;

package/dist/channels/control.js

@@ -0,0 +1,214 @@
+import { INVALID_COMMAND_CODE } from "../session.js";
+import { timingSafeEqual } from "node:crypto";
+import { readBodyCapped } from "./body.js";
+import { MAX_BODY_BYTES, createInvokeHandler, sseHeartbeat } from "./http.js";
+import { text } from "./respond.js";
+const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
+// ONE constant for every Prompt-bearing wire surface (imported from the invoke channel — the two
+// caps cannot drift apart): commands carry Prompts, which may ride base64 images.
+const DISPATCH_BODY_LIMIT = MAX_BODY_BYTES;
+/**
+ * Parse-don't-validate at the wire: a remote client can send any JSON, and the hub's inner layers
+ * trust command shapes (a malformed `steer` would surface as an ENGINE failure misclassified as
+ * `run_command_failed`). Returns the typed command, or undefined for anything malformed — which
+ * answers protocol-level `invalid_command`, same responsibility as the hub's unknown-type default.
+ */
+function parseWireCommand(raw) {
+    // COMPILE-TIME drift guard, variant level: this switch hand-mirrors the SessionCommand union,
+    // and a new variant added in session.ts would otherwise compile clean while the wire answers it
+    // `invalid_command` — silently breaking local/remote isomorphism. A new variant must break THIS
+    // line first, forcing the decision of how the wire carries it.
+    const _commandDriftGuard = {
+        steer: true,
+        follow_up: true,
+        abort: true,
+        compact: true,
+        set_model: true,
+        set_thinking: true,
+    };
+    void _commandDriftGuard;
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const c = raw;
+    const imageOk = (i) => typeof i === "object" &&
+        i !== null &&
+        typeof i.data === "string" &&
+        typeof i.mimeType === "string";
+    const promptOk = (p) => {
+        if (typeof p !== "object" || p === null)
+            return false;
+        if (typeof p.text !== "string")
+            return false;
+        const images = p.images;
+        // Element-level: `images: [42]` reaching the engine would resurface exactly the misclassified
+        // failure this parser exists to prevent (ImageRef shape from src/session.ts's Prompt).
+        return images === undefined || (Array.isArray(images) && images.every(imageOk));
+    };
+    // REBUILD, never pass raw through: "typed command out" must be construction, not assertion — a
+    // passed-through object would carry arbitrary extra keys into the engine.
+    const rebuildPrompt = (p) => {
+        const images = p.images;
+        return {
+            text: p.text,
+            ...(images ? { images: images.map((i) => ({ data: i.data, mimeType: i.mimeType })) } : {}),
+        };
+    };
+    // COMPILE-TIME drift guard: whitelist reconstruction silently strips any field it does not know.
+    // A new Prompt field must break THIS line (non-empty Exclude → {} unassignable), not vanish on
+    // the wire while the client believes it was sent.
+    const _promptDriftGuard = {};
+    void _promptDriftGuard;
+    // Same guard one level down: the image whitelist ({data, mimeType}) must break when ImageRef
+    // grows a field — top-level coverage alone would let element fields vanish silently.
+    const _imageDriftGuard = {};
+    void _imageDriftGuard;
+    switch (c.type) {
+        case "steer":
+        case "follow_up":
+            return promptOk(c.prompt) ? { type: c.type, prompt: rebuildPrompt(c.prompt) } : undefined;
+        case "abort":
+            return { type: "abort" };
+        case "compact":
+            return c.instructions === undefined || typeof c.instructions === "string"
+                ? { type: "compact", instructions: c.instructions }
+                : undefined;
+        case "set_model":
+            return typeof c.model === "string" ? { type: "set_model", model: c.model } : undefined;
+        case "set_thinking":
+            return typeof c.level === "string" ? { type: "set_thinking", level: c.level } : undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ */
+export function controlRoutes(control, options) {
+    const { token } = options;
+    if (!token)
+        throw new Error("controlRoutes: a bearer token is required (empty tokens are not a mode)");
+    const epoch = crypto.randomUUID();
+    // Timing-safe: the bearer token is this surface's ONLY auth (and the --tunnel warning names it
+    // as the sole protection on a public URL) — a plain === would leak byte-by-byte via timing.
+    const expected = Buffer.from(`Bearer ${token}`);
+    const authed = (req) => {
+        const header = Buffer.from(req.headers.get("authorization") ?? "");
+        return header.length === expected.length && timingSafeEqual(header, expected);
+    };
+    const invokeHandler = options.agent ? createInvokeHandler(options.agent) : undefined;
+    /** Wrap a handler with auth + the session query param most routes need. */
+    const guard = (handler) => (req) => {
+        if (!authed(req))
+            return text("unauthorized\n", 401);
+        return handler(req, new URL(req.url));
+    };
+    // Extraction only — each route still answers its own 400 (the name must not imply enforcement).
+    const sessionParam = (url) => url.searchParams.get("session") ?? undefined;
+    return {
+        ...(invokeHandler ? { "POST /control/invoke": guard((req) => invokeHandler(req)) } : {}),
+        "GET /control/capabilities": guard(() => json(control.capabilities())),
+        "GET /control/state": guard(async (_req, url) => {
+            const session = sessionParam(url);
+            if (!session)
+                return text("missing ?session\n", 400);
+            return json(await control.state(session));
+        }),
+        "GET /control/entries": guard(async (_req, url) => {
+            const session = sessionParam(url);
+            if (!session)
+                return text("missing ?session\n", 400);
+            const since = url.searchParams.get("since") ?? undefined;
+            return json(await control.entries(session, since !== undefined ? { since } : undefined));
+        }),
+        "POST /control/dispatch": guard(async (req) => {
+            const body = await readBodyCapped(req, DISPATCH_BODY_LIMIT);
+            // The 413 names the ceiling: the docs promise images on this plane, and an unexplained
+            // rejection would send a client author hunting everywhere but the cap.
+            if ("tooLarge" in body) {
+                // Derived from the constant — a hardcoded "1 MiB" would lie the day the cap changes.
+                return text(`body too large (limit ${MAX_BODY_BYTES >> 20} MiB — images count base64-inflated)\n`, 413);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(body.text);
+            }
+            catch {
+                return text("invalid JSON\n", 400);
+            }
+            if (typeof parsed.session !== "string") {
+                return text("expected { session: string, command: SessionCommand }\n", 400);
+            }
+            const command = parseWireCommand(parsed.command);
+            if (!command) {
+                // Malformed shape = a protocol-level answer, mirrored from the hub's unknown-type default.
+                return json({
+                    ok: false,
+                    error: { code: INVALID_COMMAND_CODE, message: "malformed command", retryable: false },
+                });
+            }
+            // The result rides HTTP 200 either way: `ok: false` is a protocol-level answer (rejected
+            // before acceptance), not a transport failure.
+            return json(await control.dispatch(parsed.session, command));
+        }),
+        "GET /control/events": guard((_req, url) => {
+            const session = sessionParam(url);
+            if (!session)
+                return text("missing ?session\n", 400);
+            const iterator = control.events(session)[Symbol.asyncIterator]();
+            // EAGER registration: issue the first pull NOW, before the Response (and thus the client's
+            // fetch resolution) exists — hub subscription is registered synchronously inside next(), so
+            // "the client saw response headers" implies "events from that moment on will be delivered".
+            // Shrinks the subscribe/backfill race to network reordering instead of a full pull cycle.
+            let pending = iterator.next();
+            // Observed here so a client that disconnects BEFORE the first pull cannot turn a rejecting
+            // events iterator (this is the neutral contract face — any implementation may reject) into a
+            // process-killing unhandledRejection; awaiting `pending` at pull still surfaces the error.
+            pending.catch(() => { });
+            let seq = 0;
+            let stopHeartbeat = () => { };
+            const encoder = new TextEncoder();
+            const stream = new ReadableStream({
+                start(controller) {
+                    stopHeartbeat = sseHeartbeat(controller);
+                },
+                async pull(controller) {
+                    let next;
+                    try {
+                        next = await (pending ?? iterator.next());
+                    }
+                    catch (error) {
+                        // A rejecting implementation (the neutral contract permits it) must not leak its
+                        // subscription: an errored stream never gets cancel(), so the unsubscribe and the
+                        // heartbeat teardown happen HERE.
+                        stopHeartbeat();
+                        void iterator.return?.(undefined)?.catch?.(() => { });
+                        controller.error(error);
+                        return;
+                    }
+                    pending = undefined;
+                    if (next.done) {
+                        stopHeartbeat();
+                        controller.close();
+                        return;
+                    }
+                    const wire = { sessionId: session, epoch, seq: seq++, event: next.value };
+                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(wire)}\n\n`));
+                },
+                cancel() {
+                    stopHeartbeat();
+                    // Same neutral-contract defense as the pull error path: a rejecting return() on client
+                    // disconnect must not become a process-level unhandledRejection.
+                    void iterator.return?.(undefined)?.catch?.(() => { });
+                },
+            });
+            return new Response(stream, {
+                headers: {
+                    "content-type": "text/event-stream",
+                    "cache-control": "no-cache",
+                    connection: "keep-alive",
+                },
+            });
+        }),
+    };
+}

package/dist/channels/feishu/card.js

@@ -11,7 +11,7 @@
  * 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).
  */
-import { truncateCodePointPrefix } from "./text.js";
+import { truncateCodePointPrefix } from "../text.js";
 /** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
 export const ANSWER_ELEMENT_ID = "answer";
 /** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */

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

@@ -1,3 +1,10 @@
+/**
+ * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
+ * ../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 { type ContextBuffer } from "../context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {
     messageId: string;
@@ -32,15 +39,5 @@ export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferE
     images: FeishuBufferedRef[];
     skipped: number;
 };
-export interface FeishuContextBuffer {
-    /** Persist before webhook ACK. A failed write throws and rolls memory back for safe redelivery. */
-    push(placeKey: string, entry: FeishuBufferEntry): void;
-    /** Render and snapshot without clearing. */
-    peek(placeKey: string): {
-        text: string;
-        consumed: FeishuBufferEntry[];
-    };
-    /** Remove only the consumed snapshot after `completed`; a post-ACK write failure is logged. */
-    commit(placeKey: string, consumed: FeishuBufferEntry[]): void;
-}
+export type FeishuContextBuffer = ContextBuffer<FeishuBufferEntry>;
 export declare function createFeishuContextBuffer(path: string, label: string): FeishuContextBuffer;

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

@@ -1,13 +1,10 @@
 /**
- * Durable context buffer for human group messages that do NOT currently summon the Feishu/Lark Agent.
- * Entries are bucketed by conversation place (main chat, or one concrete thread root) and folded into
- * the next answered turn in that place. The consume protocol mirrors Telegram: peek without clearing,
- * then commit exactly that snapshot only after the Agent emits `completed`.
+ * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
+ * ../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 { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "../state.js";
-const BUFFER_MAX_CHARS = 4000;
-const BUFFER_ATTACH_MAX = 3;
+import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
         .filter(Boolean)
@@ -71,63 +68,5 @@ function isEntry(value) {
         resources(entry.images));
 }
 export function createFeishuContextBuffer(path, label) {
-    const load = () => {
-        const raw = loadStateFile(path);
-        if (raw === undefined)
-            return new Map();
-        if (typeof raw === "object" &&
-            raw !== null &&
-            !Array.isArray(raw) &&
-            Object.values(raw).every((entries) => Array.isArray(entries) && entries.every(isEntry))) {
-            return new Map(Object.entries(raw));
-        }
-        log.warn(`${label} unexpected shape in ${path} — starting with an empty context buffer`);
-        return new Map();
-    };
-    const buffers = load();
-    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
-    return {
-        push(placeKey, entry) {
-            const previous = buffers.get(placeKey);
-            const entries = previous ? [...previous] : [];
-            entries.push(entry);
-            let total = entries.reduce((sum, candidate) => sum + bufferLine(candidate).length + 1, 0);
-            while (entries.length > 1 && total > BUFFER_MAX_CHARS) {
-                const dropped = entries.shift();
-                if (dropped)
-                    total -= bufferLine(dropped).length + 1;
-            }
-            buffers.set(placeKey, entries);
-            try {
-                persist();
-            }
-            catch (error) {
-                if (previous)
-                    buffers.set(placeKey, previous);
-                else
-                    buffers.delete(placeKey);
-                throw error;
-            }
-        },
-        peek(placeKey) {
-            const entries = buffers.get(placeKey) ?? [];
-            return { text: entries.map(bufferLine).join("\n"), consumed: [...entries] };
-        },
-        commit(placeKey, consumed) {
-            const entries = buffers.get(placeKey);
-            if (!entries)
-                return;
-            const remaining = entries.filter((entry) => !consumed.includes(entry));
-            if (remaining.length === 0)
-                buffers.delete(placeKey);
-            else
-                buffers.set(placeKey, remaining);
-            try {
-                persist();
-            }
-            catch (error) {
-                log.error(`${label} context-buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(error)}`);
-            }
-        },
-    };
+    return createGenericContextBuffer({ path, label, isEntry, line: bufferLine });
 }

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

@@ -34,6 +34,11 @@ export interface FeishuApiOptions {
     appId: string;
     appSecret: string;
 }
+export interface FeishuAppScope {
+    name: string;
+    grantStatus: number;
+    type?: "user" | "tenant";
+}
 /**
  * The Feishu Open API client: one instance per channel, holding the token cache. Every method rides the
  * single pipeline (module header). Throws {@link FeishuApiError} on any failure.
@@ -85,6 +90,12 @@ export interface FeishuApi {
         verificationToken?: string;
         encryptionKey?: string;
     }>;
+    /** List the app's scopes and grant state. Used by onboarding/runtime to make group visibility
+     * explicit instead of silently assuming unmentioned group events are delivered. */
+    listAppScopes(): Promise<FeishuAppScope[]>;
+    /** Add tenant scopes to the app draft through application-v7 config. Approval + version publishing
+     * remain console actions; this method only removes the error-prone manual draft edit. */
+    addAppScopes(appId: string, scopeNames: string[]): Promise<void>;
     /** Update the app's own event subscription (application-v7 config PATCH — tenant token can only
      *  operate on itself; the request-URL change takes effect immediately, no version publish). The
      *  platform VERIFIES `requestUrl` with a url_verification challenge during this call, so the server
@@ -100,9 +111,6 @@ export interface FeishuApi {
     /** 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>;
 }
-/** The platform caps a text-message request body at 150 KB; stay well under it (the content is a JSON
- *  envelope around the text, and multi-byte characters inflate the byte count). */
-export declare const FEISHU_MAX_TEXT_BYTES: number;
 /** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
 export declare function chunkFeishuText(text: string, maxBytes?: number): string[];
 export declare function createFeishuApi(opts: FeishuApiOptions): FeishuApi;

package/dist/channels/feishu/feishu-api.js

@@ -21,7 +21,7 @@
  */
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { utf8Prefix } from "./text.js";
+import { utf8Prefix } from "../text.js";
 /** Per-attempt timeout for a JSON API call — small JSON round-trips, so 30s is generous. */
 const API_TIMEOUT_MS = 30_000;
 /** Timeout for downloading resource bytes — sized for a slow link, not a JSON call. */
@@ -79,7 +79,7 @@ export function isTransientFeishuRegistrationError(e) {
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** The platform caps a text-message request body at 150 KB; stay well under it (the content is a JSON
  *  envelope around the text, and multi-byte characters inflate the byte count). */
-export const FEISHU_MAX_TEXT_BYTES = 100 * 1024;
+const FEISHU_MAX_TEXT_BYTES = 100 * 1024;
 /** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
 export function chunkFeishuText(text, maxBytes = FEISHU_MAX_TEXT_BYTES) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
@@ -296,6 +296,24 @@ export function createFeishuApi(opts) {
                 encryptionKey: data.data?.app?.encryption?.encryption_key,
             };
         },
+        async listAppScopes() {
+            const data = await call("listAppScopes", "GET", "/open-apis/application/v6/scopes");
+            return (data.data?.scopes ?? []).flatMap((scope) => {
+                if (typeof scope.scope_name !== "string" || typeof scope.grant_status !== "number")
+                    return [];
+                const type = scope.scope_type === "user" || scope.scope_type === "tenant" ? scope.scope_type : undefined;
+                return [{ name: scope.scope_name, grantStatus: scope.grant_status, type }];
+            });
+        },
+        async addAppScopes(appId, scopeNames) {
+            if (scopeNames.length === 0)
+                return;
+            await call("addAppScopes", "PATCH", `/open-apis/application/v7/applications/${encodeURIComponent(appId)}/config`, {
+                scope: {
+                    add_scopes: scopeNames.map((scopeName) => ({ scope_name: scopeName, token_type: "tenant" })),
+                },
+            });
+        },
         async updateEventSubscription(appId, cfg) {
             await call("updateEventSubscription", "PATCH", `/open-apis/application/v7/applications/${encodeURIComponent(appId)}/config`, {
                 event: { subscription_type: cfg.subscriptionType, request_url: cfg.requestUrl },