@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/cli/serve.d.ts

@@ -1,6 +1,7 @@
 import type { Agent } from "../agent.ts";
 import { type LoadedLongConnectionChannel } from "../engines/pi/channel.ts";
 import { type Routes } from "../host/node.ts";
+import type { LoadedSchedule } from "../schedule/schedule.ts";
 import type { SessionControl } from "../session.ts";
 export interface ServingSurface {
     routes: Routes;
@@ -15,9 +16,11 @@ export interface ServingSurface {
  * 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 declare function routesFor(workspaceDir: string, agent: Agent, stateRoot: string, control?: SessionControl): Promise<ServingSurface>;
+export declare function routesFor(agentDir: string, agent: Agent, stateRoot: string, control?: SessionControl, options?: {
+    builtinInvoke?: boolean;
+}): Promise<ServingSurface>;
 /**
- * Mount the session control plane (`/control/*`) when the workspace enabled it
+ * 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
@@ -29,20 +32,61 @@ export declare function routesFor(workspaceDir: string, agent: Agent, stateRoot:
 export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
     tunnel?: boolean;
     agent?: Agent;
+    host?: string;
 }): {
     routes: Routes;
     announce: (boundPort: number) => void;
 };
+/**
+ * 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 declare function mountAgentcore(routes: Routes, options: {
+    agent: Agent;
+    stateRoot: string;
+    schedules: LoadedSchedule[];
+    onStateReady?: () => void;
+}): Routes;
+/**
+ * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
+ * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
+ * `127.0.0.2` bind, loopback though it is — would leave the tunnel up and 502ing every request.
+ * Checked BEFORE the bind (the flag alone pre-spawn in `dev`, again once config is loaded, since
+ * `http.host` can carry the address), so the failure is clean rather than a live-but-broken public URL.
+ * `source` decides the exit code, per fail.ts: a flag COMBINATION is a usage error (2), a value that
+ * came from config is broken runtime configuration (1).
+ */
+export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
+/**
+ * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
+ * ONE function because they are one message — they were two, and `--bind` updated the first while the
+ * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
+ * neither can be changed without the other in view, and the address has a single derivation.
+ *
+ * A wildcard bind is every interface, and naming one address there would understate it — but the curl
+ * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ */
+export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
 /**
  * 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.
+ * the sole clean-shutdown command. `host` unset binds all interfaces.
  */
-export declare function serve(surface: ServingSurface, port: number, onListening?: (boundPort: number) => void): void;
+export declare function serve(surface: ServingSurface, bind: {
+    port: number;
+    host?: string;
+}, onListening?: (boundPort: number) => void): void;
 /** Start a Cloudflare tunnel for route channels only. */
-export declare function maybeTunnel(workspaceDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
+export declare function maybeTunnel(agentDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
 /**
- * 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. Best-effort stop on process signals.
+ * 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 declare function startSchedules(workspaceDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean): Promise<void>;
+export declare function startSchedules(agentDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean, options?: {
+    externalClock?: boolean;
+}): Promise<LoadedSchedule[]>;

package/dist/cli/serve.js

@@ -4,24 +4,28 @@
  */
 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 { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
 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";
+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(workspaceDir, agent, stateRoot, control) {
-    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(workspaceDir, {
+export async function routesFor(agentDir, agent, stateRoot, control, options = {}) {
+    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
         agent,
         stateRoot,
         control,
@@ -34,7 +38,7 @@ export async function routesFor(workspaceDir, agent, stateRoot, control) {
         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 = Object.keys(routes).length === 0 && longConnections.length === 0;
+    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);
@@ -53,7 +57,7 @@ export async function routesFor(workspaceDir, agent, stateRoot, control) {
     };
 }
 /**
- * Mount the session control plane (`/control/*`) when the workspace enabled it
+ * 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
@@ -87,15 +91,22 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
             // 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 });
+            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 (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)");
+            // 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
@@ -132,13 +143,95 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
         },
     };
 }
+/**
+ * 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 };
+}
+/**
+ * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
+ * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
+ * `127.0.0.2` bind, loopback though it is — would leave the tunnel up and 502ing every request.
+ * Checked BEFORE the bind (the flag alone pre-spawn in `dev`, again once config is loaded, since
+ * `http.host` can carry the address), so the failure is clean rather than a live-but-broken public URL.
+ * `source` decides the exit code, per fail.ts: a flag COMBINATION is a usage error (2), a value that
+ * came from config is broken runtime configuration (1).
+ */
+export function assertTunnelBindable(host, tunnel, source) {
+    if (!tunnel || answersLocalhost(host))
+        return;
+    // Name the source, not just the exit code: under `config` there is no `--bind` to change and no flag
+    // to drop, so flag-only wording would send the reader looking for something they never typed.
+    const fix = source === "flag"
+        ? "bind 0.0.0.0 (or 127.0.0.1), or drop --tunnel"
+        : "set http.host to 0.0.0.0 (or 127.0.0.1) in fastagent.config.*, override it with --bind, or drop --tunnel";
+    const message = `--tunnel reaches the serve by dialing localhost, which the bind address ${host} does not answer — ${fix}`;
+    if (source === "flag")
+        failUsage(message);
+    failStartup(new Error(message));
+}
+/**
+ * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
+ * ONE function because they are one message — they were two, and `--bind` updated the first while the
+ * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
+ * neither can be changed without the other in view, and the address has a single derivation.
+ *
+ * A wildcard bind is every interface, and naming one address there would understate it — but the curl
+ * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ */
+export function readyAddressLines(host, boundPort, builtinInvoke) {
+    const dial = `${clientHost(host)}:${boundPort}`;
+    const lines = [
+        `[fastagent] http host on ${classifyBind(host) === "wildcard" ? `:${boundPort} (all interfaces)` : bindLabel(host, boundPort)}`,
+    ];
+    if (builtinInvoke) {
+        lines.push(`[fastagent] try it: curl -s ${dial}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
+    }
+    return lines;
+}
 /**
  * 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.
+ * the sole clean-shutdown command. `host` unset binds all interfaces.
  */
-export function serve(surface, port, onListening) {
-    const hosted = serveNode(router(surface.routes), { port });
+export function serve(surface, bind, onListening) {
+    const { port, host } = bind;
+    const hosted = serveNode(router(surface.routes), { port, host });
     const abort = new AbortController();
     let stopping = false;
     const stop = (exitCode) => {
@@ -193,14 +286,12 @@ export function serve(surface, port, onListening) {
                 port: boundPort,
                 routeChannels: surface.routeChannels,
             });
-            log.info(`[fastagent] http host on :${boundPort}`);
+            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(", ")}`);
             }
-            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) {
@@ -211,38 +302,48 @@ export function serve(surface, port, onListening) {
             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}`));
+        if (error.code === "EADDRINUSE") {
+            // With a bind address the port is only taken ON THAT interface, so moving the bind is as valid
+            // a fix as moving the port.
+            failStartup(new Error(`${bindLabel(host, port)} is already in use; choose another with ` +
+                `--port${classifyBind(host) === "wildcard" ? "" : " or --bind"}`));
+        }
+        // Through `bindLabel`, like every other message about a bind: hand-concatenating gives `:::8787`
+        // for an IPv6 bind and a bare `:8787` for the wildcard, which reads as an explicit bind of nothing.
+        failStartup(new Error(`cannot bind http channel on ${bindLabel(host, port)}: ${error.message}`));
     });
 }
 /** Start a Cloudflare tunnel for route channels only. */
-export function maybeTunnel(workspaceDir, routeChannels, boundPort, tunnel, stateRoot) {
+export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
     void startCloudflareTunnel(boundPort).then((instance) => {
         if (!instance)
             return;
-        void announceWebhooks(workspaceDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        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. Best-effort stop on process signals.
+ * 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);
     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,4 +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;
 /**
@@ -8,6 +20,12 @@ export declare function isInteractive(): boolean;
  * bad `PORT` env is broken runtime configuration (1).
  */
 export declare function parsePort(value: string | undefined, source: string, from: "flag" | "env"): number | undefined;
+/**
+ * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to
+ * config, then all interfaces). An unbindable string is a USAGE error (2) — caught here rather than as
+ * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
+ */
+export declare function parseBind(value: string | undefined): string | undefined;
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
 /**
@@ -19,9 +37,10 @@ export declare function reportAuth(modelSpec: string, authPath: string): Promise
  * 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.
+ * 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;

package/dist/cli/shared.js

@@ -8,14 +8,31 @@ import { relative } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
-import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, resolveStateRoot, rewriteConfigModel, } from "../engines/pi/config.js";
-import { ensureStateRootSelfIgnored, isUnderDir } from "../engines/pi/definition.js";
+import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { log } 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
+ * 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 function reportLine(label, value) {
+    log.info(`[fastagent] ${`${label}:`.padEnd(11)}${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) {
+    if (hint)
+        reportLine("hint", hint);
+}
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -40,6 +57,19 @@ export function parsePort(value, source, from) {
     }
     return Number(trimmed);
 }
+/**
+ * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to
+ * config, then all interfaces). An unbindable string is a USAGE error (2) — caught here rather than as
+ * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
+ */
+export function parseBind(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    if (!isBindAddress(trimmed))
+        failUsage(`invalid --bind "${value}": must be an IP address or "localhost"`);
+    return bindAddress(trimmed); // a name never travels past this point — see bind.ts
+}
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export async function reportAuth(modelSpec, authPath) {
     const provider = providerOf(modelSpec);
@@ -65,23 +95,24 @@ export async function reportAuth(modelSpec, authPath) {
  * 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.
+ * 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 async function resolveFirstRunModel(workspaceDir, options = {}) {
-    const { config, path: configPath } = await loadConfig(workspaceDir).catch(failStartup);
+export async function resolveFirstRunModel(agentDir, options = {}) {
+    const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
     if (resolveModelSpec(options.model, config))
         return; // already set (flag > FASTAGENT_MODEL > config)
     if (options.input === false)
         return; // --no-input: never prompt (clig) — the opener raises the clear error
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
-    const authPath = resolveAuthPath(workspaceDir, options.authPath);
+    const authPath = resolveAuthPath(agentDir, options.authPath);
     const models = createPiModels({ authPath });
-    const chosen = await pickWithCredentials(workspaceDir, models, authPath);
+    const chosen = await pickWithCredentials(models, authPath);
     if (chosen === undefined)
         return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
-    await persistModelChoice(workspaceDir, configPath, chosen);
+    await persistModelChoice(agentDir, configPath, chosen);
 }
 /**
  * The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy —
@@ -89,7 +120,7 @@ export async function resolveFirstRunModel(workspaceDir, options = {}) {
  * independent of credentials), or the inline login for the rest. Returns the chosen spec, or
  * undefined when the pick should be discarded (picker cancel, login cancel, a failed auth probe).
  */
-async function pickWithCredentials(workspaceDir, models, authPath) {
+async function pickWithCredentials(models, authPath) {
     let statuses;
     try {
         statuses = await providerAuthStatuses(models);
@@ -124,11 +155,6 @@ async function pickWithCredentials(workspaceDir, models, authPath) {
         }
         return chosen;
     }
-    // Inline login. Same leak guard as `login`: self-ignore the state root BEFORE a credential
-    // can land in-tree, so the secret is never untracked-but-committable.
-    const stateRoot = resolveStateRoot(workspaceDir);
-    if (isUnderDir(authPath, stateRoot))
-        await ensureStateRootSelfIgnored(workspaceDir, stateRoot);
     try {
         // Verified against the CHOSEN model — the exact request the agent is about to make; a rejected
         // key re-prompts inside the loop, so reaching here means a usable (or at worst unverifiable) key.
@@ -224,10 +250,10 @@ function terminalLoginIO() {
 /**
  * Best-effort persist the picked model so the next run does not prompt. Rewrites the commented
  * `model:` placeholder the scaffold writes / an existing `model:` line, or re-inserts the line into a
- * scaffold-shaped config (the hand-deleted-to-reset case); anything else (zero-config, a hand-shaped
- * config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ * scaffold-shaped config (the hand-deleted-to-reset case); anything else (a hand-shaped config) is
+ * left untouched with a printed hint. Never throws — persistence is a convenience.
  */
-async function persistModelChoice(workspaceDir, configPath, spec) {
+async function persistModelChoice(agentDir, configPath, spec) {
     const hint = () => console.error(
     // No "using it for this run" promise: deploy's model-travel gate rightly ignores the un-persisted pick.
     `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
@@ -238,7 +264,7 @@ async function persistModelChoice(workspaceDir, configPath, spec) {
         if (!replaced)
             return hint();
         await writeFile(configPath, replaced);
-        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(workspaceDir, configPath)}`);
+        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(agentDir, configPath)}`);
     }
     catch {
         hint();

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

@@ -0,0 +1,117 @@
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Artifact, type ContainerInput } from "../container.ts";
+/** The one schedule fact the plan needs (from loadSchedules) — name + cron + tz. */
+export interface ScheduleFact {
+    name: string;
+    cron: string;
+    tz?: string;
+}
+export interface AgentcorePlanInput extends ContainerInput {
+    /** Base name (dir basename) — shapes the runtime name, stack name, ECR repo, session id. */
+    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[];
+    /** Extra secret env-var names (fastagent.config deploy.secrets). */
+    extraSecrets?: string[];
+    /** Static schedules — each becomes an EventBridge Scheduler rule targeting the forwarder. */
+    schedules: ScheduleFact[];
+    /** Wake tool enabled — DEGRADED here (fires only while a session happens to be awake); warned. */
+    selfSchedule: boolean;
+}
+export interface AgentcorePlan {
+    /** template + forwarder + Dockerfile/.dockerignore — written by the CLI (kept unless --force). */
+    artifacts: Artifact[];
+    /** The ordered, values-resolved deploy runbook — printed to stdout. */
+    runbook: string[];
+    /** Cron expressions EventBridge cannot express — surfaced as runbook warnings, not silent drops. */
+    untranslatableSchedules: {
+        name: string;
+        reason: string;
+    }[];
+}
+/** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
+ *  a fast LOCAL disk only: the platform wipes it on every runtime version update (= every deploy).
+ *  Durability across deploys comes from the S3 snapshot (channels/agentcore-state.ts). */
+export declare const MOUNT = "/mnt/state";
+/**
+ * How long an idle session keeps its microVM. Memory is billed per second across the WHOLE session
+ * — idle included, at the peak level reached — so this tail is the standing cost of every burst of
+ * activity, while CPU stops billing the moment the agent stops working. 3 minutes rather than the
+ * platform's 15: the tail shrinks 5×, and the cost is a cold start (image + Node + snapshot restore)
+ * for anyone who returns after a longer gap. `/ping` reports HealthyBusy while work is in flight, so
+ * this timer only ever starts once the agent has genuinely settled — a long turn is never cut short.
+ * AWS accepts 60–28800.
+ */
+export declare const IDLE_TIMEOUT_SECONDS = 180;
+/** The platform ceiling on one session's compute (8 h). The session ID outlives it: the next invoke
+ *  simply gets fresh compute with the same storage. */
+export declare const MAX_LIFETIME_SECONDS = 28800;
+/** The state snapshot's object key in the deployment bucket (one object; see agentcore-state.ts). */
+export declare const STATE_KEY = "state/snapshot.json.gz";
+/** The forwarder artifact. Named `index.js` because it IS the Lambda deployment package's entry:
+ *  zipping it as-is produces a valid package (`Handler: index.handler`), with nothing to rename. */
+export declare const FORWARDER_FILE = "lambda/index.js";
+/** The deployment bucket: forwarder code + the state snapshot. Account-suffixed for S3's GLOBAL
+ *  namespace, and created OUTSIDE the stack (like the ECR repo) so a `delete-stack` cannot take the
+ *  agent's memory with it. Bucket names cap at 63 chars; `name` is already gated to 40. */
+export declare function stateBucketName(name: string, account: string): string;
+/** AgentCore env values max 2048 chars — a real OAuth auth.json's base64 exceeds it, so the seed is
+ *  CHUNKED across FASTAGENT_AUTH_SEED + _2… (collectAuthSeed reassembles at boot). 2000 keeps margin. */
+export declare const AUTH_SEED_CHUNK_SIZE = 2000;
+export declare const AUTH_SEED_MAX_CHUNKS = 4;
+/** The generated template's filename (namespaced under the kit in the agentDir layout). */
+export declare const TEMPLATE_FILE = "agentcore.template.yaml";
+/** The generated template's first-line marker — the ONE source for both the generator and the
+ *  "did fastagent generate this?" check (deploy's drift gate), so they cannot drift apart. */
+export declare const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agentcore`";
+/** Whether an on-disk template is fastagent-generated (vs hand-written — kept, never gated). */
+export declare function isGeneratedAgentcoreTemplate(content: string): boolean;
+/** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
+export declare function toRuntimeName(basename: string): string;
+/** The ONE fixed ingress session id (webhooks + schedule fires) — ≥ 33 chars (the API minimum),
+ *  deterministic (the Lambda holds it in env), padded so any name clears the floor. */
+export declare function ingressSessionId(name: string): string;
+/** CFN parameter logical id for a secret env-var name: TELEGRAM_BOT_TOKEN → TelegramBotToken
+ *  (parameter names must be alphanumeric). Deterministic — run.ts builds the same mapping. */
+export declare function cfnParamName(envName: string): string;
+/**
+ * Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it
+ * can't be. The two dialects disagree exactly where silent translation would misfire:
+ *  - EventBridge numbers day-of-week 1–7 (1 = Sunday); standard cron uses 0–6 (0/7 = Sunday) —
+ *    numeric dow values and range endpoints are remapped ({@link mapDowField}); steps and names
+ *    pass through; a range that wraps under renumbering is refused.
+ *  - EventBridge requires `?` in dom or dow: a `*` on either side becomes `?`; BOTH restricted is
+ *    standard cron's OR semantics, which EventBridge cannot express — refused, never approximated.
+ *  - A 6-field (seconds) expression and L/# day-of-week forms are refused for the same reason.
+ */
+export declare function toEventBridgeCron(cron: string): {
+    expression: string;
+} | {
+    error: string;
+};
+/**
+ * The forwarder Lambda source — the ONLY string both the template's inline ZipFile 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
+ * 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.
+ */
+export declare function forwarderSource(): string;
+/**
+ * The EventBridge physical name for a schedule. A schedule's local name is an arbitrary MODULE FILE
+ * NAME (`schedules/晨报.ts`, `schedules/deploy check.ts`), while AWS requires `[0-9A-Za-z-_.]+` within
+ * 64 chars — and the `fa-<agent>-` prefix already eats up to 44 of them. So: sanitize, bound the
+ * readable part, and end with a hash of the ORIGINAL name, which keeps distinct schedules distinct
+ * where sanitizing or truncation would have merged them (one rule silently firing for two).
+ */
+export declare function scheduleResourceName(agent: string, schedule: string): string;
+/** Compute the AgentCore deploy plan from the resolved definition. */
+export declare function planAgentcoreDeploy(input: AgentcorePlanInput): AgentcorePlan;