@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/proxy.js

@@ -1,23 +1,59 @@
-// Namespace import (not `import { install }`): Bun's `undici` is a native shim that omits `install`, and
-// a STATIC NAMED import of a missing export fails at link time — crashing `fastagent start` under Bun
-// before any code runs. A namespace import binds whatever exports exist; the Bun guard below then never
-// touches the Node-only members.
+// Namespace import (not `import { install }`): Bun's `undici` is a native shim that omits `install`, and a STATIC
+// NAMED import of a missing export fails at link time.
 import * as undici from "undici";
-/** The Bun runtime (`process.versions.bun` is set only there). Bun's native fetch already honors the
- *  proxy env vars and decompresses gzip, and its `undici` shim has no `install()` — so the Node-only
- *  undici wiring below is both unnecessary and unavailable there. */
+/** The Bun runtime (`process.versions.bun` is set only there). */
 const isBun = typeof process.versions.bun === "string";
 /**
- * Route fetch through HTTPS_PROXY and keep fetch + dispatcher on the SAME undici implementation. Any
- * process that hits a provider or a channel API needs this UNDER NODE: Node's fetch does not honor
- * HTTPS_PROXY by itself (so login's OAuth token exchange, model calls, and a webhook setWebhook would go
- * direct, bypassing a region proxy), and Node 26's bundled fetch skips gzip decompression without
- * install() (empty stopReason:"stop"). A process-global side effect — call it once at a command/entry
- * start. No-op under Bun, whose native fetch already does both (and lacks the undici entry points).
+ * What is ALWAYS exempt from the proxy. `EnvHttpProxyAgent` proxies EVERYTHING while NO_PROXY is empty — loopback
+ * included ("Always proxy if NO_PROXY is not set or empty") — so installing a proxy would otherwise send this process's
+ * own local traffic through it: a Docker health probe on 127.0.0.1, a control-plane call to a local serve, an `ssh -L`
+ * forward given to a control-plane client's `url`. None of those are what a proxy variable is asking for.
+ *
+ * APPENDED to a declared NO_PROXY rather than used as its default, because `NO_PROXY=.corp.com` is the normal shape of
+ * a corporate environment and it is not a statement about 127.0.0.1: replacing would hand exactly the users who have a
+ * proxy back the failure this exists to remove, as a probe timeout rather than an error.
+ */
+const LOOPBACK = "localhost,127.0.0.1,::1";
+/**
+ * The exemption list the dispatcher is built with: whatever the environment declares, plus {@link LOOPBACK}.
+ *
+ * Its own function because installing happens ONCE per process, so these branches are unreachable through
+ * {@link installProxyFetch} — and the wildcard one is the kind that is silently wrong until someone reads it.
+ */
+export function noProxyList(env = process.env) {
+    // Mirroring undici's own precedence (lowercase first) so our value cannot disagree with the one it would read.
+    // `||`, not `??`: a `NO_PROXY=` line in a .env is an empty string, and undici treats it as "proxy everything".
+    const declared = (env.no_proxy || env.NO_PROXY)?.trim();
+    if (!declared)
+        return LOOPBACK;
+    // `*` is undici's "never proxy anything", matched EXACTLY (`#noProxyValue === '*'`). Appending would demote it to a
+    // hostname that matches nothing — turning "disable the proxy" into "proxy everything but loopback".
+    return declared === "*" ? declared : `${declared},${LOOPBACK}`;
+}
+/** The install is process-global and once is enough; a second call would only leak the first dispatcher (nothing
+ *  closes it) and re-read the same environment. */
+let installed = false;
+/** Whoever owned `fetch` before this module loaded. A caller that replaced it since (a test's mock, an embedder's
+ *  instrumentation) meant it, so the swap below leaves it alone — the dispatcher still routes everything that runs
+ *  on undici's global. */
+const originalFetch = globalThis.fetch;
+/**
+ * Point this process's fetch at the proxy the environment declares, with loopback exempt by default.
+ *
+ * Two jobs in one, and both are needed UNDER NODE: Node's fetch does not honor HTTP(S)_PROXY at all, and Node 26's
+ * bundled fetch skips gzip decompression when it dispatches through npm undici (empty `stopReason:"stop"`), so fetch
+ * and the dispatcher must come from the SAME undici. No-op under Bun, whose native fetch already does both (and
+ * lacks these entry points).
+ *
+ * Call it through `enterAgentEnv` (env.ts) rather than directly: the proxy may be declared in the agent's own `.env`,
+ * so it has to be read first. The only direct callers are the ones with no agent directory to read.
  */
 export function installProxyFetch() {
-    if (isBun)
+    if (isBun || installed)
         return;
-    undici.setGlobalDispatcher(new undici.EnvHttpProxyAgent());
-    undici.install();
+    undici.setGlobalDispatcher(new undici.EnvHttpProxyAgent({ noProxy: noProxyList() }));
+    // Skipping `install` leaves the caller's fetch in place, and with it Node 26's missing gzip decompression above.
+    if (globalThis.fetch === originalFetch)
+        undici.install();
+    installed = true; // last: a throw above must leave the latch open, or the process runs un-proxied forever
 }

