@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/cli/commands/start.js

@@ -2,29 +2,24 @@
  * `fastagent start [dir]`: run the agent in production posture — the SAME assembly as dev (your
  * directory is the agent), just no file-watching. No build step: start reads the definition directly.
  */
-import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { authSeedBytes, collectAuthSeed } from "../../deploy/fly/run.js";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { authSeedBytes, collectAuthSeed } from "../../deploy/secrets.js";
 import { loadDotEnv } from "../../env.js";
 import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
-import { resolveSecretsDir, workspaceHint } from "../../paths.js";
-import { isUnderDir } from "../../paths.js";
-import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures } from "../../log.js";
-import { CODING_TOOL_NAMES } from "../../engines/pi/create.js";
+import { SECRET_FILE_MODE, ensureSecretsDir, resolveSecretsDir, isUnderDir, exists } from "../../paths.js";
+import { log, setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { mountAgentService } from "../../service.js";
-import { log, setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
-import { exists } from "../../paths.js";
 import { bindAddress } from "../../bind.js";
 import { isAgentcoreRuntime, mountAgentcoreService } from "../../channels/agentcore-service.js";
-import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
+import { createWakeAlarmSink } from "../../schedule/wake-alarm.js";
 import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { failStartup, placementOrExit } from "../fail.js";
 import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
-import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { parseBind, parsePort, reportAssembly, resolveFirstRunModel } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
     // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
@@ -43,26 +38,15 @@ export async function runStart(dirArg, opts) {
     // The same opener dev uses (single assembly source), just no watch.
     const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
     const opened = await openStartDir(dir, opts, sessionsDirOverride);
-    const { agent, definition, agentDir, workspace, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, } = opened;
-    reportLine("agent", agentDir);
-    reportLine("workspace", workspace);
-    reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
-    reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
-    await reportAuth(agentDir, modelSpec, authPath);
-    reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    if (definition.persona)
-        reportLine("persona", "persona.md");
-    reportLine("skills", definition.skills.map((s) => s.name).join(", ") || "(none)");
-    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
-    if (toolNames.length > 0)
-        reportLine("tools", toolNames.join(", "));
-    if (deferredToolNames.length > 0) {
-        reportLine("deferred", `${deferredToolNames.join(", ")} (activated via search_tools)`);
-    }
-    reportToolCollisions(toolCollisions);
-    reportModuleLoadFailures(toolFailures);
-    reportLine("state", stateRoot);
-    reportLine("sessions", sessionsDir);
+    const { agent, agentDir, config, stateRoot, sessionsDir } = opened;
+    // The same report `dev` prints; `state:`/`sessions:` are start's own extras, and the persistence
+    // notes below are why (see reportAssembly on the asymmetry).
+    await reportAssembly(opened, {
+        afterTools: [
+            ["state", stateRoot],
+            ["sessions", sessionsDir],
+        ],
+    });
     // State defaults under the agent dir, which a redeploy may replace wholesale. Gate on where the
     // state root ACTUALLY resolved (inside the agent dir?), not on the raw env var: an empty
     // `FASTAGENT_STATE_DIR=""` reads as unset (resolveStateRoot) and still lands in-agent, so a raw
@@ -81,7 +65,6 @@ export async function runStart(dirArg, opts) {
         log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
             `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
     }
-    reportFindingsIfChanged(definition.dir, definition);
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
     // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
@@ -119,12 +102,6 @@ export async function runStart(dirArg, opts) {
     // and replays it next start (turn-store.ts, L1 durable execution, at-least-once); HTTP and other
     // channels have no such layer, so their in-flight turns are still lost (the asker re-invokes).
 }
-/**
- * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) into the
- * writable secrets dir ONCE — only when the seed is set AND the auth file is absent, so a refreshed
- * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
- * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
- */
 /** The opener, kept as its own call so `opened` can also feed the shared assembly below. */
 function openStartDir(dir, opts, sessionsDir) {
     return createPiAgentFromDir(dir, {
@@ -134,14 +111,25 @@ function openStartDir(dir, opts, sessionsDir) {
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
 }
+/**
+ * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) into the
+ * writable secrets dir ONCE — only when the seed is set AND the auth file is absent, so a refreshed
+ * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
+ * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
+ */
 async function maybeSeedAuth(authPath) {
     // collectAuthSeed: the seed may arrive CHUNKED (FASTAGENT_AUTH_SEED + _2…) on hosts with a small
     // env-value max length (AgentCore); single-var hosts are unchanged.
     const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
     if (!bytes)
         return;
-    await mkdir(dirname(authPath), { recursive: true });
-    await writeFile(authPath, bytes);
+    await ensureSecretsDir(dirname(authPath));
+    // Same spelling as the credential store: the mode is applied before the content is reachable, so
+    // the seed can never be published at some other file's looser permissions. It does NOT close the
+    // gap between the `exists` check and the write — the rename would overwrite a file created in
+    // between, against this function's absent-only promise. That window needs two `start` processes on
+    // one secrets dir, which no supported deployment runs (one container, one volume).
+    writeFileAtomic(authPath, bytes, SECRET_FILE_MODE);
     log.info(`[fastagent] seeded ${authPath} from FASTAGENT_AUTH_SEED (first boot)`);
 }
 /**
@@ -160,5 +148,7 @@ function armWakeAlarms(stateRoot) {
     const sink = createWakeAlarmSink({ secret });
     setWakeupsSink(sink);
     log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
-    return () => reconcileWakeAlarms(stateRoot, sink);
+    // Boot reconcile: pending wake-ups may exist while their alarms were lost (a deploy replaced the
+    // forwarder, a sink call failed). The sink re-reads the store, so a bare notification is enough.
+    return () => sink(stateRoot);
 }

package/dist/cli/serve.d.ts

@@ -1,15 +1,5 @@
 import type { ChannelHandler } from "../channel.ts";
 import type { AgentService } from "../service.ts";
-/**
- * Mount the session control plane (`/control/*`) when the agent enabled it
- * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
- * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
- * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
- * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
- * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
- * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
- * and silently shadowing either side would serve a surface the author didn't write.
- */
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
  * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
@@ -20,6 +10,12 @@ import type { AgentService } from "../service.ts";
  * came from config is broken runtime configuration (1).
  */
 export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
+/**
+ * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
+ * what mounted. One function because both commands must say the same thing at the same moment —
+ * after readiness, never at socket bind.
+ */
+export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
 /**
  * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
  * ONE function because they are one message — they were two, and `--bind` updated the first while the
@@ -29,21 +25,16 @@ export declare function assertTunnelBindable(host: string | undefined, tunnel: b
  * A wildcard bind is every interface, and naming one address there would understate it — but the curl
  * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
  */
-/**
- * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
- * what mounted. One function because both commands must say the same thing at the same moment —
- * after readiness, never at socket bind.
- */
-export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
 export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
-/**
- * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
- * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command. `host` unset binds all interfaces.
- */
 /** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
  *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
 export declare const SHUTDOWN_GRACE_MS = 800;
+/**
+ * Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment: a bound
+ * socket is not a serving agent while a declared long-connection channel is still dialling, so this
+ * awaits `hooks.ready` (mountAgentService owns the connections themselves) before announcing
+ * anything. Signals are the sole clean-shutdown command; `host` unset binds all interfaces.
+ */
 export declare function serve(handler: ChannelHandler, bind: {
     port: number;
     host?: string;

package/dist/cli/serve.js

@@ -10,18 +10,9 @@ import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.j
 import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
+import { declaredChannels } from "../channels/discover.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup, failUsage } from "./fail.js";
-/**
- * Mount the session control plane (`/control/*`) when the agent enabled it
- * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
- * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
- * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
- * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
- * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
- * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
- * and silently shadowing either side would serve a surface the author didn't write.
- */
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
  * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
@@ -44,15 +35,6 @@ export function assertTunnelBindable(host, tunnel, source) {
         failUsage(message);
     failStartup(new Error(message));
 }
-/**
- * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
- * ONE function because they are one message — they were two, and `--bind` updated the first while the
- * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
- * neither can be changed without the other in view, and the address has a single derivation.
- *
- * A wildcard bind is every interface, and naming one address there would understate it — but the curl
- * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
- */
 /**
  * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
  * what mounted. One function because both commands must say the same thing at the same moment —
@@ -67,6 +49,15 @@ export function reportServing(service, host, boundPort) {
         log.info(`[fastagent] long connections: ${service.channels.longConnections.join(", ")}`);
     }
 }
+/**
+ * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
+ * ONE function because they are one message — they were two, and `--bind` updated the first while the
+ * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
+ * neither can be changed without the other in view, and the address has a single derivation.
+ *
+ * A wildcard bind is every interface, and naming one address there would understate it — but the curl
+ * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ */
 export function readyAddressLines(host, boundPort, builtinInvoke) {
     const dial = `${clientHost(host)}:${boundPort}`;
     const lines = [
@@ -77,15 +68,16 @@ export function readyAddressLines(host, boundPort, builtinInvoke) {
     }
     return lines;
 }
-/**
- * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
- * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command. `host` unset binds all interfaces.
- */
 /** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
  *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
 export const SHUTDOWN_GRACE_MS = 800;
 const FORCED_EXIT_MS = 1_500;
+/**
+ * Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment: a bound
+ * socket is not a serving agent while a declared long-connection channel is still dialling, so this
+ * awaits `hooks.ready` (mountAgentService owns the connections themselves) before announcing
+ * anything. Signals are the sole clean-shutdown command; `host` unset binds all interfaces.
+ */
 export function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
     const hosted = serveNode(handler, { port, host });
@@ -155,7 +147,10 @@ export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoo
     void startCloudflareTunnel(boundPort).then((instance) => {
         if (!instance)
             return;
-        void announceWebhooks(agentDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        void announceWebhooks(agentDir, instance.url, declaredChannels(routeChannels), {
+            openUrl: openExternalUrl,
+            stateRoot,
+        });
         const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);

package/dist/cli/shared.d.ts

@@ -1,16 +1,46 @@
 import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
+import type { LoadedDefinition } from "../engines/pi/definition.ts";
+import type { ModuleLoadFailure } from "../loader.ts";
+import type { ToolCollision } from "../engines/pi/tool.ts";
+/** What the startup report reads off an opened directory — a structural subset of the opener's return,
+ *  spelled out so this module does not depend on that function's whole shape. */
+export interface ReportableAssembly {
+    agentDir: string;
+    workspace: string;
+    modelSpec: string;
+    authPath: string;
+    config: {
+        thinkingLevel?: string;
+    };
+    definition: LoadedDefinition;
+    toolNames: string[];
+    deferredToolNames: string[];
+    toolCollisions: ToolCollision[];
+    toolFailures: ModuleLoadFailure[];
+}
 /**
- * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
- * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
- * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
- * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
- * policy (pad, never hand-space), not a constant.
+ * What `dev` and `start` say about the directory they just opened, in the order they say it.
+ *
+ * ONE function because it is one report: the two commands wrote it out line by line, and the copies
+ * had already diverged over which lines exist at all — `dev` naming the config file, `start` naming
+ * state and sessions. A line added to one of two hand-written copies is invisible in the other.
+ *
+ * The divergence itself is PRESERVED, not resolved: `start`'s `state:`/`sessions:` pair introduces the
+ * persistence warnings that follow it in production posture, and `dev`'s `config:` has no counterpart
+ * there. Both are passed as explicit extras by the caller, so the asymmetry is visible at the call
+ * site rather than buried in two copies of a list. Whether it is RIGHT is a separate question from
+ * whether it has one owner.
+ *
+ * Findings (skill collisions, definition diagnostics) CLOSE the report — they are about the assembly
+ * just printed. What a command says next is its own posture talk, not report: `start`'s persistence
+ * notes now follow them rather than precede them.
  */
-export declare function reportLine(label: string, value: string): void;
-/** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
- *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
- *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
-export declare function reportWorkspaceHint(hint: string | undefined): void;
+export declare function reportAssembly(a: ReportableAssembly, extras?: {
+    /** Printed between `workspace:`/`hint:` and `model:` (`dev` names the config file here). */
+    beforeModel?: [label: string, value: string][];
+    /** Printed after the tool lines, before findings (`start` names state + sessions here). */
+    afterTools?: [label: string, value: string][];
+}): Promise<void>;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
 /**

package/dist/cli/shared.js

@@ -12,7 +12,10 @@ import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resol
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
-import { log } from "../log.js";
+import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
+import { workspaceHint } from "../paths.js";
+import { log, reportModuleLoadFailures } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { bindAddress, isBindAddress } from "../bind.js";
 import { failStartup, failUsage } from "./fail.js";
@@ -22,17 +25,61 @@ import { failStartup, failUsage } from "./fail.js";
  * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
  * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
  * policy (pad, never hand-space), not a constant.
+ *
+ * Private to this module: {@link reportAssembly} is the report, and a command reaching past it for a
+ * line of its own is how the two copies of that report came to differ.
  */
-export function reportLine(label, value) {
+function reportLine(label, value) {
     log.info(`[fastagent] ${`${label}:`.padEnd(13)}${value}`);
 }
 /** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
  *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
- *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
-export function reportWorkspaceHint(hint) {
+ *  as one and is silent otherwise. */
+function reportWorkspaceHint(hint) {
     if (hint)
         reportLine("hint", hint);
 }
+/**
+ * What `dev` and `start` say about the directory they just opened, in the order they say it.
+ *
+ * ONE function because it is one report: the two commands wrote it out line by line, and the copies
+ * had already diverged over which lines exist at all — `dev` naming the config file, `start` naming
+ * state and sessions. A line added to one of two hand-written copies is invisible in the other.
+ *
+ * The divergence itself is PRESERVED, not resolved: `start`'s `state:`/`sessions:` pair introduces the
+ * persistence warnings that follow it in production posture, and `dev`'s `config:` has no counterpart
+ * there. Both are passed as explicit extras by the caller, so the asymmetry is visible at the call
+ * site rather than buried in two copies of a list. Whether it is RIGHT is a separate question from
+ * whether it has one owner.
+ *
+ * Findings (skill collisions, definition diagnostics) CLOSE the report — they are about the assembly
+ * just printed. What a command says next is its own posture talk, not report: `start`'s persistence
+ * notes now follow them rather than precede them.
+ */
+export async function reportAssembly(a, extras = {}) {
+    reportLine("agent", a.agentDir);
+    reportLine("workspace", a.workspace);
+    reportWorkspaceHint(workspaceHint(a));
+    for (const [label, value] of extras.beforeModel ?? [])
+        reportLine(label, value);
+    reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
+    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
+    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
+    if (a.definition.persona)
+        reportLine("persona", "persona.md");
+    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
+    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
+    if (a.toolNames.length > 0)
+        reportLine("tools", a.toolNames.join(", "));
+    if (a.deferredToolNames.length > 0) {
+        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
+    }
+    reportToolCollisions(a.toolCollisions);
+    reportModuleLoadFailures(a.toolFailures);
+    for (const [label, value] of extras.afterTools ?? [])
+        reportLine(label, value);
+    reportFindingsIfChanged(a.definition.dir, a.definition);
+}
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);

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

@@ -29,7 +29,7 @@ export type AgentcoreLogsOutcome = {
 };
 /**
  * Find and tail one AgentCore log source. Discovery is dynamic rather than spelling `-DEFAULT`:
- * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. Runtime tailing
- * filters the log STREAM prefix so OTEL/spans in the same group never pollute the application log.
+ * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. The whole group
+ * is tailed — see the file header for why a stream filter cannot narrow it and must not be added.
  */
 export declare function tailAgentcoreLogs(plan: AgentcoreLogsPlan, aws: CliRunner, announce?: (message: string) => void): Promise<AgentcoreLogsOutcome>;

package/dist/deploy/agentcore/logs.js

@@ -17,8 +17,8 @@ function parseLogGroupNames(stdout) {
 }
 /**
  * Find and tail one AgentCore log source. Discovery is dynamic rather than spelling `-DEFAULT`:
- * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. Runtime tailing
- * filters the log STREAM prefix so OTEL/spans in the same group never pollute the application log.
+ * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. The whole group
+ * is tailed — see the file header for why a stream filter cannot narrow it and must not be added.
  */
 export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
     const stack = `fastagent-${plan.name}`;

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

@@ -1,4 +1,4 @@
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
 /** The one schedule fact the plan needs (from loadSchedules) — name + cron + tz. */
 export interface ScheduleFact {
@@ -11,10 +11,9 @@ export interface AgentcorePlanInput extends ContainerInput {
     name: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Known first-party channels — each contributes its secret metadata + webhook step. */
-    channels: ChannelKind[];
-    /** ALL route-channel basenames (customs included) — any of them requires the forwarder. */
-    routeChannels: string[];
+    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
+     *  whether the forwarder is needed at all (ANY webhook channel requires it, customs included). */
+    channels: readonly DeclaredChannel[];
     /** Extra secret env-var names (fastagent.config deploy.secrets). */
     extraSecrets?: string[];
     /** Static schedules — each becomes an EventBridge Scheduler rule targeting the forwarder. */
@@ -118,15 +117,18 @@ export declare function toEventBridgeCron(cron: string): {
     error: string;
 };
 /**
- * The forwarder Lambda source — the ONLY string both the template's inline ZipFile and the readable
+ * The forwarder Lambda source — the ONLY string both the deployment package and the readable
  * `lambda/forwarder.js` artifact are generated from (one source, no drift). Zero-dependency: the
- * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: CloudFormation inline code always
- * lands as `index.js`, where ESM `import` is a syntax error (found by the first real deploy). Two
+ * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: the package's entry lands as
+ * `index.js` ({@link zipSingleFile}), where ESM `import` is a syntax error. Two
  * event shapes: a Function URL webhook (reconstructed verbatim into a `webhook` envelope; the
  * channel's REAL response rides back inside the transport reply and is re-emitted byte-exact —
  * Feishu's URL-verification challenge depends on it), and an EventBridge Scheduler fire
- * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key). MUST stay
- * under CloudFormation's 4096-byte inline-code cap.
+ * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key).
+ *
+ * It ships as an S3 object rather than inline `ZipFile`, so there is no 4096-byte ceiling on it — a
+ * constraint this comment asserted for long after the template stopped inlining, which is the kind
+ * of stale rule that stops the next person making a correct change.
  */
 export declare function forwarderSource(): string;
 /**

package/dist/deploy/agentcore/plan.js

@@ -30,6 +30,7 @@
 import { createHash } from "node:crypto";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
+import { webhookKinds, webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
@@ -215,15 +216,18 @@ function yamlSingleQuote(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }
 /**
- * The forwarder Lambda source — the ONLY string both the template's inline ZipFile and the readable
+ * The forwarder Lambda source — the ONLY string both the deployment package and the readable
  * `lambda/forwarder.js` artifact are generated from (one source, no drift). Zero-dependency: the
- * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: CloudFormation inline code always
- * lands as `index.js`, where ESM `import` is a syntax error (found by the first real deploy). Two
+ * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: the package's entry lands as
+ * `index.js` ({@link zipSingleFile}), where ESM `import` is a syntax error. Two
  * event shapes: a Function URL webhook (reconstructed verbatim into a `webhook` envelope; the
  * channel's REAL response rides back inside the transport reply and is re-emitted byte-exact —
  * Feishu's URL-verification challenge depends on it), and an EventBridge Scheduler fire
- * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key). MUST stay
- * under CloudFormation's 4096-byte inline-code cap.
+ * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key).
+ *
+ * It ships as an S3 object rather than inline `ZipFile`, so there is no 4096-byte ceiling on it — a
+ * constraint this comment asserted for long after the template stopped inlining, which is the kind
+ * of stale rule that stops the next person making a correct change.
  */
 export function forwarderSource() {
     return `// Generated by \`fastagent deploy agentcore\` — the deployment's only ingress.
@@ -250,6 +254,15 @@ let ownUrl; // self-resolved once per cold start; rides on every envelope for th
 const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => \`%\${c.charCodeAt(0).toString(16).toUpperCase()}\`);
 const hmac = (key, data) => crypto.createHmac("sha256", key).update(data).digest();
 
+// Every shared-secret gate on this public URL goes through here. Constant-time, and an unset
+// expected secret NEVER matches — otherwise a topology that did not configure one would accept a
+// request that sent none. Non-string input is coerced to "" first: Buffer.from(8) allocates eight
+// bytes rather than throwing, which would compare a number against a secret by length alone.
+const secretEq = (given, expected) => {
+  const a = Buffer.from(typeof given === "string" ? given : ""), b = Buffer.from(expected || "");
+  return b.length > 0 && a.length === b.length && crypto.timingSafeEqual(a, b);
+};
+
 function presign(method, seconds) {
   const bucket = process.env.STATE_BUCKET, key = process.env.STATE_KEY, region = process.env.AWS_REGION;
   const host = \`\${bucket}.s3.\${region}.amazonaws.com\`;
@@ -375,11 +388,7 @@ exports.handler = async (event, ctx) => {
   // The container may settle long after the webhook Lambda (and its credentials) expired.
   if (event.rawPath === "/__fastagent/state-urls") {
     const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
-    const actual = Buffer.from(typeof req.auth === "string" ? req.auth : "");
-    const expected = Buffer.from(process.env.STATE_REFRESH_SECRET || "");
-    if (!expected.length || actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
-      return { statusCode: 403, body: "forbidden\\n" };
-    }
+    if (!secretEq(req.auth, process.env.STATE_REFRESH_SECRET)) return { statusCode: 403, body: "forbidden\\n" };
     return {
       statusCode: 200,
       headers: { "content-type": "application/json" },
@@ -389,7 +398,7 @@ exports.handler = async (event, ctx) => {
   // The container's wake-alarm callback (reserved path, shared secret) — handled HERE, never forwarded.
   if (event.rawPath === "/__fastagent/wake-alarm") {
     const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
-    if (!process.env.WAKE_SECRET || req.secret !== process.env.WAKE_SECRET) return { statusCode: 403, body: "forbidden\\n" };
+    if (!secretEq(req.secret, process.env.WAKE_SECRET)) return { statusCode: 403, body: "forbidden\\n" };
     const failed = await syncAlarms(req.alarms || [], ctx);
     // Partial failure IS failure: the container retries the whole (idempotent) set until every
     // pending wake really has its alarm.
@@ -405,7 +414,7 @@ exports.handler = async (event, ctx) => {
   // public traffic) are probeable too.
   if (event.rawPath === "/__fastagent/probe") {
     const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
-    if (!process.env.INGRESS_SECRET || req.auth !== process.env.INGRESS_SECRET) return { statusCode: 403, body: "forbidden\\n" };
+    if (!secretEq(req.auth, process.env.INGRESS_SECRET)) return { statusCode: 403, body: "forbidden\\n" };
     const r = await invoke({ kind: "probe" });
     if (r.status !== 200) {
       console.log(\`probe transport error \${r.status}: \${r.body}\`);
@@ -465,7 +474,7 @@ function template(input, translated) {
     // a schedule turn can outlive both its original presigned URL and the Lambda credentials that signed
     // it. Schedule-only URLs reject every non-reserved HTTP path before invoking AgentCore, so they do
     // not expose a webhook/data plane (and start never mounts the builtin /invoke under AgentCore).
-    const needsForwarder = input.routeChannels.length > 0 || translated.length > 0 || input.selfSchedule;
+    const needsForwarder = input.channels.some((channel) => channel.ingress === "webhook") || translated.length > 0 || input.selfSchedule;
     const needsFunctionUrl = needsForwarder;
     const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
     const forwarderFnArn = `!Sub arn:aws:lambda:\${AWS::Region}:\${AWS::AccountId}:function:fastagent-${input.name}-forwarder`;
@@ -604,7 +613,7 @@ function template(input, translated) {
                 `                Action: lambda:GetFunctionUrlConfig`,
                 `                Resource: ${forwarderFnArn}`,
             ]
-            : []), ``, `  Forwarder:`, `    Type: AWS::Lambda::Function`, `    Properties:`, `      FunctionName: fastagent-${input.name}-forwarder`, `      Runtime: nodejs22.x`, `      Handler: index.handler`, `      # Webhook ACKs are fast, but schedule-fire holds the connection for the WHOLE agent turn`, `      # (claim-before-run means a timeout never double-fires; the turn also continues and is`, `      # audited container-side). EventBridge→Lambda is async, so the long timeout costs nothing.`, `      Timeout: 900`, `      MemorySize: 256`, `      Role: !GetAtt ForwarderRole.Arn`, `      Environment:`, `        Variables:`, `          RUNTIME_ARN: !GetAtt Runtime.AgentRuntimeArn`, `          INGRESS_SESSION_ID: ${ingressSessionId(input.name)}`, ...(needsFunctionUrl ? [`          STATE_REFRESH_SECRET: !Ref FastagentIngressSecret`] : []), ...(input.routeChannels.length > 0 ? [`          WEBHOOKS_ENABLED: "1"`] : []), ...(input.selfSchedule
+            : []), ``, `  Forwarder:`, `    Type: AWS::Lambda::Function`, `    Properties:`, `      FunctionName: fastagent-${input.name}-forwarder`, `      Runtime: nodejs22.x`, `      Handler: index.handler`, `      # Webhook ACKs are fast, but schedule-fire holds the connection for the WHOLE agent turn`, `      # (claim-before-run means a timeout never double-fires; the turn also continues and is`, `      # audited container-side). EventBridge→Lambda is async, so the long timeout costs nothing.`, `      Timeout: 900`, `      MemorySize: 256`, `      Role: !GetAtt ForwarderRole.Arn`, `      Environment:`, `        Variables:`, `          RUNTIME_ARN: !GetAtt Runtime.AgentRuntimeArn`, `          INGRESS_SESSION_ID: ${ingressSessionId(input.name)}`, ...(needsFunctionUrl ? [`          STATE_REFRESH_SECRET: !Ref FastagentIngressSecret`] : []), ...(input.channels.some((channel) => channel.ingress === "webhook") ? [`          WEBHOOKS_ENABLED: "1"`] : []), ...(input.selfSchedule
             ? [
                 `          WAKE_SECRET: !Ref FastagentWakeSecret`,
                 `          WAKE_ROLE_ARN: !GetAtt WakeSchedulerRole.Arn`,
@@ -671,7 +680,7 @@ export function planAgentcoreDeploy(input) {
     }
     // Every forwarder needs its authenticated Function URL to refresh S3 snapshot capabilities during
     // a long turn. Without route channels, ordinary HTTP paths are rejected before AgentCore is invoked.
-    const needsForwarder = input.routeChannels.length > 0 || translated.length > 0 || input.selfSchedule;
+    const needsForwarder = input.channels.some((channel) => channel.ingress === "webhook") || translated.length > 0 || input.selfSchedule;
     const needsFunctionUrl = needsForwarder;
     const artifacts = [
         { path: `${prefix}${TEMPLATE_FILE}`, content: template(input, translated) },
@@ -743,22 +752,21 @@ export function planAgentcoreDeploy(input) {
             ? `# Model auth: none found at the local auth path — pass --auth-path <file>, or \`--run\` carries it`
             : `# Model auth: your local auth is "${input.modelAuth}" — the plan can't read its value; \`--run\` carries it`, `#   as the FastagentAuthSeed parameter (base64 of auth.json), materialized on first boot.`);
     }
-    // Post-deploy webhook registration — same per-channel steps as every host, pointed at the
-    // forwarder's Function URL (read from the stack outputs).
-    const post = [];
-    if (channels.includes("telegram")) {
-        post.push(`# Register the Telegram webhook (default route POST /telegram; secret_token MUST equal TELEGRAM_SECRET_TOKEN):`, `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`, `  -d url=<ForwarderUrl>/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
-    }
-    if (channels.includes("github")) {
-        post.push(`# Set the GitHub webhook (repo Settings → Webhooks): Payload URL = <ForwarderUrl>/webhook,`, `#   content type application/json, secret = GITHUB_WEBHOOK_SECRET.`, `# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy + time_of_last_update holds the session while turns run, but the 8 h compute ceiling is hard).`);
-    }
-    if (channels.includes("slack")) {
-        post.push(`# Set Slack Event Subscriptions → Request URL = <ForwarderUrl>/slack (scopes per channels/slack.ts).`);
-    }
-    for (const kind of ["feishu", "lark"]) {
-        if (!channels.includes(kind))
-            continue;
-        post.push(`# Set the ${kind === "feishu" ? "Feishu" : "Lark"} event Request URL (developer console → Events & Callbacks):`, `#   Request URL = <ForwarderUrl>/${kind} (the stack must be deployed when you save — the console`, `#   sends a challenge, which rides through the forwarder to the channel and back verbatim).`);
+    // Post-deploy webhook registration — the shared channel-ingress steps, pointed at the forwarder's
+    // Function URL (read from the stack outputs). `--run` REFUSES a long-connection channel here, but
+    // generate-only only warns and still prints this runbook, so the steps are filtered on ingress like
+    // every other host's rather than on the CLI having gated.
+    const post = webhookRunbook(`<ForwarderUrl>`, channels);
+    // AgentCore asides the shared steps cannot carry: nothing else routes through a forwarder, and
+    // nothing else has a compute ceiling.
+    // Named rather than positional: the asides land after ALL the steps, so "the console" has to say
+    // WHICH console. One line for both kinds — an agent that declares feishu AND lark reads the same
+    // fact twice otherwise and looks for a second step that does not exist.
+    if (webhookKinds(channels).some((kind) => kind === "feishu" || kind === "lark")) {
+        post.push(`# NOTE: the Feishu/Lark console's challenge rides through the forwarder to the channel and back`, `#   verbatim, so the stack must be deployed when you save the Request URL.`);
+    }
+    if (channels.some((channel) => channel.name === "github")) {
+        post.push(`# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy + time_of_last_update holds the session while turns run, but the 8 h compute ceiling is hard).`);
     }
     if (post.length > 0)
         runbook.push(``, ...post);