@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/service.js

@@ -1,20 +1,19 @@
-/** The product, as one call: an agent directory becomes a live service. */
+/** The product, as one call: an opened agent becomes a live service, its channels, schedules and wake-ups. */
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Scope from "effect/Scope";
-import { createControlPlane } from "./channels/control.js";
-import { createInvokeHandler } from "./channels/http.js";
+import { mountChannels } from "./channels/discover.js";
 import { text } from "./channels/respond.js";
-import { assertCorsOrigins, parseRouteKey, pathUnderPrefix, router } from "./channels/serve.js";
-import { loadChannels } from "./channels/discover.js";
-import { loadRoutines } from "./schedule/discover.js";
-import { createRoutineListHandler, createRunHandler } from "./schedule/run.js";
-import { createScheduler } from "./schedule/scheduler.js";
+import { parseRouteKey, router } from "./channels/router.js";
+import { serveHandler, totalFetch } from "./channels/serve.js";
+import { portCleanup } from "./effect-port.js";
+import { API_PREFIX } from "./http/contract.js";
+import { apiHandler, isApiPath } from "./http/server.js";
 import { log } from "./log.js";
-import { refuseBrokenDeclarations } from "./loader.js";
-import { gateSecrets } from "./secrets-gate.js";
+import { once } from "./once.js";
+import { createScheduler } from "./schedule/scheduler.js";
 /** Default wait for a channel's `closed` before reporting it stuck. */
 const CLOSE_DEADLINE_MS = 5_000;
 /** One deadline for all connections; a failed close must not hide a sibling that is still running. */