package/dist/runtime.d.ts

@@ -1,26 +1,32 @@
-/** How to install and run the AGENT: its package.json + lockfile decide, never the surrounding
- *  workspace's (whose toolchain is the agent's runtime concern, not fastagent's). */
+/**
+ * How to install and run the AGENT: its package.json + lockfile decide, never the surrounding workspace's (whose
+ * toolchain is the agent's runtime concern, not fastagent's).
+ */
 export interface AgentRuntime {
-    /** The JS runtime the agent targets — drives the generated Dockerfile base + install/run commands
-     *  and the package-manager hints in `init`/`add`. */
+    /**
+     * The JS runtime the agent targets — drives the generated Dockerfile base + install/run commands and the
+     * package-manager hints in `init`/`add`.
+     */
     runtime: "node" | "bun";
-    /** For `runtime: "bun"`, the version from package.json's `packageManager: "bun@x"` (undefined if a bun
-     *  lockfile made it bun but no version is pinned). */
+    /**
+     * For `runtime: "bun"`, the version from package.json's `packageManager: "bun@x"` (undefined if a bun lockfile made
+     * it bun but no version is pinned).
+     */
     bunVersion?: string;
     /** Whether the runtime's lockfile is present (package-lock.json for node, bun.lock/bun.lockb for bun). */
     hasLockfile: boolean;
 }
 /**
- * Detect which JS runtime an agent targets: `bun` when package.json's `packageManager` is `bun@…` OR a
- * bun lockfile (bun.lock/bun.lockb) is present, else `node`. `pkg` is the already-parsed package.json (or
- * `{}` when there is none / it is malformed). One source for the deploy Dockerfile and the CLI hints, so
- * they agree on what the agent is.
+ * Detect which JS runtime an agent targets: `bun` when package.json's `packageManager` is `bun@…` OR a bun lockfile
+ * (bun.lock/bun.lockb) is present, else `node`.
  */
 export declare function detectRuntime(dir: string, pkg: {
     packageManager?: unknown;
 }): AgentRuntime;
