@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/paths.js

@@ -1,74 +1,71 @@
 /**
- * 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.
+ * PLACEMENT: which directory holds the agent, and which directory the agent works ON — plus the machinery paths that
+ * follow from it.
  */
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { access, chmod, mkdir, readFile, realpath } from "node:fs/promises";
+import { readdirSync, 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 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.
- */
+/** 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 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. */
+/** The user-global machinery home under `$HOME`. */
 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. */
+/**
+ * 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 scaffolded
+ * ignore templates spell it out as literal text, so 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 optional custom-model-endpoint file inside an agent dir (pi's models.json schema). Definition
- *  data, not machinery: it declares WHICH endpoint the agent talks to, so it belongs beside the config
- *  and travels into the deployed image. The name lives HERE, with the other placement facts, because
- *  two neutral readers need it — the loader in engines/pi/models.ts and `dev`'s watcher, whose restart
- *  scope must not silently drift from what the worker actually loads. */
+/**
+ * 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.
+ */
+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 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"];
+/**
+ * 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 = ["persona.md", "skills", "tools", "channels", "routines"];
+/**
+ * "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.
+ */
+function statOrAbsent(p) {
+    try {
+        return statSync(p);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return undefined;
+        throw e;
+    }
+}
 function isDir(p) {
-    return statSync(p, { throwIfNoEntry: false })?.isDirectory() === true;
+    return statOrAbsent(p)?.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. */
+/** THE marker: a directory that declares itself an agent with a {@link AGENT_CONFIG_FILE}. */
 function hasConfig(p) {
-    return isDir(p) && AGENT_CONFIG_NAMES.some((name) => existsSync(join(p, name)));
+    return isDir(p) && statOrAbsent(join(p, AGENT_CONFIG_FILE)) !== undefined;
 }
-/** 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. */
+/**
+ * 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 {
@@ -77,44 +74,41 @@ function agentChildren(dir) {
     catch (e) {
         const code = e.code;
         if (code === "ENOENT" || code === "ENOTDIR")
-            return [];
+            return { agents: [], unreadable: [] };
         throw e;
     }
-    return entries
-        .filter((e) => !e.isFile() && hasConfig(join(dir, e.name)))
-        .map((e) => join(dir, e.name))
-        .sort();
+    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. Exported for `init`, which asks the
- * same question this lookup asks: which agents would `dir` resolve over, before and after scaffolding.
+ * 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) {
-    const base = resolve(dir);
-    return hasConfig(base) ? [base] : agentChildren(base);
+    return scanAgents(resolve(dir)).agents;
 }
-/**
- * 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.
- */
+/** {@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)
@@ -122,59 +116,16 @@ function selectAgent(agents, env) {
     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.
- */
+/** Resolve `dir` into its placement, or undefined when nothing selects one agent. */
 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`;
+    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. Login and standalone channel senders also operate outside configured agents, so
- *  they need absence as a value. Filesystem errors still propagate. */
+/** 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;
 }
-/** 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. */
+/** The agent `dir` sits INSIDE (the nearest proper ancestor that IS an agent dir), or undefined. */
 function enclosingAgentDir(dir) {
     let candidate = dirname(resolve(dir));
     for (let prev = ""; candidate !== prev; prev = candidate, candidate = dirname(candidate)) {
@@ -184,12 +135,8 @@ 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. 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.
+ * 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 function agentDefinitionOwner(dir) {
     const base = resolve(dir);
@@ -199,15 +146,7 @@ export function agentDefinitionOwner(dir) {
     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).
- */
+/** 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) {
     const base = resolve(dir);
     const enclosing = enclosingAgentDir(base);
@@ -216,60 +155,72 @@ export function placementDeadEnd(dir, env = process.env) {
     }
     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.
+    // 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 (it then works on ITSELF)`);
+            `FASTAGENT_AGENT=<name>, or point fastagent at the one you want`);
     }
     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.
+ * Resolve a directory into its placement — the ONE owner of the rule ({@link findPlacement}).
  *
- * 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}).
+ * 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 — no fastagent.config.* here, and no directory holding one ` +
-                `directly inside; run \`fastagent init\` to scaffold one`);
+        throw new Error(placementDeadEnd(base, env) ?? `${base} is not a fastagent agent${noAgentHere(base)}`);
     }
     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. */
+/** 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`);
+}
+/** How to WRITE a path for someone standing in `cwd`. */
 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".
