@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/cli/commands/start.js

@@ -4,77 +4,139 @@
  */
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { authSeedBytes } from "../../deploy/fly/run.js";
+import { authSeedBytes, collectAuthSeed } from "../../deploy/fly/run.js";
 import { loadDotEnv } from "../../env.js";
 import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
+import { resolveSecretsDir, workspaceHint } from "../../paths.js";
 import { isUnderDir } from "../../engines/pi/definition.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
-import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { log, setLogLevel } from "../../log.js";
+import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
+import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
-import { exists } from "../../scaffold/init.js";
-import { failStartup } from "../fail.js";
-import { maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
+import { exists } from "../../paths.js";
+import { bindAddress } from "../../bind.js";
+import { failStartup, placementOrExit } from "../fail.js";
+import { assertTunnelBindable, maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules, } from "../serve.js";
+import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
-    setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
+    // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
+    // the directory being an agent (which is a runtime/environment failure, exit 1).
     const portFlag = parsePort(opts.port, "--port", "flag");
-    loadDotEnv(dir);
+    const bindFlag = parseBind(opts.bind);
+    const placement = placementOrExit(dir);
+    setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
+    loadDotEnv(placement.agentDir);
     installProxyFetch();
-    await resolveFirstRunModel(dir, opts);
+    await resolveFirstRunModel(placement.agentDir, opts);
     // A `deploy --run` may carry the operator's local credential as FASTAGENT_AUTH_SEED —
-    // materialize it onto the writable state root BEFORE the opener resolves auth (once, absent-only).
+    // materialize it into the writable secrets dir BEFORE the opener resolves auth (once, absent-only).
     // Same resolveAuthPath the opener uses — ONE owner of the flag > env > default chain.
-    await maybeSeedAuth(resolveAuthPath(dir, opts.authPath));
+    await maybeSeedAuth(resolveAuthPath(placement.agentDir, opts.authPath));
     // The same opener dev uses (single assembly source), just no watch.
     const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
-    const { agent, definition, agentDir, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, sessionControl, } = await createPiAgentFromWorkspace(dir, {
+    const { agent, definition, agentDir, workspace, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, sessionControl, } = await createPiAgentFromDir(dir, {
         model: opts.model,
         sessionsDir: sessionsDirOverride,
         authPath: opts.authPath,
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
-    log.info(`[fastagent] start:  ${dir}`);
-    if (agentDir !== dir)
-        log.info(`[fastagent] agent:  ${agentDir}`);
-    log.info(`[fastagent] model:  ${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
+    reportLine("agent", agentDir);
+    reportLine("workspace", workspace);
+    reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
+    reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
     await reportAuth(modelSpec, authPath);
-    log.info(`[fastagent] context: ${definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
+    reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (definition.persona)
-        log.info(`[fastagent] persona: persona.md`);
-    log.info(`[fastagent] skills: ${definition.skills.map((s) => s.name).join(", ") || "(none)"}`);
+        reportLine("persona", "persona.md");
+    reportLine("skills", definition.skills.map((s) => s.name).join(", ") || "(none)");
     if (toolNames.length > 0)
-        log.info(`[fastagent] tools:  ${toolNames.join(", ")}`);
+        reportLine("tools", toolNames.join(", "));
     if (deferredToolNames.length > 0) {
-        log.info(`[fastagent] deferred: ${deferredToolNames.join(", ")} (activated via search_tools)`);
+        reportLine("deferred", `${deferredToolNames.join(", ")} (activated via search_tools)`);
     }
     reportToolCollisions(toolCollisions);
     reportModuleLoadFailures(toolFailures);
-    log.info(`[fastagent] state:  ${stateRoot}`);
-    log.info(`[fastagent] sessions: ${sessionsDir}`);
-    // State defaults under the definition dir, which a redeploy may replace wholesale. Gate on where the
-    // root ACTUALLY resolved (in-tree?), not on the raw env var: an empty `FASTAGENT_STATE_DIR=""` reads
-    // as unset (resolveStateRoot) and still lands in-tree, so a raw `=== undefined` check would wrongly
-    // silence the warning. A sessions/auth override to a volume does not help — channel state (the
-    // telegram turn/context files replay depends on) is still in-tree.
-    if (isUnderDir(stateRoot, dir)) {
-        log.info(`[fastagent] note: state (auth, sessions, channel state) lives under the definition dir; point ` +
+    reportLine("state", stateRoot);
+    reportLine("sessions", sessionsDir);
+    // State defaults under the agent dir, which a redeploy may replace wholesale. Gate on where the
+    // state root ACTUALLY resolved (inside the agent dir?), not on the raw env var: an empty
+    // `FASTAGENT_STATE_DIR=""` reads as unset (resolveStateRoot) and still lands in-agent, so a raw
+    // `=== undefined` check would wrongly silence the warning. A sessions override to a volume does not
+    // help — channel state (the telegram turn/context files replay depends on) is still in-agent.
+    // (auth.json is NOT under the state root — it lives in the secrets dir, resolveSecretsDir.)
+    if (isUnderDir(stateRoot, agentDir)) {
+        log.info(`[fastagent] note: state (sessions, channel state) lives under the definition dir; point ` +
             `FASTAGENT_STATE_DIR at a persistent volume so a redeploy that replaces the dir does not wipe it.`);
     }
+    // The secrets dir is the SAME trap on a different lifecycle: auth.json is MACHINE-WRITTEN (OAuth
+    // rotation), so the copy under the definition dir is the only valid one — a redeploy that replaces
+    // the dir loses a credential no re-seed can restore. An independent check on purpose: moving ONE
+    // of the two to a volume must not silence the note about the other.
+    if (isUnderDir(resolveSecretsDir(agentDir), agentDir)) {
+        log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
+            `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
+    }
     reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    // AgentCore Runtime posture (FASTAGENT_AGENTCORE=1, set by the generated deploy artifacts): the
+    // adapter (POST /invocations + GET /ping) is the container's only reachable surface, and cron
+    // slots arrive from the external clock through it — so no resident cron timers. In particular,
+    // do NOT mount the ordinary unauthenticated POST /invoke fallback: a selfSchedule-only topology
+    // needs a public Function URL for wake callbacks, and its forwarder can relay arbitrary paths.
+    const agentcore = process.env.FASTAGENT_AGENTCORE === "1";
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
-    const routed = await routesFor(agentDir, traced, stateRoot, sessionControl).catch(failStartup);
+    const routed = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: !agentcore }).catch(failStartup);
+    // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
+    // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
+    const configured = config.http?.host;
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
     const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced,
+        host,
     });
-    await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false);
-    serve({ ...routed, routes: withControl.routes }, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => {
+    // AgentCore + selfSchedule: register the wake-ALARM sink BEFORE the scheduler starts — the boot
+    // wake pump may advance a recurring entry (a store save) and that save must already re-arm its
+    // alarm. The secret arrives via the stack (FASTAGENT_WAKE_SECRET); without it the deployment
+    // degrades to awake-only wakes — warned, never silent.
+    let onStateReady;
+    if (agentcore && config.selfSchedule) {
+        const wakeSecret = process.env.FASTAGENT_WAKE_SECRET;
+        if (wakeSecret) {
+            const sink = createWakeAlarmSink({ secret: wakeSecret });
+            setWakeupsSink(sink);
+            // NOT here: at boot the state mount is whatever the platform just provisioned — after a runtime
+            // version update that is EMPTY, so a reconcile now would see no pending wake-ups and conclude
+            // there is nothing to re-arm. It runs once the snapshot has been restored (mountAgentcore).
+            onStateReady = () => reconcileWakeAlarms(stateRoot, sink);
+            log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
+        }
+        else {
+            log.warn(`[fastagent] FASTAGENT_WAKE_SECRET is not set — wake-ups fire only while a session is awake ` +
+                `(redeploy with the current template to fix)`);
+        }
+    }
+    const schedules = await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false, {
+        externalClock: agentcore,
+    });
+    let routes = withControl.routes;
+    if (agentcore) {
+        try {
+            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady });
+        }
+        catch (e) {
+            failStartup(e);
+        }
+        log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
+    }
+    serve({ ...routed, routes }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
-        maybeTunnel(dir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
+        maybeTunnel(agentDir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
     });
     // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
     // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK
@@ -82,13 +144,15 @@ export async function runStart(dirArg, opts) {
     // channels have no such layer, so their in-flight turns are still lost (the asker re-invokes).
 }
 /**
- * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) onto the
- * writable state root ONCE — only when the seed is set AND the auth file is absent, so a refreshed
+ * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) into the
+ * writable secrets dir ONCE — only when the seed is set AND the auth file is absent, so a refreshed
  * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
  * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
  */
 async function maybeSeedAuth(authPath) {
-    const bytes = authSeedBytes(process.env.FASTAGENT_AUTH_SEED, await exists(authPath));
+    // collectAuthSeed: the seed may arrive CHUNKED (FASTAGENT_AUTH_SEED + _2…) on hosts with a small
+    // env-value max length (AgentCore); single-var hosts are unchanged.
+    const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
     if (!bytes)
         return;
     await mkdir(dirname(authPath), { recursive: true });

package/dist/cli/commands/tool.js

@@ -1,20 +1,23 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
-import { resolveWorkspaceTools } from "../../engines/pi/create.js";
+import { loadConfig } from "../../engines/pi/config.js";
+import { resolveAgentTools } from "../../engines/pi/create.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
 import { turnContext } from "../../engines/pi/tool-context.js";
-import { failStartup, failUsage } from "../fail.js";
+import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
-    const toolDir = resolve(dirArg);
-    loadDotEnv(toolDir); // a tool may read a key from .env
-    const { config } = await loadConfig(toolDir).catch(failStartup);
+    // Argument shape first: malformed JSON is a USAGE error (exit 2), independent of whether the
+    // directory is an agent (a runtime failure, exit 1).
+    const args = parseToolArgs(argsJson);
+    const { agentDir, workspace } = placementOrExit(resolve(dirArg));
+    loadDotEnv(agentDir); // a tool may read a key from .env
+    const { config } = await loadConfig(agentDir).catch(failStartup);
     // The same tool set dev/start mount (defaults + config.tools + discovered, deduped), so the runner
-    // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve agentDir
-    // like the openers so `fastagent tool` finds the SAME tools/ as dev/start when config.agentDir is set.
-    const agentDir = resolveAgentDir(toolDir, config);
-    const { tools, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, toolDir).catch(failStartup);
+    // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve the
+    // placement like the openers, so `fastagent tool` finds the SAME tools/ as dev/start.
+    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir).catch(failStartup);
     for (const c of toolCollisions) {
         console.error(`[fastagent] warn: tool "${c.name}" (${c.source}) is shadowed by a default/config tool — not mounted`);
     }
@@ -23,16 +26,25 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    let args;
-    try {
-        args = JSON.parse(argsJson);
-    }
-    catch {
-        failUsage(`invalid JSON args: ${argsJson}`); // malformed input syntax = usage error, exit 2
-    }
-    const result = await turnContext.run({ cwd: toolDir }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
+    // Two contexts, because the two tool families read different ones and this command must serve both
+    // exactly as serving does: fastagent's own tools take cwd/session/activation from `turnContext`
+    // (AsyncLocalStorage), and pi's default coding tools take the ExecutionEnv from the harness's TOOL
+    // context — which no harness supplies here, so this stands in for it, rooted at the same workspace.
+    const env = new NodeExecutionEnv({ cwd: workspace });
+    const result = await turnContext
+        .run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args, undefined, undefined, { env }))
+        .catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");
     console.log(typeof out === "string" ? out : JSON.stringify(out, null, 2));
 }
+/** Parse the CLI's JSON args blob; malformed input syntax is a usage error (exit 2). */
+function parseToolArgs(argsJson) {
+    try {
+        return JSON.parse(argsJson);
+    }
+    catch {
+        failUsage(`invalid JSON args: ${argsJson}`);
+    }
+}

package/dist/cli/fail.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedPlacement } from "../paths.ts";
 /**
  * The ONE error prefix every error message carries — bold red when stderr renders color, plain
  * otherwise. Errors are the only place the CLI uses color at all.
@@ -9,6 +10,22 @@ export declare function errorPrefix(colors?: boolean): string;
  * Shared by the kernel and the command modules; exit 1 (runtime failure).
  */
 export declare function failStartup(error: unknown): never;
+/**
+ * THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. Every
+ * command that needs an agent goes through this — the try/catch was hand-repeated at sixteen call
+ * sites, which is sixteen chances to forget it (`dev`'s supervisor did, and surfaced a raw stack).
+ *
+ * The catch is what makes it a function at all: placement resolves SYNCHRONOUSLY, before any promise
+ * exists, so it cannot ride the `.catch(failStartup)` every async startup chain carries — and its
+ * refusals ("not a fastagent agent", plus the two dead ends with their own exits) are user-fixable,
+ * which means a one-line `Error:` and exit 1, never a stack.
+ *
+ * Not every command calls it — and the exceptions are the useful part of this note. `init` CREATES the
+ * agent (it must run where there is none). `models` is directory-independent. `login` needs one only for
+ * the project-level credential and falls back to the global one, and `attach --url/--token` reads
+ * nothing local. Everything else needs an agent, so it comes through here.
+ */
+export declare function placementOrExit(dir: string): ResolvedPlacement;
 /**
  * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
  * discovered in a command body): print the message and exit 2 — the same class as a parse error.

package/dist/cli/fail.js

@@ -1,3 +1,4 @@
+import { resolvePlacement } from "../paths.js";
 /** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
 function stderrHasColors() {
     return process.stderr.isTTY === true && (process.stderr.hasColors?.() ?? false);
@@ -21,6 +22,29 @@ export function failStartup(error) {
         console.error(errorPrefix(), error);
     process.exit(1);
 }
+/**
+ * THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. Every
+ * command that needs an agent goes through this — the try/catch was hand-repeated at sixteen call
+ * sites, which is sixteen chances to forget it (`dev`'s supervisor did, and surfaced a raw stack).
+ *
+ * The catch is what makes it a function at all: placement resolves SYNCHRONOUSLY, before any promise
+ * exists, so it cannot ride the `.catch(failStartup)` every async startup chain carries — and its
+ * refusals ("not a fastagent agent", plus the two dead ends with their own exits) are user-fixable,
+ * which means a one-line `Error:` and exit 1, never a stack.
+ *
+ * Not every command calls it — and the exceptions are the useful part of this note. `init` CREATES the
+ * agent (it must run where there is none). `models` is directory-independent. `login` needs one only for
+ * the project-level credential and falls back to the global one, and `attach --url/--token` reads
+ * nothing local. Everything else needs an agent, so it comes through here.
+ */
+export function placementOrExit(dir) {
+    try {
+        return resolvePlacement(dir);
+    }
+    catch (error) {
+        failStartup(error);
+    }
+}
 /**
  * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
  * discovered in a command body): print the message and exit 2 — the same class as a parse error.

package/dist/cli/program.js

@@ -8,14 +8,18 @@ import { fastagentVersion } from "../version.js";
 import { buildProgram } from "./kernel.js";
 // Help groups (clig: most common commands first) — the authoring loop leads, operations close.
 // Shared flags — same name, same meaning, on every command that supports them (clig: consistency).
-const DIR_ARG = { name: "[dir]", description: "workspace directory", default: "." };
+const DIR_ARG = {
+    name: "[dir]",
+    description: "workspace directory (the agent is here, or in a directory inside it)",
+    default: ".",
+};
 const MODEL = {
     flags: "--model <provider/modelId>",
     description: "model override (precedence: --model > FASTAGENT_MODEL > config)",
 };
 const AUTH_PATH = {
     flags: "--auth-path <file>",
-    description: "credentials file (default: <state root>/auth.json; env: FASTAGENT_AUTH_PATH)",
+    description: "credentials file (default: <agent dir>/.secrets/auth.json; env: FASTAGENT_AUTH_PATH)",
 };
 const JSON_FLAG = { flags: "--json", description: "machine-readable JSON output" };
 const NO_INPUT = {
@@ -23,6 +27,10 @@ const NO_INPUT = {
     description: "never prompt (CI/scripts) — missing information becomes an error instead of a question",
 };
 const PORT = { flags: "--port <n>", description: "HTTP port" };
+const BIND = {
+    flags: "--bind <addr>",
+    description: "bind address (default: all interfaces; 127.0.0.1 keeps it off the LAN)",
+};
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
@@ -32,31 +40,43 @@ const TUNNEL = {
 const init = {
     name: "init",
     summary: "scaffold a runnable agent and install its dependencies",
-    description: "Scaffold a runnable agent in dir (default .) and run npm install. Default is a self-iterating " +
-        "agent: persona.md (its identity), a writing-great-skills example skill, a fetch-url code tool, " +
-        "config, package.json, .gitignore. Never overwrites existing files; an existing AGENTS.md is kept " +
-        "as project context.",
+    description: "Scaffold a runnable agent and run npm install. By default the agent goes into ./fastagent/ in dir " +
+        "(default .; --agent-dir names it otherwise) — the rest of the directory gets zero writes, and it is " +
+        "the WORKSPACE the agent works ON when you point fastagent there. Default content is a " +
+        "self-iterating agent: persona.md (its identity), a writing-great-skills " +
+        "example skill, a fetch-url code tool, config, package.json, .gitignore. An existing AGENTS.md is " +
+        "kept as project context.",
     args: [DIR_ARG],
     flags: [
         { flags: "--minimal", description: "persona.md + the example skill + config only (no code tool / package.json)" },
         { flags: "--no-install", description: "scaffold everything but skip npm install" },
-        { flags: "--flat", description: "force the flat layout (skip host-signal detection)", conflicts: ["agentDir"] },
-        { flags: "--agent-dir <name>", description: "force the agent kit into ./<name>" },
+        { flags: "--agent-dir <name>", description: "name the agent directory (default fastagent; . = dir itself)" },
+        {
+            flags: "--flat",
+            description: "alias for --agent-dir . — the directory IS the agent; keeps existing files",
+            // Two spellings of ONE knob: `--flat --agent-dir bot` names the same thing twice with different
+            // values, which is a usage error, not a precedence question to settle silently.
+            conflicts: ["agentDir"],
+        },
     ],
     examples: [
-        { cmd: "fastagent init my-agent", note: "a new agent dir, ready to dev" },
-        { cmd: "fastagent init", note: "initialize the current directory" },
+        { cmd: "fastagent init", note: "the agent lands in ./fastagent/" },
+        { cmd: "fastagent init my-project", note: "my-project/fastagent/ (created)" },
+        { cmd: "fastagent init . --agent-dir bot", note: "./bot/ — any name works" },
+        { cmd: "fastagent init . --flat", note: "this repo IS the agent" },
     ],
-    notes: 'Layout: flat by default ("a directory is an agent"); when an existing toolchain/deploy claims ' +
-        "the directory (tsconfig/framework config, a non-JS build manifest like " +
-        "go.mod/pyproject.toml/Cargo.toml, Dockerfile/fly/railway, or occupied tools/, channels/, or " +
-        "skills/), the kit goes into ./agent and config.agentDir points there — the reason is printed, " +
-        "no prompt.",
+    notes: "An agent is a directory holding a fastagent.config.* — never its NAME, so --agent-dir can call it " +
+        "anything (the name decides only which agent answers when a workspace holds several: see " +
+        "FASTAGENT_AGENT). What the agent works ON (its cwd, where its AGENTS.md context is read from) is " +
+        "whatever directory you later point fastagent at: point at the project and the agent inside it " +
+        "serves with the project as its workspace; point at the agent directory (all a deployed box may " +
+        "hold) and it works on itself. A directory resolves to ONE agent, at it or one level inside.",
     run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
         minimal: f.minimal === true,
         install: f.install !== false,
-        flat: f.flat === true,
-        agentDir: f.agentDir,
+        // `--flat` is the spelling for the common case of the same knob (they conflict, so only one is
+        // ever set); both land in ONE value, so the scaffolder never sees two ways to say ".".
+        agentDir: f.flat === true ? "." : typeof f.agentDir === "string" ? f.agentDir : undefined,
     }),
 };
 const dev = {
@@ -64,11 +84,12 @@ const dev = {
     summary: "serve the agent locally, restarting on code edits",
     description: "Assemble the agent in dir (default .) and serve a local HTTP channel. persona.md/AGENTS.md/skills " +
         "are re-read every turn (edits go live next turn); edits to code inputs — tools/, channels/, " +
-        "fastagent.config.*, package.json, .env — restart the worker. Files the agent writes as work " +
-        "product never trigger a restart.",
+        "fastagent.config.*, package.json, .secrets/.env — restart the worker. Files the agent writes as " +
+        "work product never trigger a restart.",
     args: [DIR_ARG],
     flags: [
         PORT,
+        BIND,
         MODEL,
         AUTH_PATH,
         { flags: "--no-watch", description: "serve once, no file-watching" },
@@ -81,6 +102,7 @@ const dev = {
     ],
     run: async (args, f) => (await import("./commands/dev.js")).runDev(args[0], {
         port: f.port,
+        bind: f.bind,
         model: f.model,
         authPath: f.authPath,
         watch: f.watch !== false,
@@ -202,6 +224,7 @@ const start = {
     args: [DIR_ARG],
     flags: [
         PORT,
+        BIND,
         MODEL,
         { flags: "--sessions-dir <dir>", description: "sessions directory override" },
         AUTH_PATH,
@@ -214,16 +237,18 @@ const start = {
     ],
     notes: "Precedence chains:\n" +
         "  port:     --port > PORT env > fastagent.config.ts http.port > 8787\n" +
-        "  state:    FASTAGENT_STATE_DIR > <dir>/.fastagent — the ONE machine-state\n" +
-        "            root (auth, sessions, channel state all derive from it); point\n" +
-        "            it at a mounted volume so a redeploy that replaces the\n" +
-        "            directory never wipes state\n" +
+        "  bind:     --bind > fastagent.config.ts http.host > all interfaces\n" +
+        "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state — mutable machine state\n" +
+        "            (sessions, channel state, schedule state); point it at a mounted\n" +
+        "            volume so a redeploy that replaces the directory never wipes it\n" +
+        "  secrets:  FASTAGENT_SECRETS_DIR > <agent dir>/.secrets — .env + auth.json\n" +
         "  sessions: --sessions-dir > FASTAGENT_SESSIONS_DIR > <state>/sessions\n" +
-        "  auth:     --auth-path > FASTAGENT_AUTH_PATH > <state>/auth.json\n" +
-        "            (project-level; point it at ~/.fastagent/auth.json to share one\n" +
-        "            credential across projects)",
+        "  auth:     --auth-path > FASTAGENT_AUTH_PATH > <secrets>/auth.json\n" +
+        "            (project-level; point it at ~/.fastagent/.secrets/auth.json to\n" +
+        "            share one credential across projects)",
     run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
         port: f.port,
+        bind: f.bind,
         model: f.model,
         sessionsDir: f.sessionsDir,
         authPath: f.authPath,
@@ -286,7 +311,7 @@ const add = {
             "message pump, and an optional route() policy."),
         channelSub("slack", "scaffold the Slack Events API channel (files, threads, context, live preview)", "Choose group visibility, scaffold channels/slack.ts plus slack-send.ts, create a single-workspace " +
             "internal Slack app from a manifest, and install it through OAuth. The channel provides signed " +
-            "Events API ingress, durable turns, files, managed threads, context, and an edited live preview.", "Automated onboarding requires Slack App Configuration access + refresh tokens and a temporary " +
+            "Events API ingress, durable turns, files, threads, context, and an edited live preview.", "Automated onboarding requires Slack App Configuration access + refresh tokens and a temporary " +
             "cloudflared tunnel. They stay in owner-readable local state and are never deployed; --no-onboard " +
             "keeps the explicit manual/scaffold-only path."),
         channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Choose WebSocket or webhook, scaffold channels/feishu.ts, and create/configure the Feishu app " +
@@ -324,19 +349,22 @@ const add = {
 };
 const deploy = {
     name: "deploy",
-    summary: "generate deploy artifacts + a runbook for docker, fly, or railway (--run drives it)",
+    summary: "generate deploy artifacts + a runbook for docker, fly, railway, or agentcore (--run drives it)",
     description: "Generate Dockerfile/.dockerignore plus the target config and print an ordered runbook. " +
         "docker: fastagent.compose.yml, loopback port, persistent state volume. fly: fly.toml " +
         "(autostop=suspend, state→volume). railway: railway.json (healthcheck /health); its " +
-        "volume/variables/App-Sleeping are dashboard/CLI steps the runbook states. Durable ingress " +
-        "remains operator-owned.",
-    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway"] }, DIR_ARG],
+        "volume/variables/App-Sleeping are dashboard/CLI steps the runbook states. agentcore: one " +
+        "CloudFormation stack (AWS Bedrock AgentCore Runtime + forwarder Lambda for webhooks + " +
+        "EventBridge rules for schedules; linux/arm64 image built locally). Durable ingress " +
+        "remains operator-owned (agentcore's forwarder URL is the exception — the stack owns it).",
+    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway", "agentcore"] }, DIR_ARG],
     flags: [
         {
             flags: "--run",
             description: "drive the target CLI to completion. Docker runs `docker compose up -d --build`; with a tunnel " +
                 "service, reads its URL and registers webhooks. Fly/Railway provision app/service + volume + " +
-                "secrets + deploy + webhook setup. Carries your local credential (env key or OAuth auth.json). " +
+                "secrets + deploy + webhook setup. AgentCore builds/pushes the arm64 image and deploys the " +
+                "stack (aws + docker CLIs). Carries your local credential (env key or OAuth auth.json). " +
                 "Stops at a gate (missing CLI/daemon/login/secret) with one actionable line. Without it: prints " +
                 "the runbook",
         },
@@ -367,6 +395,7 @@ const deploy = {
         { cmd: "fastagent deploy fly --run", note: "provision + deploy + webhooks" },
         { cmd: "fastagent deploy docker --tunnel --run", note: "Compose + a public URL" },
         { cmd: "fastagent deploy railway", note: "print the runbook only" },
+        { cmd: "fastagent deploy agentcore --run", note: "arm64 image + stack + webhooks" },
     ],
     notes: "Definition-read-only: the only writes are generated artifacts (never clobbered without " +
         "--force). A routine redeploy of an already-provisioned agent is just the host's own command " +
@@ -427,10 +456,11 @@ const schedule = {
 const login = {
     name: "login",
     summary: "authenticate a model provider (subscription/OAuth or API key)",
-    description: "Authenticate a model provider into the project-level <state root>/auth.json — default " +
-        "<cwd>/.fastagent/auth.json (run from $HOME for the global ~/.fastagent/auth.json): pick a method " +
-        "(subscription/OAuth or API key), then a provider that offers it (configured status shown). " +
-        "[provider] takes the method from what that provider supports, asked only when both.",
+    description: "Authenticate a model provider into the project-level <agent dir>/.secrets/auth.json (outside an " +
+        "agent it writes the global ~/.fastagent/.secrets/auth.json, and says so): pick a method " +
+        "(subscription/OAuth or API " +
+        "key), then a provider that offers it (configured status shown). [provider] takes the method from " +
+        "what that provider supports, asked only when both.",
     args: [{ name: "[provider]", description: "provider id (skip the provider menu)" }],
     flags: [AUTH_PATH, NO_INPUT],
     examples: [{ cmd: "fastagent login" }, { cmd: "fastagent login openai" }],