@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/cli/serve.js

@@ -1,188 +1,18 @@
 /**
- * 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.
+ * What `dev` (its worker) and `start` need beyond the service itself: binding a port, the shutdown
+ * order, the startup report, and the optional Cloudflare quick tunnel.
+ *
+ * The ASSEMBLY 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 { 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";
+import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
 import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
-import { parseRouteKey, router, serveNode } from "../host/node.js";
+import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
-import { loadSchedules } from "../schedule/discover.js";
-import { createScheduler, fireScheduleOnce } from "../schedule/scheduler.js";
+import { declaredChannels } from "../channels/discover.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup, failUsage } from "./fail.js";
-/**
- * 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(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`);
-    }
-    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`);
-    }
-    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");
-    });
-    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://${clientHost(options.host)}:${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 by DEFAULT (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. A
-            // loopback bind closes exactly that reach, so it earns silence.
-            const bind = classifyBind(options.host);
-            if (bind !== "loopback") {
-                log.warn(`[fastagent] the port binds ${bind === "wildcard" ? "all interfaces" : `${options.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 §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);
-        },
-    };
-}
-/**
- * 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, lazyChannels } = options;
-    const mounted = agentcoreRoutes({
-        routes: lazyChannels ?? 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 };
-}
 /**
  * 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
@@ -205,6 +35,20 @@ export function assertTunnelBindable(host, tunnel, source) {
         failUsage(message);
     failStartup(new Error(message));
 }
+/**
+ * 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.
+ */
+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))
+        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 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
@@ -224,81 +68,64 @@ export function readyAddressLines(host, boundPort, builtinInvoke) {
     }
     return lines;
 }
+/** 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. */
+export const SHUTDOWN_GRACE_MS = 800;
+const FORCED_EXIT_MS = 1_500;
 /**
- * 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. `host` unset binds all interfaces.
+ * 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.
  */
