@fastagent-sh/fastagent 0.18.0 → 0.20.0

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);

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

@@ -14,8 +14,8 @@
  * 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";
 export interface AgentcoreRunPlan {
     /** The base name — stack `fastagent-<name>`, ECR repo `fastagent/<name>`. */
@@ -35,7 +35,8 @@ export interface AgentcoreRunPlan {
     secrets: Record<string, string>;
     /** Required secret names with NO local value — gated before any side effect. */
     missingSecrets: string[];
-    channels: ChannelKind[];
+    /** 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. */
@@ -70,7 +71,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;

package/dist/deploy/agentcore/run.js

@@ -1,4 +1,4 @@
-import { registrationGate } from "../registration-gate.js";
+import { registerWebhooks } from "../channel-ingress.js";
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import { AUTH_SEED_CHUNK_SIZE, AUTH_SEED_MAX_CHUNKS, cfnParamName, forwarderSource, ingressSessionId, stateBucketName, } from "./plan.js";
@@ -123,7 +123,7 @@ export function parseCheckpointReply(stdout) {
  * 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 async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack, 
+export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registrars, 
 /** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
 probe = {}) {
     const gate = (g) => ({ ok: false, gate: g });
@@ -457,40 +457,17 @@ probe = {}) {
     }
     // 9. Post-deploy webhook registration — same registrar seam as every host, pointed at the
     //    forwarder's Function URL. Gate policy is the shared registration-gate kernel.
-    const reg = registrationGate(log, "re-run to retry registration (steps already done are skipped)");
-    if (url) {
-        if (plan.channels.includes("telegram")) {
-            log("registering telegram webhook…");
-            reg.track("telegram", await registerTelegram(url));
-        }
-        if (plan.channels.includes("github")) {
-            log(`github: set the webhook in the repo (Settings → Webhooks) → ${url}/webhook`);
-            reg.track("github", "manual"); // always a human step — re-surfaced after the registrar output
-        }
-        if (plan.channels.includes("slack")) {
-            if (registerSlack) {
-                log("registering slack event URL…");
-                reg.track("slack", await registerSlack(url));
-            }
-            else {
-                log(`slack: set Event Subscriptions → Request URL → ${url}/slack`);
-                reg.track("slack", "manual");
-            }
-        }
-        for (const kind of ["feishu", "lark"]) {
-            if (!plan.channels.includes(kind))
-                continue;
-            if (registerFeishu) {
-                log(`registering ${kind} event URL…`);
-                reg.track(kind, await registerFeishu(url, kind));
-            }
-            else {
-                log(`${kind}: set the event Request URL (developer console → Events & Callbacks) → ${url}/${kind}`);
-                reg.track(kind, "manual");
-            }
-        }
-    }
-    const registrationGateMsg = reg.gate();
+    // No long-connection channels reach here: `deploy.ts` gates them before the driver runs (AgentCore
+    // has no resident process to hold a connection), so the deploy's channels are all webhook ones.
+    const registrationGateMsg = url
+        ? await registerWebhooks({
+            baseUrl: url,
+            channels: plan.channels,
+            registrars,
+            log,
+            retryHint: "re-run to retry registration (steps already done are skipped)",
+        })
+        : undefined;
     if (registrationGateMsg)
         return gate(registrationGateMsg);
     return { ok: true, runtimeArn, url };

package/dist/deploy/channel-ingress.d.ts

@@ -0,0 +1,73 @@
+/**
+ * HOW A RUNNING CHANNEL IS REACHED — the URL-neutral half of "point this channel at the agent": its
+ * default route, whether anything can set that URL end-to-end, and the words an operator needs when
+ * nothing can. Only the base URL varies, which is the argument every function here takes — a deploy
+ * host's (`<app>.fly.dev`, a minted Railway domain, a Function URL) or `dev --tunnel`'s Quick Tunnel.
+ * It lives under `deploy/` because that is where its answers are mostly consumed and where the gate
+ * policy it composes with lives; the serving path reads the same answers through `tunnel.ts`.
+ *
+ * It exists because that knowledge belongs to the CHANNEL and was written per HOST: three runbook
+ * plans, three `--run` drivers, a path table in the docker plan and the `--tunnel` announcer each
+ * hand-wrote the same five-branch if-chain. A rule spelled seven times drifts, and it did — the
+ * long-connection exception reached only the feishu/lark branches, so a long-connection Telegram
+ * deploy printed `setWebhook` in its runbook, which makes `getUpdates` return 409 and stops the
+ * channel the operator just deployed.
+ *
+ * Every function here takes the {@link DeclaredChannel} list and filters it ITSELF. Taking a
+ * pre-filtered list would put the rule back at the call sites, which is where it drifted from: the
+ * `--tunnel` announcer trusted its caller that way and had a default that passed every channel,
+ * long-connection ones included.
+ *
+ * A host adds its base URL and its own asides; it does not restate which channels have a webhook.
+ */
+import type { DeclaredChannel } from "../channels/discover.ts";
+import type { RegistrationOutcome } from "../channels/registration.ts";
+import type { ChannelKind } from "../scaffold/add-channel.ts";
+/** The registrars a host can drive. `telegram` is always available (fastagent holds the token and the
+ *  URL); the others are optional so a caller without their credentials falls back to a manual step. */
+export interface Registrars {
+    telegram: (baseUrl: string) => Promise<RegistrationOutcome>;
+    slack?: (baseUrl: string) => Promise<RegistrationOutcome>;
+    feishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>;
+}
+/**
+ * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool
+ * knows how to instruct. ONE answer for every host and every path — the runbooks, the `--run`
+ * drivers, the docker ingress note, `--tunnel`. A custom channel is skipped here and reported by the
+ * pre-flight instead: its URL is its author's to set.
+ */
+export declare function webhookKinds(channels: readonly DeclaredChannel[]): ChannelKind[];
+/** Default route keys for {@link webhookKinds}, in the same order (the docker plan's ingress note). */
+export declare function webhookPaths(channels: readonly DeclaredChannel[]): string[];
+/** The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way
+ *  (a literal `https://app.fly.dev`, or a placeholder like `<your-domain>` the operator fills in). */
+export declare function webhookRunbook(baseUrl: string, channels: readonly DeclaredChannel[]): string[];
+/**
+ * Point every channel that has a webhook at `baseUrl`, reporting what each one ended as. All channels
+ * are attempted — one failure does not skip the rest — and a channel whose registrar the caller did
+ * not wire reports `manual` with the operator's instruction. The two callers differ in what they do
+ * with the outcomes, not in how they are produced: a deploy gates on them, a long-running serve
+ * cannot ({@link registerWebhooks} is the gating half).
+ */
+export declare function pointChannelsAt(input: {
+    baseUrl: string;
+    channels: readonly DeclaredChannel[];
+    registrars: Registrars;
+    log: (msg: string) => void;
+}): Promise<{
+    kind: ChannelKind;
+    outcome: RegistrationOutcome;
+}[]>;
+/**
+ * {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS: an exit 0 claims the
+ * deployment is reachable, so a failed registration has to become a non-zero one. Returns the gate
+ * message, or undefined when nothing gates.
+ */
+export declare function registerWebhooks(input: {
+    baseUrl: string;
+    channels: readonly DeclaredChannel[];
+    registrars: Registrars;
+    log: (msg: string) => void;
+    /** How THIS host retries — the only per-host words in the gate. */
+    retryHint: string;
+}): Promise<string | undefined>;

package/dist/deploy/channel-ingress.js

@@ -0,0 +1,101 @@
+import { registrationGate } from "./registration-gate.js";
+const feishuCloud = (kind, label) => ({
+    path: `/${kind}`,
+    register: (r, baseUrl) => r.feishu?.(baseUrl, kind),
+    manual: (baseUrl) => `${kind}: set the event Request URL in the developer console (Events & Callbacks) → ${baseUrl}/${kind} (the app must be running when you save)`,
+    runbook: (baseUrl) => [
+        `# Set the ${label} event Request URL (developer console → Events & Callbacks). Default route`,
+        `# POST /${kind}; the app must be RUNNING when you save (the console verifies with a challenge):`,
+        `#   Request URL = ${baseUrl}/${kind}`,
+    ],
+});
+/** Declaration order — the order every runbook and every driver reports in. */
+const INGRESS = {
+    telegram: {
+        path: "/telegram",
+        register: (r, baseUrl) => r.telegram(baseUrl),
+        manual: (baseUrl) => `telegram: set the webhook → ${baseUrl}/telegram (secret_token = TELEGRAM_SECRET_TOKEN)`,
+        runbook: (baseUrl) => [
+            `# Register the Telegram webhook. The path assumes the default route (POST /telegram); if you`,
+            `# remapped it in channels/telegram.ts, use your path. secret_token MUST equal TELEGRAM_SECRET_TOKEN:`,
+            `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`,
+            `  -d url=${baseUrl}/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`,
+        ],
+    },
+    github: {
+        path: "/webhook",
+        // The env-var name is the part a first-time operator cannot guess, and this line is all `--tunnel`
+        // prints — there is no runbook beside it to carry the detail.
+        manual: (baseUrl) => `github: set the webhook in the repo (Settings → Webhooks) → ${baseUrl}/webhook (content type application/json, secret = GITHUB_WEBHOOK_SECRET)`,
+        runbook: (baseUrl) => [
+            `# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped`,
+            `# it in channels/github.ts, use your path:`,
+            `#   Payload URL = ${baseUrl}/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`,
+        ],
+    },
+    slack: {
+        path: "/slack",
+        register: (r, baseUrl) => r.slack?.(baseUrl),
+        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:`,
+            `#   Request URL = ${baseUrl}/slack`,
+        ],
+    },
+    feishu: feishuCloud("feishu", "Feishu"),
+    lark: feishuCloud("lark", "Lark"),
+};
+/**
+ * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool
+ * knows how to instruct. ONE answer for every host and every path — the runbooks, the `--run`
+ * drivers, the docker ingress note, `--tunnel`. A custom channel is skipped here and reported by the
+ * pre-flight instead: its URL is its author's to set.
+ */
+export function webhookKinds(channels) {
+    const declared = new Set(channels.filter((c) => c.ingress === "webhook").map((c) => c.name));
+    return Object.keys(INGRESS).filter((kind) => declared.has(kind));
+}
+/** Default route keys for {@link webhookKinds}, in the same order (the docker plan's ingress note). */
+export function webhookPaths(channels) {
+    return webhookKinds(channels).map((kind) => INGRESS[kind].path);
+}
+/** The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way
+ *  (a literal `https://app.fly.dev`, or a placeholder like `<your-domain>` the operator fills in). */
+export function webhookRunbook(baseUrl, channels) {
+    return webhookKinds(channels).flatMap((kind) => INGRESS[kind].runbook(baseUrl));
+}
+/**
+ * Point every channel that has a webhook at `baseUrl`, reporting what each one ended as. All channels
+ * are attempted — one failure does not skip the rest — and a channel whose registrar the caller did
+ * not wire reports `manual` with the operator's instruction. The two callers differ in what they do
+ * with the outcomes, not in how they are produced: a deploy gates on them, a long-running serve
+ * cannot ({@link registerWebhooks} is the gating half).
+ */
+export async function pointChannelsAt(input) {
+    const outcomes = [];
+    for (const kind of webhookKinds(input.channels)) {
+        const ingress = INGRESS[kind];
+        // Calling IS the question: a channel whose registrar the caller did not wire returns undefined.
+        const running = ingress.register?.(input.registrars, input.baseUrl);
+        if (!running) {
+            input.log(ingress.manual(input.baseUrl));
+            outcomes.push({ kind, outcome: "manual" }); // a human's step — re-surfaced after registrar output
+            continue;
+        }
+        input.log(`registering ${kind} webhook…`);
+        outcomes.push({ kind, outcome: await running });
+    }
+    return outcomes;
+}
+/**
+ * {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS: an exit 0 claims the
+ * deployment is reachable, so a failed registration has to become a non-zero one. Returns the gate
+ * message, or undefined when nothing gates.
+ */
+export async function registerWebhooks(input) {
+    const reg = registrationGate(input.log, input.retryHint);
+    for (const { kind, outcome } of await pointChannelsAt(input))
+        reg.track(kind, outcome);
+    return reg.gate();
+}

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

@@ -4,7 +4,7 @@
  * process, its loopback port, exact environment-variable names, and one persistent state volume.
  * `--tunnel` can add an ephemeral Cloudflare Quick Tunnel service; durable ingress remains operator-owned.
  */
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
 export interface DockerPlanInput extends ContainerInput {
     /** Stable Compose project name, sanitized by {@link toDockerProjectName}. */
@@ -13,10 +13,8 @@ export interface DockerPlanInput extends ContainerInput {
     port: number;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Known channels contribute their environment-variable names and webhook registration. */
-    channels: ChannelKind[];
-    /** All long-connection channel basenames, including custom channels. */
-    longConnectionChannels?: string[];
+    /** Every declared channel and its ingress — the source of the secret list and the ingress note. */
+    channels: readonly DeclaredChannel[];
     /** Generate an optional Cloudflare Quick Tunnel service in Compose. Generation only; `--run` starts it. */
     tunnel: boolean;
     /** Extra environment-variable names declared in config.deploy.secrets. */
@@ -39,7 +37,5 @@ export declare function isGeneratedCompose(content: string): boolean;
 export declare function composeHasTunnelService(content: string): boolean;
 /** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
 export declare function toDockerProjectName(directoryName: string): string;
-/** Default first-party webhook paths. Workspace glue may remap them, so guidance labels them defaults. */
-export declare function dockerWebhookPaths(channels: ChannelKind[]): string[];
 /** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
 export declare function planDockerDeploy(input: DockerPlanInput): DockerPlan;

package/dist/deploy/docker/plan.js

@@ -1,3 +1,4 @@
+import { webhookPaths } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 const MOUNT = "/data";
@@ -24,23 +25,12 @@ export function toDockerProjectName(directoryName) {
         .replace(/[-_]+$/g, "");
     return `fastagent-${slug || "agent"}`;
 }
-/** Default first-party webhook paths. Workspace glue may remap them, so guidance labels them defaults. */
-export function dockerWebhookPaths(channels) {
-    const path = {
-        github: "/webhook",
-        telegram: "/telegram",
-        slack: "/slack",
-        feishu: "/feishu",
-        lark: "/lark",
-    };
-    return channels.map((kind) => path[kind]);
-}
 /** `${NAME:-}` without making JavaScript treat it as interpolation. */
 function composeInterpolation(name) {
     return `\${${name}:-}`;
 }
 function composeYaml(input) {
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets, input.longConnectionChannels);
+    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
     // Always leave the auth-seed seam in the committed topology. `--run` uses it for OAuth/stored auth;
     // it is empty otherwise. Values never land in this file — Compose interpolates them at invocation.
     const envNames = [...new Set([...secrets.map((secret) => secret.name), "FASTAGENT_AUTH_SEED"])];
@@ -100,11 +90,10 @@ export function planDockerDeploy(input) {
     const composePath = `${input.agentPrefix}${DOCKER_COMPOSE_FILE}`;
     const artifacts = [{ path: composePath, content: composeYaml(input) }, ...containerArtifacts(input)];
     const compose = `docker compose -f ${composePath}`;
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets, input.longConnectionChannels);
+    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
     const required = secrets.filter((secret) => secret.required);
     const optional = secrets.filter((secret) => !secret.required);
-    const routeChannels = input.channels.filter((kind) => !input.longConnectionChannels?.includes(kind));
-    const paths = dockerWebhookPaths(routeChannels);
+    const paths = webhookPaths(input.channels);
     const runbook = [
         `# Run FastAgent in local Docker. ${composePath} / Dockerfile(.dockerignore) are generated above.`,
         `# Existing artifacts are authoritative and kept; edit Dockerfile or ${composePath} freely.`,

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

@@ -1,3 +1,4 @@
+import type { RegistrationOutcome } from "../../channels/registration.ts";
 import type { CliRunner } from "../runner.ts";
 export interface DockerRunPlan {
     /** Compose file relative to the runner cwd (the workspace root). */
@@ -10,6 +11,10 @@ export interface DockerRunPlan {
     missingSecrets: string[];
     /** Neither an env-key credential nor a readable auth.json is available. */
     needsModelCredential: boolean;
+    /** Register the deployment's webhooks against the tunnel URL, reporting what each registrar
+     *  answered. REQUIRED, not optional: an absent one would delete this whole step in silence, which
+     *  is the failure this driver's gate exists to end. A topology with no tunnel never calls it. */
+    announce: DockerAnnounce;
     /** `--tunnel` was requested for this run; a kept Compose file must actually contain that service. */
     requireTunnel: boolean;
 }
@@ -17,10 +22,21 @@ export type DockerRunOutcome = {
     ok: true;
     url?: string;
     tunnelUrl?: string;
-} | {
+}
+/** `url`/`tunnelUrl` travel with a gate too: Compose is up, so the operator still needs to know
+ *  where it is and what to re-run. */
+ | {
     ok: false;
     gate: string;
+    url?: string;
+    tunnelUrl?: string;
 };
+/** Register the deployment's webhooks against its public URL, reporting what each registrar
+ *  answered. Injected so the driver stays free of channel specifics — and so a test can fail one. */
+type DockerAnnounce = (baseUrl: string) => Promise<{
+    kind: string;
+    outcome: RegistrationOutcome;
+}[]>;
 export type DockerHealthProbe = (healthUrl: string) => Promise<boolean>;
 export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv) => Promise<string | undefined>;
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
@@ -38,3 +54,4 @@ export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile:
  * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
  */
 export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe): Promise<DockerRunOutcome>;
+export {};

package/dist/deploy/docker/run.js

@@ -5,6 +5,7 @@
  */
 import { waitForHealth } from "../../channels/wait-health.js";
 import { 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). */
 export function localUrlFromComposePort(stdout) {
@@ -122,5 +123,14 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (!tunnelUrl) {
         return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
     }
+    // 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.
+    const reg = registrationGate(log, `re-run this deploy to retry registration (Compose is already up)`);
+    for (const { kind, outcome } of await plan.announce(tunnelUrl))
+        reg.track(kind, outcome);
+    const blocked = reg.gate();
+    if (blocked)
+        return { ok: false, gate: blocked, url, tunnelUrl };
     return { ok: true, url, tunnelUrl };
 }

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

@@ -16,7 +16,7 @@
  * snapshot is discarded replays on the next start (the Telegram L1 turn store) — at-least-once, the
  * documented floor. State on the /data volume survives stop/suspend on the same machine.
  */
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
 export interface FlyPlanInput extends ContainerInput {
     /** Fly app name — globally unique, lowercase; the CLI sanitizes it from the dir basename. */
@@ -28,10 +28,9 @@ export interface FlyPlanInput extends ContainerInput {
      * `"OAuth"`/`"stored credential"` (a local login the server can't use), or undefined (unconfigured).
      */
     modelAuth: string | undefined;
-    /** Known first-party channels — each contributes its secret metadata + webhook step. */
-    channels: ChannelKind[];
-    /** All long-connection channel basenames, including custom channels — require one running machine. */
-    longConnectionChannels?: string[];
+    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
+     *  whether a machine must stay up for an outbound connection. */
+    channels: readonly DeclaredChannel[];
     /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
     extraSecrets?: string[];
     /** `auto_stop_machines` — `"suspend"` (default, fast resume) or `"stop"` (cold start). CLI `--stop`. */