@fastagent-sh/fastagent 0.19.0 → 0.21.0

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. */
@@ -32,6 +31,25 @@ export interface AgentcorePlan {
         name: string;
         reason: string;
     }[];
+    /** What the stack contains — the ONE reading the template, the runbook and the `--run` driver share. */
+    topology: AgentcoreTopology;
+}
+/**
+ * Which resources the definition puts in the stack. Read in one place because it was computed in
+ * three — the template, the plan and the CLI — and the third disagreed with the first about a
+ * schedule EventBridge cannot express (counted by the CLI, not by the template), which is a
+ * `cloudformation deploy` rejecting parameters the template never declared.
+ */
+export interface AgentcoreTopology {
+    /** A webhook channel: the forwarder relays public Function URL traffic to it. */
+    webhooks: boolean;
+    /** The forwarder Lambda exists — for webhooks, for EventBridge cron rules, or for wake alarms —
+     *  with its Function URL: every forwarder needs it as the authenticated refresh channel for the
+     *  state snapshot's presigned URLs, since a turn can outlive the Lambda credentials that signed
+     *  them. A schedule-only URL rejects every non-reserved path before invoking AgentCore. */
+    forwarder: boolean;
+    /** The forwarder mirrors the agent's wake-ups into one-shot EventBridge schedules. */
+    wakeAlarms: boolean;
 }
 /** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
  *  a fast LOCAL disk only: the platform wipes it on every runtime version update (= every deploy).
@@ -118,15 +136,20 @@ export declare function toEventBridgeCron(cron: string): {
     error: string;
 };
 /**
- * The forwarder Lambda source — the ONLY string both the template's inline ZipFile 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
+ * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment
+ * package and the readable `lambda/index.js` artifact are generated from. A real file, not a template
+ * literal: it is linted, and it needs no interpolation — the one value it once took from here
+ * (`MAX_WEBHOOK_BODY_BYTES`) rides in as a Lambda environment variable. Zero-dependency: the
+ * 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

@@ -28,10 +28,22 @@
  *  host where the build runs on the operator's machine (docker buildx) instead of remotely.
  */
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 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";
+function agentcoreTopology(input, 
+/** Schedules EventBridge CAN express — the ones that become rules. */
+translatedSchedules) {
+    const webhooks = input.channels.some((channel) => channel.ingress === "webhook");
+    return {
+        webhooks,
+        forwarder: webhooks || translatedSchedules > 0 || input.selfSchedule,
+        wakeAlarms: input.selfSchedule,
+    };
+}
 /** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
  *  a fast LOCAL disk only: the platform wipes it on every runtime version update (= every deploy).
  *  Durability across deploys comes from the S3 snapshot (channels/agentcore-state.ts). */
