@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/deploy/agentcore/run.js

@@ -1,4 +1,21 @@
-import { registrationGate } from "../registration-gate.js";
+/**
+ * `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";
 import { AUTH_SEED_CHUNK_SIZE, AUTH_SEED_MAX_CHUNKS, cfnParamName, forwarderSource, ingressSessionId, stateBucketName, } from "./plan.js";
@@ -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
@@ -123,7 +140,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 });
@@ -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,47 +465,24 @@ 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)");
     }
     // 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 the app \`add slack --group-behavior\` created:`,
+            `#   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,20 +22,45 @@ 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>;
+/** 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/
@@ -38,3 +68,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

@@ -4,7 +4,8 @@
  * 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). */
 export function localUrlFromComposePort(stdout) {
@@ -17,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);
 /**
@@ -118,9 +131,28 @@ 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.
+    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`. */

package/dist/deploy/fly/plan.js

@@ -1,3 +1,4 @@
+import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTriggers, hasLongConnectionChannel) {
@@ -62,7 +63,7 @@ export function planFlyDeploy(input) {
     const artifacts = [
         {
             path: flyTomlPath,
-            content: flyToml(appName, port, channels.includes("github"), input.autostop, input.scaleToZero, input.hasTimeTriggers, (input.longConnectionChannels?.length ?? 0) > 0),
+            content: flyToml(appName, port, channels.some((channel) => channel.name === "github"), input.autostop, input.scaleToZero, input.hasTimeTriggers, channels.some((channel) => channel.ingress === "long-connection")),
         },
         ...containerArtifacts(input),
     ];
@@ -70,7 +71,7 @@ export function planFlyDeploy(input) {
     // model key (when local auth is an env key) + every discovered channel's secrets. Names + hints as
     // COMMENT lines (a `#` inside a `\`-continued command would break the shell), then one flat, executable
     // `fly secrets set` the coding agent fills — `<value>` placeholders, never inline comments.
-    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
+    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
     const requiredSecrets = secrets.filter((secret) => secret.required);
     const optionalSecrets = secrets.filter((secret) => !secret.required);
     const deployCmd = `fly deploy . --config ${flyTomlPath} --dockerfile ${input.agentPrefix}Dockerfile --app ${appName}`;
@@ -86,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(" ")}`);
@@ -110,26 +118,10 @@ export function planFlyDeploy(input) {
             ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; pass --auth-path <file> (e.g. ~/.fastagent/.secrets/auth.json), or \`--run\` carries it automatically.`
             : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a secret.`, `#   Set your provider API key as a Fly secret (fly secrets set KEY=...), OR place auth.json at /data/.secrets/ on the volume.`);
     }
-    // The fastagent-only post-step: point each channel's webhook at the live URL. Only fastagent knows the routes.
-    // The URLs below assume each channel's DEFAULT route key (POST /telegram, POST /webhook). Reading the
-    // real key would mean executing the channel factory (getMe, state-dir creation) — wrong at plan time
-    // — so the runbook states the assumption instead of silently printing a stale path for remapped glue.
-    const post = [];
-    if (channels.includes("telegram")) {
-        post.push(`# After deploy — 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=https://${appName}.fly.dev/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
-    }
-    if (channels.includes("github")) {
-        post.push(`# After deploy — set the GitHub webhook (repo Settings → Webhooks). Path assumes the default route`, `# (POST /webhook); if you remapped it in channels/github.ts, use your path:`, `#   Payload URL = https://${appName}.fly.dev/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
-    }
-    if (channels.includes("slack")) {
-        post.push(`# After deploy — set Slack Event Subscriptions → Request URL. Path assumes POST /slack;`, `# Slack verifies the running endpoint with a challenge:`, `#   Request URL = https://${appName}.fly.dev/slack`, `# Ensure OAuth scopes + message.* subscriptions match the groupBehavior in channels/slack.ts.`);
-    }
-    for (const kind of ["feishu", "lark"]) {
-        if (!channels.includes(kind) || input.longConnectionChannels?.includes(kind))
-            continue;
-        const label = kind === "feishu" ? "Feishu" : "Lark";
-        post.push(`# After deploy — set the ${label} event Request URL (developer console → Events & Callbacks).`, `# Path assumes the default route (POST /${kind}); the app must be RUNNING when you save (the console`, `# verifies the URL with a challenge):`, `#   Request URL = https://${appName}.fly.dev/${kind}`);
-    }
+    // The fastagent-only post-step: point each channel at the live URL. WHICH channels and in what words
+    // is the shared channel-ingress kernel's answer; Fly's contribution is that its URL is deterministic.
+    const steps = webhookRunbook(`https://${appName}.fly.dev`, channels);
+    const post = steps.length > 0 ? [`# After deploy:`, ...steps] : [];
     if (post.length > 0)
         runbook.push(``, ...post);
     // Single-machine tier: state lives on ONE volume tied to ONE machine. Scaling to multiple machines