@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/{engines/pi/channel.js → channels/discover.js}

@@ -1,12 +1,14 @@
 /**
  * Channel discovery (the N axis, filesystem form). A channel file default-exports either the existing
  * route factory `(ctx) => Routes`, or an explicit long-connection module `{ name, connect(ctx, signal) }`.
+ *
+ * Engine-neutral, and living here rather than under `engines/` because of it: reading `channels/*.ts`
+ * is the Channel contract plus a directory, with no engine in sight.
  */
-import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { parseRouteKey, } from "../../host/node.js";
-import { isModuleFile, loadModuleDir } from "../../loader.js";
-import { assertInsideAgentDir } from "../../paths.js";
+import { assertRouteKey, routeKeysConflict } from "./serve.js";
+import { loadModuleDir, moduleInventory } from "../loader.js";
+import { assertInsideAgentDir } from "../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
 }
@@ -15,28 +17,29 @@ function validateLongConnectionModule(value, label) {
         throw new Error(`${label}: long-connection channel name must be a non-empty string`);
     }
 }
+/** Declared channels from basenames that share one ingress: the serving surface's mounted route list
+ *  (a long-connection channel mounts no HTTP route, so every route IS a webhook channel), and fixtures. */
+export function declaredChannels(names, ingress = "webhook") {
+    return names.map((name) => ({ name, ingress }));
+}
 /**
  * Import channel files without mounting route factories or opening connections. Deployment needs only
- * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * the authored structural fact: function exports are webhook channels; `{ connect() }` exports are
  * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
  */
 export async function inspectChannels(dir) {
     await assertInsideAgentDir(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const channels = [];
-    const routeChannels = [];
-    const longConnectionChannels = [];
     for (const { name, label, file, mod } of modules) {
         try {
             if (typeof mod.default === "function") {
-                channels.push(name);
-                routeChannels.push(name);
+                channels.push({ name, ingress: "webhook" });
                 continue;
             }
             if (longConnectionModule(mod.default)) {
                 validateLongConnectionModule(mod.default, label);
-                channels.push(name);
-                longConnectionChannels.push(name);
+                channels.push({ name, ingress: "long-connection" });
                 continue;
             }
             throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
@@ -45,7 +48,7 @@ export async function inspectChannels(dir) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { channels, routeChannels, longConnectionChannels, failures };
+    return { channels, failures };
 }
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
@@ -53,19 +56,8 @@ export async function inspectChannels(dir) {
  */
 export async function discoverChannelFiles(dir) {
     await assertInsideAgentDir(dir, "channels");
-    let names;
-    try {
-        names = await readdir(join(dir, "channels"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    return names
-        .filter(isModuleFile)
-        .map((name) => name.replace(/\.(ts|js|mjs)$/, ""))
-        .sort();
+    const entries = await moduleInventory(join(dir, "channels"));
+    return entries.map((entry) => entry.name);
 }
 function validateRoutes(value, label) {
     if (value === null || typeof value !== "object" || value instanceof Map) {
@@ -79,9 +71,7 @@ function validateRoutes(value, label) {
         if (typeof handler !== "function") {
             throw new Error(`${label}: route "${route}" must map to a handler function, got ${typeof handler}`);
         }
-        if (!parseRouteKey(route).path.startsWith("/")) {
-            throw new Error(`${label}: route "${route}" is not a valid route key (expected "METHOD /path" or "/path")`);
-        }
+        assertRouteKey(route, (problem) => `${label}: route "${route}" is not a valid route key — ${problem}`);
     }
     return routes;
 }
@@ -121,12 +111,7 @@ export async function loadChannels(dir, ctx) {
             }
             const declaredRoutes = validateRoutes(declared, label);
             for (const [route, handler] of declaredRoutes) {
-                const parsed = parseRouteKey(route);
-                const clash = Object.keys(routes).some((key) => {
-                    const existing = parseRouteKey(key);
-                    return (existing.path === parsed.path &&
-                        (existing.method === undefined || parsed.method === undefined || existing.method === parsed.method));
-                });
+                const clash = Object.keys(routes).some((key) => routeKeysConflict(key, route));
                 if (clash) {
                     collisions.push({ route, source: label });
                     continue;

package/dist/channels/feishu/card.js

@@ -17,7 +17,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 "../kit/text.js";
 /** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export const ANSWER_ELEMENT_ID = "answer";
 /** The volatile process element's id (thinking tail + tool lines + retry notice; live-only). */

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

@@ -1,4 +1,4 @@
-import { type ContextBuffer } from "../context-buffer.ts";
+import { type ContextBuffer } from "../kit/context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {
     messageId: string;

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

@@ -1,13 +1,13 @@
 /**
  * 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
+ * ../kit/context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
  * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
  * concrete thread root) and folded into the next answered turn in that place.
  */
 import { log } from "../../log.js";
-import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
-import { loadStateFile, saveStateFile } from "../state.js";
-import { truncateCodePointPrefix } from "../text.js";
+import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
+import { loadStateFile, saveStateFile } from "../kit/state.js";
+import { truncateCodePointPrefix } from "../kit/text.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
         .filter(Boolean)

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

@@ -20,8 +20,8 @@
  * here are shape-compatible with the SDK's `client.im.*` style, so the policy layer survives that swap.
  */
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { utf8Prefix } from "../text.js";
+import { attachmentPath } from "../kit/attachment-path.js";
+import { utf8Prefix } from "../kit/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. */
@@ -283,13 +283,10 @@ export function createFeishuApi(opts) {
         },
         async fetchFile(messageId, fileKey, name, chatId, filesDir) {
             const { bytes } = await api.downloadResource(messageId, fileKey, "file");
-            // The name is external input destined for a filesystem path — keep only its basename-safe core.
-            const safe = name.replace(/[/\\]/g, "_").replace(/^\.+/, "_") || "file";
-            const dir = join(filesDir, chatId);
-            await mkdir(dir, { recursive: true });
-            const dest = join(dir, safe);
-            await writeFile(dest, bytes);
-            return { path: dest, name: safe, size: bytes.byteLength };
+            const dest = attachmentPath(filesDir, chatId, name);
+            await mkdir(dest.dir, { recursive: true });
+            await writeFile(dest.path, bytes);
+            return { path: dest.path, name: dest.name, size: bytes.byteLength };
         },
         async getAppConfig(appId) {
             // v6 app detail — the one read surface that returns the event-security material (under data.app).

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

@@ -1,4 +1,4 @@
-import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuCloudProfile } from "./cloud.ts";
 import { type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute, feishuEnvelope } from "./parse.ts";
 import { type FeishuFailure } from "./preview.ts";

package/dist/channels/feishu/feishu.js

@@ -12,31 +12,38 @@ import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
-import { createSeenRing } from "../seen.js";
-import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome, loadStateFile, saveStateFile } from "../state.js";
-import { dispatchStop, isStopText } from "../stop-command.js";
-import { createTurnQueue } from "../turn-queue.js";
-import { createTurnStore } from "../turn-store.js";
+import { createSeenRing } from "../kit/seen.js";
+import { createTaskTracker } from "../kit/tasks.js";
+import { ensureStateHome, loadStateFile, saveStateFile } from "../kit/state.js";
+import { signatureIsFresh } from "../kit/signature.js";
+import { dispatchStop, isStopText } from "../kit/stop-command.js";
+import { createTurnQueue } from "../kit/turn-queue.js";
+import { commitAnsweredTurn, createTurnStore } from "../kit/turn-store.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { FEISHU_CLOUD } from "./cloud.js";
 import { collectFeishuBufferedAttachments, createFeishuContextBuffer, feishuBufferPlaceKey, feishuBufferText, } from "./context-buffer.js";
 import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
 import { invokeFeishuTurn } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
 import { normalizeFeishuMessage } from "./normalize.js";
-import { createThreadParticipants } from "../thread-participants.js";
+import { createThreadParticipants } from "../kit/thread-participants.js";
 import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_MESSAGE_READ_REQUEST, FEISHU_MESSAGE_READ_SCOPE, scopeSatisfied, } from "./setup-mode.js";
 import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderId, senderLabel, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
 import { connectFeishuWs } from "./ws-ingress.js";
 // Canonical public surface; the Lark subpath aliases these types/functions at its compatibility boundary.
 export { defaultFeishuRoute, feishuEnvelope };
-/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
- *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
- *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget. */
-const MAX_TURN_ATTEMPTS = 3;
 /** Event body cap — events are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_EVENT_BYTES = 1 << 20;
+/**
+ * Replay window for a SIGNED event, sized by the OPEN PLATFORM'S REDELIVERY SCHEDULE, not by Slack's
+ * 5 minutes: a failed push is retried at 15s / 5min / 1h / 6h. It is not established whether a retry
+ * is re-signed with a fresh timestamp or replays the original one, and only the second case is safe
+ * to guess wrong about in one direction — a window under 6h would 401 three of the four retries, i.e.
+ * turn one transient fault into a permanently lost user message (and a callback-health alarm). Wide
+ * enough to cover the chain, still bounded, and the `seen` ring dedups an event_id inside it.
+ */
+const MAX_SIGNATURE_AGE_S = 7 * 60 * 60;
 /** Queue feedback is immediate by default: it is the user's acknowledgement that this exact ask was
  *  accepted behind another turn. The same reply-quoted card becomes the preview/final answer, so there
  *  is no extra message or recall tombstone to avoid. Authors may still configure a delay explicitly. */
@@ -220,7 +227,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         });
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
         // Side tasks (stop feedback) run off the ingress path but drain in turnsIdle.
-        const sideTasks = createTaskTracker();
+        const sideTasks = createTaskTracker(label);
         const toStored = (r) => {
             const { preview: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
             return { ...intent, attempts: 0 };
@@ -285,7 +292,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 await notice?.done;
                 notices.delete(rec.id);
                 // Count this execution against the durable record (poison-turn ceiling) before running it again.
-                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
+                const decision = store.startAttempt(rec.id);
                 if (decision === "exceeded") {
                     notifyDropped(rec);
                     return;
@@ -312,8 +319,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 const roomBlock = room?.text
                     ? `[recent discussion in the room this thread branched from — not yet answered there:\n${room.text}\n]\n\n`
                     : "";
-                const threadBlock = recent ? `[recent group discussion:\n${recent}\n]\n\n` : "";
-                const prompt = `${roomBlock}${threadBlock}${rec.baseText}`;
+                const prompt = `${roomBlock}${discussionBlock(recent)}${rec.baseText}`;
                 // Room entries FIRST: the collector keeps the TAIL under its cap, so the thread's own
                 // attachments win the slots.
                 const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...consumed], {
@@ -331,12 +337,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                         label,
                         appId,
                         ...(parentSession !== undefined ? { parentSession } : {}),
-                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
-                        // Drop intent first: a crash between these writes may re-fold answered context later,
-                        // but can never replay this turn after its context was removed.
-                        store.remove(rec.id);
-                        buffer.commit(rec.bufferKey, consumed);
-                    }), api, targetOf(rec), formatError, rec.preview, label);
+                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey: rec.bufferKey, consumed })), api, targetOf(rec), formatError, rec.preview, label);
                     log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
                 }
                 catch (error) {
@@ -583,6 +584,12 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
     const { verificationToken, encryptKey } = opts;
     const { kind, envPrefix } = profile;
     const label = `[${kind}]`;
+    if (!encryptKey) {
+        // Said once at wiring, not per request: without an encrypt key events arrive in plaintext and
+        // carry no signature, so the freshness window below never runs and a captured body replays for
+        // as long as the verification token lives.
+        log.warn(`${label} no ${envPrefix}_ENCRYPT_KEY: events are accepted unsigned, with no replay window — set one in the console to enable it`);
+    }
     const handler = async (req) => {
         if (req.method !== "POST")
             return text("POST only\n", 405);
@@ -609,9 +616,19 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
                 nonce: req.headers.get("x-lark-request-nonce") ?? "",
                 signature: req.headers.get("x-lark-signature") ?? "",
             };
-            if (sig.signature && !verifySignature(encryptKey, sig, body.text)) {
-                log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
-                return text("invalid signature\n", 401);
+            if (sig.signature) {
+                // Freshness BEFORE the signature: the signature covers the timestamp but proves nothing about
+                // it, so without a window a captured body + its three x-lark-* headers replays forever. The
+                // `seen` ring is not that defence — it is bounded, and past its rollover a replay re-runs the
+                // turn (a re-sent message, a re-fired tool).
+                if (!signatureIsFresh(sig.timestamp, MAX_SIGNATURE_AGE_S)) {
+                    log.warn(`${label} rejected an event: X-Lark-Request-Timestamp outside the ±${MAX_SIGNATURE_AGE_S / 3600} h replay window`);
+                    return text("stale signature\n", 401);
+                }
+                if (!verifySignature(encryptKey, sig, body.text)) {
+                    log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
+                    return text("invalid signature\n", 401);
+                }
             }
             try {
                 envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));

package/dist/channels/feishu/invoke-turn.d.ts

@@ -13,7 +13,7 @@
  * or hide its still-readable siblings.
  */
 import type { Agent, AgentEvent } from "../../agent.ts";
-import { type BusyRetry } from "../invoke-turn-kit.ts";
+import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { FeishuBufferedRef } from "./context-buffer.ts";
 import type { FeishuApi } from "./feishu-api.ts";
 /** Everything the transport needs to fetch a turn's attachments. */

package/dist/channels/feishu/invoke-turn.js

@@ -1,8 +1,8 @@
 import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
-import { BUFFER_ATTACH_MAX } from "../context-buffer.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/invoke-turn-kit.js";
+import { BUFFER_ATTACH_MAX } from "../kit/context-buffer.js";
 import { parseContent } from "./parse.js";
-import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
+import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../kit/text.js";
 /** The per-turn REPLY CONTRACT, appended to the prompt (not the system prompt). Two halves, one
  *  concept — what happens to the reply: its FORMAT (rendered in a card whose markdown element is the
  *  natural fit for LLM output — steer away from HTML/plain) and its DELIVERY OWNERSHIP (the channel
@@ -169,7 +169,6 @@ async function resolveTurnInputs(t, attachments) {
             referentBlock += chain.block;
         }
     }
-    // Primary first and fail-fast: these are resources the current user explicitly pointed at.
     const imageRefs = [];
     for (const ref of images)
         imageRefs.push(await t.api.fetchImage(ref.msg, ref.key));

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

@@ -1,6 +1,6 @@
 import type { AgentEvent } from "../../agent.ts";
 import { type FeishuApi, type FeishuTarget } from "./feishu-api.ts";
-import { type ChannelFailure, defaultErrorMessage } from "../preview-kit.ts";
+import { type ChannelFailure, defaultErrorMessage } from "../kit/preview-kit.ts";
 /** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
 export type FeishuFailure = ChannelFailure;
 export { defaultErrorMessage };

package/dist/channels/feishu/preview.js

@@ -25,8 +25,8 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
 import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, PROCESS_ELEMENT_ID, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
 import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
-import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
-import { truncateCodePointPrefix, truncateUtf8 } from "../text.js";
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../kit/preview-kit.js";
+import { truncateCodePointPrefix, truncateUtf8 } from "../kit/text.js";
 export { defaultErrorMessage };
 /** How often (ms) to push a live-preview snapshot; tool events still flush on the next loop. Cardkit
  *  allows 10 QPS per card entity (50 per app), but one snapshot a second reads smoothly (the client
@@ -286,7 +286,11 @@ export async function streamFeishuReply(events, api, target, formatError, initia
                 // we throw below regardless.
                 finalized = true;
                 {
-                    const msg = formatError({ details: e.details, retryable: e.retryable }) ?? "";
+                    const msg = formatError({
+                        details: e.details,
+                        retryable: e.retryable,
+                        ...(e.code !== undefined ? { code: e.code } : {}),
+                    }) ?? "";
                     try {
                         await settle(msg);
                     }

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

@@ -1,4 +1,4 @@
-import type { LongConnection } from "../../host/node.ts";
+import type { LongConnection } from "../../channel.ts";
 import type { FeishuCloudKind } from "./cloud.ts";
 import type { FeishuMessageEvent } from "./parse.ts";
 interface FeishuWsClient {

package/dist/channels/github/github.d.ts

@@ -1,5 +1,5 @@
 import type { Schema } from "@octokit/webhooks-types";
-import type { ChannelModule } from "../../host/node.ts";
+import type { ChannelModule } from "../../channel.ts";
 /** A verified GitHub webhook event. Header fields plus the official typed payload. */
 export interface GithubEvent {
     /** `X-GitHub-Event` (e.g. "pull_request", "issue_comment"). */

package/dist/channels/http.d.ts

@@ -1,4 +1,14 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * 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.
+ */
 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. */
@@ -19,9 +29,3 @@ export declare const INVOKE_EXAMPLE_BODY = "{\"session\":\"dev\",\"text\":\"hell
  * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.
  */
 export declare function createInvokeHandler(agent: Agent): (req: Request) => Promise<Response>;
-/**
- * node:http adapter for a Fetch handler. Bridges IncomingMessage → Request and pumps the
- * Response body back to ServerResponse with backpressure; a client disconnect (`res` close)
- * cancels both the request signal and the response stream (→ invoke cancellation).
- */
-export declare function nodeListener(handler: (req: Request) => Promise<Response>): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/channels/http.js

@@ -1,17 +1,5 @@
-/**
- * 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.
- *
- * `nodeListener` is the thin node:http adapter for the embedded `fastagent dev/start` server.
- */
-import { Readable } from "node:stream";
-import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
-import { text, textHeaders } from "./respond.js";
+import { text } from "./respond.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. */
 export const MAX_BODY_BYTES = 1 << 20;
@@ -109,99 +97,3 @@ export function createInvokeHandler(agent) {
         });
     };
 }
