@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/service.js

@@ -1,50 +1,83 @@
-import { CONTROL_TOKEN_ENV, createControlPlane } from "./channels/control.js";
+/** The product, as one call: an agent directory becomes a live service. */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Scope from "effect/Scope";
+import { createControlPlane } from "./channels/control.js";
 import { createInvokeHandler } from "./channels/http.js";
 import { text } from "./channels/respond.js";
-import { parseRouteKey, pathUnderPrefix, router } from "./channels/serve.js";
+import { assertCorsOrigins, parseRouteKey, pathUnderPrefix, router } from "./channels/serve.js";
 import { loadChannels } from "./channels/discover.js";
-import { loadSchedules } from "./schedule/discover.js";
+import { loadRoutines } from "./schedule/discover.js";
+import { createRoutineListHandler, createRunHandler } from "./schedule/run.js";
 import { createScheduler } from "./schedule/scheduler.js";
 import { log } from "./log.js";
-import { reportModuleLoadFailures } from "./loader.js";
-/** Default wait for a channel's `closed` before reporting it stuck. A channel that ignores its
- *  abort signal must not hang a caller's teardown — or, during a failed start, keep the original
- *  error from arriving. The CLI passes a shorter one: its own forced exit must come AFTER this, or
- *  the process leaves at 0 before the failure is known. */
+import { refuseBrokenDeclarations } from "./loader.js";
+import { gateSecrets } from "./secrets-gate.js";
+/** Default wait for a channel's `closed` before reporting it stuck. */
 const CLOSE_DEADLINE_MS = 5_000;
-/** Settle when every connection has closed, or when the deadline passes. Reports the ones that did
- *  NOT settle — named individually, so a single stuck channel is not reported as all of them. */
-async function closeWithin(runs, names, deadlineMs) {
-    const pending = new Set(runs.map((_, i) => i));
-    const failures = [];
-    const tracked = runs.map((run, i) => run.closed.then(() => {
-        pending.delete(i);
-    }, (error) => {
-        pending.delete(i);
-        failures.push(error);
-    }));
-    let timer;
-    try {
-        await Promise.race([
-            Promise.all(tracked),
-            // NOT unref'd: this timer is the thing being awaited, and an unref'd one lets the loop go
-            // idle with nothing left to advance it. Cleared below so a prompt close does not hold the
-            // process for the rest of the deadline.
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, deadlineMs);
-            }),
-        ]);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-    return { stuck: [...pending].map((i) => names[i] ?? "channel"), failures };
+/** One deadline for all connections; a failed close must not hide a sibling that is still running. */
+function closeWithin(runs, names, deadlineMs) {
+    return Effect.gen(function* () {
+        const pending = new Set(runs.map((_, i) => i));
+        const failures = [];
+        yield* Effect.forEach(runs, (run, i) => Effect.tryPromise({ try: () => run.closed, catch: (error) => error }).pipe(Effect.match({
+            onSuccess: () => {
+                pending.delete(i);
+            },
+            onFailure: (error) => {
+                pending.delete(i);
+                failures.push(error);
+            },
+        })), { concurrency: "unbounded", discard: true }).pipe(Effect.timeoutOrElse({ duration: deadlineMs, orElse: () => Effect.void }));
+        if (pending.size > 0) {
+            const stuck = [...pending].map((i) => names[i] ?? "channel");
+            return yield* Effect.fail(new Error(`long connection(s) did not stop within ${deadlineMs}ms: ${stuck.join(", ")}`));
+        }
+        if (failures.length > 0) {
+            return yield* Effect.fail(failures.length === 1 ? failures[0] : new AggregateError(failures, "long connections failed to close"));
+        }
+    });
+}
+/** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
+export const DEFAULT_HTTP_PORT = 8787;
+/**
+ * Does this surface serve `POST /run`, given a routine to run? It FOLLOWS `invoke` unless `run` says otherwise (see
+ * {@link HttpSurface.run}). ONE function because the assembly mounts the route and `preflightDeploy` names it; a
+ * default spelled twice is a default that moves once.
+ */
+export function shouldServeRun(http) {
+    return http?.run ?? http?.invoke !== false;
 }
 /**
- * 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.
+ * What an anonymous caller of a port can do, worst first — the ONE wording the startup report and deploy's pre-flight
+ * both print, each from its own facts (what mounted vs what will mount).
  */