+    // "Climbs out" is a path-SEGMENT check — rel is ".." or starts with "../" (or "..\" on Windows).
     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);
 }
-/** The file's text, or undefined when there is no file. ONLY absence reads as absence: a file that
- *  exists but cannot be read (EACCES, a directory in its place) throws, because a decision made on
- *  "not there" — regenerate it, skip its gate — is the wrong one for a file that is there. */
+/** The file's text, or undefined when there is no file. */
 export async function readTextIfExists(p) {
     try {
         return await readFile(p, "utf8");
@@ -281,11 +232,8 @@ export async function readTextIfExists(p) {
     }
 }
 /**
- * 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.
+ * 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.
  */
 export function resolveOverridePath(raw) {
     if (!raw)
@@ -294,64 +242,54 @@ export function resolveOverridePath(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.
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
+ * `FASTAGENT_STATE_DIR` env > `<agentDir>/.state`.
  */
 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).
+ * 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");
+}
+/**
+ * The resolved secrets dir — everything fastagent manages that must NEVER leave the machine (the agent's `.env` +
+ * auth.json).
  */
 export function resolveSecretsDir(dir, env = process.env) {
     return resolveOverridePath(env.FASTAGENT_SECRETS_DIR) ?? join(resolve(dir), SECRETS_DIRNAME);
 }
-/** What a file under {@link resolveSecretsDir} is written with (auth.json, .env). */
-export const SECRET_FILE_MODE = 0o600;
-/** What the secrets directory itself is created with. */
-const SECRETS_DIR_MODE = 0o700;
+/** 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. */
+export function isDeployedWorkspace() {
+    return Boolean(process.env.FASTAGENT_RELEASE_FILE);
+}
+/** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
+export function isAgentcoreRuntime() {
+    return process.env.FASTAGENT_AGENTCORE === "1";
+}
 /**
- * Create the secrets directory with the mode its contents require — and REPAIR it when it already
- * exists, which is the case that matters.
+ * 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
+ * keeps the mode its owner gave it, and no directory's mode is ever decided or repaired. Every comparable tool
+ * draws the line here: Rails chmods the `master.key` it generates and leaves `config/` alone
+ * (rails/rails@4c6c357), the aws CLI ships a 0600 `~/.aws/config` inside a 0755 `~/.aws`.
  *
- * The DIRECTORY is the boundary that actually protects a credential: without its `x` bit nothing
- * below it is reachable, whatever a file's own mode says. And it is decided ONCE, by whichever
- * writer gets there first — `mkdir`'s `mode` is ignored for a directory that already exists, so a
- * later, more careful caller silently inherits the first one's answer. Four callers create this
- * directory (`init`, `add <channel>`, the credential store, the deploy seed) and the ordinary order
- * is init → add → login, so the careful one is LAST: the rule has to live where all of them can
- * reach it, and it has to chmod rather than trust the create.
+ * "Who created the file" is the load-bearing half: asking instead whether a given WRITE carries a secret has a
+ * different answer at every call site and one more with each new writer.
  *
- * A chmod the caller never asked for owes them its reason: the raw `EPERM ... chmod '/shared/creds'`
- * reads as a bug in whatever they WERE doing (storing a credential), not as fastagent tightening a
- * directory they pointed it at, and says nothing about the way out.
- */
-export async function ensureSecretsDir(dir) {
-    await mkdir(dir, { recursive: true, mode: SECRETS_DIR_MODE });
-    await chmod(dir, SECRETS_DIR_MODE).catch((e) => {
-        throw new Error(`cannot secure secrets dir ${dir} (fastagent keeps it 0700): ${e.message} — point --auth-path/FASTAGENT_SECRETS_DIR at a directory this process owns`, { cause: e });
-    });
-}
-/**
- * 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).
+ * One consequence worth knowing: `writeFileAtomic` sets the mode on the temp file it renames into place, so a
+ * file it owns end-to-end (`auth.json`) is 0600 after every write, including one an operator had
+ * placed by hand. Appending to a file fastagent did not create (`.env`) cannot and does not do that.
  */
+export const SECRET_FILE_MODE = 0o600;
+/** Guard that `<agentDir>/<name>` resolves INSIDE the agent dir. */
 export async function assertInsideAgentDir(agentDir, name) {
     const target = join(agentDir, name);
     const real = await realpath(target).catch((e) => {
@@ -368,12 +306,7 @@ export async function assertInsideAgentDir(agentDir, name) {
             `use a real directory or a symlink that stays within it`);
     }
 }
-/**
- * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
- * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
- * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
- * does not act on where a user's paths point.
- */
+/** Whether `targetPath` lives inside `baseDir` (same path counts). */
 export function isUnderDir(targetPath, baseDir) {
     const rel = relative(baseDir, targetPath);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));

package/dist/pi.d.ts

@@ -3,13 +3,9 @@ export { defineTool, type DefineToolOptions, type FastagentTool, type MountedToo
 export type { ReadonlySessionManager, ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
 export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
-/**
- * A conversation record, as the tool runtime and the control plane hold it. Its entries are pi's own
- * — exported under a qualified name because `SessionEntry` in this package is the NEUTRAL one the
- * control plane publishes (session.ts), and the two are different shapes.
- */
+/** A conversation record, as the tool runtime and the control plane hold it. */
 export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
-export { createPiAgentFromDir, type CreatePiAgentFromDirOptions, } from "./engines/pi/open.ts";
+export { availableModelsFromDir, 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 type { SessionObserver } from "./engines/pi/turn-kit.ts";
@@ -19,6 +15,8 @@ export { piInMemorySessionRecordStore, piSessionRecordStore, type PiSessionRecor
 export type { SessionInheritance } from "./engines/pi/session-inheritance.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
 export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
+export { login, loginOptions, LoginCancelled, type LoginMethod, type LoginOption, type LoginRequest, type LoginResult, } from "./engines/pi/login.ts";
+export type { AuthEvent, AuthInteraction, AuthPrompt } from "@earendil-works/pi-ai";
 export type { Models } from "@earendil-works/pi-ai";
 export type { Provider, ProviderAuth } from "@earendil-works/pi-ai";
 export type { Model } from "@earendil-works/pi-ai";

package/dist/pi.js

@@ -2,13 +2,13 @@
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
 export { defineTool, } from "./engines/pi/tool.js";
 export { z } from "zod";
-export { createPiAgentFromDir, } from "./engines/pi/open.js";
+export { availableModelsFromDir, createPiAgentFromDir, } from "./engines/pi/open.js";
 export { defineConfig, listModels, resolveModel, } from "./engines/pi/config.js";
 export { inProcessLease } from "./engines/pi/turn-kit.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";
 export { piInMemorySessionRecordStore, piSessionRecordStore, } from "./engines/pi/session-store.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
 export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
-// The product's one-call assembly: a directory becomes a live service. On the pi surface because
-// it opens a directory the pi way (channels, schedules, the assembled agent).
+export { login, loginOptions, LoginCancelled, } from "./engines/pi/login.js";
+// The product's one-call assembly: a directory becomes a live service.
 export { createAgentService } from "./engines/pi/service.js";

package/dist/proxy.d.ts

@@ -1,9 +1,19 @@
 /**
- * Route fetch through HTTPS_PROXY and keep fetch + dispatcher on the SAME undici implementation. Any
- * process that hits a provider or a channel API needs this UNDER NODE: Node's fetch does not honor
- * HTTPS_PROXY by itself (so login's OAuth token exchange, model calls, and a webhook setWebhook would go
- * direct, bypassing a region proxy), and Node 26's bundled fetch skips gzip decompression without
- * install() (empty stopReason:"stop"). A process-global side effect — call it once at a command/entry
- * start. No-op under Bun, whose native fetch already does both (and lacks the undici entry points).
+ * The exemption list the dispatcher is built with: whatever the environment declares, plus {@link LOOPBACK}.
+ *
+ * Its own function because installing happens ONCE per process, so these branches are unreachable through
+ * {@link installProxyFetch} — and the wildcard one is the kind that is silently wrong until someone reads it.
+ */
+export declare function noProxyList(env?: NodeJS.ProcessEnv): string;
+/**
+ * Point this process's fetch at the proxy the environment declares, with loopback exempt by default.
+ *
+ * Two jobs in one, and both are needed UNDER NODE: Node's fetch does not honor HTTP(S)_PROXY at all, and Node 26's
+ * bundled fetch skips gzip decompression when it dispatches through npm undici (empty `stopReason:"stop"`), so fetch
+ * and the dispatcher must come from the SAME undici. No-op under Bun, whose native fetch already does both (and
+ * lacks these entry points).
+ *
+ * Call it through `enterAgentEnv` (env.ts) rather than directly: the proxy may be declared in the agent's own `.env`,
+ * so it has to be read first. The only direct callers are the ones with no agent directory to read.
  */
 export declare function installProxyFetch(): void;