@fastagent-sh/fastagent 0.19.0 → 0.20.0

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`. */

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}`;
@@ -110,26 +111,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

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

@@ -17,23 +17,9 @@
  * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
  * never land in argv/process listings.
  */
-import type { RegistrationOutcome } from "../../channels/registration.ts";
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Registrars } from "../channel-ingress.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import type { CliRunner } from "../runner.ts";
-/**
- * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
- * FASTAGENT_AUTH_SEED materialization. ABSENT-ONLY by design: a present file (a refreshed volume copy)
- * is never overwritten by the stale seed, so a box that ran its own OAuth refresh is not rolled back.
- */
-export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
-/**
- * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
- * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
- * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
- * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
- * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
- */
-export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;
 export interface FlyRunPlan {
     appName: string;
     region: string;
@@ -42,8 +28,8 @@ export interface FlyRunPlan {
     secrets: Record<string, string>;
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
-    channels: ChannelKind[];
-    longConnectionChannels?: string[];
+    /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
+    channels: readonly DeclaredChannel[];
     /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace root). */
     flyConfig: string;
     /** Dockerfile path passed explicitly (`fastagent/Dockerfile`, with the workspace as context —
@@ -58,9 +44,9 @@ export type FlyRunOutcome = {
     gate: string;
 };
 /**
- * Run the deploy through `fly`. `log` reports progress; the injected Telegram/Feishu/Slack registrars
- * perform post-deploy webhook steps from the builder machine (Slack's control credential never travels
- * to the host). Absent, the manual console
- * instruction is printed. Every gate is fail-visible.
+ * 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
+ * host). A registrar the caller did not wire becomes the printed manual step. Every gate is
+ * fail-visible.
  */
-export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<FlyRunOutcome>;
+export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registrars: Registrars): Promise<FlyRunOutcome>;