@@ -42,98 +41,23 @@ function closeWithin(runs, names, deadlineMs) {
 }
 /** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
 export const DEFAULT_HTTP_PORT = 8787;
-/**
- * Does this surface serve `POST /run`, given a routine to run? It FOLLOWS `invoke` unless `run` says otherwise (see
- * {@link HttpSurface.run}). ONE function because the assembly mounts the route and `preflightDeploy` names it; a
- * default spelled twice is a default that moves once.
- */
-export function shouldServeRun(http) {
-    return http?.run ?? http?.invoke !== false;
-}
-/**
- * What an anonymous caller of a port can do, worst first — the ONE wording the startup report and deploy's pre-flight
- * both print, each from its own facts (what mounted vs what will mount).
- */
-export function describeAnonymousSurface(open) {
-    return [
-        ...(open.invoke ? ["POST /invoke (run a turn with this agent's tools)"] : []),
-        ...(open.run ? ["POST /run (run any routine this agent declares; GET /routines lists them)"] : []),
-        ...(open.controlPrefix ? [`${open.controlPrefix}/* (read, steer or delete any session)`] : []),
-    ];
-}
-/**
- * The surface this deployment serves: the DATA plane (`POST /invoke`), `GET /health`, and the discovered channels.
- *
- * `/invoke` is the framework's interface, so it is served whatever channels a definition declares (unless
- * `http.invoke: false`). It is RESERVED for the same reason `/control/*` is: a channel taking that path would silently replace the one route every client,
- * every doc and the startup line all name. `/health` stays overridable — a probe is the deployment's to shape.
- */
-export async function routesFor(agentDir, agent, stateRoot, control, 
-/**
- * `http.invoke: false` withholds the data plane. Two callers, two reasons: the AgentCore adapter serves the
- * Runtime's `/invocations` contract instead, and an author sets it to leave the channels' signature checks as the
- * only way into a public port.
- *
- * `routines` mounts `POST /run` and `GET /routines` (per {@link shouldServeRun}). Passed in rather than loaded here
- * so the routes and the resident clock cannot disagree about which routines exist (`loadServingRoutines`).
- */
-options = {}) {
-    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
-        agent,
-        stateRoot,
-        control,
-    });
-    for (const c of collisions) {
-        log.warn(`[fastagent] channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
-    }
-    refuseBrokenDeclarations(failures);
-    if (collisions.length > 0) {
-        throw new Error(`${collisions.length} channel route collision(s) — two channels cannot serve one route`);
+/** Mount the channels and the health check. */
+export function routesFor(agent, stateRoot, channels) {
+    const { routes, longConnections, routeChannels } = mountChannels(channels, agent, stateRoot);
+    for (const key of Object.keys(routes)) {
+        if (isApiPath(parseRouteKey(key).path)) {
+            throw new Error(`route "${key}" is under ${API_PREFIX}, which the Agent API serves — move it`);
+        }
     }
-    /**
-     * Which channel key already serves this path for the method a built-in would answer — the CHANNEL's spelling, not
-     * ours. A channel may write the method-less `"/invoke"`, and an error naming `"POST /invoke"` sends its author
-     * grepping their own file for a string that is not in it.
-     */
-    const covered = (path, method) => Object.keys(routes).find((key) => {
-        const entry = parseRouteKey(key);
-        return entry.path === path && (entry.method === undefined || entry.method === method);
-    });
     let ready = longConnections.length === 0;
     const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
-    // AgentCore serves the data plane through the Runtime's own `/invocations` contract, so the adapter opts out — and
-    // with no `/invoke` of ours on that surface there is nothing to reserve, which is why the refusal is in here.
-    const unverified = { ...(covered("/health", "GET") ? {} : { "GET /health": health }) };
-    if (options.http?.invoke !== false)
-        unverified["POST /invoke"] = createInvokeHandler(agent);
-    // `POST /run` exists only where there is something to run, and `GET /routines` exactly where that route does:
-    // it is the catalogue OF that route, so listing names nobody can use would be a catalogue of nothing. Both ride
-    // this table for the reason the table exists: they authenticate nobody, so they inherit the JSON body gate, the
-    // cross-origin policy, the reserved path and the startup report's account of what is open.
-    if (shouldServeRun(options.http)) {
-        const routines = options.routines ?? [];
-        const run = createRunHandler({ agent, routines });
-        if (run)
-            unverified["POST /run"] = run;
-        const list = createRoutineListHandler({ routines });
-        if (list)
-            unverified["GET /routines"] = list;
-    }
-    // ONE rule over the whole table, so the next route we add is reserved by existing here rather than by someone
-    // remembering to write a second check for it. `/health` is exempt by construction: it is only in `ours` when no
-    // channel already serves it, because a probe is the deployment's to shape.
-    const taken = Object.keys(unverified).flatMap((key) => {
+    const probed = Object.keys(routes).some((key) => {
         const entry = parseRouteKey(key);
-        const channelKey = covered(entry.path, entry.method ?? "");
-        return channelKey === undefined ? [] : [{ channelKey, key }];
+        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
     });
-    if (taken.length > 0) {
-        throw new Error(`channel route(s) ${taken.map((t) => `"${t.channelKey}"`).join(", ")} take a path this serve answers on ` +
-            `itself (${taken.map((t) => `"${t.key}"`).join(", ")}) — rename the channel route`);
-    }
     return {
-        unverified,
-        selfVerifying: routes,
+        // A probe is the deployment's to shape, so a channel may serve `/health` itself.
+        routes: probed ? routes : { ...routes, "GET /health": health },
         longConnections,
         routeChannels,
         setReady(value) {
@@ -141,78 +65,71 @@ options = {}) {
         },
     };
 }
-/** Refuse channel routes the control plane would swallow. */
-export function assertNoControlPlaneCollision(channelRoutes, plane) {
-    const collisions = Object.keys(channelRoutes).filter((key) => pathUnderPrefix(parseRouteKey(key).path, plane.prefix));
-    if (collisions.length > 0) {
-        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control plane — ` +
-            `rename the channel route or disable sessionControl in fastagent.config`);
-    }
-}
-export function mountSessionControl(routes, control) {
-    if (!control)
-        return { routes, mounts: [] };
-    const plane = createControlPlane(control);
-    assertNoControlPlaneCollision(routes, plane);
-    return { routes, mounts: [plane], controlPrefix: plane.prefix };
-}
-/**
- * Load the agent's `routines/`, gated.
- *
- * Separate from {@link startSchedules} because two things need the SAME list and one of them runs first: the
- * `POST /run` route is built with the routes (so a channel cannot take that path unnoticed), and the resident
- * clock starts later, inside the service's scope. Loading twice would let them disagree about which routines exist.
- */
-export async function loadServingRoutines(agentDir) {
-    // Thrown, not exited on: this runs inside an embedder's app as well as the CLI, and a library that calls
-    // process.exit takes a decision (degrade? retry? stop?) that belongs to its host.
-    const { routines, secrets, failures } = await loadRoutines(agentDir);
-    // The routines' half of the serving-path gate (the opener does the tools', loadChannels the
-    // channels'): a routine reads its env at IMPORT time, so an unset declared value has already
-    // produced a broken prompt — refusing here is the last point where that is a startup failure.
-    gateSecrets({ declared: secrets, failures });
-    refuseBrokenDeclarations(failures);
-    return routines;
-}
-/**
- * Start the clock over routines {@link loadServingRoutines} already gated — on every serve, routines or not: the
- * agent's own wake-ups are a default capability, and this is what fires them.
- */
-export function startSchedules(agent, stateRoot, routines, options = {}) {
-    const scheduler = Effect.runSync(createScheduler({ agent, stateRoot, routines, externalClock: options.externalClock }));
+/** Start the clock: the definition's schedules, and the wake-ups the agent sets for itself, on every serve. */
+export function startSchedules(agent, stateRoot, schedules, options = {}) {
+    const scheduler = Effect.runSync(createScheduler({
+        agent,
+        stateRoot,
+        schedules,
+        ...(options.localClock === false ? { localClock: false } : {}),
+    }));
     scheduler.start();
-    if (routines.length > 0) {
-        log.info(`[fastagent] routines: ${routines.map((r) => r.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
-    }
-    return { routines, stop: () => scheduler.stop() };
+    if (schedules.length > 0)
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    return scheduler;
 }
 /**
- * The assembly itself, over an already-opened directory: channels, the control plane, routines and long connections,
- * composed into one handler.
+ * A Service over `handler`: answered in process, or served on a server of its own. `endStreams` ends what would hold
+ * the server's close open (a Caller watching events), and `shutdown` stops the rest once the server has.
  */
-export async function mountAgentService(opened, options = {}) {
-    const { agentDir, workspace, stateRoot, sessionControl } = opened;
-    // Wrapped BEFORE anything consumes it: routes, the control plane and routines must all drive the same agent, so
-    // this is a hook rather than something a caller applies afterwards.
-    const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
+export function serviceOver(handler, ready, shutdown, endStreams = async () => { }) {
+    let listener;
+    let closing;
+    const fetch = totalFetch(handler);
+    return {
+        fetch,
+        listen(port, host) {
+            if (closing !== undefined)
+                return Promise.reject(new Error("the service is closed"));
+            if (listener !== undefined)
+                return Promise.reject(new Error("the service is already listening"));
+            const current = serveHandler(handler, { port, ...(host === undefined ? {} : { host }) });
+            listener = current;
+            return current.listening.catch(async (error) => {
+                // A bind that failed holds nothing once its scope is closed, so the service may listen again, elsewhere.
+                if (listener === current)
+                    listener = undefined;
+                await current.close();
+                throw error;
+            });
+        },
+        ready,
+        close() {
+            closing ??= (async () => {
+                // The server first, so nothing new reaches what stops after it; each step runs, and every failure is said.
+                const failures = [];
+                for (const step of [endStreams, () => listener?.close(), shutdown]) {
+                    await Promise.resolve()
+                        .then(step)
+                        .catch((error) => failures.push(error));
+                }
+                if (failures.length > 0) {
+                    throw failures.length === 1 ? failures[0] : new AggregateError(failures, "the service did not close cleanly");
+                }
+            })();
+            return closing;
+        },
+    };
+}
+/** The assembly itself: channels, schedules and long connections, composed into one handler. */
+export async function serveAgent(opened, options = {}) {
+    const { agent, agentDir, stateRoot, schedules } = opened;
     const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
-    // The embedder's way in, checked like the config file's: `allowedOrigin` compares exact strings, so a stray
-    // trailing slash would refuse the front end with nothing naming the rule.
-    const corsOrigins = opened.http?.cors;
-    if (corsOrigins)
-        assertCorsOrigins(corsOrigins, "mountAgentService: http.cors");
-    // Loaded BEFORE the routes, because `POST /run` is one of them and the resident clock below must run over the
-    // same list — two loads would be two answers to "which routines exist".
-    const routines = await loadServingRoutines(agentDir);
-    const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { http: opened.http, routines });
-    const withControl = mountSessionControl(routed.selfVerifying, opened.publishControl ? sessionControl : undefined);
+    const routed = routesFor(agent, stateRoot, opened.channels);
     // Composed BEFORE anything starts.
-    const handler = router({
-        unverified: routed.unverified,
-        selfVerifying: withControl.routes,
-        mounts: withControl.mounts,
-        ...(corsOrigins ? { corsOrigins } : {}),
-    });
+    const channels = router(routed.routes);
+    const api = options.apiKeys?.length ? apiHandler(agent, { keys: options.apiKeys }) : undefined;
+    const handler = api === undefined ? channels : (req) => (isApiPath(new URL(req.url).pathname) ? api.fetch(req) : channels(req));
     return Effect.runPromise(Effect.gen(function* () {
         const lifetime = yield* Scope.make();
         const abort = new AbortController();
@@ -229,21 +146,21 @@ export async function mountAgentService(opened, options = {}) {
             routed.setReady(false);
             onClosed(name, error);
         };
-        // Scope.close alone does not join concurrent closes or retain their failure.
-        const shutdown = yield* Effect.cached(Effect.gen(function* () {
+        // Scope.close alone does not join concurrent closes or retain their failure. Every later call, the rollback a
+        // close itself triggers included, awaits the first one's outcome.
+        const shutdown = once(Effect.gen(function* () {
             abort.abort();
             yield* Scope.close(lifetime, Exit.void);
         }));
         const close = () => Effect.runPromise(shutdown);
         const rollback = shutdown.pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`[fastagent] cleanup after a failed start also failed: ${String(Cause.squash(cause))}`))));
-        const onAbort = () => {
-            void close().catch((error) => log.error(`[fastagent] service close failed: ${String(error)}`));
-        };
         return yield* Effect.gen(function* () {
+            if (api !== undefined)
+                yield* Effect.addFinalizer(() => portCleanup("closing the Agent API", api.dispose));
             // Registered first, so subscriptions and schedule timers stop before waiting for transports.
             yield* Effect.addFinalizer(() => closeWithin(runs, names, closeTimeoutMs).pipe(Effect.orDie));
-            const scheduled = yield* Effect.acquireRelease(Effect.try({
-                try: () => startSchedules(agent, stateRoot, routines),
+            yield* Effect.acquireRelease(Effect.try({
+                try: () => startSchedules(agent, stateRoot, schedules),
                 catch: (error) => error,
             }), (scheduled) => Effect.sync(scheduled.stop));
             const readiness = yield* Effect.forEach(routed.longConnections, (connection) => Effect.gen(function* () {
@@ -269,10 +186,6 @@ export async function mountAgentService(opened, options = {}) {
                         log.info(`[fastagent] long connection ready: ${connection.name}`);
                 })), Effect.forkScoped({ startImmediately: true }));
             }));
-            if (options.signal?.aborted)
-                yield* shutdown;
-            else
-                yield* Effect.acquireRelease(Effect.sync(() => options.signal?.addEventListener("abort", onAbort, { once: true })), () => Effect.sync(() => options.signal?.removeEventListener("abort", onAbort)));
             // The public readiness waiter lives outside the scope it may roll back.
             const ready = Effect.runPromise(Effect.gen(function* () {
                 yield* Effect.forEach(readiness, Fiber.join, { concurrency: "unbounded", discard: true });
@@ -287,21 +200,12 @@ export async function mountAgentService(opened, options = {}) {
             // The rejection is still delivered to callers that await ready.
             ready.catch(() => { });
             return {
-                handler,
-                agent,
-                routes: { ...routed.unverified, ...withControl.routes },
+                ...serviceOver(handler, ready, close, async () => api?.endStreams()),
+                routes: routed.routes,
                 agentDir,
-                workspace,
-                channels: {
-                    routes: routed.routeChannels,
-                    longConnections: names,
-                },
-                unverifiedRoutes: Object.keys(routed.unverified),
-                ...(corsOrigins ? { corsOrigins } : {}),
-                routines: scheduled.routines,
-                ready,
-                ...(withControl.controlPrefix ? { controlPrefix: withControl.controlPrefix } : {}),
-                close,
+                channels: { routes: routed.routeChannels, longConnections: names },
+                schedules,
+                api: api !== undefined,
             };
         }).pipe(Scope.provide(lifetime), Effect.onError(() => rollback));
     }));

package/dist/serving-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Which command serves this process: `dev` marks it, and everything else (`start`, a deployed box, an embedder) is
+ * the default. A channel file reads it at import through the agent's OWN installed copy of this package, which shares
+ * nothing with the CLI's copy but the process environment, so the mark lives there.
+ */
+export declare const DEV_SERVE_ENV = "FASTAGENT_DEV";
+export declare function markDevServe(env?: NodeJS.ProcessEnv): void;
+/** For a command that is never `dev` (`start`, `deploy`), run from a shell or a tool that a `dev` process spawned. */
+export declare function unmarkDevServe(env?: NodeJS.ProcessEnv): void;
+export declare function servedByDev(env?: NodeJS.ProcessEnv): boolean;

package/dist/serving-command.js

@@ -0,0 +1,16 @@
+/**
+ * Which command serves this process: `dev` marks it, and everything else (`start`, a deployed box, an embedder) is
+ * the default. A channel file reads it at import through the agent's OWN installed copy of this package, which shares
+ * nothing with the CLI's copy but the process environment, so the mark lives there.
+ */
+export const DEV_SERVE_ENV = "FASTAGENT_DEV";
+export function markDevServe(env = process.env) {
+    env[DEV_SERVE_ENV] = "1";
+}
+/** For a command that is never `dev` (`start`, `deploy`), run from a shell or a tool that a `dev` process spawned. */
+export function unmarkDevServe(env = process.env) {
+    delete env[DEV_SERVE_ENV];
+}
+export function servedByDev(env = process.env) {
+    return env[DEV_SERVE_ENV] === "1";
+}

package/dist/slack.d.ts

@@ -1,4 +1,4 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
 export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
-export { slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
+export { slackThreads, slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
 export type { SentSlackMessage, SlackTarget, UploadedSlackFile } from "./channels/slack/slack-api.ts";

package/dist/slack.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
 export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
-export { slackTransport } from "./channels/slack/shared-api.js";
+export { slackThreads, slackTransport } from "./channels/slack/shared-api.js";

package/dist/{channels/kit/state.js → state-file.js}

@@ -1,12 +1,12 @@
 /**
- * Durable channel state, with no cross-instance locking: every file here is keyed by CHANNEL KIND
- * (`<stateRoot>/channels/<kind>/`), so what must not happen is two processes serving the SAME channel — which also
- * means one ingress credential in two places, and no local guard can see that. Two processes serving different
- * channels of one agent never touch the same file (docs/design/core.md, "the shipped file-backed implementations").
+ * A Caller's durable state under the state root, with no cross-instance locking: a channel's files are in its own
+ * directory (`<stateRoot>/channels/<the channel file's name>/`) and the schedules' in `schedule/`, so what must not
+ * happen is two processes serving the SAME channel — which also means one ingress credential in two places, and no
+ * local guard can see that (docs/design/core.md §9).
  */
 import { mkdirSync, readFileSync } from "node:fs";
-import { writeFileAtomic } from "../../atomic-write.js";
-import { log } from "../../log.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { log } from "./log.js";
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
     mkdirSync(dir, { recursive: true });

package/dist/telegram.d.ts

@@ -1,2 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
 export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
+export { telegramTransport, type TelegramSendTarget, type TelegramSent, type TelegramTransport, } from "./channels/telegram/shared-api.ts";

package/dist/telegram.js

@@ -1,2 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
 export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";
+export { telegramTransport, } from "./channels/telegram/shared-api.js";

package/dist/tunnel.d.ts

@@ -27,6 +27,9 @@ export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloud
 export declare function announceWebhooks(dir: string, baseUrl: string, channels: readonly DeclaredChannel[], opts?: {
     openUrl?: (url: string) => void;
     stateRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    /** {@link Registrars.leave}. */
+    leave?: (step: string) => void;
 }): Promise<{
     kind: string;
     outcome: RegistrationOutcome;

package/dist/tunnel.js

@@ -7,10 +7,10 @@ import { spawn } from "node:child_process";
 import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
 import { registerSlackWebhook } from "./channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
-import { pointChannelsAt } from "./deploy/channel-ingress.js";
+import { pointChannelsAt, webhookKinds } from "./deploy/channel-ingress.js";
 import { dotEnvPath, loadDotEnv } from "./env.js";
 import { installProxyFetch } from "./proxy.js";
-import { resolveStateRoot } from "./paths.js";
+import { AGENT_ENVIRONMENT_ENV, resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";
 // `(?!api\.)`: cloudflared's ERROR lines mention its request endpoint (`https://api.trycloudflare.com/tunnel`, e.g.
 // "failed to request quick Tunnel: Post ... timeout" under a flaky proxy) — without the exclusion a transient error
@@ -130,7 +130,8 @@ function lastErrorLine(tail) {
 export async function announceWebhooks(dir, baseUrl, channels, opts = {}) {
     log.info(`[fastagent] public URL: ${baseUrl}`);
     try {
-        loadDotEnv(dir); // webhook registrars read channel credentials from .env
+        if (!opts.env)
+            loadDotEnv(dir);
     }
     catch (error) {
         // best-effort boundary: an unreadable .env (a MISSING one is already tolerated) still leaves registrars that can
@@ -141,16 +142,23 @@ export async function announceWebhooks(dir, baseUrl, channels, opts = {}) {
     // Readiness is the registrar's job: a fresh quick tunnel returns Cloudflare 530 for ~20-30s before its origin
     // connects, and each registrar absorbs that by retrying the platform call whose own URL verification reports it.
     const feishuOptions = {
+        env: opts.env,
         onManualRegistration: ({ consoleUrl }) => opts.openUrl?.(consoleUrl),
     };
+    const moving = webhookKinds(channels);
+    if (moving.length > 0) {
+        log.info(`[fastagent] pointing the selected ${moving.join(", ")} app at ${baseUrl}; only this app's Request URL changes`);
+    }
     return pointChannelsAt({
         baseUrl,
         channels,
         log: (message) => log.info(`[fastagent] ${message}`),
         registrars: {
-            telegram: (url) => registerTelegramWebhook(url),
+            ...(opts.leave === undefined ? {} : { leave: opts.leave }),
+            telegram: (url) => registerTelegramWebhook(url, { env: opts.env }),
             slack: (url) => registerSlackWebhook(url, {
                 stateRoot: opts.stateRoot ?? resolveStateRoot(dir),
+                environment: process.env[AGENT_ENVIRONMENT_ENV] === "production" ? "production" : "dev",
                 log: (message) => log.info(message),
             }),
             feishu: (url, kind) => registerFeishuWebhook(url, kind, feishuOptions),

package/dist/value-file.d.ts

@@ -0,0 +1,21 @@
+/** One variable to write: with a `value`, an active line; without one, a placeholder under its `hint`. */
+export interface ValueEntry {
+    name: string;
+    value?: string;
+    hint?: string;
+}
+export interface ValueWriteResult {
+    /** Generated values written as active `NAME=value` lines. */
+    written: string[];
+    /** Vars already present with a non-empty active value; left untouched and omitted from next steps. */
+    alreadySet: string[];
+    /** Set when the secrets dir is an operator-chosen one (`FASTAGENT_SECRETS_DIR`) carrying no `.gitignore`. */
+    unprotectedSecretsDir?: string;
+}
+/** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
+export declare function unprotectedSecretsNote(dir: string): string;
+/**
+ * Write `entries` into the selected environment's value file, under a `# --- <section> ---` line. A name with a
+ * non-empty active value is kept unless `overwrite` names it.
+ */
+export declare function writeValues(dir: string, section: string, entries: readonly ValueEntry[], overwrite?: readonly string[]): Promise<ValueWriteResult>;

package/dist/value-file.js

@@ -0,0 +1,108 @@
+/**
+ * Writing the selected environment's value file (`.secrets/.env`, or `.secrets/production/.env` for a deployment):
+ * what a command generates (a channel's secret, the Agent API's key) goes in as an active `NAME=value` line, a value
+ * already set stays, and the secrets directory fastagent made carries its own `.gitignore`.
+ */
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { dotEnvPath, parseEnvContent } from "./env.js";
+import { SECRETS_DIRNAME, SECRET_FILE_MODE, exists } from "./paths.js";
+import { baseTemplate } from "./scaffold/templates.js";
+/** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
+export function unprotectedSecretsNote(dir) {
+    return (`${dir} (FASTAGENT_SECRETS_DIR) now holds a secret and has no .gitignore — that directory is yours, so ` +
+        "fastagent will not write one into it. Make sure git does not track what is in there.");
+}
+/** Whether `.env` content carries a non-empty ACTIVE value for `name`. */
+function hasActiveEnvValue(content, name) {
+    return (parseEnvContent(content).get(name)?.trim() ?? "") !== "";
+}
+function mentionsEnvName(content, name) {
+    return content.split("\n").some((line) => new RegExp(`^\\s*#?\\s*${name}\\s*=`).test(line));
+}
+/**
+ * Write `entries` into the selected environment's value file, under a `# --- <section> ---` line. A name with a
+ * non-empty active value is kept unless `overwrite` names it.
+ */
+export async function writeValues(dir, section, entries, overwrite = []) {
+    const file = dotEnvPath(dir);
+    const secretsDir = dirname(file);
+    await mkdir(secretsDir, { recursive: true });
+    // THE one exception to "fastagent has no opinion about git": the directory it writes secrets into carries its own
+    // `.gitignore`.
+    const owned = secretsDir === join(dir, SECRETS_DIRNAME) || secretsDir === join(dir, SECRETS_DIRNAME, "production");
+    let unprotectedSecretsDir;
+    if (owned) {
+        // Only EEXIST is tolerable (already protected, or a concurrent writer).
+        await writeFile(join(secretsDir, ".gitignore"), baseTemplate("secrets.gitignore"), { flag: "wx" }).catch((e) => {
+            if (e.code !== "EEXIST")
+                throw e;
+        });
+    }
+    else if (!(await exists(join(secretsDir, ".gitignore")))) {
+        unprotectedSecretsDir = secretsDir;
+    }
+    let current = "";
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const alreadySet = entries
+        .filter((e) => !overwrite.includes(e.name) && hasActiveEnvValue(current, e.name))
+        .map((e) => e.name);
+    const lines = [];
+    const written = [];
+    const contentLines = current.split("\n");
+    let replacedInPlace = false;
+    for (const e of entries) {
+        if (alreadySet.includes(e.name))
+            continue;
+        if (e.value !== undefined) {
+            // An ACTIVE but EMPTY assignment already in the file (an uncommented, unfilled placeholder from `cp
+            // .env.example .env`) must be replaced IN PLACE.
+            let idx = -1;
+            for (let i = contentLines.length - 1; i >= 0; i--) {
+                if (parseEnvContent(contentLines[i]).has(e.name)) {
+                    idx = i;
+                    break;
+                }
+            }
+            if (idx >= 0) {
+                contentLines[idx] = `${e.name}=${e.value}`;
+                replacedInPlace = true;
+            }
+            else {
+                lines.push(`${e.name}=${e.value}`);
+            }
+            written.push(e.name);
+        }
+        else if (!mentionsEnvName(current, e.name)) {
+            // Hint above, never inline after `=` (this IS the file loadDotEnv reads).
+            lines.push(...(e.hint === undefined ? [] : [`# ${e.hint}`]), `# ${e.name}=`);
+        }
+    }
+    // 0600 on the file this call CREATES, and nothing at all about one it did not: a `.env` the operator made with
+    // `cp .secrets/.env.example .secrets/.env` carries the mode that command gave it, and re-deciding it would be
+    // fastagent changing the permissions of a file it does not own.
+    const secret = { mode: SECRET_FILE_MODE };
+    if (replacedInPlace) {
+        current = contentLines.join("\n");
+        await writeFile(file, current, secret);
+    }
+    if (lines.length > 0) {
+        const marker = `# --- ${section} ---`;
+        if (current.includes(marker)) {
+            // A marker already present (e.g. a .env copied from .env.example) — slot the new lines under it instead of
+            // orphaning them at the end of the file.
+            await writeFile(file, current.replace(marker, `${marker}\n${lines.join("\n")}`), secret);
+        }
+        else {
+            const prefix = current === "" ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+            await appendFile(file, `${prefix}${marker}\n${lines.join("\n")}\n`, secret);
+        }
+    }
+    return { written, alreadySet, ...(unprotectedSecretsDir === undefined ? {} : { unprotectedSecretsDir }) };
+}

package/dist/version.d.ts

@@ -3,3 +3,8 @@
  * scaffolded dependency range (`^${version}`), so `init` must never fall back and scaffold an uninstallable `^0.0.0`.
  */
 export declare function fastagentVersion(): Promise<string>;
+/** This build's version, and the exact versions of the harness packages it runs, for a new agent to depend on. */
+export declare function fastagentBuild(): Promise<{
+    version: string;
+    harness: Record<string, string>;
+}>;