@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/paths.js

@@ -0,0 +1,326 @@
+/**
+ * PLACEMENT: which directory holds the agent, and which directory the agent works ON — plus the
+ * machinery paths that follow from it.
+ *
+ * ONE marker and ONE rule. `fastagent.config.*` declares an agent; the WORKSPACE is the directory you
+ * pointed fastagent at. Nothing here reads a directory NAME, so an agent directory can be called
+ * anything — and the same tree answers two ways depending on where you aim it: point at the project and
+ * the agent directory inside it answers with the project as its workspace; point at the agent directory
+ * itself (all a container may have been shipped) and it works on itself. That is not an ambiguity to
+ * resolve but the honest answer — an agent alone on a box has no project to work on, and a rule that
+ * insisted otherwise would hand it the container root.
+ *
+ * Engine-neutral by nature (pure fs/path: existence checks and one shallow scan), so it lives here
+ * rather than under engines/pi. Not a filing preference: the scaffold, the deploy planners, the dev
+ * watcher and env.ts all need these facts, and routing them through the engine would make neutral
+ * modules depend on it for something the engine has no say in.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+/**
+ * The directory name `init` gives a nested agent (`<workspace>/fastagent/`) unless `--agent-dir` names
+ * another. A DEFAULT, not a rule: resolution reads the config marker and never a name, so renaming an
+ * agent directory changes nothing about how it resolves. Visible on purpose — the agent directory holds
+ * the AUTHOR's content (persona, skills, tool code: code, not tool configuration), so it follows the
+ * repo convention for code (a plain directory), while fastagent's own machinery inside it (`.secrets/`,
+ * `.state/`) keeps the dot prefix.
+ */
+export const DEFAULT_AGENT_DIRNAME = "fastagent";
+/** The user-global machinery home under `$HOME` — hidden, per the dotfile convention for per-user
+ *  tool homes (`~/.cargo`, `~/.docker`); unrelated to {@link DEFAULT_AGENT_DIRNAME}, which only names
+ *  what `init` creates.
+ *  It carries the same shape inside it as an agent dir does (`~/.fastagent/.secrets/auth.json`), so the
+ *  resolvers below need no special case: `login` outside any agent simply hands them this directory. */
+export const GLOBAL_HOME_DIR = ".fastagent";
+/** The secrets segment inside an agent dir (or the global home): every PATH fastagent resolves —
+ *  `.env`, `.env.example`, auth.json, the scaffold's write — derives from it, so they cannot drift
+ *  apart. `FASTAGENT_SECRETS_DIR` relocates the RESOLVED dir ({@link resolveSecretsDir}), never this
+ *  name. The scaffold's ignore templates are real files the author owns from `init` on, so they spell
+ *  their rules out as literal text — renaming this constant means editing them too. */
+export const SECRETS_DIRNAME = ".secrets";
+/** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
+export const STATE_DIRNAME = ".state";
+/** The config filenames, in load precedence. ONE source: the loader (below) and `scaffoldAgent`'s
+ *  already-an-agent refusal both read this, so "is there a config?" can't diverge between them. */
+export const AGENT_CONFIG_NAMES = ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+/** The definition paths an agent LOADS content from — the surface a second agent must not be scaffolded
+ *  inside ({@link agentDefinitionOwner}), because the outer agent would read it as its own skills/tools.
+ *  NOT evidence of an agent: `tools/` and `skills/` are ordinary names half the world's repositories
+ *  use, and the config is the only marker. */
+const LOADED_SURFACE = ["persona.md", "skills", "tools", "channels", "schedules"];
+function isDir(p) {
+    return statSync(p, { throwIfNoEntry: false })?.isDirectory() === true;
+}
+/** THE marker: a directory that declares itself an agent with a `fastagent.config.*`. One file decides
+ *  it, at every position — which is why an agent directory needs no reserved name and why there is no
+ *  zero-config agent. */
+function hasConfig(p) {
+    return isDir(p) && AGENT_CONFIG_NAMES.some((name) => existsSync(join(p, name)));
+}
+/** The agent directories DIRECTLY inside `dir` — the one-level scan that finds an agent without knowing
+ *  its name. ONE level: deeper is that directory's own workspace, not this one's agent. Sorted, so a
+ *  refusal names them in a stable order. A missing `dir` yields none (callers resolve paths that may not
+ *  exist); a permission fault surfaces. */
+function agentChildren(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return [];
+        throw e;
+    }
+    return entries
+        .filter((e) => !e.isFile() && hasConfig(join(dir, e.name)))
+        .map((e) => join(dir, e.name))
+        .sort();
+}
+/**
+ * The agents `dir` resolves over: ITSELF when it holds a config, else the ones directly inside it —
+ * never both, because aiming at an agent can only mean that agent. Exported for `init`, which asks the
+ * same question this lookup asks: which agents would `dir` resolve over, before and after scaffolding.
+ */
+export function agentsAt(dir) {
+    const base = resolve(dir);
+    return hasConfig(base) ? [base] : agentChildren(base);
+}
+/**
+ * WHICH agent is meant, when a directory holds several: an engineer's, a PM's and a content owner's
+ * agent can each drive the same repository, so they must be selectable rather than refused.
+ *
+ * `FASTAGENT_AGENT` reaches this from the REAL environment only. Placement resolves before anything
+ * reads the agent's `.env` — it is what tells the loader which agent's `.env` to read — so a value set
+ * there is a silent no-op (the same ordering caveat `FASTAGENT_SECRETS_DIR` carries). A shell, an
+ * `.envrc`, or the command itself.
+ *
+ * It is an ASSERTION, not a preference: it names the agent, and a directory without one
+ * by that name resolves to nothing — even when exactly one agent is sitting there. Serving a DIFFERENT
+ * agent than the one asked for is the silent-wrong-target this codebase refuses everywhere else, and the
+ * uniform rule ("it names the agent") beats one that changes meaning with the sibling count. The stated
+ * cost: a `FASTAGENT_AGENT` exported in a shell PROFILE refuses in every unrelated directory it travels
+ * into. Scope it per-repo (an `.envrc`) or pass it per-command; the refusal names the way out.
+ *
+ * With nothing asserted, the {@link DEFAULT_AGENT_DIRNAME} breaks the tie. That is the one place a
+ * directory NAME carries weight, and deliberately not an identity rule — the config alone says what IS
+ * an agent; the name only decides which already-identified one answers. What it buys: adding a second
+ * agent to a working `<workspace>/fastagent/` setup does not break the command everyone already types.
+ */
+function selectAgent(agents, env) {
+    const wanted = env.FASTAGENT_AGENT;
+    if (wanted)
+        return agents.find((a) => basename(a) === wanted);
+    const [only, ...rest] = agents;
+    return rest.length === 0 ? only : agents.find((a) => basename(a) === DEFAULT_AGENT_DIRNAME);
+}
+/**
+ * Resolve `dir` into its placement, or undefined when nothing selects one agent. The whole rule: `dir`
+ * is the WORKSPACE, and the agent is a `fastagent.config.*` holder at it or one level inside
+ * ({@link agentsAt}), narrowed by {@link selectAgent} when there are several.
+ */
+function findPlacement(dir, env = process.env) {
+    const base = resolve(dir);
+    const agentDir = selectAgent(agentsAt(base), env);
+    return agentDir === undefined ? undefined : { agentDir, workspace: base };
+}
+/**
+ * The one-line hint for "you pointed at the agent, but the project around it is what you meant" — or
+ * undefined. The workspace being whatever you aimed at is deliberate (a deployed box may hold nothing
+ * but the agent), and the cost is that `cd my-agent && fastagent dev` legitimately narrows the agent's
+ * WORKSPACE to its own directory: its cwd, its coding tools' root, and deploy's build context. (②
+ * context is not affected — that walk climbs ancestors either way.) Resolution must not guess which you
+ * wanted, so this is a HINT — and a hint may use the heuristic ("the parent carries an AGENTS.md or a
+ * .git") that a rule may not.
+ *
+ * It suggests a command only after RUNNING the lookup that command would run, because a hint that dead-ends
+ * is worse than none: with several agents beside this one, `..` refuses and names them — sending the
+ * reader to a refusal whose own advice points back here.
+ */
+export function workspaceHint({ agentDir, workspace }, env = process.env) {
+    if (agentDir !== workspace)
+        return undefined;
+    const parent = dirname(agentDir);
+    if (parent === agentDir)
+        return undefined;
+    // Would `..` actually serve THIS agent? A parent holding a config is an agent itself, and one holding
+    // siblings resolves to none without a selector — neither is the project view asked about here.
+    if (findPlacement(parent, env)?.agentDir !== agentDir)
+        return undefined;
+    if (!["AGENTS.md", ".git"].some((name) => existsSync(join(parent, name))))
+        return undefined;
+    return `${parent} looks like a project — point fastagent at it (\`..\`) to have the agent work ON it`;
+}
+/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair,
+ *  and without the throw. `login` is the caller: it is the one command allowed to run outside an agent,
+ *  so it needs the answer as a value rather than as a refusal. */
+export function findAgentDir(dir) {
+    return findPlacement(dir)?.agentDir;
+}
+/** The agent `dir` sits INSIDE (the nearest proper ancestor that IS an agent dir), or undefined.
+ *  Module-private: the two questions callers actually ask are "where do I `cd` to?"
+ *  ({@link placementDeadEnd}) and "would a new agent here become part of an existing one's definition?"
+ *  ({@link agentDefinitionOwner}) — and those answers differ (an agent's `src/` is inside it, but is not
+ *  part of what it loads), so exporting the raw containment fact would invite conflating them.
+ *  Placement resolution deliberately never walks up — the answer must not depend on how deep you stand
+ *  — but "you are inside an agent, just not at its root" is the likeliest reason resolution fails, and
+ *  both the refusal below and `login`'s global-fallback decision need to tell that case apart. Uses the
+ *  same marker as resolution (an ancestor holding a config), so it never claims a position it cannot
+ *  justify. */
+function enclosingAgentDir(dir) {
+    let candidate = dirname(resolve(dir));
+    for (let prev = ""; candidate !== prev; prev = candidate, candidate = dirname(candidate)) {
+        if (hasConfig(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The agent whose DEFINITION contains `dir` — scaffolding there would make the new agent part of the
+ * outer one's loaded surface rather than an agent of its own. Narrower than {@link enclosingAgentDir} on
+ * purpose: an agent owns only what it LOADS ({@link LOADED_SURFACE}); the rest of its directory is the
+ * author's tree, where a second agent (a monorepo package, say) is a legitimate thing to create.
+ * `enclosingAgentDir` answers a different question ("where do I `cd` to?"), and for that an agent's
+ * `src/` genuinely IS inside it.
+ */
+export function agentDefinitionOwner(dir) {
+    const base = resolve(dir);
+    const agent = enclosingAgentDir(base);
+    if (!agent)
+        return undefined;
+    const [head] = relative(agent, base).split(sep);
+    return head && LOADED_SURFACE.includes(head) ? agent : undefined;
+}
+/**
+ * Why `dir` is not an agent, when it has its OWN way out — or undefined when it is simply not near one.
+ * Two positions qualify: standing INSIDE an agent (its `tools/`, its `src/`), and standing on a
+ * directory whose several agents nothing selects between. Both matter because the generic advice ("run
+ * `fastagent init`") would not help — the agent already exists, one step away.
+ *
+ * Exported because `login` is the one command allowed to run outside an agent, and it must tell "truly
+ * outside" (→ the global credential) from "a dead end" (→ refuse, like every other command).
+ */
+export function placementDeadEnd(dir, env = process.env) {
+    const base = resolve(dir);
+    const enclosing = enclosingAgentDir(base);
+    if (enclosing) {
+        return `${base} is inside the agent ${enclosing} but is not its root — \`cd\` there (or to its workspace) and re-run`;
+    }
+    const agents = agentsAt(base).map((a) => basename(a));
+    const listed = `${base} holds ${agents.length} agent${agents.length === 1 ? "" : "s"} (${agents.join(", ")})`;
+    // Asserting a name that is not here is a different mistake from asserting none, and it is worth its own
+    // message at ANY count: the value sits in the environment (often a shell profile carried in from
+    // somewhere else), so echo it back with what is actually here instead of restating the general rule.
+    if (env.FASTAGENT_AGENT && agents.length > 0) {
+        return (`${listed}, and FASTAGENT_AGENT asserts "${env.FASTAGENT_AGENT}", which is not one of them — set it ` +
+            `to one of those, unset it, or scope it to the repository that needs it (an .envrc)`);
+    }
+    if (agents.length > 1) {
+        return (`${listed} and none of them is named "${DEFAULT_AGENT_DIRNAME}" (the default) — pick one with ` +
+            `FASTAGENT_AGENT=<name>, or point fastagent at the one you want (it then works on ITSELF)`);
+    }
+    return undefined;
+}
+/**
+ * Resolve a directory into its placement — the ONE owner of the rule ({@link findPlacement}): `dir` is
+ * the workspace, and the agent is the single `fastagent.config.*` holder at it or one level inside.
+ * Placement is never configured and never detected from surroundings; it is that lookup and the
+ * directory you pointed at.
+ *
+ * Anything else throws (fail visibly). Resolution never walks UP — an agent must not be claimed from
+ * arbitrarily deep inside it — but the MESSAGE reads the path, so each dead end gets the exit that fits
+ * it ({@link placementDeadEnd}).
+ */
+export function resolvePlacement(dir, env = process.env) {
+    const placement = findPlacement(dir, env);
+    if (!placement) {
+        const base = resolve(dir);
+        throw new Error(placementDeadEnd(base, env) ??
+            `${base} is not a fastagent agent — no fastagent.config.* here, and no directory holding one ` +
+                `directly inside; run \`fastagent init\` to scaffold one`);
+    }
+    return placement;
+}
+/** How to WRITE a path for someone standing in `cwd`: relative when it is inside `cwd`, absolute when
+ *  it climbs out (a `../../..` is noise), and undefined when it IS `cwd` (nothing to say). ONE policy,
+ *  shared by `init`'s `cd` step, `add`'s next-steps paths and `fire`'s "looked in" hint — they all answer
+ *  the same question, which is a placement-PRESENTATION question, not a scaffolding one. */
+export function displayPath(cwd, dir) {
+    const rel = relative(cwd, dir);
+    if (rel === "")
+        return undefined;
+    // "Climbs out" is a path-SEGMENT check — rel is ".." or starts with "../" (or "..\" on Windows). A
+    // bare startsWith("..") would wrongly flag an in-cwd directory literally named "..agent".
+    const escapes = rel === ".." || /^\.\.[/\\]/.test(rel);
+    return escapes ? dir : rel;
+}
+/** Does a path exist? Plain fs, no placement in it — it lives here because `paths.ts` is where the
+ *  neutral path helpers are, and the scaffolder is not a utility home for the CLI and deploy. */
+export async function exists(p) {
+    return access(p).then(() => true, () => false);
+}
+/**
+ * Resolve a user-supplied path override (a CLI flag or an env var) to an absolute path, expanding a
+ * leading `~`/`~/` to the home dir FIRST. Path-valued config from `.env` (or any non-shell source)
+ * never gets the shell's `~` expansion, so a bare `resolve("~/x")` would silently create a literal `~`
+ * directory — a fail-silently footgun for a secret/state path. Expanding here makes `~` mean home
+ * everywhere these knobs are read.
+ */
+export function resolveOverridePath(raw) {
+    if (!raw)
+        return undefined;
+    const expanded = raw === "~" ? homedir() : raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw;
+    return resolve(expanded);
+}
+/**
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/,
+ * control.json): `FASTAGENT_STATE_DIR` env > `<agentDir>/.state`. Absolute, so channels and the
+ * startup report agree regardless of cwd. Definition: mutable runtime state — single lifecycle
+ * (precious, survives redeploy), single process; a container points this at its mounted volume.
+ * Secrets are NOT here — they live under {@link resolveSecretsDir} (a different deploy lifecycle:
+ * secret store vs volume). The finer knob (`FASTAGENT_SESSIONS_DIR`) still overrides its path on top.
+ *
+ * `FASTAGENT_STATE_DIR` is an OPERATOR override, so a relative value resolves against `process.cwd()`
+ * — the CLI convention its sibling knobs share (`resolveOverridePath`), NOT against `dir`. Only the
+ * DEFAULT (`<root>/.state`) is dir-anchored.
+ */
+export function resolveStateRoot(dir, env = process.env) {
+    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? join(resolve(dir), STATE_DIRNAME);
+}
+/**
+ * The resolved secrets dir — everything fastagent manages that must NEVER leave the machine (the
+ * agent's `.env` + auth.json): `FASTAGENT_SECRETS_DIR` env > `<agentDir>/.secrets`. Split from
+ * the state root on deploy lifecycle: secrets travel through the host's secret store (env vars / the
+ * auth seed), state through a volume. A deployed box sets both env knobs at its volume (e.g.
+ * `/data/.secrets`, `/data/.state`) so a seeded-then-ROTATED OAuth credential persists across
+ * restarts. The `.env`'s OWN location resolves from the REAL environment — commands locate and load
+ * `.env` before anything else, so a `FASTAGENT_SECRETS_DIR` set INSIDE `.env` still relocates
+ * auth.json but cannot move the file it is read from (env.ts dotEnvPath).
+ */
+export function resolveSecretsDir(dir, env = process.env) {
+    return resolveOverridePath(env.FASTAGENT_SECRETS_DIR) ?? join(resolve(dir), SECRETS_DIRNAME);
+}
+/**
+ * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
+ * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.
+ * A missing target is fine (nothing to guard yet).
+ */
+export async function assertInsideAgentDir(agentDir, name) {
+    const target = join(agentDir, name);
+    const real = await realpath(target).catch((e) => {
+        if (e.code === "ENOENT" || e.code === "not_found")
+            return undefined;
+        throw e;
+    });
+    if (real === undefined)
+        return;
+    const root = await realpath(agentDir).catch(() => resolve(agentDir));
+    const rel = relative(root, real);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`${target} resolves outside the agent dir (${real}) — it must live inside the definition directory; ` +
+            `use a real directory or a symlink that stays within it`);
+    }
+}

package/dist/pi.d.ts

@@ -1,10 +1,10 @@
 export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
-export { defineTool, loadTools, type DefineToolOptions, type FastagentTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export { defineTool, loadTools, type DefineToolOptions, type FastagentTool, type MountedTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
 export type { ReadonlySessionManager, ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
 export type { AgentTool, ExecutionEnv, Session, SessionTreeEntry, Skill, SkillDiagnostic, } from "@earendil-works/pi-agent-core";
 export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";
-export { createPiAgentFromWorkspace, type CreatePiAgentFromWorkspaceOptions, } from "./engines/pi/workspace.ts";
+export { createPiAgentFromDir, type CreatePiAgentFromDirOptions, } from "./engines/pi/open.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
 export { defineConfig, listModels, resolveModel, type FastagentConfig } from "./engines/pi/config.ts";
 export { inProcessLease, type Lease, type Release, type SessionObserver } from "./engines/pi/invoke.ts";

package/dist/pi.js

@@ -1,9 +1,9 @@
-// The pi reference implementation: assembly, workspace discovery, tools, config, models, auth, and state ports.
+// The pi reference implementation: assembly, agent discovery, tools, config, models, auth, and state ports.
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
 export { defineTool, loadTools, } from "./engines/pi/tool.js";
 export { z } from "zod";
 export { loadChannels } from "./engines/pi/channel.js";
-export { createPiAgentFromWorkspace, } from "./engines/pi/workspace.js";
+export { createPiAgentFromDir, } from "./engines/pi/open.js";
 export { defineConfig, listModels, resolveModel } from "./engines/pi/config.js";
 export { inProcessLease } from "./engines/pi/invoke.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";

package/dist/runtime.d.ts

@@ -1,5 +1,7 @@
-export interface WorkspaceRuntime {
-    /** The JS runtime the workspace targets — drives the generated Dockerfile base + install/run commands
+/** 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`. */
     runtime: "node" | "bun";
     /** For `runtime: "bun"`, the version from package.json's `packageManager: "bun@x"` (undefined if a bun
@@ -9,14 +11,14 @@ export interface WorkspaceRuntime {
     hasLockfile: boolean;
 }
 /**
- * Detect which JS runtime a workspace targets: `bun` when package.json's `packageManager` is `bun@…` OR a
+ * 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 workspace is.
+ * they agree on what the agent is.
  */
 export declare function detectRuntime(dir: string, pkg: {
     packageManager?: unknown;
-}): WorkspaceRuntime;
+}): 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. */
 export declare function readPackageJson(dir: string): Promise<{

package/dist/runtime.js

@@ -2,10 +2,10 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 /**
- * Detect which JS runtime a workspace targets: `bun` when package.json's `packageManager` is `bun@…` OR a
+ * 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 workspace is.
+ * they agree on what the agent is.
  */
 export function detectRuntime(dir, pkg) {
     const pm = typeof pkg.packageManager === "string" ? pkg.packageManager : "";

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

@@ -35,10 +35,14 @@ 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. */
+    unprotectedSecretsDir?: string;
 }
 /**
- * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * 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
@@ -56,7 +60,7 @@ export declare function scaffoldChannel(dir: string, kind: ChannelKind, options?
     groupBehavior?: GroupBehavior;
 }): Promise<string>;
 /**
- * Verify the workspace is ready to host a channel: an ESM package.json that declares
+ * 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.
  */

package/dist/scaffold/add-channel.js

@@ -1,16 +1,15 @@
 /**
  * `fastagent add <channel>`: drop a `channels/<kind>.ts` adapter-glue file (+ any companion tool, +
- * `.env.example` vars) into an existing workspace. `add` checks and guides; it never bootstraps a
- * workspace (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. `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.
  */
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { detectRuntime } from "../runtime.js";
-import { assertInsideWorkspace } from "../workspace.js";
-import { channelBundleFiles, channelTemplate } from "./templates.js";
-import { exists } from "./init.js";
-import { parseEnvContent } from "../env.js";
+import { SECRETS_DIRNAME, assertInsideAgentDir, exists } from "../paths.js";
+import { baseTemplate, channelBundleFiles, channelTemplate } from "./templates.js";
+import { dotEnvPath, envExamplePath, parseEnvContent } from "../env.js";
 const CHANNEL_SCAFFOLDS = {
     github: {
         env: [
@@ -21,8 +20,8 @@ const CHANNEL_SCAFFOLDS = {
                 generate: true,
             },
         ],
-        // `{channel}` / `{tools}` are path placeholders the CLI resolves to the real workspace-relative
-        // location (agentDir-aware) — the CLI holds no channel-private filenames.
+        // `{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",
@@ -100,7 +99,7 @@ const CHANNEL_SCAFFOLDS = {
             },
         ],
         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 managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "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 — 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`",
@@ -124,7 +123,7 @@ const CHANNEL_SCAFFOLDS = {
         ],
         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 managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "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",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
         ],
@@ -136,7 +135,7 @@ const WEBSOCKET_SETUPS = {
     feishu: {
         env: CHANNEL_SCAFFOLDS.feishu.env.filter((entry) => ["FEISHU_APP_ID", "FEISHU_APP_SECRET"].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 managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "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)",
@@ -146,7 +145,7 @@ const WEBSOCKET_SETUPS = {
     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 managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "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)",
@@ -164,7 +163,7 @@ export function channelSetup(kind, ingress = "webhook", groupBehavior) {
         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 managed-thread replies and group context buffering remain disabled"
+                ? "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),
         };
     }
@@ -174,7 +173,7 @@ export function channelSetup(kind, ingress = "webhook", groupBehavior) {
             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 token rotation; subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
-                "group behavior: mention-only — bare managed-thread replies and unsummoned group context remain disabled",
+                "group behavior: mention-only — bare thread replies and unsummoned group context remain disabled",
                 ...setup.steps.slice(2),
             ],
         };
@@ -187,7 +186,7 @@ export function channelSetup(kind, ingress = "webhook", groupBehavior) {
  * is already present. Placeholders only — no real secret lands in the committable template.
  */
 export async function appendChannelEnv(dir, kind, ingress = "webhook") {
-    const file = join(dir, ".env.example");
+    const file = envExamplePath(dir);
     let current;
     try {
         current = await readFile(file, "utf8");
@@ -220,15 +219,42 @@ function mentionsEnvName(content, name) {
     return content.split("\n").some((line) => new RegExp(`^\\s*#?\\s*${name}\\s*=`).test(line));
 }
 /**
- * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * 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.
  */
 export async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
-    const file = join(dir, ".env");
+    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`. `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.
+    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.
+        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");
@@ -291,7 +317,7 @@ export async function appendChannelDotEnv(dir, kind, generated, overwrite = [],
             await appendFile(file, `${prefix}${marker}\n${lines.join("\n")}\n`);
         }
     }
-    return { written, alreadySet };
+    return { written, alreadySet, unprotectedSecretsDir };
 }
 /** The path `add <kind>` scaffolds to. */
 function channelPath(dir, kind) {
@@ -307,8 +333,8 @@ export async function channelExists(dir, kind) {
  */
 export async function scaffoldChannel(dir, kind, options = {}) {
     const channelsDir = join(dir, "channels");
-    // Don't write through a channels/ symlink that escapes the workspace; an in-workspace one is fine.
-    await assertInsideWorkspace(dir, "channels");
+    // Don't write through a channels/ symlink that escapes the agent dir; one inside it is fine.
+    await assertInsideAgentDir(dir, "channels");
     const file = channelPath(dir, kind);
     if (await exists(file)) {
         throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
@@ -365,7 +391,7 @@ export async function scaffoldChannel(dir, kind, options = {}) {
     return file;
 }
 /**
- * Verify the workspace is ready to host a channel: an ESM package.json that declares
+ * 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.
  */
@@ -377,11 +403,11 @@ export async function assertChannelReady(dir) {
     }
     catch (e) {
         if (e.code === "ENOENT") {
-            // `dir` is where the kit lives (agentDir when set) — "run init" is only the right advice when no
-            // workspace exists yet; a kit missing its manifest (e.g. a --minimal init) needs the manifest, not init.
-            throw new Error(`${dir}: no package.json — a channel adapter is code and needs the kit's own manifest. ` +
-                `Run \`fastagent init\` for a fresh workspace, or add a package.json with @fastagent-sh/fastagent there ` +
-                `(a --minimal init has none)`);
+            // `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.
+            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), ` +
+                `or run \`fastagent init\` in the workspace for a fresh agent`);
         }
         throw e;
     }