@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/paths.d.ts

@@ -1,6 +1,5 @@
-/** The directory name `init` gives an agent (`<workspace>/fastagent/`) unless `--agent-dir` names another. */
-export declare const DEFAULT_AGENT_DIRNAME = "fastagent";
-/** The user-global machinery home, `~/.fastagent`: the machine's credentials, models.json and model catalog. */
+import type { DeployHost } from "./deploy/hosts.ts";
+/** The user-global machinery home, `~/.fastagent`: the machine's model credentials. */
 export declare function globalHome(): string;
 /**
  * The secrets segment inside an agent dir (or the global home). Every path fastagent resolves — `.env`,
@@ -9,55 +8,37 @@ export declare function globalHome(): string;
  * ignore templates spell it out as literal text, so renaming this constant means editing them too.
  */
 export declare const SECRETS_DIRNAME = ".secrets";
+export declare const AGENT_ENVIRONMENT_ENV = "FASTAGENT_ENVIRONMENT";
+type AgentEnvironment = "dev" | "production";
+export declare function selectAgentEnvironment(environment: AgentEnvironment, env?: NodeJS.ProcessEnv): void;
 /** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
 export declare const STATE_DIRNAME = ".state";
+/**
+ * Where fastagent clones the repositories `context.json` declares, `content/<name>` in the agent dir. Never an env
+ * override: a machine that has a checkout of its own binds it in {@link LOCAL_CONTEXT_FILE} instead.
+ */
+export declare const CONTENT_DIRNAME = "content";
+/** The agent's context declaration (`context.json`), beside its config: shared, so only what every instance reaches. */
+export declare const CONTEXT_FILE = "context.json";
+/** The directories of THIS machine the agent is bound to: never committed, never deployed. */
+export declare const LOCAL_CONTEXT_FILE = "context.local.json";
 /**
  * THE config filename. One spelling, not a family: fastagent generates this file, so a choice of extension buys
  * an author nothing and costs a precedence order plus a "you have two of them" failure path. Everything else an
- * author writes (`tools/`, `channels/`, `routines/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
+ * author writes (`tools/`, `channels/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
  */
 export declare const AGENT_CONFIG_FILE = "fastagent.config.ts";
-/** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). */
-export declare const AGENT_MODELS_FILE = "models.json";
-/** The agent's model catalog: pi.dev's models newer than pi's bundled catalog, fetched by `models --refresh`. */
-export declare const AGENT_MODEL_CATALOG_FILE = "models-store.json";
-export interface ResolvedPlacement {
-    /**
-     * The AGENT directory — where the definition (SYSTEM.md/skills/tools/channels/routines), the config, and the
-     * machinery dirs (`.secrets/`, `.state/`) live.
-     */
-    agentDir: string;
-    /**
-     * The WORKSPACE — what the agent works ON: its cwd, and the start of the ② context walk. Always the agent
-     * directory's parent, whichever of the two the command was pointed at.
-     */
-    workspace: string;
-}
+/** The agent `dir` sits INSIDE (the nearest proper ancestor that IS an agent dir), or undefined. */
+export declare function enclosingAgentDir(dir: string): string | undefined;
 /**
- * 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.
+ * The agent directory `dir` names, for a command that also works without one (`login`, `models`): `dir` itself when it
+ * holds the config, undefined when it is no agent and inside none. Inside an agent is refused, naming its root —
+ * answering for the enclosing agent would act on a directory the caller did not name, and answering "no agent" would
+ * send a login to the machine's store.
  */
-export declare function agentsAt(dir: string): string[];
-/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair or the throw. */
 export declare function findAgentDir(dir: string): string | 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.