-export function serve(surface, bind, onListening) {
+export function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
-    const hosted = serveNode(router(surface.routes), { port, host });
-    const abort = new AbortController();
+    const hosted = serveNode(handler, { port, host });
     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(() => {
+        // 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.
+        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.
+        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.
+        void Promise.allSettled([closingServer, Promise.resolve(hooks.onShutdown?.())]).then((outcomes) => {
+            let code = exitCode;
+            for (const outcome of outcomes) {
+                if (outcome.status === "rejected") {
+                    log.error(`[fastagent] shutdown failed: ${String(outcome.reason)}`);
+                    code = 1;
+                }
+            }
             clearTimeout(deadline);
-            process.exit(exitCode);
+            process.exit(code);
         });
-        // 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)
+            // 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;
-            surface.markReady();
-            process.send?.({
-                type: "ready",
-                port: boundPort,
-                routeChannels: surface.routeChannels,
-            });
-            for (const line of readyAddressLines(host, boundPort, surface.builtinInvoke))
-                log.info(line);
-            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(", ")}`);
-            }
-            onListening?.(boundPort);
+            hooks.onListening?.(boundPort);
         }
         catch (error) {
-            abort.abort();
-            const closing = hosted.close().catch(() => { });
-            hosted.closeAllConnections();
-            await closing;
             failStartup(error);
         }
     }, (error) => {
@@ -320,30 +147,12 @@ export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoo
     void startCloudflareTunnel(boundPort).then((instance) => {
         if (!instance)
             return;
-        void announceWebhooks(agentDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        void announceWebhooks(agentDir, instance.url, declaredChannels(routeChannels), {
+            openUrl: openExternalUrl,
+            stateRoot,
+        });
         const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);
     });
 }
-/**
- * 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(agentDir, agent, stateRoot, selfSchedule, options = {}) {
-    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
-    reportModuleLoadFailures(failures);
-    if (schedules.length === 0 && !selfSchedule)
-        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(", ")}${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,16 +1,46 @@
 import { type LoginIO, type LoginMethod, type LoginResult } 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";
+/** 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. */
+export interface ReportableAssembly {
+    agentDir: string;
+    workspace: string;
+    modelSpec: string;
+    authPath: string;
+    config: {
+        thinkingLevel?: string;
+    };
+    definition: LoadedDefinition;
+    toolNames: string[];
+    deferredToolNames: string[];
+    toolCollisions: ToolCollision[];
+    toolFailures: ModuleLoadFailure[];
+}
 /**
- * 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.
+ * 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.
  */
-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;
+export declare function reportAssembly(a: ReportableAssembly, extras?: {
+    /** Printed between `workspace:`/`hint:` 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;
 /**

package/dist/cli/shared.js

@@ -12,27 +12,74 @@ import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resol
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
-import { log } from "../log.js";
+import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
+import { workspaceHint } from "../paths.js";
+import { log, reportModuleLoadFailures } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { bindAddress, isBindAddress } from "../bind.js";
 import { failStartup, failUsage } from "./fail.js";
 /**
  * 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
+ * `codingTools:` joined `workspace:`/`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.
+ *
+ * Private to this module: {@link reportAssembly} is the report, and a command reaching past it for a
+ * line of its own is how the two copies of that report came to differ.
  */
-export function reportLine(label, value) {
-    log.info(`[fastagent] ${`${label}:`.padEnd(11)}${value}`);
+function reportLine(label, value) {
+    log.info(`[fastagent] ${`${label}:`.padEnd(13)}${value}`);
 }
 /** 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 function reportWorkspaceHint(hint) {
+ *  as one and is silent otherwise. */
+function reportWorkspaceHint(hint) {
     if (hint)
         reportLine("hint", hint);
 }
+/**
+ * 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.
+ */
+export async function reportAssembly(a, extras = {}) {
+    reportLine("agent", a.agentDir);
+    reportLine("workspace", a.workspace);
+    reportWorkspaceHint(workspaceHint(a));
+    for (const [label, value] of extras.beforeModel ?? [])
+        reportLine(label, value);
+    reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
+    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
+    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
+    if (a.definition.persona)
+        reportLine("persona", "persona.md");
+    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
+    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
+    if (a.toolNames.length > 0)
+        reportLine("tools", a.toolNames.join(", "));
+    if (a.deferredToolNames.length > 0) {
+        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
+    }
+    reportToolCollisions(a.toolCollisions);
+    reportModuleLoadFailures(a.toolFailures);
+    for (const [label, value] of extras.afterTools ?? [])
+        reportLine(label, value);
+    reportFindingsIfChanged(a.definition.dir, a.definition);
+}
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);

package/dist/core.d.ts

@@ -1,12 +1,10 @@
 export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.ts";
 export { collect, AgentFailure, type CollectResult } from "./collect.ts";
 export type { ModuleLoadFailure } from "./loader.ts";
-export { createInvokeHandler, nodeListener } from "./channels/http.ts";
-export { controlRoutes, type ControlRoutesOptions, type WireEvent } from "./channels/control.ts";
+export { createInvokeHandler } from "./channels/http.ts";
+export type { WireEvent } from "./channels/control.ts";
 export { ControlRequestError, connectAgent, connectSessionControl, type RemoteEndpointOptions, } from "./session-remote.ts";
 export { readBodyCapped } from "./channels/body.ts";
 export { text, textHeaders } from "./channels/respond.ts";
-export { type ChannelContext, type ChannelHandler, type ChannelModule, type LongConnection, type LongConnectionChannelModule, type Routes, router, serveNode, } from "./host/node.ts";
+export type { ChannelContext, ChannelHandler, ChannelModule, LongConnection, LongConnectionChannelModule, Routes, } from "./channel.ts";
 export { defineSchedule, type LoadedSchedule, type Schedule } from "./schedule/schedule.ts";
-export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.ts";
-export { createScheduler, scheduleSession, type Scheduler, type SchedulerOptions } from "./schedule/scheduler.ts";

package/dist/core.js

@@ -1,10 +1,12 @@
 export { collect, AgentFailure } from "./collect.js";
-export { createInvokeHandler, nodeListener } from "./channels/http.js";
-export { controlRoutes } from "./channels/control.js";
+export { createInvokeHandler } from "./channels/http.js";
 export { ControlRequestError, connectAgent, connectSessionControl, } from "./session-remote.js";
 export { readBodyCapped } from "./channels/body.js";
 export { text, textHeaders } from "./channels/respond.js";
-export { router, serveNode, } from "./host/node.js";
+// Mounting only. Composing a route table (`router`) and owning a prefix (`PrefixMount`) are how
+// `createAgentService` assembles a service — not something a caller has to reproduce.
+// Binding to a Node server lives at `/node`: it is the only runtime-specific piece here, and the
+// only one that costs a third-party package.
+// `defineSchedule` is what a `schedules/*.ts` file is written against. Discovering those files and
+// running the clock is what `createAgentService` does with them — parts a caller does not reproduce.
 export { defineSchedule } from "./schedule/schedule.js";
-export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.js";
-export { createScheduler, scheduleSession } from "./schedule/scheduler.js";

package/dist/deploy/agentcore/logs.d.ts

@@ -29,7 +29,7 @@ export type AgentcoreLogsOutcome = {
 };
 /**
  * Find and tail one AgentCore log source. Discovery is dynamic rather than spelling `-DEFAULT`:
- * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. Runtime tailing
- * filters the log STREAM prefix so OTEL/spans in the same group never pollute the application log.
+ * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. The whole group
+ * is tailed — see the file header for why a stream filter cannot narrow it and must not be added.
  */
 export declare function tailAgentcoreLogs(plan: AgentcoreLogsPlan, aws: CliRunner, announce?: (message: string) => void): Promise<AgentcoreLogsOutcome>;

package/dist/deploy/agentcore/logs.js

@@ -17,8 +17,8 @@ function parseLogGroupNames(stdout) {
 }
 /**
  * Find and tail one AgentCore log source. Discovery is dynamic rather than spelling `-DEFAULT`:
- * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. Runtime tailing
- * filters the log STREAM prefix so OTEL/spans in the same group never pollute the application log.
+ * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. The whole group
+ * is tailed — see the file header for why a stream filter cannot narrow it and must not be added.
  */
 export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
     const stack = `fastagent-${plan.name}`;

package/dist/deploy/agentcore/plan.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
 /** The one schedule fact the plan needs (from loadSchedules) — name + cron + tz. */
 export interface ScheduleFact {
@@ -11,10 +11,9 @@ export interface AgentcorePlanInput extends ContainerInput {
     name: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Known first-party channels — each contributes its secret metadata + webhook step. */
-    channels: ChannelKind[];
-    /** ALL route-channel basenames (customs included) — any of them requires the forwarder. */
-    routeChannels: string[];
+    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
+     *  whether the forwarder is needed at all (ANY webhook channel requires it, customs included). */
+    channels: readonly DeclaredChannel[];
     /** Extra secret env-var names (fastagent.config deploy.secrets). */
     extraSecrets?: string[];
     /** Static schedules — each becomes an EventBridge Scheduler rule targeting the forwarder. */
@@ -118,15 +117,18 @@ export declare function toEventBridgeCron(cron: string): {
     error: string;
 };
 /**
- * The forwarder Lambda source — the ONLY string both the template's inline ZipFile and the readable
+ * The forwarder Lambda source — the ONLY string both the deployment package and the readable
  * `lambda/forwarder.js` artifact are generated from (one source, no drift). Zero-dependency: the
- * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: CloudFormation inline code always
- * lands as `index.js`, where ESM `import` is a syntax error (found by the first real deploy). Two
+ * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: the package's entry lands as
+ * `index.js` ({@link zipSingleFile}), where ESM `import` is a syntax error. Two
  * event shapes: a Function URL webhook (reconstructed verbatim into a `webhook` envelope; the
  * channel's REAL response rides back inside the transport reply and is re-emitted byte-exact —
  * Feishu's URL-verification challenge depends on it), and an EventBridge Scheduler fire
- * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key). MUST stay
- * under CloudFormation's 4096-byte inline-code cap.
+ * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key).
+ *
+ * It ships as an S3 object rather than inline `ZipFile`, so there is no 4096-byte ceiling on it — a
+ * constraint this comment asserted for long after the template stopped inlining, which is the kind
+ * of stale rule that stops the next person making a correct change.
  */
 export declare function forwarderSource(): string;
 /**