@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/scaffold/add-channel.js

@@ -1,13 +1,27 @@
 /**
- * `fastagent add <channel>`: drop a `channels/<kind>.ts` adapter-glue file (+ any companion tool, +
+ * `fastagent add <channel>`: drop a `src/channels/<kind>.ts` adapter-glue file (+ any companion tool, +
  * `.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, SECRET_FILE_MODE, assertInsideAgentDir, exists } from "../paths.js";
-import { baseTemplate, channelBundleFiles, channelTemplate } from "./templates.js";
-import { dotEnvPath, envExamplePath, parseEnvContent } from "../env.js";
+import { assertInsideAgentDir, exists } from "../paths.js";
+import { channelBundleFiles, channelTemplate } from "./templates.js";
+import { writeValues } from "../value-file.js";
+import { envExamplePath } from "../env.js";
+import { FEISHU_AGENT_SCOPES } from "../channels/feishu/setup-mode.js";
+import { slackBotScopes } from "../channels/slack/manifest.js";
+const AGENT_SCOPE_LIST = FEISHU_AGENT_SCOPES.map((entry) => entry.request).join(", ");
+const FEISHU_PERMISSION_STEP = `before publishing: the app needs ${AGENT_SCOPE_LIST} — \`add feishu\` requests them with the app and names any ` +
+    "your tenant withheld (approve those, then publish)";
+/** The setting both clouds read, said the same way in `.env.example` and in `add`'s next steps. */
+const ingressEnv = (prefix) => ({
+    name: `${prefix}_INGRESS`,
+    hint: "webhook | websocket — unset, `dev` connects by websocket, and `start` and every deployment receive by webhook",
+    required: false,
+});
+const LARK_PERMISSION_STEP = `before publishing: add ${AGENT_SCOPE_LIST} — \`add lark\` checks them and opens the permission page for any that ` +
+    "are missing";
 const CHANNEL_SCAFFOLDS = {
     telegram: {
         env: [
@@ -30,10 +44,11 @@ const CHANNEL_SCAFFOLDS = {
             { name: "SLACK_SIGNING_SECRET", hint: "Slack app → Basic Information → App Credentials", required: true },
         ],
         steps: [
-            "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write, channels:history, groups:history, mpim:history",
+            `Slack Bot Token Scopes: ${slackBotScopes().join(", ")}`,
             "enable Agents (agent_view) and leave token rotation OFF (it cannot be turned off again); subscribe app_home_opened, app_context_changed, app_mention, message.im, message.channels, message.groups, message.mpim; set Request URL to <public-url>/slack",
             "reinstall the app after changing scopes, then invite it to each channel it should read",
             "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
+            "the agent reads the threads of the channel it is asked in via the scaffolded {tools}/slack-threads.ts tool",
         ],
     },
     // Feishu is the canonical engine/cloud; Lark international reuses its protocol through a degraded compatibility
@@ -52,21 +67,23 @@ const CHANNEL_SCAFFOLDS = {
             },
             {
                 name: "FEISHU_VERIFICATION_TOKEN",
-                hint: "captured automatically (console → Events & Callbacks)",
+                hint: "webhook only (`start`, every deployment) — captured by `deploy --run` (console → Events & Callbacks)",
                 required: true,
             },
             {
                 name: "FEISHU_ENCRYPT_KEY",
-                hint: "optional but recommended — set one in the console and copy it here",
+                hint: "webhook only; optional but recommended — set one in the console and copy it here",
                 required: false,
             },
+            ingressEnv("FEISHU"),
         ],
         steps: [
-            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (the CLI adds it to the app draft when supported); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
+            FEISHU_PERMISSION_STEP,
             "PUBLISH the app version in the developer console after permission approval — the switch to webhook mode takes effect on publish (one click, once ever; no API for it)",
             "edit {channel} — routing policy (the header walks through the console setup, for hand-made apps)",
-            "the event Request URL is auto-registered by `dev --tunnel` / `deploy --run`",
+            "for webhook ingress, run `{serve} --tunnel` locally or `deploy --run` to register the selected app's event Request URL",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
+            "the agent reads the threads of the group it is asked in via the scaffolded {tools}/feishu-threads.ts tool",
         ],
     },
     lark: {
@@ -75,79 +92,63 @@ const CHANNEL_SCAFFOLDS = {
             { name: "LARK_APP_SECRET", hint: "developer console → Credentials & Basic Info", required: true },
             {
                 name: "LARK_VERIFICATION_TOKEN",
-                hint: "console → Events & Callbacks; authenticates inbound events",
+                hint: "webhook only (`start`, every deployment) — console → Events & Callbacks; authenticates inbound events",
                 required: true,
             },
             {
                 name: "LARK_ENCRYPT_KEY",
-                hint: "optional but recommended — set one in the console and copy it here",
+                hint: "webhook only; optional but recommended — set one in the console and copy it here",
                 required: false,
             },
+            ingressEnv("LARK"),
         ],
         steps: [
             "finish the console setup: enable Bot and add the required permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
-            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (add it manually if Lark's config API fallback was used); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
-            "run `fastagent dev --tunnel` and keep it running; if auto-registration reports a config-API 404, manually switch Subscription mode to webhook, set its printed https://…/lark Request URL, save, then create + publish a version",
+            LARK_PERMISSION_STEP,
+            "for webhook ingress, run `{serve} --tunnel` and keep it running; if auto-registration reports a config-API 404, manually switch Subscription mode to webhook, set its printed https://…/lark Request URL, save, then create + publish a version",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
+            "the agent reads the threads of the group it is asked in via the scaffolded {tools}/lark-threads.ts tool",
         ],
     },
 };
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
-const WEBSOCKET_SETUPS = {
-    feishu: {
-        env: CHANNEL_SCAFFOLDS.feishu.env.filter((entry) => ["FEISHU_APP_ID", "FEISHU_APP_SECRET"].includes(entry.name)),
+/** Local setup never changes the production app or ingress. */
+const deploymentStep = (kind, pinned) => pinned
+    ? `run \`{serve}\` (no tunnel needed: it connects by WebSocket); ${kind.toUpperCase()}_INGRESS=websocket is ` +
+        "set for this environment; production has its own app and ingress setting"
+    : "run `{serve}` (no tunnel needed: it connects by WebSocket); " +
+        "`deploy --run` creates a separate production app for webhook";
+const websocketSetup = (kind, pinned) => {
+    const prefix = kind.toUpperCase();
+    return {
+        env: CHANNEL_SCAFFOLDS[kind].env.filter((entry) => [`${prefix}_APP_ID`, `${prefix}_APP_SECRET`, `${prefix}_INGRESS`].includes(entry.name)),
         steps: [
-            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (the CLI adds it to the app draft when supported); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
-            "PUBLISH the app version in the developer console after permission approval — long-connection event subscriptions become active with the published version",
-            "edit {channel} — routing policy (the scaffold is already set to WebSocket ingress)",
-            "run `fastagent dev` without --tunnel; deployments must keep one process running (no scale-to-zero)",
-            "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
-        ],
-    },
-    lark: {
-        env: CHANNEL_SCAFFOLDS.lark.env.filter((entry) => ["LARK_APP_ID", "LARK_APP_SECRET"].includes(entry.name)),
-        steps: [
-            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (add it manually if Lark's config API fallback was used); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
-            "in Events & Callbacks choose long connection, subscribe im.message.receive_v1, then create + publish a version",
-            "edit {channel} — routing policy (the scaffold is already set to WebSocket ingress)",
-            "run `fastagent dev` without --tunnel; deployments must keep one process running (no scale-to-zero)",
-            "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
+            kind === "feishu" ? FEISHU_PERMISSION_STEP : LARK_PERMISSION_STEP,
+            kind === "feishu"
+                ? "PUBLISH the app version in the developer console after permission approval — long-connection event subscriptions become active with the published version"
+                : "in Events & Callbacks choose long connection, subscribe im.message.receive_v1, then create + publish a version",
+            "edit {channel} — routing policy",
+            deploymentStep(kind, pinned),
+            `the agent can push messages from scheduled turns via the scaffolded {tools}/${kind}-send.ts tool`,
+            `the agent reads the threads of the group it is asked in via the scaffolded {tools}/${kind}-threads.ts tool`,
         ],
-    },
+    };
 };
 /** The mode-specific env vars + next-step lines a scaffolded channel needs. */
-export function channelSetup(kind, ingress = "webhook", groupBehavior) {
-    const behavior = groupBehavior ?? "context";
-    const setup = ingress === "websocket" && (kind === "feishu" || kind === "lark")
-        ? WEBSOCKET_SETUPS[kind]
-        : CHANNEL_SCAFFOLDS[kind];
-    if ((kind === "feishu" || kind === "lark") && behavior === "mentions") {
-        return {
-            env: setup.env,
-            steps: setup.steps.map((step) => step.includes("im:message.group_msg")
-                ? "group behavior: mention-only — do not grant im:message.group_msg; bare thread replies and group context buffering remain disabled. im:message:readonly is independent of this choice: add it if you want an @mention to carry the message it quotes (without it that quote degrades to a marker)"
-                : step),
-        };
-    }
-    if (kind === "slack" && behavior === "mentions") {
-        return {
-            env: setup.env,
-            steps: [
-                "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write (no channel/group/mpim history scopes)",
-                "enable Agents (agent_view) and leave token rotation OFF (it cannot be turned off again); subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
-                "group behavior: mention-only — bare thread replies and unsummoned group context remain disabled",
-                ...setup.steps.slice(2),
-            ],
-        };
-    }
-    return { env: setup.env, steps: setup.steps };
+export function channelSetup(kind, ingress = "webhook", 
+/** Whether `<PREFIX>_INGRESS` is explicitly set in this environment. */
+pinned = false) {
+    if (ingress !== "websocket" || (kind !== "feishu" && kind !== "lark"))
+        return CHANNEL_SCAFFOLDS[kind];
+    return websocketSetup(kind, pinned);
 }
 /**
  * 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.
+ * `.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 async function appendChannelEnv(dir, kind, ingress = "webhook") {
+export async function appendChannelEnv(dir, kind) {
     const file = envExamplePath(dir);
     let current;
     try {
@@ -162,149 +163,50 @@ export async function appendChannelEnv(dir, kind, ingress = "webhook") {
     if (current.includes(marker))
         return false;
     // 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`;
+    const block = `\n${marker}\n${CHANNEL_SCAFFOLDS[kind].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`. */
-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));
-}
 /**
- * Append generated channel secrets to the agent's `.env` (`.secrets/.env` — never `.env.example`) Existing non-empty
- * values are kept.
+ * 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 async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
-    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);
-    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 env = channelSetup(kind, ingress).env;
-    const alreadySet = env
-        .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 env) {
-        if (alreadySet.includes(e.name))
-            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.
-            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}=${value}`;
-                replacedInPlace = true;
-            }
-            else {
-                lines.push(`${e.name}=${value}`);
-            }
-            written.push(e.name);
-        }
-        else if (!mentionsEnvName(current, e.name)) {
-            // 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, 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")}`), 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 };
+export function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
+    const entries = channelSetup(kind, ingress).env.map(({ name, hint }) => ({
+        name,
+        hint,
+        ...(generated[name] === undefined ? {} : { value: generated[name] }),
+    }));
+    return writeValues(dir, `${kind} channel`, entries, overwrite);
 }
 /** The path `add <kind>` scaffolds to. */
 function channelPath(dir, kind) {
-    return join(dir, "channels", `${kind}.ts`);
+    return join(dir, "src", "channels", `${kind}.ts`);
 }
 /** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
 export async function channelExists(dir, kind) {
     return exists(channelPath(dir, kind));
 }
-/** 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.
-    await assertInsideAgentDir(dir, "channels");
+/** Scaffold `src/channels/<kind>.ts` into {@link dir}. */
+export async function scaffoldChannel(dir, kind) {
+    const channelsDir = join(dir, "src", "channels");
+    // Don't write through a src/ symlink that escapes the agent dir; one inside it is fine.
+    await assertInsideAgentDir(dir, "src");
     const file = channelPath(dir, kind);
     if (await exists(file)) {
         throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
     }
     await mkdir(channelsDir, { recursive: true });
-    // 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, channelTemplate(kind, template), { flag: "wx" });
+    await writeFile(file, channelTemplate(kind, "channel.ts"), { flag: "wx" });
     return file;
 }
