@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/mcp/sign-in.js

@@ -0,0 +1,204 @@
+/** Explicit browser OAuth for MCP; no auth URL, code or token passes through a model turn. */
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { agentValues } from "../value-file.js";
+import { declareMcp, mcpInstance, resolveMcpServers } from "./config.js";
+import { registerClient, startAuthorization, exchangeAuthorization, selectClientAuthMethod, validateAuthorizationResponseIssuer, } from "@modelcontextprotocol/client";
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Exit from "effect/Exit";
+import { port, portJoin, portCleanup, portError } from "../effect-port.js";
+import { McpError } from "../mcp-api.js";
+import { sendPage, setupRequestUrl, statusCard } from "../setup-page.js";
+import { discoverMcp, mcpFailure } from "./auth.js";
+import { mcpFetch, openMcpNetwork } from "./network.js";
+import { httpServer } from "./host.js";
+import { grantSummary } from "./grants.js";
+export async function signInMcp(request) {
+    const timeout = request.timeoutSeconds ?? 900;
+    if (!Number.isInteger(timeout) ||
+        timeout <= 0 ||
+        (request.callbackPort !== undefined &&
+            (!Number.isInteger(request.callbackPort) || request.callbackPort < 0 || request.callbackPort > 65535))) {
+        throw new McpError("configuration", "Invalid MCP sign-in timeout or callback port", request.server);
+    }
+    const dir = resolve(request.agentDir);
+    const server = httpServer(resolveMcpServers(declareMcp(dir, mcpInstance(request.config)), { ...process.env, ...agentValues(dir), ...request.variables }, request.server, dir, {}), request.server);
+    let saved;
+    const work = Effect.gen(function* () {
+        const network = yield* Effect.acquireRelease(port(() => openMcpNetwork(server.url, request.fetch)), (value) => portCleanup("MCP network", () => value.close()));
+        const fetchImpl = mcpFetch(server.url, network.fetch);
+        const discovery = yield* port(() => discoverMcp(server.url, fetchImpl));
+        if (!discovery.metadata.code_challenge_methods_supported?.includes("S256")) {
+            return yield* Effect.fail(new McpError("protocol", "MCP authorization server does not advertise PKCE S256", server.name));
+        }
+        if (!request.clientId && !discovery.metadata.registration_endpoint)
+            return yield* Effect.fail(new McpError("configuration", "This MCP service requires a public clientId or client metadata URL; dynamic registration is unavailable", server.name));
+        const scopes = [...new Set(request.scopes ?? discovery.resourceMetadata.scopes_supported ?? [])];
+        if (scopes.some((scope) => !/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)))
+            return yield* Effect.fail(new McpError("configuration", "Invalid OAuth scope", server.name));
+        const approved = yield* port(() => request.interaction.confirmAuthorization({
+            server: server.name,
+            resource: discovery.resource,
+            issuer: discovery.issuer,
+            scopes,
+        }));
+        if (!approved)
+            return yield* Effect.fail(new McpError("canceled", "MCP authorization canceled", server.name));
+        const callback = yield* Deferred.make();
+        const state = randomBytes(32).toString("base64url");
+        const path = request.clientId ? "/mcp/oauth/callback" : `/mcp/oauth/${randomBytes(24).toString("hex")}`;
+        let portNumber = 0;
+        let consumed = false;
+        const listener = createServer((incoming, response) => {
+            // This one-shot listener closes after sign-in; a later flow may bind the same callback port.
+            response.setHeader("connection", "close");
+            const url = setupRequestUrl(incoming, response);
+            if (!url)
+                return;
+            if (incoming.headers.host !== `127.0.0.1:${portNumber}` ||
+                incoming.method !== "GET" ||
+                url.pathname !== path ||
+                consumed) {
+                response.writeHead(404).end("not found\n");
+                return;
+            }
+            const received = url.searchParams.get("state") ?? "";
+            if (Buffer.byteLength(received) !== Buffer.byteLength(state) ||
+                !timingSafeEqual(Buffer.from(received), Buffer.from(state))) {
+                response.writeHead(400).end("invalid OAuth state\n");
+                return;
+            }
+            let problem;
+            try {
+                validateAuthorizationResponseIssuer({
+                    iss: url.searchParams.get("iss") ?? undefined,
+                    expectedIssuer: discovery.issuer,
+                    issParameterSupported: discovery.metadata.authorization_response_iss_parameter_supported === true,
+                });
+                if (url.searchParams.has("error"))
+                    problem = new McpError("canceled", "MCP authorization was not approved", server.name);
+                else if (!url.searchParams.get("code"))
+                    problem = new McpError("protocol", "MCP callback contained no authorization code", server.name);
+            }
+            catch {
+                problem = new McpError("authorization_mismatch", "MCP OAuth callback issuer mismatch", server.name);
+            }
+            consumed = true;
+            const completed = problem ? Deferred.fail(callback, problem) : Deferred.succeed(callback, url.searchParams);
+            // Closing the scope tears down the listener; first flush the page or observe the browser disconnect.
+            if (response.destroyed)
+                Effect.runSync(completed);
+            else
+                response.once("close", () => Effect.runSync(completed));
+            sendPage(response, problem ? 400 : 200, {
+                title: "MCP authorization — FastAgent",
+                card: statusCard({
+                    state: problem ? "failed" : "working",
+                    heading: problem ? "Authorization stopped" : "Authorization response received",
+                    lede: problem?.message ?? "FastAgent is verifying and saving the authorization.",
+                    next: "Return to your application or coding agent. Do not copy this address.",
+                }),
+            });
+        });
+        yield* Effect.acquireRelease(Effect.succeed(listener), (value) => portCleanup("MCP OAuth callback", () => new Promise((resolve, reject) => {
+            value.close((error) => (error ? reject(error) : resolve()));
+            value.closeAllConnections();
+        })));
+        yield* portJoin(() => new Promise((resolve, reject) => {
+            listener.once("error", reject);
+            listener.listen(request.callbackPort ?? 0, "127.0.0.1", () => {
+                listener.off("error", reject);
+                resolve();
+            });
+        }));
+        const address = listener.address();
+        if (!address || typeof address === "string")
+            return yield* Effect.fail(new McpError("connection", "MCP callback has no local port", server.name));
+        portNumber = address.port;
+        const redirectUrl = `http://127.0.0.1:${portNumber}${path}`;
+        const registration = request.clientId
+            ? { client_id: request.clientId }
+            : yield* portJoin(() => registerClient(discovery.issuer, {
+                metadata: discovery.metadata,
+                clientMetadata: {
+                    client_name: "FastAgent",
+                    redirect_uris: [redirectUrl],
+                    grant_types: ["authorization_code", "refresh_token"],
+                    response_types: ["code"],
+                    token_endpoint_auth_method: "none",
+                    application_type: "native",
+                    scope: scopes.join(" "),
+                },
+                scope: scopes.join(" "),
+                fetchFn: fetchImpl,
+            }));
+        const { authorizationUrl, codeVerifier } = yield* portJoin(() => startAuthorization(discovery.issuer, {
+            metadata: discovery.metadata,
+            clientInformation: registration,
+            state,
+            redirectUrl,
+            scope: scopes.join(" "),
+            resource: discovery.resource,
+        }));
+        request.interaction.notify({ type: "auth_url", url: authorizationUrl.href });
+        const params = yield* Deferred.await(callback);
+        // Redeeming a code can consume it. Finish the bounded exchange and durable save even if its waiter cancels.
+        return yield* Effect.uninterruptible(Effect.gen(function* () {
+            request.interaction.notify({ type: "progress", message: "Saving MCP authorization" });
+            const tokens = yield* portJoin(() => exchangeAuthorization(discovery.issuer, {
+                metadata: discovery.metadata,
+                clientInformation: registration,
+                authorizationCode: params.get("code"),
+                codeVerifier,
+                redirectUri: redirectUrl,
+                iss: params.get("iss") ?? undefined,
+                resource: discovery.resource,
+                fetchFn: fetchImpl,
+            }));
+            const granted = tokens.scope === undefined ? scopes : tokens.scope.split(/\s+/).filter(Boolean);
+            if (tokens.token_type.toLowerCase() !== "bearer" || granted.some((scope) => !scopes.includes(scope)))
+                return yield* Effect.fail(new McpError("insufficient_scope", "MCP authorization returned an unsupported token type or unapproved scopes", server.name));
+            const method = selectClientAuthMethod(registration, discovery.metadata.token_endpoint_auth_methods_supported ?? []);
+            if (method !== "none" && method !== "client_secret_post" && method !== "client_secret_basic")
+                return yield* Effect.fail(new McpError("protocol", "Unsupported MCP client authentication method", server.name));
+            const record = {
+                version: 1,
+                serverUrl: server.url,
+                resource: discovery.resource,
+                issuer: discovery.issuer,
+                client: {
+                    id: registration.client_id,
+                    tokenEndpointAuthMethod: method,
+                    ...("client_secret" in registration && registration.client_secret
+                        ? { secret: registration.client_secret }
+                        : {}),
+                },
+                scopes: granted,
+                status: "ready",
+                generation: 0,
+                accessToken: tokens.access_token,
+                ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+                ...(tokens.expires_in === undefined ? {} : { expiresAt: Date.now() + tokens.expires_in * 1000 }),
+            };
+            const id = randomUUID();
+            yield* portJoin(() => request.store.withGrant(id, async (access) => {
+                if (access.read())
+                    throw new McpError("storage", "MCP grant ID collision");
+                await access.write(record);
+            }));
+            saved = grantSummary(id, record);
+            return saved;
+        }));
+    }).pipe(Effect.timeout(timeout * 1000), Effect.scoped);
+    const result = await Effect.runPromiseExit(work, { signal: request.interaction.signal });
+    if (saved)
+        return saved;
+    if (Exit.isFailure(result)) {
+        if (Exit.hasInterrupts(result) || request.interaction.signal?.aborted)
+            throw new McpError("canceled", "MCP sign-in canceled", request.server);
+        throw mcpFailure(portError(result.cause), "MCP sign-in", request.server);
+    }
+    return result.value;
+}

