@fastagent-sh/fastagent 0.16.0 → 0.16.2

package/dist/cli/serve.d.ts

@@ -32,6 +32,7 @@ export declare function routesFor(agentDir: string, agent: Agent, stateRoot: str
 export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
     tunnel?: boolean;
     agent?: Agent;
+    host?: string;
 }): {
     routes: Routes;
     announce: (boundPort: number) => void;
@@ -49,12 +50,35 @@ export declare function mountAgentcore(routes: Routes, options: {
     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(agentDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
 /**

package/dist/cli/serve.js

@@ -12,13 +12,14 @@ 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, 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.
@@ -90,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
@@ -175,13 +183,55 @@ export function mountAgentcore(routes, options) {
     }
     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) => {
@@ -236,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) {
@@ -254,9 +302,15 @@ 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. */

package/dist/cli/shared.d.ts

@@ -20,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>;
 /**

package/dist/cli/shared.js

@@ -14,6 +14,7 @@ import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } fr
 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
@@ -56,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);

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

@@ -0,0 +1,30 @@
+/**
+ * AgentCore log discovery + tailing. AWS puts the container's stdout/stderr and its OTEL telemetry
+ * in the same per-endpoint CloudWatch log group, while the forwarder Lambda has a separate group.
+ * This operator surface resolves the stack's RuntimeArn, discovers the endpoint group by prefix, and
+ * tails ONLY `[runtime-logs]` for the runtime source — the same application lines shown locally,
+ * without mixing in spans/otel-rt-logs.
+ */
+import type { CliRunner } from "../runner.ts";
+export type AgentcoreLogSource = "runtime" | "forwarder";
+export interface AgentcoreLogsPlan {
+    /** Deployment base name — stack `fastagent-<name>`, forwarder `fastagent-<name>-forwarder`. */
+    name: string;
+    source: AgentcoreLogSource;
+    /** AWS CLI relative/ISO-8601 window (`10m`, `2h`, ...). Defaults to the CLI's own 10 minutes. */
+    since?: string;
+    follow: boolean;
+}
+export type AgentcoreLogsOutcome = {
+    ok: true;
+    logGroup: string;
+} | {
+    ok: false;
+    gate: string;
+};
+/**
+ * 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.
+ */
+export declare function tailAgentcoreLogs(plan: AgentcoreLogsPlan, aws: CliRunner, announce?: (message: string) => void): Promise<AgentcoreLogsOutcome>;

package/dist/deploy/agentcore/logs.js

@@ -0,0 +1,115 @@
+import { parseStackOutputs } from "./run.js";
+/** Runtime id from `arn:...:runtime/<id>` — the id prefixes AgentCore's per-endpoint log group. */
+function runtimeIdFromArn(arn) {
+    const marker = ":runtime/";
+    const at = arn.lastIndexOf(marker);
+    const id = at === -1 ? "" : arn.slice(at + marker.length);
+    return id && !id.includes("/") ? id : undefined;
+}
+function parseLogGroupNames(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) && parsed.every((v) => typeof v === "string") ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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.
+ */
+export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
+    const stack = `fastagent-${plan.name}`;
+    const outputsResult = await aws(["cloudformation", "describe-stacks", "--stack-name", stack, "--query", "Stacks[0].Outputs", "--output", "json"], { capture: true });
+    if (outputsResult.code === 127) {
+        return { ok: false, gate: "aws CLI not found — install AWS CLI v2: https://docs.aws.amazon.com/cli/" };
+    }
+    if (outputsResult.code !== 0) {
+        return {
+            ok: false,
+            gate: `could not read AgentCore stack ${stack} — deploy it first, or fix the AWS account/region shown above`,
+        };
+    }
+    const outputs = parseStackOutputs(outputsResult.stdout);
+    let prefix;
+    let exact;
+    if (plan.source === "runtime") {
+        const runtimeArn = outputs.RuntimeArn;
+        const runtimeId = runtimeArn && runtimeIdFromArn(runtimeArn);
+        if (!runtimeId) {
+            return {
+                ok: false,
+                gate: `stack ${stack} has no valid RuntimeArn output — regenerate/deploy the AgentCore stack`,
+            };
+        }
+        prefix = `/aws/bedrock-agentcore/runtimes/${runtimeId}-`;
+    }
+    else {
+        // `ForwarderUrl` is the stack's INGRESS URL, NOT proof that a forwarder Lambda exists: plan.ts
+        // keeps needsForwarder and needsFunctionUrl as two variables on purpose (a schedules-only topology
+        // may keep the forwarder and drop the public URL). So DISCOVERY decides existence below, and the
+        // URL output only picks which not-found sentence is true.
+        exact = `/aws/lambda/fastagent-${plan.name}-forwarder`;
+        prefix = exact;
+    }
+    const groupsResult = await aws([
+        "logs",
+        "describe-log-groups",
+        "--log-group-name-prefix",
+        prefix,
+        "--query",
+        "logGroups[].logGroupName",
+        "--output",
+        "json",
+    ], { capture: true });
+    if (groupsResult.code !== 0) {
+        return { ok: false, gate: "could not discover the CloudWatch log group — see the AWS error above" };
+    }
+    const groups = parseLogGroupNames(groupsResult.stdout);
+    if (!groups) {
+        return { ok: false, gate: "AWS returned an invalid CloudWatch log-group response" };
+    }
+    const matches = groups.filter((group) => (exact ? group === exact : group.startsWith(prefix))).sort();
+    if (matches.length === 0) {
+        // Absent group = never used, EXCEPT when the stack has no forwarder at all — an invoke-only
+        // deployment would otherwise be told to deliver a webhook it can never receive. Both facts agree
+        // there (no ingress URL output either), so the message can name the topology instead of a trigger.
+        if (plan.source === "forwarder" && !outputs.ForwarderUrl) {
+            return {
+                ok: false,
+                gate: `stack ${stack} has neither a forwarder log group nor an ingress URL — this looks like an invoke-only deployment, which has Runtime logs only`,
+            };
+        }
+        const trigger = plan.source === "runtime" ? "invoke the Runtime once" : "deliver one webhook or schedule fire";
+        return {
+            ok: false,
+            gate: `no ${plan.source} log group exists yet — ${trigger}, then retry (AWS creates it on first use)`,
+        };
+    }
+    // A generated stack has one Runtime endpoint. If an operator's edited stack has several, choosing
+    // one silently would show a valid but potentially WRONG agent log — list them and make the choice explicit.
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            gate: `several Runtime log groups match this stack: ${matches.join(", ")} — tail the intended one with the ` +
+                `same stream filter this command applies: aws logs tail <group> --log-stream-name-prefix '[runtime-logs]' ` +
+                `(quote the prefix — [...] is a shell glob)`,
+        };
+    }
+    const logGroup = matches[0];
+    announce(`${plan.source} → ${logGroup}`);
+    const tailArgs = ["logs", "tail", logGroup, "--format", "short"];
+    if (plan.since)
+        tailArgs.push("--since", plan.since);
+    if (plan.source === "runtime")
+        tailArgs.push("--log-stream-name-prefix", "[runtime-logs]");
+    if (plan.follow)
+        tailArgs.push("--follow");
+    const tailed = await aws(tailArgs);
+    if (tailed.code !== 0) {
+        return { ok: false, gate: `aws logs tail failed for ${logGroup} — see the AWS error above` };
+    }
+    return { ok: true, logGroup };
+}

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

@@ -37,6 +37,27 @@ export interface AgentcorePlan {
  *  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";
+/**
+ * FASTAGENT_SECRETS_DIR — the seeded-then-ROTATED auth.json, deliberately INSIDE the state root
+ * rather than beside it.
+ *
+ * Every other host mounts a real volume and puts the two machinery dirs side by side (`/data/.state`
+ * + `/data/.secrets`), because there the persistence boundary is the MOUNT POINT: anything under it
+ * survives. AgentCore has no volume. Its persistence boundary is `packStateRoot(stateRoot)` — the one
+ * directory tree the S3 snapshot copies out and back (channels/agentcore-state.ts) — while {@link MOUNT}
+ * itself is wiped on every runtime version update, i.e. on every deploy.
+ *
+ * So the sibling layout would put credentials INSIDE the mount but OUTSIDE the snapshot: nothing
+ * copies them out, the platform wipes them, and the next microVM re-seeds the deploy-time copy. With
+ * single-use OAuth refresh tokens that is a slow-motion outage — the box works until the seeded token
+ * is rotated away, then loses model access with only a redeploy to restore it.
+ *
+ * Nesting is what makes agentcore-state.ts's stated contract ("restores VERBATIM — including
+ * auth.json") reachable at all; `packStateRoot` walks the whole tree, so no snapshot code knows about
+ * this. Tests assert the containment, not just the two names — the sibling spelling looks tidier and
+ * reintroduces the outage silently.
+ */
+export declare const SECRETS_DIR = "/mnt/state/.secrets";
 /**
  * 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
@@ -70,6 +91,8 @@ export declare const TEMPLATE_FILE = "agentcore.template.yaml";
 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;
+/** Deployment base name from the workspace basename — the ONE mapping used to find its stack later. */
+export declare function agentcoreName(workspaceBasename: string): string;
 /** 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),

package/dist/deploy/agentcore/plan.js

@@ -29,12 +29,34 @@
  */
 import { createHash } from "node:crypto";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
+import { SECRETS_DIRNAME } from "../../paths.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** 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 const MOUNT = "/mnt/state";
+/**
+ * FASTAGENT_SECRETS_DIR — the seeded-then-ROTATED auth.json, deliberately INSIDE the state root
+ * rather than beside it.
+ *
+ * Every other host mounts a real volume and puts the two machinery dirs side by side (`/data/.state`
+ * + `/data/.secrets`), because there the persistence boundary is the MOUNT POINT: anything under it
+ * survives. AgentCore has no volume. Its persistence boundary is `packStateRoot(stateRoot)` — the one
+ * directory tree the S3 snapshot copies out and back (channels/agentcore-state.ts) — while {@link MOUNT}
+ * itself is wiped on every runtime version update, i.e. on every deploy.
+ *
+ * So the sibling layout would put credentials INSIDE the mount but OUTSIDE the snapshot: nothing
+ * copies them out, the platform wipes them, and the next microVM re-seeds the deploy-time copy. With
+ * single-use OAuth refresh tokens that is a slow-motion outage — the box works until the seeded token
+ * is rotated away, then loses model access with only a redeploy to restore it.
+ *
+ * Nesting is what makes agentcore-state.ts's stated contract ("restores VERBATIM — including
+ * auth.json") reachable at all; `packStateRoot` walks the whole tree, so no snapshot code knows about
+ * this. Tests assert the containment, not just the two names — the sibling spelling looks tidier and
+ * reintroduces the outage silently.
+ */
+export const SECRETS_DIR = `${MOUNT}/${SECRETS_DIRNAME}`;
 /**
  * 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
@@ -72,6 +94,13 @@ export const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agent
 export function isGeneratedAgentcoreTemplate(content) {
     return content.startsWith(GENERATED_TEMPLATE_MARKER);
 }
+/** Deployment base name from the workspace basename — the ONE mapping used to find its stack later. */
+export function agentcoreName(workspaceBasename) {
+    return (workspaceBasename
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "agent");
+}
 /** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
 export function toRuntimeName(basename) {
     const slug = basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
@@ -437,6 +466,10 @@ function template(input, translated) {
         `        PORT: "8080"`, // the Runtime service contract's fixed port (config.http.port does not apply here)
         `        FASTAGENT_AGENTCORE: "1"`, // serve mounts /invocations + /ping, arms no resident cron
         `        FASTAGENT_STATE_DIR: ${MOUNT}`,
+        // Inside the state root on purpose — the snapshot is this host's only durable store, and it copies
+        // exactly one tree. See {@link SECRETS_DIR}: the sibling layout every other host uses would leave a
+        // rotated OAuth credential outside it, i.e. discarded with the microVM.
+        `        FASTAGENT_SECRETS_DIR: ${SECRETS_DIR}`,
     ];
     // The auth seed is chunked (env values max 2048 chars — see AUTH_SEED_CHUNK_SIZE): N parameters,
     // each riding its own env var; `start` reassembles them (collectAuthSeed). Empty defaults = unused.
@@ -538,7 +571,7 @@ function template(input, translated) {
         ...envLines,
     ];
     if (needsForwarder) {
-        lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # mint the presigned URLs the container uses for its state snapshot`, `                Action: [s3:GetObject, s3:PutObject]`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}/${STATE_KEY}`, ...(input.selfSchedule
+        lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # mint the presigned URLs the container uses for its state snapshot`, `                Action: [s3:GetObject, s3:PutObject]`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}/${STATE_KEY}`, `              # Without s3:ListBucket, S3 folds "key absent" into 403 (anti-enumeration), which is`, `              # indistinguishable from a broken signature — so the container's restore contract`, `              # (agentcore-state.ts: ONLY 404 means first deploy) would dead-end every first deploy.`, `              # Scoped to the snapshot prefix: this grants "may know whether the snapshot exists",`, `              # not a listing of the whole deployment bucket.`, `              - Effect: Allow`, `                Action: s3:ListBucket`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}`, `                Condition:`, `                  StringLike: { s3:prefix: state/* }`, ...(input.selfSchedule
             ? [
                 `              - Effect: Allow # wake alarms: mirror pending wake-ups into one-shot schedules`,
                 `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule]`,
@@ -679,7 +712,12 @@ export function planAgentcoreDeploy(input) {
         ? `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`
         : `# 4. Read the outputs (the runtime ARN — this topology has NO public URL: nothing outside AWS`, ...(needsFunctionUrl
         ? []
-        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`);
+        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery filters to [runtime-logs], excluding OTEL/spans AWS stores in the same log group:`, `fastagent logs agentcore --follow`, ...(needsForwarder
+        ? [
+            `# The ingress transport is a separate Lambda and therefore a separate log source:`,
+            `fastagent logs agentcore --source forwarder --follow`,
+        ]
+        : []));
     // Model-auth guidance mirrors the other hosts: an env key became a parameter above; OAuth/stored
     // can't be read at plan time — `--run` carries it as FastagentAuthSeed.
     if (!isEnvKey(input.modelAuth)) {
@@ -716,6 +754,6 @@ export function planAgentcoreDeploy(input) {
     if (needsForwarder) {
         runbook.push(``, `# After a REDEPLOY, stop the ingress session so the new image serves immediately — a live session`, `# keeps its old compute (and the OLD image) until ${IDLE_TIMEOUT_SECONDS}s idle / the 8 h compute ceiling`, `# (\`--run\` does this automatically):`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`);
     }
-    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`);
+    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`, `# CREDENTIALS RIDE THAT SNAPSHOT TOO: FASTAGENT_SECRETS_DIR is ${SECRETS_DIR}, inside the state`, `# root, so an OAuth auth.json ROTATED on the box persists (a refresh token is single-use — without`, `# this the next microVM would re-seed the deploy-time copy and eventually fail to authenticate).`, `# The bucket is therefore credential storage: it is created with public access blocked and`, `# versioning on, and deleting it costs model access until the next deploy re-seeds.`);
     return { artifacts, runbook, untranslatableSchedules: untranslatable };
 }

package/dist/deploy/container.js

@@ -128,8 +128,10 @@ CMD ["./${into("node_modules/.bin/fastagent")}", "start", "/app"]
 /** Patterns are RECURSIVE (`**​/`) on purpose — dockerignore patterns are root-anchored (unlike
  *  .gitignore), and a baked workspace can hold nested projects: a bare `node_modules` would upload
  *  their build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the
- *  image. `.secrets`/`.state` are fastagent machinery — secrets travel through the host's secret
- *  store, state lives on the volume; neither may ever enter an image. `.cache` is generic hygiene
+ *  image. `.secrets`/`.state` are fastagent machinery — credential contents travel through the host's
+ *  secret store and state lives on the volume, so neither may enter an image. The two tracked secrets
+ *  scaffolds (`.env.example` + `.gitignore`) are the narrow exception: they carry no values and must stay
+ *  beside the shipped `.git`, or the image starts with tracked deletions. `.cache` is generic hygiene
  *  (a baked project's own build cache), not a fastagent directory.
  *  `.git` is deliberately SHIPPED: the deployed agent's write-back (pull/commit/push) needs the
  *  repo's history+remote — the WYSIWYG bake's freshness/durability loop runs through git, driven by
@@ -145,12 +147,13 @@ const dockerignore = (input) => DOCKERIGNORE_BASE +
         .join("");
 const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to take ownership (deploy then keeps your file).
 **/node_modules
-**/${SECRETS_DIRNAME}
+**/${SECRETS_DIRNAME}/**
 **/${STATE_DIRNAME}
 **/.cache
 **/.env
 **/.env.*
 !**/.env.example
+!**/${SECRETS_DIRNAME}/.gitignore
 **/*.log
 # .git is deliberately shipped: the agent can pull to freshen content and push its work back
 # (the generated image installs the git binary when this directory ships a .git; otherwise

package/dist/deploy/preflight.js

@@ -12,6 +12,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
+import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
 import { inspectChannels } from "../engines/pi/channel.js";
@@ -341,6 +342,23 @@ export async function preflightDeploy(input) {
         shipsGit,
     };
     const port = config.http?.port ?? 8787;
+    // `http.host` travels in the artifact (config is what deploy ships), and any non-wildcard value that
+    // is right on a laptop is wrong in a container: the wildcard bind is what makes the published port,
+    // the health check and webhook ingress reachable at all. `--bind` is the local-only knob; config is not.
+    const configBind = classifyBind(config.http?.host);
+    if (configBind !== "wildcard") {
+        const issue = `fastagent.config.ts sets http.host: "${config.http?.host}" — it travels into the image, where ` +
+            (configBind === "loopback"
+                ? `nothing outside the container can reach the serve (published port, health check, webhooks).`
+                : `that address does not exist, so the container fails to bind at start.`) +
+            ` Drop it and use \`--bind ${config.http?.host}\` locally instead.`;
+        // Same disposition as the model-travel issue: warn when producing artifacts (the operator may be
+        // deploying somewhere that fronts the port), gate `--run` — which would otherwise ship a box that
+        // answers nothing, or crash-loops on a bind that cannot resolve inside the container.
+        if (run)
+            return { ok: false, gate: issue };
+        messages.push({ level: "warn", text: issue });
+    }
     // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
     // secrets: listed in the runbook, set from the local env under --run, gated if a value is missing.
     const extraSecrets = config.deploy?.secrets ?? [];

package/dist/engines/pi/config.d.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import { type AnyModel } from "./harness.ts";
+import type { AnyModel } from "./harness.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
@@ -12,8 +12,11 @@ export interface FastagentConfig {
     /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
      *  plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
+    /** `host` is the bind address: unset (or `0.0.0.0`) binds all interfaces — what containers need;
+     *  `127.0.0.1` keeps the serve (including `/control/*`) off the LAN. Precedence: `--bind` > this. */
     http?: {
         port?: number;
+        host?: string;
     };
     /** Mount the built-in `wake` tool so the agent can schedule its OWN follow-up turns (self-scheduling).
      *  Off by default — self-scheduling is an autonomy capability, opt in when you want it. Only takes
@@ -24,8 +27,9 @@ export interface FastagentConfig {
      * steer/abort/compact/set_model…) for remote consumers: a Web panel, a desktop app, `fastagent
      * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
      * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
-     * binds all interfaces, so the routes are LAN-reachable with the token as the only protection —
-     * firewall the port, or wrap it for real exposure (design §14).
+     * binds all interfaces by default, so the routes are LAN-reachable with the token as the only
+     * protection — bind loopback (`--bind 127.0.0.1`; not `http.host`, which travels into a deployed
+     * image), firewall the port, or wrap it for real exposure (design §14).
      */
     sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a

package/dist/engines/pi/config.js

@@ -20,7 +20,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { THINKING_LEVELS } from "./harness.js";
+import { THINKING_LEVELS } from "./session-settings.js";
+import { isBindAddress } from "../../bind.js";
 import { moduleLoadHint } from "../../loader.js";
 import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
@@ -116,13 +117,18 @@ export async function loadConfig(dir) {
         throw new Error(`${path}: "http" must be an object`);
     }
     for (const key of Object.keys(c.http ?? {})) {
-        if (key !== "port") {
-            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port)`);
+        if (key !== "port" && key !== "host") {
+            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port, host)`);
         }
     }
     if (c.http?.port !== undefined && (typeof c.http.port !== "number" || !isValidPort(c.http.port))) {
         throw new Error(`${path}: "http.port" must be an integer 0-65535`);
     }
+    // Validated as strictly as http.port: an unbindable string ("banana") must fail HERE, not surface
+    // later as a topology diagnostic about "the interface you bound".
+    if (c.http?.host !== undefined && (typeof c.http.host !== "string" || !isBindAddress(c.http.host))) {
+        throw new Error(`${path}: "http.host" must be an IP address or "localhost" (e.g. "127.0.0.1", "0.0.0.0")`);
+    }
     if (c.deploy !== undefined && (typeof c.deploy !== "object" || c.deploy === null)) {
         throw new Error(`${path}: "deploy" must be an object`);
     }