@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/channels/serve.js

@@ -1,256 +1,22 @@
-/**
- * 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";
+/** The server a Fetch handler is served on, behind the totality boundary every serving path shares. */
+import { createServer } from "node:http";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+import { HttpEffect, HttpServer, HttpServerError } from "effect/http";
+import { LIMITS } from "../agent-api.js";
 import { log } from "../log.js";
-import { refuseNonJsonBody } from "./body.js";
 import { text } from "./respond.js";
-/** 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. */
-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`).
-    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? */
-export function routeKeysConflict(a, b) {
-    const ka = parseRouteKey(a);
-    const kb = parseRouteKey(b);
-    if (ka.path !== kb.path)
-        return false;
-    return ka.method === undefined || kb.method === undefined || ka.method === kb.method;
-}
-/** 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 });
-}
-export function pathUnderPrefix(path, prefix) {
-    return path === prefix || path.startsWith(`${prefix}/`);
-}
-/**
- * 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.
- *
- * 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.
- *
- * `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.
- */
-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 === "/") {
-            throw new Error(`mount prefix "/" is invalid — a handler owning every path IS that handler; serve it directly`);
-        }
-        if (mount.prefix.endsWith("/")) {
-            throw new Error(`mount prefix "${mount.prefix}" is invalid — no trailing slash (write "/control")`);
-        }
-        const clash = mounts
-            .slice(0, i)
-            .find((other) => pathUnderPrefix(mount.prefix, other.prefix) || pathUnderPrefix(other.prefix, mount.prefix));
-        if (clash) {
-            throw new Error(`mount "${mount.prefix}" overlaps "${clash.prefix}" — one of them would never receive a request`);
-        }
-    }
-    const byKey = new Map();
-    const paths = new Set();
-    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) {
-            if (pathUnderPrefix(path, mount.prefix)) {
-                throw new Error(`route "${key}" is inside the mount "${mount.prefix}" — it would never receive a request`);
-            }
-        }
-        const shadowed = [...byKey.keys()].find((other) => routeKeysConflict(other, key));
-        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.
-        const { method } = parseRouteKey(key);
-        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);
-            const exact = byKey.get(`${req.method} ${path}`) ?? byKey.get(path);
-            if (exact)
-                return exact(req);
-            if (req.method === "HEAD") {
-                const get = byKey.get(`GET ${path}`);
-                if (get)
-                    return get(req);
-            }
-            return paths.has(path) ? text("method not allowed\n", 405) : text("not found\n", 404);
-        };
-        /**
-         * 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();
-        return res instanceof Promise ? res.then(finish) : finish(res);
-    };
-}
-/** The totality boundary every serving path shares. */
-function totalFetch(handler) {
+/** The totality boundary every serving path shares; `prepare` shapes the handler's response inside it. */
+export function totalFetch(handler, prepare = (response) => response) {
     return async (req) => {
         try {
             const response = await handler(req);
             if (!(response instanceof Response))
                 throw new TypeError("handler did not return a Response");
-            return response;
+            return prepare(response);
         }
         catch (error) {
             log.error(`[serve] request failed: ${String(error)}`);
@@ -258,50 +24,102 @@ function totalFetch(handler) {
         }
     };
 }
-/** 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.
+ * A response whose body fails mid-flight, said in the log. Once the headers are out the failure can only cut the body
+ * short, and the server this binds to reports nothing of it; the client sees a truncated body and nothing more. A
+ * client that leaves is not a failure: the server cancels the body, which ends the read in progress and calls `left`.
  */
-export function nodeListener(handler) {
-    const listener = getRequestListener(totalFetch(handler), { overrideGlobalObjects: false });
-    return (req, res) => {
-        if (bodyAlreadyRead(req)) {
-            log.error(`[serve] ${req.method} ${req.url}: the request body was already read by upstream middleware ` +
-                `(e.g. express.json()) — mount fastagent BEFORE the body parser, or scope the parser away ` +
-                `from this route. Channels that verify webhook signatures need the RAW body.`);
-            res.writeHead(500, { "content-type": "text/plain" });
-            res.end("internal error\n");
-            return;
-        }
-        listener(req, res);
-    };
-}
-export function serveNode(handler, options) {
-    let onListening;
-    let onBindError;
-    const listening = new Promise((resolve, reject) => {
-        onListening = resolve;
-        onBindError = reject;
+function watchedBody(response, left) {
+    if (response.body === null)
+        return response;
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            let next;
+            try {
+                next = await reader.read();
+            }
+            catch (error) {
+                log.error(`[serve] a response body failed mid-flight: ${String(error)}`);
+                controller.error(error);
+                return;
+            }
+            // Outside the try: when the client left, the read in progress ends `done` on a body already cancelled, and
+            // closing it throws; that is not the body failing.
+            if (next.done)
+                controller.close();
+            else
+                controller.enqueue(next.value);
+        },
+        cancel(reason) {
+            left();
+            return reader.cancel(reason);
+        },
     });
-    // serve() types its return as the union of every server it CAN build (incl. http2).
-    const server = serve({
-        fetch: totalFetch(handler),
-        overrideGlobalObjects: false,
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+const isBun = typeof process.versions.bun === "string";
+/**
+ * How long `close()` gives the requests in flight before it ends them, on either runtime: a webhook is answered in
+ * milliseconds, and a close must fit the CLI's shutdown deadline (`FORCED_EXIT_MS` in `src/cli/serve.ts`).
+ */
+const GRACEFUL_SHUTDOWN = "500 millis";
+/**
+ * How long Bun lets a response say nothing before it ends it (10 s by default): longer than an Agent API request waits
+ * for a message, and than an event stream's keep-alive interval. Node sets no such limit.
+ */
+const BUN_IDLE_TIMEOUT_SECONDS = LIMITS.httpWaitSeconds + 15;
+/** The server this runtime serves on: Node's `http.Server`, or `Bun.serve`. */
+async function serverLayer(options) {
+    if (isBun) {
+        const { layer } = await import("@effect/platform-bun/BunHttpServer");
+        return layer({
+            port: options.port,
+            ...(options.host === undefined ? {} : { hostname: options.host }),
+            gracefulShutdownTimeout: GRACEFUL_SHUTDOWN,
+            idleTimeout: BUN_IDLE_TIMEOUT_SECONDS,
+        });
+    }
+    const { layer } = await import("@effect/platform-node/NodeHttpServer");
+    return layer(() => createServer(), {
         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.
-        server.off("error", onBindError);
-        onListening(info.port);
+        ...(options.host === undefined ? {} : { host: options.host }),
+        gracefulShutdownTimeout: GRACEFUL_SHUTDOWN,
+    });
+}
+/** A bind that failed, as the error its runtime raised (`EADDRINUSE` and the like), not Effect's wrapper of it. */
+function bindFailure(error) {
+    return error instanceof HttpServerError.ServeError ? error.cause : error;
+}
+/** Serve `handler` on this runtime's own server: Node's `http.Server`, or `Bun.serve`. */
+export function serveHandler(handler, options) {
+    const scope = Scope.makeUnsafe();
+    let closed = false;
+    // A server runs each request uninterruptibly unless told otherwise; a request that has not answered when the server
+    // closes must be interruptible, or closing waits on it forever.
+    const app = Effect.interruptible(HttpEffect.fromWebHandler((request) => {
+        // The handler's `signal` follows its client to the end of the response, as a Node server's request does: this
+        // server aborts it only while the handler runs, so a body cancelled because the client left aborts it too.
+        const left = new AbortController();
+        const followed = new Request(request, { signal: AbortSignal.any([request.signal, left.signal]) });
+        return totalFetch(handler, (response) => watchedBody(response, () => left.abort()))(followed);
+    }));
+    const listening = serverLayer(options)
+        .then((server) => {
+        if (closed)
+            throw new Error("the server was closed before it listened");
+        return Effect.runPromise(Layer.buildWithScope(HttpServer.serve(app).pipe(Layer.provideMerge(server)), scope));
+    })
+        .then((context) => Context.get(context, HttpServer.HttpServer).address.port, (error) => {
+        throw bindFailure(error);
     });
-    server.once("error", onBindError); // a bind failure surfaces here, before "listening"
-    const close = () => new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
-    const closeAllConnections = () => server.closeAllConnections();
-    return { listening, close, closeAllConnections };
+    return {
+        listening,
+        async close() {
+            closed = true;
+            // A bind in progress finishes first, so what it bound is released here; how it ended is `listening`'s to say.
+            await listening.then(() => undefined, () => undefined);
+            await Effect.runPromise(Scope.close(scope, Exit.void));
+        },
+    };
 }

package/dist/channels/slack/history.d.ts

@@ -0,0 +1,42 @@
+import { type PlaceDiscussion, type PlaceHistory, type PlaceMessage, type PlaceRead } from "../kit/place-history.ts";
+import { type SlackApi } from "./slack-api.ts";
+export type SlackPlaceRead = PlaceRead<string>;
+export type SlackDiscussion = PlaceDiscussion<string>;
+export interface SlackPlaceHistory extends PlaceHistory<string> {
+    /** The channel's threads among its newest messages, for a tool (`kit/room-threads.ts`); `room` is its place key. */
+    threads(room: string): Promise<string>;
+}
+/** A background file carried into a turn, with attribution for its prompt manifest. */
+export interface SlackBufferedFileRef {
+    id: string;
+    from: string;
+    messageId: string;
+}
+/** A place: a channel's top level, or a thread in it. The turn record carries it as this key. */
+export declare function slackHistoryKey(teamId: string, place: {
+    channelId: string;
+    threadTs?: string;
+}): string;
+/** The inverse of {@link slackHistoryKey}. Slack ids and timestamps never contain a colon. */
+export declare function slackPlaceOf(key: string): {
+    teamId: string;
+    channelId: string;
+    threadTs?: string;
+};
+/** Select the most recent background files of the folded messages, excluding the turn's own. */
+export declare function collectFoldedFiles(folded: readonly PlaceMessage[], primaryIds: ReadonlySet<string>): {
+    files: SlackBufferedFileRef[];
+    skipped: number;
+};
+export declare function createSlackPlaceHistory(deps: {
+    api: Pick<SlackApi, "channelHistory" | "threadReplies" | "userName">;
+    /** THIS app's bot user and bot ids, once `auth.test` answered: a message from either is the agent's own. */
+    self(): {
+        userId?: string;
+        botId?: string;
+    };
+    label: string;
+    /** Where each place's cursor and outputs persist. */
+    path: string;
+    isTurnInput(key: string, ts: string): boolean;
+}): SlackPlaceHistory;