@fastagent-sh/fastagent 0.12.0 → 0.13.0

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

@@ -28,7 +28,7 @@ export interface FlyPlanInput extends ContainerInput {
      * `"OAuth"`/`"stored credential"` (a local login the server can't use), or undefined (unconfigured).
      */
     modelAuth: string | undefined;
-    /** Channels discovered in the workspace — each contributes its required secrets + webhook step. */
+    /** Channels discovered in the workspace — each contributes its secret metadata + webhook step. */
     channels: ChannelKind[];
     /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
     extraSecrets?: string[];

package/dist/deploy/fly/plan.js

@@ -1,5 +1,5 @@
 import { containerArtifacts } from "../container.js";
-import { isEnvKey, requiredSecrets } from "../secrets.js";
+import { deploymentSecrets, isEnvKey } from "../secrets.js";
 function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTriggers) {
     // min_machines_running: 1 (keep one up) when a github channel is present, TIME triggers exist, OR the
     // operator opted out of scale-to-zero. GitHub's is a SAFETY default — its fire-and-forget turns have no
@@ -60,7 +60,9 @@ 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 = requiredSecrets(modelAuth, channels, input.extraSecrets);
+    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
+    const requiredSecrets = secrets.filter((secret) => secret.required);
+    const optionalSecrets = secrets.filter((secret) => !secret.required);
     const deployCmd = kitDir
         ? `fly deploy . --config ${kitDir}/fly.toml --dockerfile ${kitDir}/Dockerfile --app ${appName}`
         : `fly deploy --app ${appName}`;
@@ -77,8 +79,11 @@ export function planFlyDeploy(input) {
         `# 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`,
     ];
-    if (secrets.length > 0) {
-        runbook.push(``, `# Secrets (replace each <value>):`, ...secrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+    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(" ")}`);
+    }
+    if (optionalSecrets.length > 0) {
+        runbook.push(``, `# Optional secrets — set only when the matching feature is configured:`, ...optionalSecrets.map((s) => `#   ${s.name}: ${s.hint}`), `# fly secrets set --app ${appName} ${optionalSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
     if (kitDir) {
         runbook.push(``, `# Repo-as-workspace: the build context is the REPO ROOT (the whole repo is the agent's cwd); the`, `# config/Dockerfile live under ${kitDir}/ so they never collide with the repo's own deploy files.`, `# Run this from the repo root:`);
@@ -106,6 +111,12 @@ export function planFlyDeploy(input) {
     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`);
     }
+    for (const kind of ["feishu", "lark"]) {
+        if (!channels.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}`);
+    }
     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

@@ -3,7 +3,7 @@
  * 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) with one actionable line and a non-zero
+ * (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).
@@ -17,6 +17,7 @@
  * (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 { CliRunner } from "../runner.ts";
 /**
@@ -45,7 +46,9 @@ export type FlyRunOutcome = {
     gate: string;
 };
 /**
- * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` performs the
- * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` /
+ * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
+ * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * instruction is printed. Every gate is fail-visible.
  */
-export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<void>): Promise<FlyRunOutcome>;
+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>): Promise<FlyRunOutcome>;

package/dist/deploy/fly/run.js

@@ -1,3 +1,4 @@
+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)
@@ -18,10 +19,12 @@ function listHasName(stdout, name) {
     }
 }
 /**
- * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` performs the
- * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` /
+ * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
+ * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * instruction is printed. Every gate is fail-visible.
  */
