@fastagent-sh/fastagent 0.20.0 → 0.21.1

package/dist/deploy/agentcore/plan.js

@@ -28,11 +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). */
@@ -216,8 +227,10 @@ function yamlSingleQuote(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }
 /**
- * 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
+ * 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
@@ -230,227 +243,7 @@ function yamlSingleQuote(value) {
  * 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();
-
-// 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\`;
-  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 || "{}");
-    if (!secretEq(req.auth, process.env.STATE_REFRESH_SECRET)) 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 (!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.
-    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 (!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}\`);
-      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
@@ -467,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.channels.some((channel) => channel.ingress === "webhook") || 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 "")
@@ -607,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.channels.some((channel) => channel.ingress === "webhook") ? [`          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}`);
@@ -634,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`;
@@ -678,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.channels.some((channel) => channel.ingress === "webhook") || 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),
     ];
@@ -735,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
         ? [
@@ -781,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 { 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;
@@ -37,10 +22,9 @@ export interface AgentcoreRunPlan {
     missingSecrets: string[];
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];
-    /** 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;
+    /** 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;

package/dist/deploy/agentcore/run.js

@@ -1,3 +1,20 @@
+/**
+ * `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 { RESERVED_PATHS } from "../../channels/agentcore-protocol.js";
 import { registerWebhooks } from "../channel-ingress.js";
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
@@ -8,7 +25,7 @@ import { zipSingleFile } from "./zip.js";
 const PROBE_TIMEOUT_MS = 120_000;
 const PROBE_INTERVAL_MS = 3_000;
 /**
- * Drive the forwarder's reserved `/__fastagent/probe` path until it answers, and read the runtime's
+ * Drive the forwarder's reserved probe path until it answers, and read the runtime's
  * STRUCTURED verdict. The path answers on every forwarder topology (a schedule-only URL refuses
  * ordinary public traffic, so a plain `GET /health` would 404 there), and the verdict rides a
  * transport-200 JSON body `{ ok, error? }` — the ordinary webhook relay folds a non-200 transport
@@ -208,7 +225,7 @@ probe = {}) {
     //     out of CloudFormation means a `delete-stack` — or a rolled-back create — cannot take the
     //     agent's sessions, channel state and pending wake-ups with it.
     let forwarderParams;
-    if (plan.needsForwarder) {
+    if (plan.topology.forwarder) {
         const bucket = stateBucketName(plan.name, account);
         if ((await aws(["s3api", "head-bucket", "--bucket", bucket], { capture: true })).code !== 0) {
             log(`creating deployment bucket ${bucket}…`);
@@ -360,7 +377,7 @@ probe = {}) {
     // Keyed on the FORWARDER: every current forwarder has a callback URL for state-capability refresh,
     // and every forwarder topology has an ingress session whose next event would otherwise land on compute still
     // running the previous image.
-    if (plan.needsForwarder) {
+    if (plan.topology.forwarder) {
         // CHECKPOINT FIRST. The stop cuts whatever turn is running, and that turn's durable intent was
         // written to a mount the version update erases — so without this flush "replay re-runs it" would
         // be false: the intent never reaches S3 and the message is simply gone. Best-effort: a session
@@ -437,9 +454,7 @@ probe = {}) {
     //     check (there is no boot-time failStartup on this host). A missing output means an edited
     //     template; skipping the probe silently would let such a deploy report success unverified.
     //     Only a pure-invoke deployment (no forwarder) legitimately has no URL and nothing to probe.
-    //     `channels.length` is belt-and-braces: the planner derives needsForwarder FROM the channel
-    //     list, but this gate must not silently trust that invariant across callers.
-    if ((plan.needsForwarder || plan.channels.length > 0) && !url) {
+    if (plan.topology.forwarder && !url) {
         return gate("this deployment needs the forwarder but the stack has no ForwarderUrl output — regenerate the " +
             "template with --force");
     }
@@ -450,7 +465,7 @@ probe = {}) {
     //     unrestorable snapshot surfaces AT DEPLOY TIME with the runtime's own error text.
     if (url) {
         log("probing the deployed runtime (state restore + channel construction)…");
-        const verdict = await probeRuntime(`${url}/__fastagent/probe`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
+        const verdict = await probeRuntime(`${url}${RESERVED_PATHS.probe}`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
         if (!verdict.ok)
             return gate(verdict.gate);
         log("runtime verified (state restored, channels constructed)");

package/dist/deploy/channel-ingress.js

@@ -39,7 +39,7 @@ const INGRESS = {
         manual: (baseUrl) => `slack: set Event Subscriptions → Request URL → ${baseUrl}/slack`,
         runbook: (baseUrl) => [
             `# Set Slack Event Subscriptions → Request URL (default route POST /slack; the running service`,
-            `# answers Slack's challenge), and match scopes/subscriptions to channels/slack.ts groupBehavior:`,
+            `# answers Slack's challenge), and match scopes/subscriptions to the app \`add slack --group-behavior\` created:`,
             `#   Request URL = ${baseUrl}/slack`,
         ],
     },

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

@@ -38,15 +38,29 @@ type DockerAnnounce = (baseUrl: string) => Promise<{
     outcome: RegistrationOutcome;
 }[]>;
 export type DockerHealthProbe = (healthUrl: string) => Promise<boolean>;
-export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv) => Promise<string | undefined>;
+/** A published Quick Tunnel URL, and whether its tunnel ever reported an edge connection. Both, because
+ *  a URL that never connected still gets served (retrying meets the same network) and the operator has
+ *  to be told which of the two they are looking at. */
+export interface ComposeTunnel {
+    url: string;
+    connected: boolean;
+}
+export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv) => Promise<ComposeTunnel | undefined>;
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export declare function localUrlFromComposePort(stdout: string): string | undefined;
-/** Poll the detached cloudflared service's logs until its assigned Quick Tunnel URL appears. */
+/**
+ * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel
+ * reports an edge connection. Waiting for the second is the same requirement `startCloudflareTunnel`
+ * has and for the same reason — the hostname does not exist until then (#435), and this driver hands
+ * the URL straight to `announce`. Returns a URL that never connected rather than nothing: the
+ * registrars downstream report their own outcome, and a gate saying "no URL" would misname it — but it
+ * says WHICH it is returning, because the caller owes the operator that sentence.
+ */
 export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv, options?: {
     attempts?: number;
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;
-}): Promise<string | undefined>;
+}): Promise<ComposeTunnel | undefined>;
 /**
  * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
  * only assumes the generated service contract (`agent`, config's container port) for optional URL/

package/dist/deploy/docker/run.js

@@ -4,7 +4,7 @@
  * carry through the child environment (never argv), and a readiness check on the published loopback port.
  */
 import { waitForHealth } from "../../channels/wait-health.js";