-/** The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). */
+/** The bundle's companion tools (every `.ts` beside `channel.ts` → `src/tools/<name>`). */
 export async function scaffoldCompanionTools(dir, kind) {
     const written = [];
     for (const name of channelBundleFiles(kind)) {
-        if (name.startsWith("channel."))
-            continue; // channel.ts / channel.websocket.ts are the channel, not tools
-        const file = join(dir, "tools", name);
+        if (name === "channel.ts")
+            continue; // the channel, not a tool
+        const file = join(dir, "src", "tools", name);
         await mkdir(dirname(file), { recursive: true });
         await writeFile(file, channelTemplate(kind, name));
         written.push(file);
@@ -326,7 +228,7 @@ export async function assertChannelReady(dir) {
             // `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 (\`init\` scaffolds one), ` +
-                `or run \`fastagent init\` in the workspace for a fresh agent`);
+                `or create a fresh agent with \`fastagent init <dir>\``);
         }
         throw e;
     }

package/dist/scaffold/init.d.ts

@@ -1,23 +1,22 @@
-/** 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.
- *
- * `"."` 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 {
-    /** The agent directory's name inside `dir` — default {@link DEFAULT_AGENT_DIRNAME}. */
-    agentDir?: string;
-}
 export interface ScaffoldResult {
+    /** The agent directory: `dir` itself. */
     dir: string;
-    /** 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[];
+    /** Remove what this run created, for a caller whose next step failed: the same rollback a failed write runs. */
+    undo(): Promise<void>;
 }