-export async function deployFlyRun(plan, fly, log, registerTelegram) {
+export async function deployFlyRun(plan, fly, log, registerTelegram, registerFeishu) {
     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.
@@ -77,13 +80,31 @@ export async function deployFlyRun(plan, fly, log, registerTelegram) {
         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.
+    //    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…");
-        await registerTelegram(`https://${plan.appName}.fly.dev`);
+        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
     }
+    for (const kind of ["feishu", "lark"]) {
+        if (!plan.channels.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();
+    if (registrationGateMsg)
+        return gate(registrationGateMsg);
     return { ok: true };
 }

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

@@ -29,7 +29,7 @@ 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;
-    /** Channels discovered in the workspace — each contributes its required secrets + webhook step. */
+    /** Channels discovered in the workspace — each contributes its secret metadata + webhook step. */
     channels: ChannelKind[];
     /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
     extraSecrets?: string[];

package/dist/deploy/railway/plan.js

@@ -1,5 +1,5 @@
 import { containerArtifacts } from "../container.js";
-import { isEnvKey, requiredSecrets } from "../secrets.js";
+import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** State root = the volume mount path, kept in lockstep. `/data` matches the Fly recipe. */
 const MOUNT = "/data";
 /** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
@@ -23,7 +23,9 @@ export function planRailwayDeploy(input) {
         { path: configPath, content: railwayJson(input.kitDir) },
         ...containerArtifacts(input),
     ];
-    const secrets = requiredSecrets(modelAuth, channels, input.extraSecrets);
+    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
     // variables are service-scoped and `railway up` deploys THE service — so the service must exist first
     // (`railway add --service`), and variables must be set BEFORE the first `up` or the box boots without a
@@ -51,8 +53,11 @@ export function planRailwayDeploy(input) {
         `# Variables — set BEFORE the first deploy so the box boots with them. Railway injects PORT itself.`,
         `railway variables set FASTAGENT_STATE_DIR=${MOUNT}`,
     ];
-    if (secrets.length > 0) {
-        runbook.push(`#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+    if (requiredSecrets.length > 0) {
+        runbook.push(`# Required secrets:`, `#   ${requiredSecrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${requiredSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+    }
+    if (optionalSecrets.length > 0) {
+        runbook.push(`# Optional secrets — set only when the matching feature is configured:`, `#   ${optionalSecrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `# railway variables set ${optionalSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
     // Model-auth guidance: an env key becomes a variable above. Otherwise the plan can't read the local
     // credential's value (OAuth or a stored key) to set it — same wording discipline as the Fly plan.
@@ -70,7 +75,8 @@ 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).
-    if (channels.includes("telegram") || channels.includes("github")) {
+    const hasFeishuCloudChannel = ["feishu", "lark"].some((kind) => channels.includes(kind));
+    if (channels.includes("telegram") || channels.includes("github") || 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")) {
@@ -79,6 +85,12 @@ export function planRailwayDeploy(input) {
     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`);
     }
+    for (const kind of ["feishu", "lark"]) {
+        if (!channels.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}`);
+    }
     // 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.

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

@@ -23,6 +23,7 @@
  * 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 { CliRunner } from "../runner.ts";
 export interface RailwayRunPlan {
@@ -75,7 +76,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; `registerTelegram(baseUrl)` performs the
- * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
+ * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
+ * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * instruction is printed. Every gate is fail-visible.
  */
-export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<void>): Promise<RailwayRunOutcome>;
+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>): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -1,3 +1,4 @@
+import { registrationGate } from "../registration-gate.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
@@ -61,10 +62,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` performs the
- * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
+ * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
+ * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * instruction is printed. Every gate is fail-visible.
  */
-export async function deployRailwayRun(plan, railway, log, registerTelegram) {
+export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu) {
     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
@@ -165,12 +168,31 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram) {
     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…");
-        await registerTelegram(url);
+        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
+    }
+    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 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();
+    if (registrationGateMsg)
+        return gate(registrationGateMsg);
     return { ok: true, url };
 }

package/dist/deploy/registration-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Host-NEUTRAL step-7 gate policy, shared by the host runners: the registrars report facts
+ * ({@link RegistrationOutcome}), this module owns what to do about them.
+ *
+ * - "failed" gates — exit 0 would tell a coding agent "done" while the deployed agent cannot receive
+ *   messages, and the runners' earlier steps are idempotent so a re-run just retries registration.
+ * - "manual" does NOT gate — re-running can never change it (an unclearable gate would spin a coding
+ *   agent forever) — but is re-surfaced after all registrar output (and before any gate message) so
+ *   the operator cannot miss it under the registrar's earlier log lines.
+ *
+ * The runners attempt ALL channels first (one failure doesn't skip the rest), then apply this policy
+ * once. Only the retry remediation differs per host (`retryHint`).
+ */
+import type { RegistrationOutcome } from "../channels/registration.ts";
+export declare function registrationGate(log: (msg: string) => void, retryHint: string): {
+    track: (kind: string, outcome: RegistrationOutcome) => void;
+    /** Logs the manual notices; returns the gate message (composes with cli.ts's "deploy stopped:"
+     *  prefix — it leads with the failure, not "the deploy succeeded"), or undefined for no gate. */
+    gate: () => string | undefined;
+};

package/dist/deploy/registration-gate.js

@@ -0,0 +1,20 @@
+export function registrationGate(log, retryHint) {
+    const unregistered = [];
+    const manual = [];
+    return {
+        track(kind, outcome) {
+            if (outcome === "failed")
+                unregistered.push(kind);
+            if (outcome === "manual")
+                manual.push(kind);
+        },
+        gate() {
+            for (const kind of manual) {
+                log(`${kind}: webhook registration needs a one-time manual step — see the instructions above`);
+            }
+            if (unregistered.length === 0)
+                return undefined;
+            return `webhook registration failed for: ${unregistered.join(", ")} — the app itself deployed; fix the error above, then ${retryHint}`;
+        },
+    };
+}

package/dist/deploy/secrets.d.ts

@@ -1,8 +1,7 @@
 /**
- * The secret set a deployed agent needs, computed from the definition — host-neutral. WHAT secrets are
- * required (the model key when local auth is an env key + every discovered channel's secrets) is the
- * same on every target; only the SET command differs (`fly secrets import` vs `railway variables set`).
- * The runbooks list these NAMES; `--run` (per host) reads their VALUES from the local env.
+ * The secret set a deployed agent needs, computed from the definition — host-neutral. Required values
+ * gate every target; optional channel values travel only when configured. Only the SET command differs
+ * (`fly secrets import` vs `railway variables set`). The runbooks list both classes; `--run` reads local values.
  */
 import { type ChannelKind } from "../scaffold/add-channel.ts";
 /**
@@ -13,13 +12,15 @@ import { type ChannelKind } from "../scaffold/add-channel.ts";
  */
 export declare function isEnvKey(source: string | undefined): source is string;
 /**
- * The required secret NAMES + hints for a runbook: the model key (when local auth is an env key) plus
- * every discovered channel's secrets. An OAuth/stored login has no env key here — it carries as
+ * Secret NAMES + hints for a runbook: the model key (when local auth is an env key), discovered channel
+ * secrets, and config extras. Channel metadata keeps optional values visible without presenting them as
+ * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export declare function requiredSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
+export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
     name: string;
     hint: string;
+    required: boolean;
 }[];
 /**
  * Assemble the secret VALUES a `--run` deploy sets on the host, from the local credential + channels —
@@ -32,8 +33,8 @@ export declare function requiredSecrets(modelAuth: string | undefined, channels:
  *
  * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
  * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
- * which a silent mint never surfaces) and would rotate every run (breaking idempotency). Absent →
- * `missingSecrets`, same as the plain runbook's operator-filled placeholders.
+ * which a silent mint never surfaces) and would rotate every run (breaking idempotency). An absent
+ * required value enters `missingSecrets`; an absent optional value is simply omitted.
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;

package/dist/deploy/secrets.js

@@ -1,8 +1,7 @@
 /**
- * The secret set a deployed agent needs, computed from the definition — host-neutral. WHAT secrets are
- * required (the model key when local auth is an env key + every discovered channel's secrets) is the
- * same on every target; only the SET command differs (`fly secrets import` vs `railway variables set`).
- * The runbooks list these NAMES; `--run` (per host) reads their VALUES from the local env.
+ * The secret set a deployed agent needs, computed from the definition — host-neutral. Required values
+ * gate every target; optional channel values travel only when configured. Only the SET command differs
+ * (`fly secrets import` vs `railway variables set`). The runbooks list both classes; `--run` reads local values.
  */
 import { channelSetup } from "../scaffold/add-channel.js";
 /**
@@ -15,22 +14,23 @@ export function isEnvKey(source) {
     return source !== undefined && /^[A-Z][A-Z0-9_]*$/.test(source);
 }
 /**
- * The required secret NAMES + hints for a runbook: the model key (when local auth is an env key) plus
- * every discovered channel's secrets. An OAuth/stored login has no env key here — it carries as
+ * Secret NAMES + hints for a runbook: the model key (when local auth is an env key), discovered channel
+ * secrets, and config extras. Channel metadata keeps optional values visible without presenting them as
+ * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export function requiredSecrets(modelAuth, channels, extraSecrets = []) {
+export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
     const secrets = [];
     if (isEnvKey(modelAuth))
-        secrets.push({ name: modelAuth, hint: "your model provider key" });
+        secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
     for (const kind of channels) {
         for (const e of channelSetup(kind).env)
-            secrets.push({ name: e.name, hint: e.hint });
+            secrets.push({ name: e.name, hint: e.hint, required: e.required });
     }
     // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
     for (const name of extraSecrets) {
         if (!secrets.some((s) => s.name === name)) {
-            secrets.push({ name, hint: "declared in fastagent.config deploy.secrets" });
+            secrets.push({ name, hint: "declared in fastagent.config deploy.secrets", required: true });
         }
     }
     return secrets;
@@ -46,8 +46,8 @@ export function requiredSecrets(modelAuth, channels, extraSecrets = []) {
  *
  * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
  * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
- * which a silent mint never surfaces) and would rotate every run (breaking idempotency). Absent →
- * `missingSecrets`, same as the plain runbook's operator-filled placeholders.
+ * which a silent mint never surfaces) and would rotate every run (breaking idempotency). An absent
+ * required value enters `missingSecrets`; an absent optional value is simply omitted.
  */
 export function assembleSecrets(input) {
     const secrets = {};
@@ -70,9 +70,10 @@ export function assembleSecrets(input) {
         for (const e of channelSetup(kind).env) {
             const v = input.env[e.name];
             if (v)
-                secrets[e.name] = v;
-            else
+                secrets[e.name] = v; // optional channel values travel when configured
+            else if (e.required) {
                 missingSecrets.push(e.name); // operator-provided (in .env); a human-shared secret can't be minted
+            }
         }
     }
     for (const name of input.extraSecrets ?? []) {

package/dist/dev-supervisor.js

@@ -16,6 +16,7 @@ import { watch as watchTree } from "chokidar";
 import { loadConfig, resolveAgentDir } from "./engines/pi/config.js";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
+import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
 export const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
@@ -99,7 +100,7 @@ export async function runDevSupervisor(dir, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(agentDir, t.url);
+                        void announceWebhooks(agentDir, t.url, { openUrl: openExternalUrl });
                     }
                 });
             }

package/dist/engines/pi/chat.js

@@ -7,7 +7,7 @@
  * AGENTS.md up to the repo root and discover skills from pi's own global dirs). So fastagent's
  * assembly is INJECTED into pi's session:
  *   - prompt  → systemPromptOverride = base + instructions ONLY; pi appends the skill section and env
- *               (date/cwd) itself (including them here would duplicate both).
+ *               (cwd) itself (including it here would duplicate it).
  *   - skills  → skillsOverride (fastagent's skills, for the section + invocation).
  *   - tools   → default coding tools by NAME (pi rebuilds them cwd-bound for rich rendering) +
  *               fastagent's custom tools via pi's customTools path (so they survive /new, /resume, fork).
@@ -68,8 +68,8 @@ sessionManager) {
             parameters: t.parameters,
             execute: (id, params, signal) => t.execute(id, params, signal),
         }));
-        // base + instructions ONLY — pi appends the skill section and env (date/cwd) itself (including
-        // them here would duplicate both).
+        // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
+        // them here would duplicate them).
         const systemPrompt = assembleSystemPrompt({
             base: piBasePrompt({ tools, persona: definition.persona }),
             contextFiles: definition.contextFiles,

package/dist/engines/pi/create.d.ts

@@ -46,7 +46,6 @@ export interface AssembleSystemPromptOptions {
     /** ③ Skills for the <available_skills> listing. */
     skills?: Skill[];
     /** ④ Env context, caller-provided (keeps this function pure). Omitted = segment omitted. */
-    date?: string;
     cwd?: string;
 }
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;

package/dist/engines/pi/create.js

@@ -54,10 +54,14 @@ export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
 //
 //   systemPrompt = ① base (engine asset; a persona.md persona overrides its identity line)
 //                + ② project context (AGENTS.md files via pi's loadProjectContextFiles, <project_context>-wrapped)
-//                + ③ skills listing + ④ env context (date/cwd)
+//                + ③ skills listing + ④ env context (cwd)
 //
-// AGENTS.md ≠ system prompt. Pure functions: segment ④ inputs (date/cwd) are caller-provided, so the
-// same inputs always produce the same prompt (testable, reproducible).
+// AGENTS.md ≠ system prompt. Pure functions: segment ④ input (cwd) is caller-provided, so the
+// same inputs always produce the same prompt (testable, reproducible). No date: a date line would
+// invalidate the provider prompt cache (a prefix cache) for every session at each day boundary —
+// channel sessions routinely live for weeks (pi ≥0.80.7 dropped it from its default prompt for the
+// same reason). The model gets the date when it needs it: `bash date`, and the wake tool takes
+// relative delays ("30m") / cron — never an absolute now-derived instant.
 /**
  * The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two
  * deviations: the pi-TUI docs section is dropped (those paths don't exist in deployments), and the
@@ -96,8 +100,6 @@ export function assembleSystemPrompt(options) {
     if (options.skills && options.skills.length > 0) {
         prompt += `\n${formatSkillsForSystemPrompt(options.skills)}\n`;
     }
-    if (options.date)
-        prompt += `\nCurrent date: ${options.date}`;
     if (options.cwd)
         prompt += `\nCurrent working directory: ${options.cwd}`;
     return prompt;
@@ -185,7 +187,7 @@ export async function createPiAgentFromDefinition(dir, options) {
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).
-        // One read yields prompt AND skills (they can never diverge), `date` is the turn's date, and the
+        // One read yields prompt AND skills (they can never diverge), and the
         // fs cost is a few reads against a model call. Broken edits stay visible: a throw-class problem
         // (unreadable AGENTS.md) fails that turn's invoke, and the loader's NON-fatal findings (bad
         // SKILL.md frontmatter, name collisions — returned as data, not thrown) are warned the moment
@@ -207,7 +209,6 @@ export async function createPiAgentFromDefinition(dir, options) {
                     // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
                     contextFiles: def.contextFiles,
                     skills: def.skills,
-                    date: new Date().toISOString().slice(0, 10),
                     cwd: env.cwd,
                 }),
                 skills: def.skills,

package/dist/feishu.d.ts

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
+export { feishuChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";

package/dist/feishu.js

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
+export { feishuChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";

package/dist/lark.d.ts

@@ -0,0 +1,3 @@
+/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
+ *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
+export { larkChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";

package/dist/lark.js

@@ -0,0 +1,3 @@
+/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
+ *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
+export { larkChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";

package/dist/open-url.d.ts

@@ -0,0 +1,2 @@
+/** Best-effort open a URL in the default browser. Callers must also print the URL for headless use. */
+export declare function openExternalUrl(url: string): void;

package/dist/open-url.js

@@ -0,0 +1,6 @@
+import { spawn } from "node:child_process";
+/** Best-effort open a URL in the default browser. Callers must also print the URL for headless use. */
+export function openExternalUrl(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).on("error", () => { });
+}

package/dist/scaffold/add-channel.d.ts

@@ -1,8 +1,10 @@
-export type ChannelKind = "github" | "telegram";
+export type ChannelKind = "github" | "telegram" | "feishu" | "lark";
 /** An env var a scaffolded channel reads. `generate` = a random-string secret the CLI can pre-fill. */
 export interface ChannelEnv {
     name: string;
     hint: string;
+    /** Required for the channel to run. Optional values are deployed when present but never gate deploy. */
+    required: boolean;
     generate?: boolean;
 }
 /** The channel kinds `fastagent add <kind>` can scaffold. */
@@ -26,11 +28,13 @@ export interface DotEnvWriteResult {
 }
 /**
  * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept. Manual values (e.g.
- * TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is ready to
- * edit while no fake secret is committed to the user's mental model.
+ * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * `overwrite`: those are authoritative (e.g. the credentials of an app `add feishu` JUST minted —
+ * skipping them for a stale value would silently discard a fresh, unrecoverable secret). Manual values
+ * (e.g. TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is
+ * ready to edit while no fake secret is committed to the user's mental model.
  */
-export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>): Promise<DotEnvWriteResult>;
+export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[]): Promise<DotEnvWriteResult>;
 /** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
 export declare function channelExists(dir: string, kind: ChannelKind): Promise<boolean>;
 /**