@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/engines/pi/config.js

@@ -11,15 +11,19 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * (resolveModel, resolveModelSpec). One concern: everything about fastagent.config.ts.
  *
  * Red line: config describes deployment/runtime choices, never authored identity or expertise (those
- * live in persona.md + skills, with AGENTS.md as project context). Deleting the config still leaves a
- * zero-config agent runnable with a model supplied by --model / FASTAGENT_MODEL.
+ * live in persona.md + skills, with AGENTS.md as project context). It has no say in PLACEMENT either —
+ * that rule lives in the neutral src/paths.ts — but its FILE is what marks a directory as an agent, so a
+ * served agent always has one (its contents may be `export default {}`; a model can still come from
+ * --model / FASTAGENT_MODEL). The loader below stays tolerant of a missing file because it is a loader:
+ * callers that have not resolved a placement (deploy inspection, tests) may point it anywhere.
  */
-import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { THINKING_LEVELS } from "./harness.js";
+import { isBindAddress } from "../../bind.js";
 import { moduleLoadHint } from "../../loader.js";
+import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
@@ -41,13 +45,9 @@ function validateStringList(value, key, shape, desc, path) {
         }
     }
 }
-/** The config filenames that make a directory a fastagent workspace, in load precedence. ONE source: the
- *  loader (below) and `scaffoldWorkspace`'s already-a-workspace refusal both read this, so "is there a
- *  config?" can't diverge between them when the set changes. */
-export const WORKSPACE_CONFIG_NAMES = ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = zero-config; a wrong-shape file throws. */
+/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
 export async function loadConfig(dir) {
-    const found = WORKSPACE_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
+    const found = AGENT_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
     if (found.length === 0)
         return { config: {} };
     if (found.length > 1) {
@@ -75,17 +75,16 @@ export async function loadConfig(dir) {
     }
     const c = config;
     // Unknown keys throw: defineConfig only type-protects .ts authors; a typo in a .js/.mjs config
-    // (`modle:`) must not silently degrade to zero-config.
+    // (`modle:`) must not silently degrade to defaults.
     for (const key of Object.keys(c)) {
         if (key !== "model" &&
             key !== "thinkingLevel" &&
-            key !== "agentDir" &&
             key !== "tools" &&
             key !== "http" &&
             key !== "deploy" &&
             key !== "selfSchedule" &&
             key !== "sessionControl") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, agentDir, tools, http, deploy, selfSchedule, sessionControl)`);
+            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, tools, http, deploy, selfSchedule, sessionControl)`);
         }
     }
     if (c.model !== undefined && typeof c.model !== "string") {
@@ -97,47 +96,6 @@ export async function loadConfig(dir) {
     if (c.thinkingLevel !== undefined && !THINKING_LEVELS.has(c.thinkingLevel)) {
         throw new Error(`${path}: "thinkingLevel" must be one of ${[...THINKING_LEVELS].join(", ")}`);
     }
-    if (c.agentDir !== undefined && typeof c.agentDir !== "string") {
-        throw new Error(`${path}: "agentDir" must be a string (a subdirectory relative to the config file)`);
-    }
-    if (typeof c.agentDir === "string") {
-        // Enforce the documented "subdirectory of the config dir" contract: an escaping agentDir (e.g.
-        // "../shared") would still resolve for tool/channel/persona discovery, but `dev`'s chokidar only
-        // watches the config dir subtree — edits outside it would silently never trigger a restart. Reject
-        // it here (fail visibly) rather than let hot-reload break without a signal.
-        const rel = relative(dir, resolve(dir, c.agentDir));
-        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") must be a subdirectory of the config directory, not escape it`);
-        }
-        // An explicitly declared agentDir that doesn't exist is a typo until proven otherwise ("./agnet"):
-        // without this check every opener would assemble an EMPTY agent (no persona, no skills, no tools)
-        // with zero errors — the worst silent failure this config can produce. Deliberately NOT auto-created:
-        // config load is read-only (no implicit operations), and a mkdir would turn the typo into a served
-        // empty agent plus a junk directory.
-        // lstat, not stat: a symlink would pass the literal containment check above while its TARGET lives
-        // outside the config dir — exactly what that check exists to prevent (dev's watch would silently
-        // never see edits). Same rule as init's parent preflight: reject, don't follow.
-        const agentDirAbs = resolve(dir, c.agentDir);
-        const st = lstatSync(agentDirAbs, { throwIfNoEntry: false });
-        if (!st) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") does not exist — create it, or fix the path`);
-        }
-        if (st.isSymbolicLink()) {
-            // Separate message: to its user a symlink LOOKS like a working directory — name the reason and the fix.
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is a symlink — not allowed (its target can live outside the ` +
-                `config directory, where dev's watch would never see edits); use a real directory, or point agentDir at the target's real path`);
-        }
-        if (!st.isDirectory()) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is not a directory`);
-        }
-        // The leaf lstat can't see a symlinked INTERMEDIATE segment (agentDir "./a/b" with `a` → outside):
-        // realpath equality covers every segment under the config dir in one comparison. dir itself is
-        // realpath'd on both sides, so a symlinked config-dir path (macOS /tmp) stays legal.
-        if (realpathSync(agentDirAbs) !== resolve(realpathSync(dir), relative(dir, agentDirAbs))) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") resolves through a symlink — not allowed (the target can ` +
-                `live outside the config directory, where dev's watch would never see edits); use the real path`);
-        }
-    }
     if (c.selfSchedule !== undefined && typeof c.selfSchedule !== "boolean") {
         throw new Error(`${path}: "selfSchedule" must be a boolean`);
     }
