@fastagent-sh/fastagent 0.14.0 → 0.16.0

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,15 +1,16 @@
 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 type { ToolActivation } from "./engines/pi/tool-context.ts";
+export type { ReadonlySessionManager, ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
-export type { AgentTool, ExecutionEnv, Session, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+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 } from "./engines/pi/invoke.ts";
+export { inProcessLease, type Lease, type Release, type SessionObserver } from "./engines/pi/invoke.ts";
+export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./engines/pi/session-control.ts";
 export type { AnyModel } from "./engines/pi/harness.ts";
-export { inMemorySessionStore, jsonlSessionStore, type PiSessionStore } from "./engines/pi/sessions.ts";
+export { inMemorySessionStore, jsonlSessionStore, type PiSessionReader, type PiSessionStore, } from "./engines/pi/sessions.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
 export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
 export type { Models } from "@earendil-works/pi-ai";

package/dist/pi.js

@@ -1,12 +1,13 @@
-// 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 { inMemorySessionStore, jsonlSessionStore } from "./engines/pi/sessions.js";
+export { createPiSessionControl, } from "./engines/pi/session-control.js";
+export { inMemorySessionStore, jsonlSessionStore, } from "./engines/pi/sessions.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
 export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
 export { createProvider } from "@earendil-works/pi-ai";

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

@@ -1,4 +1,14 @@
-export type ChannelKind = "github" | "telegram" | "feishu" | "lark";
+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 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. */
+export interface GroupBehaviorChoice {
+    behavior: GroupBehavior;
+    explicit: boolean;
+}
 /** An env var a scaffolded channel reads. `generate` = a random-string secret the CLI can pre-fill. */
 export interface ChannelEnv {
     name: string;
@@ -9,8 +19,8 @@ export interface ChannelEnv {
 }
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export declare const CHANNEL_KINDS: ChannelKind[];
-/** The env vars + next-step lines a scaffolded channel needs (for the CLI to print). */
-export declare function channelSetup(kind: ChannelKind): {
+/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
+export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehavior): {
     env: ChannelEnv[];
     steps: string[];
 };
@@ -19,31 +29,38 @@ export declare function channelSetup(kind: ChannelKind): {
  * 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.
  */
-export declare function appendChannelEnv(dir: string, kind: ChannelKind): Promise<boolean>;
+export declare function appendChannelEnv(dir: string, kind: ChannelKind, ingress?: FeishuSubscriptionMode): Promise<boolean>;
 export interface DotEnvWriteResult {
     /** Generated secret vars written as active `KEY=value` lines. */
     written: string[];
     /** Vars already present with a non-empty active value; left untouched and omitted from next steps. */
     alreadySet: string[];
+    /** Set when the secrets dir is an operator-chosen one (`FASTAGENT_SECRETS_DIR`) carrying no
+     *  `.gitignore`: 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
  * ready to edit while no fake secret is committed to the user's mental model.
  */
-export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[]): Promise<DotEnvWriteResult>;
+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}.
  */
-export declare function scaffoldChannel(dir: string, kind: ChannelKind): Promise<string>;
+export declare function scaffoldChannel(dir: string, kind: ChannelKind, options?: {
+    ingress?: FeishuSubscriptionMode;
+    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.
  */