@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/engines/pi/agent-session-factory.js

@@ -0,0 +1,314 @@
+/**
+ * The AgentSession L0's engine binding: fastagent's assembled agent — model, prompt, skills, tools —
+ * bound to one durable record, per invoke.
+ *
+ * The chat path builds the same pi class from the same assembly (session-builder.ts) but keeps ONE
+ * resident session. What is specific here is the posture: many sessions, one turn each, nothing in
+ * memory between turns.
+ *
+ * Shared once, rebuilt per turn:
+ * - `services` (ResourceLoader, settings, model runtime) is built lazily and reused — it is the
+ *   expensive half, and it holds nothing session-specific;
+ * - the `AgentSession` and its tool bindings are per turn, because a tool's `execute` closes over the
+ *   session it runs in and this posture has several in flight at once.
+ */
+import { dirname, join } from "node:path";
+import { createAgentSessionFromServices, createAgentSessionServices, } from "@earendil-works/pi-coding-agent";
+import { log } from "../../log.js";
+import { isDeferredTool } from "./tool.js";
+import { activePath, resolveSessionSettings } from "./session-settings.js";
+import { DEFAULT_THINKING_LEVEL } from "./models.js";
+import { additiveActivation, agentSessionManager, turnContext } from "./tool-context.js";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call.
+ *
+ * A DEDICATED record, not pi's own `active_tools_change`: that one is a full SNAPSHOT of everything
+ * active at the moment, so replaying it would keep a tool active in old sessions after the author
+ * flips it to `deferred` — the session never discovered it. A delta carries only what was actually
+ * found, and is layered onto whatever the workspace mounts TODAY.
+ */
+const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+/** Every deferred tool this session has ever discovered, oldest first. */
+function recordedActivations(session) {
+    const names = [];
+    for (const entry of session.sessionManager.getBranch()) {
+        const record = entry;
+        if (record.type !== "custom" || record.customType !== TOOL_ACTIVATION_ENTRY)
+            continue;
+        if (Array.isArray(record.data?.names)) {
+            for (const name of record.data.names)
+                if (typeof name === "string")
+                    names.push(name);
+        }
+    }
+    return names;
+}
+/** Warned once per session+missing set: a fresh session is built per invoke and channel sessions run
+ *  for weeks, so an un-deduped warn would repeat every turn and dilute its own signal. */
+const warnedDroppedActivations = new Set();
+/**
+ * The turn's {@link ToolActivation} over a live session — the same bridge chat uses, so one
+ * built-in `search_tools` serves both.
+ *
+ * Activations are PERSISTED as deltas, so a tool discovered in one turn stays callable in the next.
+ * pi's own chat session does not do this (it has no place to put the record); a served session does,
+ * because the alternative is an agent that re-discovers the same capability every single turn.
+ */
+function sessionToolActivation(session) {
+    // Serialize activations: the read-modify-write below is only race-free while nothing awaits
+    // between read and write, and parallel tool calls in one batch would otherwise double-stamp.
+    let chain = Promise.resolve([]);
+    return {
+        active: () => session.getActiveToolNames(),
+        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+        activate(names) {
+            const run = async () => {
+                const current = session.getActiveToolNames();
+                const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
+                if (added.length > 0) {
+                    session.setActiveToolsByName([...current, ...added]);
+                    session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
+                }
+                return added;
+            };
+            const result = chain.then(run, run);
+            chain = result.catch(() => []);
+            return result;
+        },
+    };
+}
+/**
+ * fastagent's tools as pi tool definitions, bound to ONE session.
+ *
+ * `bound` is filled after the session exists — pi needs the definitions to build the session, and a
+ * tool needs the session to reach the turn context. A tool that somehow runs before that binding
+ * throws rather than executing outside the turn: a broken lifecycle must not look like a normal
+ * out-of-turn call.
+ */
+function toolDefinitions(tools, cwd, env, sessionId, bound) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        label: tool.name,
+        description: tool.description ?? "",
+        parameters: tool.parameters,
+        // An activating tool (the built-in loader) declares "sequential" so pi serializes its batch;
+        // without it pi's outer active-set diff double-stamps parallel calls.
+        executionMode: tool.executionMode,
+        execute: (id, params, signal) => {
+            const session = bound.session;
+            if (!session)
+                throw new Error("tool executed before its session was bound (lifecycle invariant broken)");
+            return turnContext.run({ cwd, sessionManager: agentSessionManager(session, sessionId), tools: sessionToolActivation(session) }, 
+            // Lower-level MountedTools may consume the fifth-argument env. Directory coding tools are
+            // cwd-bound and ignore it; authored tools read FastAgent's turnContext instead.
+            () => tool.execute(id, params, signal, undefined, { env }));
+        },
+    }));
+}
+/**
+ * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
+ * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
+ * A definition running without the extension it ships is exactly the "quietly missing" failure this
+ * exists to remove. CHAT calls it, once per built services — serving does not load extensions at
+ * all, and announces that instead (see PiAgentSessionFactoryOptions.extensionPaths).
+ */
+export function reportExtensionErrors(services) {
+    for (const { path, error } of services.resourceLoader.getExtensions().errors) {
+        log.warn(`[fastagent] extension ${path} failed to load: ${error}`);
+    }
+}
+/**
+ * The resource posture a fastagent definition asks pi for — ONE definition of it, for both
+ * assemblies. Serving (`piAgentSessionFactory`) and chat (`buildAgentSessionRuntime`) build
+ * different sessions on top, but what pi is allowed to DISCOVER is not one of the differences:
+ * everything comes from the definition, nothing from the machine that happens to be running it.
+ *
+ * Two copies of this drifted once already: `additionalExtensionPaths` was added to both, and only
+ * one of them also passed the resulting tool names through pi's `tools` allowlist — so extensions
+ * worked when served and vanished in chat. A difference between the two has to be visible AS a
+ * difference, which is what the parameters are for: serving reads a prompt and skills that change
+ * per turn and passes NO extension paths (it does not run them — see
+ * {@link PiAgentSessionFactoryOptions.extensionPaths}); chat reads a fixed assembly and passes its
+ * own. Both are arguments now, rather than two files that happen to disagree.
+ */
+export function definitionResourceLoaderOptions(source) {
+    return {
+        // Definition-only, like dev/start: pi's machine-global discovery (the operator's own ~/.pi
+        // extensions, slash commands, global AGENTS.md, APPEND_SYSTEM.md) stays out, so the agent that
+        // runs is the artifact, not the artifact plus whoever's laptop it is.
+        noExtensions: true,
+        // ...except the definition's OWN extensions/: pi honours additionalExtensionPaths even under
+        // noExtensions, which is exactly the split wanted here — the artifact travels with its
+        // extensions, the machine's stay out.
+        ...(source.extensionPaths?.length ? { additionalExtensionPaths: [...source.extensionPaths] } : {}),
+        noPromptTemplates: true,
+        noContextFiles: true,
+        // A SPACE, not "", when the assembly has no prompt: pi treats an empty custom prompt as absent
+        // and substitutes its own coding-assistant identity, which an L1 agent
+        // (`createPiAgent({ model, tools })`) never asked for. pi appends its own working-directory line
+        // either way — that is engine behaviour this binding does not fight.
+        systemPromptOverride: () => source.systemPrompt() ?? " ",
+        appendSystemPromptOverride: () => [],
+        skillsOverride: (base) => ({
+            skills: toPiSkills(source.skills()),
+            diagnostics: base.diagnostics,
+        }),
+    };
+}
+/** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
+export function piAgentSessionFactory(options) {
+    const { sessions, thinkingLevel, cwd, env } = options;
+    const extensionPaths = options.extensionPaths ?? [];
+    const excludedToolNames = options.excludedToolNames ?? [];
+    if (extensionPaths.length > 0) {
+        log.warn(`[fastagent] ${extensionPaths.length} extension(s) in the definition are NOT loaded when serving ` +
+            "(they run in `fastagent chat`): pi's extension runtime is shared across sessions, and serving " +
+            "runs concurrent turns for different conversations. See docs/configuration.md#extensions.");
+    }
+    const tools = options.tools ?? [];
+    const deferred = tools.filter(isDeferredTool).map((t) => t.name);
+    // What the shared ResourceLoader serves, refreshed per turn before the session is built.
+    let prompt = typeof options.systemPrompt === "function" ? options.systemPrompt() : options.systemPrompt;
+    let skills = options.skills ?? [];
+    let services;
+    let engine;
+    const buildServices = async (modelRuntime) => createAgentSessionServices({
+        cwd,
+        agentDir: options.agentDir ?? join(cwd, ".fastagent", "pi"),
+        modelRuntime,
+        // No extensionPaths: serving does not run them (see PiAgentSessionFactoryOptions), which is
+        // the one resource question the two assemblies answer differently. The accessors read the
+        // CURRENT prompt/skills — serving refreshes both per turn, so a snapshot taken here would
+        // serve a stale definition after the first edit.
+        resourceLoaderOptions: definitionResourceLoaderOptions({
+            systemPrompt: () => prompt,
+            skills: () => skills,
+        }),
+    });
+    return async (sessionId, inherit) => {
+        const fresh = options.live ? await options.live() : undefined;
+        const nextPrompt = fresh
+            ? fresh.systemPrompt
+            : typeof options.systemPrompt === "function"
+                ? options.systemPrompt()
+                : prompt;
+        const nextSkills = fresh ? (fresh.skills ?? []) : skills;
+        engine ??= options.engine();
+        const { modelRuntime, model } = await engine;
+        if (services === undefined) {
+            prompt = nextPrompt;
+            skills = nextSkills;
+            services = buildServices(modelRuntime); // assigned before any await: concurrent turns share it
+        }
+        else {
+            // The ResourceLoader reads the overrides once and caches, so a re-read of the definition only
+            // reaches the model after a reload. Reload only when the definition ACTUALLY changed — an
+            // author edits persona.md far less often than the agent takes a turn, and a reload costs ~5ms
+            // against ~0.6ms to bind a session.
+            //
+            // "Changed" is measured against the LOADER, not against what this factory last wrote. Serving
+            // is concurrent across sessions, and a shared variable makes the check lie: one turn writes
+            // its new prompt, awaits before reloading, and the next turn sees that value already present,
+            // concludes nothing changed, and skips the reload — so the edit reaches neither the loader nor
+            // any error. Asking the loader what it is actually serving cannot go stale that way. The cost
+            // of losing the race is one redundant reload, not a swallowed edit.
+            //
+            // Skill CONTENT is not part of this — pi reads a skill from its file at invocation time, so
+            // only the declared set matters.
+            //
+            // What this deliberately does NOT provide is a per-turn snapshot. The definition is an AGENT
+            // property, not a session one: two turns running either side of an edit each get a definition
+            // that genuinely existed, and the product promise — an edit is live on the next turn — holds
+            // for both. Pinning a snapshot per turn would cost either a loader per turn or a queue in
+            // front of every bind, to buy a guarantee nothing asks for.
+            const loader = (await services).resourceLoader;
+            const definitionChanged = loader.getSystemPrompt() !== nextPrompt || loadedSkillSet(loader.getSkills().skills) !== skillSet(nextSkills);
+            if (definitionChanged) {
+                prompt = nextPrompt;
+                skills = nextSkills;
+                await loader.reload();
+            }
+        }
+        const sessionManager = await sessions.openOrCreate(sessionId, inherit);
+        // What the session RUNS on: the boundary plane records model/thinking overrides as entries, and
+        // pi does not read them back — a binding that ignored them would silently run every turn on the
+        // assembly default, and `state()` would report a setting no turn uses.
+        // The SAME read the control plane performs, including its integrity check: a record whose chain
+        // is broken must not run on assembly defaults while `state()` rejects it — one of the two planes
+        // would be lying. A throw here becomes this turn's `failed` event, which is where the fault has
+        // a channel to be reported through.
+        const settings = resolveSessionSettings(activePath(sessionManager), modelRuntime, {
+            model,
+            thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+        });
+        const bound = {};
+        const { session } = await createAgentSessionFromServices({
+            services: await services,
+            sessionManager,
+            model: settings.model,
+            thinkingLevel: settings.thinkingLevel,
+            // pi would otherwise mount its built-ins on top of fastagent's copies, offering duplicate names.
+            // Lower-level callers with an explicit list also rely on omitted built-ins staying omitted.
+            noTools: "builtin",
+            ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
+            customTools: toolDefinitions(tools, cwd, env, sessionId, bound),
+        });
+        bound.session = session;
+        // An extension handler that throws is otherwise dropped: pi fans errors out to registered
+        // listeners and has none by default, which on a server means a broken extension looks like an
+        // extension that simply did nothing.
+        //
+        // Deferral, then restoration: pi starts every mounted tool active, so narrow by SUBTRACTING the
+        // deferred names (robust to pi mounting tools of its own, unlike an exact-set replacement), then
+        // add back what THIS session has already discovered.
+        if (deferred.length > 0) {
+            const active = session.getActiveToolNames();
+            const mounted = new Set(session.getAllTools().map((tool) => tool.name));
+            const recorded = recordedActivations(session);
+            // A recorded name that is no longer mounted is dropped rather than replayed: pi's setter
+            // THROWS on an unknown name, so replaying one would brick every future turn of this session.
+            const restored = recorded.filter((name) => mounted.has(name));
+            const dropped = recorded.filter((name) => !mounted.has(name));
+            if (dropped.length > 0) {
+                const key = `${sessionId}\u0000${[...new Set(dropped)].sort().join(",")}`;
+                const emit = warnedDroppedActivations.has(key) ? log.debug : log.warn;
+                warnedDroppedActivations.add(key);
+                emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${[...new Set(dropped)].join(", ")}`);
+            }
+            const next = [...new Set([...active.filter((name) => !deferred.includes(name)), ...restored])];
+            if (next.length !== active.length || next.some((name) => !active.includes(name))) {
+                session.setActiveToolsByName(next);
+            }
+        }
+        return session;
+    };
+}
+/** What a reload has to notice: the declared set, not the files behind it. */
+function skillSet(skills) {
+    return skills.map((s) => `${s.name}\u0000${s.filePath}\u0000${s.description}`).join("\u0001");
+}
+/** The same signature, read back off the loader. */
+function loadedSkillSet(skills) {
+    return skills.map((s) => `${s.name}\u0000${s.filePath ?? ""}\u0000${s.description}`).join("\u0001");
+}
+/** fastagent's Skill (content inline) as pi's (read from filePath at invocation time). */
+function toPiSkills(skills) {
+    return skills.map((skill) => {
+        const baseDir = dirname(skill.filePath);
+        return {
+            name: skill.name,
+            description: skill.description,
+            filePath: skill.filePath,
+            baseDir,
+            sourceInfo: {
+                path: skill.filePath,
+                source: "fastagent",
+                scope: "project",
+                origin: "top-level",
+                baseDir,
+            },
+            disableModelInvocation: skill.disableModelInvocation ?? false,
+        };
+    });
+}

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

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import type { AnyModel } from "./harness.ts";
+import type { AnyModel } from "./models.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
@@ -9,8 +9,8 @@ export interface FastagentConfig {
      *  "xhigh" | "max"). Unset = pi's default. Authors tune thinking in the pi TUI while vibing — this
      *  is the serving-side counterpart (fidelity). Levels a model doesn't support are clamped by pi. */
     thinkingLevel?: ThinkingLevel;