-export async function routesFor(agentDir, agent, stateRoot, control, options = {}) {
+export function describeAnonymousSurface(open) {
+    return [
+        ...(open.invoke ? ["POST /invoke (run a turn with this agent's tools)"] : []),
+        ...(open.run ? ["POST /run (run any routine this agent declares; GET /routines lists them)"] : []),
+        ...(open.controlPrefix ? [`${open.controlPrefix}/* (read, steer or delete any session)`] : []),
+    ];
+}
+/**
+ * The surface this deployment serves: the DATA plane (`POST /invoke`), `GET /health`, and the discovered channels.
+ *
+ * `/invoke` is the framework's interface, so it is served whatever channels a definition declares (unless
+ * `http.invoke: false`). It is RESERVED for the same reason `/control/*` is: a channel taking that path would silently replace the one route every client,
+ * every doc and the startup line all name. `/health` stays overridable — a probe is the deployment's to shape.
+ */
+export async function routesFor(agentDir, agent, stateRoot, control, 
+/**
+ * `http.invoke: false` withholds the data plane. Two callers, two reasons: the AgentCore adapter serves the
+ * Runtime's `/invocations` contract instead, and an author sets it to leave the channels' signature checks as the
+ * only way into a public port.
+ *
+ * `routines` mounts `POST /run` and `GET /routines` (per {@link shouldServeRun}). Passed in rather than loaded here
+ * so the routes and the resident clock cannot disagree about which routines exist (`loadServingRoutines`).
+ */
+options = {}) {
     const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
         agent,
         stateRoot,
@@ -53,40 +86,62 @@ export async function routesFor(agentDir, agent, stateRoot, control, options = {
     for (const c of collisions) {
         log.warn(`[fastagent] channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
     }
-    reportModuleLoadFailures(failures);
-    if (failures.length > 0 || collisions.length > 0) {
-        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`);
+    refuseBrokenDeclarations(failures);
+    if (collisions.length > 0) {
+        throw new Error(`${collisions.length} channel route collision(s) — two channels cannot serve one route`);
     }
-    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) => {
+    /**
+     * Which channel key already serves this path for the method a built-in would answer — the CHANNEL's spelling, not
+     * ours. A channel may write the method-less `"/invoke"`, and an error naming `"POST /invoke"` sends its author
+     * grepping their own file for a string that is not in it.
+     */
+    const covered = (path, method) => Object.keys(routes).find((key) => {
         const entry = parseRouteKey(key);
-        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
+        return entry.path === path && (entry.method === undefined || entry.method === method);
     });
     let ready = longConnections.length === 0;
     const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
+    // AgentCore serves the data plane through the Runtime's own `/invocations` contract, so the adapter opts out — and
+    // with no `/invoke` of ours on that surface there is nothing to reserve, which is why the refusal is in here.
+    const unverified = { ...(covered("/health", "GET") ? {} : { "GET /health": health }) };
+    if (options.http?.invoke !== false)
+        unverified["POST /invoke"] = createInvokeHandler(agent);
+    // `POST /run` exists only where there is something to run, and `GET /routines` exactly where that route does:
+    // it is the catalogue OF that route, so listing names nobody can use would be a catalogue of nothing. Both ride
+    // this table for the reason the table exists: they authenticate nobody, so they inherit the JSON body gate, the
+    // cross-origin policy, the reserved path and the startup report's account of what is open.
+    if (shouldServeRun(options.http)) {
+        const routines = options.routines ?? [];
+        const run = createRunHandler({ agent, routines });
+        if (run)
+            unverified["POST /run"] = run;
+        const list = createRoutineListHandler({ routines });
+        if (list)
+            unverified["GET /routines"] = list;
+    }
+    // ONE rule over the whole table, so the next route we add is reserved by existing here rather than by someone
+    // remembering to write a second check for it. `/health` is exempt by construction: it is only in `ours` when no
+    // channel already serves it, because a probe is the deployment's to shape.
+    const taken = Object.keys(unverified).flatMap((key) => {
+        const entry = parseRouteKey(key);
+        const channelKey = covered(entry.path, entry.method ?? "");
+        return channelKey === undefined ? [] : [{ channelKey, key }];
+    });
+    if (taken.length > 0) {
+        throw new Error(`channel route(s) ${taken.map((t) => `"${t.channelKey}"`).join(", ")} take a path this serve answers on ` +
+            `itself (${taken.map((t) => `"${t.key}"`).join(", ")}) — rename the channel route`);
+    }
     return {
-        routes: healthCovered ? channels : { "GET /health": health, ...channels },
+        unverified,
+        selfVerifying: routes,
         longConnections,
         routeChannels,
-        builtinInvoke,
         setReady(value) {
             ready = value;
         },
     };
 }
-/**
- * Refuse channel routes the control plane would swallow.
- *
- * `router` refuses this too, and would catch it a moment later; this exists for the sentence, not
- * the check — an author who lands a route under `/control` needs to hear about `sessionControl`,
- * which the host has no way to mention. Both ask {@link pathUnderPrefix}, so there is one rule with
- * two wordings, not two rules.
- *
- * Called from BOTH mount points: here at boot, and again on agentcore's lazy path, whose channels
- * load after this ran against an empty base.
- */
+/** Refuse channel routes the control plane would swallow. */
 export function assertNoControlPlaneCollision(channelRoutes, plane) {
     const collisions = Object.keys(channelRoutes).filter((key) => pathUnderPrefix(parseRouteKey(key).path, plane.prefix));
     if (collisions.length > 0) {
@@ -94,217 +149,160 @@ export function assertNoControlPlaneCollision(channelRoutes, plane) {
             `rename the channel route or disable sessionControl in fastagent.config`);
     }
 }
-export function mountSessionControl(routes, control, options = {}) {
+export function mountSessionControl(routes, control) {
     if (!control)
         return { routes, mounts: [] };
-    // WHO OWNS the secret. Per-boot mint is right locally: discovery is `control.json` and its file
-    // permissions, which works because both holders share a filesystem. A deployment removes that
-    // premise — a token minted in the container is replaced every restart and reachable only by shelling
-    // in — so there the deployer mints it and injects it here, like the wake/ingress secrets.
-    // Trimmed on read, like `.env` values already are: a token pasted from a dashboard with a trailing
-    // newline would otherwise become the box's token verbatim, and every caller holding the clean value
-    // gets a bare 401 — the undiagnosable symptom, one character wide.
-    const injected = process.env[CONTROL_TOKEN_ENV]?.trim();
-    // SET BUT EMPTY is the deployed default, not an edge case: the generated Compose topology writes
-    // every secret as `NAME: "${NAME:-}"`, so an operator who skipped this one lands here. Falling back
-    // silently would leave exactly the symptom the injection exists to remove — a token the caller does
-    // not have — with nothing in the log to tell it apart from a deployment that never asked.
-    if (injected === "") {
-        log.warn(`[fastagent] ${CONTROL_TOKEN_ENV} is set but empty — minting a per-boot token instead; callers holding ` +
-            "the deploy-time value will get 401 (set it, or read the minted one from control.json on the box)");
-    }
-    else if (injected !== undefined && injected.length < 16) {
-        // Length is a crude proxy for entropy — sixteen `a`s pass. It is aimed at `changeme`, which this
-        // change makes newly dangerous: the plane went from unusable-in-a-deployment to usable by whoever
-        // holds this string, and the empty case is the only other thing that says anything.
-        log.warn(`[fastagent] ${CONTROL_TOKEN_ENV} is ${injected.length} characters — it is the ONLY thing between ` +
-            "/control/* (steer, stop, rewrite a session) and anyone who can reach the port; use a random value (uuidgen)");
-    }
-    const token = injected || crypto.randomUUID();
-    const plane = createControlPlane(control, { token, agent: options.agent });
+    const plane = createControlPlane(control);
     assertNoControlPlaneCollision(routes, plane);
-    return { routes, mounts: [plane], control: { token, prefix: plane.prefix } };
+    return { routes, mounts: [plane], controlPrefix: plane.prefix };
 }
 /**
- * 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.
+ * Load the agent's `routines/`, gated.
+ *
+ * Separate from {@link startSchedules} because two things need the SAME list and one of them runs first: the
+ * `POST /run` route is built with the routes (so a channel cannot take that path unnoticed), and the resident
+ * clock starts later, inside the service's scope. Loading twice would let them disagree about which routines exist.
+ */
+export async function loadServingRoutines(agentDir) {
+    // Thrown, not exited on: this runs inside an embedder's app as well as the CLI, and a library that calls
+    // process.exit takes a decision (degrade? retry? stop?) that belongs to its host.
+    const { routines, secrets, failures } = await loadRoutines(agentDir);
+    // The routines' half of the serving-path gate (the opener does the tools', loadChannels the
+    // channels'): a routine reads its env at IMPORT time, so an unset declared value has already
+    // produced a broken prompt — refusing here is the last point where that is a startup failure.
+    gateSecrets({ declared: secrets, failures });
+    refuseBrokenDeclarations(failures);
+    return routines;
+}
+/**
+ * Start the clock over routines {@link loadServingRoutines} already gated — on every serve, routines or not: the
+ * agent's own wake-ups are a default capability, and this is what fires them.
  */
-export async function startSchedules(agentDir, agent, stateRoot, selfSchedule, options = {}) {
-    // Thrown, not exited on: this runs inside an embedder's app as well as the CLI, and a library
-    // that calls process.exit takes a decision (degrade? retry? stop?) that belongs to its host. The
-    // CLI catches at its own boundary.
-    const { schedules, failures } = await loadSchedules(agentDir);
-    reportModuleLoadFailures(failures);
-    if (schedules.length === 0 && !selfSchedule)
-        return { schedules, stop: () => { } };
-    const scheduler = createScheduler({ agent, stateRoot, schedules, externalClock: options.externalClock });
+export function startSchedules(agent, stateRoot, routines, options = {}) {
+    const scheduler = Effect.runSync(createScheduler({ agent, stateRoot, routines, externalClock: options.externalClock }));
     scheduler.start();
-    if (schedules.length > 0) {
-        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
+    if (routines.length > 0) {
+        log.info(`[fastagent] routines: ${routines.map((r) => r.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
     }
-    // Returned rather than bound to process signals here: this runs inside an embedder's app as well
-    // as the CLI, and a library that installs SIGINT handlers is deciding something that is not its
-    // to decide. `runStart`/`runDev` wire it to their own shutdown.
-    return { schedules, stop: () => scheduler.stop() };
+    return { routines, stop: () => scheduler.stop() };
 }
 /**
- * The assembly itself, over an already-opened directory: channels, the control plane, schedules and
- * long connections, composed into one handler.
- *
- * {@link createAgentService} is this plus opening the directory. `dev`/`start` open separately — their
- * startup report needs the opened values before anything mounts — and then arrive here, so there is
- * one assembly rather than one per caller.
+ * The assembly itself, over an already-opened directory: channels, the control plane, routines and long connections,
+ * composed into one handler.
  */
 export async function mountAgentService(opened, options = {}) {
     const { agentDir, workspace, stateRoot, sessionControl } = opened;
-    // Wrapped BEFORE anything consumes it: routes, the control plane and schedules must all drive the
-    // same agent, so this is a hook rather than something a caller applies afterwards.
+    // Wrapped BEFORE anything consumes it: routes, the control plane and routines must all drive the same agent, so
+    // this is a hook rather than something a caller applies afterwards.
     const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
     const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
-    const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { builtinInvoke: true });
-    const withControl = mountSessionControl(routed.routes, sessionControl, { agent });
-    // Composed BEFORE anything starts. `router` re-validates what `loadChannels` and the control
-    // mount already checked, so on THIS path it should not fail — but "should not" is not an ordering
-    // guarantee, and a throw after the scheduler ticks and channels dial would leave both running
-    // with no service for the caller to close. Free to order correctly; expensive to discover later.
-    const handler = router(withControl.routes, withControl.mounts);
-    const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule);
-    const abort = new AbortController();
-    // A connection that drops while others are still dialling must not be undone by their later
-    // readiness: the service is missing a declared channel from that moment on, whatever else arrives.
-    let dropped = false;
-    const onClosed = options.onChannelClosed ??
-        ((name, error) => log.error(`[fastagent] long connection ${name} ${error === undefined ? "closed" : `failed: ${String(error)}`}`));
-    const runs = [];
-    // A FUNCTION declaration, not a const: `close()` detaches this listener, and a rollback can call
-    // `close()` before this point is reached — a `const` would be in its temporal dead zone there, so
-    // the cleanup would throw a ReferenceError and silently skip everything after it.
-    //
-    // Detached because a caller that closes services itself while holding one long-lived signal would
-    // otherwise accumulate listeners, each pinning a whole service through its closure. The signal
-    // path has no caller awaiting the promise, so a failure to stop is reported rather than left as an
-    // unhandled rejection — in an embedded library, potentially the host's exit.
-    function onAbort() {
-        void close().catch((error) => log.error(`[fastagent] service close failed: ${String(error)}`));
-    }
-    let closing;
-    const close = () => {
-        // Awaits the connections rather than only signalling them: `close()` promises they are stopped,
-        // and a caller tearing down a test or a request-scoped service needs that to be true on return.
-        closing ??= (async () => {
-            abort.abort();
-            scheduled.stop();
-            options.signal?.removeEventListener("abort", onAbort);
-            // A failure to stop is the caller's to know about — swallowing it would let `close()` report
-            // success over a channel still holding on. Bounded, because a channel that ignores its abort
-            // signal must not hang the teardown either.
-            const { stuck, failures } = await closeWithin(runs, routed.longConnections.map((c) => c.name), closeTimeoutMs);
-            if (stuck.length > 0) {
-                throw new Error(`long connection(s) did not stop within ${closeTimeoutMs}ms: ${stuck.join(", ")}`);
-            }
-            if (failures.length > 0) {
-                throw failures.length === 1 ? failures[0] : new AggregateError(failures, "long connections failed to close");
-            }
-        })();
-        return closing;
-    };
-    // Rollback IS close(), plus keeping the original error: a failure to clean up is the aftermath,
-    // and replacing the reason the caller needs with it hides the actual cause.
-    const rollback = async (error) => {
-        await close().catch((closeError) => log.error(`[fastagent] cleanup after a failed start also failed: ${String(closeError)}`));
-        throw error;
-    };
-    // Rolled back on failure: a connection that throws while the ones before it are open, and the
-    // scheduler already ticking, would otherwise leave both running behind a rejected open().
-    for (const connection of routed.longConnections) {
-        let run;
-        try {
-            run = connection.connect(abort.signal);
-        }
-        catch (error) {
-            return rollback(error);
-        }
-        if (typeof run?.ready?.then !== "function" || typeof run?.closed?.then !== "function") {
-            return rollback(new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`));
-        }
-        void run.closed.then(() => {
-            if (abort.signal.aborted)
-                return;
-            // A channel that dies leaves the service serving something it no longer has.
-            dropped = true;
-            routed.setReady(false);
-            onClosed(connection.name);
-        }, (error) => {
+    // The embedder's way in, checked like the config file's: `allowedOrigin` compares exact strings, so a stray
+    // trailing slash would refuse the front end with nothing naming the rule.
+    const corsOrigins = opened.http?.cors;
+    if (corsOrigins)
+        assertCorsOrigins(corsOrigins, "mountAgentService: http.cors");
+    // Loaded BEFORE the routes, because `POST /run` is one of them and the resident clock below must run over the
+    // same list — two loads would be two answers to "which routines exist".
+    const routines = await loadServingRoutines(agentDir);
+    const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { http: opened.http, routines });
+    const withControl = mountSessionControl(routed.selfVerifying, opened.publishControl ? sessionControl : undefined);
+    // Composed BEFORE anything starts.
+    const handler = router({
+        unverified: routed.unverified,
+        selfVerifying: withControl.routes,
+        mounts: withControl.mounts,
+        ...(corsOrigins ? { corsOrigins } : {}),
+    });
+    return Effect.runPromise(Effect.gen(function* () {
+        const lifetime = yield* Scope.make();
+        const abort = new AbortController();
+        const runs = [];
+        const names = routed.longConnections.map((c) => c.name);
+        // A connection lost during startup must not be hidden by a sibling becoming ready later.
+        let dropped = false;
+        const onClosed = options.onChannelClosed ??
+            ((name, error) => log.error(`[fastagent] long connection ${name} ${error === undefined ? "closed" : `failed: ${String(error)}`}`));
+        const notifyClosed = (name, error) => {
             if (abort.signal.aborted)
                 return;
             dropped = true;
             routed.setReady(false);
-            onClosed(connection.name, error);
-        });
-        runs.push(run);
-    }
-    if (options.signal?.aborted)
-        await close();
-    else
-        options.signal?.addEventListener("abort", onAbort, { once: true });
-    // Health answers 503 until EVERY long connection is up, so a load balancer does not route into a
-    // service whose socket-mode channels are still dialling. An abort before that settles `ready` as
-    // cancellation, not readiness — a service being torn down must not report itself healthy.
-    const ready = (async () => {
-        try {
-            await Promise.all(runs.map(async (run, i) => {
-                const name = routed.longConnections[i]?.name ?? "channel";
-                // Raced against `closed`, because the contract puts a terminal failure THERE: a channel
-                // that dies dialling may leave `ready` pending forever, and waiting on it alone hangs
-                // startup with no diagnosis.
-                await Promise.race([
-                    run.ready,
-                    run.closed.then(() => Promise.reject(new Error(`${name} closed before it was ready`)), (error) => Promise.reject(new Error(`${name} failed before it was ready: ${String(error)}`))),
-                ]);
-                if (!abort.signal.aborted)
-                    log.info(`[fastagent] long connection ready: ${name}`);
+            onClosed(name, error);
+        };
+        // Scope.close alone does not join concurrent closes or retain their failure.
+        const shutdown = yield* Effect.cached(Effect.gen(function* () {
+            abort.abort();
+            yield* Scope.close(lifetime, Exit.void);
+        }));
+        const close = () => Effect.runPromise(shutdown);
+        const rollback = shutdown.pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`[fastagent] cleanup after a failed start also failed: ${String(Cause.squash(cause))}`))));
+        const onAbort = () => {
+            void close().catch((error) => log.error(`[fastagent] service close failed: ${String(error)}`));
+        };
+        return yield* Effect.gen(function* () {
+            // Registered first, so subscriptions and schedule timers stop before waiting for transports.
+            yield* Effect.addFinalizer(() => closeWithin(runs, names, closeTimeoutMs).pipe(Effect.orDie));
+            const scheduled = yield* Effect.acquireRelease(Effect.try({
+                try: () => startSchedules(agent, stateRoot, routines),
+                catch: (error) => error,
+            }), (scheduled) => Effect.sync(scheduled.stop));
+            const readiness = yield* Effect.forEach(routed.longConnections, (connection) => Effect.gen(function* () {
+                const run = yield* Effect.try({
+                    try: () => connection.connect(abort.signal),
+                    catch: (error) => error,
+                });
+                if (typeof run?.ready?.then !== "function" || typeof run?.closed?.then !== "function") {
+                    return yield* Effect.fail(new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`));
+                }
+                runs.push(run);
+                const closed = Effect.tryPromise({ try: () => run.closed, catch: (error) => error });
+                yield* closed.pipe(Effect.match({
+                    onSuccess: () => notifyClosed(connection.name),
+                    onFailure: (error) => notifyClosed(connection.name, error),
+                }), Effect.catchCause((cause) => Effect.sync(() => log.error(`[fastagent] channel closure callback failed: ${String(Cause.squash(cause))}`))), Effect.forkScoped({ startImmediately: true }));
+                // Observe ready immediately, including when a later connect() throws and mount rolls back.
+                return yield* Effect.raceFirst(Effect.tryPromise({ try: () => run.ready, catch: (error) => error }), closed.pipe(Effect.matchEffect({
+                    onSuccess: () => Effect.fail(new Error(`${connection.name} closed before it was ready`)),
+                    onFailure: (error) => Effect.fail(new Error(`${connection.name} failed before it was ready: ${String(error)}`)),
+                }))).pipe(Effect.tap(() => Effect.sync(() => {
+                    if (!abort.signal.aborted)
+                        log.info(`[fastagent] long connection ready: ${connection.name}`);
+                })), Effect.forkScoped({ startImmediately: true }));
             }));
-        }
-        catch (error) {
-            // A connection that cannot come up is a startup failure, not a degraded service: tear the rest
-            // down before rejecting, so nothing is left running behind a caller that saw an error. A
-            // cleanup that ALSO fails is logged, never rethrown — it would replace the reason the caller
-            // actually needs with the aftermath of it.
-            await close().catch((closeError) => log.error(`[fastagent] cleanup after a failed start also failed: ${String(closeError)}`));
-            throw error;
-        }
-        // A `ready` that settles because the service was CLOSED is cancellation, not readiness — the
-        // contract lets a connection resolve it on abort. Returning normally would tell a caller its
-        // channels are up while the service is shut and health says 503.
-        if (abort.signal.aborted)
-            throw new Error("service closed before it became ready");
-        // A drop DURING startup fails it. `dropped` is only reachable here from the startup window —
-        // after this line `ready` has settled — and resolving while health is permanently 503 would
-        // hand the caller two contradictory answers about the same surface.
-        if (dropped) {
-            await close();
-            throw new Error("a long connection closed before startup completed");
-        }
-        routed.setReady(true);
-    })();
-    // Observed here so a rejection is never unhandled; every caller still sees it through `ready`.
-    ready.catch(() => { });
-    return {
-        handler,
-        agent,
-        routes: withControl.routes,
-        agentDir,
-        workspace,
-        channels: {
-            routes: routed.routeChannels,
-            longConnections: routed.longConnections.map((c) => c.name),
-            builtinInvoke: routed.builtinInvoke,
-        },
-        schedules: scheduled.schedules,
-        ready,
-        ...(withControl.control ? { control: withControl.control } : {}),
-        close,
-    };
+            if (options.signal?.aborted)
+                yield* shutdown;
+            else
+                yield* Effect.acquireRelease(Effect.sync(() => options.signal?.addEventListener("abort", onAbort, { once: true })), () => Effect.sync(() => options.signal?.removeEventListener("abort", onAbort)));
+            // The public readiness waiter lives outside the scope it may roll back.
+            const ready = Effect.runPromise(Effect.gen(function* () {
+                yield* Effect.forEach(readiness, Fiber.join, { concurrency: "unbounded", discard: true });
+                if (abort.signal.aborted)
+                    return yield* Effect.fail(new Error("service closed before it became ready"));
+                if (dropped)
+                    return yield* Effect.fail(new Error("a long connection closed before startup completed"));
+                routed.setReady(true);
+            }).pipe(Effect.catchCause((cause) => abort.signal.aborted
+                ? Effect.fail(new Error("service closed before it became ready"))
+                : Effect.failCause(cause)), Effect.onError(() => rollback)));
+            // The rejection is still delivered to callers that await ready.
+            ready.catch(() => { });
+            return {
+                handler,
+                agent,
+                routes: { ...routed.unverified, ...withControl.routes },
+                agentDir,
+                workspace,
+                channels: {
+                    routes: routed.routeChannels,
+                    longConnections: names,
+                },
+                unverifiedRoutes: Object.keys(routed.unverified),
+                ...(corsOrigins ? { corsOrigins } : {}),
+                routines: scheduled.routines,
+                ready,
+                ...(withControl.controlPrefix ? { controlPrefix: withControl.controlPrefix } : {}),
+                close,
+            };
+        }).pipe(Scope.provide(lifetime), Effect.onError(() => rollback));
+    }));
 }