-import { parseTunnelUrl } from "../../tunnel.js";
+import { TUNNEL_DNS_LAG_MS, hasTunnelConnection, parseTunnelUrl } from "../../tunnel.js";
 import { registrationGate } from "../registration-gate.js";
 import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
@@ -18,19 +18,31 @@ export function localUrlFromComposePort(stdout) {
 }
 const defaultHealthProbe = (healthUrl) => waitForHealth(healthUrl, 30_000, 500);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/** Poll the detached cloudflared service's logs until its assigned Quick Tunnel URL appears. */
+/**
+ * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel
+ * reports an edge connection. Waiting for the second is the same requirement `startCloudflareTunnel`
+ * has and for the same reason — the hostname does not exist until then (#435), and this driver hands
+ * the URL straight to `announce`. Returns a URL that never connected rather than nothing: the
+ * registrars downstream report their own outcome, and a gate saying "no URL" would misname it — but it
+ * says WHICH it is returning, because the caller owes the operator that sentence.
+ */
 export async function waitForComposeTunnelUrl(docker, composeFile, env, options = {}) {
     const compose = ["compose", "-f", composeFile];
     const attempts = options.attempts ?? 60;
+    let assigned;
     for (let attempt = 0; attempt < attempts; attempt++) {
         const logs = await docker([...compose, "logs", "--no-color", "tunnel"], { capture: true, env });
-        const url = logs.code === 0 ? parseTunnelUrl(logs.stdout) : undefined;
-        if (url)
-            return url;
+        if (logs.code === 0) {
+            assigned ??= parseTunnelUrl(logs.stdout);
+            if (assigned && hasTunnelConnection(logs.stdout)) {
+                await (options.sleep ?? sleep)(TUNNEL_DNS_LAG_MS);
+                return { url: assigned, connected: true };
+            }
+        }
         if (attempt + 1 < attempts)
             await (options.sleep ?? sleep)(options.intervalMs ?? 500);
     }
-    return undefined;
+    return assigned ? { url: assigned, connected: false } : undefined;
 }
 const defaultTunnelUrlProbe = (docker, composeFile, env) => waitForComposeTunnelUrl(docker, composeFile, env);
 /**
@@ -119,10 +131,20 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (!hasTunnel)
         return { ok: true, url };
     log("waiting for the Compose tunnel service to publish its Quick Tunnel URL…");
-    const tunnelUrl = await tunnelUrlProbe(docker, plan.composeFile, env);
-    if (!tunnelUrl) {
+    const tunnel = await tunnelUrlProbe(docker, plan.composeFile, env);
+    if (!tunnel) {
         return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
     }
+    // The same sentence `startCloudflareTunnel` prints for the same state, and needed MORE here: this
+    // cloudflared runs in a container, so the author cannot see the logs that would explain the
+    // registration failures about to follow. Silence sends them to debug the platform for what is a
+    // local tunnel that never came up.
+    if (!tunnel.connected) {
+        log(`warn: the tunnel service never reported an edge connection for ${tunnel.url} — announcing it anyway. ` +
+            `Nothing reaches a tunnel that has not connected, so a webhook registration that cannot resolve the ` +
+            `host is this, not the platform. Inspect \`docker compose -f ${plan.composeFile} logs tunnel\`.`);
+    }
+    const tunnelUrl = tunnel.url;
     // Registration lives HERE, like every other host's driver, and not at the CLI: this is the layer
     // that owns the outcome, so it is the layer that can gate on one. While it sat above, docker was
     // the one target whose `--run` could exit 0 with a webhook that never registered.

package/dist/deploy/fly/plan.js

@@ -87,6 +87,13 @@ export function planFlyDeploy(input) {
         `# <region> MUST equal primary_region in fly.toml (a volume in another region can't mount) — fly.toml`,
         `# is the single source for the region; skip this if the volume exists (fly volumes list --app ${appName}):`,
         `fly volumes create data --app ${appName} --region <region> --size 1`,
+        ``,
+        `# An address to be reached ON: [http_service] declares a service, it does not allocate an IP.`,
+        `# \`fly deploy\` allocates one on a FIRST deploy only, and merely WARNS when that fails — which`,
+        `# leaves the machine serving and https://${appName}.fly.dev with no DNS record at all. Both are`,
+        `# free; skip if \`fly ips list --app ${appName}\` already shows a v4/v6/shared_v4 address:`,
+        `fly ips allocate-v4 --shared --app ${appName}`,
+        `fly ips allocate-v6 --app ${appName}`,
     ];
     if (requiredSecrets.length > 0) {
         runbook.push(``, `# Required secrets (replace each <value>):`, ...requiredSecrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${requiredSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);

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

@@ -43,6 +43,33 @@ export type FlyRunOutcome = {
     ok: false;
     gate: string;
 };
+/**
+ * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an
+ * ingress address" is not the question the two allocate commands answer. An app holding only a `v6`
+ * passes the coarse test and still resolves `<app>.fly.dev` to an AAAA record alone, so an IPv4-only
+ * webhook sender (Telegram, GitHub) reproduces #425 against it.
+ *
+ * The list is EVERY assignment the app holds, and a Flycast or egress address carries a non-empty
+ * `Address` too — reading one as routable pre-empts flyctl's own first-deploy fallback, which returns
+ * early once any assignment exists.
+ *
+ * Output that is not a JSON array THROWS rather than reading as "no address": the caller turns that
+ * into a gate, because a list we cannot read is not a state we can act on.
+ */
+export declare function ingressAddresses(stdout: string): {
+    v4: boolean;
+    v6: boolean;
+};
+/**
+ * Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept
+ * both). Exported for the same reason railway's parsers are: what it encodes is an assumption about
+ * another tool's output, and the live probe checks that assumption against the real `flyctl`.
+ *
+ * THROWS on output that is not a JSON array, for the same reason {@link ingressAddresses} does —
+ * `false` here means "the host does not have it", and answering that for a list nobody could read
+ * creates a SECOND volume, or in teardown destroys nothing at all.
+ */
+export declare function listHasName(stdout: string, name: string): boolean;
 /**
  * Run the deploy through `fly`. `log` reports progress; the injected {@link Registrars} perform the
  * post-deploy webhook steps from the builder machine (Slack's control credential never travels to the