-    /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
-     *  plus the optional `deferred` marker (see defineTool). */
+    /** Extra custom tools, appended after the pi coding tools — never replaces them. `FastagentTool`
+     *  = AgentTool plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
     /** `host` is the bind address: unset (or `0.0.0.0`) binds all interfaces — what containers need;
      *  `127.0.0.1` keeps the serve (including `/control/*`) off the LAN. Precedence: `--bind` > this. */
@@ -60,7 +60,7 @@ export declare function loadConfig(dir: string): Promise<LoadedConfig>;
  *  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). */
 export declare function providerOf(spec: string): string;
-/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
 export declare function listModels(models: Models): string[];

package/dist/engines/pi/config.js

@@ -151,7 +151,7 @@ export function providerOf(spec) {
     const slash = spec.indexOf("/");
     return slash > 0 ? spec.slice(0, slash) : spec;
 }
-/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export function resolveModel(models, spec) {
     const slash = spec.indexOf("/");
     if (slash < 1 || slash === spec.length - 1) {

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

@@ -1,25 +1,30 @@
-import { type ExecutionEnv, type Skill, type ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Models, Provider } from "@earendil-works/pi-ai";
+import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
-import { type AnyModel, piHarnessFactory } from "./harness.ts";
-import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
-import { type SessionObserver } from "./invoke.ts";
-import { type Lease } from "./turn-kit.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 declare function piDefaultTools(): MountedTool[];
-/** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export declare function resolveTools(config: FastagentConfig): MountedTool[];
+import { type PiAgentSessionFactory } from "./invoke-session.ts";
+import { type AnyModel } from "./models.ts";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type PiSessionRecordStore } from "./session-store.ts";
+import { type Lease, type SessionObserver } from "./turn-kit.ts";
 /**
- * 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
+ * Every pi coding tool, in canonical order, rooted at the workspace it operates in.
+ *
+ * pi ships two overlapping groupings and neither is the whole set: `createCodingTools` is the four it
+ * ACTIVATES for a terminal (read/bash/edit/write, no searching), `createReadOnlyTools` is
+ * read/grep/find/ls. `read` is in both; a directory agent mounts their union.
+ */
+export declare const CODING_TOOL_NAMES: readonly ["read", "grep", "find", "ls", "bash", "edit", "write"];
+export declare function piAllCodingTools(cwd: string): MountedTool[];
+/**
+ * The full directory-agent tool set: all pi coding tools + `config.tools` + discovered `tools/`
+ * (deduped, existing win), plus the authored 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 resolveAgentTools(config: FastagentConfig, agentDir: string): Promise<{
+export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd: string): Promise<{
     tools: MountedTool[];
     toolNames: string[];
     /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
@@ -57,20 +62,22 @@ export interface AssembleSystemPromptOptions {
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
 /**
  * INTERNAL seam (workspace ↔ assembly): hands the hub-wiring consumer the assembly's live parts —
- * the SAME models collection, harness factory, and lease the agent runs with — so boundary
- * mutations (session-control.ts) contend on the real lease and validate against the real registry.
- * Called synchronously, exactly once, before the agent is returned. Not part of the public surface.
+ * the SAME session factory and lease the agent runs with, plus the model registry behind a thunk —
+ * so boundary mutations (session-control.ts) contend on the real lease and validate against the real
+ * registry. Called synchronously, exactly once, before the agent is returned. Not public surface.
  */
-type OnAssembly = (parts: {
-    models: Models;
-    harnessFactory: ReturnType<typeof piHarnessFactory>;
+export type PiAssemblyParts = {
     lease: Lease;
-    /** The resolved configured pair — what a session without overrides runs on. */
-    defaults: {
+    sessionFactory: PiAgentSessionFactory;
+    /** The registry and configured model, resolved on first use (a credential read is async). */
+    engine: () => Promise<{
+        modelRuntime: ModelRuntime;
         model: AnyModel;
-        thinkingLevel: ThinkingLevel;
-    };
-}) => void;
+    }>;
+    /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
+    thinkingLevel: ThinkingLevel;
+};
+type OnAssembly = (parts: PiAssemblyParts) => void;
 /** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
 export interface CreatePiAgentOptions {
     /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
@@ -78,14 +85,18 @@ export interface CreatePiAgentOptions {
     /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
     thinkingLevel?: ThinkingLevel;
     /**
-     * The system prompt itself — verbatim, no engine base and no wrapping (unlike the directory path,
-     * which assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string
-     * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
+     * The system prompt itself — no engine base and no wrapping (unlike the directory path, which
+     * assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string or
+     * a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
+     *
+     * Not byte-for-byte verbatim: pi appends its own `Current working directory:` line to whatever
+     * prompt it is given. What this rung guarantees is that no engine IDENTITY is imposed — a
+     * hand-built agent is not told it is a coding assistant.
      */
     instructions?: string | (() => string);
     /** 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. */
+     *  coding tools — those bind their workspace at construction rather than reading a turn context. */
     tools?: MountedTool[];
     skills?: Skill[];
     /**
@@ -100,12 +111,15 @@ export interface CreatePiAgentOptions {
      * 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;
-    /** 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. */
+    /** Session persistence. Defaults to in-memory; inject piSessionRecordStore for restart-surviving
+     *  continuity. */
+    sessions?: PiSessionRecordStore;
+    /** Filesystem/process environment, handed to tools that read one as the turn's context. Defaults to
+     *  a local NodeExecutionEnv at `process.cwd()`. At THIS rung nothing else consumes it: L1 loads no
+     *  definition. It does NOT constrain the coding tools (pi's own, rooted at the workspace they were
+     *  built for) or author-written `tools/`, which are code and can import anything. Not a
+     *  sandbox — see {@link createPiAgentFromDefinition} for the rung where it also reads the
+     *  definition. */
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
@@ -127,11 +141,11 @@ 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 {@link piDefaultTools} (lock down with a custom list). An authored
+    /** Override tools. Defaults to {@link piAllCodingTools} (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
+     * The agent's working directory: where the coding tools operate AND whose ancestors are walked for
      * ② 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.
@@ -145,12 +159,11 @@ export interface CreatePiAgentFromDefinitionOptions {
      * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
      */
     authPath?: string;
-    sessions?: PiSessionStore;
-    /** 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. */
+    sessions?: PiSessionRecordStore;
+    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. At THIS rung it reads
+     *  persona.md and skills/. The seven coding tools, ② project context (pi's
+     *  loadProjectContextFiles uses node fs directly), and author-written `tools/` stay outside it.
+     *  Injecting an env narrows the blast radius rather than closing it. */
     env?: ExecutionEnv;
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */