@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/cli/serve.js

@@ -1,4 +1,14 @@
-import { createInvokeHandler } from "../channels/http.js";
+/**
+ * The serving spine shared by `dev` (its worker) and `start`: channel assembly, Node HTTP binding,
+ * long-connection lifecycle, scheduler lifecycle, and the optional Cloudflare quick tunnel.
+ */
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createStateSync } from "../channels/agentcore-state.js";
+import { agentcoreRoutes, UnknownScheduleError } from "../channels/agentcore.js";
+import { activeWork } from "../channels/busy.js";
+import { controlRoutes } from "../channels/control.js";
+import { INVOKE_EXAMPLE_BODY, createInvokeHandler } from "../channels/http.js";
 import { text } from "../channels/respond.js";
 import { loadChannels } from "../engines/pi/channel.js";
 import { reportModuleLoadFailures } from "../engines/pi/report.js";
@@ -6,15 +16,19 @@ import { parseRouteKey, router, serveNode } from "../host/node.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { loadSchedules } from "../schedule/discover.js";
-import { createScheduler } from "../schedule/scheduler.js";
+import { createScheduler, fireScheduleOnce } from "../schedule/scheduler.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup } from "./fail.js";
 /**
- * The routes this deployment serves: a default `GET /health` plus the workspace's discovered
- * `channels/` — or the default invoke channel at POST /invoke when none are declared.
+ * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
+ * POST `/invoke` only when neither a route nor a long-connection channel was declared.
  */
-export async function routesFor(workspaceDir, agent, stateRoot) {
-    const { routes, collisions, failures } = await loadChannels(workspaceDir, { agent, stateRoot });
+export async function routesFor(agentDir, agent, stateRoot, control, options = {}) {
+    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
+        agent,
+        stateRoot,
+        control,
+    });
     for (const c of collisions) {
         console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
     }
@@ -23,68 +37,259 @@ export async function routesFor(workspaceDir, agent, stateRoot) {
         throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
             `fix it, or rename an intentionally disabled file to *.disabled`);
     }