@@ -159,13 +117,18 @@ export async function loadConfig(dir) {
         throw new Error(`${path}: "http" must be an object`);
     }
     for (const key of Object.keys(c.http ?? {})) {
-        if (key !== "port") {
-            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port)`);
+        if (key !== "port" && key !== "host") {
+            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port, host)`);
         }
     }
     if (c.http?.port !== undefined && (typeof c.http.port !== "number" || !isValidPort(c.http.port))) {
         throw new Error(`${path}: "http.port" must be an integer 0-65535`);
     }
+    // Validated as strictly as http.port: an unbindable string ("banana") must fail HERE, not surface
+    // later as a topology diagnostic about "the interface you bound".
+    if (c.http?.host !== undefined && (typeof c.http.host !== "string" || !isBindAddress(c.http.host))) {
+        throw new Error(`${path}: "http.host" must be an IP address or "localhost" (e.g. "127.0.0.1", "0.0.0.0")`);
+    }
     if (c.deploy !== undefined && (typeof c.deploy !== "object" || c.deploy === null)) {
         throw new Error(`${path}: "deploy" must be an object`);
     }
@@ -181,15 +144,6 @@ export async function loadConfig(dir) {
     validateStringList(c.deploy?.apt, "deploy.apt", /^[a-z0-9][a-z0-9.+-]*$/, "a Debian package name", path);
     return { config: c, path };
 }
-/**
- * The agent-definition dir from config: `config.agentDir` resolved against `dir`, or `dir` itself when
- * unset (flat). The ONE place this is computed — every opener (`dev`/`start`/`info`/`tool`/`deploy`/`chat`)
- * calls it, so the "relative to the config dir, default `.`" rule can never diverge. loadConfig has
- * already validated that agentDir stays under `dir`.
- */
-export function resolveAgentDir(dir, config) {
-    return resolve(dir, config.agentDir ?? ".");
-}
 /** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
  *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
  *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
@@ -223,7 +177,7 @@ export function listModels(models) {
 /**
  * Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back.
  * Handles the scaffold's commented placeholder (`// model: "…"`) and an existing `model:` line; returns
- * null when neither is present (zero-config or a hand-shaped config) so the caller falls back to a
+ * null when neither is present (no config file, or a hand-shaped one) so the caller falls back to a
  * printed hint instead of guessing where to insert. Text-level (not AST) on purpose — it only ever
  * touches a line it recognizes, never reformats the author's file.
  */