-/** Parse `<dir>/package.json`, or `{}` when absent/malformed (a real build surfaces the actual error).
- *  The already-parsed input to {@link detectRuntime} and the deploy dep/lockfile checks. */
+/**
+ * Parse `<dir>/package.json`, or `{}` when there is none (a markdown-only agent). A file that does not parse throws,
+ * naming itself: read as `{}` it became "does not list @fastagent-sh/fastagent" and an npm-based image, both wrong.
+ */
 export declare function readPackageJson(dir: string): Promise<{
     packageManager?: unknown;
     dependencies?: Record<string, unknown>;

package/dist/runtime.js

@@ -2,28 +2,35 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 /**
- * Detect which JS runtime an agent targets: `bun` when package.json's `packageManager` is `bun@…` OR a
- * bun lockfile (bun.lock/bun.lockb) is present, else `node`. `pkg` is the already-parsed package.json (or
- * `{}` when there is none / it is malformed). One source for the deploy Dockerfile and the CLI hints, so
- * they agree on what the agent is.
+ * Detect which JS runtime an agent targets: `bun` when package.json's `packageManager` is `bun@…` OR a bun lockfile
+ * (bun.lock/bun.lockb) is present, else `node`.
  */
 export function detectRuntime(dir, pkg) {
     const pm = typeof pkg.packageManager === "string" ? pkg.packageManager : "";
     const bunLock = existsSync(join(dir, "bun.lock")) || existsSync(join(dir, "bun.lockb"));
     if (pm.startsWith("bun@") || bunLock) {
-        // corepack pins as `bun@1.3.13+sha256.<hash>`; the version (a Docker tag for oven/bun) is the part
-        // BEFORE `+` — keeping the hash would build an invalid `FROM oven/bun:1.3.13+sha256…` tag.
+        // corepack pins as `bun@1.3.13+sha256.<hash>`; the version (a Docker tag for oven/bun) is the part BEFORE `+`.
         return { runtime: "bun", bunVersion: pm.match(/^bun@([^+]+)/)?.[1], hasLockfile: bunLock };
     }
     return { runtime: "node", hasLockfile: existsSync(join(dir, "package-lock.json")) };
 }
-/** Parse `<dir>/package.json`, or `{}` when absent/malformed (a real build surfaces the actual error).
- *  The already-parsed input to {@link detectRuntime} and the deploy dep/lockfile checks. */
+/**
+ * Parse `<dir>/package.json`, or `{}` when there is none (a markdown-only agent). A file that does not parse throws,
+ * naming itself: read as `{}` it became "does not list @fastagent-sh/fastagent" and an npm-based image, both wrong.
+ */
 export async function readPackageJson(dir) {
+    const path = join(dir, "package.json");
+    const raw = await readFile(path, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (raw === undefined)
+        return {};
     try {
-        return JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+        return JSON.parse(raw);
     }
-    catch {
-        return {};
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
     }
 }

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

@@ -1,19 +1,17 @@
 import type { FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
-export type ChannelKind = "github" | "telegram" | "slack" | "feishu" | "lark";
-/** Group-visibility choice shared by the slack/feishu/lark onboarding flows. Each channel keeps its
- * own channel-level type (`SlackGroupBehavior`, `FeishuGroupBehavior`) — this is the CLI-side value. */
+export type ChannelKind = "telegram" | "slack" | "feishu" | "lark";
+/** Group-visibility choice shared by the slack/feishu/lark onboarding flows. */
 export type GroupBehavior = "context" | "mentions";
-/** A resolved group-behavior decision plus whether the author actually chose it (flag or prompt).
- * A defaulted "context" (non-interactive, no flag) must never drive a sensitive-scope write. */
+/** A resolved group-behavior decision plus whether the author actually chose it (flag or prompt). */
 export interface GroupBehaviorChoice {
     behavior: GroupBehavior;
     explicit: boolean;
 }
-/** An env var a scaffolded channel reads. `generate` = a random-string secret the CLI can pre-fill. */
+/** An env var a scaffolded channel reads. */
 export interface ChannelEnv {
     name: string;
     hint: string;
-    /** Required for the channel to run. Optional values are deployed when present but never gate deploy. */
+    /** Required for the channel to run. */
     required: boolean;
     generate?: boolean;
 }
@@ -25,9 +23,8 @@ export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscrip
     steps: string[];
 };
 /**
- * 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. No-op when there is no `.env.example` or the block
- * is already present. Placeholders only — no real secret lands in the committable template.
+ * 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.
  */
 export declare function appendChannelEnv(dir: string, kind: ChannelKind, ingress?: FeishuSubscriptionMode): Promise<boolean>;
 export interface DotEnvWriteResult {
@@ -35,38 +32,24 @@ export interface DotEnvWriteResult {
     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`: a secret was just written into a directory fastagent does not own, so the caller
-     *  states the fact rather than dropping a `*`-ignoring file into someone else's path. */
+    /** Set when the secrets dir is an operator-chosen one (`FASTAGENT_SECRETS_DIR`) carrying no `.gitignore`. */
     unprotectedSecretsDir?: string;
 }
 /**
- * Append generated channel secrets to the agent's `.env` (`.secrets/.env` — never `.env.example`)
- * 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.
+ * Append generated channel secrets to the agent's `.env` (`.secrets/.env` — never `.env.example`) Existing non-empty
+ * values are kept.
  */
 export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[], ingress?: FeishuSubscriptionMode): 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>;
-/**
- * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
- * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
- */
+/** Scaffold `channels/<kind>.ts` into {@link dir}. */
 export declare function scaffoldChannel(dir: string, kind: ChannelKind, options?: {
     ingress?: FeishuSubscriptionMode;
 }): Promise<string>;
-/**
- * The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). Unlike the channel
- * file they are the package's, not authored glue, so they are written on EVERY add: re-running
- * `add <kind>` is how an upgraded tool reaches an existing agent.
- */
+/** The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). */
 export declare function scaffoldCompanionTools(dir: string, kind: ChannelKind): Promise<string[]>;
 /**
- * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares
- * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that
- * is `init`'s job.
+ * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares `@fastagent-sh/fastagent` (the
+ * channel file imports it).
  */
 export declare function assertChannelReady(dir: string): Promise<void>;

package/dist/scaffold/add-channel.js

@@ -1,32 +1,14 @@
 /**
  * `fastagent add <channel>`: drop a `channels/<kind>.ts` adapter-glue file (+ any companion tool, +
- * `.secrets/.env.example` vars) into an existing agent. `add` checks and guides; it never
- * bootstraps an agent (that is `init`'s job). Each channel's template files live in its own bundle
- * at src/channels/<kind>/scaffold/, read here at scaffold time.
+ * `.secrets/.env.example` vars) into an existing agent.
  */
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { detectRuntime } from "../runtime.js";
-import { SECRETS_DIRNAME, assertInsideAgentDir, ensureSecretsDir, exists } from "../paths.js";
+import { SECRETS_DIRNAME, SECRET_FILE_MODE, assertInsideAgentDir, exists } from "../paths.js";
 import { baseTemplate, channelBundleFiles, channelTemplate } from "./templates.js";
 import { dotEnvPath, envExamplePath, parseEnvContent } from "../env.js";
 const CHANNEL_SCAFFOLDS = {
-    github: {
-        env: [
-            {
-                name: "GITHUB_WEBHOOK_SECRET",
-                hint: "any random string; set the same value in the GitHub webhook",
-                required: true,
-                generate: true,
-            },
-        ],
-        // `{channel}` / `{tools}` are path placeholders the CLI resolves to the real agent-dir-relative
-        // location — the CLI holds no channel-private filenames.
-        steps: [
-            "edit {channel} — map events to intents in on()",
-            "add the webhook in your repo (Settings → Webhooks): Payload URL = <public-url>/webhook, content type application/json",
-        ],
-    },
     telegram: {
         env: [
             { name: "TELEGRAM_BOT_TOKEN", hint: "from @BotFather → /newbot", required: true },
@@ -54,11 +36,8 @@ const CHANNEL_SCAFFOLDS = {
             "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
         ],
     },
-    // Feishu is the canonical engine/cloud; Lark international reuses its protocol through a degraded
-    // compatibility profile. Each remains its own channel KIND: route, env, state, console, onboarding.
-    // This table is the webhook setup; continuous mode below selects only App ID/Secret. No `generate`
-    // in either: values come FROM the platform. `add feishu` scan-creates the app; Lark lacks that
-    // control-plane capability, so `add lark` guides console credential collection.
+    // Feishu is the canonical engine/cloud; Lark international reuses its protocol through a degraded compatibility
+    // profile.
     feishu: {
         env: [
             {
@@ -165,9 +144,8 @@ export function channelSetup(kind, ingress = "webhook", groupBehavior) {
     return { env: setup.env, steps: setup.steps };
 }
 /**
- * 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. No-op when there is no `.env.example` or the block
- * is already present. Placeholders only — no real secret lands in the committable template.
+ * 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.
  */
 export async function appendChannelEnv(dir, kind, ingress = "webhook") {
     const file = envExamplePath(dir);
@@ -183,19 +161,14 @@ export async function appendChannelEnv(dir, kind, ingress = "webhook") {
     const marker = `# --- ${kind} channel ---`;
     if (current.includes(marker))
         return false;
-    // Hint on its OWN line above the placeholder (like the base env.example template) — never inline
-    // after `=`: loadEnvFile does not strip trailing comments, so an uncommented `KEY=   # hint` (or a
-    // value pasted before the `#`) would carry the hint text into the parsed value.
+    // Hint on its OWN line above the placeholder (like the base env.example template).
     const block = `\n${marker}\n${channelSetup(kind, ingress)
         .env.map((e) => `# ${e.hint}\n# ${e.name}=`)
         .join("\n")}\n`;
     await appendFile(file, block);
     return true;
 }
-/** Whether `.env` content carries a non-empty ACTIVE value for `name` — decided by THE .env parser
- *  ({@link parseEnvContent}), not a re-implementation, so this check can never disagree with what
- *  `loadEnvFile` will actually read (a missed match here would append a second assignment that
- *  last-wins over the user's working secret). */
+/** Whether `.env` content carries a non-empty ACTIVE value for `name`. */
 function hasActiveEnvValue(content, name) {
     return (parseEnvContent(content).get(name)?.trim() ?? "") !== "";
 }
@@ -203,34 +176,19 @@ function mentionsEnvName(content, name) {
     return content.split("\n").some((line) => new RegExp(`^\\s*#?\\s*${name}\\s*=`).test(line));
 }
 /**
- * Append generated channel secrets to the agent's `.env` (`.secrets/.env` — never `.env.example`)
- * 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.
+ * Append generated channel secrets to the agent's `.env` (`.secrets/.env` — never `.env.example`) Existing non-empty
+ * values are kept.
  */
 export async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
     const file = dotEnvPath(dir);
     const secretsDir = dirname(file);
-    await ensureSecretsDir(secretsDir);
-    // THE one exception to "fastagent has no opinion about git": the directory it writes secrets into
-    // carries its own `.gitignore`. `init` writes it, and so does this — the reachable case where it is
-    // missing (a hand-made agent) is exactly the one where the next line mints an unrecoverable app
-    // secret. `wx`, so a file the author wrote is never touched; the accepted cost is that someone who
-    // DELETED it to track secrets deliberately gets it back once. The risk is not symmetric — that is an
-    // annoyance; the other way is a published credential.
-    //
-    // Scoped to the DEFAULT `<agentDir>/.secrets`, which is fastagent's own directory. A dir named by
-    // `FASTAGENT_SECRETS_DIR` belongs to the operator, and this template is `*` plus two negations —
-    // dropping it there would hide that directory's OTHER contents from their `git add`, which is a
-    // bigger harm than the one it prevents, and inflicted on a path they chose deliberately. They get the
-    // fact instead, and own the decision.
+    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);
     let unprotectedSecretsDir;
     if (owned) {
-        // Only EEXIST is tolerable (already protected, or a concurrent writer). A permission/disk failure on
-        // the file that keeps credentials out of git must surface, not be swallowed.
+        // 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;
@@ -260,10 +218,8 @@ export async function appendChannelDotEnv(dir, kind, generated, overwrite = [],
             continue;
         const value = generated[e.name];
         if (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: a new line written anywhere else either loses
-            // to it or wins by position under last-wins — both silently. Replace the LAST occurrence (the one
-            // the parser would honor). Line-level match uses THE parser, never a hand regex.
+            // 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)) {
@@ -281,24 +237,28 @@ export async function appendChannelDotEnv(dir, kind, generated, overwrite = [],
             written.push(e.name);
         }
         else if (!mentionsEnvName(current, e.name)) {
-            // Hint above, never inline after `=` — see appendChannelEnv (this IS the file loadEnvFile reads).
+            // Hint above, never inline after `=` — see appendChannelEnv (this IS the file loadDotEnv reads).
             lines.push(`# ${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);
+        await writeFile(file, current, secret);
     }
     if (lines.length > 0) {
         const marker = `# --- ${kind} channel ---`;
         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")}`));
+            // 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`);
+            await appendFile(file, `${prefix}${marker}\n${lines.join("\n")}\n`, secret);
         }
     }
     return { written, alreadySet, unprotectedSecretsDir };
@@ -311,10 +271,7 @@ function channelPath(dir, kind) {
 export async function channelExists(dir, kind) {
     return exists(channelPath(dir, kind));
 }
-/**
- * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
- * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
- */
+/** Scaffold `channels/<kind>.ts` into {@link dir}. */
 export async function scaffoldChannel(dir, kind, options = {}) {
     const channelsDir = join(dir, "channels");
     // Don't write through a channels/ symlink that escapes the agent dir; one inside it is fine.
@@ -324,48 +281,29 @@ export async function scaffoldChannel(dir, kind, options = {}) {
         throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
     }
     await mkdir(channelsDir, { recursive: true });
-    let content = channelTemplate(kind, "channel.ts");
-    if ((kind === "feishu" || kind === "lark") && options.ingress === "websocket") {
-        const factory = `${kind}Channel`;
-        const wsFactory = `${kind}WebSocketChannel`;
-        let configured = content
-            .replace(`import { ${factory} }`, `import { ${wsFactory} }`)
-            .replace(`export default ${factory}({`, `export default ${wsFactory}({`);
-        if (configured === content)
-            throw new Error(`${kind} channel template has no factory anchors`);
-        const prefix = kind === "feishu" ? "FEISHU" : "LARK";
-        const exportAt = configured.indexOf("export default");
-        const importEnd = configured.indexOf("\n\n");
-        if (exportAt < 0 || importEnd < 0)
-            throw new Error(`${kind} channel template header anchors are missing`);
-        const brand = kind === "feishu" ? "Feishu" : "Lark";
-        configured =
-            `${configured.slice(0, importEnd)}\n\n` +
-                `// ${brand} WebSocket long connection: the process connects OUT to the platform, so no public URL,\n` +
-                `// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long\n` +
-                `// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process\n` +
-                `// running in production: scale-to-zero/App Sleeping would disconnect ingress.\n` +
-                configured.slice(exportAt);
-        configured = configured
-            .split("\n")
-            .filter((line) => !line.includes(`verificationToken: process.env.${prefix}_VERIFICATION_TOKEN`) &&
-            !line.includes(`encryptKey: process.env.${prefix}_ENCRYPT_KEY`))
-            .join("\n");
-        content = configured;
+    // The long-connection variant is its own template FILE, not a transform of the webhook one: a transform
+    // has to be re-taught every time the template changes shape, and a missed anchor scaffolds a channel
+    // configured for the wrong ingress with nothing failing.
+    // Which templates exist is the BUNDLE's fact, asked here rather than assumed from the kind: only
+    // feishu/lark ship a long-connection variant today, and a caller asking for one that is missing
+    // must get that sentence, not the ENOENT of a path it never named.
+    const template = options.ingress === "websocket" ? "channel.websocket.ts" : "channel.ts";
+    // CHANNEL templates only: the bundle also holds companion tools (`telegram-send.ts`), and listing
+    // one as an available scaffold sends whoever reads this line looking for an ingress that is a tool.
+    const available = channelBundleFiles(kind).filter((f) => f.startsWith("channel."));
+    if (!available.includes(template)) {
+        throw new Error(`${kind} has no ${options.ingress ?? "webhook"} scaffold (${template} is not in its bundle) — ` +
+            `available: ${available.join(", ")}`);
     }
-    await writeFile(file, content, { flag: "wx" });
+    await writeFile(file, channelTemplate(kind, template), { flag: "wx" });
     return file;
 }
-/**
- * The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). Unlike the channel
- * file they are the package's, not authored glue, so they are written on EVERY add: re-running
- * `add <kind>` is how an upgraded tool reaches an existing agent.
- */
+/** The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). */
 export async function scaffoldCompanionTools(dir, kind) {
     const written = [];
     for (const name of channelBundleFiles(kind)) {
-        if (name === "channel.ts")
-            continue;
+        if (name.startsWith("channel."))
+            continue; // channel.ts / channel.websocket.ts are the channel, not tools
         const file = join(dir, "tools", name);
         await mkdir(dirname(file), { recursive: true });
         await writeFile(file, channelTemplate(kind, name));
@@ -374,9 +312,8 @@ export async function scaffoldCompanionTools(dir, kind) {
     return written;
 }
 /**
- * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares
- * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that
- * is `init`'s job.
+ * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares `@fastagent-sh/fastagent` (the
+ * channel file imports it).
  */
 export async function assertChannelReady(dir) {
     const pkgPath = join(dir, "package.json");
@@ -386,10 +323,9 @@ export async function assertChannelReady(dir) {
     }
     catch (e) {
         if (e.code === "ENOENT") {
-            // `dir` is the AGENT dir, so `fastagent init` here would nest a second agent inside it — the
-            // right remedy is the missing manifest (a --minimal init writes none), or init in the workspace.
+            // `dir` is the AGENT dir, so `fastagent init` here would nest a second agent inside it.
             throw new Error(`${dir}: no package.json — a channel adapter is code and needs the agent's own manifest. ` +
-                `Add a package.json declaring @fastagent-sh/fastagent there (a --minimal init writes none), ` +
+                `Add a package.json declaring @fastagent-sh/fastagent there (\`init\` scaffolds one), ` +
                 `or run \`fastagent init\` in the workspace for a fresh agent`);
         }
         throw e;

package/dist/scaffold/init.d.ts

@@ -1,45 +1,23 @@
-/** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as
- *  `bot` — `basename` already says that is what it means, so rejecting the spelling would be pedantry. */
+/** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as `bot`. */
 export declare function agentDirName(raw: string | undefined): string;
-/** Why `name` cannot be an agent directory name, or undefined when it can. It must stay ONE segment
- *  inside the target: anything else (a separator, `..`, an absolute path) would land the agent where the
- *  one-level lookup cannot see it — an agent nothing would ever serve.
+/**
+ * Why `name` cannot be an agent directory name, or undefined when it can.
  *
- *  Returns the CONSTRAINT, not a sentence: the CLI prefixes the flag it owns and reports it as the usage
- *  error it is (exit 2), while {@link scaffoldAgent} prefixes the option name for a programmatic caller,
- *  who never passed a flag and should not be told to fix one. */
+ * `"."` is refused along with every path: the definition always lands in a SUBDIRECTORY, and the directory around it
+ * is the workspace. The subdirectory also carries its own `package.json`, so a `fastagent.config.ts` never loads under
+ * the host repo's module settings.
+ */
 export declare function agentDirNameError(name: string): string | undefined;
 export interface ScaffoldOptions {
-    /** Scaffold the markdown-only unit (no package.json, no tool, no install) instead of a complete agent. */
-    minimal?: boolean;
-    /** The agent directory's name inside `dir` — default {@link DEFAULT_AGENT_DIRNAME}, `"."` for `dir`
-     *  itself. ONE path segment: a separator or `..` would put the agent outside the directory the author
-     *  named, where the one-level lookup could never find it. */
+    /** The agent directory's name inside `dir` — default {@link DEFAULT_AGENT_DIRNAME}. */
     agentDir?: string;
 }
 export interface ScaffoldResult {
     dir: string;
-    /** Whether a complete (code-tool) agent was scaffolded (false for --minimal). */
-    complete: boolean;
     /** The agent dir relative to `dir`: the {@link ScaffoldOptions.agentDir} that was used. */
     agentDir: string;
     /** Files written by this run (relative to `dir`). */
     created: string[];
-    /** Files that already existed and were KEPT untouched. Only reachable with `agentDir: "."` (a
-     *  subdirectory target is proven empty first): adopting a directory means its `.gitignore`/
-     *  `package.json` are the author's. The caller surfaces them — silently skipping a file the user
-     *  expected would be worse. */
-    kept: string[];
 }
-/**
- * Scaffold a runnable agent into `<dir>/<agentDir>/` — or into `dir` itself when `agentDir` is `"."`
- * (both created if missing). Default is a complete agent (persona.md + the writing-great-skills skill +
- * a code tool + package.json); `--minimal` drops the code tool and package.json.
- *
- * A SUBDIRECTORY target must be empty (any content there is an unfinished agent or something unrelated,
- * and landing persona.md beside it would be a silent mix), while `"."` is a directory being adopted —
- * content is expected. So `"."` KEEPS every file that already exists (reported, never overwritten, never
- * verified) and refuses only on a config, which means the directory is already an agent. An existing
- * AGENTS.md is untouched either way: that is the project's context, adopted as-is.
- */
+/** Scaffold a runnable agent into `<dir>/<agentDir>/` (both created if missing). */
 export declare function scaffoldAgent(dir: string, options?: ScaffoldOptions): Promise<ScaffoldResult>;