@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/channels/serve.js

@@ -1,62 +1,32 @@
 /**
- * How a {@link Routes} table becomes a running server: the path rule, dispatch, the totality
- * boundary, and the node:http binding.
- *
- * Shared ground, not a deployment target — every host in `src/deploy/` runs this same process; what
- * differs between them is process, storage, credentials and deployment (core.md §1), none of it
- * here.
- *
- * Dispatch is a Map lookup rather than a router because a deployment mounts a handful of LITERAL
- * paths. A routing library would answer through a pattern language we do not use, and its extra
- * semantics (decode-before-match, HEAD fallback, wildcard precedence) would have to be predicted by
- * every collision check.
- *
- * The types a channel author or an embedder writes stay pure Fetch — SPEC §11 fixes the gateway
- * contract as `(Request) => Response`, and an embedding app may already run its own framework.
- * `overrideGlobalObjects: false` is part of that: the adapter otherwise swaps
- * `globalThis.Request`/`Response` process-wide, which breaks a channel holding a `Response`
- * captured before mount (it fails `instanceof` in {@link totalFetch} and is answered 500).
- *
- * Post-ACK work (a webhook channel's fire-and-forget turns) runs on this event loop and is lost on
- * shutdown — the accepted tradeoff until durable execution (the K axis) exists.
+ * How a {@link Routes} table becomes a running server: the path rule, dispatch, WHO MAY CALL IT FROM A BROWSER, the
+ * totality boundary, and the node:http binding.
  */
 import { serve, getRequestListener } from "@hono/node-server";
 import { log } from "../log.js";
+import { refuseNonJsonBody } from "./body.js";
 import { text } from "./respond.js";
-/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method).
- *  An empty method (`" /x"`) parses as `""`, which {@link assertRouteKey} refuses — see there. */
+/** Methods whose request carries a body a handler will parse — what the JSON gate applies to. */
+const BODY_METHODS = new Set(["POST", "PUT", "PATCH"]);
+/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
 export function parseRouteKey(key) {
     const sp = key.indexOf(" ");
     return sp === -1 ? { path: key } : { method: key.slice(0, sp).toUpperCase(), path: key.slice(sp + 1) };
 }
-/**
- * A route key is `"METHOD /path"` or `"/path"`, with a literal path.
- *
- * Every rule here exists because breaking it costs SOMEONE ELSE. Two keys naming one route, a route
- * under a mount, a path a URL rewrites (`/a/../x` and `/x` are one route spelled two ways, while
- * the conflict check compares strings) — in each case a channel goes dark and its author did
- * nothing wrong.
- *
- * Mistakes that only cost their own author a debugging session are NOT policed: `:id` and `*` are
- * literal path characters here, so such a key simply never matches, and an unusual method is the
- * same. Refusing those would trade a working capability for a lecture.
- */
+/** A route key is `"METHOD /path"` or `"/path"`, with a literal path. */
 export function assertRouteKey(key, describe) {
     const { method, path } = parseRouteKey(key);
     if (method === "")
         throw new Error(describe('a leading space is not a method — write "/path" for any method'));
     if (!path.startsWith("/"))
         throw new Error(describe('must start with "/"'));
-    // Asked of `URL` rather than by listing what it rewrites (`?`/`#`, `.`/`..`, `\`, `%2e`). A key it
-    // rewrites is unreachable AND compares as a different string, hiding that `/a/../x` and `/x` are
-    // one route.
+    // Asked of `URL` rather than by listing what it rewrites (`?`/`#`, `.`/`..`, `\`, `%2e`).
     const arrives = new URL(path, "http://x").pathname;
     if (arrives !== path) {
         throw new Error(describe(`is not the path a request would carry — that request arrives as "${arrives}"`));
     }
 }
-/** Do these two keys fight over the same request? Equal paths, and a method each answers; a key
- *  with no method answers all of them. */
+/** Do these two keys fight over the same request? */
 export function routeKeysConflict(a, b) {
     const ka = parseRouteKey(a);
     const kb = parseRouteKey(b);
@@ -64,28 +34,97 @@ export function routeKeysConflict(a, b) {
         return false;
     return ka.method === undefined || kb.method === undefined || ka.method === kb.method;
 }
-/** Same status and headers, no content (RFC 9110's HEAD). The discarded body is cancelled, or a
- *  streaming producer keeps running with no reader. Shared with the control plane, which answers
- *  HEAD too. */
+/** Same status and headers, no content (RFC 9110's HEAD). */
 export function withoutBody(res) {
     void res.body?.cancel().catch(() => { });
     return new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers });
 }
