@fastagent-sh/fastagent 0.21.0 → 0.22.0

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

@@ -1,4 +1,5 @@
 import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
+import { defineChannel } from "@fastagent-sh/fastagent";
 
 // feishuChannel is fastagent's canonical Feishu adapter (verify + run + reply), configured with YOUR
 // policy. fastagent discovers this file, mounts POST /feishu, and pipes the agent + state home to it.
@@ -20,23 +21,30 @@ import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
 //   5. create a version and publish the app (a Feishu admin approves it), then add the bot to a chat
 // `fastagent add feishu` already did steps 1-3 for you (scan-to-create); this walkthrough is for a
 // hand-made app or for auditing what the scan configured.
-export default feishuChannel({
-  appId: process.env.FEISHU_APP_ID ?? "", // missing → fails at startup (no replies could be sent)
-  appSecret: process.env.FEISHU_APP_SECRET ?? "",
-  verificationToken: process.env.FEISHU_VERIFICATION_TOKEN ?? "", // authenticates inbound events
-  encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
-  // No session modes: a chat is one session and a thread is another, and where the answer goes follows
-  // from that (docs/design/participant-model.md).
-  // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-  // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
-  // full details always go to the server log regardless.
-  onError: (failed) => `⚠️ ${failed.details}`,
-  // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
-  // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
-  // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
-  // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
-  // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
-  // Override to customise explicit routing, reusing the export:
-  //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
-  //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
+export default defineChannel({
+  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
+  // while one is unset — a bare process.env read gets neither guarantee. FEISHU_ENCRYPT_KEY is
+  // optional, so it is NOT declared here: an undeclared read stays undeclared on purpose.
+  secrets: ["FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_VERIFICATION_TOKEN"],
+  channel: (secrets) =>
+    feishuChannel({
+      appId: secrets.FEISHU_APP_ID,
+      appSecret: secrets.FEISHU_APP_SECRET,
+      verificationToken: secrets.FEISHU_VERIFICATION_TOKEN, // authenticates inbound events
+      encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
+      // No session modes: a chat is one session and a thread is another, and where the answer goes follows
+      // from that (docs/design/participant-model.md).
+      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+      // full details always go to the server log regardless.
+      onError: (failed) => `⚠️ ${failed.details}`,
+      // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
+      // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
+      // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
+      // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
+      // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
+      // Override to customise explicit routing, reusing the export:
+      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
+      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
+    }),
 });

package/dist/channels/feishu/scaffold/channel.websocket.ts

@@ -0,0 +1,31 @@
+import { feishuWebSocketChannel } from "@fastagent-sh/fastagent/feishu";
+import { defineChannel } from "@fastagent-sh/fastagent";
+
+// Feishu WebSocket long connection: the process connects OUT to the platform, so no public URL,
+// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long
+// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process
+// running in production: scale-to-zero/App Sleeping would disconnect ingress.
+export default defineChannel({
+  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
+  // while one is unset — a bare process.env read gets neither guarantee.
+  secrets: ["FEISHU_APP_ID", "FEISHU_APP_SECRET"],
+  channel: (secrets) =>
+    feishuWebSocketChannel({
+      appId: secrets.FEISHU_APP_ID,
+      appSecret: secrets.FEISHU_APP_SECRET,
+      // No session modes: a chat is one session and a thread is another, and where the answer goes follows
+      // from that (docs/design/participant-model.md).
+      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+      // full details always go to the server log regardless.
+      onError: (failed) => `⚠️ ${failed.details}`,
+      // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
+      // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
+      // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
+      // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
+      // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
+      // Override to customise explicit routing, reusing the export:
+      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
+      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
+    }),
+});

package/dist/channels/feishu/setup-mode.d.ts

@@ -1,28 +1,17 @@
 /** Feishu/Lark app-level event subscription choice used by onboarding and scaffolding. */
 export type FeishuSubscriptionMode = "webhook" | "websocket";
-/** Onboarding choice for group visibility. `context` needs the tenant-wide group-message scope; the
- * runtime remains capability-driven because the platform, not channel source, decides which events
- * are delivered. */
+/** Onboarding choice for group visibility. */
 export type FeishuGroupBehavior = "context" | "mentions";
 /**
- * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and
- * adding a scope to the app draft during context-aware group setup.
- *
- * Requested at creation for BOTH ingress modes, though only webhook uses it on day one. A WebSocket
- * app that later wants webhook delivery cannot acquire it in passing: changing mode is a migration
- * the CLI deliberately refuses to perform (`resolveIngress`), so the app would have to be recreated
- * or the scope added by hand in the console after a failed PATCH. It is not a data scope — it reads
- * and writes this app's own configuration — so carrying it costs an app nothing and keeps the one
- * door open that the alternative nails shut.
+ * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and adding a scope to
+ * the app draft during context-aware group setup.
  */
 export declare const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
 /** The one event an agent app cannot serve without: an inbound message. */
 export declare const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
 /**
- * What a created app carries on top of the platform's agent template, for EITHER ingress — the
- * `addons` merged onto the confirm page. Here rather than inline at the call site because it is a
- * policy decision (which capabilities an app is born with), and the CLI layer that requests it is
- * terminal wiring with no seam to test through.
+ * What a created app carries on top of the platform's agent template, for EITHER ingress — the `addons` merged onto
+ * the confirm page.
  */
 export declare function feishuAppAddons(): {
     scopes: {
@@ -36,32 +25,18 @@ export declare function feishuAppAddons(): {
 };
 /** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
 export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
-/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).
- *  INDEPENDENT of the delivery scope above and of the group posture: the read runs in every chat type
- *  (a p2p thread's opening ask, any quoted @mention in a group). It is also a softer dependency —
- *  without it everything still works, and an unreadable quote degrades to a marker in the prompt.
- *  Bundled into the context-aware request only because that path already needs an approval round; a
- *  mention-only app wanting referents must add it by hand. */
+/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8). */
 export declare const FEISHU_MESSAGE_READ_SCOPE = "im:message:readonly";
-/** A scope the onboarding asks for, plus any BROADER spelling that already satisfies it. One concept,
- *  so adding a superset means editing the entry — not every call site that tests a scope. */
+/** A scope the onboarding asks for, plus any BROADER spelling that already satisfies it. */
 export interface FeishuScopeRequest {
-    /** What to add to the app draft when nothing satisfies it. Always counts as satisfying itself. */
+    /** What to add to the app draft when nothing satisfies it. */
     request: string;
-    /** EXTRA spellings that also count — supersets. Optional; `request` is implicit. Modelled this way
-     *  so a request that can never be satisfied (a list omitting its own `request`) cannot be
-     *  written: onboarding would add the scope, the tenant would grant it, and it would still read as
-     *  missing forever. */
+    /** EXTRA spellings that also count — supersets. */
     supersets?: string[];
 }
 /** Whether `predicate` holds for any spelling that satisfies this request. */
 export declare function scopeSatisfied(entry: FeishuScopeRequest, predicate: (name: string) => boolean): boolean;
-/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already
- *  do so — checking only the readonly spelling would warn a correctly configured app forever and push
- *  its author into a redundant approval round. Exported on its own because the serving-time capability
- *  report asks the same question, and a second mechanism there is what this type exists to prevent. */
+/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already do so. */
 export declare const FEISHU_MESSAGE_READ_REQUEST: FeishuScopeRequest;
-/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. Only the
- *  delivery scope is required for the context path; the read scope rides along because it shares the
- *  round and its absence merely degrades quoted messages to a marker. */
+/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. */
 export declare const FEISHU_CONTEXT_ONBOARDING_SCOPES: FeishuScopeRequest[];

package/dist/channels/feishu/setup-mode.js

@@ -1,22 +1,13 @@
 /**
- * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and
- * adding a scope to the app draft during context-aware group setup.
- *
- * Requested at creation for BOTH ingress modes, though only webhook uses it on day one. A WebSocket
- * app that later wants webhook delivery cannot acquire it in passing: changing mode is a migration
- * the CLI deliberately refuses to perform (`resolveIngress`), so the app would have to be recreated
- * or the scope added by hand in the console after a failed PATCH. It is not a data scope — it reads
- * and writes this app's own configuration — so carrying it costs an app nothing and keeps the one
- * door open that the alternative nails shut.
+ * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and adding a scope to
+ * the app draft during context-aware group setup.
  */
 export const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
 /** The one event an agent app cannot serve without: an inbound message. */
 export const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
 /**
- * What a created app carries on top of the platform's agent template, for EITHER ingress — the
- * `addons` merged onto the confirm page. Here rather than inline at the call site because it is a
- * policy decision (which capabilities an app is born with), and the CLI layer that requests it is
- * terminal wiring with no seam to test through.
+ * What a created app carries on top of the platform's agent template, for EITHER ingress — the `addons` merged onto
+ * the confirm page.
  */
 export function feishuAppAddons() {
     return {
@@ -26,28 +17,18 @@ export function feishuAppAddons() {
 }
 /** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
 export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
-/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).
- *  INDEPENDENT of the delivery scope above and of the group posture: the read runs in every chat type
- *  (a p2p thread's opening ask, any quoted @mention in a group). It is also a softer dependency —
- *  without it everything still works, and an unreadable quote degrades to a marker in the prompt.
- *  Bundled into the context-aware request only because that path already needs an approval round; a
- *  mention-only app wanting referents must add it by hand. */
+/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8). */
 export const FEISHU_MESSAGE_READ_SCOPE = "im:message:readonly";
 /** Whether `predicate` holds for any spelling that satisfies this request. */
 export function scopeSatisfied(entry, predicate) {
     return [entry.request, ...(entry.supersets ?? [])].some(predicate);
 }
-/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already
- *  do so — checking only the readonly spelling would warn a correctly configured app forever and push
- *  its author into a redundant approval round. Exported on its own because the serving-time capability
- *  report asks the same question, and a second mechanism there is what this type exists to prevent. */
+/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already do so. */
 export const FEISHU_MESSAGE_READ_REQUEST = {
     request: FEISHU_MESSAGE_READ_SCOPE,
     supersets: ["im:message"],
 };
-/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. Only the
- *  delivery scope is required for the context path; the read scope rides along because it shares the
- *  round and its absence merely degrades quoted messages to a marker. */
+/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. */
 export const FEISHU_CONTEXT_ONBOARDING_SCOPES = [
     { request: FEISHU_GROUP_CONTEXT_SCOPE },
     FEISHU_MESSAGE_READ_REQUEST,

package/dist/channels/feishu/ws-ingress.d.ts

@@ -22,7 +22,6 @@ export interface FeishuWsConnectionOptions {
     /** Internal SDK seam for deterministic tests. */
     createClient?: CreateFeishuWsClient;
 }
-/** Open Feishu/Lark's official-SDK WebSocket connection. The SDK ACKs only after `onEvent` settles;
- * a persistence throw therefore becomes a 500 response frame and the platform re-pushes the event. */
+/** Open Feishu/Lark's official-SDK WebSocket connection. */
 export declare function connectFeishuWs(options: FeishuWsConnectionOptions, signal: AbortSignal): LongConnection;
 export {};

package/dist/channels/feishu/ws-ingress.js

@@ -9,8 +9,8 @@ function sdkLogger(label) {
     };
 }
 async function productionClient(options, callbacks) {
-    // Webhook-only users stay on the lightweight fetch path; load the proprietary-protocol SDK only
-    // when a WebSocket connection is actually opened.
+    // Webhook-only users stay on the lightweight fetch path; load the proprietary-protocol SDK only when a WebSocket
+    // connection is actually opened.
     const { EventDispatcher, LoggerLevel, WSClient } = await import("@larksuiteoapi/node-sdk");
     const label = `[${options.kind}:ws]`;
     const logger = sdkLogger(label);
@@ -36,8 +36,7 @@ async function productionClient(options, callbacks) {
         close: () => client.close(),
     };
 }
-/** Open Feishu/Lark's official-SDK WebSocket connection. The SDK ACKs only after `onEvent` settles;
- * a persistence throw therefore becomes a 500 response frame and the platform re-pushes the event. */
+/** Open Feishu/Lark's official-SDK WebSocket connection. */
 export function connectFeishuWs(options, signal) {
     const label = `[${options.kind}:ws]`;
     // The SDK only logs + returns for this case (no onError), which would leave readiness pending forever.
@@ -63,8 +62,7 @@ export function connectFeishuWs(options, signal) {
             return;
         // Settle-then-close: closedSettled first makes a close()-triggered SDK callback re-entry a no-op.
         closedSettled = true;
-        // Terminal failure must release the transport here: the abort listener's close() no-ops once
-        // closedSettled is set, and only close() destroys SDK-held resources (e.g. its cache sweep timer).
+        // Terminal failure must release the transport here.
         if (client)
             closeClient(client);
         const failure = error instanceof Error ? error : new Error(String(error));
@@ -112,8 +110,8 @@ export function connectFeishuWs(options, signal) {
         if (client)
             closeClient(client);
         if (!readySettled) {
-            // Abort before the first connection: `ready` still settles, and resolution here means
-            // cancellation, not readiness (the LongConnection contract; serve skips ready-side effects).
+            // Abort before the first connection: `ready` still settles, and resolution here means cancellation, not
+            // readiness (the LongConnection contract; serve skips ready-side effects).
             readySettled = true;
             resolveReady();
         }

package/dist/channels/http.d.ts

@@ -1,23 +1,23 @@
 /**
- * HTTP/SSE channel: fan one invoke stream out to Server-Sent Events.
- *
- * The handler is Fetch-shaped (`(Request) => Promise<Response>`) — the cross-runtime form every
- * embedding host speaks, so it mounts inside an existing app's own route. It is path-agnostic. The
- * web stream primitives give cancellation (consumer disconnect → cancel() → iterator.return() →
- * invoke cancellation, SPEC MUST 3), backpressure (pull-based), and the body cap natively.
- *
- * Serving it is somebody else's job: the node:http bridge and the route table belong to the HOST
- * (`./serve.ts`). This file knows only the Agent contract and the wire shape of one stream.
+ * HTTP/SSE channel: fan one invoke stream out to Server-Sent Events. The web stream primitives supply cancellation
+ * natively (consumer disconnect → `cancel()` → `iterator.return()` → invoke cancellation, SPEC MUST 3), backpressure,
+ * and the body cap.
  */
 import type { Agent } from "../agent.ts";
-/** Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's
- *  dispatch imports it), so the two caps cannot drift apart. */
+/**
+ * Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's dispatch imports it), so
+ * the two caps cannot drift apart.
+ */
 export declare const MAX_BODY_BYTES: number;
-/** A valid example request body for the invoke handler — lives HERE, next to the shape check it must
- *  satisfy, so the CLI's "try it" hint can't drift from the protocol. */
+/**
+ * A valid example request body for the invoke handler — lives HERE, next to the shape check it must satisfy, so the
+ * CLI's "try it" hint can't drift from the protocol.
+ */
 export declare const INVOKE_EXAMPLE_BODY = "{\"session\":\"dev\",\"text\":\"hello\"}";
 /**
- * Fetch-shaped invoke handler. Mount it at any route in the host app; it accepts POST only.
- * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.
+ * Fetch-shaped invoke handler.
+ *
+ * No CORS here: who may call this from a browser is decided once, before dispatch, in `channels/serve.ts`'s router
+ * — which is also the only layer that can answer the `OPTIONS` preflight, since this route registers only `POST`.
  */
 export declare function createInvokeHandler(agent: Agent): (req: Request) => Promise<Response>;

package/dist/channels/http.js

@@ -1,20 +1,32 @@
-import { readBodyCapped } from "./body.js";
+import { readBodyCapped, refuseNonJsonBody } from "./body.js";
 import { text } from "./respond.js";
 import { sseResponse } from "./sse.js";
-/** Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's
- *  dispatch imports it), so the two caps cannot drift apart. */
+/**
+ * Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's dispatch imports it), so
+ * the two caps cannot drift apart.
+ */
 export const MAX_BODY_BYTES = 1 << 20;
-/** A valid example request body for the invoke handler — lives HERE, next to the shape check it must
- *  satisfy, so the CLI's "try it" hint can't drift from the protocol. */
+/**
+ * A valid example request body for the invoke handler — lives HERE, next to the shape check it must satisfy, so the
+ * CLI's "try it" hint can't drift from the protocol.
+ */
 export const INVOKE_EXAMPLE_BODY = '{"session":"dev","text":"hello"}';
 /**
- * Fetch-shaped invoke handler. Mount it at any route in the host app; it accepts POST only.
- * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.
+ * Fetch-shaped invoke handler.
+ *
+ * No CORS here: who may call this from a browser is decided once, before dispatch, in `channels/serve.ts`'s router
+ * — which is also the only layer that can answer the `OPTIONS` preflight, since this route registers only `POST`.
  */
 export function createInvokeHandler(agent) {
     return async (req) => {
         if (req.method !== "POST")
             return text("POST only\n", 405);
+        // Also applied by the host router over every unguarded route — kept HERE too because this handler is a
+        // PUBLIC standalone artifact (docs/overview.md mounts it as a Next.js route), and a handler you can mount
+        // anywhere has to be safe anywhere. The router's copy is what stops a route added later from forgetting.
+        const wrongType = refuseNonJsonBody(req);
+        if (wrongType)
+            return wrongType;
         const body = await readBodyCapped(req, MAX_BODY_BYTES);
         if ("tooLarge" in body)
             return text("body too large\n", 413);
@@ -30,8 +42,6 @@ export function createInvokeHandler(agent) {
             return text('need { "session": string, "text": string }\n', 400);
         }
         // INVOKE_EXAMPLE_BODY must keep satisfying this request shape.
-        // The OPTIONAL lineage extension (Scope): malformed values are a 400, not a silent drop — a
-        // caller that sent them meant them.
         if (parentSession !== undefined && typeof parentSession !== "string") {
             return text('"parentSession" must be a string\n', 400);
         }

package/dist/channels/kit/attachment-path.d.ts

@@ -1,10 +1,9 @@
 /**
- * Attachment destination for one conversation. Never rejects an id — but the path it returns is not
- * promised to be one the filesystem accepts: percent-encoding spends up to 9 bytes per character, so
- * an id of ~29 CJK characters exceeds a 255-byte `NAME_MAX` and the caller's `mkdir` fails with
- * `ENAMETOOLONG`. Left to fail there rather than truncated here: a digest suffix would buy a length
- * no platform id approaches, at the cost of the readability this encoding exists to keep.
+ * THE inbound-attachment root inside a channel's state home. One spelling because three channels write here and a
+ * conversation id becomes a directory under it; nothing else reads it, and nothing removes it — an attachment is
+ * durable conversation data, and this directory grows with the agent's inbound traffic (docs/design/core.md §9).
  */
+export declare const attachmentsDir: (stateHome: string) => string;
 export declare function attachmentPath(filesDir: string, conversationId: string | number, fileName: string): {
     dir: string;
     name: string;

package/dist/channels/kit/attachment-path.js

@@ -1,42 +1,18 @@
+/** Where an inbound attachment lands: `<stateHome>/files/<conversation>/<file>`. */
+import { join, resolve, sep } from "node:path";
 /**
- * Where an inbound attachment lands: `<filesDir>/<conversation>/<file>`.
- *
- * Both halves come from outside the channel, and they are NOT the same question:
- *
- * - The conversation is an id, and turning an arbitrary caller id into a storage name is a job this
- *   repo already answers by ENCODING it, never by rejecting it (`piSessionId` in
- *   engines/pi/session-store.ts, same shape: a character whitelist under a fixed prefix). An id is
- *   the caller's — a route returning `../..` gets an odd directory, not a failed turn, because the
- *   place to notice that id is broken is the reply it cannot deliver, not the disk.
- * - The file name is not an id: it is read by a human and by the model, in a path this puts into the
- *   prompt. Encoding it would cost that, so it is reduced instead — losing the odd character rather
- *   than the readability. A leading dot survives: `.gitignore` is a name, not an escape, and nothing
- *   lists this directory, so hiding is not a property anyone here depends on.
- *
- * The encoding makes containment structural rather than checked: `encodeURIComponent` emits no path
- * separator (`/` → `%2F`, `\` → `%5C`, `:` → `%3A`), and the prefix leaves no way to spell `.`, `..`
- * or the empty string.
- *
- * It is lossless for a well-formed id, so `a/b` and `a_b` are different places. Two exceptions, both
- * outside what a platform hands over: ids differing only in malformed UTF-16 (see the substitution
- * below), and ids differing only in case on a case-insensitive filesystem.
- */
-import { resolve, sep } from "node:path";
-/**
- * Attachment destination for one conversation. Never rejects an id — but the path it returns is not
- * promised to be one the filesystem accepts: percent-encoding spends up to 9 bytes per character, so
- * an id of ~29 CJK characters exceeds a 255-byte `NAME_MAX` and the caller's `mkdir` fails with
- * `ENAMETOOLONG`. Left to fail there rather than truncated here: a digest suffix would buy a length
- * no platform id approaches, at the cost of the readability this encoding exists to keep.
+ * THE inbound-attachment root inside a channel's state home. One spelling because three channels write here and a
+ * conversation id becomes a directory under it; nothing else reads it, and nothing removes it — an attachment is
+ * durable conversation data, and this directory grows with the agent's inbound traffic (docs/design/core.md §9).
  */
+export const attachmentsDir = (stateHome) => join(stateHome, "files");
 export function attachmentPath(filesDir, conversationId, fileName) {
-    // A lone surrogate makes `encodeURIComponent` throw `URIError`, and this function rejecting an id
-    // is the one thing it must not do — a permanent bad id would surface as a retryable turn failure.
-    // The `u` flag matches by code point, so a valid pair (an emoji in a route's id) is left alone.
+    // A lone surrogate makes `encodeURIComponent` throw `URIError`, and this function rejecting an id is the one thing
+    // it must not do.
     const id = String(conversationId).replace(/\p{Surrogate}/gu, "\uFFFD");
     const dir = resolve(filesDir, `c-${encodeURIComponent(id)}`);
-    // The name keeps its own check because it is NOT encoded: separators go, and `resolve` settles
-    // whether what is left (`..`, a Windows `D:foo`) still lands in `dir`.
+    // The name keeps its own check because it is NOT encoded: separators go, and `resolve` settles whether what is left
+    // (`..`, a Windows `D:foo`) still lands in `dir`.
     const cleaned = fileName.replace(/[/\\]/g, "_");
     const name = resolve(dir, cleaned).startsWith(dir + sep) ? cleaned : "file";
     return { dir, name, path: resolve(dir, name) };

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

@@ -1,36 +1,29 @@
-/** Per-message bound INSIDE that budget. The fold is a digest of many messages competing for one
- *  allowance, so the job here is fairness, not fidelity: one rambler must not price out everyone who
- *  spoke after them. 280 against 4000 keeps at least ~14 messages in a full buffer. A referent — the
- *  single message the asker points at — is the opposite job and takes REFERENT_MAX_CODE_POINTS. */
+/** Per-message bound INSIDE that budget. */
 export declare const BUFFER_LINE_MAX_CHARS = 280;
-/** 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. */
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded discussion. */
 export declare const BUFFER_ATTACH_MAX = 3;
 /**
- * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
- * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
- * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
- *
- * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
- * different claim about a different place, not this block with another name.
+ * Keep the newest {@link BUFFER_ATTACH_MAX} refs of one kind. The overflow is COUNTED, not silently dropped: the
+ * prompt note tells the model what it is not holding, so it cannot pretend to have read it.
  */
+export declare function capBufferedRefs<R>(refs: R[]): {
+    kept: R[];
+    skipped: number;
+};
+/** The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is empty. */
 export declare function discussionBlock(text: string): string;
 export interface ContextBuffer<E> {
-    /** Record an un-summoned message. Persists BEFORE returning (pre-ACK; see the module header). */
+    /** Record an un-summoned message. */
     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). */
+    /**
+     * Remove exactly `consumed` (by identity) — call on the turn's `completed` event, when the folded discussion
+     * provably lives in the durable session.
+     */
     commit(placeKey: string, consumed: E[]): void;
 }
 export declare function createContextBuffer<E>(options: {

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

@@ -1,52 +1,37 @@
 /**
- * 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.
+ * Generic durable context buffer — the SHARED mechanics behind each stateful channel's "un-summoned group discussion"
+ * module (telegram/feishu/slack `context-buffer.ts`). Generic over the entry shape: the channel supplies its entry
+ * type, the shape validator, the fold-line renderer and its log label.
  *
- * Channel-neutral and generic over the entry shape (like ../kit/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.
+ * 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.
  *  - `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).
+ *  - `commit` removes only that snapshot, by object identity, on the turn's `completed` — so a failure or crash before
+ *    `completed` leaves the discussion intact, and a message arriving mid-turn survives for the next answered turn.
+ *
+ * State files are an IO boundary: valid JSON of the WRONG shape degrades exactly like a corrupt file (warn + empty),
+ * never flowing in as trusted data.
  */
 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. */
+/**
+ * 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.
+ */
 const BUFFER_MAX_CHARS = 4000;
-/** Per-message bound INSIDE that budget. The fold is a digest of many messages competing for one
- *  allowance, so the job here is fairness, not fidelity: one rambler must not price out everyone who
- *  spoke after them. 280 against 4000 keeps at least ~14 messages in a full buffer. A referent — the
- *  single message the asker points at — is the opposite job and takes REFERENT_MAX_CODE_POINTS. */
+/** Per-message bound INSIDE that budget. */
 export const BUFFER_LINE_MAX_CHARS = 280;
-/** 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. */
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded discussion. */
 export const BUFFER_ATTACH_MAX = 3;
 /**
- * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
- * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
- * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
- *
- * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
- * different claim about a different place, not this block with another name.
+ * Keep the newest {@link BUFFER_ATTACH_MAX} refs of one kind. The overflow is COUNTED, not silently dropped: the
+ * prompt note tells the model what it is not holding, so it cannot pretend to have read it.
  */
+export function capBufferedRefs(refs) {
+    return { kept: refs.slice(-BUFFER_ATTACH_MAX), skipped: Math.max(0, refs.length - BUFFER_ATTACH_MAX) };
+}
+/** The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is empty. */
 export function discussionBlock(text) {
     return text ? `[recent group discussion:\n${text}\n]\n\n` : "";
 }
@@ -83,6 +68,8 @@ export function createContextBuffer(options) {
                 persist();
             }
             catch (error) {
+                // Staged on a copy, rolled back on a failed write, then rethrown: the throw becomes the webhook's 500 and the
+                // platform redelivers, so an entry left in memory here would be appended a second time.
                 if (previous)
                     buffers.set(placeKey, previous);
                 else