@fastagent-sh/fastagent 0.18.0 → 0.20.0

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

package/dist/deploy/fly/run.js

@@ -1,32 +1,23 @@
-import { registrationGate } from "../registration-gate.js";
 /**
- * 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.
+ * `fastagent deploy fly --run` — drive flyctl to completion. The middle of the deploy (app / volume /
+ * secrets / deploy) that the plain runbook hands to the operator; `--run` executes it instead, so a
+ * coding agent runs ONE command. Idempotent (app/volume check-then-act; channel secrets come from the
+ * local env — NOT minted — so a re-run sets the same values) and resumable: it STOPS at a human gate
+ * (not logged in, a missing secret value, a taken app name, a failed webhook registration) with one actionable line and a non-zero
+ * exit, so the agent clears the gate and re-runs. A `generate` channel secret absent from `.env` is a
+ * gate too (`missingSecrets`), not a silent mint — fill it in `.env` (use the random string that
+ * `add <channel>` prints).
+ *
+ * flyctl is behind the shared {@link CliRunner} seam — production spawns `fly`, tests inject a fake that
+ * records the command sequence and scripts outputs. That seam is the benchmark: the agent's journey
+ * encoded as an asserted command sequence + gate behavior, validated without a real Fly account.
+ *
+ * Non-interactive incantations the agent would otherwise get wrong: `--remote-only` (build on Fly's
+ * builders — no local Docker in a sandbox), `--yes` (no prompts), `--ha=false` + the mounted volume
+ * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
+ * never land in argv/process listings.
  */