-/** Is `path` inside `prefix`? Segment-wise, so `/controlled` is not inside `/control`. */
 export function pathUnderPrefix(path, prefix) {
     return path === prefix || path.startsWith(`${prefix}/`);
 }
 /**
- * Compose a {@link Routes} table and its {@link PrefixMount}s into one handler.
+ * THE cross-origin policy, in one place, for the routes that authenticate nobody.
+ *
+ * THIS IS AN API, so the default is an API's: `*`, unconditionally. Origin is not access control — what makes any
+ * API safe to call from a page is a credential the page does not have, which makes the caller's origin irrelevant.
+ * We have no credential, and the boundary that replaces it — who may reach this port — belongs to the deployment,
+ * the same rule that removed the bearer token. Deciding for the operator from a signal this process can observe
+ * (which address it bound) is not that rule: a wildcard bind is what a container needs, not something the operator
+ * said, and a loopback one is `dev`'s default, not a claim about who may call.
  *
- * Refuses at assembly anything that could not receive a request: a key naming the same route as
- * another (`"/x"` and `"GET /x"`), a route inside a mount, two mounts claiming the same ground. A
- * channel must never go dark unannounced.
+ * WHAT `*` GRANTS, stated because it is the default and nobody opts into it: any page the user's browser visits can
+ * call this port cross-origin and read the reply — a turn with the agent's full tool authority, and with
+ * `sessionControl: true`, reading and deleting sessions. On a published port that is nothing an attacker could not
+ * already curl. On a loopback `dev` serve it is the whole attack path, and this is the posture the decision costs:
+ * `announceControl` says so at every boot, and `http.cors` is the one way to take it back.
  *
- * 404 and 405 stay distinct: a remote client reads 404 as "this serve predates the route" (version
- * skew) rather than as a fault.
+ * `allow` is `http.cors`, and when it is set it REPLACES the default rather than adding to it: `["*"]` is the
+ * default said out loud, a list of origins is the narrowing.
+ *
+ * An origin that is not allowed is simply not ANSWERED — no headers, no refusal. That is safe only because a route
+ * that authenticates nobody also refuses a body that is not `application/json` (channels/body.ts): without that, a
+ * cross-origin `text/plain` POST is a CORS simple request, sent with no preflight, and withholding the headers
+ * would only stop the page from reading a turn that had already run.
  */