-/**
- * node:http adapter for a Fetch handler. Bridges IncomingMessage → Request and pumps the
- * Response body back to ServerResponse with backpressure; a client disconnect (`res` close)
- * cancels both the request signal and the response stream (→ invoke cancellation).
- */
-export function nodeListener(handler) {
-    return (req, res) => {
-        void pump(handler, req, res); // safe: pump is TOTAL (never rejects) — see its contract below
-    };
-}
-/**
- * Consume ONE request and drive its response to a terminal state. pump is TOTAL: a SINGLE try/catch wraps
- * the whole request→response→stream path, so EVERY failure — a handler throw, a non-Response return
- * (`response.headers` undefined), a header Node rejects, `getReader`, or a body stream that errors
- * mid-flight — ends the response and the returned promise NEVER rejects, which is what lets the
- * `void pump(...)` above be safe. Before any byte goes out (headers not sent) it is a clean 500; once the
- * response is streaming, the only honest signal left is to destroy the socket (truncated stream, not a
- * hang). The process installs no `unhandledRejection` handler by design: robustness against a background
- * throw is each fire-and-forget's OWN contract (fail into a terminal HTTP response here), not a global net
- * that would blanket-swallow.
- */
-async function pump(handler, req, res) {
-    const controller = new AbortController();
-    res.on("close", () => controller.abort());
-    try {
-        const method = req.method ?? "GET";
-        const hasBody = method !== "GET" && method !== "HEAD";
-        const headers = new Headers();
-        for (const [k, v] of Object.entries(req.headers)) {
-            if (Array.isArray(v))
-                for (const vv of v)
-                    headers.append(k, vv);
-            else if (v != null)
-                headers.set(k, v);
-        }
-        const request = new Request(`http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, {
-            method,
-            headers,
-            body: hasBody ? Readable.toWeb(req) : undefined,
-            duplex: "half",
-            signal: controller.signal,
-        });
-        const response = await handler(request);
-        const outHeaders = {};
-        response.headers.forEach((value, key) => {
-            outHeaders[key] = value;
-        });
-        res.writeHead(response.status, outHeaders);
-        if (!response.body) {
-            res.end();
-            return;
-        }
-        const reader = response.body.getReader();
-        res.on("close", () => void reader.cancel());
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done || res.destroyed)
-                break;
-            // Backpressure: wait for drain, but ALSO resolve on close. A client disconnect after write()
-            // returned false never emits 'drain' on the closed socket, so waiting on 'drain' alone would
-            // suspend pump() forever (leaking the request/stream).
-            if (!res.write(value)) {
-                await new Promise((resolve) => {
-                    const settle = () => {
-                        res.off("drain", settle);
-                        res.off("close", settle);
-                        resolve();
-                    };
-                    res.once("drain", settle);
-                    res.once("close", settle);
-                });
-            }
-        }
-        if (!res.destroyed)
-            res.end(); // normal completion
-    }
-    catch (error) {
-        // The ONE totality boundary: every failure above lands here, so pump never rejects (see the header
-        // doc) — which REQUIRES the catch itself not to throw. Don't leak the internal message to the client.
-        log.error(`[host] request failed: ${String(error)}`);
-        // Never touch an already-terminal res: a client that disconnects during the handler await destroys res
-        // (headers not yet sent), and writeHead/end on a dead socket can throw ERR_STREAM_DESTROYED here — which
-        // WOULD be the unhandled rejection this boundary exists to kill. One named gate states the invariant;
-        // with it the catch is provably non-throwing (writeHead only when !headersSent && !destroyed, destroy is
-        // idempotent).
-        if (res.destroyed)
-            return;
-        if (res.headersSent) {
-            res.destroy(error instanceof Error ? error : undefined); // streaming → truncate (not a hang)
-        }
-        else {
-            res.writeHead(500, textHeaders); // pre-header → a clean 500
-            res.end("internal error\n");
-        }
-    }
-}

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export declare function attachmentPath(filesDir: string, conversationId: string | number, fileName: string): {
+    dir: string;
+    name: string;
+    path: string;
+};

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+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.
+    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`.
+    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/{context-buffer.d.ts → kit/context-buffer.d.ts}

@@ -9,6 +9,15 @@ export declare const BUFFER_LINE_MAX_CHARS = 280;
  *  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;
+/**
+ * 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.
+ */
+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). */
     push(placeKey: string, entry: E): void;