- */
-export declare function agentDefinitionOwner(dir: string): string | undefined;
-/** Why `dir` is not an agent, when it has its OWN way out — or undefined when it is simply not near one. */
-export declare function placementDeadEnd(dir: string, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * Resolve a directory into its placement — the ONE owner of the rule ({@link findPlacement}).
- *
- * WHERE AN UNREADABLE CANDIDATE IS SPENT, and only here: this caller MUST produce an agent, so a directory it
- * could not look into is the difference between "there is none" and "there might be". `placementDeadEnd` is
- * asked a weaker question — is this place a dead end with its own way out — by callers like `login`, for which
- * a neighbour it may not enter is environment noise, not a reason to exit instead of logging in globally. It
- * also comes AFTER that call: with two agents to choose between, a permission problem in a third directory is
- * not the message that gets the caller moving.
- */
-export declare function resolvePlacement(dir: string, env?: NodeJS.ProcessEnv): ResolvedPlacement;
+/** The agent directory `dir` names ({@link findAgentDir}), refusing when there is none. */
+export declare function resolveAgentDir(dir: string): string;
 /** How to WRITE a path for someone standing in `cwd`. */
 export declare function displayPath(cwd: string, dir: string): string | undefined;
 export declare function exists(p: string): Promise<boolean>;
@@ -70,20 +51,14 @@ export declare function readTextIfExists(p: string): Promise<string | undefined>
 export declare function resolveOverridePath(raw: string | undefined): string | undefined;
 /**
  * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
- * `FASTAGENT_STATE_DIR` env > `<agentDir>/.state`.
+ * Explicit paths win; production otherwise uses `.state/production`, dev uses `.state`.
  */
 export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
-/**
- * WHERE an agent's session records live: `<state root>/sessions`, always. Records are machine state like channel
- * state and schedule claims, so they move with the ONE knob that moves all of it rather than with a second one that
- * moves only them — a split every reader would then have to agree about, and which left channel state behind anyway.
- * An embedder that really wants the records elsewhere passes `sessionsDir` to `createAgentService`; there is no env
- * or flag spelling of it, for the reason `resolveAuthPathOverride` states.
- */
-export declare function resolveSessionsDir(dir: string, env?: NodeJS.ProcessEnv): string;
+/** Where fastagent clones the content entry `name` of the agent in `dir`. */
+export declare function contentEntryPath(dir: string, name: string): string;
 /**
  * The resolved secrets dir — everything fastagent manages that must NEVER leave the machine (the agent's `.env` +
- * auth.json).
+ * auth.json). Explicit paths win; production otherwise uses `.secrets/production`, dev uses `.secrets`.
  */
 export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
 /** Is this process the deployed container the generated artifacts describe? ONE reading of the
@@ -91,6 +66,14 @@ export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv):
 export declare function isDeployedWorkspace(): boolean;
 /** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
 export declare function isAgentcoreRuntime(): boolean;
+/**
+ * Which host this deployed box runs on, for the command that logs it in (`login --deployment <host>`). Read from what
+ * each platform puts in a box's environment (`FLY_APP_NAME`, `RAILWAY_SERVICE_ID`) or what our AgentCore template
+ * sets, because the artifacts in the agent directory cannot say it: a Railway deploy leaves no file of its own, and a
+ * directory can hold several hosts' files. Undefined where nothing says (Docker sets nothing, nor would a host
+ * fastagent did not deploy to): the caller then asks for the host by name.
+ */
+export declare function deployedHost(env?: NodeJS.ProcessEnv): DeployHost | undefined;
 /**
  * The mode of a file fastagent CREATES to hold a secret: `auth.json`, a `.env` it makes itself,
  * a host's parameter file. That is the whole extent of its opinion about permissions — a file it did not create
@@ -110,3 +93,4 @@ export declare const SECRET_FILE_MODE = 384;
 export declare function assertInsideAgentDir(agentDir: string, name: string): Promise<void>;
 /** Whether `targetPath` lives inside `baseDir` (same path counts). */
 export declare function isUnderDir(targetPath: string, baseDir: string): boolean;
+export {};

package/dist/paths.js

@@ -1,14 +1,13 @@
 /**
- * PLACEMENT: which directory holds the agent, and which directory the agent works ON — plus the machinery paths that
- * follow from it.
+ * ADDRESSING: which directory is the agent — the one holding `fastagent.config.ts`, named by the caller — plus the
+ * machinery paths that follow from it. Nothing about what the agent works on is derived from where it sits; that is
+ * its declared content (src/content/).
  */
-import { readdirSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
 import { access, readFile, 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 an agent (`<workspace>/fastagent/`) unless `--agent-dir` names another. */
-export const DEFAULT_AGENT_DIRNAME = "fastagent";
-/** The user-global machinery home, `~/.fastagent`: the machine's credentials, models.json and model catalog. */
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+/** The user-global machinery home, `~/.fastagent`: the machine's model credentials. */
 export function globalHome() {
     return join(homedir(), ".fastagent");
 }
@@ -19,39 +18,35 @@ export function globalHome() {
  * ignore templates spell it out as literal text, so renaming this constant means editing them too.
  */
 export const SECRETS_DIRNAME = ".secrets";
+export const AGENT_ENVIRONMENT_ENV = "FASTAGENT_ENVIRONMENT";
+export function selectAgentEnvironment(environment, env = process.env) {
+    env[AGENT_ENVIRONMENT_ENV] = environment;
+}
+function environmentPath(dir, segment, env) {
+    const root = join(resolve(dir), segment);
+    return env[AGENT_ENVIRONMENT_ENV] === "production" ? join(root, "production") : root;
+}
 /** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
 export const STATE_DIRNAME = ".state";
+/**
+ * Where fastagent clones the repositories `context.json` declares, `content/<name>` in the agent dir. Never an env
+ * override: a machine that has a checkout of its own binds it in {@link LOCAL_CONTEXT_FILE} instead.
+ */
+export const CONTENT_DIRNAME = "content";
+/** The agent's context declaration (`context.json`), beside its config: shared, so only what every instance reaches. */
+export const CONTEXT_FILE = "context.json";
+/** The directories of THIS machine the agent is bound to: never committed, never deployed. */
+export const LOCAL_CONTEXT_FILE = "context.local.json";
 /**
  * THE config filename. One spelling, not a family: fastagent generates this file, so a choice of extension buys
  * an author nothing and costs a precedence order plus a "you have two of them" failure path. Everything else an
- * author writes (`tools/`, `channels/`, `routines/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
+ * author writes (`tools/`, `channels/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
  */
 export const AGENT_CONFIG_FILE = "fastagent.config.ts";
-/** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). */
-export const AGENT_MODELS_FILE = "models.json";
-/** The agent's model catalog: pi.dev's models newer than pi's bundled catalog, fetched by `models --refresh`. */
-export const AGENT_MODEL_CATALOG_FILE = "models-store.json";
-/**
- * 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.
- */
-const LOADED_SURFACE = [
-    "SYSTEM.md",
-    "APPEND_SYSTEM.md",
-    "skills",
-    "prompts",
-    "tools",
-    "channels",
-    "routines",
-    // pi's and the standard spellings the definition also reads: `.pi/skills`, `.pi/prompts`, `.agents/skills`.
-    ".pi",
-    ".agents",
-];
 /**
  * "Not there" and "could not look" are different answers, and only the first may read as an absence: an agent
- * directory the caller cannot enter (EACCES) reported as no-agent-here ends in `run \`fastagent init\` to
- * scaffold one` — over a definition that exists. So ENOENT/ENOTDIR are absence, and every other errno travels
- * with its path, as {@link agentChildren} already did for the scan itself.
+ * directory the caller cannot enter (EACCES) reported as no-agent-here ends in `run \`fastagent init\`` — over a
+ * definition that exists. So ENOENT/ENOTDIR are absence, and every other errno travels with its path.
  */
 function statOrAbsent(p) {
     try {
@@ -64,84 +59,12 @@ function statOrAbsent(p) {
         throw e;
     }
 }
-function isDir(p) {
-    return statOrAbsent(p)?.isDirectory() === true;
-}
 /** THE marker: a directory that declares itself an agent with a {@link AGENT_CONFIG_FILE}. */
 function hasConfig(p) {
-    return isDir(p) && statOrAbsent(join(p, AGENT_CONFIG_FILE)) !== undefined;
-}
-/**
- * DIRECTLY inside `dir`: the agent directories, and the ones the answer is missing for.
- *
- * A NAMED directory and a SCANNED one are different questions. `hasConfig` throws for the first, because the
- * caller pointed at it. Here it cannot: every machine has directories this process may not enter, and one of
- * them sitting next to the agent must not fail a command that found the agent — `workspaceHint` scans the
- * PARENT for a hint, which on a CI runner means scanning `/tmp` and its `snap-private-tmp`. So an unreadable
- * candidate is carried, not thrown, and {@link resolvePlacement} spends it where it is the answer: a caller
- * that must produce an agent and found none says "I could not look at these", never `fastagent init`.
- */
-function agentChildren(dir) {
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch (e) {
-        const code = e.code;
-        if (code === "ENOENT" || code === "ENOTDIR")
-            return { agents: [], unreadable: [] };
-        throw e;
-    }
-    const agents = [];
-    const unreadable = [];
-    for (const entry of entries.filter((e) => !e.isFile())) {
-        const child = join(dir, entry.name);
-        try {
-            if (hasConfig(child))
-                agents.push(child);
-        }
-        catch (e) {
-            // PERMISSION ONLY. "Someone else's 0700 directory sits next to mine" is the normal case this carrying
-            // exists for, and it is the one an operator can act on. EIO, ELOOP, a non-errno throw: those are real
-            // failures with different fixes, and a scan has no business turning them into a line of prose.
-            const code = e.code;
-            if (code !== "EACCES" && code !== "EPERM")
-                throw e;
-            unreadable.push(entry.name);
-        }
-    }
-    return { agents: agents.sort(), unreadable: unreadable.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.
- */
-export function agentsAt(dir) {
-    return scanAgents(resolve(dir)).agents;
-}
-/** {@link agentsAt} plus what the scan could not look at — one readdir answering both questions. */
-function scanAgents(base) {
-    return hasConfig(base) ? { agents: [base], unreadable: [] } : agentChildren(base);
-}
-/** WHICH agent is meant, when a directory holds several. */
-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. */
-function findPlacement(dir, env = process.env) {
-    const agentDir = selectAgent(agentsAt(resolve(dir)), env);
-    return agentDir === undefined ? undefined : { agentDir, workspace: dirname(agentDir) };
-}
-/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair or the throw. */
-export function findAgentDir(dir) {
-    return findPlacement(dir)?.agentDir;
+    return statOrAbsent(p)?.isDirectory() === true && statOrAbsent(join(p, AGENT_CONFIG_FILE)) !== undefined;
 }
 /** The agent `dir` sits INSIDE (the nearest proper ancestor that IS an agent dir), or undefined. */
-function enclosingAgentDir(dir) {
+export function enclosingAgentDir(dir) {
     let candidate = dirname(resolve(dir));
     for (let prev = ""; candidate !== prev; prev = candidate, candidate = dirname(candidate)) {
         if (hasConfig(candidate))
@@ -150,78 +73,29 @@ function enclosingAgentDir(dir) {
     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.
+ * The agent directory `dir` names, for a command that also works without one (`login`, `models`): `dir` itself when it
+ * holds the config, undefined when it is no agent and inside none. Inside an agent is refused, naming its root —
+ * answering for the enclosing agent would act on a directory the caller did not name, and answering "no agent" would
+ * send a login to the machine's store.
  */
-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. */
-export function placementDeadEnd(dir, env = process.env) {
+export function findAgentDir(dir) {
     const base = resolve(dir);
+    if (hasConfig(base))
+        return base;
     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.
-    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`);
+        throw new Error(`${base} is inside the agent ${enclosing} — run from ${enclosing}, or pass it as the agent`);
     }
     return undefined;
 }
-/**
- * Resolve a directory into its placement — the ONE owner of the rule ({@link findPlacement}).
- *
- * WHERE AN UNREADABLE CANDIDATE IS SPENT, and only here: this caller MUST produce an agent, so a directory it
- * could not look into is the difference between "there is none" and "there might be". `placementDeadEnd` is
- * asked a weaker question — is this place a dead end with its own way out — by callers like `login`, for which
- * a neighbour it may not enter is environment noise, not a reason to exit instead of logging in globally. It
- * also comes AFTER that call: with two agents to choose between, a permission problem in a third directory is
- * not the message that gets the caller moving.
- */
-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${noAgentHere(base)}`);
+/** The agent directory `dir` names ({@link findAgentDir}), refusing when there is none. */
+export function resolveAgentDir(dir) {
+    const agentDir = findAgentDir(dir);
+    if (agentDir === undefined) {
+        throw new Error(`${resolve(dir)} is not a fastagent agent — it holds no ${AGENT_CONFIG_FILE}; pass the agent's directory, ` +
+            "or create one with `fastagent init <dir>`");
     }
-    return placement;
-}
-/** At most this many names before the rest become a count — `/tmp` on a shared machine has plenty. */
-const LISTED_UNREADABLE = 3;
-/**
- * The rest of the "not an agent" refusal: the way out, plus what could not be looked at.
- *
- * BOTH, never one or the other. `fastagent init` is the only line that tells the caller what to do, and a
- * directory it cannot enter is exactly why that advice can be wrong (#571: scaffolding over a definition that
- * is there but invisible). Substituting the second for the first sends anyone running in `/tmp`, or on a
- * shared machine, to fix permissions on directories that were never theirs and hold no agent.
- */
-function noAgentHere(base) {
-    const { unreadable } = scanAgents(base);
-    const noConfig = ` — no fastagent.config.ts here, and no readable directory holding one directly inside`;
-    const scaffold = "run `fastagent init` to scaffold one";
-    if (unreadable.length === 0)
-        return `${noConfig}; ${scaffold}`;
-    const shown = unreadable.slice(0, LISTED_UNREADABLE).join(", ");
-    const rest = unreadable.length - LISTED_UNREADABLE;
-    // The unknown FIRST, because it is the one thing that can make the advice wrong.
-    return (`${noConfig}. ${unreadable.length} director${unreadable.length === 1 ? "y" : "ies"} here could not be ` +
-        `read (permission), so an agent may be inside one: ${shown}${rest > 0 ? `, +${rest} more` : ""}. Check ` +
-        `those first; ${scaffold} only if none of them holds an agent`);
+    return agentDir;
 }
 /** How to WRITE a path for someone standing in `cwd`. */
 export function displayPath(cwd, dir) {
@@ -258,27 +132,21 @@ export function resolveOverridePath(raw) {
 }
 /**
  * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
- * `FASTAGENT_STATE_DIR` env > `<agentDir>/.state`.
+ * Explicit paths win; production otherwise uses `.state/production`, dev uses `.state`.
  */
 export function resolveStateRoot(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? join(resolve(dir), STATE_DIRNAME);
+    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? environmentPath(dir, STATE_DIRNAME, env);
 }
-/**
- * WHERE an agent's session records live: `<state root>/sessions`, always. Records are machine state like channel
- * state and schedule claims, so they move with the ONE knob that moves all of it rather than with a second one that
- * moves only them — a split every reader would then have to agree about, and which left channel state behind anyway.
- * An embedder that really wants the records elsewhere passes `sessionsDir` to `createAgentService`; there is no env
- * or flag spelling of it, for the reason `resolveAuthPathOverride` states.
- */
-export function resolveSessionsDir(dir, env = process.env) {
-    return join(resolveStateRoot(dir, env), "sessions");
+/** Where fastagent clones the content entry `name` of the agent in `dir`. */
+export function contentEntryPath(dir, name) {
+    return join(resolve(dir), CONTENT_DIRNAME, name);
 }
 /**
  * The resolved secrets dir — everything fastagent manages that must NEVER leave the machine (the agent's `.env` +
- * auth.json).
+ * auth.json). Explicit paths win; production otherwise uses `.secrets/production`, dev uses `.secrets`.
  */
 export function resolveSecretsDir(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_SECRETS_DIR) ?? join(resolve(dir), SECRETS_DIRNAME);
+    return resolveOverridePath(env.FASTAGENT_SECRETS_DIR) ?? environmentPath(dir, SECRETS_DIRNAME, env);
 }
 /** Is this process the deployed container the generated artifacts describe? ONE reading of the
  *  environment fact the image states, so a second spelling cannot drift from it. */
@@ -289,6 +157,22 @@ export function isDeployedWorkspace() {
 export function isAgentcoreRuntime() {
     return process.env.FASTAGENT_AGENTCORE === "1";
 }
+/**
+ * Which host this deployed box runs on, for the command that logs it in (`login --deployment <host>`). Read from what
+ * each platform puts in a box's environment (`FLY_APP_NAME`, `RAILWAY_SERVICE_ID`) or what our AgentCore template
+ * sets, because the artifacts in the agent directory cannot say it: a Railway deploy leaves no file of its own, and a
+ * directory can hold several hosts' files. Undefined where nothing says (Docker sets nothing, nor would a host
+ * fastagent did not deploy to): the caller then asks for the host by name.
+ */
+export function deployedHost(env = process.env) {
+    if (env.FASTAGENT_AGENTCORE === "1")
+        return "agentcore";
+    if (env.FLY_APP_NAME)
+        return "fly";
+    if (env.RAILWAY_SERVICE_ID)
+        return "railway";
+    return undefined;
+}
 /**
  * The mode of a file fastagent CREATES to hold a secret: `auth.json`, a `.env` it makes itself,
  * a host's parameter file. That is the whole extent of its opinion about permissions — a file it did not create

package/dist/runtime.d.ts

@@ -1,6 +1,5 @@
 /**
- * How to install and run the AGENT: its package.json + lockfile decide, never the surrounding workspace's (whose
- * toolchain is the agent's runtime concern, not fastagent's).
+ * How to install and run the AGENT: its own package.json + lockfile decide.
  */
 export interface AgentRuntime {
     /**
@@ -23,6 +22,29 @@ export interface AgentRuntime {
 export declare function detectRuntime(dir: string, pkg: {
     packageManager?: unknown;
 }): AgentRuntime;
+/**
+ * The oldest runtimes that run an agent, both set by the instance's storage, `node:sqlite`: Bun ships it from 1.4.0,
+ * and Node stops calling it experimental, and printing so on every start, from 24.15.0.
+ */
+export declare const RUNTIME_FLOOR: {
+    readonly node: "24.15.0";
+    readonly bun: "1.4.0";
+};
+/** Whether `version` (`1.3.13`, `24.4`) is older than `floor`; false for one that names no version (`canary`). */
+export declare function belowFloor(version: string, floor: string): boolean;
+/** Why this process's runtime cannot run fastagent, or undefined when it can. Bun reports a Node version too. */
+export declare function unsupportedRuntime(versions?: {
+    node: string;
+    bun?: string;
+}): string | undefined;
+/**
+ * Whether a manifest lists FastAgent, which the image of an agent with a `package.json` runs from its own
+ * `node_modules`: without it, the container cannot start.
+ */
+export declare function listsFastagent(pkg: {
+    dependencies?: Record<string, unknown>;
+    devDependencies?: Record<string, unknown>;
+}): boolean;
 /**
  * Parse `<dir>/package.json`, or `{}` when there is none (a markdown-only agent). A file that does not parse throws,
  * naming itself: read as `{}` it became "does not list @fastagent-sh/fastagent" and an npm-based image, both wrong.
@@ -31,4 +53,5 @@ export declare function readPackageJson(dir: string): Promise<{
     packageManager?: unknown;
     dependencies?: Record<string, unknown>;
     devDependencies?: Record<string, unknown>;
+    optionalDependencies?: Record<string, unknown>;
 }>;

package/dist/runtime.js

@@ -14,6 +14,33 @@ export function detectRuntime(dir, pkg) {
     }
     return { runtime: "node", hasLockfile: existsSync(join(dir, "package-lock.json")) };
 }
+/**
+ * The oldest runtimes that run an agent, both set by the instance's storage, `node:sqlite`: Bun ships it from 1.4.0,
+ * and Node stops calling it experimental, and printing so on every start, from 24.15.0.
+ */
+export const RUNTIME_FLOOR = { node: "24.15.0", bun: "1.4.0" };
+/** Whether `version` (`1.3.13`, `24.4`) is older than `floor`; false for one that names no version (`canary`). */
+export function belowFloor(version, floor) {
+    const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(version);
+    if (match === null)
+        return false;
+    const given = [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+    const least = floor.split(".").map(Number);
+    const differs = given.findIndex((part, i) => part !== least[i]);
+    return differs !== -1 && given[differs] < least[differs];
+}
+/** Why this process's runtime cannot run fastagent, or undefined when it can. Bun reports a Node version too. */
+export function unsupportedRuntime(versions = process.versions) {
+    const [name, version, floor] = versions.bun === undefined ? ["Node", versions.node, RUNTIME_FLOOR.node] : ["Bun", versions.bun, RUNTIME_FLOOR.bun];
+    return belowFloor(version, floor) ? `fastagent needs ${name} ${floor} or later; this is ${version}` : undefined;
+}
+/**
+ * Whether a manifest lists FastAgent, which the image of an agent with a `package.json` runs from its own
+ * `node_modules`: without it, the container cannot start.
+ */
+export function listsFastagent(pkg) {
+    return "@fastagent-sh/fastagent" in { ...pkg.dependencies, ...pkg.devDependencies };
+}
 /**
  * Parse `<dir>/package.json`, or `{}` when there is none (a markdown-only agent). A file that does not parse throws,
  * naming itself: read as `{}` it became "does not list @fastagent-sh/fastagent" and an npm-based image, both wrong.

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

@@ -1,12 +1,6 @@
-import type { FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
+import { type ValueWriteResult } from "../value-file.ts";
+import { type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
 export type ChannelKind = "telegram" | "slack" | "feishu" | "lark";
-/** Group-visibility choice shared by the slack/feishu/lark onboarding flows. */
-export type GroupBehavior = "context" | "mentions";
-/** A resolved group-behavior decision plus whether the author actually chose it (flag or prompt). */
-export interface GroupBehaviorChoice {
-    behavior: GroupBehavior;
-    explicit: boolean;
-}
 /** An env var a scaffolded channel reads. */
 export interface ChannelEnv {
     name: string;
@@ -18,35 +12,28 @@ export interface ChannelEnv {
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export declare const CHANNEL_KINDS: ChannelKind[];
 /** The mode-specific env vars + next-step lines a scaffolded channel needs. */
-export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehavior): {
+export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscriptionMode, 
+/** Whether `<PREFIX>_INGRESS` is explicitly set in this environment. */
+pinned?: boolean): {
     env: ChannelEnv[];
     steps: string[];
 };
 /**
  * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who copies it to
- * `.env` finds the vars already there.
+ * `.env` finds the vars already there. Every var the channel can declare, whichever way this machine receives it:
+ * the file is what a collaborator or CI fills for a deployment, which receives Feishu/Lark by webhook.
  */
-export declare function appendChannelEnv(dir: string, kind: ChannelKind, 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`. */
-    unprotectedSecretsDir?: string;
-}
+export declare function appendChannelEnv(dir: string, kind: ChannelKind): Promise<boolean>;
 /**
- * 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 declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[], ingress?: FeishuSubscriptionMode): Promise<DotEnvWriteResult>;
+export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[], ingress?: FeishuSubscriptionMode): Promise<ValueWriteResult>;
 /** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
 export declare function channelExists(dir: string, kind: ChannelKind): Promise<boolean>;
-/** Scaffold `channels/<kind>.ts` into {@link dir}. */
-export declare function scaffoldChannel(dir: string, kind: ChannelKind, options?: {
-    ingress?: FeishuSubscriptionMode;
-}): Promise<string>;
-/** The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). */
+/** Scaffold `src/channels/<kind>.ts` into {@link dir}. */
+export declare function scaffoldChannel(dir: string, kind: ChannelKind): Promise<string>;
+/** The bundle's companion tools (every `.ts` beside `channel.ts` → `src/tools/<name>`). */
 export declare function scaffoldCompanionTools(dir: string, kind: ChannelKind): Promise<string[]>;
 /**
  * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares `@fastagent-sh/fastagent` (the