@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/cli/serve.js

@@ -1,53 +1,35 @@
-/**
- * What `dev` (its worker) and `start` need beyond the service itself: binding a port, the shutdown
- * order, the startup report, the optional Cloudflare quick tunnel, and the options the CLI hands the
- * assembly (`cliMountOptions`, `resolveBindHost` — policy ABOUT the assembly, decided per command).
- *
- * The ASSEMBLY itself is not here — it lives in `src/service.ts`, which a public entry may import and
- * this directory may not be (it decides process-level things: `fail.ts` calls `process.exit`).
- */
-import { mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+/** What `dev` (its worker) and `start` need beyond the service itself. */
 import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
-import { answersLocalhost, bindAddress, bindLabel, classifyBind, clientHost } from "../bind.js";
-import { writeFileAtomic } from "../atomic-write.js";
+import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
+import { describeAnonymousSurface, } from "../service.js";
 import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { declaredChannels } from "../channels/discover.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup, failUsage } from "./fail.js";
-/**
- * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
- * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
- * `127.0.0.2` bind, loopback though it is — would leave the tunnel up and 502ing every request.
- * Checked BEFORE the bind (the flag alone pre-spawn in `dev`, again once config is loaded, since
- * `http.host` can carry the address), so the failure is clean rather than a live-but-broken public URL.
- * `source` decides the exit code, per fail.ts: a flag COMBINATION is a usage error (2), a value that
- * came from config is broken runtime configuration (1).
- */
-export function assertTunnelBindable(host, tunnel, source) {
+/** Refuse `--tunnel` with a `--bind` that cloudflared cannot reach. */
+export function assertTunnelBindable(host, tunnel) {
     if (!tunnel || answersLocalhost(host))
         return;
-    // Name the source, not just the exit code: under `config` there is no `--bind` to change and no flag
-    // to drop, so flag-only wording would send the reader looking for something they never typed.
-    const fix = source === "flag"
-        ? "bind 0.0.0.0 (or 127.0.0.1), or drop --tunnel"
-        : "set http.host to 0.0.0.0 (or 127.0.0.1) in fastagent.config.*, override it with --bind, or drop --tunnel";
-    const message = `--tunnel reaches the serve by dialing localhost, which the bind address ${host} does not answer — ${fix}`;
-    if (source === "flag")
-        failUsage(message);
-    failStartup(new Error(message));
+    failUsage(`--tunnel reaches the serve by dialing localhost, which the bind address ${host} does not answer — bind 0.0.0.0 (or 127.0.0.1), or drop --tunnel`);
 }
 /**
- * The bind address a serve uses: the flag, else `http.host` from the config — through `bindAddress`,
- * so a configured `localhost` is an ADDRESS by the time anything binds, renders or dials it — checked
- * against `--tunnel` with the exit code the SOURCE of the value earns (serve.ts assertTunnelBindable).
+ * Apply the flags that override what the definition said, for THIS run only.
+ *
+ * ONE place, because `dev` and `start` both do it and a mapping two call sites must each remember is one a third
+ * will not.
+ *
+ * `--no-invoke` outranks `http.invoke`: a config value travels into a deployed image, so "do not publish a turn
+ * endpoint on this tunnel" has to be sayable without editing the definition.
+ *
+ * It takes `POST /run` WITH it, including over a definition that said `http.run: true`. Both routes start a
+ * turn for an anonymous caller, and the flag's whole reason for existing is the case where the definition cannot be
+ * edited — `dev --tunnel --no-invoke` leaving the other one published at the tunnel URL would be the flag failing at
+ * exactly the job it was added for.
  */
-export function resolveBindHost(bindFlag, configured, tunnel) {
-    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
-    assertTunnelBindable(host, tunnel, bindFlag ? "flag" : "config");
-    return host;
+export function withRunOverrides(opened, run) {
+    return run.invoke === false ? { ...opened, http: { ...opened.http, invoke: false, run: false } } : opened;
 }
 /** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
 export function cliMountOptions(wrapAgent) {
@@ -58,111 +40,109 @@ export function cliMountOptions(wrapAgent) {
     };
 }
 /**
- * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the
- * tail dev's worker and start share once the service is assembled.
+ * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the tail dev's worker
+ * and start share once the service is assembled.
  */
 export function serveService(service, bind, posture) {
     const { host } = bind;
     const { tunnel, agentDir, stateRoot } = posture;
-    let unannounce = () => { };
     serve(service.handler, bind, {
         ready: service.ready,
         onListening: (p) => {
             reportServing(service, host, p);
-            unannounce = announceControl(service.control, stateRoot, { host, tunnel }, p);
+            announceControl(service, { host, tunnel });
             maybeTunnel(agentDir, service.channels.routes, p, tunnel, stateRoot);
         },
-        onShutdown: () => {
-            unannounce();
-            return service.close();
-        },
+        onShutdown: () => service.close(),
     });
 }
-/**
- * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
- * what mounted. One function because both commands must say the same thing at the same moment —
- * after readiness, never at socket bind.
- */
+/** The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and what mounted. */
 export function reportServing(service, host, boundPort) {
     process.send?.({ type: "ready", port: boundPort, routeChannels: service.channels.routes });
-    for (const line of readyAddressLines(host, boundPort, service.channels.builtinInvoke))
+    for (const line of readyAddressLines(host, boundPort, service.unverifiedRoutes.includes("POST /invoke"))) {
         log.info(line);
+    }
     log.info(`[fastagent] routes: ${Object.keys(service.routes).join(", ") || "(none)"}`);
     if (service.channels.longConnections.length > 0) {
         log.info(`[fastagent] long connections: ${service.channels.longConnections.join(", ")}`);
     }
 }
+/** The line that names WHERE the serve is — every posture reports it, including AgentCore's own surface. */
+export function bindLine(host, boundPort) {
+    return `[fastagent] http host on ${classifyBind(host) === "wildcard" ? `:${boundPort} (all interfaces)` : bindLabel(host, boundPort)}`;
+}
 /**
- * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
- * ONE function because they are one message — they were two, and `--bind` updated the first while the
- * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
- * neither can be changed without the other in view, and the address has a single derivation.
+ * The startup lines for a serve of OUR surface: the bind report, and the curl the reader copies.
  *
- * A wildcard bind is every interface, and naming one address there would understate it — but the curl
- * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ * `servesInvoke` is `AgentService.unverifiedRoutes`, never a guess from the route table: `http.invoke: false` leaves no
+ * `/invoke` to curl, and a channel may serve that path with a protocol of its own — both would turn this line into
+ * a copyable request that fails.
  */
-export function readyAddressLines(host, boundPort, builtinInvoke) {
+export function readyAddressLines(host, boundPort, servesInvoke) {
     const dial = `${clientHost(host)}:${boundPort}`;
-    const lines = [
-        `[fastagent] http host on ${classifyBind(host) === "wildcard" ? `:${boundPort} (all interfaces)` : bindLabel(host, boundPort)}`,
+    return [
+        bindLine(host, boundPort),
+        ...(servesInvoke
+            ? [
+                `[fastagent] try it: curl -s ${dial}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`,
+            ]
+            : []),
     ];
-    if (builtinInvoke) {
-        lines.push(`[fastagent] try it: curl -s ${dial}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
-    }
-    return lines;
 }
 /**
- * Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the control plane
- * once the port is known, and say what reaches it. Returns the file's removal — wired into the
- * shutdown so a stale file cannot point a client at a dead port (`attach` then fails with "cannot
- * read", accurate, instead of a stale token's misleading 401/ECONNREFUSED). A hard exit leaves the
- * file behind: advisory, overwritten by the next boot.
+ * Say what this port exposes and how far it reaches.
+ *
+ * NOTHING fastagent serves is authenticated — authentication belongs to the deployment (a gateway, a private
+ * network, AgentCore's IAM, an embedder's middleware). Two of the three warnings fire at a REACH the operator did
+ * not get by default: a bind off this machine, and `--tunnel`'s public URL.
  *
- * Here and not in the assembly: the file, its permissions and the warnings are how THIS process's
- * operator finds and protects the plane. An embedder distributes `service.control` itself.
+ * The cross-origin one is UNCONDITIONAL, including on a loopback `dev`, because the grant is. `*` is the default
+ * (`channels/serve.ts`), so a page the developer merely visits can drive this port from their browser and read the
+ * reply, loopback bind or not. Nobody opts into a default, so the one posture the decision costs is the one that
+ * has to hear about it.
+ *
+ * WHAT IS EXPOSED is read off `AgentService.unverifiedRoutes`, never assumed and never guessed from the route table.
+ * `POST /invoke` is on most serves but not all: AgentCore answers the Runtime's `/invocations` behind IAM,
+ * `http.invoke: false` withholds it, and a channel may serve that path itself — in which case the caller it is
+ * open to is the platform that signs its requests, not anyone at all. A warning naming an endpoint this process
+ * does not serve is how an operator learns to skim past all of them — the same reason `preflightDeploy` takes
+ * `publicUrl`.
  */
-export function announceControl(control, stateRoot, bind, boundPort) {
-    if (!control)
-        return () => { };
-    mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
-    const path = join(stateRoot, "control.json");
-    const url = `http://${clientHost(bind.host)}:${boundPort}`;
-    writeFileAtomic(path, `${JSON.stringify({ url, token: control.token })}\n`, 0o600);
-    log.info(`[fastagent] session control on ${control.prefix}/* (token in ${path})`);
-    // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths warn
-    // loudly, and the LAN path must not be the silent third way past the local trust story. A
-    // loopback bind closes exactly that reach, so it earns silence.
+export function announceControl(service, bind) {
+    const { controlPrefix, corsOrigins } = service;
+    if (controlPrefix)
+        log.info(`[fastagent] session control on ${controlPrefix}/*`);
+    // What an unauthenticated caller of this port can do, worst first. From `unverifiedRoutes`, so a channel that serves
+    // `/invoke` itself is not described as our unauthenticated data plane — it has its own signature check.
+    const exposed = describeAnonymousSurface({
+        invoke: service.unverifiedRoutes.includes("POST /invoke"),
+        run: service.unverifiedRoutes.includes("POST /run"),
+        ...(controlPrefix ? { controlPrefix } : {}),
+    });
+    if (exposed.length === 0)
+        return; // nothing of ours answers here (the AgentCore adapter's surface)
+    const what = `${exposed.join(" and ")} ${exposed.length > 1 ? "answer" : "answers"}`;
+    if (corsOrigins === undefined || corsOrigins.includes("*")) {
+        log.warn(`[fastagent] any web page your browser visits can call this serve cross-origin and read the reply: ${what} ` +
+            "with no credential. That is the default (`*`); pin the origins you actually use with http.cors " +
+            "(docs/design/session-control.md §14)");
+    }
     const reach = classifyBind(bind.host);
     if (reach !== "loopback") {
         log.warn(`[fastagent] the port binds ${reach === "wildcard" ? "all interfaces" : `${bind.host} (off this machine)`}: ` +
-            "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
-            "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs/design/session-control.md §14)");
+            `${what} UNAUTHENTICATED to anyone who can reach it — bind loopback (--bind 127.0.0.1), ` +
+            "firewall the port, or front it with a gateway (docs/design/session-control.md §14)");
     }
     if (bind.tunnel) {
-        // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC.
-        log.warn("[fastagent] --tunnel exposes /control/* (steer, stop, rewrite or delete a session) at the public tunnel URL, " +
-            "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs/design/session-control.md §14)");
+        log.warn(`[fastagent] --tunnel publishes this port at a public URL with NO authentication: ${what} to anyone with ` +
+            "that URL — put real auth in front before sharing it (docs/design/session-control.md §14)");
     }
-    return () => {
-        try {
-            rmSync(path, { force: true });
-        }
-        catch {
-            /* the file is advisory — shutdown must not fail on it */
-        }
-    };
 }
-/** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
- *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
+/** What the CLI gives a service to stop in, and the hard exit that follows it. */
 const SHUTDOWN_GRACE_MS = 800;
 const FORCED_EXIT_MS = 1_500;
-/**
- * Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment: a bound
- * socket is not a serving agent while a declared long-connection channel is still dialling, so this
- * awaits `hooks.ready` (mountAgentService owns the connections themselves) before announcing
- * anything. Signals are the sole clean-shutdown command; `host` unset binds all interfaces.
- */
-function serve(handler, bind, hooks = {}) {
+/** Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment. */
+export function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
     const hosted = serveNode(handler, { port, host });
     let stopping = false;
@@ -170,21 +150,15 @@ function serve(handler, bind, hooks = {}) {
         if (stopping)
             return;
         stopping = true;
-        // Bounded: shutdown must not hang on a channel that will not close, so the deadline fires
-        // regardless. No drain — an in-flight turn is cut, which is the existing contract.
-        // Later than the service's own close deadline (SHUTDOWN_GRACE_MS below), or the process leaves
-        // at 0 before `close()` has said a channel would not stop.
+        // Bounded: shutdown must not hang on a channel that will not close, so the deadline fires regardless.
         const deadline = setTimeout(() => {
             log.error(`[fastagent] shutdown did not finish within ${FORCED_EXIT_MS}ms; exiting`);
             process.exit(1);
         }, FORCED_EXIT_MS);
-        // Stop accepting FIRST, before anything is awaited. `onShutdown` waits for long connections to
-        // close, and a socket still listening through that wait would dispatch new work into channels
-        // and a scheduler that are already shutting down.
+        // Stop accepting FIRST, before anything is awaited.
         const closingServer = hosted.close();
         hosted.closeAllConnections();
-        // A cleanup that failed is not a clean exit: `close()` reports a channel that would not stop,
-        // and swallowing it here would end the process at 0 over a resource still holding on.
+        // A cleanup that failed is not a clean exit.
         void Promise.allSettled([closingServer, Promise.resolve(hooks.onShutdown?.())]).then((outcomes) => {
             let code = exitCode;
             for (const outcome of outcomes) {
@@ -201,9 +175,9 @@ function serve(handler, bind, hooks = {}) {
     process.once("SIGTERM", () => stop(0));
     hosted.listening.then(async (boundPort) => {
         try {
-            // A bound socket is NOT a serving agent: a declared socket-mode channel still has to come
-            // up, and reporting ready before it does tells the supervisor (and --tunnel, and the
-            // operator) that a surface is live while a channel is dead.
+            // A bound socket is NOT a serving agent: a declared socket-mode channel still has to come up, and reporting
+            // ready before it does tells the supervisor (and --tunnel, and the operator) that a surface is live while a
+            // channel is dead.
             await hooks.ready;
             if (stopping)
                 return;
@@ -214,13 +188,12 @@ function serve(handler, bind, hooks = {}) {
         }
     }, (error) => {
         if (error.code === "EADDRINUSE") {
-            // With a bind address the port is only taken ON THAT interface, so moving the bind is as valid
-            // a fix as moving the port.
+            // With a bind address the port is only taken ON THAT interface, so moving the bind is as valid a fix as
+            // moving the port.
             failStartup(new Error(`${bindLabel(host, port)} is already in use; choose another with ` +
                 `--port${classifyBind(host) === "wildcard" ? "" : " or --bind"}`));
         }
-        // Through `bindLabel`, like every other message about a bind: hand-concatenating gives `:::8787`
-        // for an IPv6 bind and a bare `:8787` for the wildcard, which reads as an explicit bind of nothing.
+        // Through `bindLabel`, like every other message about a bind.
         failStartup(new Error(`cannot bind http channel on ${bindLabel(host, port)}: ${error.message}`));
     });
 }

package/dist/cli/shared.d.ts

@@ -1,26 +1,19 @@
-import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
+import { type AuthLayers } from "../engines/pi/config.ts";
+import { type LoginIO } from "../engines/pi/login.ts";
 import type { LoadedDefinition } from "../engines/pi/definition.ts";
-import { type ModuleLoadFailure } from "../loader.ts";
 import type { ToolCollision } from "../engines/pi/tool.ts";
-import { type ResolvedPlacement } from "../paths.ts";
-/**
- * How every command that runs the model enters its agent directory, in the one order that works:
- * placement decides whose `.env` to read; `.env` may carry the proxy and the provider keys the
- * picker's auth probe needs; the picker runs last. Six commands wrote these steps out by hand, and
- * one carried the order as a comment. The result is the placement every later step reads.
- */
+import type { ResolvedPlacement } from "../paths.ts";
+/** How every command that runs the model enters its agent directory, in the one order that works. */
 export declare function enterAgentCommand(dirArg: string, opts: {
     model?: string;
-    authPath?: string;
     input?: boolean;
 }): Promise<ResolvedPlacement>;
-/** What the startup report reads off an opened directory — a structural subset of the opener's return,
- *  spelled out so this module does not depend on that function's whole shape. */
+/** What the startup report reads off an opened directory. */
 export interface ReportableAssembly {
     agentDir: string;
     workspace: string;
     modelSpec: string;
-    authPath: string;
+    auth: AuthLayers;
     config: {
         thinkingLevel?: string;
     };
@@ -28,63 +21,24 @@ export interface ReportableAssembly {
     toolNames: string[];
     deferredToolNames: string[];
     toolCollisions: ToolCollision[];
-    toolFailures: ModuleLoadFailure[];
 }
-/**
- * What `dev` and `start` say about the directory they just opened, in the order they say it.
- *
- * ONE function because it is one report: the two commands wrote it out line by line, and the copies
- * had already diverged over which lines exist at all — `dev` naming the config file, `start` naming
- * state and sessions. A line added to one of two hand-written copies is invisible in the other.
- *
- * The divergence itself is PRESERVED, not resolved: `start`'s `state:`/`sessions:` pair introduces the
- * persistence warnings that follow it in production posture, and `dev`'s `config:` has no counterpart
- * there. Both are passed as explicit extras by the caller, so the asymmetry is visible at the call
- * site rather than buried in two copies of a list. Whether it is RIGHT is a separate question from
- * whether it has one owner.
- *
- * Findings (skill collisions, definition diagnostics) CLOSE the report — they are about the assembly
- * just printed. What a command says next is its own posture talk, not report: `start`'s persistence
- * notes now follow them rather than precede them.
- */
+/** What `dev` and `start` say about the directory they just opened, in the order they say it. */
 export declare function reportAssembly(a: ReportableAssembly, extras?: {
-    /** Printed between `workspace:`/`hint:` and `model:` (`dev` names the config file here). */
+    /** Printed between `workspace:` and `model:` (`dev` names the config file here). */
     beforeModel?: [label: string, value: string][];
     /** Printed after the tool lines, before findings (`start` names state + sessions here). */
     afterTools?: [label: string, value: string][];
 }): Promise<void>;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
-/**
- * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
- * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
- * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
- * bad `PORT` env is broken runtime configuration (1).
- */
+/** Parse + range-check a port string (CLI flag or env). */
 export declare function parsePort(value: string | undefined, source: string, from: "flag" | "env"): number | undefined;
 /**
- * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to
- * config, then all interfaces). An unbindable string is a USAGE error (2) — caught here rather than as
- * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
+ * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to config, then
+ * all interfaces).
  */
 export declare function parseBind(value: string | undefined): string | undefined;
-/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking.
- *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
- *  reported like any built-in rather than as an unknown provider. */
-export declare function reportAuth(agentDir: string, modelSpec: string, authPath: string): Promise<void>;
-/**
- * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
- * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the
- * keyboard NOW; parking the failure for a later `fastagent login` would waste that. The loop exits on
- * a verified/unverifiable key (kept), an OAuth login (completing the flow already proved the
- * credential), or cancel (LoginCancelled propagates to the caller's cancel policy). Used by both the
- * `login` command and the first-run picker's inline login.
- */
-export declare function loginWithKeyCheck(provider: string | undefined, authPath: string, spec?: string, seams?: {
-    flow?: (io: LoginIO, options: {
-        provider?: string;
-        authPath?: string;
-        method?: LoginMethod;
-    }) => Promise<LoginResult>;
-    verify?: (provider: string, authPath: string, spec?: string) => Promise<"ok" | "rejected" | "unknown">;
-}): Promise<LoginResult>;
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
+export declare function reportAuth(agentDir: string, modelSpec: string, auth: AuthLayers): Promise<void>;
+/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
+export declare function terminalLoginIO(): LoginIO;