@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/dist/cli/commands/deploy.js

@@ -7,56 +7,65 @@
  * Read-only on the definition; the only writes are generated artifacts (never clobbered without
  * --force). `--run` drives the target CLI instead of printing.
  */
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { registerFeishuWebhook } from "../../channels/feishu/register-webhook.js";
 import { readSlackBotAuthEnv } from "../../channels/slack/bot-auth.js";
 import { registerSlackWebhook } from "../../channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "../../channels/telegram/register-webhook.js";
-import { isGeneratedDockerfile } from "../../deploy/container.js";
+import { FORWARDER_FILE, TEMPLATE_FILE, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../deploy/agentcore/plan.js";
+import { deployAgentcoreRun } from "../../deploy/agentcore/run.js";
+import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../deploy/container.js";
 import { composeHasTunnelService, dockerWebhookPaths, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../deploy/docker/plan.js";
 import { deployDockerRun } from "../../deploy/docker/run.js";
-import { parseFlyAppName, parseFlyMinMachines, parseFlyRegion, planFlyDeploy, toFlyAppName, } from "../../deploy/fly/plan.js";
+import { isGeneratedFlyToml, parseFlyAppName, parseFlyMinMachines, parseFlyRegion, planFlyDeploy, toFlyAppName, } from "../../deploy/fly/plan.js";
 import { deployFlyRun } from "../../deploy/fly/run.js";
 import { preflightDeploy } from "../../deploy/preflight.js";
-import { planRailwayDeploy } from "../../deploy/railway/plan.js";
+import { dockerfilePathVar, isGeneratedRailwayJson, planRailwayDeploy } from "../../deploy/railway/plan.js";
 import { deployRailwayRun } from "../../deploy/railway/run.js";
 import { spawnRunner } from "../../deploy/runner.js";
 import { assembleSecrets } from "../../deploy/secrets.js";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir, resolveModelSpec, resolveStateRoot } from "../../engines/pi/config.js";
+import { loadConfig, resolveModelSpec } from "../../engines/pi/config.js";
+import { resolveStateRoot } from "../../paths.js";
+import { loadSchedules } from "../../schedule/discover.js";
 import { installProxyFetch } from "../../proxy.js";
 import { openExternalUrl } from "../../open-url.js";
-import { exists } from "../../scaffold/init.js";
+import { exists } from "../../paths.js";
 import { announceWebhooks } from "../../tunnel.js";
-import { failStartup, failUsage } from "../fail.js";
+import { failStartup, failUsage, placementOrExit } from "../fail.js";
 import { resolveFirstRunModel } from "../shared.js";
 export async function runDeploy(host, dirArg, opts) {
-    const target = resolve(dirArg);
+    // ONE deploy semantic: bake the WORKSPACE (WYSIWYG). Artifacts land under the agent dir
+    // (`fastagent/`) plus the one workspace-root `.dockerignore` the packers require; host CLIs run
+    // from the workspace, which is the build context.
+    const placement = placementOrExit(resolve(dirArg));
+    const { agentDir, workspace } = placement;
     if (opts.tunnel && host !== "docker") {
         // A flag/host combination the parser cannot see (host is an argument) — usage class, exit 2.
         failUsage(`deploy stopped: --tunnel is supported only by the local Docker target`);
     }
-    loadDotEnv(target); // a custom provider/tool may read a key at config load
+    loadDotEnv(agentDir); // a custom provider/tool may read a key at config load
     installProxyFetch(); // post-deploy channel API calls must honor HTTP(S)_PROXY under Node
     // First-run funnel, FULL picker: the write-back lands the model in fastagent.config.* — exactly what
     // the model-travel gate below requires (--model/env don't reach the deployed box) — and an inline
     // login stores the credential `--run` then carries. Runs BEFORE loadConfig; the read-back sees the
     // rewritten file because loadConfig cache-busts on mtime (a failed write-back still gates, correctly).
-    await resolveFirstRunModel(target, { model: opts.model, authPath: opts.authPath, input: opts.input });
-    const { config } = await loadConfig(target).catch(failStartup);
-    const agentDir = resolveAgentDir(target, config);
+    await resolveFirstRunModel(agentDir, { model: opts.model, authPath: opts.authPath, input: opts.input });
+    const { config } = await loadConfig(agentDir).catch(failStartup);
     const modelSpec = resolveModelSpec(opts.model, config);
     // The host-neutral pre-flight (model-travel gate, channel discovery, model-auth probe, container facts +
     // their warnings) lives in deploy/preflight.ts — testable in isolation. The CLI prints its messages and
     // stops on its gate; the host branch below adds only the host-specific artifacts + runbook + run drive.
     const pre = await preflightDeploy({
-        target,
-        agentDir,
+        placement,
         config,
         modelSpec,
         run: !!opts.run,
         force: !!opts.force,
+        externalClock: host === "agentcore", // cron rides EventBridge there — the resident-host notes don't apply
         authPathFlag: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by preflight (one owner)
     }).catch(failStartup);
     if (!pre.ok)
@@ -74,7 +83,7 @@ export async function runDeploy(host, dirArg, opts) {
         if (opts.intoLinked) {
             console.error(`[fastagent] warn: --into-linked is Railway-only — ignored for local Docker`);
         }
-        const projectName = toDockerProjectName(basename(target));
+        const projectName = toDockerProjectName(basename(workspace));
         const dockerPlan = (tunnel) => planDockerDeploy({
             projectName,
             port,
@@ -92,20 +101,23 @@ export async function runDeploy(host, dirArg, opts) {
         let plan = dockerPlan(requestedTunnel);
         // An existing Compose file is authoritative: shape its comparison/runbook from the topology on disk,
         // regardless of the current flag. `--force` is the explicit reset to the requested generated shape.
-        const composeFile = join(target, plan.composePath);
+        const composeFile = join(workspace, plan.composePath);
         let keptWithoutRequestedTunnel = false;
-        if (!opts.force && (await exists(composeFile))) {
-            const existingHasTunnel = composeHasTunnelService(await readFile(composeFile, "utf8"));
+        // Same ownership question as fly.toml: a hand-owned compose file survives --force, so the plan must
+        // describe the topology that will actually be there.
+        const composeText = await readFile(composeFile, "utf8").catch(() => undefined);
+        if (composeText !== undefined && (!opts.force || !isGeneratedCompose(composeText))) {
+            const existingHasTunnel = composeHasTunnelService(composeText);
             plan = dockerPlan(existingHasTunnel);
             keptWithoutRequestedTunnel = requestedTunnel && !existingHasTunnel;
         }
-        await writeArtifacts(target, plan.artifacts, {
+        await writeArtifacts(workspace, plan.artifacts, {
             force: !!opts.force,
-            neverForce: container.kitDir ? [".dockerignore"] : [],
         });
         if (opts.run) {
             return runDeployDocker({
-                target,
+                agentDir,
+                workspace,
                 composeFile: plan.composePath,
                 port,
                 requireTunnel: requestedTunnel,
@@ -132,7 +144,7 @@ export async function runDeploy(host, dirArg, opts) {
         }
         // Railway service names are project-scoped (not globally unique like a Fly app); slug the dir
         // basename so a name with spaces/odd chars can't break the `railway add --service <name>` command.
-        const serviceName = basename(target)
+        const serviceName = basename(workspace)
             .replace(/[^a-zA-Z0-9-]+/g, "-")
             .replace(/^-+|-+$/g, "") || "agent";
         const plan = planRailwayDeploy({
@@ -144,13 +156,20 @@ export async function runDeploy(host, dirArg, opts) {
             hasTimeTriggers,
             ...container,
         });
-        await writeArtifacts(target, plan.artifacts, {
+        await writeArtifacts(workspace, plan.artifacts, {
             force: !!opts.force,
-            neverForce: container.kitDir ? [".dockerignore"] : [],
         });
         if (opts.run) {
+            // The BUILD entry is guaranteed by the RAILWAY_DOCKERFILE_PATH service variable the runner sets
+            // (Railway's documented non-root-Dockerfile route), and Railway's default restart policy already
+            // equals the file's ON_FAILURE — the dashboard-only Config-as-code pointer only adds the /health
+            // deploy gate (boot-crash visibility), so it is an OPTIONAL note, not a gate.
+            console.error(`[fastagent] note: optional — point the service at fastagent/railway.json (Service → Settings → ` +
+                `Config-as-code, dashboard-only) so the /health healthcheck marks a boot-crashing deploy as FAILED; ` +
+                `the build already uses fastagent/Dockerfile via the RAILWAY_DOCKERFILE_PATH variable`);
             return runDeployRailway({
-                target,
+                agentDir,
+                workspace,
                 name: serviceName,
                 modelAuth,
                 authPath,
@@ -158,6 +177,113 @@ export async function runDeploy(host, dirArg, opts) {
                 longConnectionChannels,
                 extraSecrets,
                 intoLinked: !!opts.intoLinked,
+                dockerfilePath: dockerfilePathVar(pre.container.agentPrefix),
+            });
+        }
+        console.log(plan.runbook.join("\n"));
+        return;
+    }
+    // AgentCore: one CloudFormation stack (runtime + forwarder Lambda + EventBridge schedules); no
+    // public URL and no resident process — see deploy/agentcore/plan.ts for the topology decisions.
+    if (host === "agentcore") {
+        if (opts.stop || opts.scaleToZero === false) {
+            console.error(`[fastagent] warn: --stop/--no-scale-to-zero are Fly-only — AgentCore's idle/lifetime policy lives in ` +
+                `the template's LifecycleConfiguration.`);
+        }
+        if (opts.intoLinked) {
+            console.error(`[fastagent] warn: --into-linked is Railway-only — ignored for AgentCore`);
+        }
+        // Long-connection channels are STRUCTURALLY unsupported: the connection is the ingress, and a
+        // reclaimed session has nothing to wake it — events in the gap are silently lost. `--run` gates
+        // (deploying a channel that can't connect); generate-only warns and prints the runbook.
+        if (longConnectionChannels.length > 0) {
+            const msg = `long-connection channel (${longConnectionChannels.join(", ")}) cannot run on AgentCore — there is no ` +
+                `resident process to hold the connection, and nothing wakes a reclaimed session. Switch the channel ` +
+                `to webhook mode (its events then ride the forwarder like every other channel).`;
+            if (opts.run)
+                failStartup(new Error(`deploy stopped: ${msg}`));
+            console.error(`[fastagent] warn: ${msg}`);
+        }
+        // selfSchedule is fully supported: pending wake-ups are mirrored into one-shot EventBridge
+        // schedules via the forwarder (the wake-alarm mechanism — see deploy/agentcore/plan.ts).
+        // Schedules feed EventBridge rules — parsed facts (cron/tz), not just file names, so a bad file
+        // must surface here (a schedule silently missing its rule would never fire).
+        const loaded = await loadSchedules(agentDir).catch(failStartup);
+        if (loaded.failures.length > 0) {
+            failStartup(new Error(`deploy stopped: cannot load schedules: ${loaded.failures.map((x) => `${x.label}: ${x.message}`).join("; ")}`));
+        }
+        const acName = basename(workspace)
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/^-+|-+$/g, "") || "agent";
+        // Every derived AWS name embeds acName; the tightest ceiling is the Lambda function name
+        // (`fastagent-<name>-forwarder` ≤ 64 chars). Gate the base instead of silently truncating —
+        // truncation would break the redeploy identity (a renamed stack starts blank state).
+        if (acName.length > 40) {
+            failStartup(new Error(`deploy stopped: the directory name maps to "${acName}" (${acName.length} chars) — AWS resource ` +
+                `names derived from it exceed their limits past 40 chars. Deploy from a shorter directory name.`));
+        }
+        const plan = planAgentcoreDeploy({
+            name: acName,
+            modelAuth,
+            channels,
+            routeChannels,
+            extraSecrets,
+            schedules: loaded.schedules.map((s) => ({ name: s.name, cron: s.cron, tz: s.tz })),
+            selfSchedule: !!config.selfSchedule,
+            ...container,
+        });
+        for (const u of plan.untranslatableSchedules) {
+            // Same discipline as Fly's kept-toml time-trigger gate: a deploy whose schedule silently never
+            // fires is worse than a stopped deploy — nothing fails visibly when the instant passes.
+            const msg = `schedule "${u.name}" cannot be expressed as an EventBridge rule — ${u.reason}`;
+            if (opts.run)
+                failStartup(new Error(`deploy stopped: ${msg}`));
+            console.error(`[fastagent] warn: ${msg} — it will NOT fire on this deployment`);
+        }
+        // Host capability limit, stated at plan time. GitHub's own webhook contract is 25 MiB, but a
+        // Lambda Function URL request caps at 6 MB — so on this host a large payload cannot arrive at
+        // all. Better a sentence here than an opaque 502 the first time someone pushes a big diff.
+        if (channels.includes("github")) {
+            console.error(`[fastagent] note: on AgentCore a webhook body is capped at ~${Math.round(MAX_WEBHOOK_BODY_BYTES / (1 << 20))} MiB ` +
+                `(the forwarder's Function URL limit); the GitHub channel accepts 25 MiB on a resident host, so the largest ` +
+                `payloads are rejected here rather than delivered`);
+        }
+        // The template IS the topology (EventBridge rules, wake wiring, secrets) — a kept generated
+        // template that no longer matches the definition would deploy a stack silently missing the
+        // difference (a new schedule with no rule never fires: the exact miss the gate above stops).
+        // A hand-written template (marker removed) is the operator's own — kept, never gated.
+        const templateArtifact = plan.artifacts.find((a) => a.path.endsWith(TEMPLATE_FILE));
+        const templateHome = join(workspace, templateArtifact?.path ?? TEMPLATE_FILE);
+        if (!opts.force && templateArtifact && (await exists(templateHome))) {
+            const existing = await readFile(templateHome, "utf8");
+            if (isGeneratedAgentcoreTemplate(existing) && existing !== templateArtifact.content) {
+                const msg = `${templateArtifact.path} no longer matches this definition (channels/schedules/selfSchedule changed) — ` +
+                    `the kept template would silently drop the difference. Pass --force to regenerate (hand edits are lost), ` +
+                    `or delete the file.`;
+                if (opts.run)
+                    failStartup(new Error(`deploy stopped: ${msg}`));
+                console.error(`[fastagent] warn: ${msg}`);
+            }
+        }
+        await writeArtifacts(workspace, plan.artifacts, {
+            force: !!opts.force,
+            alwaysWrite: [`${container.agentPrefix}${FORWARDER_FILE}`],
+        });
+        if (opts.run) {
+            return runDeployAgentcore({
+                agentDir,
+                workspace,
+                agentPrefix: container.agentPrefix,
+                name: acName,
+                modelAuth,
+                authPath,
+                channels,
+                extraSecrets,
+                selfSchedule: !!config.selfSchedule,
+                // Same predicate the template uses for the forwarder resource — kept in one expression so
+                // the run path and the topology cannot disagree about whether a forwarder exists.
+                needsForwarder: routeChannels.length > 0 || loaded.schedules.length > 0 || !!config.selfSchedule,
             });
         }
         console.log(plan.runbook.join("\n"));
@@ -178,20 +304,26 @@ export async function runDeploy(host, dirArg, opts) {
     // and the runbook reads its `app=` (Fly app names are globally unique, so the basename guess may be
     // taken and the user renamed it). --force: the template is authoritative — the WHOLE fly.toml resets
     // (app→basename, region→iad, vm→defaults), so we do NOT round-trip `app` and warn that hand edits go.
-    // Kit layout: fly.toml lives under the kit (agent/fly.toml) — the host repo's own fly.toml (if any)
-    // belongs to the host's product deploy and is never read or written here.
-    const flyTomlPath = container.kitDir ? join(target, container.kitDir, "fly.toml") : join(target, "fly.toml");
-    const flyTomlExists = await exists(flyTomlPath);
-    const keptApp = flyTomlExists && !opts.force ? parseFlyAppName(await readFile(flyTomlPath, "utf8")) : undefined;
-    const appName = keptApp ?? toFlyAppName(basename(target));
+    // fly.toml lives in the agent dir (fastagent/fly.toml) — the workspace's own
+    // fly.toml (if any) belongs to the host's product deploy and is never read or written here.
+    const flyTomlPath = join(agentDir, "fly.toml");
+    const flyToml = await readFile(flyTomlPath, "utf8").catch(() => undefined);
+    // Every decision below turns on ONE question — will `writeArtifacts` keep this file? — and the answer is
+    // OWNERSHIP, not the flag: `--force` resets a fly.toml we generated and leaves a hand-written one alone.
+    // Keying these on `--force` alone meant a forced deploy of a hand-owned fly.toml took the app name from
+    // the directory basename (shipping that file at a DIFFERENT app than it declares) and skipped the
+    // scale-to-zero gate below (a schedules deploy that silently sleeps). Read once, decide once.
+    const flyTomlKept = flyToml !== undefined && (!opts.force || !isGeneratedFlyToml(flyToml));
+    const keptApp = flyTomlKept ? parseFlyAppName(flyToml) : undefined;
+    const appName = keptApp ?? toFlyAppName(basename(workspace));
     if (keptApp)
         console.error(`[fastagent] app: ${keptApp} (from fly.toml)`);
-    if (flyTomlExists && opts.force) {
+    if (flyToml !== undefined && !flyTomlKept) {
         console.error(`[fastagent] warn: --force resets fly.toml to defaults (app, region, vm) — re-apply any hand edits`);
     }
     // Autostop flags shape the GENERATED fly.toml only. In KEEP mode (fly.toml exists, no --force) it is
     // not rewritten, so the flags would silently do nothing — surface that instead of a confusing no-op.
-    if (flyTomlExists && !opts.force && (opts.stop || opts.scaleToZero === false)) {
+    if (flyTomlKept && (opts.stop || opts.scaleToZero === false)) {
         console.error(`[fastagent] warn: --stop/--no-scale-to-zero only shape a freshly generated fly.toml — yours exists and ` +
             `was kept. Edit auto_stop_machines/min_machines_running in fly.toml, or pass --force to regenerate.`);
     }
@@ -201,8 +333,8 @@ export async function runDeploy(host, dirArg, opts) {
     // Under `--run` this is a GATE (same discipline as the model-travel gate): a full deploy whose schedules
     // silently never fire is worse than a crash-loop — nothing fails visibly when a cron instant passes on a
     // sleeping machine, and unlike github's min=0 there is no legitimate trade to accept here.
-    if (flyTomlExists && !opts.force && (hasTimeTriggers || longConnectionChannels.length > 0)) {
-        const min = parseFlyMinMachines(await readFile(flyTomlPath, "utf8"));
+    if (flyTomlKept && (hasTimeTriggers || longConnectionChannels.length > 0)) {
+        const min = parseFlyMinMachines(flyToml);
         if ((min ?? 0) === 0) {
             // undefined = the line is absent — Fly's platform default for min_machines_running is 0, so a
             // hand-written fly.toml without the line scales to zero exactly like an explicit 0.
@@ -228,13 +360,14 @@ export async function runDeploy(host, dirArg, opts) {
         autostop: opts.stop ? "stop" : "suspend",
         scaleToZero: opts.scaleToZero !== false,
     });
-    await writeArtifacts(target, plan.artifacts, {
+    await writeArtifacts(workspace, plan.artifacts, {
         force: !!opts.force,
-        neverForce: container.kitDir ? [".dockerignore"] : [],
     });
     if (opts.run) {
         return runDeployFly({
-            target,
+            agentDir,
+            workspace,
+            agentPrefix: container.agentPrefix,
             appName,
             modelAuth,
             authPath,
@@ -247,44 +380,79 @@ export async function runDeploy(host, dirArg, opts) {
     console.log(plan.runbook.join("\n"));
 }
 /**
- * Write each generated artifact. An existing file is KEPT unless --force — deploy NEVER clobbers a file
- * without it (no silent data loss). A Dockerfile/Compose file WE generated is definition-derived, so a
- * KEPT one that no longer matches what deploy would generate now (config/channel/lockfile/version drift —
- * OR the user's own edits, which we can't distinguish) is flagged stale; --force regenerates it. A
- * hand-written Dockerfile/Compose/ignore or fly.toml's app+region state is simply kept.
+ * Write each generated artifact, under ONE ownership rule: **deploy only ever overwrites its own
+ * output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
+ * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
+ * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
+ *
+ * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
+ * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
+ * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
+ * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
+ * Ownership is a property of the file, not of where the agent sits.
+ *
+ * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
+ * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
+ * regenerates that one.
  */
+/** Did fastagent generate the file at `path`? ONE table for all five artifact kinds: a kind missing from
+ *  it is permanently classified as the author's, which silently turns `--force` into a no-op for that
+ *  file (`fly.toml` and `railway.json` were, until the marker predicates below existed). */
+function isOurArtifact(path, content) {
+    if (path.endsWith("Dockerfile"))
+        return isGeneratedDockerfile(content);
+    if (path.endsWith(".dockerignore"))
+        return isGeneratedDockerignore(content);
+    if (path.endsWith("fastagent.compose.yml"))
+        return isGeneratedCompose(content);
+    if (path.endsWith("fly.toml"))
+        return isGeneratedFlyToml(content);
+    if (path.endsWith("railway.json"))
+        return isGeneratedRailwayJson(content);
+    if (path.endsWith(TEMPLATE_FILE))
+        return isGeneratedAgentcoreTemplate(content);
+    return false;
+}
 async function writeArtifacts(target, artifacts, options) {
     for (const a of artifacts) {
         const abs = join(target, a.path);
-        // Host-owned paths (the root .dockerignore in the agentDir layout): --force means "MY generated
-        // artifact is authoritative", which never licenses clobbering the HOST's file — keep it always.
-        if (options.neverForce?.includes(a.path) && (await exists(abs))) {
-            console.error(`[fastagent] kept ${a.path} — the host repo's own file (never overwritten, even with --force); ` +
-                `see the preflight warnings for what it must contain`);
+        // Pure build output, not operator-owned configuration. It must track the generated template/runbook.
+        if (options.alwaysWrite?.includes(a.path)) {
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, a.content);
+            console.error(`[fastagent] wrote ${a.path}`);
             continue;
         }
-        if (!options.force && (await exists(abs))) {
-            const existing = await readFile(abs, "utf8");
-            const generatedDrift = (a.path.endsWith("Dockerfile") && isGeneratedDockerfile(existing)) ||
-                (a.path.endsWith("fastagent.compose.yml") && isGeneratedCompose(existing));
-            if (generatedDrift && existing !== a.content) {
-                console.error(`[fastagent] kept ${a.path} — it no longer matches what deploy would generate (config changed, or ` +
-                    `you edited it); pass --force to regenerate.`);
-            }
-            else {
-                console.error(`[fastagent] kept ${a.path} (exists — pass --force to overwrite)`);
-            }
+        const existing = (await exists(abs)) ? await readFile(abs, "utf8") : undefined;
+        const ours = existing !== undefined && isOurArtifact(a.path, existing);
+        if (existing !== undefined && !ours) {
+            // Only the `.dockerignore` has content checks in preflight — pointing at "the preflight warnings"
+            // for the other kinds would send the reader looking for output that is never printed.
+            console.error(`[fastagent] kept ${a.path} — not generated by fastagent, so --force does not touch it ` +
+                `(delete it to let deploy own the path)` +
+                (a.path.endsWith(".dockerignore")
+                    ? `; see the preflight warnings for what it must exclude`
+                    : a.path.endsWith("Dockerfile")
+                        ? `; deploy still assumes it listens on $PORT and runs \`fastagent start /app\``
+                        : ``));
+            continue;
+        }
+        if (existing !== undefined && !options.force) {
+            console.error(existing !== a.content
+                ? `[fastagent] kept ${a.path} — it no longer matches what deploy would generate (config changed, or ` +
+                    `you edited it); pass --force to regenerate.`
+                : `[fastagent] kept ${a.path} (unchanged)`);
             continue;
         }
-        await mkdir(dirname(abs), { recursive: true }); // kit-layout artifacts live under agent/
+        await mkdir(dirname(abs), { recursive: true }); // artifacts live under fastagent/
         await writeFile(abs, a.content);
         console.error(`[fastagent] wrote ${a.path}`);
     }
 }
-function deployEnvironment(target, channels) {
+function deployEnvironment(agentDir, channels) {
     if (!channels.includes("slack"))
         return process.env;
-    const latest = readSlackBotAuthEnv(join(resolveStateRoot(target), "channels", "slack", "bot-auth.json"));
+    const latest = readSlackBotAuthEnv(join(resolveStateRoot(agentDir), "channels", "slack", "bot-auth.json"));
     return { ...process.env, ...latest };
 }
 /**
@@ -293,16 +461,16 @@ function deployEnvironment(target, channels) {
  * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
  */
 async function runDeployDocker(params) {
-    const { target, composeFile, port, requireTunnel, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, } = params;
+    const { agentDir, workspace, composeFile, port, requireTunnel, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, } = params;
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,
         extraSecrets,
-        env: deployEnvironment(target, channels),
+        env: deployEnvironment(agentDir, channels),
     });
-    const outcome = await deployDockerRun({ composeFile, port, secrets, missingSecrets, needsModelCredential, requireTunnel }, spawnRunner("docker", target), (message) => console.error(`[fastagent] ${message}`));
+    const outcome = await deployDockerRun({ composeFile, port, secrets, missingSecrets, needsModelCredential, requireTunnel }, spawnRunner("docker", workspace), (message) => console.error(`[fastagent] ${message}`));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     const compose = `docker compose -f ${composeFile}`;
@@ -313,10 +481,10 @@ async function runDeployDocker(params) {
         // Docker Desktop commonly injects a host proxy. The Quick Tunnel hostname may be resolvable only
         // through it, exactly like provider/channel APIs; use the same Node dispatcher as dev/start/login.
         installProxyFetch();
-        await announceWebhooks(target, outcome.tunnelUrl, {
+        await announceWebhooks(agentDir, outcome.tunnelUrl, {
             openUrl: openExternalUrl,
             routeChannels: channels.filter((kind) => !longConnectionChannels.includes(kind)),
-            stateRoot: resolveStateRoot(target),
+            stateRoot: resolveStateRoot(agentDir),
         });
         console.error(`[fastagent] note: Quick Tunnel URLs are ephemeral — after the tunnel container/Docker daemon ` +
             `restarts, re-run this deploy so webhooks receive the new URL`);
@@ -333,11 +501,11 @@ async function runDeployDocker(params) {
  * from the local env — the model key (env auth) or the whole auth.json as a `FASTAGENT_AUTH_SEED` seed
  * (OAuth/stored auth: the deployed box materializes it onto the /data volume on first boot, so a
  * personal deploy runs on the SAME subscription) plus channel secrets — then runs the flyctl steps
- * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the agent).
+ * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the whole workspace).
  */
 async function runDeployFly(params) {
-    const { target, appName, modelAuth, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets } = params;
-    const fly = spawnRunner("fly", target);
+    const { agentDir, workspace, agentPrefix, appName, modelAuth, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets, } = params;
+    const fly = spawnRunner("fly", workspace);
     // Fail fast if flyctl is absent (spawn ENOENT → 127), with the install link — not a confusing auth gate.
     if ((await fly(["version"], { capture: true })).code === 127) {
         failStartup(new Error(`flyctl not found — install it: https://fly.io/docs/flyctl/install, then re-run`));
@@ -349,28 +517,106 @@ async function runDeployFly(params) {
         channels,
         longConnectionChannels,
         extraSecrets,
-        env: deployEnvironment(target, channels),
+        env: deployEnvironment(agentDir, channels),
     });
     // Model credential has its OWN remediation (login), distinct from a missing secret's (.env) — gate it
     // here, not through missingSecrets, so the message isn't a contradictory mash of both.
     if (needsModelCredential) {
         failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
     }
-    const outcome = await deployFlyRun({ appName, region, secrets, missingSecrets, channels, longConnectionChannels, flyConfig: "fly.toml" }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(target) }));
+    const outcome = await deployFlyRun({
+        appName,
+        region,
+        secrets,
+        missingSecrets,
+        channels,
+        longConnectionChannels,
+        flyConfig: `${agentPrefix}fly.toml`,
+        dockerfile: `${agentPrefix}Dockerfile`,
+    }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → https://${appName}.fly.dev`);
 }
+/**
+ * `deploy agentcore --run`: drive aws + docker to completion. Mirrors {@link runDeployFly} — same
+ * credential carry via {@link assembleSecrets}, same runner seam (spawned `aws` + `docker`, cwd = the
+ * workspace so the build context is the agent). The AgentCore-specific sequence (identity → buildx →
+ * ECR → CloudFormation → outputs → webhooks) lives in {@link deployAgentcoreRun}; the params temp
+ * file (secret values off argv) is created here — 0600, removed after the run either way.
+ */
+async function runDeployAgentcore(params) {
+    const { agentDir, workspace, agentPrefix, name, modelAuth, authPath, channels, extraSecrets, selfSchedule } = params;
+    const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
+        modelAuth,
+        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
+        channels,
+        extraSecrets,
+        env: deployEnvironment(agentDir, channels),
+    });
+    // The wake-alarm shared secret (container ↔ forwarder). Minted fresh each run — both sides receive
+    // the SAME parameter, so rotation is atomic; it never needs to be remembered locally.
+    if (selfSchedule)
+        secrets.FASTAGENT_WAKE_SECRET = crypto.randomUUID();
+    // The forwarder→runtime ingress secret: what makes an envelope the forwarder's rather than any IAM
+    // principal's. Minted fresh each run — both sides receive the SAME parameter, so rotation is atomic.
+    if (params.needsForwarder)
+        secrets.FASTAGENT_INGRESS_SECRET = crypto.randomUUID();
+    if (needsModelCredential) {
+        failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
+    }
+    // The params temp dir holds the ONE file carrying secret values (file:// parameter-overrides —
+    // never argv); 0700/0600 and removed after the run, success or gate.
+    const paramsDir = await mkdtemp(join(tmpdir(), "fastagent-agentcore-"));
+    try {
+        const outcome = await deployAgentcoreRun({
+            name,
+            templatePath: `${agentPrefix}${TEMPLATE_FILE}`,
+            dockerfilePath: agentPrefix ? `${agentPrefix}Dockerfile` : undefined,
+            tag: new Date()
+                .toISOString()
+                .replace(/[-:.TZ]/g, "")
+                .slice(0, 14),
+            region: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION,
+            secrets,
+            missingSecrets,
+            channels,
+            // Same predicate the template uses: the forwarder exists for route channels, cron schedules
+            // or selfSchedule — and it is what mints the state snapshot's presigned URLs.
+            needsForwarder: params.needsForwarder,
+        }, spawnRunner("aws", workspace), spawnRunner("docker", workspace), (m) => console.error(`[fastagent] ${m}`), async (content) => {
+            const path = join(paramsDir, "params.json");
+            await writeFile(path, content, { mode: 0o600 });
+            await chmod(path, 0o600);
+            return path;
+        }, async (bytes) => {
+            const path = join(paramsDir, "forwarder.zip");
+            await writeFile(path, bytes);
+            return path;
+        }, (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }));
+        if (!outcome.ok)
+            failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+        console.error(`[fastagent] deployed → ${outcome.runtimeArn}`);
+        if (outcome.url)
+            console.error(`[fastagent] webhook ingress → ${outcome.url}`);
+        console.error(`[fastagent] invoke: aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn ${outcome.runtimeArn} \\\n` +
+            `  --runtime-session-id "my-conversation-000000000000000000" \\\n` +
+            `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --cli-binary-format raw-in-base64-out /dev/stdout`);
+    }
+    finally {
+        await rm(paramsDir, { recursive: true, force: true });
+    }
+}
 /**
  * `deploy railway --run`: drive the railway CLI to completion. Mirrors {@link runDeployFly} — same
  * credential carry (env key OR the OAuth auth.json as `FASTAGENT_AUTH_SEED`) via {@link assembleSecrets},
- * same runner seam (spawned `railway`, cwd = the workspace so `railway up`'s upload is the agent). The
+ * same runner seam (spawned `railway`, cwd = the workspace so `railway up`'s upload is the whole workspace). The
  * Railway-specific sequence (linked-check → init/add/volume when fresh → variables → up → domain →
  * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
  */
 async function runDeployRailway(params) {
-    const { target, name, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, intoLinked } = params;
-    const railway = spawnRunner("railway", target);
+    const { agentDir, workspace, name, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, intoLinked, dockerfilePath, } = params;
+    const railway = spawnRunner("railway", workspace);
     // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
     if ((await railway(["--version"], { capture: true })).code === 127) {
         failStartup(new Error(`railway CLI not found — install it: https://docs.railway.com/guides/cli, then re-run`));
@@ -381,13 +627,13 @@ async function runDeployRailway(params) {
         channels,
         longConnectionChannels,
         extraSecrets,
-        env: deployEnvironment(target, channels),
+        env: deployEnvironment(agentDir, channels),
     });
     // Model credential has its OWN remediation (login), distinct from a missing secret's (.env).
     if (needsModelCredential) {
         failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
     }
-    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, longConnectionChannels, intoLinked }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(target) }));
+    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, longConnectionChannels, intoLinked, dockerfilePath }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir) }));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → ${outcome.url}`);