@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/README.md

@@ -36,10 +36,10 @@ 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 build step — the directory is the deployable unit. `fastagent deploy fly|railway` generates the deploy config + a runbook (`--run` drives it to completion); idle agents scale to zero and resume in hundreds of milliseconds on the next webhook. The generated container runs on any Docker host.
+- **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.
 
 ## Design philosophy
 
@@ -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,11 +194,11 @@ 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.
-- **More deploy targets** — Fly and Railway ship today; the generated container is the portable path for other hosts.
+- **More deploy targets** — local Docker, Fly, and Railway ship today; the generated container is the portable path for other hosts.
 
 See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
 

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

@@ -0,0 +1,43 @@
+/**
+ * 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;
+    key: string;
+    name?: string;
+}
+export interface FeishuBufferEntry {
+    sender: string;
+    body: string;
+    messageId: string;
+    replyTo?: string;
+    files?: FeishuBufferedResource[];
+    images?: FeishuBufferedResource[];
+}
+/** A background resource carried into a later turn, with attribution for its prompt manifest. */
+export interface FeishuBufferedRef extends FeishuBufferedResource {
+    from: string;
+}
+/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "rootId" | "threadId">): string;
+/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+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.
+ */
+export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferEntry[], primary: {
+    files: FeishuBufferedResource[];
+    images: FeishuBufferedResource[];
+}): {
+    files: FeishuBufferedRef[];
+    images: FeishuBufferedRef[];
+    skipped: number;
+};
+export type FeishuContextBuffer = ContextBuffer<FeishuBufferEntry>;
+export declare function createFeishuContextBuffer(path: string, label: string): FeishuContextBuffer;

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

@@ -0,0 +1,72 @@
+/**
+ * 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 { 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)
+        .join(", ");
+    return `${entry.sender} (${meta}): ${entry.body}`;
+}
+/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+export function feishuBufferPlaceKey(conversation) {
+    const topic = conversation.rootId ?? conversation.threadId;
+    return topic ? `${conversation.chatId}:root:${topic}` : conversation.chatId;
+}
+/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+export function feishuBufferText(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 280);
+}
+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.
+ */
+export function collectFeishuBufferedAttachments(consumed, primary) {
+    const refs = (pick, primaryRefs) => {
+        const excluded = new Set(primaryRefs.map(resourceIdentity));
+        const seen = new Set();
+        const out = [];
+        for (const entry of consumed) {
+            for (const resource of pick(entry) ?? []) {
+                const identity = resourceIdentity(resource);
+                if (excluded.has(identity) || seen.has(identity))
+                    continue;
+                seen.add(identity);
+                out.push({ ...resource, from: entry.sender });
+            }
+        }
+        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),
+    };
+}
+function isResource(value) {
+    const resource = value;
+    return (typeof resource?.messageId === "string" &&
+        typeof resource.key === "string" &&
+        (resource.name === undefined || typeof resource.name === "string"));
+}
+function isEntry(value) {
+    const entry = value;
+    const resources = (candidate) => candidate === undefined || (Array.isArray(candidate) && candidate.every(isResource));
+    return (typeof entry?.sender === "string" &&
+        typeof entry.body === "string" &&
+        typeof entry.messageId === "string" &&
+        (entry.replyTo === undefined || typeof entry.replyTo === "string") &&
+        resources(entry.files) &&
+        resources(entry.images));
+}
+export function createFeishuContextBuffer(path, label) {
+    return createGenericContextBuffer({ path, label, isEntry, line: bufferLine });
+}

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

@@ -1,7 +1,9 @@
 /** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
 export declare function timingSafeEqualStr(a: string, b: string): boolean;
-/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
- *  or a wrong key (bad padding) — the caller turns that into a 4xx, never 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 verifies signed events before decrypting and JSON-parses every
+ * plaintext envelope, turning wrong-key garbage into 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. */
 export declare function eventSignature(encryptKey: string, timestamp: string, nonce: string, rawBody: string): string;

package/dist/channels/feishu/crypto.js

@@ -21,8 +21,10 @@ export function timingSafeEqualStr(a, b) {
     const bb = Buffer.from(b);
     return ab.length === bb.length && timingSafeEqual(ab, bb);
 }
-/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
- *  or a wrong key (bad padding) — the caller turns that into a 4xx, never 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 verifies signed events before decrypting and JSON-parses every
+ * plaintext envelope, turning wrong-key garbage into 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");