@@ -215,233 +227,23 @@ function yamlSingleQuote(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }
 /**
- * The forwarder Lambda source — the ONLY string both the template's inline ZipFile 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
+ * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment
+ * package and the readable `lambda/index.js` artifact are generated from. A real file, not a template
+ * literal: it is linted, and it needs no interpolation — the one value it once took from here
+ * (`MAX_WEBHOOK_BODY_BYTES`) rides in as a Lambda environment variable. Zero-dependency: the
+ * 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.
-// REGENERATED ON EVERY DEPLOY; edits here are overwritten and never deployed. \`--run\` builds the
-// Lambda package from fastagent's own copy of this source, so this file is the readable MIRROR of
-// what runs (and what the manual runbook zips) — not an input you can change.
-// Webhooks (Function URL) and EventBridge Scheduler fires are forwarded as envelopes to the
-// AgentCore Runtime over SigV4 InvokeAgentRuntime, all on ONE fixed ingress session (fastagent
-// channel state is single-writer; one session = at most one microVM). With selfSchedule, this
-// Lambda also OWNS the wake alarms: the container POSTs its pending wake-ups to /__fastagent/
-// wake-alarm (shared secret) and each becomes a self-deleting one-shot EventBridge schedule that
-// pokes this Lambda — which wakes the container, whose wake pump fires the due entry.
-// CommonJS on purpose: the deployment package's entry lands as index.js, where ESM import is invalid.
-"use strict";
-const crypto = require("node:crypto");
-const { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } = require("@aws-sdk/client-bedrock-agentcore");
-const client = new BedrockAgentCoreClient({});
-let ownUrl; // self-resolved once per cold start; rides on every envelope for the wake-alarm callback
-
-// Presigned S3 URLs for the container's state snapshot. AgentCore wipes the /mnt/state mount on
-// every runtime version update (= every deploy), so the durable copy lives in S3 — but the
-// container is given NO AWS credentials by the platform, so the only reachable form is a URL that
-// carries its own authorization. SigV4 query signing, node:crypto only (no SDK, nothing to install).
-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();
-
-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\`;
-  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\\.\\d+/, "");
-  const scope = \`\${stamp.slice(0, 8)}/\${region}/s3/aws4_request\`;
-  const pairs = [
-    ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
-    ["X-Amz-Credential", \`\${process.env.AWS_ACCESS_KEY_ID}/\${scope}\`],
-    ["X-Amz-Date", stamp],
-    ["X-Amz-Expires", String(seconds)],
-    ["X-Amz-SignedHeaders", "host"],
-  ];
-  if (process.env.AWS_SESSION_TOKEN) pairs.push(["X-Amz-Security-Token", process.env.AWS_SESSION_TOKEN]);
-  // The canonical query must be byte-identical to the one on the wire — build it ONCE, reuse below.
-  const query = pairs
-    .map(([k, v]) => [enc(k), enc(v)])
-    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
-    .map((p) => p.join("="))
-    .join("&");
-  const path = \`/\${key.split("/").map(enc).join("/")}\`;
-  const canonical = [method, path, query, \`host:\${host}\\n\`, "host", "UNSIGNED-PAYLOAD"].join("\\n");
-  const sts = ["AWS4-HMAC-SHA256", stamp, scope, crypto.createHash("sha256").update(canonical).digest("hex")].join("\\n");
-  let k = hmac(\`AWS4\${process.env.AWS_SECRET_ACCESS_KEY}\`, stamp.slice(0, 8));
-  for (const part of [region, "s3", "aws4_request"]) k = hmac(k, part);
-  return \`https://\${host}\${path}?\${query}&X-Amz-Signature=\${hmac(k, sts).toString("hex")}\`;
-}
-
-async function invoke(envelope) {
-  if ((process.env.WAKE_SECRET || process.env.STATE_REFRESH_SECRET) && !ownUrl) {
-    const { LambdaClient, GetFunctionUrlConfigCommand } = require("@aws-sdk/client-lambda");
-    ownUrl = (await new LambdaClient({}).send(
-      new GetFunctionUrlConfigCommand({ FunctionName: process.env.AWS_LAMBDA_FUNCTION_NAME }),
-    )).FunctionUrl;
-  }
-  if (ownUrl) envelope.wake = { url: ownUrl };
-  // Authenticates this envelope as coming from the forwarder (see the template's FastagentIngressSecret).
-  envelope.auth = process.env.INGRESS_SECRET;
-  // Keep each capability short-lived. Function-URL deployments also carry an authenticated refresh
-  // endpoint, so a background turn settling hours after its webhook never depends on the temporary
-  // Lambda credentials that signed the original pair still being alive.
-  if (process.env.STATE_BUCKET) envelope.state = {
-    getUrl: presign("GET", 3600),
-    putUrl: presign("PUT", 3600),
-    ...(ownUrl && process.env.STATE_REFRESH_SECRET ? {
-      refresh: { url: ownUrl.replace(/\\/$/, "") + "/__fastagent/state-urls", auth: process.env.STATE_REFRESH_SECRET },
-    } : {}),
-  };
-  const res = await client.send(new InvokeAgentRuntimeCommand({
-    agentRuntimeArn: process.env.RUNTIME_ARN,
-    runtimeSessionId: process.env.INGRESS_SESSION_ID,
-    contentType: "application/json",
-    accept: "application/json",
-    payload: new TextEncoder().encode(JSON.stringify(envelope)),
-  }));
-  const body = Buffer.from(await res.response.transformToByteArray());
-  return { status: res.statusCode ?? 200, body };
-}
-
-// Mirror the container's pending wake-ups into one-shot schedules: at(fireAt), poke me, delete
-// after firing. Upsert (create → conflict → update). The container pre-filters DUE alarms (it is
-// awake handling those), so every failure here is REAL — counted and propagated: a swallowed error
-// would leave a pending wake with no alarm, exactly the reliability hole this mechanism closes.
-// Cancelled wakes are NOT deleted here: their poke fires, finds nothing due, and the schedule
-// self-deletes (lazy cleanup by design).
-async function syncAlarms(alarms, ctx) {
-  const { SchedulerClient, CreateScheduleCommand, UpdateScheduleCommand } = require("@aws-sdk/client-scheduler");
-  const sch = new SchedulerClient({});
-  let failed = 0;
-  // Alarm name = a stable hash of the WHOLE wake id. A prefix of the id would collide (two wakes
-  // sharing 8 hex chars), and a collision is INDISTINGUISHABLE from the legitimate re-arm below:
-  // the second wake would "update" the first's alarm and silently steal its fire time.
-  const names = new Map();
-  for (const a of alarms) {
-    const name = process.env.WAKE_PREFIX + crypto.createHash("sha256").update(a.id).digest("hex").slice(0, 16);
-    if (names.has(name)) {
-      failed += 1;
-      console.log(\`alarm name collision \${name}: \${names.get(name)} vs \${a.id}\`);
-      continue;
-    }
-    names.set(name, a.id);
-    const p = {
-      Name: name,
-      ScheduleExpression: \`at(\${a.at.slice(0, 19)})\`,
-      ScheduleExpressionTimezone: "UTC",
-      FlexibleTimeWindow: { Mode: "OFF" },
-      ActionAfterCompletion: "DELETE",
-      Target: { Arn: ctx.invokedFunctionArn, RoleArn: process.env.WAKE_ROLE_ARN, Input: '{"wakePoke":true}' },
-    };
-    try {
-      await sch.send(new CreateScheduleCommand(p));
-    } catch (e) {
-      try {
-        if (e.name !== "ConflictException") throw e;
-        await sch.send(new UpdateScheduleCommand(p));
-      } catch (u) {
-        failed += 1;
-        console.log(\`alarm \${p.Name}: \${u}\`);
-      }
-    }
-  }
-  return failed;
-}
-
-exports.handler = async (event, ctx) => {
-  // EventBridge wake-up poke: the invocation itself wakes the container; its pump does the rest.
-  if (event && event.wakePoke) {
-    const r = await invoke({ kind: "wake-poke" });
-    console.log(\`wake-poke: \${r.status}\`);
-    return { status: r.status };
-  }
-  // EventBridge Scheduler fire — throw on failure so the miss lands in CloudWatch, never silently.
-  if (event && event.scheduleFire) {
-    const { name, slot } = event.scheduleFire;
-    const r = await invoke({ kind: "schedule-fire", name, slot });
-    const out = r.body.toString();
-    console.log(\`schedule-fire \${name} (\${slot}): \${r.status} \${out}\`);
-    if (r.status >= 400) throw new Error(\`schedule-fire \${name} failed: \${r.status} \${out}\`);
-    return { status: r.status };
-  }
-  const http = event && event.requestContext && event.requestContext.http;
-  if (!http) throw new Error("unrecognized event shape");
-  // Refresh the snapshot capabilities with THIS Lambda invocation's current temporary credentials.
-  // 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" };
-    }
-    return {
-      statusCode: 200,
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ getUrl: presign("GET", 3600), putUrl: presign("PUT", 3600) }),
-    };
-  }
-  // 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" };
-    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.
-    if (failed > 0) return { statusCode: 500, body: \`\${failed} alarm(s) failed\\n\` };
-    return { statusCode: 200, body: "ok\\n" };
-  }
-  // The deploy driver's probe (reserved path, ingress secret): wake the runtime through the SAME
-  // trusted envelope pipeline (state URLs included — a direct InvokeAgentRuntime call could not mint
-  // them, and would make the runtime construct against a pre-restore mount) and pass its structured
-  // transport-200 verdict back VERBATIM. The ordinary webhook path below folds a non-200 transport
-  // into an opaque 502, which would strip exactly the diagnostics the probe exists to carry — and it
-  // sits BEFORE the WEBHOOKS_ENABLED gate so schedule-only topologies (whose URLs refuse ordinary
-  // 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" };
-    const r = await invoke({ kind: "probe" });
-    if (r.status !== 200) {
-      console.log(\`probe transport error \${r.status}: \${r.body}\`);
-      return { statusCode: 502, body: "upstream error\\n" };
-    }
-    return { statusCode: 200, headers: { "content-type": "application/json" }, body: r.body.toString() };
-  }
-  // Enforce the advertised ORIGINAL-body ceiling before base64 adds another 4/3 inside the runtime
-  // envelope. This also leaves deterministic room for headers/query/JSON under Lambda's 6 MB cap.
-  const webhookBytes = event.body === undefined ? 0
-    : event.isBase64Encoded ? Buffer.byteLength(event.body, "base64") : Buffer.byteLength(event.body);
-  if (webhookBytes > ${MAX_WEBHOOK_BODY_BYTES}) return { statusCode: 413, body: "payload too large\\n" };
-  // A schedule-only deployment has a Function URL solely for the authenticated refresh callback.
-  // Reject arbitrary public traffic BEFORE it can wake AgentCore (cost/DoS) or reach an inner route.
-  if (process.env.WEBHOOKS_ENABLED !== "1") return { statusCode: 404, body: "not found\\n" };
-  // Function URL webhook — forward the original request verbatim (signature material included).
-  const r = await invoke({
-    kind: "webhook",
-    method: http.method,
-    path: event.rawPath || "/",
-    query: event.rawQueryString || undefined,
-    headers: event.headers || {},
-    bodyB64: event.body === undefined ? undefined
-      : event.isBase64Encoded ? event.body : Buffer.from(event.body).toString("base64"),
-  });
-  if (r.status !== 200) {
-    console.log(\`transport error \${r.status}: \${r.body}\`);
-    return { statusCode: 502, body: "upstream error\\n" };
-  }
-  const reply = JSON.parse(r.body.toString()); // { status, headers, bodyB64 } from the adapter
-  for (const k of Object.keys(reply.headers)) {
-    if (/^(content-length|transfer-encoding|connection)$/i.test(k)) delete reply.headers[k];
-  }
-  return { statusCode: reply.status, headers: reply.headers, body: reply.bodyB64, isBase64Encoded: true };
-};
-`;
+    return readFileSync(new URL("./forwarder.js", import.meta.url), "utf8");
 }
 /**
  * The EventBridge physical name for a schedule. A schedule's local name is an arbitrary MODULE FILE
@@ -458,15 +260,9 @@ export function scheduleResourceName(agent, schedule) {
     return `${prefix}${safe.slice(0, room)}-${hash}`;
 }
 /** The CloudFormation template — the whole topology in one stack. */