-export function authSeedBytes(seed, fileExists) {
-    return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
-}
-/**
- * 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 function collectAuthSeed(env) {
-    const first = env.FASTAGENT_AUTH_SEED;
-    if (!first)
-        return undefined;
-    let seed = first;
-    for (let i = 2;; i++) {
-        const part = env[`FASTAGENT_AUTH_SEED_${i}`];
-        if (!part)
-            break;
-        seed += part;
-    }
-    return seed;
-}
+import { registerWebhooks } from "../channel-ingress.js";
 /** Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept both). */
 function listHasName(stdout, name) {
     try {
@@ -39,12 +30,12 @@ function listHasName(stdout, name) {
     }
 }
 /**
- * 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 async function deployFlyRun(plan, fly, log, registerTelegram, registerFeishu, registerSlack) {
+export async function deployFlyRun(plan, fly, log, registrars) {
     const gate = (g) => ({ ok: false, gate: g });
     // 1. Auth is the one gate a coding agent can't clear itself (browser OAuth). `whoami` succeeds with
     //    either an interactive login or FLY_API_TOKEN, so one check covers both.
@@ -113,42 +104,15 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
     if ((await fly(deployArgs)).code !== 0) {
         return gate("`fly deploy` failed — see the flyctl output above; fix and re-run");
     }
-    // 7. Post-deploy webhook — telegram end-to-end (fastagent has the token + the live URL); github is a
-    //    repo-settings step only a human can do. Gate policy is the shared registration-gate kernel
-    //    (registrars report facts, it owns the policy); all channels are attempted first.
-    const reg = registrationGate(log, "re-run to retry registration (steps already done are skipped)");
-    if (plan.channels.includes("telegram")) {
-        log("registering telegram webhook…");
-        reg.track("telegram", await registerTelegram(`https://${plan.appName}.fly.dev`));
-    }
-    if (plan.channels.includes("github")) {
-        log(`github: set the webhook in the repo (Settings → Webhooks) → https://${plan.appName}.fly.dev/webhook`);
-        reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
-    }
-    if (plan.channels.includes("slack")) {
-        const baseUrl = `https://${plan.appName}.fly.dev`;
-        if (registerSlack) {
-            log("registering slack event URL…");
-            reg.track("slack", await registerSlack(baseUrl));
-        }
-        else {
-            log(`slack: set Event Subscriptions → Request URL → ${baseUrl}/slack`);
-            reg.track("slack", "manual");
-        }
-    }
-    for (const kind of ["feishu", "lark"]) {
-        if (!plan.channels.includes(kind) || plan.longConnectionChannels?.includes(kind))
-            continue;
-        if (registerFeishu) {
-            log(`registering ${kind} event URL…`);
-            reg.track(kind, await registerFeishu(`https://${plan.appName}.fly.dev`, kind));
-        }
-        else {
-            log(`${kind}: set the event Request URL in the developer console (Events & Callbacks) → https://${plan.appName}.fly.dev/${kind} (the app must be running when you save)`);
-            reg.track(kind, "manual"); // no registrar wired — the console step above is the operator's
-        }
-    }
-    const registrationGateMsg = reg.gate();
+    // 7. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
+    //    kernel's; Fly contributes its deterministic URL and how to retry.
+    const registrationGateMsg = await registerWebhooks({
+        baseUrl: `https://${plan.appName}.fly.dev`,
+        channels: plan.channels,
+        registrars,
+        log,
+        retryHint: "re-run to retry registration (steps already done are skipped)",
+    });
     if (registrationGateMsg)
         return gate(registrationGateMsg);
     return { ok: true };

package/dist/deploy/preflight.d.ts

@@ -1,6 +1,6 @@
-import type { FastagentConfig } from "../engines/pi/config.ts";
+import { type FastagentConfig } from "../engines/pi/config.ts";
 import { type ResolvedPlacement } from "../paths.ts";
-import { type ChannelKind } from "../scaffold/add-channel.ts";
+import { type DeclaredChannel } from "../channels/discover.ts";
 import { type ContainerInput } from "./container.ts";
 /** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). Host-neutral advisories. */
 interface DeployMessage {
@@ -10,11 +10,10 @@ interface DeployMessage {
 /** The resolved facts every host plan needs (the container shape, channels, model auth, ports/secrets). */
 interface DeployFacts {
     messages: DeployMessage[];
-    channels: ChannelKind[];
-    /** Every structurally detected HTTP-route channel basename, including custom channels. */
-    routeChannels: string[];
-    /** Every structurally detected long-connection channel basename, including custom channels. */
-    longConnectionChannels: string[];
+    /** Every declared channel with the ingress its module shape says it has, custom ones included. The
+     *  ONE channel fact the plans and drivers read: a consumer that needs a subset derives it (see
+     *  {@link webhookKinds}) rather than receiving a list someone else already filtered. */
+    channels: DeclaredChannel[];
     /** Whether the agent has TIME triggers — `schedules/` files or `selfSchedule` (the wake tool). Cron/wake
      *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
      *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */

package/dist/deploy/preflight.js

@@ -14,15 +14,15 @@ import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
 import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
-import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
-import { inspectChannels } from "../engines/pi/channel.js";
+import { resolveSecretsDir, resolveStateRoot, exists } from "../paths.js";
+import { inspectChannels } from "../channels/discover.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
-import { exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.js";
+import { CONTROL_TOKEN_ENV } from "../channels/control.js";
 import { isEnvKey } from "./secrets.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore`
@@ -74,17 +74,19 @@ export async function preflightDeploy(input) {
         messages.push({ level: "warn", text: modelIssue });
     }
     // The control plane on a deployed box: `start` honors `sessionControl: true`, so `/control/*`
-    // (steer/abort/set_model) rides the PUBLIC host URL — protected only by a per-boot bearer token
-    // minted INSIDE the container (`<stateRoot>/control.json`), which external consumers cannot read.
-    // Publicly reachable yet unusable is the worst of both; the tunnel path warns loudly and deploy
-    // must not be the silent second way to break the loopback trust story.
+    // (steer, stop, rewrite or delete a session) rides the PUBLIC host URL, protected only by the bearer token. The token
+    // travels as a deploy secret (see extraSecrets below) so the caller has it; the reach still warrants
+    // a warning — the tunnel path warns loudly and deploy must not be the silent second way to break the
+    // loopback trust story.
     if (config.sessionControl === true) {
         messages.push({
             level: "warn",
-            text: `sessionControl: true — the deployed box serves /control/* (steer/abort/set_model) at its public URL, ` +
-                `protected only by a per-boot token written inside the container. Read the TOKEN from ` +
-                `<stateRoot>/control.json on the box (its url field is container-loopback — pair the token with the ` +
-                `public host URL: attach --url <public-url> --token …), or front the endpoint with real auth (design §14)`,
+            text: `sessionControl: true — the deployed box serves /control/* (steer, stop, rewrite or delete a session) at its public URL, ` +
+                `protected only by a bearer token. Set ${CONTROL_TOKEN_ENV} (listed with the other secrets) and give the ` +
+                `same value to callers: attach --url <public-url> --token …. Unset, the box mints its own per boot — ` +
+                `readable only by shelling in (\`docker compose exec\`/\`fly ssh console\`: <stateRoot>/control.json, whose ` +
+                `url field is container-loopback) and replaced on every restart. Front the endpoint with real auth for ` +
+                `anything wider (design §14)`,
         });
     }
     // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
@@ -93,20 +95,18 @@ export async function preflightDeploy(input) {
     if (inspected.failures.length > 0) {
         throw new Error(`cannot inspect channel modules: ${inspected.failures.map((failure) => `${failure.label}: ${failure.message}`).join("; ")}`);
     }
-    const discovered = inspected.channels;
-    const channels = discovered.filter((c) => CHANNEL_KINDS.includes(c));
-    const routeChannels = inspected.routeChannels;
-    const longConnectionChannels = inspected.longConnectionChannels;
-    for (const c of discovered) {
-        if (channels.includes(c))
+    const channels = inspected.channels;
+    for (const { name, ingress } of channels) {
+        if (CHANNEL_KINDS.includes(name))
             continue;
         messages.push({
             level: "note",
-            text: longConnectionChannels.includes(c)
-                ? `long-connection channel "${c}" is custom — configure its secrets yourself; generated deploy plans keep the process running and skip webhook registration`
-                : `route channel "${c}" is custom — configure its secrets and webhook yourself`,
+            text: ingress === "long-connection"
+                ? `long-connection channel "${name}" is custom — configure its secrets yourself; generated deploy plans keep the process running and skip webhook registration`
+                : `route channel "${name}" is custom — configure its secrets and webhook yourself`,
         });
     }
+    const longConnectionChannels = channels.filter((c) => c.ingress === "long-connection").map((c) => c.name);
     // Time triggers (static schedules or self-scheduling) need a machine kept running — unlike a webhook,
     // nothing external wakes a scale-to-zero box for a cron instant or a wake-up. The note is CONDITIONAL
     // ("the generated plan…"): in KEEP mode an existing fly.toml is not rewritten — the CLI warns separately
@@ -405,7 +405,13 @@ export async function preflightDeploy(input) {
     }
     // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
     // secrets: listed in the runbook, set from the local env under --run, gated if a value is missing.
-    const extraSecrets = config.deploy?.secrets ?? [];
+    const extraSecrets = [...(config.deploy?.secrets ?? [])];
+    // The plane's bearer token is the DEPLOYMENT's secret, not the container's: minted inside the box it
+    // is unreadable from outside and replaced on every restart, which is what makes a public /control/*
+    // unusable. Carried like any declared secret — listed in the runbook, taken from the local env under
+    // --run, gated when absent (never minted: a value minted per deploy rotates under its holder).
+    if (config.sessionControl === true)
+        extraSecrets.push(CONTROL_TOKEN_ENV);
     // deploy.apt only shapes the GENERATED Dockerfile. Warn ONLY when the kept Dockerfile is HAND-WRITTEN
     // (its apt won't include these) — a fastagent-generated one is handled by writeArtifacts. Don't suggest
     // --force here: it would overwrite the user's hand-written file.
@@ -423,8 +429,6 @@ export async function preflightDeploy(input) {
         ok: true,
         messages,
         channels,
-        routeChannels,
-        longConnectionChannels,
         hasTimeTriggers,
         modelAuth,
         modelKeyInDefinition,

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

@@ -21,7 +21,7 @@
  * the required-secret list. `railway.json`'s `healthcheckPath=/health` also fixes the "routed before the
  * server is listening" boot race Fly's deploy hit — Railway only routes once /health passes.
  */
-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 RailwayPlanInput extends ContainerInput {
     /** The service name to create (`railway add --service`). Railway service names are project-scoped, not
@@ -29,10 +29,9 @@ export interface RailwayPlanInput extends ContainerInput {
     serviceName: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Known first-party channels — each contributes its secret metadata + webhook step. */
-    channels: ChannelKind[];
-    /** All long-connection channel basenames, including custom channels — no App Sleeping. */
-    longConnectionChannels?: string[];
+    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
+     *  whether App Sleeping must stay off 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[];
     /** Time triggers present (schedules/ or selfSchedule) — the runbook forbids App Sleeping: cron/wake has

package/dist/deploy/railway/plan.js

@@ -1,3 +1,4 @@
+import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** State root = the volume mount path, kept in lockstep. `/data` matches the Fly recipe. */
@@ -7,8 +8,6 @@ const MOUNT = "/data";
  *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
  *  convention); two mechanisms, two documented spellings, one fact each. */
 export const dockerfilePathVar = (prefix) => `/${prefix}Dockerfile`;
-/** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
- *  are service settings the runbook applies via CLI. healthcheckPath gates routing on a live server. */
 /** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. Railway ignores
  *  unknown keys; the predicate below is what lets `--force` reset OUR file and keep a hand-written one. */
 const GENERATED_RAILWAY_KEY = "x-generated-by";
@@ -22,6 +21,8 @@ export function isGeneratedRailwayJson(content) {
         return false;
     }
 }
+/** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
+ *  are service settings the runbook applies via CLI. healthcheckPath gates routing on a live server. */
 function railwayJson(prefix) {
     return `${JSON.stringify({
         $schema: "https://railway.com/railway.schema.json",
@@ -45,7 +46,7 @@ export function planRailwayDeploy(input) {
         { path: configPath, content: railwayJson(input.agentPrefix) },
         ...containerArtifacts(input),
     ];
-    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);
     // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and
@@ -100,36 +101,20 @@ export function planRailwayDeploy(input) {
     }
     // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev) — ONE mint step, then each
     // channel's webhook uses that domain (mint once even when both channels are present).
-    const hasFeishuCloudChannel = ["feishu", "lark"].some((kind) => channels.includes(kind));
-    if (channels.includes("telegram") ||
-        channels.includes("github") ||
-        channels.includes("slack") ||
-        hasFeishuCloudChannel) {
-        runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`);
-    }
-    if (channels.includes("telegram")) {
-        runbook.push(`# Register the Telegram webhook (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://<your-domain>/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
-    }
-    if (channels.includes("github")) {
-        runbook.push(`# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped it`, `# in channels/github.ts, use your path:`, `#   Payload URL = https://<your-domain>/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
-    }
-    if (channels.includes("slack")) {
-        runbook.push(`# 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 = https://<your-domain>/slack`);
-    }
-    for (const kind of ["feishu", "lark"]) {
-        if (!channels.includes(kind) || input.longConnectionChannels?.includes(kind))
-            continue;
-        const label = kind === "feishu" ? "Feishu" : "Lark";
-        runbook.push(`# Set the ${label} event Request URL (developer console → Events & Callbacks). Default route`, `# POST /${kind}; the service must be RUNNING when you save (the console verifies with a challenge):`, `#   Request URL = https://<your-domain>/${kind}`);
+    // Mint only when something below needs it: with nothing to point at the domain (no channels, or only
+    // long-connection ones), "use it in the step(s) below" would refer to steps that do not follow.
+    const steps = webhookRunbook(`https://<your-domain>`, channels);
+    if (steps.length > 0) {
+        runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`, ...steps);
     }
     // Scale-to-zero: App Sleeping is dashboard-only (no CLI/API) — a manual step, not a generated setting.
     // A github channel should NOT enable it: fire-and-forget reviews have no replay (unlike Telegram's L1
     // turn store), so a sleep mid-review would drop it — the same floor the Fly plan enforces via config.
-    runbook.push(``, channels.includes("github")
+    runbook.push(``, channels.some((channel) => channel.name === "github")
         ? `# Scale-to-zero: do NOT enable App Sleeping — github turns have no replay, a sleep mid-review is lost.`
         : input.hasTimeTriggers
             ? `# Scale-to-zero: do NOT enable App Sleeping — schedules/wake-ups have no external wake-up; a sleeping service sleeps through them.`
-            : (input.longConnectionChannels?.length ?? 0) > 0
+            : channels.some((channel) => channel.ingress === "long-connection")
                 ? `# Scale-to-zero: do NOT enable App Sleeping — a long-connection channel must remain connected.`
                 : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
     return { artifacts, runbook };

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

@@ -23,8 +23,8 @@
  * no bulk stdin import like Fly's `secrets import`). Auth needs an ACCOUNT credential (login or
  * `RAILWAY_API_KEY`), not a project token: `init` creates a project that a project token can't predate.
  */
-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";
 export interface RailwayRunPlan {
     /** Names both the project (`railway init --name`) and the service (`railway add --service`). Railway
@@ -38,8 +38,8 @@ export interface RailwayRunPlan {
     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[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. Off
      *  by default so `--run` only creates on an unlinked dir and never deploys into a pre-existing (possibly
      *  unrelated/production) project; the flag is the operator's explicit "yes, this project". */
@@ -84,9 +84,9 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  */
 export declare function parseHasVolume(stdout: string, mountPath: string): boolean;
 /**
- * Run the deploy through `railway`. `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 `railway`. `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 deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registrars: Registrars): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -1,4 +1,29 @@
-import { registrationGate } from "../registration-gate.js";
+/**
+ * `fastagent deploy railway --run` — drive the Railway CLI to completion. The middle of the deploy the
+ * plain runbook hands to the operator; `--run` executes it so a coding agent runs ONE command.
+ *
+ * Railway's model forces differences from the Fly runner (fly/run.ts), all validated against CLI 5.15.0:
+ *
+ *  - **`--run` PROVISIONS a project and only runs on an UNLINKED directory** — so it can never deploy
+ *    into a project it didn't create. `railway init` isn't check-then-act (it ALWAYS makes a new project)
+ *    and `railway status` exits 0 even when unlinked (linkedness is read from stdout: JSON when linked,
+ *    empty when not). We do NOT track ownership: a pre-existing link is refused (Railway has no globally
+ *    unique name to give free identity like Fly's app name, and synthesizing one — a machine-local marker
+ *    — was a large, bug-prone premature optimization). The only "yes, this project" signal is the operator's
+ *    explicit `--into-linked`, which provisions INTO the linked project; a routine redeploy is just
+ *    `railway up`. The volume is check-then-act, so `--into-linked` (or a create that failed at volume-add) still gets it.
+ *  - **Every command needs `--service` explicitly** to stay non-interactive (a bare command prompts to
+ *    pick a service). `railway volume add` is the exception — it has NO `--service` flag and rides the
+ *    linked service, so the service must be created (and thus linked) first.
+ *  - **The public URL is minted, not deterministic** — bare `railway domain --json` returns the service
+ *    domain (minting one if absent), read for the webhook. We avoid the newer `domain list` subcommand:
+ *    on a CLI without it, `railway domain list` registers a bogus custom domain named "list" (destructive).
+ *
+ * Secrets go in one-per-`variable set --stdin` (value on stdin, never argv/process listing — Railway has
+ * no bulk stdin import like Fly's `secrets import`). Auth needs an ACCOUNT credential (login or
+ * `RAILWAY_API_KEY`), not a project token: `init` creates a project that a project token can't predate.
+ */
+import { registerWebhooks } from "../channel-ingress.js";
 /**
  * Whether `railway status --json` shows a linked project: non-empty stdout. Unlinked prints its message
  * to stderr and leaves stdout EMPTY (the exit code is 0 either way, so it can't be the signal). ANY
@@ -62,12 +87,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `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 `railway`. `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 async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu, registerSlack) {
+export async function deployRailwayRun(plan, railway, log, registrars) {
     const gate = (g) => ({ ok: false, gate: g });
     // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
     // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
@@ -173,40 +198,15 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
     if (!url) {
         return gate("couldn't read a domain from `railway domain` — run `railway domain` manually, then set any webhook");
     }
-    // 7. Post-deploy webhook — gate policy is the shared registration-gate kernel (registrars report
-    //    facts, it owns the policy); all channels are attempted first.
-    const reg = registrationGate(log, "re-run with --into-linked to retry registration");
-    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-surface it 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) || plan.longConnectionChannels?.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 in the developer console (Events & Callbacks) → ${url}/${kind} (the service must be running when you save)`);
-            reg.track(kind, "manual"); // no registrar wired — the console step above is the operator's
-        }
-    }
-    const registrationGateMsg = reg.gate();
+    // 7. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
+    //    kernel's; Railway contributes the minted URL and how to retry.
+    const registrationGateMsg = await registerWebhooks({
+        baseUrl: url,
+        channels: plan.channels,
+        registrars,
+        log,
+        retryHint: "re-run with --into-linked to retry registration",
+    });
     if (registrationGateMsg)
         return gate(registrationGateMsg);
     return { ok: true, url };