package/dist/mcp-api.d.ts

@@ -0,0 +1,107 @@
+/** MCP authorization as an embedding host sees it. No SDK or harness types cross this boundary. */
+export type McpErrorCode = "configuration" | "authorization_required" | "authorization_mismatch" | "insufficient_scope" | "refresh_uncertain" | "canceled" | "connection" | "protocol" | "storage";
+export declare class McpError extends Error {
+    readonly code: McpErrorCode;
+    readonly server?: string;
+    constructor(code: McpErrorCode, message: string, server?: string);
+}
+export interface McpGrantRecord {
+    version: 1;
+    serverUrl: string;
+    resource: string;
+    issuer: string;
+    client: {
+        id: string;
+        secret?: string;
+        tokenEndpointAuthMethod: "none" | "client_secret_post" | "client_secret_basic";
+    };
+    scopes: readonly string[];
+    status: "ready" | "refreshing" | "reauthorization_required";
+    generation: number;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+}
+export interface McpGrantSummary {
+    id: string;
+    serverUrl: string;
+    resource: string;
+    issuer: string;
+    scopes: readonly string[];
+    status: McpGrantRecord["status"];
+    expiresAt?: number;
+}
+export interface McpGrantAccess {
+    read(): McpGrantRecord | undefined;
+    write(record: McpGrantRecord): Promise<void>;
+    remove(): Promise<void>;
+}
+export interface McpGrantStore {
+    read(grantId: string): Promise<McpGrantRecord | undefined>;
+    list(): Promise<readonly McpGrantSummary[]>;
+    /** Exclusive across all callers sharing storage. Each write is durable immediately, even if operation later throws. */
+    withGrant<T>(grantId: string, operation: (grant: McpGrantAccess) => Promise<T>): Promise<T>;
+}
+export interface McpAuthorization {
+    store: McpGrantStore;
+    bindings: Readonly<Record<string, string>>;
+}
+export interface McpOptions {
+    store?: McpGrantStore;
+    bindings?: Readonly<Record<string, string>>;
+    /** Per-instance interpolation values; never copied into process.env. */
+    variables?: Readonly<Record<string, string>>;
+    /** Trusted transport override: the host must enforce connection-level DNS/IP and redirect safety itself. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The instance configuration as far as MCP reads it: an object, or the absolute path of a `fastagent.json`. Its
+ * `mcpServers` add to the program's (`context.json`), and a name in both refuses.
+ */
+export type McpConfigInput = {
+    mcpServers?: Readonly<Record<string, unknown>>;
+    [key: string]: unknown;
+} | string;
+/** What `inspectMcp` is given beside the grants: the instance configuration whose servers it reads with the program's. */
+export interface McpInspectOptions extends McpOptions {
+    config?: McpConfigInput;
+}
+export interface McpServerSummary {
+    name: string;
+    transport: "stdio" | "http";
+    url?: string;
+    authorization: "not_required" | "not_bound" | "ready" | "refresh_needed" | "reauthorization_required" | "binding_mismatch";
+    grantId?: string;
+}
+export interface McpSignInInteraction {
+    signal?: AbortSignal;
+    confirmAuthorization(request: {
+        server: string;
+        resource: string;
+        issuer: string;
+        scopes: readonly string[];
+    }): Promise<boolean>;
+    notify(event: {
+        type: "auth_url";
+        url: string;
+    } | {
+        type: "progress";
+        message: string;
+    }): void;
+}
+export interface McpSignInRequest {
+    agentDir: string;
+    server: string;
+    store: McpGrantStore;
+    interaction: McpSignInInteraction;
+    scopes?: readonly string[];
+    /** Non-secret registration choices for servers that require a pre-registered public client. */
+    clientId?: string;
+    /** With clientId, register http://127.0.0.1:<port>/mcp/oauth/callback. */
+    callbackPort?: number;
+    timeoutSeconds?: number;
+    variables?: Readonly<Record<string, string>>;
+    fetch?: McpOptions["fetch"];
+    /** The instance configuration whose servers are read with the program's. */
+    config?: McpConfigInput;
+}

package/dist/mcp-api.js

@@ -0,0 +1,10 @@
+export class McpError extends Error {
+    code;
+    server;
+    constructor(code, message, server) {
+        super(server ? `${server}: ${message}` : message);
+        this.name = "McpError";
+        this.code = code;
+        this.server = server;
+    }
+}

package/dist/paths.d.ts

@@ -14,20 +14,20 @@ export declare function selectAgentEnvironment(environment: AgentEnvironment, en
 /** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
 export declare const STATE_DIRNAME = ".state";
 /**
- * Where fastagent clones the repositories `context.json` declares, `content/<name>` in the agent dir. Never an env
- * override: a machine that has a checkout of its own binds it in {@link LOCAL_CONTEXT_FILE} instead.
+ * Where fastagent clones the repositories an agent's content declares, `content/<name>` in the instance's working
+ * directory. Never an env override: a machine that has a checkout of its own adds it as a directory instead.
  */
 export declare const CONTENT_DIRNAME = "content";
 /** The agent's context declaration (`context.json`), beside its config: shared, so only what every instance reaches. */
 export declare const CONTEXT_FILE = "context.json";
-/** The directories of THIS machine the agent is bound to: never committed, never deployed. */
-export declare const LOCAL_CONTEXT_FILE = "context.local.json";
 /**
  * THE config filename. One spelling, not a family: fastagent generates this file, so a choice of extension buys
  * an author nothing and costs a precedence order plus a "you have two of them" failure path. Everything else an
  * author writes (`tools/`, `channels/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
  */
 export declare const AGENT_CONFIG_FILE = "fastagent.config.ts";
+/** The instance configuration a development project holds beside its `fastagent.config.ts`. */
+export declare const INSTANCE_CONFIG_FILE = "fastagent.json";
 /** The agent `dir` sits INSIDE (the nearest proper ancestor that IS an agent dir), or undefined. */
 export declare function enclosingAgentDir(dir: string): string | undefined;
 /**
@@ -50,10 +50,24 @@ export declare function readTextIfExists(p: string): Promise<string | undefined>
  */
 export declare function resolveOverridePath(raw: string | undefined): string | undefined;
 /**
- * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
- * Explicit paths win; production otherwise uses `.state/production`, dev uses `.state`.
+ * A path as an instance configuration writes it, absolute: `~/` is the home directory, a relative one is `base`'s (the
+ * configuration file's directory). Undefined for a relative one when there is no file to anchor it.
+ */
+export declare function configurationPath(path: string, base: string | undefined): string | undefined;
+/** Where an instance is, from the environment: the root, or its state and its workspace apart (agent-artifact.md §4.1). */
+export declare const INSTANCE_ROOT_ENV = "FASTAGENT_ROOT";
+export declare const INSTANCE_WORKDIR_ENV = "FASTAGENT_WORKDIR";
+export declare const INSTANCE_STATE_ENV = "FASTAGENT_STATE_DIR";
+export declare const INSTANCE_CONFIG_ENV = "FASTAGENT_CONFIG";
+/** Where fastagent keeps what it makes for a local instance of the project in `dir`, one directory per environment. */
+export declare const INSTANCES_DIRNAME = ".fastagent";
+/**
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/): the state
+ * directory, else `.state` in the instance root, which is the project's default one when none is given.
  */
 export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
+/** The agent's working directory: the workspace directory, else the instance root, which is the project's default one. */
+export declare function resolveWorkdir(dir: string, env?: NodeJS.ProcessEnv): string;
 /** Where fastagent clones the content entry `name` of the agent in `dir`. */
 export declare function contentEntryPath(dir: string, name: string): string;
 /**
@@ -63,9 +77,9 @@ export declare function contentEntryPath(dir: string, name: string): string;
 export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
 /** Is this process the deployed container the generated artifacts describe? ONE reading of the
  *  environment fact the image states, so a second spelling cannot drift from it. */
-export declare function isDeployedWorkspace(): boolean;
+export declare function isDeployedWorkspace(env?: NodeJS.ProcessEnv): boolean;
 /** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
-export declare function isAgentcoreRuntime(): boolean;
+export declare function isAgentcoreRuntime(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Which host this deployed box runs on, for the command that logs it in (`login --deployment <host>`). Read from what
  * each platform puts in a box's environment (`FLY_APP_NAME`, `RAILWAY_SERVICE_ID`) or what our AgentCore template

package/dist/paths.js

@@ -29,20 +29,20 @@ function environmentPath(dir, segment, env) {
 /** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
 export const STATE_DIRNAME = ".state";
 /**
- * Where fastagent clones the repositories `context.json` declares, `content/<name>` in the agent dir. Never an env
- * override: a machine that has a checkout of its own binds it in {@link LOCAL_CONTEXT_FILE} instead.
+ * Where fastagent clones the repositories an agent's content declares, `content/<name>` in the instance's working
+ * directory. Never an env override: a machine that has a checkout of its own adds it as a directory instead.
  */
 export const CONTENT_DIRNAME = "content";
 /** The agent's context declaration (`context.json`), beside its config: shared, so only what every instance reaches. */
 export const CONTEXT_FILE = "context.json";
-/** The directories of THIS machine the agent is bound to: never committed, never deployed. */
-export const LOCAL_CONTEXT_FILE = "context.local.json";
 /**
  * THE config filename. One spelling, not a family: fastagent generates this file, so a choice of extension buys
  * an author nothing and costs a precedence order plus a "you have two of them" failure path. Everything else an
  * author writes (`tools/`, `channels/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
  */
 export const AGENT_CONFIG_FILE = "fastagent.config.ts";
+/** The instance configuration a development project holds beside its `fastagent.config.ts`. */
+export const INSTANCE_CONFIG_FILE = "fastagent.json";
 /**
  * "Not there" and "could not look" are different answers, and only the first may read as an absence: an agent
  * directory the caller cannot enter (EACCES) reported as no-agent-here ends in `run \`fastagent init\`` — over a
@@ -131,11 +131,44 @@ export function resolveOverridePath(raw) {
     return resolve(expanded);
 }
 /**
- * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
- * Explicit paths win; production otherwise uses `.state/production`, dev uses `.state`.
+ * A path as an instance configuration writes it, absolute: `~/` is the home directory, a relative one is `base`'s (the
+ * configuration file's directory). Undefined for a relative one when there is no file to anchor it.
+ */
+export function configurationPath(path, base) {
+    if (path === "~" || path.startsWith("~/"))
+        return join(homedir(), path.slice(1));
+    if (isAbsolute(path))
+        return resolve(path);
+    return base === undefined ? undefined : resolve(base, path);
+}
+/** Where an instance is, from the environment: the root, or its state and its workspace apart (agent-artifact.md §4.1). */
+export const INSTANCE_ROOT_ENV = "FASTAGENT_ROOT";
+export const INSTANCE_WORKDIR_ENV = "FASTAGENT_WORKDIR";
+export const INSTANCE_STATE_ENV = "FASTAGENT_STATE_DIR";
+export const INSTANCE_CONFIG_ENV = "FASTAGENT_CONFIG";
+/** Where fastagent keeps what it makes for a local instance of the project in `dir`, one directory per environment. */
+export const INSTANCES_DIRNAME = ".fastagent";
+/**
+ * The instance root of the project in `dir` when none is given (agent-artifact.md §4.1): `.fastagent/dev/` for `dev`,
+ * and `.fastagent/start/` for the commands that run what `start` runs, kept apart so a trial of the production build
+ * never reads or writes the development sessions and clones.
+ */
+function defaultInstanceRoot(dir, env) {
+    return join(resolve(dir), INSTANCES_DIRNAME, env[AGENT_ENVIRONMENT_ENV] === "production" ? "start" : "dev");
+}
+/**
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/): the state
+ * directory, else `.state` in the instance root, which is the project's default one when none is given.
  */
 export function resolveStateRoot(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? environmentPath(dir, STATE_DIRNAME, env);
+    return (resolveOverridePath(env[INSTANCE_STATE_ENV]) ??
+        join(resolveOverridePath(env[INSTANCE_ROOT_ENV]) ?? defaultInstanceRoot(dir, env), STATE_DIRNAME));
+}
+/** The agent's working directory: the workspace directory, else the instance root, which is the project's default one. */
+export function resolveWorkdir(dir, env = process.env) {
+    return (resolveOverridePath(env[INSTANCE_WORKDIR_ENV]) ??
+        resolveOverridePath(env[INSTANCE_ROOT_ENV]) ??
+        defaultInstanceRoot(dir, env));
 }
 /** Where fastagent clones the content entry `name` of the agent in `dir`. */
 export function contentEntryPath(dir, name) {
@@ -150,12 +183,12 @@ export function resolveSecretsDir(dir, env = process.env) {
 }
 /** Is this process the deployed container the generated artifacts describe? ONE reading of the
  *  environment fact the image states, so a second spelling cannot drift from it. */
-export function isDeployedWorkspace() {
-    return Boolean(process.env.FASTAGENT_RELEASE_FILE);
+export function isDeployedWorkspace(env = process.env) {
+    return Boolean(env.FASTAGENT_RELEASE_FILE);
 }
 /** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
-export function isAgentcoreRuntime() {
-    return process.env.FASTAGENT_AGENTCORE === "1";
+export function isAgentcoreRuntime(env = process.env) {
+    return env.FASTAGENT_AGENTCORE === "1";
 }
 /**
  * Which host this deployed box runs on, for the command that logs it in (`login --deployment <host>`). Read from what

package/dist/runtime-websocket.d.ts

@@ -0,0 +1,14 @@
+import * as undici from "undici";
+export declare const RuntimeWebSocket: {
+    new (url: string | URL, protocols?: string | string[] | undici.WebSocketInit): undici.WebSocket;
+    prototype: undici.WebSocket;
+    readonly CLOSED: number;
+    readonly CLOSING: number;
+    readonly CONNECTING: number;
+    readonly OPEN: number;
+};
+export type RuntimeWebSocket = InstanceType<typeof RuntimeWebSocket>;
+/** Send a ping on `socket`, or `undefined` when this runtime cannot. */
+export declare function pinger(socket: RuntimeWebSocket): (() => void) | undefined;
+/** Call `onPong` for each pong `socket` receives. Returns what stops it. */
+export declare function watchPongs(socket: RuntimeWebSocket, onPong: () => void): () => void;

package/dist/runtime-websocket.js

@@ -0,0 +1,39 @@
+/**
+ * The runtime's own WebSocket and the pings it can send, for the two places that hold a WebSocket open against a
+ * service that drops one nobody pings: Slack's Socket Mode and AgentCore's command shell.
+ *
+ * Node's undici sends a ping with `undici.ping` and reports the pong on a diagnostics channel; Bun 1.4.4 and later has
+ * both in its `undici` shim. Before that the shim has no `ping` and its WebSocket is the runtime's own, which pings with
+ * its `ping()` and reports a `pong` event. A runtime with neither has no pings: `pinger` says so, and the caller decides.
+ *
+ * A namespace import, because Bun's `undici` is a shim that leaves out what it does not have, and a named import of a
+ * missing export fails the whole module's link.
+ */
+import { channel } from "node:diagnostics_channel";
+import * as undici from "undici";
+export const RuntimeWebSocket = undici.WebSocket ?? globalThis.WebSocket;
+const undiciPings = undici.WebSocket !== undefined && typeof undici.ping === "function";
+const nativePing = (socket) => socket.ping;
+/** Send a ping on `socket`, or `undefined` when this runtime cannot. */
+export function pinger(socket) {
+    if (undiciPings)
+        return () => undici.ping(socket);
+    return typeof nativePing(socket) === "function" ? () => nativePing(socket)?.call(socket) : undefined;
+}
+/** Call `onPong` for each pong `socket` receives. Returns what stops it. */
+export function watchPongs(socket, onPong) {
+    if (undiciPings) {
+        const pongs = channel("undici:websocket:pong");
+        const listener = (message) => {
+            if (message.websocket === socket)
+                onPong();
+        };
+        pongs.subscribe(listener);
+        return () => pongs.unsubscribe(listener);
+    }
+    if (typeof nativePing(socket) !== "function")
+        return () => { };
+    const listener = () => onPong();
+    socket.addEventListener("pong", listener);
+    return () => socket.removeEventListener("pong", listener);
+}

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

@@ -1,34 +1,26 @@
-import { type ValueWriteResult } from "../value-file.ts";
-import { type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
 export type ChannelKind = "telegram" | "slack" | "feishu" | "lark";
 /** An env var a scaffolded channel reads. */
-export interface ChannelEnv {
+interface ChannelEnv {
     name: string;
     hint: string;
     /** Required for the channel to run. */
     required: boolean;
-    generate?: boolean;
 }
-/** The channel kinds `fastagent add <kind>` can scaffold. */
-export declare const CHANNEL_KINDS: ChannelKind[];
-/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
-export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscriptionMode, 
-/** Whether `<PREFIX>_INGRESS` is explicitly set in this environment. */
-pinned?: boolean): {
+interface ChannelScaffold {
     env: ChannelEnv[];
+    /** Channel instructions with paths and the serving command filled by the CLI. */
     steps: string[];
-};
+}
+/** The channel kinds `fastagent add <kind>` can scaffold. */
+export declare const CHANNEL_KINDS: ChannelKind[];
+/** The env vars and next-step lines a scaffolded channel has. */
+export declare function channelSetup(kind: ChannelKind): ChannelScaffold;
 /**
  * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who copies it to
  * `.env` finds the vars already there. Every var the channel can declare, whichever way this machine receives it:
  * the file is what a collaborator or CI fills for a deployment, which receives Feishu/Lark by webhook.
  */
 export declare function appendChannelEnv(dir: string, kind: ChannelKind): Promise<boolean>;
-/**
- * Append generated channel secrets to the selected environment's value file, and a placeholder for each the channel
- * reads that nothing generated. Existing non-empty values are kept.
- */
-export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[], ingress?: FeishuSubscriptionMode): Promise<ValueWriteResult>;
 /** 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>;
 /** Scaffold `src/channels/<kind>.ts` into {@link dir}. */
@@ -40,3 +32,4 @@ export declare function scaffoldCompanionTools(dir: string, kind: ChannelKind):
  * channel file imports it).
  */
 export declare function assertChannelReady(dir: string): Promise<void>;
+export {};