@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/cli/commands/add.js

@@ -8,13 +8,9 @@ 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 { resolveStateRoot } from "../../paths.js";
-import { SECRETS_DIRNAME } from "../../paths.js";
+import { resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
-import { isUnderDir } from "../../paths.js";
-import { displayPath } from "../../paths.js";
-import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
-import { exists } from "../../paths.js";
+import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, scaffoldCompanionTools, } from "../../scaffold/add-channel.js";
 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()`. */
@@ -37,25 +33,10 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     const inAgent = (p) => (agentFromCwd === undefined ? p : join(agentFromCwd, p));
     const envPath = dotEnvPath(target);
     const envLabel = isUnderDir(envPath, target) ? inAgent(relative(target, envPath)) : envPath;
-    // App creation is not a flag — it is what `add feishu` IS (the scan-to-create flow is the default
-    // and only path there). The retired --create-app spelling gets a pointer, not silence.
-    if (opts.createApp) {
-        if (channelKind === "feishu") {
-            console.error(`[fastagent] note: --create-app is retired — \`add feishu\` creates the app by default`);
-        }
-        else if (channelKind === "lark") {
-            failStartup(new Error("--create-app is retired — `add lark` now opens the developer console and guides credential setup by default"));
-        }
-        else {
-            failStartup(new Error("--create-app is retired — app creation is the default behavior of `add feishu`"));
-        }
-    }
     // Preconditions before the write, so a refusal is side-effect-free. slack/feishu/lark are exceptions:
     // their add is scaffold + ONBOARD THE APP, so an existing scaffold skips the write and continues (a
     // failed/cancelled app or OAuth flow must be re-runnable without hand-deleting authored glue).
     const file = join(target, "channels", `${channelKind}.ts`);
-    const slackToolFile = join(target, "tools", "slack-send.ts");
-    const slackToolExisted = channelKind === "slack" ? await exists(slackToolFile) : false;
     const existsAlready = await channelExists(target, channelKind).catch(failStartup);
     const ingress = await resolveIngress(channelKind, file, existsAlready, opts.ingress);
     const groupBehavior = await resolveGroupBehavior(channelKind, opts.groupBehavior);