-    const channels = Object.keys(routes).length > 0 ? routes : { "POST /invoke": createInvokeHandler(agent) };
-    // Add a default GET /health unless a channel already covers it (overlap, not exact-key: an
-    // any-method `/health` also handles GET, so the built-in steps aside).
-    const healthCovered = Object.keys(channels).some((k) => {
-        const e = parseRouteKey(k);
-        return e.path === "/health" && (e.method === undefined || e.method === "GET");
+    const builtinInvoke = options.builtinInvoke !== false && Object.keys(routes).length === 0 && longConnections.length === 0;
+    const channels = builtinInvoke ? { "POST /invoke": createInvokeHandler(agent) } : routes;
+    const healthCovered = Object.keys(channels).some((key) => {
+        const entry = parseRouteKey(key);
+        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
     });
-    return healthCovered ? channels : { "GET /health": () => text("ok\n", 200), ...channels };
+    let ready = longConnections.length === 0;
+    const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
+    return {
+        routes: healthCovered ? channels : { "GET /health": health, ...channels },
+        longConnections,
+        routeChannels,
+        builtinInvoke,
+        markReady() {
+            ready = true;
+        },
+    };
+}
+/**
+ * Mount the session control plane (`/control/*`) when the agent enabled it
+ * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
+ * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
+ * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
+ * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
+ * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
+ * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
+ * and silently shadowing either side would serve a surface the author didn't write.
+ */
+export function mountSessionControl(routes, control, stateRoot, options = {}) {
+    if (!control)
+        return { routes, announce: () => { } };
+    const token = crypto.randomUUID();
+    const mounted = controlRoutes(control, { token, agent: options.agent });
+    // PATH-level collision, matching the router's semantics (an any-method "/control/dispatch"
+    // channel key would dodge an exact-key check yet still shadow the method-qualified control
+    // route at match time — the router matches by path first).
+    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
+    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
+    if (collisions.length > 0) {
+        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control plane — ` +
+            `rename the channel route or disable sessionControl in fastagent.config`);
+    }
+    return {
+        routes: { ...routes, ...mounted },
+        announce: (boundPort) => {
+            // The state root normally exists (the opener mkdirs the sessions dir under it), but an
+            // external --sessions-dir leaves it uncreated — and announce runs inside serve's listening
+            // callback, where a throw is an unhandled rejection, not a one-line startup diagnostic.
+            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+            const path = join(stateRoot, "control.json");
+            // Atomic (tmp+rename, the state.ts pattern): attach re-reads this file exactly during the
+            // restart window — a torn read would be misdiagnosed as "serve gone".
+            const tmp = `${path}.tmp`;
+            writeFileSync(tmp, `${JSON.stringify({ url: `http://127.0.0.1:${boundPort}`, token })}\n`, { mode: 0o600 });
+            chmodSync(tmp, 0o600); // an existing file keeps its old mode on rewrite — pin it
+            renameSync(tmp, path);
+            log.info(`[fastagent] session control on /control/* (token in ${path})`);
+            // The serve binds ALL interfaces (containers require it), so /control/* is 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.
+            log.warn("[fastagent] the port binds all interfaces: /control/* is reachable on your LAN, protected only by " +
+                "the bearer token — firewall the port or wrap it for real exposure (docs: design §14)");
+            if (options.tunnel) {
+                // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC
+                // (beyond even the LAN reach the mount already warned about). The operator asked for the tunnel (webhooks), but must not DISCOVER the control
+                // plane went public with it — say it loudly.
+                log.warn("[fastagent] --tunnel exposes /control/* (steer/abort/set_model) at the public tunnel URL, " +
+                    "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs: design §14)");
+            }
+            // Best-effort lifecycle end: a clean exit removes the discovery file so a later `attach`
+            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
+            const unlink = () => {
+                try {
+                    rmSync(path, { force: true });
+                }
+                catch {
+                    /* the file is advisory — exit must not fail on it */
+                }
+            };
+            // Signal handlers MUST NOT absorb termination: registering any listener disables Node's
+            // default kill, so clean up and RE-RAISE. The mechanism: `process.kill` delivery is ASYNC —
+            // it lands after the current emit completes, so every listener of this same emit (scheduler
+            // stop, tunnel close — regardless of registration order) runs first, and the re-raised
+            // signal then hits the default action because each `once` handler is already consumed. When
+            // some listener exits the process itself (the tunnel path calls process.exit(0)), the
+            // re-raise is harmless redundancy. Without this, the first Ctrl+C would leave the serve
+            // alive minus its control.json, and dev's watch restart (SIGTERM → wait for exit → respawn)
+            // would hang on a worker that never exits.
+            const unlinkAndReraise = (signal) => () => {
+                unlink();
+                process.kill(process.pid, signal);
+            };
+            process.once("SIGINT", unlinkAndReraise("SIGINT"));
+            process.once("SIGTERM", unlinkAndReraise("SIGTERM"));
+            process.once("exit", unlink);
+        },
+    };
 }