@@ -248,19 +202,6 @@ export function rewriteConfigModel(src, spec) {
 export function resolveModelSpec(flag, config, env = process.env) {
     return flag ?? env.FASTAGENT_MODEL ?? config.model;
 }
-/**
- * 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.
- */
-function resolveOverridePath(raw) {
-    if (!raw)
-        return undefined;
-    const expanded = raw === "~" ? homedir() : raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw;
-    return resolve(expanded);
-}
 /**
  * `start`'s sessions-dir override: `--sessions-dir` flag > `FASTAGENT_SESSIONS_DIR` env > undefined
  * (the opener then falls back to {@link defaultSessionsDir} under the {@link resolveStateRoot} root).
@@ -271,43 +212,21 @@ export function resolveSessionsDirOverride(flag, env = process.env) {
 }
 /**
  * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
- * falls back to {@link defaultAuthPath} under the {@link resolveStateRoot} root). Resolved to absolute
+ * falls back to {@link defaultAuthPath} under the {@link resolveSecretsDir} dir). Resolved to absolute
  * so the store and the startup report agree regardless of cwd. No implicit project↔global fallback (isolation
  * + fail-visibly; see auth.ts); to share one account across projects, point this at the global
- * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
+ * `~/.fastagent/.secrets/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
  */
-export function resolveAuthPathOverride(flag, env = process.env) {
+function resolveAuthPathOverride(flag, env = process.env) {
     return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
 }
-/**
- * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
- * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
- */
-function projectStateDir(dir) {
-    return join(dir, ".fastagent");
-}
-/**
- * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
- * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels
- * and the startup report agree regardless of cwd. Definition: single lifecycle (precious, survives
- * redeploy), single process — a container mounts ONE volume here. The finer knobs
- * (`FASTAGENT_SESSIONS_DIR`, `FASTAGENT_AUTH_PATH`) still override their specific 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 (`<dir>/.fastagent`) is dir-anchored. Deployments set an absolute path (a mounted volume);
- * a relative value is in-tree — hence self-ignored — only when run from the definition dir (cwd == dir).
- */
-export function resolveStateRoot(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? resolve(projectStateDir(dir));
-}
-/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
-export function defaultAuthPath(stateRoot) {
-    return join(stateRoot, "auth.json");
+/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
+export function defaultAuthPath(secretsDir) {
+    return join(secretsDir, "auth.json");
 }
-/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
 export function resolveAuthPath(dir, flag, env = process.env) {
-    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveStateRoot(dir, env));
+    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveSecretsDir(dir, env));
 }
 /** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
 export function defaultSessionsDir(stateRoot) {

package/dist/engines/pi/create.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type ExecutionEnv, type Skill, type ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Models, Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
@@ -6,19 +6,20 @@ import { type LoadedDefinition } from "./definition.ts";
 import { piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import { type FastagentTool, type ToolCollision } from "./tool.ts";
+import { type ToolCollision, type MountedTool } from "./tool.ts";
 import { type Lease, type SessionObserver } from "./invoke.ts";
-/** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
-export declare function piDefaultTools(cwd: string): AgentTool[];
+/** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
+ *  turn as the harness tool context — hence no argument here. */
+export declare function piDefaultTools(): MountedTool[];
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export declare function resolveTools(config: FastagentConfig, cwd: string): AgentTool[];
+export declare function resolveTools(config: FastagentConfig): MountedTool[];
 /**
- * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * The full tool set an agent mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
  * existing win), plus the non-default tool names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
-    tools: AgentTool[];
+export declare function resolveAgentTools(config: FastagentConfig, agentDir: string): Promise<{
+    tools: MountedTool[];
     toolNames: string[];
     /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
      *  via the built-in `search_tools` loader. Surfaced so the operator can see deferral took effect. */
@@ -33,7 +34,7 @@ export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir:
  * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
  */
 export declare function piBasePrompt(options?: {
-    tools?: AgentTool[];
+    tools?: MountedTool[];
     persona?: string;
 }): string;
 export interface AssembleSystemPromptOptions {
@@ -76,8 +77,10 @@ export interface CreatePiAgentOptions {
      * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
      */
     instructions?: string | (() => string);
-    /** `FastagentTool` = AgentTool plus the optional `deferred` marker (see {@link DefineToolOptions}). */
-    tools?: FastagentTool[];
+    /** The tool set to mount. `FastagentTool` (AgentTool plus the optional `deferred` marker, see
+     *  {@link DefineToolOptions}) widens into {@link MountedTool}, which additionally admits pi's default
+     *  coding tools — they read the turn's ExecutionEnv as a fifth `execute` parameter. */
+    tools?: MountedTool[];
     skills?: Skill[];
     /**
      * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint /
@@ -86,15 +89,17 @@ export interface CreatePiAgentOptions {
      */
     providers?: Provider[];
     /**
-     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/auth.json`; the
-     * directory opener passes the project-level `<dir>/.fastagent/auth.json` instead. Env vars are still
+     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/.secrets/auth.json`; the
+     * directory opener passes the project-level `<root>/.secrets/auth.json` instead. Env vars are still
      * consulted when a provider is absent from the file (resolution order is upstream-owned).
      */
     authPath?: string;
     /** Session persistence. Defaults to in-memory; inject jsonlSessionStore for restart-surviving continuity. */
     sessions?: PiSessionStore;
-    /** Harness filesystem/process environment. Defaults to local NodeExecutionEnv (cwd). This is not yet
-     *  a sandbox boundary for pi's cwd-bound coding tools; a sandbox adapter must wire those tools too. */
+    /** Filesystem/process environment. Defaults to a local NodeExecutionEnv at `process.cwd()`, and its
+     *  cwd is the agent's. The default coding tools (read/bash/edit/write) take it as the turn's tool
+     *  context, so injecting a constrained one narrows where the agent reads, writes and shells. It does
+     *  NOT constrain author-written `tools/`, which are code and can import anything. */
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
@@ -116,27 +121,30 @@ export interface CreatePiAgentFromDefinitionOptions {
     /** Override the engine base prompt (segment ①). Defaults to piBasePrompt({ tools, persona }) using the
      *  live-read persona.md; pass base to fully opt out of persona.md. */
     base?: string;
-    /** Override tools. Defaults to piDefaultTools (lock down with a custom list). `FastagentTool` =
-     *  AgentTool plus the optional `deferred` marker. */
-    tools?: FastagentTool[];
+    /** Override tools. Defaults to {@link piDefaultTools} (lock down with a custom list). An authored
+     *  `FastagentTool[]` (AgentTool plus the optional `deferred` marker) widens into {@link MountedTool}. */
+    tools?: MountedTool[];
     /**
      * The agent's working directory: where the default tools operate AND whose ancestors are walked for
-     * ② project context (AGENTS.md). Defaults to `dir` (flat: the definition dir is also the run root).
-     * Set it to the enclosing repo so a coding agent whose definition lives in `dir` operates on — and
-     * reads the AGENTS.md of — that repo (core.md scenario grid).
+     * ② project context (AGENTS.md). Defaults to `dir`. Set it to the enclosing repo so a coding agent
+     * whose definition lives in `dir` operates on — and reads the AGENTS.md of — that repo (core.md
+     * scenario grid); that is what the CLI's opener does with the workspace.
      */
     cwd?: string;
     /** Extra providers registered on top of the built-ins (your own gateway / self-hosted endpoint). */
     providers?: Provider[];
     /**
      * Credentials file (see {@link CreatePiAgentOptions.authPath}). Being dir-aware, this rung defaults
-     * to the PROJECT-level `<dir>/.fastagent/auth.json` (matching `fastagent dev`/`start` on the same
+     * to the PROJECT-level `<dir>/.secrets/auth.json` (matching `fastagent dev`/`start` on the same
      * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
      */
     authPath?: string;
     sessions?: PiSessionStore;
-    /** Harness environment; see {@link CreatePiAgentOptions.env}. The default coding tools and project-
-     *  context loader remain local today, so injecting this alone does not sandbox a directory agent. */
+    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. At THIS rung it does more
+     *  than root the default tools: persona.md and skills/ are read through it too. Two surfaces stay
+     *  OUTSIDE it — ② project context (pi's loadProjectContextFiles uses node fs directly; see
+     *  definition.ts) and author-written `tools/`, which are code and can import anything. Injecting an
+     *  env narrows the blast radius rather than closing it. */
     env?: ExecutionEnv;
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */

package/dist/engines/pi/create.js

@@ -6,14 +6,16 @@
  *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
  *   L0  createPiAgentFromHarness({ harnessFactory }) — in invoke.ts (its body is the turn mechanism).
  *
- * Above L2 sits the workspace opener createPiAgentFromWorkspace (workspace.ts), which both `dev` and
+ * Above L2 sits the agent opener createPiAgentFromDir (open.ts), which both `dev` and
  * `start` drive. Each rung calls the one below; options narrow as you go up (L2 owns systemPrompt/skills —
  * they come from the definition; the openers own model/tools — from config resolution).
  */
 import { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
+import { createBashTool, createEditTool, createReadTool, createWriteTool, } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { createCodingTools } from "@earendil-works/pi-coding-agent";
-import { defaultAuthPath, resolveModel, resolveStateRoot } from "./config.js";
+import { readImageProcessor } from "./read-image.js";
+import { defaultAuthPath, resolveModel } from "./config.js";
+import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
 import { piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
@@ -25,30 +27,52 @@ import { createPiAgentFromHarness, inProcessLease } from "./invoke.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
 // The full pi toolset is the default for fidelity: authors vibe in local pi with it, so serving with
-// fewer tools is behavior drift. Isolation is the K-side ExecutionEnv/sandbox's job, not the tool
-// layer's; locking down for public exposure = passing a restricted `tools` list (a deployment posture).
-/** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
-export function piDefaultTools(cwd) {
-    return createCodingTools(cwd);
+// fewer tools is behavior drift. Locking down for public exposure = passing a restricted `tools` list
+// (a deployment posture).
+//
+// These are pi-agent-core's tools, which reach the filesystem and the shell through the
+// {@link ExecutionEnv} the harness hands them per turn — NOT pi-coding-agent's, which are the same four
+// tools wired to `node:fs` directly. Going through the env is the point, and the whole of it: it makes
+// {@link CreatePiAgentOptions.env} the one seam a sandbox adapter has to implement, instead of a knob
+// that governed everything except the tools that actually touch the machine. (It buys no decoupling
+// from pi-coding-agent — definition.ts, models.ts and read-image.ts all import it regardless.)
+//
+// The swap holds only while the two behave alike, which they do NOT for free: core's `read` does
+// nothing with images unless a processor is injected (read-image.ts), and both families are compared
+// on every path in test/tools-parity.test.ts.
+//
+// `chat` is unaffected: it takes these NAMES only and lets pi's own runtime rebuild the tools it
+// renders (see session-builder.ts).
+/** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
+ *  turn as the harness tool context — hence no argument here. */
+export function piDefaultTools() {
+    // `read` needs its image pipeline INJECTED (core ships none); see read-image.ts for what is at stake.
+    return [
+        createReadTool({ imageProcessor: readImageProcessor }),
+        createBashTool(),
+        createEditTool(),
+        createWriteTool(),
+    ];
 }
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export function resolveTools(config, cwd) {
-    const defaults = piDefaultTools(cwd);
+export function resolveTools(config) {
+    const defaults = piDefaultTools();
     return config.tools ? [...defaults, ...config.tools] : defaults;
 }
 /**
- * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * The full tool set an agent mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
  * existing win), plus the non-default tool names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
-    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the run root the agent operates on);
-    // discovered `tools/` come from `agentDir` (the agent's own surface). They coincide in the flat case.
+export async function resolveAgentTools(config, agentDir) {
+    // Discovered `tools/` come from `agentDir` (the agent's own surface); the default coding tools carry
+    // no root of their own — they operate through the ExecutionEnv handed to them per turn, whose cwd is
+    // the workspace.
     const discovered = await loadTools(agentDir);
-    const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-    // The built-in `search_tools` loader mounts here — the one place the workspace's full tool set is
-    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; a
-    // workspace-defined search_tools wins).
+    const merged = mergeDiscoveredTools(resolveTools(config), discovered.tools);
+    // The built-in `search_tools` loader mounts here — the one place the agent's full tool set is
+    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; an
+    // agent-defined search_tools wins).
     const tools = withSearchTool(merged.tools);
     // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire
     // on the deferred-authored-loader case, where withSearchTool returns a new array without adding one).
@@ -58,7 +82,7 @@ export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
     // defaults, the builtin loader (like wake, a builtin gets its own report line, not an anonymous
     // slot in the author's list — an author-DEFINED search_tools still shows), and deferred tools —
     // each name lives in exactly ONE report slot, and deferred names live in `deferredToolNames`.
-    const defaultNames = new Set(piDefaultTools(cwd).map((t) => t.name));
+    const defaultNames = new Set(piDefaultTools().map((t) => t.name));
     const toolNames = tools
         .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
         .map((t) => t.name);
@@ -98,7 +122,7 @@ export function piBasePrompt(options = {}) {
     const deferredCount = mounted.length - tools.length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
-    // (the standalone×code-repo cell's persona; core.md §11), keeping the tools list + guidelines below.
+    // (core.md §11), keeping the tools list + guidelines below.
     const identity = options.persona?.trim() ||
         "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
     const deferredNote = deferredCount > 0
@@ -215,14 +239,14 @@ export async function createPiAgentFromDefinition(dir, options) {
     let reportedFindings = findingsSignature(definition);
     // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
     // it; a caller's own search_tools wins).
-    const tools = withSearchTool(options.tools ?? piDefaultTools(env.cwd));
+    const tools = withSearchTool(options.tools ?? piDefaultTools());
     const agent = buildPiAgent({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
         providers: options.providers,
-        // Dir-aware default: the same state-root-derived file the opener uses for this dir (the opener
+        // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
         // passes an explicit authPath, so this only affects direct L2 callers).
-        authPath: options.authPath ?? defaultAuthPath(resolveStateRoot(dir)),
+        authPath: options.authPath ?? defaultAuthPath(resolveSecretsDir(dir)),
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).

package/dist/engines/pi/definition.d.ts

@@ -32,9 +32,9 @@ export interface LoadedDefinition {
 }
 export interface LoadAgentDefinitionOptions {
     /**
-     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`
-     * (flat: the agent dir is also the run root). The opener passes the run root so a coding agent that
-     * lives in `agentDir` picks up the host repo's AGENTS.md up the tree (core.md scenario grid).
+     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`.
+     * The opener passes the workspace instead, so an agent that lives in `agentDir` picks up the
+     * project's AGENTS.md up the tree (core.md scenario grid).
      */
     cwd?: string;
     env?: ExecutionEnv;
@@ -42,31 +42,12 @@ export interface LoadAgentDefinitionOptions {
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
 /**
- * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
- * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
- * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
- * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
- * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ * 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.
  */
 export declare function isUnderDir(targetPath: string, baseDir: string): boolean;
-/**
- * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
- * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
- * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
- * write a `.gitignore` bypassing this.
- *
- * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
- * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
- * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
- * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
- * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
- * `.gitignore` into it (it may be a directory the operator deliberately tracks).
- *
- * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
- * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
- * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
- */
-export declare function ensureStateRootSelfIgnored(dir: string, stateRoot: string): Promise<void>;
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export declare function canonicalPath(p: string): string;

package/dist/engines/pi/definition.js

@@ -14,12 +14,11 @@
  * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
  */
 import { realpathSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { loadSkills } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { assertInsideAgentDir } from "../../paths.js";
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export async function loadAgentDefinition(agentDir, options = {}) {
     // One resolved default for the working directory (env cwd AND the context-walk start), so they can
@@ -44,7 +43,9 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     }
     const persona = personaRead.ok ? personaRead.value : undefined;
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
-    // definition loads the same skills on every machine.
+    // definition loads the same skills on every machine — and, like tools/channels/schedules, a symlink
+    // that escapes the agent dir is refused rather than followed (the fourth of four surfaces).
+    await assertInsideAgentDir(root, "skills");
     const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")]);
     const byName = new Map();
     const collisions = [];
@@ -60,62 +61,15 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     return { contextFiles, persona, skills: [...byName.values()], diagnostics, collisions, dir: root };
 }
 /**
- * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
- * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
- * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
- * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
- * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ * 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.
  */
 export function isUnderDir(targetPath, baseDir) {
     const rel = relative(baseDir, targetPath);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-/**
- * Self-ignore a state dir: create it if missing, then write `<stateDir>/.gitignore` = "*" (idempotent
- * — an existing one is kept), so a workspace that runs dev/start never shows machine state as
- * untracked. Creates the dir because a caller may self-ignore it before anything else populates it
- * (e.g. `login` writing auth.json into a not-yet-created root).
- *
- * Module-PRIVATE on purpose: the only entry to the leak guard is {@link ensureStateRootSelfIgnored}
- * (home exclusion + containment). Keeping this unexported makes that single-owner claim hold at the
- * type level — a sibling command can't bypass those checks by writing a `.gitignore` directly.
- */
-async function ensureStateDirSelfIgnored(stateDir) {
-    await mkdir(stateDir, { recursive: true });
-    await writeFile(join(stateDir, ".gitignore"), "*\n", { flag: "wx" }).catch((e) => {
-        if (e.code !== "EEXIST")
-            throw e;
-    });
-}
-/**
- * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
- * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
- * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
- * write a `.gitignore` bypassing this.
- *
- * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
- * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
- * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
- * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
- * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
- * `.gitignore` into it (it may be a directory the operator deliberately tracks).
- *
- * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
- * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
- * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
- */
-export async function ensureStateRootSelfIgnored(dir, stateRoot) {
-    // Compare CANONICAL paths for the home check: `dir` arrives realpath-resolved (it is `process.cwd()`
-    // or `resolve(".")`) but `homedir()` returns the raw `$HOME`, so a symlinked home would slip past raw
-    // equality and we'd write a `.gitignore` into the real `~/.fastagent` — the very thing the doc forbids
-    // (chat.ts canonicalizes for the same reason).
-    if (canonicalPath(dir) === canonicalPath(homedir()))
-        return;
-    // Containment on RAW paths: stateRoot is resolve()'d (config.ts) and `dir` is absolute, so it is exact
-    // by construction. An external-volume root resolves outside the tree → skip (not ours to ignore).
-    if (isUnderDir(stateRoot, dir))
-        await ensureStateDirSelfIgnored(stateRoot);
-}
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export function canonicalPath(p) {