-function template(input, translated) {
+function template(input, translated, topology) {
     const runtimeName = toRuntimeName(input.name);
-    // selfSchedule needs the forwarder too: it is both the wake-alarm registrar and the poke target.
-    // Every forwarder also gets a Function URL as the authenticated state-capability refresh channel:
-    // 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 needsFunctionUrl = needsForwarder;
+    const needsForwarder = topology.forwarder;
     const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
     const forwarderFnArn = `!Sub arn:aws:lambda:\${AWS::Region}:\${AWS::AccountId}:function:fastagent-${input.name}-forwarder`;
     // Secret env vars ride CFN NoEcho parameters. FASTAGENT_AUTH_SEED is always declared (Default "")
@@ -598,21 +394,21 @@ function template(input, translated) {
                 `                Action: iam:PassRole`,
                 `                Resource: !GetAtt WakeSchedulerRole.Arn`,
             ]
-            : []), ...(needsFunctionUrl
+            : []), ...(needsForwarder
             ? [
                 `              - Effect: Allow # self-resolve callback URL for state-URL refresh / wake alarms`,
                 `                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)}`, ...(needsForwarder ? [`          STATE_REFRESH_SECRET: !Ref FastagentIngressSecret`] : []), ...(topology.webhooks ? [`          WEBHOOKS_ENABLED: "1"`] : []), ...(input.selfSchedule
             ? [
                 `          WAKE_SECRET: !Ref FastagentWakeSecret`,
                 `          WAKE_ROLE_ARN: !GetAtt WakeSchedulerRole.Arn`,
                 `          WAKE_PREFIX: fa-${input.name}-wk-`,
             ]
-            : []), `          INGRESS_SECRET: !Ref FastagentIngressSecret`, `          STATE_BUCKET: !Ref StateBucket`, `          STATE_KEY: ${STATE_KEY}`, `      # From S3, not inline: the forwarder mints SigV4-presigned URLs for the state snapshot and`, `      # no longer fits CloudFormation's 4096-byte inline cap. The key is content-hashed, so a`, `      # code change is a parameter change — CloudFormation cannot miss it.`, `      Code:`, `        S3Bucket: !Ref StateBucket`, `        S3Key: !Ref ForwarderS3Key`);
+            : []), `          INGRESS_SECRET: !Ref FastagentIngressSecret`, `          STATE_BUCKET: !Ref StateBucket`, `          STATE_KEY: ${STATE_KEY}`, `          MAX_WEBHOOK_BODY_BYTES: "${MAX_WEBHOOK_BODY_BYTES}"`, `      # From S3, not inline: the forwarder mints SigV4-presigned URLs for the state snapshot and`, `      # no longer fits CloudFormation's 4096-byte inline cap. The key is content-hashed, so a`, `      # code change is a parameter change — CloudFormation cannot miss it.`, `      Code:`, `        S3Bucket: !Ref StateBucket`, `        S3Key: !Ref ForwarderS3Key`);
     }
