@fastagent-sh/fastagent 0.18.0 → 0.19.0

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

@@ -1,5 +1,5 @@
-import { type ChannelContext, type LongConnection, type Routes } from "../../host/node.ts";
-import { type ModuleLoadFailure } from "../../loader.ts";
+import type { ChannelContext, LongConnection, Routes } from "../channel.ts";
+import { type ModuleLoadFailure } from "../loader.ts";
 /** A dropped route: two channels claim the same key. Surfaced, never silent. */
 export interface ChannelCollision {
     route: string;

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

@@ -1,12 +1,15 @@
 /**
  * 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 { isModuleFile, loadModuleDir } from "../loader.js";
+import { assertInsideAgentDir } from "../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
 }
@@ -79,9 +82,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 +122,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

@@ -21,7 +21,7 @@
  */
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { utf8Prefix } from "../text.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. */

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,19 +12,19 @@ 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 { dispatchStop, isStopText } from "../kit/stop-command.js";
+import { createTurnQueue } from "../kit/turn-queue.js";
+import { createTurnStore } from "../kit/turn-store.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";

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/{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, type Scope } 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
@@ -49,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
@@ -59,11 +63,18 @@ scope, 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/{state.js → kit/state.js}

@@ -12,9 +12,9 @@
  * is an ENVIRONMENT error the operator must fix: it throws, and construction fails loudly — booting
  * with silently-empty state would hide real data behind a config mistake.
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { log } from "../log.js";
+import { mkdirSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { log } from "../../log.js";
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
     mkdirSync(dir, { recursive: true });
@@ -43,8 +43,5 @@ export function loadStateFile(path) {
     }
 }
 export function saveStateFile(path, value) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(value));
-    renameSync(tmp, path);
+    writeFileAtomic(path, JSON.stringify(value));
 }

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

@@ -1,4 +1,4 @@
-import { type SessionControl } from "../session.ts";
+import { type SessionControl } from "../../session.ts";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export declare function isStopText(text: string): boolean;
 /** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;

package/dist/channels/{stop-command.js → kit/stop-command.js}

@@ -6,8 +6,8 @@
  * at-least-once floor; and the hub stays gated by `config.sessionControl`, so without it the command
  * degrades to a visible "not enabled" notice, never a silent ignore.
  */
-import { log } from "../log.js";
-import { NO_ACTIVE_RUN_CODE } from "../session.js";
+import { log } from "../../log.js";
+import { NO_ACTIVE_RUN_CODE } from "../../session.js";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export function isStopText(text) {
     return /^(stop|cancel)[.!]?$/i.test(text.trim());

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

@@ -4,7 +4,7 @@
  * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
  * handling stays with the caller: track() only guarantees the drain sees the task settle.
  */
-import { beginWork } from "./busy.js";
+import { beginWork } from "../busy.js";
 export function createTaskTracker() {
     const tasks = new Set();
     return {

package/dist/channels/{thread-participants.js → kit/thread-participants.js}

@@ -19,7 +19,7 @@
  * - Keyed by `thread_id`, never a reply-chain root: Feishu's `root_id` moves with the chain, so it
  *   cannot identify a side conversation at all.
  */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
 /** Cap on remembered threads. Losing one costs a mention to re-enter that thread, so an unbounded file
  *  buys little — and a merge that carries new information rewrites the whole map synchronously, so the

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

@@ -10,8 +10,8 @@
  * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
  * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
  */
-import { log } from "../log.js";
-import { beginWork } from "./busy.js";
+import { log } from "../../log.js";
+import { beginWork } from "../busy.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
     // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of

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

@@ -49,7 +49,7 @@
  * Single-process, single-writer: same durability model as state.ts (crash-safe via atomic rename;
  * power-loss is best-effort — no fsync, consistent with the rest of the channel's state).
  */
-import { log } from "../log.js";
+import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
 export function createTurnStore(path, opts) {
     const { label, isRecord, order } = opts;

package/dist/channels/lark/lark.d.ts

@@ -3,7 +3,7 @@
  * this module binds it to Lark's cloud profile and exposes natural Lark-branded public names. Lark's
  * weaker control-plane capabilities live in onboarding/registration, not in a fork of the turn engine.
  */
-import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, type FeishuWebSocketChannelOptions, defaultFeishuRoute } from "../feishu/feishu.ts";
 export type LarkChannelOptions = FeishuChannelOptions;
 export type LarkWebSocketChannelOptions = FeishuWebSocketChannelOptions;