@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/cli/commands/add.js

@@ -1,13 +1,13 @@
 /**
- * `fastagent add <channel>|skill` — scaffold channel glue (`channels/<kind>.ts`) or vendor an Agent
- * Skills skill. slack/feishu/lark additionally CREATE OR RESUME the platform app.
+ * `fastagent add <channel>|skill` — scaffold channel glue (`channels/<kind>.ts`) or vendor an Agent Skills skill.
+ * slack/feishu/lark additionally CREATE OR RESUME the platform app.
  */
 import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { isCancel, select } from "@clack/prompts";
 import { onboardFeishuCloudApp } from "../add-feishu.js";
-import { dotEnvPath, loadDotEnv } from "../../env.js";
+import { dotEnvPath, enterAgentEnv } from "../../env.js";
 import { resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, scaffoldCompanionTools, } from "../../scaffold/add-channel.js";
@@ -15,27 +15,20 @@ import { vendorSkill } from "../../scaffold/vendor-skill.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 /** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
 export async function runAddChannel(channelKind, dirArg, opts) {
-    // The channel (glue + companion tool + secrets) is agent surface — everything lands in the
-    // AGENT DIR (`fastagent/`), the same place dev/start discover channels/.
-    // Flag conflicts first: a bad combination is a USAGE error (exit 2), and reporting it must not depend
-    // on the directory being an agent (a runtime/environment failure, exit 1) — the same order start/tool
-    // follow.
+    // The channel (glue + companion tool + secrets) is agent surface — everything lands in the AGENT DIR
+    // (`fastagent/`), the same place dev/start discover channels/.
     if (opts.replaceConfig && opts.onboard === false) {
         failUsage("--replace-config replaces onboarding credentials; it cannot be combined with --no-onboard");
     }
     const { agentDir: target } = placementOrExit(resolve(dirArg));
-    loadDotEnv(target); // onboarding state follows the same FASTAGENT_STATE_DIR as serving/deploy
-    // Paths are printed to someone standing in their CWD, usually the workspace, while every file
-    // belongs to the AGENT dir — prefix them, or they point at nothing. `displayPath` owns the
-    // relative-vs-absolute policy (shared with `init`). The `.env` label names the file actually
-    // WRITTEN (FASTAGENT_SECRETS_DIR relocates it, possibly out of the agent), never the default spelling.
+    enterAgentEnv(target); // onboarding state follows the same FASTAGENT_STATE_DIR as serving/deploy
+    // Paths are printed to someone standing in their CWD, usually the workspace, while every file belongs to the AGENT
+    // dir — prefix them, or they point at nothing.
     const agentFromCwd = displayPath(process.cwd(), target);
     const inAgent = (p) => (agentFromCwd === undefined ? p : join(agentFromCwd, p));
     const envPath = dotEnvPath(target);
     const envLabel = isUnderDir(envPath, target) ? inAgent(relative(target, envPath)) : envPath;
-    // An existing channel file is authored glue: kept, never rewritten. The add continues past it — the
-    // companion tools below are refreshed, and slack/feishu/lark resume a failed/cancelled app or OAuth
-    // flow — so re-running `add <kind>` never requires hand-deleting the glue.
+    // An existing channel file is authored glue: kept, never rewritten.
     const file = join(target, "channels", `${channelKind}.ts`);
     const existsAlready = await channelExists(target, channelKind).catch(failStartup);
     const ingress = await resolveIngress(channelKind, file, existsAlready, opts.ingress);
@@ -48,16 +41,14 @@ export async function runAddChannel(channelKind, dirArg, opts) {
         await scaffoldChannel(target, channelKind, { ingress }).catch(failStartup);
         console.error(`[fastagent] created ${relative(target, file)}`);
     }
-    // Companion tools are the package's, not authored glue: written on every add, so an upgraded
-    // package reaches an existing agent by re-running `add <kind>` (slack: `--no-onboard` skips the prompts).
+    // Companion tools are the package's, not authored glue.
     for (const tool of await scaffoldCompanionTools(target, channelKind).catch(failStartup)) {
         console.error(`[fastagent] wrote ${relative(target, tool)}`);
     }
     if (await appendChannelEnv(target, channelKind, ingress).catch(failStartup)) {
         console.error(`[fastagent] added ${channelKind} env vars to ${inAgent(join(SECRETS_DIRNAME, ".env.example"))}`);
     }
-    // Stateful app onboarding is re-runnable after the scaffold boundary. Slack's internal-app path
-    // persists its manifest/OAuth recovery state separately and writes runtime secrets directly.
+    // Stateful app onboarding is re-runnable after the scaffold boundary.
     let created;
     if (channelKind === "slack" && opts.onboard !== false) {
         const { onboardSlackInternalApp } = await import("../add-slack.js");
@@ -77,16 +68,14 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     const env = setup.env;
     const steps = channelKind === "slack" && opts.onboard !== false
         ? [
-            // No line about the Request URL: the `dev --tunnel` line below is the whole instruction, and
-            // FastAgent sets that URL itself when the agent first runs.
+            // No line about the Request URL: the `dev --tunnel` line below is the whole instruction, and FastAgent sets
+            // that URL itself when the agent first runs.
             "invite the app to each channel it should read",
             "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
         ]
         : setup.steps;
     const generated = Object.fromEntries(env.filter((e) => e.generate).map((e) => [e.name, randomBytes(24).toString("hex")]));
-    // Kind-neutral: every channel's generated secrets get the same treatment (github's webhook secret is
-    // the same class of value as telegram's); guided Lark credentials ride the same write as overwrites.
-    // Feishu's irreversible credentials were already staged inside add-feishu.ts before bootstrap.
+    // Kind-neutral: every channel's generated secrets get the same treatment.
     const dotEnv = await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {}), ingress).catch(failStartup);
     if (dotEnv.unprotectedSecretsDir) {
         console.error(`[fastagent] note: ${dotEnv.unprotectedSecretsDir} (FASTAGENT_SECRETS_DIR) now holds a secret and has ` +
@@ -96,15 +85,16 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     if (dotEnv.written.length > 0) {
         console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to ${envLabel}`);
     }
-    const install = detectRuntime(target, await readPackageJson(target)).runtime === "bun" ? "bun install" : "npm install";
+    const install = detectRuntime(target, await readPackageJson(target).catch(failStartup)).runtime === "bun"
+        ? "bun install"
+        : "npm install";
     console.error(`  next steps:`);
     console.error(`    ${agentFromCwd === undefined ? install : `(cd ${agentFromCwd} && ${install})`}                      # if @fastagent-sh/fastagent is not installed yet`);
     for (const e of env) {
         if (dotEnv.alreadySet.includes(e.name))
             continue; // the user already has it — nothing to do
         if (dotEnv.written.includes(e.name)) {
-            // Written, but its hint may still carry an action (github: paste the same value into the webhook
-            // UI) — keep the variable visible instead of silently absorbing it.
+            // Written, but its hint may still carry an action — keep the variable visible instead of silently absorbing it.
             console.error(`    ${e.name} — ${e.generate ? "generated and " : ""}written to ${envLabel}   # ${e.hint}`);
             continue;
         }
@@ -112,8 +102,8 @@ export async function runAddChannel(channelKind, dirArg, opts) {
         const action = e.required ? "set" : "optionally set";
         console.error(`    ${action} ${e.name}${value} in ${envLabel}   # ${e.hint}`);
     }
-    // Steps carry `{channel}`/`{tools}` path placeholders (their filenames are the scaffold's private
-    // knowledge) — resolve them to the real agent-dir-relative locations here.
+    // Steps carry `{channel}`/`{tools}` path placeholders (their filenames are the scaffold's private knowledge) —
+    // resolve them to the real agent-dir-relative locations here.
     for (const s of steps) {
         console.error(`    ${s.replace("{channel}", inAgent(relative(target, file))).replace("{tools}", inAgent("tools"))}`);
     }
@@ -123,14 +113,11 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     else if (channelKind === "slack") {
         console.error(`    fastagent dev --tunnel   # ${opts.onboard === false ? "serve locally + print the URL to paste into the Slack app's Event Subscriptions" : "start the agent — then message it in Slack"}`);
     }
-    else if (channelKind === "github") {
-        console.error(`    fastagent dev --tunnel   # serve locally + print the URL for manual GitHub webhook setup`);
-    }
     else if (channelKind !== "lark") {
         console.error(`    fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
     }
-    // App-creation flows leave platform/tunnel sockets behind that would otherwise hold the one-shot
-    // scaffold command open after all durable boundaries have completed — exit crisply.
+    // App-creation flows leave platform/tunnel sockets behind that would otherwise hold the one-shot scaffold command
+    // open after all durable boundaries have completed.
     process.exit(0);
 }
 async function resolveIngress(kind, file, existsAlready, raw) {
@@ -167,9 +154,7 @@ async function resolveIngress(kind, file, existsAlready, raw) {
     }
     const answer = await select({
         message: `How should ${kind === "feishu" ? "Feishu" : "Lark"} deliver events?`,
-        // The default must match the non-interactive branch above. Webhook is the cheaper side to be
-        // wrong on: its credentials are a superset of websocket's (App ID/Secret plus the Verification
-        // Token), and that token has no read API — a websocket app moving to webhook must re-acquire it.
+        // The default must match the non-interactive branch above.
         initialValue: "webhook",
         options: [
             {
@@ -228,8 +213,7 @@ async function resolveGroupBehavior(kind, raw) {
 export async function runAddSkill(source, dirArg, opts) {
     const { agentDir: target } = placementOrExit(resolve(dirArg));
     if (!source) {
-        // A missing source is a usage error (exit 2), but the guide is worth more than a bare
-        // missing-argument line — the common path (writing your own skill) needs no command at all.
+        // A missing source is a usage error (exit 2), but the guide is worth more than a bare missing-argument line.
         failUsage(`add a skill — two ways:\n` +
             `  1. write your own (vibe): create skills/<name>/SKILL.md with name + description\n` +
             `     frontmatter; it's auto-discovered. No command needed — this is the common path.\n` +
@@ -240,6 +224,7 @@ export async function runAddSkill(source, dirArg, opts) {
             `     --update overwrites an existing skill (re-fetch from source); review with git diff`);
     }
     // Skills are agent surface — vendored into the agent dir's `skills/`.
+    enterAgentEnv(target); // a git-ref source is a network fetch (giget uses global fetch)
     const { name, description, dest, hasScripts, diagnostics, overwritten } = await vendorSkill(target, source, {
         update: opts.update ?? false,
     }).catch(failStartup);

package/dist/cli/commands/chat.d.ts

@@ -1,4 +1,3 @@
 export declare function runChat(dirArg: string, opts: {
     model?: string;
-    authPath?: string;
 }): Promise<void>;

package/dist/cli/commands/chat.js

@@ -2,14 +2,13 @@
 import { failStartup } from "../fail.js";
 import { enterAgentCommand } from "../shared.js";
 export async function runChat(dirArg, opts) {
-    // Chat authenticates through fastagent's credential store like every other command (the shared
-    // session builder injects it — see engines/pi/session-builder.ts), so the first-run picker and its
-    // inline login apply here too.
+    // Chat authenticates through fastagent's credential store like every other command (the shared session builder
+    // injects it — see engines/pi/session-builder.ts), so the first-run picker and its inline login apply here too.
     const placement = await enterAgentCommand(dirArg, opts);
-    // Run the chat process AT the workspace: pi resolves a session's cwd as `header.cwd ?? process.cwd()`,
-    // so aligning process.cwd() with the workspace keeps a cwd-less session on it. Paths are absolute.
+    // Run the chat process AT the workspace: pi resolves a session's cwd as `header.cwd ?? process.cwd()`, so aligning
+    // process.cwd() with the workspace keeps a cwd-less session on it.
     process.chdir(placement.workspace);
     // Lazy-import: chat pulls pi's interactive TUI module graph; headless start/dev never need it.
     const { runPiChat } = await import("../../engines/pi/chat.js");
-    await runPiChat(placement.workspace, { model: opts.model, authPath: opts.authPath }).catch(failStartup);
+    await runPiChat(placement.agentDir, { model: opts.model }).catch(failStartup);
 }

package/dist/cli/commands/deploy/agentcore.js

@@ -1,16 +1,15 @@
 /**
- * `deploy 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.
+ * `deploy agentcore`: one CloudFormation stack (runtime + forwarder Lambda behind a Function URL + EventBridge
+ * schedules); no resident process.
  */
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
-import { MAX_WEBHOOK_BODY_BYTES } from "../../../channels/agentcore-limits.js";
-import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../../deploy/agentcore/plan.js";
+import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, forwarderLogGroup, ingressSessionId, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../../deploy/agentcore/plan.js";
 import { deployAgentcoreRun } from "../../../deploy/agentcore/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
-import { exists } from "../../../paths.js";
-import { loadSchedules } from "../../../schedule/discover.js";
+import { SECRET_FILE_MODE, exists } from "../../../paths.js";
+import { loadRoutines } from "../../../schedule/discover.js";
 import { failStartup } from "../../fail.js";
 import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
 /** A copy/paste-safe POSIX shell argument for the command hints deploy prints. */
@@ -21,10 +20,9 @@ export const agentcoreHost = {
     isOurs: (path, content) => path.endsWith(TEMPLATE_FILE) && isGeneratedAgentcoreTemplate(content),
     async deploy(ctx) {
         const { opts, agentDir, workspace, config, channels, longConnectionChannels, pre, write } = ctx;
-        const { modelAuth, modelKeyInDefinition, authPath, container, extraSecrets } = pre;
-        // 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.
+        const { modelAuth, modelKeyInDefinition, authPath, container, declaredSecrets, values, valueFile } = pre;
+        // Long-connection channels are STRUCTURALLY unsupported: the connection is the ingress, and a reclaimed session
+        // has nothing to wake it.
         if (longConnectionChannels.length > 0) {
             const msg = `long-connection channel (${longConnectionChannels.map((c) => c.name).join(", ")}) cannot run on AgentCore — there is no ` +
                 `resident process to hold the connection, and nothing wakes a reclaimed session. Switch the channel ` +
@@ -33,18 +31,23 @@ export const agentcoreHost = {
                 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);
+        // Host capability limit, stated before the image is built rather than left to a line in CloudWatch.
+        if (config.sessionControl === true) {
+            console.error(`[fastagent] warn: sessionControl: true has no effect on AgentCore — /control/* is not served here. This ` +
+                `host's only public ingress relays anonymous traffic to the container as trusted (the forwarder holds the ` +
+                `ingress secret and attaches it), and the plane has nothing of its own to verify. Steer sessions from a ` +
+                `host that serves it behind your own auth (docs/design/session-control.md §14).`);
+        }
+        // Wake-ups are a default capability here as everywhere: pending ones are mirrored into one-shot EventBridge
+        // schedules via the forwarder (the wake-alarm mechanism — see deploy/agentcore/plan.ts), which is why every stack
+        // has one.
+        const loaded = await loadRoutines(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("; ")}`));
+            failStartup(new Error(`deploy stopped: cannot load routines: ${loaded.failures.map((x) => `${x.label}: ${x.message}`).join("; ")}`));
         }
         const acName = agentcoreName(basename(workspace));
         // 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).
+        // (`fastagent-<name>-forwarder` ≤ 64 chars).
         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.`));
@@ -53,42 +56,35 @@ export const agentcoreHost = {
             name: acName,
             modelAuth,
             channels,
-            extraSecrets,
-            schedules: loaded.schedules.map((s) => ({ name: s.name, cron: s.cron, tz: s.tz })),
-            selfSchedule: !!config.selfSchedule,
+            secrets: pre.secrets,
+            // ONLY THE ONES WITH A CRON become rules. A routine without one is reached by NAME, through this host's
+            // IAM-gated `routine-run` envelope (channels/agentcore.ts) rather than a route — so it needs no rule and
+            // loses nothing by not having one.
+            schedules: loaded.routines.flatMap((r) => r.cron === undefined ? [] : [{ name: r.name, cron: r.cron, ...(r.tz !== undefined ? { tz: r.tz } : {}) }]),
+            idleTimeoutSeconds: config.deploy?.agentcore?.idleTimeoutSeconds,
             ...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.
+            // Same discipline as Fly's kept-toml time-trigger gate: a deploy whose schedule silently never fires is worse
+            // than a stopped deploy.
             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.some((channel) => channel.name === "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.
+        // The template IS the topology (EventBridge rules, wake wiring, secrets).
         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}`);
+                // WHY it matters here, not WHETHER to stop: the template IS the topology, so a kept one drops the
+                // difference rather than degrading visibly. Stopping a `--run` on a stale artifact is the dispatcher's
+                // rule (deploy.ts) for every host and every path — stating it a second time here is how the two
+                // wordings drift apart.
+                console.error(`[fastagent] warn: ${templateArtifact.path} no longer matches this definition ` +
+                    `(channels/routines or a deploy.agentcore setting changed) — the kept template would ` +
+                    `silently drop the difference.`);
             }
         }
         await write(plan.artifacts, {
@@ -105,7 +101,9 @@ export const agentcoreHost = {
                 modelKeyInDefinition,
                 authPath,
                 channels,
-                extraSecrets,
+                declaredSecrets,
+                values,
+                valueFile,
                 topology: plan.topology,
             });
         }
@@ -113,33 +111,23 @@ export const agentcoreHost = {
         return;
     },
 };
-/**
- * `deploy agentcore --run`: drive aws + docker to completion. Mirrors the fly driver — same
- * credential carry via {@link carryCredentials}, 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.
- */
+/** `deploy agentcore --run`: drive aws + docker to completion. */
 async function runDeployAgentcore(params) {
     const { agentDir, workspace, agentPrefix, name, channels, topology } = params;
     const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
-    // 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 (topology.wakeAlarms)
-        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 (topology.forwarder)
-        secrets.FASTAGENT_INGRESS_SECRET = crypto.randomUUID();
+    // The wake-alarm shared secret (container ↔ forwarder).
+    secrets.FASTAGENT_WAKE_SECRET = crypto.randomUUID();
+    // The forwarder→runtime ingress secret: what makes an envelope the forwarder's rather than any IAM principal's.
+    secrets.FASTAGENT_INGRESS_SECRET = crypto.randomUUID();
     gateOnModelCredential(needsModelCredential);
-    // 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.
+    // 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,
+            dockerfilePath: `${agentPrefix}Dockerfile`,
             tag: new Date()
                 .toISOString()
                 .replace(/[-:.TZ]/g, "")
@@ -147,11 +135,12 @@ async function runDeployAgentcore(params) {
             region: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION,
             secrets,
             missingSecrets,
+            valueFile: params.valueFile,
             channels,
             topology,
         }, 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 writeFile(path, content, { mode: SECRET_FILE_MODE });
             return path;
         }, async (bytes) => {
             const path = join(paramsDir, "forwarder.zip");
@@ -165,11 +154,17 @@ async function runDeployAgentcore(params) {
             console.error(`[fastagent] webhook ingress → ${outcome.url}`);
         const logsDir = shellArg(workspace);
         console.error(`[fastagent] runtime logs → fastagent logs agentcore ${logsDir} --follow`);
-        if (topology.forwarder) {
-            console.error(`[fastagent] forwarder logs → fastagent logs agentcore ${logsDir} --source forwarder --follow`);
-        }
+        console.error(`[fastagent] forwarder logs → fastagent logs agentcore ${logsDir} --source forwarder --follow`);
+        // `--run` never prints the runbook, and this is the ONE step in it that nothing else will remind anyone of: a
+        // log group is created by whatever writes it, CloudWatch keeps log data indefinitely, and these logs are where
+        // a failed turn's reason lives. The runtime's group name is only known after discovery, so it is named by the command that
+        // resolves it — spelled out, because the line above it may be the forwarder's.
+        console.error(`[fastagent] logs are kept FOREVER until you say otherwise: aws logs put-retention-policy ` +
+            `--log-group-name <the group \`fastagent logs agentcore ${logsDir} --follow\` resolves> --retention-in-days 14`);
+        console.error(`[fastagent] ...and for the forwarder: aws logs put-retention-policy ` +
+            `--log-group-name ${forwarderLogGroup(name)} --retention-in-days 14`);
         console.error(`[fastagent] invoke: aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn ${outcome.runtimeArn} \\\n` +
-            `  --runtime-session-id "my-conversation-000000000000000000" \\\n` +
+            `  --runtime-session-id "${ingressSessionId(name)}" \\\n` +
             `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --cli-binary-format raw-in-base64-out /dev/stdout`);
     }
     finally {

package/dist/cli/commands/deploy/docker.js

@@ -1,15 +1,13 @@
-/**
- * `deploy docker`: one app service + loopback port + state volume, as a user-owned Compose file.
- * `--tunnel` shapes the generated topology with an optional Quick Tunnel service; `--run` alone
- * decides whether Docker receives side effects.
- */
-import { basename, join } from "node:path";
+/** `deploy docker`: one app service + loopback port + state volume, as a user-owned Compose file. */
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { webhookPaths } from "../../../deploy/channel-ingress.js";
 import { composeHasTunnelService, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../../deploy/docker/plan.js";
 import { deployDockerRun } from "../../../deploy/docker/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
 import { openExternalUrl } from "../../../open-url.js";
-import { readTextIfExists, resolveStateRoot } from "../../../paths.js";
+import { SECRETS_DIRNAME, SECRET_FILE_MODE, exists, readTextIfExists, resolveStateRoot, } from "../../../paths.js";
+import { dotEnvPath } from "../../../env.js";
 import { announceWebhooks } from "../../../tunnel.js";
 import { failStartup } from "../../fail.js";
 import { carryCredentials } from "./shared.js";
@@ -17,7 +15,37 @@ export const dockerHost = {
     isOurs: (path, content) => path.endsWith("fastagent.compose.yml") && isGeneratedCompose(content),
     async deploy(ctx) {
         const { opts, agentDir, workspace, channels, webhookChannels, pre, write } = ctx;
-        const { modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets } = pre;
+        const { modelAuth, modelKeyInDefinition, authPath, container, port, declaredSecrets, values, valueFile } = pre;
+        // The generated Compose names `<agent>/.secrets/.env` unconditionally, so it has to be there — Compose refuses
+        // an `env_file` entry pointing at a missing path, and this floor predates `required: false` (Compose 2.24).
+        // Creating it empty is honest: a deployment that declares nothing declares it in an empty file.
+        const composeValueFile = join(agentDir, SECRETS_DIRNAME, ".env");
+        await mkdir(dirname(composeValueFile), { recursive: true });
+        if (!(await exists(composeValueFile)))
+            await writeFile(composeValueFile, "", { mode: SECRET_FILE_MODE });
+        // The pre-flight read whatever `FASTAGENT_SECRETS_DIR` resolved to; the committed Compose cannot, because a
+        // builder's path would not mean the same thing anywhere else. Under `--run` the two files disagreeing is a
+        // DETERMINISTIC failure and gates like every other one: the missing-values gate would pass on the file this
+        // machine reads while `compose up` starts a container whose declared secrets and model are all absent.
+        if (resolve(dotEnvPath(agentDir)) !== resolve(composeValueFile)) {
+            const issue = `FASTAGENT_SECRETS_DIR points this run's values at ${valueFile}, but the generated Compose reads ` +
+                `${relative(workspace, composeValueFile)} (a committed artifact cannot carry this machine's path), so the ` +
+                `container would start with none of them. Unset FASTAGENT_SECRETS_DIR, or put the values in that file.`;
+            if (opts.run)
+                failStartup(new Error(`deploy stopped: ${issue}`));
+            console.error(`[fastagent] warn: ${issue}`);
+        }
+        // Compose interpolates `$VAR` INSIDE env_file values (`format: raw` needs Compose 2.30), so a credential
+        // containing `$` reaches the container rewritten — silently, and differently from what this pre-flight read.
+        // No escaping advice: this ONE file is also read literally by `dev`/`start` (`parseEnvContent`) and pushed
+        // as-is by every other host, so `$$` would fix Docker by corrupting all of them.
+        const dollarValues = [...values].filter(([, value]) => value.includes("$")).map(([name]) => name);
+        if (dollarValues.length > 0) {
+            console.error(`[fastagent] warn: ${dollarValues.join(", ")} contain "$", which Compose expands when reading ${valueFile} ` +
+                `(an undefined name becomes empty), so the container sees a different value. "$$" escapes it for Compose ` +
+                `ONLY — \`fastagent dev\`/\`start\` and the other hosts read this file literally and would keep the extra ` +
+                `"$". Prefer a value without "$".`);
+        }
         const hasDeclaredChannels = channels.length > 0;
         const projectName = toDockerProjectName(basename(workspace));
         const dockerPlan = (tunnel) => planDockerDeploy({
@@ -26,7 +54,8 @@ export const dockerHost = {
             modelAuth,
             channels,
             tunnel,
-            extraSecrets,
+            secrets: pre.secrets,
+            valueFile,
             ...container,
         });
         const requestedTunnel = !!opts.tunnel && (!hasDeclaredChannels || webhookChannels.length > 0);
@@ -34,12 +63,12 @@ export const dockerHost = {
             console.error(`[fastagent] note: --tunnel skipped — every channel uses a long connection`);
         }
         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.
+        // An existing Compose file is authoritative: shape its comparison/runbook from the topology on disk, regardless
+        // of the current flag.
         const composeFile = join(workspace, plan.composePath);
         let keptWithoutRequestedTunnel = false;
-        // 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.
+        // 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 readTextIfExists(composeFile).catch(failStartup);
         if (composeText !== undefined && (!opts.force || !isGeneratedCompose(composeText))) {
             const existingHasTunnel = composeHasTunnelService(composeText);
@@ -58,7 +87,9 @@ export const dockerHost = {
                 modelKeyInDefinition,
                 authPath,
                 channels,
-                extraSecrets,
+                declaredSecrets,
+                values,
+                valueFile,
             });
         }
         if (keptWithoutRequestedTunnel) {
@@ -70,9 +101,8 @@ export const dockerHost = {
     },
 };
 /**
- * `deploy docker --run`: carry local credentials into Compose's child environment, then reconcile the
- * user-owned local topology. Docker owns container/network/volume lifecycle. A Compose tunnel service,
- * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
+ * `deploy docker --run`: carry local credentials into Compose's child environment, then reconcile the user-owned local
+ * topology.
  */
 async function runDeployDocker(params) {
     const { agentDir, workspace, composeFile, port, requireTunnel, channels } = params;
@@ -82,6 +112,7 @@ async function runDeployDocker(params) {
         port,
         secrets,
         missingSecrets,
+        valueFile: params.valueFile,
         needsModelCredential,
         requireTunnel,
         announce: (tunnelUrl) => announceWebhooks(agentDir, tunnelUrl, channels, {
@@ -90,9 +121,7 @@ async function runDeployDocker(params) {
         }),
     }, spawnRunner("docker", workspace), (message) => console.error(`[fastagent] ${message}`));
     const compose = `docker compose -f ${composeFile}`;
-    // Compose reached "up" iff the driver could report where it is. The gates before that point
-    // (no Docker CLI, no daemon, missing secrets) must not be preceded by `docker compose logs`
-    // instructions for containers that do not exist; the health-check gate names its own logs command.
+    // Compose reached "up" iff the driver could report where it is.
     const isUp = outcome.ok || outcome.url !== undefined || outcome.tunnelUrl !== undefined;
     if (outcome.url)
         console.error(`[fastagent] running → ${outcome.url}`);
@@ -100,9 +129,7 @@ async function runDeployDocker(params) {
         console.error(`[fastagent] logs: ${compose} logs -f agent`);
         console.error(`[fastagent] stop: ${compose} down (state volume is kept)`);
     }
-    // BEFORE failStartup: a registration gate says "re-run this deploy", and a re-run rebuilds the
-    // tunnel service — the operator needs to know the URL will be a different one, or they will read
-    // the retry as re-registering the same address.
+    // BEFORE failStartup: a registration gate says "re-run this deploy", and a re-run rebuilds the tunnel service.
     if (outcome.tunnelUrl) {
         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`);