@@ -67,11 +48,13 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     }
     else {
         await assertChannelReady(target).catch(failStartup);
-        await scaffoldChannel(target, channelKind, { ingress, groupBehavior: groupBehavior.behavior }).catch(failStartup);
+        await scaffoldChannel(target, channelKind, { ingress }).catch(failStartup);
         console.error(`[fastagent] created ${relative(target, file)}`);
-        if (channelKind === "slack") {
-            console.error(`[fastagent] ${slackToolExisted ? "kept existing" : "created"} ${relative(target, slackToolFile)}`);
-        }
+    }
+    // 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>` (`--no-onboard` skips the prompts).
+    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"))}`);
@@ -97,9 +80,9 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     const env = setup.env;
     const steps = channelKind === "slack" && opts.onboard !== false
         ? [
-            `Slack internal app created/configured/installed through OAuth; runtime credentials are in ${envLabel}`,
-            "run fastagent dev --tunnel to replace the temporary Events API URL automatically",
-            "invite the app to every channel it should read",
+            // 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;
@@ -141,7 +124,7 @@ export async function runAddChannel(channelKind, dirArg, opts) {
         console.error(`    fastagent dev            # no public URL or tunnel required`);
     }
     else if (channelKind === "slack") {
-        console.error(`    fastagent dev --tunnel   # serve locally; ${opts.onboard === false ? "print the Request URL for manual Slack setup" : "auto-update the onboarded Slack Request URL"}`);
+        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`);
@@ -187,16 +170,20 @@ 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.
+        initialValue: "webhook",
         options: [
-            {
-                value: "websocket",
-                label: "WebSocket long connection",
-                hint: "no public URL; requires an always-on process",
-            },
             {
                 value: "webhook",
                 label: "Webhook endpoint",
-                hint: "supports scale-to-zero; requires a public HTTPS URL",
+                hint: "works on every deploy target; supports scale-to-zero; requires a public HTTPS URL",
+            },
+            {
+                value: "websocket",
+                label: "WebSocket long connection",
+                hint: "no public URL; needs an always-on process (not on AgentCore)",
             },
         ],
     });

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

@@ -1,4 +1,4 @@
-import type { SessionControl, SessionEntry } from "../../session.ts";
+import { type SessionControl, type SessionEntry } from "../../session.ts";
 export interface AttachOptions {
     /** Override the control endpoint (skip control.json discovery) — for a remote serve. */
     url?: string;
@@ -63,7 +63,7 @@ export interface AttachIo {
     warn: (line: string) => void;
 }
 /**
- * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a `navigate`, or a
+ * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a leaf move, or a
  * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
  * branch interleaved with the live one as if it were one conversation. Reachability is computed
  * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
@@ -106,5 +106,3 @@ settleMs?: number): Promise<{
     cursor: string | undefined;
     sawProgress: boolean;
 }>;
-/** The cursor a failed round reached, if it recorded one. */
-export declare function roundCursor(error: unknown): string | undefined;

package/dist/cli/commands/attach.js

@@ -16,7 +16,7 @@ import { loadDotEnv } from "../../env.js";
 import { resolveStateRoot } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
 import { ABORTED_CODE, SESSION_BUSY_CODE } from "../../agent.js";
-import { NO_ACTIVE_RUN_CODE } from "../../session.js";
+import { NO_ACTIVE_RUN_CODE, } from "../../session.js";
 import { ControlRequestError, connectAgent, connectSessionControl } from "../../session-remote.js";
 import { failStartup, placementOrExit } from "../fail.js";
 /** Read the serving process's local discovery file. */
@@ -157,7 +157,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
                 if (!endpoint)
                     endpoint = discover(dir); // discovered: the first read shares the budget
                 const connected = await connectSessionControl(endpoint);
-                return { control: connected, state: await connected.state(sessionArg) };
+                return { control: connected, state: await connected.sessions.get(sessionArg).state() };
             }
             catch (error) {
                 const decision = decideRound(errorFacts(error), {
@@ -208,7 +208,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
             // ABORTED_CODE: a deliberate stop from ANY client (this attach's /abort, another attach, a
             // Web panel) — the settled line reports it either way; no source discrimination here.
         }
-        // session_busy = the LEASE is held — by another run OR a boundary mutation (compact/set_model
+        // session_busy = the LEASE is held — by another run OR a boundary mutation (compact/update
         // contend on the same lease); "a run started" would be a guess, and "steer it" bad advice
         // against a compact. State the lease fact, promise nothing.
         if (sawBusy)
@@ -225,12 +225,14 @@ export async function runAttach(sessionArg, dirArg, opts) {
             void answerSlashInput(trimmed, control, (l) => console.log(l));
             return;
         }
-        const command = trimmed === "/abort" ? { type: "abort" } : { type: "steer", prompt: { text: trimmed } };
-        void control.dispatch(sessionArg, command).then((result) => {
+        const stopping = trimmed === "/abort";
+        const label = stopping ? "abort" : "steer";
+        const session = control.sessions.get(sessionArg);
+        void (stopping ? session.abort() : session.steer({ text: trimmed })).then((result) => {
             if (result.ok) {
-                console.log(`[${command.type} accepted]`);
+                console.log(`[${label} accepted]`);
             }
-            else if (command.type === "steer" && result.error.code === NO_ACTIVE_RUN_CODE) {
+            else if (!stopping && result.error.code === NO_ACTIVE_RUN_CODE) {
                 // The invoke stream attach holds IS this run's driver (design: disconnect = cancel), so
                 // unlike channel-started runs, this one dies with the attach. Say so up front.
                 // Intent, not fact: admission may still fail (session_busy — the lease could be held
@@ -240,9 +242,9 @@ export async function runAttach(sessionArg, dirArg, opts) {
                 void startRun(trimmed).catch((error) => console.log(`[prompt failed: ${String(error)}]`));
             }
             else {
-                console.log(`[${command.type} rejected: ${result.error.code} — ${result.error.message}]`);
+                console.log(`[${label} rejected: ${result.error.code} — ${result.error.message}]`);
             }
-        }, (error) => console.log(`[${command.type} failed: ${String(error)}]`));
+        }, (error) => console.log(`[${label} failed: ${String(error)}]`));
     });
     // Every round has ONE shape: subscribe → backfill (render the durable record since the cursor)
     // → drain live until the stream drops. Subscribing first + the server's eager registration
@@ -424,7 +426,7 @@ const isAuthError = (error) => error instanceof ControlRequestError && error.sta
  *  startup (a serve restart hours in), so the local name must not imply "startup only". */
 const exitWith = failStartup;
 /**
- * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a `navigate`, or a
+ * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a leaf move, or a
  * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
  * branch interleaved with the live one as if it were one conversation. Reachability is computed
  * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
@@ -437,7 +439,7 @@ export function activePathSlice(entries, leafEntryId) {
         return entries;
     const byId = new Map(entries.map((e) => [e.id, e]));
     // An append always moves the leaf, so a leaf BEHIND the slice means every entry in it was
-    // appended and then abandoned — a navigate backwards with no new turn since. Nothing here is on
+    // appended and then abandoned — a leaf move backwards with no new turn since. Nothing here is on
     // the active path.
     if (!byId.has(leafEntryId))
         return [];
@@ -509,7 +511,7 @@ settleMs = 300) {
     // The round HOLDS its subscription's iterator: one round = one stream, on every path — a
     // backfill failure must close it before propagating, or the caller's retry round would stack a
     // second concurrent stream interleaving the same session's output.
-    const iterator = control.events(session)[Symbol.asyncIterator]();
+    const iterator = control.sessions.get(session).events()[Symbol.asyncIterator]();
     // Live output is BUFFERED while the replay block prints, then flushed — the drain runs
     // concurrently with the backfill, and interleaving raw deltas into the labeled replay would make
     // both unreadable; the [end of replay] label is only honest if the block is contiguous.
@@ -554,7 +556,7 @@ settleMs = 300) {
     let next = cursor;
     let sawBackfill = false;
     try {
-        const backfill = await control.entries(session, cursor !== undefined ? { since: cursor } : undefined);
+        const backfill = await control.sessions.get(session).entries(cursor !== undefined ? { since: cursor } : undefined);
         sawBackfill = backfill.entries.length > 0;
         // Advance by APPEND ORDER (the last returned record), never by leafEntryId: `since` is an
         // append-position cursor (design §7), and a leaf that sits before later appends (abandoned
@@ -579,7 +581,7 @@ settleMs = 300) {
         }
         // The protocol's reconnect step the replay cannot cover: status changes while away are
         // LIVE-only events (state_changed before a restart is neither replayed nor re-emitted).
-        const now = await control.state(session);
+        const now = await control.sessions.get(session).state();
         io.println(`[live — ${now.status}${now.activeRunId ? ` (run ${now.activeRunId})` : ""}]`);
     }
     catch (error) {
@@ -612,7 +614,7 @@ function withCursor(error, cursor) {
     return Object.assign(e, { attachCursor: cursor });
 }
 /** The cursor a failed round reached, if it recorded one. */
-export function roundCursor(error) {
+function roundCursor(error) {
     return error.attachCursor;
 }
 /** Render one durable record on replay — the guaranteed kind vocabulary; other kinds are skipped. */

package/dist/cli/commands/chat.js

@@ -1,17 +1,11 @@
 /** `fastagent chat [dir]`: open the SAME assembled agent in pi's interactive TUI. */
-import { resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
-import { installProxyFetch } from "../../proxy.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { enterAgentCommand } from "../shared.js";
 export async function runChat(dirArg, opts) {
-    const placement = placementOrExit(resolve(dirArg));
-    loadDotEnv(placement.agentDir);
-    installProxyFetch(); // model calls (and the login dialog) must go through the proxy too
-    // First-run funnel, FULL picker: 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
-    // credential-annotated catalog and inline login apply here too.
-    await resolveFirstRunModel(placement.agentDir, { model: opts.model, authPath: opts.authPath });
+    // 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.
     process.chdir(placement.workspace);

package/dist/cli/commands/deploy/agentcore.d.ts

@@ -0,0 +1,2 @@
+import { type HostDeploy } from "./shared.ts";
+export declare const agentcoreHost: HostDeploy;

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

@@ -0,0 +1,178 @@
+/**
+ * `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.
+ */
+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 { deployAgentcoreRun } from "../../../deploy/agentcore/run.js";
+import { spawnRunner } from "../../../deploy/runner.js";
+import { exists } from "../../../paths.js";
+import { loadSchedules } 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. */
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+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.
+        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 ` +
+                `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 = 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).
+        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,
+            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.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.
+        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 write(plan.artifacts, {
+            force: !!opts.force,
+            alwaysWrite: [`${container.agentPrefix}${FORWARDER_FILE}`],
+        });
+        if (opts.run) {
+            return runDeployAgentcore({
+                agentDir,
+                workspace,
+                agentPrefix: container.agentPrefix,
+                name: acName,
+                modelAuth,
+                modelKeyInDefinition,
+                authPath,
+                channels,
+                extraSecrets,
+                topology: plan.topology,
+            });
+        }
+        console.log(plan.runbook.join("\n"));
+        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.
+ */
+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();
+    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.
+    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,
+            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 });
+            return path;
+        }, async (bytes) => {
+            const path = join(paramsDir, "forwarder.zip");
+            await writeFile(path, bytes);
+            return path;
+        }, registrarsFor(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}`);
+        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] 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 });
+    }
+}

package/dist/cli/commands/deploy/docker.d.ts

@@ -0,0 +1,2 @@
+import { type HostDeploy } from "./shared.ts";
+export declare const dockerHost: HostDeploy;

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

@@ -0,0 +1,119 @@
+/**
+ * `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";
+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 { announceWebhooks } from "../../../tunnel.js";
+import { failStartup } from "../../fail.js";
+import { carryCredentials } from "./shared.js";
+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 hasDeclaredChannels = channels.length > 0;
+        const projectName = toDockerProjectName(basename(workspace));
+        const dockerPlan = (tunnel) => planDockerDeploy({
+            projectName,
+            port,
+            modelAuth,
+            channels,
+            tunnel,
+            extraSecrets,
+            ...container,
+        });
+        const requestedTunnel = !!opts.tunnel && (!hasDeclaredChannels || webhookChannels.length > 0);
+        if (opts.tunnel && hasDeclaredChannels && webhookChannels.length === 0) {
+            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.
+        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.
+        const composeText = await readTextIfExists(composeFile).catch(failStartup);
+        if (composeText !== undefined && (!opts.force || !isGeneratedCompose(composeText))) {
+            const existingHasTunnel = composeHasTunnelService(composeText);
+            plan = dockerPlan(existingHasTunnel);
+            keptWithoutRequestedTunnel = requestedTunnel && !existingHasTunnel;
+        }
+        await write(plan.artifacts, { force: !!opts.force });
+        if (opts.run) {
+            return runDeployDocker({
+                agentDir,
+                workspace,
+                composeFile: plan.composePath,
+                port,
+                requireTunnel: requestedTunnel,
+                modelAuth,
+                modelKeyInDefinition,
+                authPath,
+                channels,
+                extraSecrets,
+            });
+        }
+        if (keptWithoutRequestedTunnel) {
+            console.error(`[fastagent] warn: --tunnel was requested but kept ${plan.composePath} has no "tunnel" service — ` +
+                `edit it, delete it and regenerate, or pass --force`);
+        }
+        console.log(plan.runbook.join("\n"));
+        return;
+    },
+};
+/**
+ * `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`.
+ */
+async function runDeployDocker(params) {
+    const { agentDir, workspace, composeFile, port, requireTunnel, channels } = params;
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    const outcome = await deployDockerRun({
+        composeFile,
+        port,
+        secrets,
+        missingSecrets,
+        needsModelCredential,
+        requireTunnel,
+        announce: (tunnelUrl) => announceWebhooks(agentDir, tunnelUrl, channels, {
+            openUrl: openExternalUrl,
+            stateRoot: resolveStateRoot(agentDir),
+        }),
+    }, 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.
+    const isUp = outcome.ok || outcome.url !== undefined || outcome.tunnelUrl !== undefined;
+    if (outcome.url)
+        console.error(`[fastagent] running → ${outcome.url}`);
+    if (isUp) {
+        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.
+    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`);
+    }
+    if (!outcome.ok)
+        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+    if (outcome.tunnelUrl)
+        return;
+    const paths = webhookPaths(channels);
+    if (paths.length > 0) {
+        console.error(`[fastagent] note: public ingress is operator-owned — configure your tunnel/proxy, then wire the ` +
+            `default webhook path(s): ${paths.join(", ")} (or your remapped channel routes)`);
+    }
+}

package/dist/cli/commands/deploy/fly.d.ts

@@ -0,0 +1,2 @@
+import { type HostDeploy } from "./shared.ts";
+export declare const flyHost: HostDeploy;