-    if (needsFunctionUrl) {
+    if (needsForwarder) {
         lines.push(``, `  ForwarderUrl:`, `    Type: AWS::Lambda::Url`, `    Properties:`, `      TargetFunctionArn: !GetAtt Forwarder.Arn`, `      # NONE is deliberate: webhook callers (Telegram/Feishu) cannot SigV4-sign. Authenticity is`, `      # verified downstream by each channel (secret token / signature), exactly as on every host.`, `      AuthType: NONE`, ``, `  ForwarderUrlPermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunctionUrl`, `      Principal: "*"`, `      FunctionUrlAuthType: NONE`, ``, `  # Function URLs created after Oct 2025 require lambda:InvokeFunction IN ADDITION to`, `  # lambda:InvokeFunctionUrl for public (NONE) access — with only the first, every request 403s`, `  # (found by the first real deploy). InvokedViaFunctionUrl scopes it to URL traffic: without it`, `  # the bare * principal would also let any AWS principal call the Lambda API directly, bypassing`, `  # the Function URL event shape to forge internal events.`, `  ForwarderInvokePermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunction`, `      Principal: "*"`, `      InvokedViaFunctionUrl: true`);
         if (input.selfSchedule) {
             lines.push(``, `  # The role the wake-poke schedules assume to invoke the forwarder. Its policy names the`, `  # function by CONSTRUCTED arn (not !Ref) — the forwarder's env references this role, so a`, `  # !Ref back would be a circular dependency.`, `  WakeSchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: poke-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: ${forwarderFnArn}`);
@@ -625,7 +421,7 @@ function template(input, translated) {
         }
     }
     lines.push(``, `Outputs:`, `  RuntimeArn:`, `    Value: !GetAtt Runtime.AgentRuntimeArn`);
-    if (needsFunctionUrl) {
+    if (needsForwarder) {
         lines.push(`  ForwarderUrl:`, `    Value: !GetAtt ForwarderUrl.FunctionUrl`);
     }
     return `${lines.join("\n")}\n`;
@@ -669,12 +465,10 @@ export function planAgentcoreDeploy(input) {
         }
         paramNames.set(p, s.name);
     }
-    // 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 needsFunctionUrl = needsForwarder;
+    const topology = agentcoreTopology(input, translated.length);
+    const needsForwarder = topology.forwarder;
     const artifacts = [
-        { path: `${prefix}${TEMPLATE_FILE}`, content: template(input, translated) },
+        { path: `${prefix}${TEMPLATE_FILE}`, content: template(input, translated, topology) },
         ...(needsForwarder ? [{ path: `${prefix}${FORWARDER_FILE}`, content: forwarderSource() }] : []),
         ...containerArtifacts(input),
     ];
@@ -726,9 +520,9 @@ export function planAgentcoreDeploy(input) {
     if (input.selfSchedule) {
         runbook.push(`#      FastagentWakeSecret: the wake-alarm shared secret — any random string (\`--run\` mints one)`);
     }
-    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${prefix}${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image}${needsForwarder ? ` StateBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip` : ""}${requiredSecrets.length > 0 ? ` ${paramHint(requiredSecrets)}` : ""}${wakeSecretHint}`, ``, needsFunctionUrl
+    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${prefix}${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image}${needsForwarder ? ` StateBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip` : ""}${requiredSecrets.length > 0 ? ` ${paramHint(requiredSecrets)}` : ""}${wakeSecretHint}`, ``, needsForwarder
         ? `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`
-        : `# 4. Read the outputs (the runtime ARN — this topology has NO public URL: nothing outside AWS`, ...(needsFunctionUrl
+        : `# 4. Read the outputs (the runtime ARN — this topology has NO public URL: nothing outside AWS`, ...(needsForwarder
         ? []
         : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, ...(needsForwarder
         ? [
@@ -743,22 +537,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);
@@ -773,5 +566,5 @@ export function planAgentcoreDeploy(input) {
         runbook.push(``, `# After a REDEPLOY, stop the ingress session so the new image serves immediately — a live session`, `# keeps its old compute (and the OLD image) until ${IDLE_TIMEOUT_SECONDS}s idle / the 8 h compute ceiling`, `# (\`--run\` does this automatically):`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`);
     }
     runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`, `# CREDENTIALS RIDE THAT SNAPSHOT TOO: FASTAGENT_SECRETS_DIR is ${SECRETS_DIR}, inside the state`, `# root, so an OAuth auth.json ROTATED on the box persists (a refresh token is single-use — without`, `# this the next microVM would re-seed the deploy-time copy and eventually fail to authenticate).`, `# The bucket is therefore credential storage: it is created with public access blocked and`, `# versioning on, and deleting it costs model access until the next deploy re-seeds.`);
-    return { artifacts, runbook, untranslatableSchedules: untranslatable };
+    return { artifacts, runbook, untranslatableSchedules: untranslatable, topology };
 }

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

@@ -1,22 +1,7 @@
-/**
- * `fastagent deploy agentcore --run` — drive the AWS CLI + Docker to completion. The middle of the
- * deploy the plain runbook hands to the operator; `--run` executes it so a coding agent runs ONE
- * command. Idempotent (ECR check-then-act; `cloudformation deploy` converges the stack) and
- * resumable: it STOPS at a human gate with one actionable line and a non-zero exit.
- *
- * TWO runners, one seam ({@link CliRunner}): `aws` (identity, ECR, CloudFormation) and `docker`
- * (buildx). AgentCore is the ONE host whose image builds on the operator's machine — the platform
- * requires linux/arm64 in the account's ECR and has no remote builder — so a missing Docker/buildx
- * is a first-class gate, not an incidental failure.
- *
- * Secrets ride CloudFormation NoEcho parameters. `--parameter-overrides` on argv would put the
- * values in the process listing (the same reason Fly imports secrets over stdin), so they go through
- * a caller-provided temp parameters file (`file://…`, mode 0600, deleted by the caller) — the write
- * is injected to keep this module pure and the security-sensitive wiring testable.
- */
-import type { RegistrationOutcome } from "../../channels/registration.ts";
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
+import { type Registrars } from "../channel-ingress.ts";
 import type { CliRunner } from "../runner.ts";
+import { type AgentcoreTopology } from "./plan.ts";
 export interface AgentcoreRunPlan {
     /** The base name — stack `fastagent-<name>`, ECR repo `fastagent/<name>`. */
     name: string;
@@ -35,11 +20,11 @@ export interface AgentcoreRunPlan {
     secrets: Record<string, string>;
     /** Required secret names with NO local value — gated before any side effect. */
     missingSecrets: string[];
-    channels: ChannelKind[];
-    /** Whether the topology includes the forwarder Lambda (route channels / schedules / selfSchedule).
-     *  It owns the state snapshot's presigned URLs, so its absence means an invoke-only deployment
-     *  with no cross-deploy state to keep. */
-    needsForwarder: boolean;
+    /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
+    channels: readonly DeclaredChannel[];
+    /** What the stack contains — the plan's own reading, so this driver cannot disagree with the
+     *  template about whether a forwarder (and with it the state bucket and its parameters) exists. */
+    topology: AgentcoreTopology;
 }
 export type AgentcoreRunOutcome = {
     ok: true;
@@ -70,7 +55,7 @@ export declare function parseCheckpointReply(stdout: string): CheckpointReply |
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>, 
+export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registrars: Registrars, 
 /** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
 probe?: {
     fetchImpl?: typeof fetch;