@fastagent-sh/fastagent 0.17.1 → 0.19.0

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

@@ -1,24 +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 Lease, type SessionObserver } from "./invoke.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
@@ -56,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}. */
@@ -77,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[];
     /**
@@ -99,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;
@@ -126,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.
@@ -144,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}. */

package/dist/engines/pi/create.js

@@ -4,72 +4,97 @@
  *
  *   L2  createPiAgentFromDefinition(dir, options)   — load a definition directory, assemble, then L1.
  *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
- *   L0  createPiAgentFromHarness({ harnessFactory }) — in invoke.ts (its body is the turn mechanism).
+ *   L0  createPiAgentFromSession({ sessionFactory }) — in invoke-session.ts (the turn mechanism).
  *
  * 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 { readImageProcessor } from "./read-image.js";
+import { createCodingTools, createPowerShellTool, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
 import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
-import { loadAgentDefinition } from "./definition.js";
-import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
-import { createPiModels } from "./models.js";
+import { loadAgentDefinition, loadExtensionPaths } from "./definition.js";
 import { reportFindingsIfChanged } from "./report.js";
-import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
-import { createPiAgentFromHarness, inProcessLease } from "./invoke.js";
+import { createPiAgentFromSession } from "./invoke-session.js";
+import { piAgentSessionFactory } from "./agent-session-factory.js";
+import { DEFAULT_THINKING_LEVEL, createPiModelRuntime } from "./models.js";
+import { piInMemorySessionRecordStore } from "./session-store.js";
+import { inProcessLease } from "./turn-kit.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. Locking down for public exposure = passing a restricted `tools` list
-// (a deployment posture).
+// A directory agent gets every pi coding tool. Restricting what those tools can reach belongs at the
+// sandbox boundary, not in an allowlist that leaves authored tools unrestricted. L1/L2 library callers
+// can still replace the coding defaults through `tools`; deferred tools may add `search_tools`.
 //
-// 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.)
+// This is not a security boundary and no default here could be one: the built-in POST /invoke has no
+// authentication, author-written `tools/` import whatever they like, and a WebSocket or Socket-Mode
+// channel dials OUT, so no bind address constrains who can message the agent. Whoever can reach an
+// agent can use everything it mounts — put it behind something that decides who may.
 //
-// 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.
+// All seven come from pi-coding-agent and reach the machine through `node:fs`, bypassing the per-turn
+// {@link ExecutionEnv}. pi-agent-core ships env-routed look-alikes, but that seam narrows a blast
+// radius rather than closing one (authored `tools/` ignore it), so a real sandbox must wrap the
+// process instead.
 //
-// `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.
+// Chat receives the same tool objects through pi's `customTools` path; pi's builtin copies stay off.
+/**
+ * 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 const CODING_TOOL_NAMES = ["read", "grep", "find", "ls", "bash", "edit", "write"];
+export function piAllCodingTools(cwd) {
+    const mutating = createCodingTools(cwd).filter((tool) => tool.name !== "read");
+    return [...createReadOnlyTools(cwd), ...mutating];
+}
+/**
+ * Every tool an `AgentSession` registers on its own, whether or not a directory agent mounts it.
+ *
+ * Wider than {@link CODING_TOOL_NAMES} on purpose: pi 0.84.3 added `powershell`, which the session
+ * registers regardless of the tools we pass. A name absent from THIS list is a name never excluded,
+ * and an excluded name is the only thing that cannot be activated — so leaving it out would let
+ * `tools: [read]` keep a reachable shell.
+ */
+function piRegisteredToolNames(cwd) {
     return [
-        createReadTool({ imageProcessor: readImageProcessor }),
-        createBashTool(),
-        createEditTool(),
-        createWriteTool(),
+        ...createReadOnlyTools(cwd).map((tool) => tool.name),
+        ...createCodingTools(cwd).map((tool) => tool.name),
+        createPowerShellTool(cwd).name,
     ];
 }
-/** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export function resolveTools(config) {
-    const defaults = piDefaultTools();
-    return config.tools ? [...defaults, ...config.tools] : defaults;
+/** Built-ins omitted by an explicit lower-level tool list. A reused name stays mounted. */
+function omittedBuiltinNames(mounted, cwd) {
+    const mountedNames = new Set(mounted.map((tool) => tool.name));
+    return [...new Set(piRegisteredToolNames(cwd))].filter((name) => !mountedNames.has(name));
 }
 /**
- * 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
+ * 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 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.
+export async function resolveAgentTools(config, agentDir, cwd) {
+    // Discovered `tools/` come from `agentDir` (the agent's own surface); the coding tools are
+    // rooted at `cwd`, the WORKSPACE — the project the agent works on, which is where an author expects
+    // `read`/`bash` to land, and which is not always the definition directory.
     const discovered = await loadTools(agentDir);
-    const merged = mergeDiscoveredTools(resolveTools(config), discovered.tools);
+    const configured = piAllCodingTools(cwd);
+    const configuredNames = new Set(configured.map((tool) => tool.name));
+    const configuredCollisions = [];
+    for (const tool of config.tools ?? []) {
+        if (configuredNames.has(tool.name)) {
+            configuredCollisions.push({ name: tool.name, source: "config.tools" });
+            continue;
+        }
+        configuredNames.add(tool.name);
+        configured.push(tool);
+    }
+    const merged = mergeDiscoveredTools(configured, 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).
@@ -77,12 +102,12 @@ export async function resolveAgentTools(config, agentDir) {
     // 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).
     const builtinLoaderMounted = !merged.tools.some((t) => t.name === "search_tools") && tools.some((t) => t.name === "search_tools");
-    const toolCollisions = [...discovered.collisions, ...merged.collisions];
-    // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/): exclude pi
-    // 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().map((t) => t.name));
+    const toolCollisions = [...discovered.collisions, ...configuredCollisions, ...merged.collisions];
+    // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/): exclude pi coding
+    // tools, 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(CODING_TOOL_NAMES);
     const toolNames = tools
         .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
         .map((t) => t.name);
@@ -122,9 +147,16 @@ 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
-    // (core.md §11), keeping the tools list + guidelines below.
+    // (core.md §11), keeping the tools list + guidelines below. Preserve pi's coding identity only for
+    // the full coding surface; a partial/empty surface must not claim machine capabilities it lacks.
+    // The four this sentence NAMES — reading, executing, editing, writing. Searching is not part of the
+    // claim, so requiring it would demote an agent that can do everything the identity says it can.
+    const mountedNames = new Set(mounted.map((tool) => tool.name));
+    const fullCodingSurface = ["read", "bash", "edit", "write"].every((name) => mountedNames.has(name));
     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.";
+        (fullCodingSurface
+            ? "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."
+            : "You are an AI assistant operating inside pi, an agent harness. Help users using only the tools and context available to you.");
     const deferredNote = deferredCount > 0
         ? `\n\n${deferredCount} additional tool(s) are registered but inactive — use search_tools to discover and activate them before concluding a capability is missing.`
         : "";
@@ -164,30 +196,56 @@ export function assembleSystemPrompt(options) {
  * directory) and route through here.
  */
 function buildPiAgent(opts) {
-    const models = createPiModels({ providers: opts.providers, authPath: opts.authPath });
     const env = opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() });
