@fastagent-sh/fastagent 0.17.1 → 0.19.0

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

@@ -1,7 +1,8 @@
 import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.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
@@ -10,14 +11,126 @@ import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
 const REPLY_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card. This reply is " +
     "delivered to the current chat by the channel itself: do not call a send tool to answer the " +
     "current chat.)";
+/** How far up a reply chain the walk reads, beyond the replied-to message itself. The chain's natural
+ *  end is its ROOT — the platform threads every reply back to one — so this is an IO guard, not a
+ *  semantic boundary: each ancestor costs one serial `getMessage`, and a pathological chain must not
+ *  stall the turn. Field chains are 1–3 long; a capped walk says so in the block. */
+const MAX_CHAIN_ANCESTORS = 8;
+/** Attribution for a FETCHED message. getMessage's sender is `{ id, id_type, sender_type }` — a
+ *  DIFFERENT shape from the event's sender (`{ sender_id: { open_id } }`) — so the label is built
+ *  here, not via parse.senderLabel.
+ *
+ *  OWN means THIS app, not "an app". A group can hold several bots, and `sender_type === "app"` is
+ *  true for every one of them — matching on it alone would tell the model it wrote another bot's
+ *  message. The identity to compare is the app id, because an app sender carries `id_type: "app_id"`:
+ *  the cached bot open_id answers a different question (who was @mentioned) and would never match
+ *  here. A missing or unexpected id fails CLOSED — labelled by id, never claimed as the agent's own.
+ *  And an app is not a person: labelling another bot's message "user cli_…" is the same
+ *  misattribution in a quieter form, so the noun follows the sender type. */
+function fetchedSenderLabel(sender, appId) {
+    const appSender = sender?.sender_type === "app";
+    const senderId = sender?.id;
+    if (appSender && senderId === appId)
+        return "you, the agent";
+    return senderId ? `${appSender ? "app" : "user"} ${senderId}` : undefined;
+}
+/**
+ * Walk the reply chain ABOVE the replied-to message, to its root. Quoting a reply points at one link
+ * of an exchange; the pointer is only fully resolved when the model can read what that link was
+ * replying to — all the way up, because the platform defines where the chain ends (its root), which
+ * is what makes the walk bounded by STRUCTURE rather than by a level count someone picked.
+ *
+ * This is pointer resolution, not history. Session memory — what this place already knows — is a
+ * different track (design/participant-model.md §8): a one-hop version of this walk was removed once
+ * for trying to be that substitute; it returns doing only the pointer's job, which is also why it
+ * walks through ANY author's message — the chain is the platform's structure, not a conversation the
+ * agent took part in. The repetition this implies (an established session re-reads chain text it may
+ * already hold, each reply turn) is accepted deliberately and bounded: ancestors are CONTEXT, not
+ * the ask, so their text shares ONE further `REFERENT_MAX_CODE_POINTS` budget across the whole chain
+ * — the walk costs at most one more referent — while the pointed-at referent keeps its own full
+ * fidelity bound.
+ *
+ * Fail-open at every edge, but never silently at the model: any walk that ends short of the root —
+ * the ancestor cap, an exhausted text budget, an unreadable ancestor, a cycle — leaves the same
+ * neutral truncation line at the top of the block, because a chain rendered without it READS as
+ * complete and the model would take the oldest fetched node for the original ask. Unreadable
+ * ancestors and cycles also warn the operator; a cycle is corrupt platform data (reply chains are
+ * temporally acyclic by construction — a reply can only point at an EARLIER message — so one firing
+ * means the data, not the walk, is wrong).
+ */
+async function walkReplyChain(t, start, visited) {
+    const nodes = [];
+    const images = [];
+    const files = [];
+    // No parent above the referent = no chain — not a truncated one. The marker below is only for
+    // walks that END SHORT of a root that exists.
+    if (start === undefined)
+        return { block: "", images, files, ids: [] };
+    let reachedRoot = false;
+    let textBudget = REFERENT_MAX_CODE_POINTS;
+    let next = start;
+    while (next !== undefined) {
+        if (visited.has(next)) {
+            log.warn(`${t.label} reply chain points back to already-visited message ${next} — corrupt platform data; the walk ends here`);
+            break;
+        }
+        if (nodes.length >= MAX_CHAIN_ANCESTORS || textBudget <= 0)
+            break;
+        // The annotation breaks a control-flow-analysis cycle (id → msg → next → id) that trips TS7022.
+        const id = next;
+        visited.add(id);
+        let failure;
+        const msg = await t.api.getMessage(id).catch((error) => {
+            failure = String(error);
+            return undefined;
+        });
+        if (!msg) {
+            log.warn(`${t.label} could not read reply-chain message ${id} (${failure ?? "no such message"}) — the chain is rendered up to it`);
+            break;
+        }
+        const parsed = parseContent({
+            message_type: msg.msg_type ?? "unknown",
+            content: msg.body?.content ?? "",
+            mentions: msg.mentions,
+        });
+        const label = fetchedSenderLabel(msg.sender, t.appId);
+        const from = label ?? "reply chain";
+        for (const key of parsed.imageKeys)
+            images.push({ messageId: id, key, from });
+        for (const ref of parsed.fileRefs)
+            files.push({ messageId: id, key: ref.key, name: ref.name, from });
+        const text = truncateCodePointPrefix(parsed.text, textBudget) || "(empty)";
+        textBudget -= [...text].length;
+        nodes.push({ id, label, text });
+        if (msg.parent_id === undefined)
+            reachedRoot = true;
+        next = msg.parent_id;
+    }
+    nodes.reverse(); // fetched leaf→root; rendered oldest first, the way a transcript reads
+    const lines = nodes.map((node) => `(msg ${node.id}${node.label ? `, from ${node.label}` : ""}): ${node.text}`);
+    // One line for every way of ending short of the root — cap, budget, unreadable, cycle. It names no
+    // cause on purpose: the model needs the SHAPE (there is more above), the operator log has the why.
+    if (!reachedRoot)
+        lines.unshift("(…the chain continues above this point)");
+    return {
+        block: `\n[reply chain above it, oldest first:\n${lines.join("\n")}]`,
+        images,
+        files,
+        // Walked (fetched) order = nearest first — nodes were reversed for RENDERING above, so read the
+        // hint order off the rendered list backwards.
+        ids: nodes.map((node) => node.id).reverse(),
+    };
+}
 /**
- * Resolve a turn's inputs (module header): fetch the reply referent's content, then load every image
- * (vision) and file (disk). Primary failures throw; buffered resources degrade independently.
+ * Resolve a turn's inputs (module header): fetch the reply referent's content and resolve its reply
+ * chain, then load every image (vision) and file (disk). Primary failures throw; buffered resources
+ * degrade independently.
  */
 async function resolveTurnInputs(t, attachments) {
     const images = [...attachments.primary.images];
     const files = [...attachments.primary.files];
     let referentBlock = "";
+    let chain = { block: "", images: [], files: [], ids: [] };
     if (attachments.primary.parentId !== undefined) {
         const parentId = attachments.primary.parentId;
         // A referent is CONTEXT, not the ask. Losing it (deleted, restricted, unreadable) must not cost
@@ -49,35 +162,13 @@ async function resolveTurnInputs(t, attachments) {
                 images.push({ msg: parentId, key });
             for (const ref of parsed.fileRefs)
                 files.push({ msg: parentId, key: ref.key, name: ref.name });
-            // getMessage's sender is `{ id, id_type, sender_type }` — a DIFFERENT shape from the event's
-            // sender (`{ sender_id: { open_id } }`), so the label is built here, not via parse.senderLabel.
-            //
-            // OWN means THIS app, not "an app". A group can hold several bots, and `sender_type === "app"`
-            // is true for every one of them — matching on it alone would tell the model it wrote another
-            // bot's message. The identity to compare is the app id, because an app sender carries
-            // `id_type: "app_id"`: the cached bot open_id answers a different question (who was @mentioned)
-            // and would never match here. A missing or unexpected id fails CLOSED — labelled by id, never
-            // claimed as the agent's own.
-            const appSender = parent.sender?.sender_type === "app";
-            const senderId = parent.sender?.id;
-            const ownMessage = appSender && senderId === t.appId;
-            // An app is not a person: labelling another bot's message "user cli_…" is the same misattribution
-            // in a quieter form, so the noun follows the sender type.
-            const from = ownMessage ? "you, the agent" : senderId ? `${appSender ? "app" : "user"} ${senderId}` : undefined;
+            const from = fetchedSenderLabel(parent.sender, t.appId);
             referentBlock = `\n\n[replied-to message (msg ${parentId}${from ? `, from ${from}` : ""}): ${truncateCodePointPrefix(parsed.text, REFERENT_MAX_CODE_POINTS) || "(empty)"}]`;
-            // The chain STOPS here, at the one message the user pointed at. Walking further — to what that
-            // message was itself replying to — was built and removed: it reconstructs HISTORY out of reply
-            // pointers, and history is the session's job. That framing has no non-arbitrary answers (how
-            // many levels? what about the level above that? how is it deduplicated against what the session
-            // already holds? how does an IMAGE two levels up become prompt text at all?), and every one of
-            // those questions is a symptom of solving a session-layer problem in the prompt layer. The real
-            // gap it was papering over — a thread opened on a room answer starts with an EMPTY session while
-            // the room's session holds the exchange — belongs to memory inheritance (design/participant-
-            // model.md §8, rungs 3-4), where images and tool results come along for free because they are
-            // already in the history rather than being re-serialised into a prompt string.
+            // The referent's own parent starts the chain walk; the referent id seeds the cycle guard.
+            chain = await walkReplyChain(t, parent.parent_id, new Set([parentId]));
+            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));
@@ -88,8 +179,28 @@ async function resolveTurnInputs(t, attachments) {
     // downloaded twice or rendered twice in the manifest.
     const primaryImages = new Set(images.map((ref) => `${ref.msg}\u0000${ref.key}`));
     const primaryFiles = new Set(files.map((ref) => `${ref.msg}\u0000${ref.key}`));
-    const bufferedImages = attachments.buffered.images.filter((ref) => !primaryImages.has(`${ref.messageId}\u0000${ref.key}`));
-    const bufferedFiles = attachments.buffered.files.filter((ref) => !primaryFiles.has(`${ref.messageId}\u0000${ref.key}`));
+    // Chain ancestors and the context buffer share ONE background budget: BUFFER_ATTACH_MAX per kind.
+    // The cap is part of the tier's meaning, not an accident of who collected the ref — a rich-text
+    // ancestor must not turn the walk into an unbounded fan-out of downloads. Chain refs take slots
+    // FIRST: they are the direct upstream of the message the user pointed at, buffer refs are ambient
+    // discussion. Duplicates (a chain that points back into still-buffered discussion) count once, and
+    // what the cap drops is counted into the missing-attachments note like every other unloaded ref.
+    const capMerge = (chainRefs, bufferRefs, primary) => {
+        const seen = new Set();
+        const merged = [];
+        for (const ref of [...chainRefs, ...bufferRefs]) {
+            const identity = `${ref.messageId}\u0000${ref.key}`;
+            if (primary.has(identity) || seen.has(identity))
+                continue;
+            seen.add(identity);
+            merged.push(ref);
+        }
+        return { kept: merged.slice(0, BUFFER_ATTACH_MAX), dropped: Math.max(0, merged.length - BUFFER_ATTACH_MAX) };
+    };
+    const mergedImages = capMerge(chain.images, attachments.buffered.images, primaryImages);
+    const mergedFiles = capMerge(chain.files, attachments.buffered.files, primaryFiles);
+    const bufferedImages = mergedImages.kept;
+    const bufferedFiles = mergedFiles.kept;
     const backgroundImages = [];
     const backgroundFiles = [];
     let lost = 0;
@@ -114,7 +225,7 @@ async function resolveTurnInputs(t, attachments) {
             log.warn(`${t.label} could not load an earlier (buffered) attachment: ${String(result.reason)}`);
         }
     }
-    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped + mergedImages.dropped + mergedFiles.dropped);
     const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.map(({ ref }) => ref));
     const allFiles = [
         ...downloaded,
@@ -127,6 +238,7 @@ async function resolveTurnInputs(t, attachments) {
     return {
         images: allImages.length ? allImages : undefined,
         promptSuffix: `${referentBlock}${missingNote}${backgroundImageManifest}${attachedFilesManifest(allFiles)}`,
+        referentIds: [...(attachments.primary.parentId !== undefined ? [attachments.primary.parentId] : []), ...chain.ids],
     };
 }
 /**
@@ -144,5 +256,11 @@ export async function* invokeFeishuTurn(agent, session, text, transport, attachm
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${REPLY_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
+    // A thread turn names its lineage: parent place + the message ids that can locate the branch point
+    // (the referent and its chain — nearest first). The engine reads them ONCE, when the thread's
+    // session does not exist yet; on every later turn they ride along inertly.
+    const scope = transport.parentSession === undefined
+        ? { session }
+        : { session, parentSession: transport.parentSession, branchHints: resolved.referentIds };
+    yield* streamTurnWithBusyRetry(agent, scope, prompt, { label: transport.label, onCompleted, busyRetry });
 }

package/dist/channels/feishu/parse.js

@@ -52,6 +52,12 @@ export function cloudEnvelope(event, tag) {
         `chat ${message.chat_id} (${message.chat_type})`,
         message.thread_id ? `topic ${message.thread_id}` : undefined,
         from ? `from ${from}` : undefined,
+        // The message's own id is LOAD-BEARING, not decoration: it is the only way this message's id
+        // enters the session transcript, and session inheritance locates a thread's branch point by
+        // searching the parent transcript for exactly these ids (scope.branchHints — sessions.ts).
+        // Remove it and every thread quietly inherits from the room's present instead of the branch
+        // point. It also lets the model name what it is answering in a busy chat.
+        `msg ${message.message_id}`,
     ]
         .filter(Boolean)
         .join(", ");

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;
@@ -56,14 +44,27 @@ export function createInvokeHandler(agent) {
         catch {
             return text("invalid json\n", 400);
         }
-        const { session, text: promptText } = (payload ?? {});
+        const { session, text: promptText, parentSession, branchHints, } = (payload ?? {});
         if (typeof session !== "string" || typeof promptText !== "string") {
             return text('need { "session": string, "text": string }\n', 400);
         }
         // ^ the request shape INVOKE_EXAMPLE_BODY (below) must keep satisfying.
+        // 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);
+        }
+        if (branchHints !== undefined && !(Array.isArray(branchHints) && branchHints.every((h) => typeof h === "string"))) {
+            return text('"branchHints" must be an array of strings\n', 400);
+        }
         // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
         // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
-        const iterator = agent.invoke({ session }, { text: promptText })[Symbol.asyncIterator]();
+        const iterator = agent
+            .invoke({
+            session,
+            ...(parentSession !== undefined ? { parentSession } : {}),
+            ...(branchHints !== undefined ? { branchHints } : {}),
+        }, { text: promptText })[Symbol.asyncIterator]();
         // Heartbeats: a QUIET stream (a long tool call, no events) is normal here — remote consumers
         // distinguish "quiet but alive" from a dead connection by byte arrival, so silence must not
         // look identical to a black hole (SSE comments are ignored by spec-conforming parsers).
@@ -96,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/{context-buffer.js → kit/context-buffer.js}

@@ -4,7 +4,7 @@
  * 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
+ * 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
@@ -21,7 +21,7 @@
  *    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 { 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

package/dist/channels/{invoke-turn-kit.d.ts → kit/invoke-turn-kit.d.ts}

@@ -7,10 +7,14 @@
  *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
  *     {@link missingAttachmentsNote}, {@link attributedFileName}.
  *
+ * None of it asks what the agent can DO with an attachment. A channel resolves platform resources and
+ * states what it found; deciding whether to open a file is the agent's, and one assembled without a
+ * file tool answers that it cannot — visibly, at the moment it is asked.
+ *
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
  * message-scoped Feishu keys, Slack file objects) are real differences.
  */
-import { type Agent, type AgentEvent, type Prompt } from "../agent.ts";
+import { type Agent, type AgentEvent, type Prompt, type Scope } from "../../agent.ts";
 /** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
  *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
  *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
@@ -35,7 +39,10 @@ export declare const DEFAULT_BUSY_RETRY: BusyRetry;
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export declare function streamTurnWithBusyRetry(agent: Agent, session: string, prompt: Prompt, options: {
+export declare function streamTurnWithBusyRetry(agent: Agent, 
+/** The full scope, not a session string — channels that set extension fields (lineage) pass them
+ *  through here; channels that don't pass `{ session }` and nothing changes. */
+scope: Scope, prompt: Prompt, options: {
     label: string;
     onCompleted?: () => void;
     busyRetry?: BusyRetry;
@@ -46,8 +53,15 @@ export interface ManifestFile {
     size: number;
     path: string;
 }
-/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
- *  Empty input renders nothing. */
+/**
+ * The downloaded-file manifest appended to the prompt: name, size, path. Empty input renders nothing.
+ *
+ * It STATES, it does not instruct. The earlier wording ("read them with your tools") was an
+ * assumption about the reader, and an assumption has to be verified — which is where a capability
+ * flag threaded through eight files came from. An agent with a file tool decides for itself whether
+ * to open one, and how much of it; an agent without one says so. Neither needs this line to have
+ * guessed first.
+ */
 export declare function attachedFilesManifest(files: readonly ManifestFile[]): string;
 /** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),
  *  the way the fold attributes text lines. */

package/dist/channels/{invoke-turn-kit.js → kit/invoke-turn-kit.js}

@@ -7,12 +7,16 @@
  *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
  *     {@link missingAttachmentsNote}, {@link attributedFileName}.
  *
+ * None of it asks what the agent can DO with an attachment. A channel resolves platform resources and
+ * states what it found; deciding whether to open a file is the agent's, and one assembled without a
+ * file tool answers that it cannot — visibly, at the moment it is asked.
+ *
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
  * message-scoped Feishu keys, Slack file objects) are real differences.
  */
-import { SESSION_BUSY_CODE } from "../agent.js";
-import { log } from "../log.js";
-// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
+import { SESSION_BUSY_CODE } from "../../agent.js";
+import { log } from "../../log.js";
+// Each retry is a lease-check-level reject (tryAcquire runs before the session is bound) — waiting is nearly
 // free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
 // real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
 // this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
@@ -33,13 +37,17 @@ export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export async function* streamTurnWithBusyRetry(agent, session, prompt, options) {
+export async function* streamTurnWithBusyRetry(agent, 
+/** The full scope, not a session string — channels that set extension fields (lineage) pass them
+ *  through here; channels that don't pass `{ session }` and nothing changes. */
+scope, prompt, options) {
     const { label, onCompleted, busyRetry = DEFAULT_BUSY_RETRY } = options;
+    const session = scope.session;
     const deadline = Date.now() + busyRetry.maxWaitMs;
     for (;;) {
         let retryBusy = false;
         let first = true;
-        for await (const e of agent.invoke({ session }, prompt)) {
+        for await (const e of agent.invoke(scope, prompt)) {
             if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
                 retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
                 break;
@@ -55,11 +63,18 @@ export async function* streamTurnWithBusyRetry(agent, session, prompt, options)
         await new Promise((r) => setTimeout(r, busyRetry.delayMs));
     }
 }
-/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
- *  Empty input renders nothing. */
+/**
+ * The downloaded-file manifest appended to the prompt: name, size, path. Empty input renders nothing.
+ *
+ * It STATES, it does not instruct. The earlier wording ("read them with your tools") was an
+ * assumption about the reader, and an assumption has to be verified — which is where a capability
+ * flag threaded through eight files came from. An agent with a file tool decides for itself whether
+ * to open one, and how much of it; an agent without one says so. Neither needs this line to have
+ * guessed first.
+ */
 export function attachedFilesManifest(files) {
     return files.length
-        ? `\n\n[attached files — read them with your tools:\n${files.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+        ? `\n\n[attached files:\n${files.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
         : "";
 }
 /** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),

package/dist/channels/{preview-kit.d.ts → kit/preview-kit.d.ts}

@@ -8,11 +8,13 @@
  * everything platform-independent lives here, so a new event type or a wording change lands in ONE
  * place instead of one hunk per channel.
  */
-import type { AgentEvent, Json } from "../agent.ts";
+import type { AgentEvent, Json } from "../../agent.ts";
 /** A terminal failure, as a channel hands it to its `onError`. */
 export interface ChannelFailure {
     details: string;
     retryable: boolean;
+    /** The engine's failure code, when it set one. */
+    code?: string;
 }
 /** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
  *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").

package/dist/channels/{seen.js → kit/seen.js}

@@ -1,5 +1,5 @@
 /** Best-effort bounded durable dedup ring, recorded only after the caller's pre-ACK side effect is durable. */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
 export function createSeenRing(path, label, cap = 2000) {
     const raw = loadStateFile(path);

package/dist/channels/kit/state.d.ts

@@ -0,0 +1,6 @@
+/** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
+export declare function ensureStateHome(dir: string): void;
+/** Returns `unknown` on purpose — no generic pretending otherwise: the file is an IO boundary, and the
+ *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
+export declare function loadStateFile(path: string): unknown;
+export declare function saveStateFile(path: string, value: unknown): void;