-/** Scaffold a runnable agent into `<dir>/<agentDir>/` (both created if missing). */
-export declare function scaffoldAgent(dir: string, options?: ScaffoldOptions): Promise<ScaffoldResult>;
+/**
+ * Scaffold a runnable agent INTO `dir`, which must be new or empty. An agent is a directory of its own: what it works
+ * on is declared, never the directory around it.
+ */
+export declare function scaffoldAgent(dir: string): Promise<ScaffoldResult>;
+/**
+ * Make the new agent a git repository whose first commit is what creating it wrote (`createAgent`, which `init` and a
+ * client both run). An agent changes itself, and version control is how its author goes back to a version that worked;
+ * the scaffolded `.gitignore` already keeps its instance (`.state`, `.secrets`, `content`) out. Returns a sentence to
+ * show: when there is no repository of its own or no first commit, it says which and why. The catches are this
+ * step's boundary: the agent is created either way, so a git that is missing or refuses becomes that sentence rather
+ * than a failed create.
+ */
+export declare function initRepository(dir: string): Promise<string>;

package/dist/scaffold/init.js

@@ -1,117 +1,78 @@
-/** Init: scaffold a runnable fastagent agent, offline. */
+/** Init: scaffold a runnable fastagent agent, offline, and make it a git repository of its own. */
 import { lstat, mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve, sep } from "node:path";