-export function router(routes, mounts = []) {
+function allowedOrigin(origin, allow) {
+    if (allow.length === 0)
+        return "*";
+    return allow.includes("*") ? "*" : allow.includes(origin) ? origin : undefined;
+}
+/**
+ * Refuse a cross-origin allow-list that cannot match anything.
+ *
+ * ONE check for BOTH ways in: `http.cors` in a config file, and `corsOrigins` handed to `mountAgentService` by an
+ * embedder. `allowedOrigin` compares exact strings, so `"https://app.example.com/"` — one trailing slash — never
+ * matches and the front end is refused with nothing pointing at the rule. A rule that silently matches nothing is
+ * worse than one that refuses to load.
+ */
+export function assertCorsOrigins(origins, where) {
+    if (!Array.isArray(origins) || origins.some((o) => typeof o !== "string" || o === "")) {
+        throw new Error(`${where} must be an array of origin strings (e.g. ["https://app.example.com"])`);
+    }
+    // An EMPTY list is the one spelling that means the OPPOSITE of what it looks like. `allowedOrigin` reads "nothing
+    // configured" as the `*` default and cannot tell that apart from a list someone wrote as empty, so `http.cors: []`
+    // — the obvious way to write "no page may call this" — would grant the widest policy there is, and silence the
+    // boot warning that names it (`announceControl` treats a set list as the operator having chosen the origins).
+    if (origins.length === 0) {
+        throw new Error(`${where} is empty — list at least one origin, or write ["*"] to say the default out loud`);
+    }
+    for (const origin of origins) {
+        if (origin === "*")
+            continue;
+        let parsed;
+        try {
+            parsed = new URL(origin);
+        }
+        catch {
+            // `new URL` throwing IS the answer here ("not a URL at all"); rethrown as the rule that cannot load.
+            throw new Error(`${where} entry ${JSON.stringify(origin)} is not an origin ("https://host[:port]")`);
+        }
+        // An ORIGIN, not a URL with a path: `new URL(...).origin` is what a browser sends.
+        if (parsed.origin !== origin) {
+            throw new Error(`${where} entry ${JSON.stringify(origin)} is not the origin a browser sends — use ${JSON.stringify(parsed.origin)}`);
+        }
+    }
+}
+/**
+ * Compose the routes that AUTHENTICATE NOBODY, the self-verifying channel routes, and the {@link PrefixMount}s
+ * into one handler.
+ *
+ * That is the axis, not authorship. Two things follow from it and nothing else does: whether a browser may drive
+ * the route, and whether its body must declare JSON. A channel route is exempt from both because it checks its
+ * platform's signature inside itself — a Telegram webhook is public on purpose. Ours check nothing, so the router
+ * checks for them.
+ *
+ * TWO TABLES, not one table plus a list of which keys are which, so the three readers (browser reachability, the JSON
+ * body gate, the startup report) cannot answer differently.
+ *
+ * CAVEAT, stated because we cannot enforce it: a CUSTOM channel that verifies nothing lands in `selfVerifying`
+ * anyway and gets neither guard. That is decision B (docs/design/session-control.md §14) and it belongs to the
+ * channel's author, who owns the credential the platform issued — but it is an assumption here, not a property.
+ */
+export function router(surface) {
+    const { unverified = {}, selfVerifying = {}, mounts = [], corsOrigins = [] } = surface;
     for (const [i, mount] of mounts.entries()) {
         assertRouteKey(mount.prefix, (problem) => `mount prefix "${mount.prefix}" is invalid — ${problem}`);
         if (mount.prefix === "/") {
@@ -103,7 +142,8 @@ export function router(routes, mounts = []) {
     }
     const byKey = new Map();
     const paths = new Set();
-    for (const [key, handler] of Object.entries(routes)) {
+    const unguarded = new Set();
+    for (const [key, handler] of [...Object.entries(unverified), ...Object.entries(selfVerifying)]) {
         assertRouteKey(key, (problem) => `route "${key}" is not a valid route key — ${problem}`);
         const { path } = parseRouteKey(key);
         for (const mount of mounts) {
@@ -115,16 +155,52 @@ export function router(routes, mounts = []) {
         if (shadowed) {
             throw new Error(`route "${key}" conflicts with "${shadowed}" — one of them would never receive a request`);
         }
-        // Stored normalised: `parseRouteKey` upper-cases the method, so `"get /x"` validates under
-        // `GET` and would otherwise be looked up under a name nothing stores.
+        // Stored normalised: `parseRouteKey` upper-cases the method, so `"get /x"` validates under `GET` and would
+        // otherwise be looked up under a name nothing stores.
         const { method } = parseRouteKey(key);
-        byKey.set(method ? `${method} ${path}` : path, handler);
+        const normalised = method ? `${method} ${path}` : path;
+        byKey.set(normalised, handler);
         paths.add(path);
+        if (key in unverified)
+            unguarded.add(normalised);
     }
+    /** Does this route authenticate nobody? Every mount does (the control plane), plus what we registered ourselves. */
+    const authenticatesNobody = (method, path) => mounts.some((mount) => pathUnderPrefix(path, mount.prefix)) ||
+        unguarded.has(`${method} ${path}`) ||
+        unguarded.has(path) ||
+        // The router answers HEAD from a GET route, so the question follows it.
+        (method === "HEAD" && unguarded.has(`GET ${path}`));
     return (req) => {
         // `URL` normalises the path (`/a/../x` → `/x`) and drops query/fragment.
         const path = new URL(req.url).pathname;
+        const origin = req.headers.get("origin");
+        // A preflight asks ABOUT a method; ownership is that method's, not `OPTIONS`'s (nothing registers OPTIONS).
+        const asking = req.method === "OPTIONS"
+            ? (req.headers.get("access-control-request-method")?.toUpperCase() ?? "OPTIONS")
+            : req.method;
+        // A BROWSER request against a route that authenticates nobody. A non-browser client sends no `Origin` and is
+        // untouched by any of this.
+        const owned = authenticatesNobody(asking, path);
+        const fromPage = origin !== null && owned;
+        // Decided BEFORE dispatch, so a 404, a 405 and a handler's own reply all leave with the same verdict — a browser
+        // that cannot read the 405 gets an opaque network error instead of the reason.
+        const cors = fromPage ? allowedOrigin(origin, corsOrigins) : undefined;
         const answer = () => {
+            // The gate that makes "an origin we do not allow is simply not answered" safe: a POST carrying `text/plain`
+            // is a CORS simple request, sent with no preflight at all, so a route that authenticates nobody must refuse
+            // the body itself. HERE, over the whole unguarded surface, rather than inside each handler — the next route
+            // we add is covered by existing. A self-verifying channel is exempt: Slack posts urlencoded, and a page
+            // cannot forge its signature anyway.
+            if (owned && BODY_METHODS.has(req.method)) {
+                const wrongType = refuseNonJsonBody(req);
+                if (wrongType)
+                    return wrongType;
+            }
+            // The preflight is the ROUTER's to answer: it names a method the route table does not register, so leaving it
+            // to the routes below is a 405 with no CORS headers, which is a browser client that cannot call a route that
+            // works.
+            if (req.method === "OPTIONS" && cors !== undefined)
+                return new Response(null, { status: 204 });
             for (const mount of mounts)
                 if (pathUnderPrefix(path, mount.prefix))
                     return mount.handler(req);
@@ -138,22 +214,36 @@ export function router(routes, mounts = []) {
             }
             return paths.has(path) ? text("method not allowed\n", 405) : text("not found\n", 404);
         };
-        // ONE exit, so the HEAD rule holds for every reply — a mount's, a route's, the GET fallback's,
-        // and the 404/405 this router writes itself. RFC 9110: HEAD is GET without the content.
+        /**
+         * ONE exit, so the HEAD rule and the CORS verdict hold for every reply — a mount's, a route's, the GET
+         * fallback's, and the 404/405 this router writes itself.
+         */
+        const finish = (res) => {
+            const out = req.method === "HEAD" ? withoutBody(res) : res;
+            // `vary` whether or not the origin was allowed: the answer DEPENDS on the request's origin either way, and a
+            // cache that does not know it would serve one caller's verdict to another.
+            if (owned)
+                out.headers.append("vary", "origin");
+            if (cors === undefined)
+                return out;
+            out.headers.set("access-control-allow-origin", cors);
+            // Echoed for the same reason the methods are: what a caller needs is not ours to enumerate. A gateway in front
+            // of this port demands its own header (`connectSessionControl({ fetchFn })` is how a client sends one), and a
+            // fixed list turns that preflight into a 204 the browser then refuses to act on. The default names the two a
+            // client of ours always needs, for a preflight that asked about nothing.
+            out.headers.set("access-control-allow-headers", req.headers.get("access-control-request-headers") ?? "authorization, content-type");
+            // The method the preflight ASKED about, not a table lookup: a mount owns a prefix and does not publish which
+            // methods each path under it serves. Naming one the path does not serve costs nothing now that the 405 it
+            // produces carries these same headers.
+            const asked = req.headers.get("access-control-request-method")?.toUpperCase();
+            out.headers.set("access-control-allow-methods", [...new Set([asked, "OPTIONS"].filter(Boolean))].join(", "));
+            return out;
+        };
         const res = answer();
-        if (req.method !== "HEAD")
-            return res;
-        return res instanceof Promise ? res.then(withoutBody) : withoutBody(res);
+        return res instanceof Promise ? res.then(finish) : finish(res);
     };
 }
-/**
- * The totality boundary every serving path shares. `loadChannels` imports arbitrary author code, so
- * a channel that throws — or forgets to return — must become a logged 500 rather than escape as an
- * unhandled rejection. Both `nodeListener` and `serveNode` route through it.
- *
- * The message stays internal: an adapter's default error page would echo exception text (a stack, a
- * path, a key inside an error string) to whoever made the request. Visibility is the LOG's job.
- */
+/** The totality boundary every serving path shares. */
 function totalFetch(handler) {
     return async (req) => {
         try {
@@ -168,30 +258,15 @@ function totalFetch(handler) {
         }
     };
 }
-/**
- * Has upstream middleware already drained the request body?
- *
- * Node's `req` is one-shot, so a body parser mounted ahead of this route consumes it — a property of
- * the Node/Fetch seam, not of this adapter. What is avoidable is the diagnosis: undici answers
- * `TypeError: Body is unusable`, naming neither the cause nor the fix, and for a webhook channel
- * that reads as "the integration is broken and the platform keeps retrying".
- *
- * Answers only when CERTAIN — a positive `content-length`. `readableEnded` alone is true for any
- * request something upstream merely touched, and an empty chunked body is legal, arrives drained,
- * and is indistinguishable from an eaten one. Guessing there rejects valid requests, making this
- * guard the outage it explains.
- */
+/** Has upstream middleware already drained the request body? */
 function bodyAlreadyRead(req) {
     const length = Number(req.headers["content-length"]);
     return Number.isFinite(length) && length > 0 && req.readableEnded;
 }
-/** The node:http adapter for a Fetch handler — the embedded server uses it, and an embedder mounting
- *  fastagent on its OWN node:http server can too.
- *
- *  Takes the same {@link ChannelHandler} `serveNode` does, so both doors accept the same thing: a
- *  handler may answer synchronously, and `router()` returns exactly that. Requiring a Promise here
- *  made the most natural mount — `nodeListener(router(routes))`, the whole agent on the app's own
- *  server — a type error. */
+/**
+ * The node:http adapter for a Fetch handler — the embedded server uses it, and an embedder mounting fastagent on its
+ * OWN node:http server can too.
+ */
 export function nodeListener(handler) {
     const listener = getRequestListener(totalFetch(handler), { overrideGlobalObjects: false });
     return (req, res) => {
@@ -206,12 +281,6 @@ export function nodeListener(handler) {
         listener(req, res);
     };
 }
-/**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
- * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
- * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
- * `host` is the bind address; unset means all interfaces (what containers need).
- */
 export function serveNode(handler, options) {
     let onListening;
     let onBindError;
@@ -219,20 +288,15 @@ export function serveNode(handler, options) {
         onListening = resolve;
         onBindError = reject;
     });
-    // serve() types its return as the union of every server it CAN build (incl. http2). We never pass
-    // a createServer/http2 option, so it is always node:http's Server — the one carrying
-    // closeAllConnections, which the caller-owned force-close depends on.
+    // serve() types its return as the union of every server it CAN build (incl. http2).
     const server = serve({
         fetch: totalFetch(handler),
         overrideGlobalObjects: false,
         port: options.port,
         ...(options.host !== undefined ? { hostname: options.host } : {}),
     }, (info) => {
-        // Detach before resolving: this listener answers the BIND, and leaving it attached would let
-        // a later runtime error call reject() on a settled promise — swallowed, with nothing raised
-        // anywhere. Detached, an error after bind is an unhandled 'error' event, which is loud.
-        // (Not reachable from a test without forging an event on a server this function does not
-        // expose; the bind-failure half below is covered.)
+        // Detach before resolving: this listener answers the BIND, and leaving it attached would let a later runtime
+        // error call reject() on a settled promise.
         server.off("error", onBindError);
         onListening(info.port);
     });

package/dist/channels/slack/config-api.d.ts

@@ -10,37 +10,16 @@ interface SlackErrorShape {
 export declare class SlackConfigApiError extends Error {
     readonly code: string;
     readonly status: number;
-    /** Kept, not just formatted into the message: which FIELD Slack rejected is how a caller tells a
-     *  not-yet-reachable URL from a malformed one, and a message match cannot see the difference. */
+    /** Kept, not just formatted into the message. */
     readonly errors: {
         message?: string;
         pointer?: string;
     }[];
     constructor(method: string, status: number, data: SlackErrorShape, fallback: string);
 }
-/**
- * Whether a manifest call failed because Slack could not verify the `request_url` it carries — the
- * platform's own readiness verdict on a freshly minted public URL, and the reason no local `/health`
- * poll precedes these calls (#421). Slack validates the manifest BEFORE acting on it, so a call that
- * ends here changed nothing and is safe to repeat.
- *
- * Read from the rejected FIELD (`invalid_manifest` + {@link rejectsRequestUrl}), not from `request_url`
- * appearing anywhere in the formatted string: that also matched errors which merely mention the field.
- *
- * KNOWN IMPRECISION: this cannot separate "not reachable yet" from "this URL is unacceptable" — both
- * arrive the same way, and the wording that would tell them apart has not been observed against the
- * real API, so guessing at it would risk never retrying at all. A permanently bad URL therefore costs
- * the full budget before it is reported. Every URL here is a tunnel's or a host's, so it is well-formed
- * https by construction; narrow this the day a real rejection is captured.
- */
+/** Whether a manifest call failed because Slack could not verify the `request_url` it carries. */
 export declare function isSlackRequestUrlUnverified(error: unknown): boolean;
-/**
- * Whether a manifest write was refused because the app has token rotation on, which Slack never lets
- * off again — the refusal every app created by a release up to 0.20 meets, since this release sends
- * `token_rotation_enabled: false`. Slack documents field rejections as `invalid_manifest` plus an
- * `errors[]` of message + pointer; the bare code was what a real refusal once showed. Both shapes are
- * read: a miss here sends the operator to repair configuration tokens that are not the problem.
- */
+/** Whether a manifest write was refused because the app has token rotation on, which Slack never lets off again. */
 export declare function isSlackRotationLocked(error: unknown): boolean;
 /** The upgrade every rotating-app refusal points at. */
 export declare const SLACK_ROTATING_APP_UPGRADE = "this app has token rotation on, which this release no longer uses and Slack cannot turn off \u2014 create a new app (docs/slack.md \u2192 \"Upgrading from a rotating-token app\")";
@@ -51,9 +30,7 @@ export interface SlackAppCredentials {
     signingSecret: string;
     oauthAuthorizeUrl?: string;
 }
-/** Single-attempt BY DESIGN: an ambiguous response may already have created the app, so this never
- *  retries itself. The one repeatable failure — a `request_url` Slack could not verify, which it
- *  rejects before creating anything — is retried by the caller ({@link isSlackRequestUrlUnverified}). */
+/** Single-attempt BY DESIGN: an ambiguous response may already have created the app, so this never retries itself. */
 export declare function createSlackApp(configToken: string, manifest: SlackAppManifest, options?: {
     apiBaseUrl?: string;
     fetch?: typeof fetch;

package/dist/channels/slack/config-api.js

@@ -1,19 +1,12 @@
 const SLACK_API = "https://slack.com/api";
 const REQUEST_TIMEOUT_MS = 30_000;
-/** One `errors[]` entry that means "Slack could not verify this URL", by either signal it may carry.
- *  The pointer is the precise one but an INFERENCE — the only reply captured from the real API is the
- *  PERMANENT shape error, which reports on the parent pointer (`/settings/event_subscriptions`). If the
- *  unverifiable case reports there too, a pointer-only check would retry zero times and gate the deploy
- *  immediately, which is the failure this whole path exists to prevent. So a message about VERIFICATION
- *  (challenge wording included) counts as well, while one that merely names the field does not — the
- *  captured permanent error says "Event Subscription requires a Request URL". */
+/** One `errors[]` entry that means "Slack could not verify this URL", by either signal it may carry. */
 const rejectsRequestUrl = (e) => e.pointer?.endsWith("/request_url") === true ||
     (/request.?url/i.test(e.message ?? "") && /verif|challenge/i.test(e.message ?? ""));
 export class SlackConfigApiError extends Error {
     code;
     status;
-    /** Kept, not just formatted into the message: which FIELD Slack rejected is how a caller tells a
-     *  not-yet-reachable URL from a malformed one, and a message match cannot see the difference. */
+    /** Kept, not just formatted into the message. */
     errors;
     constructor(method, status, data, fallback) {
         const code = data.error ?? fallback;
@@ -27,31 +20,11 @@ export class SlackConfigApiError extends Error {
         this.errors = data.errors ?? [];
     }
 }
-/**
- * Whether a manifest call failed because Slack could not verify the `request_url` it carries — the
- * platform's own readiness verdict on a freshly minted public URL, and the reason no local `/health`
- * poll precedes these calls (#421). Slack validates the manifest BEFORE acting on it, so a call that
- * ends here changed nothing and is safe to repeat.
- *
- * Read from the rejected FIELD (`invalid_manifest` + {@link rejectsRequestUrl}), not from `request_url`
- * appearing anywhere in the formatted string: that also matched errors which merely mention the field.
- *
- * KNOWN IMPRECISION: this cannot separate "not reachable yet" from "this URL is unacceptable" — both
- * arrive the same way, and the wording that would tell them apart has not been observed against the
- * real API, so guessing at it would risk never retrying at all. A permanently bad URL therefore costs
- * the full budget before it is reported. Every URL here is a tunnel's or a host's, so it is well-formed
- * https by construction; narrow this the day a real rejection is captured.
- */
+/** Whether a manifest call failed because Slack could not verify the `request_url` it carries. */
 export function isSlackRequestUrlUnverified(error) {
     return (error instanceof SlackConfigApiError && error.code === "invalid_manifest" && error.errors.some(rejectsRequestUrl));
 }
-/**
- * Whether a manifest write was refused because the app has token rotation on, which Slack never lets
- * off again — the refusal every app created by a release up to 0.20 meets, since this release sends
- * `token_rotation_enabled: false`. Slack documents field rejections as `invalid_manifest` plus an
- * `errors[]` of message + pointer; the bare code was what a real refusal once showed. Both shapes are
- * read: a miss here sends the operator to repair configuration tokens that are not the problem.
- */
+/** Whether a manifest write was refused because the app has token rotation on, which Slack never lets off again. */
 export function isSlackRotationLocked(error) {
     if (!(error instanceof SlackConfigApiError))
         return false;
@@ -91,9 +64,7 @@ async function slackJson(method, body, options = {}) {
     }
     return data;
 }
-/** Single-attempt BY DESIGN: an ambiguous response may already have created the app, so this never
- *  retries itself. The one repeatable failure — a `request_url` Slack could not verify, which it
- *  rejects before creating anything — is retried by the caller ({@link isSlackRequestUrlUnverified}). */
+/** Single-attempt BY DESIGN: an ambiguous response may already have created the app, so this never retries itself. */
 export async function createSlackApp(configToken, manifest, options = {}) {
     const data = await slackJson("apps.manifest.create", { manifest: JSON.stringify(manifest) }, { ...options, token: configToken });
     const credentials = data.credentials;

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

@@ -1,7 +1,6 @@
 /**
- * Slack's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts):
- * the entry shape, its fold-line rendering, and buffered-file selection. Durable, bounded
- * unsummoned Slack discussion folded into the next answered turn in the same place.
+ * Slack's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts): the entry shape,
+ * its fold-line rendering, and buffered-file selection.
  */
 import { type ContextBuffer } from "../kit/context-buffer.ts";
 export interface SlackBufferEntry {

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

@@ -1,9 +1,8 @@
 /**
- * Slack's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts):
- * the entry shape, its fold-line rendering, and buffered-file selection. Durable, bounded
- * unsummoned Slack discussion folded into the next answered turn in the same place.
+ * Slack's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts): the entry shape,
+ * its fold-line rendering, and buffered-file selection.
  */
-import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
+import { capBufferedRefs, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `thread root ${entry.replyTo}` : undefined]
         .filter(Boolean)
@@ -21,7 +20,8 @@ export function collectSlackBufferedFiles(consumed, primaryIds) {
             files.push({ id, from: entry.sender, messageId: entry.messageId });
         }
     }
-    return { files: files.slice(-BUFFER_ATTACH_MAX), skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) };
+    const capped = capBufferedRefs(files);
+    return { files: capped.kept, skipped: capped.skipped };
 }
 function isEntry(value) {
     const entry = value;

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

@@ -1,5 +1,7 @@
 /** Resolve Slack file IDs at dequeue, then stream one engine-neutral Agent turn. */
 import type { Agent, AgentEvent } from "../../agent.ts";
+import type * as Stream from "effect/Stream";
+import type { PortFailure } from "../../effect-port.ts";
 import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { SlackBufferedFileRef } from "./context-buffer.ts";
 import { type SlackApi } from "./slack-api.ts";
@@ -16,4 +18,4 @@ export interface SlackTurnAttachments {
         skipped: number;
     };
 }
-export declare function invokeSlackTurn(agent: Agent, session: string, text: string, transport: SlackTurnTransport, attachments: SlackTurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;
+export declare function slackTurnStream(agent: Agent, session: string, text: string, transport: SlackTurnTransport, attachments: SlackTurnAttachments, busyRetry?: BusyRetry): Stream.Stream<AgentEvent, PortFailure>;

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

@@ -1,5 +1,4 @@
-import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/invoke-turn-kit.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, loadBackground, missingAttachmentsNote, turnStream, } from "../kit/invoke-turn-kit.js";
 import { SlackApiError } from "./slack-api.js";
 const MARKDOWN_INSTRUCTION = "\n\n(Format your reply as standard Markdown. Slack renders it natively. Do not use HTML or Slack control-mention syntax such as <!here>, <!channel>, or <!everyone>.)";
 async function resolveFile(transport, fileId) {
@@ -20,25 +19,17 @@ async function resolveInputs(transport, attachments) {
     }
     const backgroundImages = [];
     const backgroundFiles = [];
-    let lost = 0;
-    const results = await Promise.allSettled(attachments.buffered.files.map(async (ref) => ({
-        ref,
-        resolved: await resolveFile(transport, ref.id),
-    })));
-    for (const result of results) {
-        if (result.status === "fulfilled") {
-            const { ref, resolved } = result.value;
-            if (resolved.image)
-                backgroundImages.push({ image: resolved.image, ref });
-            if (resolved.file)
-                backgroundFiles.push({ file: resolved.file, ref });
-        }
-        else {
-            lost++;
-            log.warn(`${transport.label} could not load an earlier (buffered) Slack file: ${String(result.reason)}`);
-        }
+    const background = await loadBackground(attachments.buffered.files, (ref) => resolveFile(transport, ref.id), {
+        label: transport.label,
+        what: "Slack file",
+    });
+    for (const { ref, value } of background.loaded) {
+        if (value.image)
+            backgroundImages.push({ image: value.image, ref });
+        if (value.file)
+            backgroundFiles.push({ file: value.file, ref });
     }
-    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const missingNote = missingAttachmentsNote(background.lost + attachments.buffered.skipped);
     const imageManifest = backgroundImagesManifest(images.length, backgroundImages.map(({ ref }) => ref));
     const allFiles = [
         ...files,
@@ -53,18 +44,18 @@ async function resolveInputs(transport, attachments) {
         promptSuffix: `${missingNote}${imageManifest}${attachedFilesManifest(allFiles)}`,
     };
 }
-export async function* invokeSlackTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
-    let resolved;
-    try {
-        resolved = await resolveInputs(transport, attachments);
-    }
-    catch (error) {
-        // transient (network, exhausted 429 retries, Slack 5xx) is worth re-sending; an access or shape
-        // error reads the same every time, and "try again in a moment" is the wrong thing to tell the user
-        const retryable = error instanceof SlackApiError && (error.status === 0 || error.status === 429 || error.status >= 500);
-        yield { type: "failed", details: `could not load Slack attachment: ${String(error)}`, retryable };
-        return;
-    }
-    const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, { session }, prompt, { label: transport.label, onCompleted, busyRetry });
+export function slackTurnStream(agent, session, text, transport, attachments, busyRetry = DEFAULT_BUSY_RETRY) {
+    return turnStream({
+        agent,
+        label: transport.label,
+        busyRetry,
+        resolve: () => resolveInputs(transport, attachments),
+        turn: (resolved) => ({
+            scope: { session },
+            prompt: { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images },
+        }),
+        // Slack says which failures are transient; anything else (a deleted file, a missing scope) will
+        // fail the same way on redelivery.
+        retryableLoadFailure: (cause) => cause instanceof SlackApiError && (cause.status === 0 || cause.status === 429 || cause.status >= 500),
+    });
 }

package/dist/channels/slack/manifest.js

@@ -64,9 +64,7 @@ export function buildSlackManifest(input) {
             org_deploy_enabled: false,
             socket_mode_enabled: false,
             // Off, and Slack makes the alternative permanent: an app with rotation on can never turn it off
-            // (`cannot_disable_once_enabled`, verified against the API). Rotation would ship the refresh token
-            // and the client secret to every host beside the access token — the same blast radius as one
-            // long-lived bot token, plus a 12-hour refresh lineage to keep single and durable.
+            // (`cannot_disable_once_enabled`, verified against the API).
             token_rotation_enabled: false,
         },
     };