-/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
-export function serve(routes, port, onListening) {
-    serveNode(router(routes), { port }).listening.then((boundPort) => {
-        process.send?.({ type: "ready", port: boundPort }); // tell the dev supervisor we bound + on which port
-        log.info(`[fastagent] http channel on :${boundPort}`);
-        log.info(`[fastagent] routes: ${Object.keys(routes).join(", ") || "(none)"}`);
-        onListening?.(boundPort);
+/**
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
+ * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
+ * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
+ * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
+ * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
+ */
+export function mountAgentcore(routes, options) {
+    const { agent, stateRoot, schedules, onStateReady } = options;
+    const mounted = agentcoreRoutes({
+        routes,
+        agent,
+        stateRoot,
+        isBusy: () => activeWork() > 0,
+        // Cross-deploy durability: AgentCore wipes the state mount on every runtime version update, so
+        // the state root is restored from (and pushed to) an S3 snapshot through presigned URLs the
+        // forwarder mints per envelope. Always wired on this path — the platform gives no other way to
+        // keep an agent's memory across a deploy.
+        stateSync: createStateSync({ stateRoot }),
+        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call. Absent =
+        // no forwarder in this topology, so only the public `invoke` kind is servable.
+        ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
+        onStateReady,
+        fire: schedules.length === 0
+            ? undefined
+            : (name, slot) => {
+                const schedule = schedules.find((s) => s.name === name);
+                if (!schedule)
+                    throw new UnknownScheduleError(name);
+                return fireScheduleOnce({ agent, stateRoot, schedule, slot });
+            },
+    });
+    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
+    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
+    if (collisions.length > 0) {
+        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the AgentCore adapter ` +
+            `(/invocations, /ping) — rename the channel route`);
+    }
+    return { ...routes, ...mounted };
+}
+/**
+ * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
+ * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
+ * the sole clean-shutdown command.
+ */
+export function serve(surface, port, onListening) {
+    const hosted = serveNode(router(surface.routes), { port });
+    const abort = new AbortController();
+    let stopping = false;
+    const stop = (exitCode) => {
+        if (stopping)
+            return;
+        stopping = true;
+        abort.abort();
+        const deadline = setTimeout(() => process.exit(exitCode), 1_000);
+        void hosted
+            .close()
+            .catch(() => { })
+            .finally(() => {
+            clearTimeout(deadline);
+            process.exit(exitCode);
+        });
+        // Preserve the existing no-drain shutdown contract: stop accepting first, then cut active streams.
+        hosted.closeAllConnections();
+    };
+    process.once("SIGINT", () => stop(0));
+    process.once("SIGTERM", () => stop(0));
+    hosted.listening.then(async (boundPort) => {
+        try {
+            const runs = surface.longConnections.map((connection) => {
+                const run = connection.connect(abort.signal);
+                if (run === null ||
+                    typeof run !== "object" ||
+                    typeof run.ready?.then !== "function" ||
+                    typeof run.closed?.then !== "function") {
+                    throw new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`);
+                }
+                void run.closed.then(() => {
+                    if (!abort.signal.aborted)
+                        failStartup(new Error(`${connection.name} closed unexpectedly`));
+                }, (error) => {
+                    if (!abort.signal.aborted)
+                        failStartup(new Error(`${connection.name} failed: ${String(error)}`));
+                });
+                return { connection, run };
+            });
+            await Promise.all(runs.map(async ({ connection, run }) => {
+                await run.ready;
+                if (!abort.signal.aborted)
+                    log.info(`[fastagent] long connection ready: ${connection.name}`);
+            }));
+            // Shutdown raced startup: a pre-ready abort settles `ready` as cancellation, not readiness —
+            // stop() already owns the exit; don't mark ready or report a surface being torn down.
+            if (abort.signal.aborted)
+                return;
+            surface.markReady();
+            process.send?.({
+                type: "ready",
+                port: boundPort,
+                routeChannels: surface.routeChannels,
+            });
+            log.info(`[fastagent] http host on :${boundPort}`);
+            log.info(`[fastagent] routes: ${Object.keys(surface.routes).join(", ") || "(none)"}`);
+            if (surface.longConnections.length > 0) {
+                log.info(`[fastagent] long connections: ${surface.longConnections.map((connection) => connection.name).join(", ")}`);
+            }
+            if (surface.builtinInvoke) {
+                log.info(`[fastagent] try it: curl -s localhost:${boundPort}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
+            }
+            onListening?.(boundPort);
+        }
+        catch (error) {
+            abort.abort();
+            const closing = hosted.close().catch(() => { });
+            hosted.closeAllConnections();
+            await closing;
+            failStartup(error);
+        }
     }, (error) => {
         if (error.code === "EADDRINUSE")
             failStartup(new Error(`port ${port} is already in use; choose another with --port`));
         failStartup(new Error(`cannot bind http channel on :${port}: ${error.message}`));
     });
 }
-/**
- * Start a Cloudflare tunnel + announce/register webhooks once the server is bound — unless this is a
- * watch-supervisor worker, where the supervisor owns the long-lived tunnel so the public URL survives
- * reloads.
- */
-export function maybeTunnel(workspaceDir, boundPort, tunnel) {
+/** Start a Cloudflare tunnel for route channels only. */
+export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
-    void startCloudflareTunnel(boundPort).then((t) => {
-        if (!t)
+    void startCloudflareTunnel(boundPort).then((instance) => {
+        if (!instance)
             return;
-        void announceWebhooks(workspaceDir, t.url, { openUrl: openExternalUrl });
-        // Single-process (start / --no-watch): close the tunnel on exit (watch mode's supervisor owns its own).
-        const cleanup = () => {
-            t.close();
-            process.exit(0);
-        };
+        void announceWebhooks(agentDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);
     });
 }
 /**
- * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on (the scheduler also polls the agent's self-scheduled
- * wake-ups, which the built-in `wake` tool creates only when opted in). Shares the SAME (trace-wrapped)
- * agent the routes serve, so a scheduled turn is observed like any other. Best-effort stop on exit; dev's
- * watch restart re-reads schedules with the worker (schedules are a code input). Single-process.
+ * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals. Returns the
+ * loaded schedules so a serving surface that needs them (the AgentCore adapter's fire binding) shares
+ * ONE load instead of re-discovering. `externalClock` (AgentCore) arms no resident cron timers.
  */
-export async function startSchedules(workspaceDir, agent, stateRoot, selfSchedule) {
-    const { schedules, failures } = await loadSchedules(workspaceDir).catch(failStartup);
+export async function startSchedules(agentDir, agent, stateRoot, selfSchedule, options = {}) {
+    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
     reportModuleLoadFailures(failures);
-    // Nothing to run when there are neither static `schedules/` nor self-scheduling (the `wake` tool, and
-    // thus any wake-up to poll, is mounted only when config.selfSchedule is on) — skip the poller entirely.
     if (schedules.length === 0 && !selfSchedule)
-        return;
-    const scheduler = createScheduler({ agent, stateRoot, schedules });
+        return schedules;
+    const scheduler = createScheduler({ agent, stateRoot, schedules, externalClock: options.externalClock });
     scheduler.start();
-    if (schedules.length > 0)
-        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    if (schedules.length > 0) {
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
+    }
     const stop = () => scheduler.stop();
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
+    return schedules;
 }

package/dist/cli/shared.d.ts

@@ -1,3 +1,16 @@
+import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
+/**
+ * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
+ * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
+ * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
+ * policy (pad, never hand-space), not a constant.
+ */
+export declare function reportLine(label: string, value: string): void;
+/** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
+ *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
+ *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
+export declare function reportWorkspaceHint(hint: string | undefined): void;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
 /**
@@ -10,15 +23,35 @@ export declare function parsePort(value: string | undefined, source: string, fro
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
 /**
- * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
- * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
- * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
- * configured it stays silent and lets the opener raise its clear "missing model" error. The pick is
- * exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it, and best-effort written back to
- * the config so the next run is quiet.
+ * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
+ * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL
+ * catalog annotated per provider — ready (with the credential source, so which account pays is
+ * visible at the decision point) or login-required — and, when the choice needs auth, run the login
+ * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
+ * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
+ * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
+ * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
+ * and best-effort written back to the config so the next run is quiet. `agentDir` is the resolved
+ * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
  */
-export declare function resolveFirstRunModel(workspaceDir: string, options?: {
+export declare function resolveFirstRunModel(agentDir: string, options?: {
     model?: string;
     authPath?: string;
     input?: boolean;
 }): 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>;