-import { AGENT_CONFIG_FILE, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, exists, } from "../paths.js";
+import { dirname, join, sep } from "node:path";
+import { AGENT_CONFIG_FILE, SECRETS_DIRNAME, displayPath, enclosingAgentDir } from "../paths.js";
 import { baseTemplate, packageJson, toPackageName } from "./templates.js";
-import { fastagentVersion } from "../version.js";
-/** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as `bot`. */
-export function agentDirName(raw) {
-    if (raw === undefined)
-        return DEFAULT_AGENT_DIRNAME;
-    const trimmed = raw.replace(/^\.[/\\]/, "");
-    return trimmed === "" ? raw : trimmed;
-}
+import { fastagentBuild } from "../version.js";
+import { GitNotInstalled, gitFor } from "../git.js";
+/** Entries a directory may hold and still count as empty. */
+const IGNORABLE = [".DS_Store", ".gitkeep", ".keep"];
 /**
- * Why `name` cannot be an agent directory name, or undefined when it can.
- *
- * `"."` 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.
+ * Scaffold a runnable agent INTO `dir`, which must be new or empty. An agent is a directory of its own: what it works
+ * on is declared, never the directory around it.
  */
-export function agentDirNameError(name) {
-    if (name !== "" && name !== "." && name !== ".." && name === basename(name))
-        return undefined;
-    return (`must be a single directory name — the definition lives in a subdirectory, and the directory around it is ` +
-        `the workspace the agent works on (a path, or ".", would put it elsewhere)`);
-}
-/** Scaffold a runnable agent into `<dir>/<agentDir>/` (both created if missing). */
-export async function scaffoldAgent(dir, options = {}) {
-    const root = agentDirName(options.agentDir);
-    const invalid = agentDirNameError(root);
-    if (invalid)
-        throw new Error(`agentDir "${root}" ${invalid}`);
+export async function scaffoldAgent(dir) {
     const skill = (name) => ({
-        rel: join(root, "skills", "writing-great-skills", name),
+        rel: join("skills", "writing-great-skills", name),
         content: baseTemplate(`skills/writing-great-skills/${name}`),
     });
     const files = [
-        // Standing instructions, added to pi's default prompt (SYSTEM.md would replace it).
-        { rel: join(root, "APPEND_SYSTEM.md"), content: baseTemplate("APPEND_SYSTEM.md") },
+        // Standing instructions: the agent's system prompt.
+        { rel: "SYSTEM.md", content: baseTemplate("SYSTEM.md") },
         // The example skill: how to author skills well — the core of self-iteration.
         skill("SKILL.md"),
         skill("GLOSSARY.md"),
         skill("LICENSE"),
-        { rel: join(root, AGENT_CONFIG_FILE), content: baseTemplate(AGENT_CONFIG_FILE) },
+        { rel: AGENT_CONFIG_FILE, content: baseTemplate(AGENT_CONFIG_FILE) },
         // Two ignore files, scaffolded ONCE and owned by the author from then on — no command rewrites, reads or verifies
         // them.
-        { rel: join(root, ".gitignore"), content: baseTemplate("gitignore") },
-        { rel: join(root, SECRETS_DIRNAME, ".gitignore"), content: baseTemplate("secrets.gitignore") },
-        { rel: join(root, SECRETS_DIRNAME, ".env.example"), content: baseTemplate("env.example") },
-        { rel: join(root, "tools", "fetch-url.ts"), content: baseTemplate("tools/fetch-url.ts") },
-        // The agent's own manifest, named after the directory it serves. Its `type: module` is why the definition gets a
-        // subdirectory of its own: a config file under a host repo's CommonJS manifest does not load.
-        {
-            rel: join(root, "package.json"),
-            content: packageJson(`${toPackageName(dir)}-agent`, await fastagentVersion()),
-        },
+        { rel: ".gitignore", content: baseTemplate("gitignore") },
+        { rel: join(SECRETS_DIRNAME, ".gitignore"), content: baseTemplate("secrets.gitignore") },
+        { rel: join(SECRETS_DIRNAME, ".env.example"), content: baseTemplate("env.example") },
+        // The agent's own manifest, named after its directory.
+        { rel: "package.json", content: packageJson(toPackageName(dir), await fastagentBuild()) },
     ];
-    // Inside another agent's DEFINITION (its `skills/`, `tools/`, `channels/` or `routines/`): the outer agent would
-    // load the new one as its own content.
-    const owner = agentDefinitionOwner(dir);
+    const shown = displayPath(process.cwd(), dir) ?? dir;
+    // Inside another agent: that agent's directory is its own definition and working directory, so the new one would be
+    // read as part of it.
+    const owner = enclosingAgentDir(dir);
     if (owner) {
-        throw new Error(`"${dir}" is inside the definition of the agent at ${owner} — an agent scaffolded here would be ` +
-            `part of THAT agent's surface, not one of its own. Init outside it.`);
-    }
-    // Preflight scaffold parent dirs FIRST: a pre-existing non-directory there would make mkdir fail mid-loop AFTER the
-    // first write, leaving a half-scaffold.
-    const parents = new Set();
-    for (const file of files) {
-        let p = dirname(file.rel);
-        while (p !== "." && p !== "") {
-            parents.add(p);
-            p = dirname(p);
-        }
-    }
-    for (const rel of parents) {
-        const st = await lstat(join(dir, rel)).catch(() => undefined);
-        if (st && !st.isDirectory()) {
-            throw new Error(`cannot scaffold: "${rel}" exists and is not a directory (a regular file or symlink) — remove it, or init elsewhere`);
-        }
+        throw new Error(`"${shown}" is inside the agent ${owner} — an agent is a directory of its own; create it outside that one`);
     }
-    // Refuse an occupied agent dir.
-    const occupants = (await readdir(join(dir, root)).catch((e) => {
+    const st = await lstat(dir).catch((e) => {
         if (e.code === "ENOENT")
-            return [];
+            return undefined;
         throw e;
-    })).filter((f) => ![".DS_Store", ".gitkeep", ".keep"].includes(f));
-    // Could `dir` still SELECT the agent this run creates?
-    const existing = agentsAt(dir).filter((a) => a !== resolve(dir, root));
-    const shadowed = existing.filter((a) => a === resolve(dir)); // an agent AT `dir` hides the new one inside it
-    if (shadowed.length > 0) {
-        throw new Error(`"${dir}" already resolves to ${shadowed.map((a) => displayPath(process.cwd(), a) ?? a).join(", ")} — ` +
-            `an agent scaffolded in ./${root}/ would be hidden by it and never served ` +
-            `from "${dir}" (an agent AT a directory wins over any inside it). Use that agent, move it away, ` +
-            `or init in a different directory.`);
-    }
-    // ONE coordinate system for both refusals — `displayPath` is the shared policy (relative inside the cwd, absolute
-    // when it climbs out).
-    const target = displayPath(process.cwd(), join(dir, root)) ?? join(dir, root);
+    });
+    if (st && !st.isDirectory())
+        throw new Error(`"${shown}" exists and is not a directory`);
+    const occupants = st ? (await readdir(dir)).filter((name) => !IGNORABLE.includes(name)) : [];
     if (occupants.includes(AGENT_CONFIG_FILE)) {
-        throw new Error(`"${target}" already has ${AGENT_CONFIG_FILE} — already a fastagent agent`);
+        throw new Error(`"${shown}" already has ${AGENT_CONFIG_FILE} — already a fastagent agent`);
     }
     if (occupants.length > 0) {
-        throw new Error(`"${target}" already holds ${occupants.join(", ")} — move it away first, or run ` +
-            `\`fastagent init\` in a different directory`);
+        throw new Error(`"${shown}" is not empty (it holds ${occupants.join(", ")}) — an agent lives in a directory of its own; to ` +
+            `have one work on this directory: \`fastagent init <new directory> --content ${displayPath(process.cwd(), dir) ?? "."}\``);
+    }
+    const parents = new Set();
+    for (const file of files) {
+        for (let p = dirname(file.rel); p !== "." && p !== ""; p = dirname(p))
+            parents.add(p);
     }
-    // Which directories were OURS to create?
-    const preexisting = new Set();
-    for (const rel of parents)
-        if (await exists(join(dir, rel)))
-            preexisting.add(rel);
-    const agentDirExisted = await exists(join(dir, root));
+    const dirExisted = st !== undefined;
     await mkdir(dir, { recursive: true });
     const created = [];
-    // ONE rollback scope: any failure removes what THIS run created — files AND the directories it made for them.
+    // ONE rollback: it removes what THIS run created — files AND the directories it made for them — and leaves a
+    // directory the caller handed over empty. Best-effort, because it runs while another failure is being reported.
+    const undo = async () => {
+        for (const rel of [...created].reverse())
+            await rm(join(dir, rel), { force: true }).catch(() => { });
+        for (const rel of [...parents].sort((a, b) => b.split(sep).length - a.split(sep).length)) {
+            await rmdir(join(dir, rel)).catch(() => { });
+        }
+        if (!dirExisted)
+            await rmdir(dir).catch(() => { });
+    };
     // `wx` so a collision is a failure: the target was checked empty above, so anything here appeared mid-run.
     try {
         for (const file of files) {
@@ -122,16 +83,43 @@ export async function scaffoldAgent(dir, options = {}) {
         }
     }
     catch (error) {
-        // Best-effort rollback of a partial scaffold.
-        for (const rel of created.reverse())
-            await rm(join(dir, rel), { force: true }).catch(() => { });
-        for (const rel of [...parents].sort((a, b) => b.split(sep).length - a.split(sep).length)) {
-            if (rel !== root && !preexisting.has(rel))
-                await rmdir(join(dir, rel)).catch(() => { });
-        }
-        if (!agentDirExisted)
-            await rmdir(join(dir, root)).catch(() => { });
+        await undo();
         throw error;
     }
-    return { dir, agentDir: root, created };
+    return { dir, created, undo };
+}
+const git = gitFor("no repository was created");
+/**
+ * Make the new agent a git repository whose first commit is what creating it wrote (`createAgent`, which `init` and a
+ * client both run). An agent changes itself, and version control is how its author goes back to a version that worked;
+ * the scaffolded `.gitignore` already keeps its instance (`.state`, `.secrets`, `content`) out. Returns a sentence to
+ * show: when there is no repository of its own or no first commit, it says which and why. The catches are this
+ * step's boundary: the agent is created either way, so a git that is missing or refuses becomes that sentence rather
+ * than a failed create.
+ */
+export async function initRepository(dir) {
+    const reason = (error) => error.message.split("\n")[0];
+    try {
+        // A directory another repository TRACKS is that repository's: a second one inside it would hide the agent's files
+        // from the first. One it ignores (a home directory kept in git with `*` ignored) tracks nothing, so the agent gets
+        // its own.
+        const enclosing = git.answer(["rev-parse", "--show-toplevel"], dir);
+        if (enclosing !== undefined && git.answer(["check-ignore", "-q", "."], dir) === undefined) {
+            return `inside the git repository ${enclosing}: it tracks the agent, so none was created`;
+        }
+        await git.run(["init", "--quiet"], dir);
+        await git.run(["add", "--all"], dir);
+    }
+    catch (error) {
+        if (error instanceof GitNotInstalled)
+            return error.message;
+        return `git could not create a repository: ${reason(error)}`;
+    }
+    try {
+        await git.run(["commit", "--quiet", "--message", "Create the agent with fastagent"], dir);
+    }
+    catch (error) {
+        return `created a git repository, but its first commit failed (${reason(error)}): commit the scaffold yourself`;
+    }
+    return "created a git repository, with the scaffold as its first commit";
 }