-    // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
-    // the SAME lease instance the agent runs under — boundary mutations must contend on it.
+    const cwd = opts.cwd ?? env.cwd;
+    // Materialized here (not defaulted inside the L0) so the exposed parts carry the SAME lease
+    // instance the agent runs under — boundary mutations must contend on it.
     const lease = opts.lease ?? inProcessLease();
-    // The assembly's configured PAIR — handed to the factory and to the control plane as ONE value, so
-    // there is no wiring in which they could disagree (which levels exist depends on the model).
-    const defaults = {
-        model: resolveModel(models, opts.model),
-        thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+    const sessions = opts.sessions ?? piInMemorySessionRecordStore({ cwd });
+    // The model and its runtime resolve on FIRST USE: building a ModelRuntime is async while
+    // assembling an agent is not, so the credential read belongs on the first turn rather than in the
+    // caller's constructor. Memoized by the factory, and shared with the control plane below so a
+    // boundary mutation validates against the registry the runs actually use.
+    let engine;
+    const resolveEngine = () => {
+        engine ??= (async () => {
+            // The caller's registry when there is one — the directory rung builds it from the agent's own
+            // models.json, so a custom endpoint declared there is the one a turn resolves against.
+            const modelRuntime = opts.models ?? (await createPiModelRuntime({ authPath: opts.authPath }));
+            // ModelRuntime registers providers by config record, so an injected Provider INSTANCE (a
+            // gateway, a self-hosted endpoint, a test fake) goes in through its native seam.
+            for (const provider of opts.providers ?? [])
+                modelRuntime.registerNativeProvider(provider);
+            return { modelRuntime, model: resolveModel(modelRuntime, opts.model) };
+        })();
+        return engine;
     };
-    const harnessFactory = piHarnessFactory({
-        sessions: opts.sessions ?? inMemorySessionStore(),
-        env,
-        models,
-        model: defaults.model,
+    const sessionFactory = piAgentSessionFactory({
+        sessions,
+        engine: resolveEngine,
         thinkingLevel: opts.thinkingLevel,
-        systemPrompt: opts.systemPrompt,
         tools: opts.tools,
+        systemPrompt: opts.systemPrompt,
         skills: opts.skills,
         live: opts.live,
+        cwd,
+        ...(opts.agentDir ? { agentDir: opts.agentDir } : {}),
+        ...(opts.extensionPaths ? { extensionPaths: opts.extensionPaths } : {}),
+        // `noTools: "builtin"` leaves pi's built-ins in the registry; a lower-level replacement must also
+        // deny every omitted coding name so a loader cannot reactivate one later.
+        excludedToolNames: omittedBuiltinNames(opts.tools ?? [], cwd),
+        env,
+    });
+    opts.onAssembly?.({
+        lease,
+        sessionFactory,
+        // The control plane needs the registry and the configured pair as VALUES, and both only exist
+        // after the first credential read. Asking for them lazily keeps assembly synchronous without
+        // making the hub wait on a runtime it may never need (a control-less deployment never calls it).
+        engine: resolveEngine,
+        thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
     });
-    opts.onAssembly?.({ models, harnessFactory, lease, defaults });
-    return createPiAgentFromHarness({ lease, observer: opts.observer, cwd: env.cwd, harnessFactory });
+    return createPiAgentFromSession({ lease, observer: opts.observer, sessionFactory });
 }
 /**
  * L1 system prompt: `instructions` ARE the prompt (no engine base, no wrapping); the skills listing
@@ -232,22 +290,32 @@ export async function createPiAgentFromDefinition(dir, options) {
     const env = options.env ?? new NodeExecutionEnv({ cwd });
     // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to
     // report (skills/diagnostics/collisions). Serving does NOT close over it — see `live` below.
-    const definition = await loadAgentDefinition(dir, { cwd: env.cwd, env });
+    // `cwd`, not `env.cwd`, for the same reason as the tools below: `cwd` is the run root whose
+    // ancestors carry ② project context. Reading it off the env pointed the AGENTS.md walk at the
+    // loader's directory whenever a caller supplied both.
+    const definition = await loadAgentDefinition(dir, { cwd, env });
+    // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
+    // it; a caller's own search_tools wins).
+    // `cwd`, not `env.cwd`: the workspace is what this option MEANS, and a caller may hand a custom env
+    // for definition loading whose root is a different directory. Taking it off the env would silently
+    // point the coding tools at the loader's directory.
+    const tools = withSearchTool(options.tools ?? piAllCodingTools(cwd));
     // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by
     // the resolved dir): announced once here, and re-announced by a turn or by the control plane's
     // command list only when the set CHANGES — a runtime-written bad skill surfaces the moment it
     // appears, a static one does not spam. Log dedup, not session state (stateless invoke holds).
     reportFindingsIfChanged(definition.dir, 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());
+    // 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).
+    const authPath = options.authPath ?? defaultAuthPath(resolveSecretsDir(dir));
     const agent = buildPiAgent({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        providers: options.providers,
-        // 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(resolveSecretsDir(dir)),
+        // THE directory rung's model surface: built-ins + the agent's own models.json (custom endpoints,
+        // which are definition data and travel with the artifact) + any injected Provider instance. This
+        // is what makes `dev`/`start`/`invoke` and an embedded L2 caller resolve the same specs.
+        models: await createPiModelRuntime({ agentDir: dir, authPath, providers: options.providers }),
+        authPath,
         // 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).
@@ -259,7 +327,7 @@ export async function createPiAgentFromDefinition(dir, options) {
         // not silently vanish from the agent, and a static one must not spam every turn's log. The
         // next good edit heals both.
         live: async () => {
-            const def = await loadAgentDefinition(dir, { cwd: env.cwd, env });
+            const def = await loadAgentDefinition(dir, { cwd, env });
             reportFindingsIfChanged(def.dir, def);
             return {
                 systemPrompt: assembleSystemPrompt({
@@ -269,13 +337,20 @@ export async function createPiAgentFromDefinition(dir, options) {
                     // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
                     contextFiles: def.contextFiles,
                     skills: def.skills,
-                    cwd: env.cwd,
+                    // The workspace, matching where the tools operate. Telling the model one directory while
+                    // `read`/`bash` resolve relative paths against another is a lie it cannot detect.
+                    cwd,
                 }),
                 skills: def.skills,
             };
         },
         tools,
         sessions: options.sessions,
+        // Discovered so the serving assembly can WARN that it does not run them (and so the refusals
+        // apply to the artifact either way) — `chat` is where they load. Boot-resolved: the set cannot
+        // change without a restart, which is why this sits outside `live` above.
+        extensionPaths: await loadExtensionPaths(dir, { cwd, env }),
+        cwd,
         env,
         lease: options.lease,
         observer: options.observer,

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

@@ -41,6 +41,47 @@ 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>;
+/**
+ * Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none.
+ *
+ * Paths, not loaded objects — unlike skills (data: content inline, serializable), an extension is
+ * CODE that pi loads with jiti and binds to its own eventBus/runtime, so loading it here would
+ * reimplement pi's loader. The engine binding hands these to pi as `additionalExtensionPaths`, which
+ * survives `noExtensions: true` — that flag suppresses MACHINE-GLOBAL discovery (`~/.pi`), and the
+ * definition's own extensions were only ever collateral to it. FILES, not the directory: pi's paths
+ * are module specifiers, and a directory fails as `Cannot find module` into a
+ * `LoadExtensionsResult.errors` entry nothing reads.
+ *
+ * SEPARATE from {@link loadAgentDefinition} on purpose. Prompt and skills are re-read every invoke
+ * ("the directory is the agent, LIVE"); scanning for extension entry points is not, since the set
+ * cannot change without a restart. Called once per assembly, like `tools/`.
+ *
+ * Discovery runs on BOTH paths; loading does not. `chat` hands these to pi and runs them fully.
+ * Serving only announces them — pi's extension runtime is shared across sessions, and serving has
+ * concurrent turns for unrelated conversations (see `PiAgentSessionFactoryOptions.extensionPaths`).
+ * The refusals below are therefore about what the ARTIFACT may contain, and hold for both.
+ *
+ * Discovery follows pi's own rules, so an extension that works in pi works here:
+ *
+ * 1. a direct `*.ts` / `*.js` file;
+ * 2. a subdirectory with `index.ts` / `index.js`.
+ *
+ * pi has a third rule — a subdirectory whose `package.json` declares a `pi` field — which is NOT
+ * implemented here. That shape is reported rather than skipped: a definition whose extension silently
+ * fails to load is the failure mode this whole path exists to remove.
+ *
+ * Containment matches skills/tools/channels/schedules (the fifth of five surfaces): a symlinked
+ * `extensions/` escaping the agent dir is refused, and — like `loadModuleDir`, whose `entry.isFile()`
+ * excludes them — a symlinked ENTRY is not loaded either. pi's own discovery does follow those, but
+ * an extension reached through a link out of the definition is code the artifact does not carry: it
+ * resolves on the authoring machine and is missing in the container. Refused loudly, never silently.
+ *
+ * Absent is normal and silent; a FILE at that path is not — that is an author who meant something.
+ */
+export declare function loadExtensionPaths(agentDir: string, options?: {
+    cwd?: string;
+    env?: ExecutionEnv;
+}): Promise<string[]>;
 /**
  * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same
  * loader, same containment guard, same first-wins collision rule) — for readers that need only the
@@ -56,13 +97,6 @@ export declare function loadAgentSkills(agentDir: string, options?: {
     collisions: SkillCollision[];
     dir: string;
 }>;
-/**
- * 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;
 /** 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;