@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/engines/pi/create.js

@@ -4,73 +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 { createPiModelRuntime, 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 } 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).
@@ -78,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);
@@ -123,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.`
         : "";
@@ -165,30 +196,56 @@ export function assembleSystemPrompt(options) {
  * directory) and route through here.
  */
 function buildPiAgent(opts) {
-    const models = opts.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
@@ -233,15 +290,21 @@ 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));
@@ -264,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({
@@ -274,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;

package/dist/engines/pi/definition.js

@@ -14,10 +14,11 @@
  * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
  */
 import { realpathSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { join, 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 { log } from "../../log.js";
 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 = {}) {
@@ -45,6 +46,119 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     const { skills, diagnostics, collisions } = await readSkills(e, root);
     return { contextFiles, persona, skills, diagnostics, collisions, dir: root };
 }
+/**
+ * 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 async function loadExtensionPaths(agentDir, options = {}) {
+    const cwd = options.cwd ?? agentDir;
+    const e = options.env ?? new NodeExecutionEnv({ cwd });
+    const rootResult = await e.absolutePath(agentDir);
+    if (!rootResult.ok)
+        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
+    const root = rootResult.value;
+    await assertInsideAgentDir(root, "extensions");
+    const dir = join(root, "extensions");
+    const listed = await e.listDir(dir);
+    if (!listed.ok) {
+        if (listed.error.code === "not_found")
+            return [];
+        throw new Error(`cannot read ${dir}: ${listed.error.message}`);
+    }
+    const paths = [];
+    for (const entry of listed.value) {
+        if (entry.kind === "symlink") {
+            // EVERY symlink here is announced, without guessing whether it meant to be an extension. The
+            // two mistakes are not equal: a needless line about a symlinked README costs a glance, while
+            // staying quiet about a symlinked extension loses a feature silently and only shows up in the
+            // container. A name-based guess also cannot see through the link — `audit.ext -> some/dir` is
+            // a directory candidate to pi and a mystery here — so the warning says what it knows and
+            // tells the author when to ignore it.
+            warnSymlinkRefused(entry.path);
+            continue;
+        }
+        if (entry.name.endsWith(".ts") || entry.name.endsWith(".js")) {
+            if (entry.kind === "file")
+                paths.push(entry.path);
+            continue;
+        }
+        if (entry.kind === "file")
+            continue; // a README, a .json — not an extension, not a problem
+        const index = await firstRealFile(e, [join(entry.path, "index.ts"), join(entry.path, "index.js")]);
+        if (index.path) {
+            paths.push(index.path);
+        }
+        else if (!index.refused) {
+            // Silent when the index WAS found and refused for being a symlink: that warning already named
+            // the real problem, and "expected index.ts" on top of it describes a directory that has one.
+            log.warn(`[fastagent] ${entry.path} is not a loadable extension: expected index.ts or index.js ` +
+                `(pi's package.json "pi" manifest form is not supported here) — it will not be loaded`);
+        }
+    }
+    return paths.sort();
+}
+/**
+ * The first candidate that is a REAL file. `exists` would follow a symlink, which is how a
+ * subdirectory's `index.ts` could otherwise point outside the definition and slip past the rule the
+ * top-level entries already follow.
+ */
+/** The first real file among the candidates, and whether one was found but REFUSED as a symlink. */
+async function firstRealFile(e, candidates) {
+    let refused = false;
+    for (const candidate of candidates) {
+        const info = await e.fileInfo(candidate);
+        if (!info.ok) {
+            if (info.error.code === "not_found")
+                continue;
+            throw new Error(`cannot read ${candidate}: ${info.error.message}`);
+        }
+        if (info.value.kind === "file")
+            return { path: candidate, refused };
+        if (info.value.kind === "symlink") {
+            warnSymlinkRefused(candidate);
+            refused = true;
+        }
+    }
+    return { refused };
+}
+function warnSymlinkRefused(path) {
+    log.warn(`[fastagent] ${path} is a symlink and will not be loaded: an extension must be a real file inside ` +
+        `the definition so it travels with the artifact — move it in. (If it is not an extension, ` +
+        `keep it outside extensions/ to silence this.)`);
+}
 /** The skills half, shared by the full load and {@link loadAgentSkills}. `root` is already resolved. */
 async function readSkills(e, root) {
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
@@ -81,16 +195,6 @@ export async function loadAgentSkills(agentDir, options = {}) {
     // (the findings memo) on it, and "./agent" vs an absolute path must not become two definitions.
     return { ...(await readSkills(e, rootResult.value)), dir: rootResult.value };
 }
-/**
- * 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));
-}
 /** 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) {

package/dist/engines/pi/invoke-session.d.ts

@@ -1,32 +1,35 @@
 /**
- * L0 over pi-coding-agent's `AgentSession`, in the `per-invoke` state locality
- * ([conformance-levels.md](../../../docs/design/conformance-levels.md) §2, top-right cell): build a
- * session per invoke over the SAME durable jsonl, run one turn, dispose.
+ * THE L0: pi's `AgentSession`, one per invoke, over the same durable record —
+ * [conformance-levels.md](../../../docs/design/conformance-levels.md) §2's `per-invoke` posture.
+ * Build a session, run one turn, dispose; continuity lives in the record, never in this process.
  *
- * Why this exists next to {@link createPiAgentFromHarness}: pi 0.84 replaced `AgentHarness` with an
- * unimplemented lane-based skeleton, and pi does not consume that class itself — its TUI, RPC and SDK
- * all run on `AgentSession`. This is the executable proof that the SPEC's four Agent-side MUSTs hold
- * on the class pi actually maintains (test/conformance-session.test.ts).
+ * Why this class: pi 0.84 replaced `AgentHarness` with an unimplemented lane-based skeleton, and pi
+ * does not consume that class itself — its TUI, RPC and SDK all run on `AgentSession`. Being the
+ * sole consumer of a surface nobody dogfoods is a position, not an architecture.
  *
- * SCOPE, deliberately narrow: the concurrency floor, the event stream, and cancellation. The
- * observation plane (SessionObserver / RunControls / the rich `SessionEvent` vocabulary), the tool
- * activation bridge, auto-compaction and session inheritance are NOT wired.
+ * Events are translated ONCE, into the rich `SessionEvent` vocabulary the observation plane speaks;
+ * the SPEC stream is a projection of that (`docs/design/session-control.md` §6 — one translation
+ * plus one projection, never two parallel ones).
  *
- * WHICH L0 SERVES: {@link createPiAgentFromHarness}, still — this one is reachable only from its
- * conformance test (deliberately absent from `src/pi.ts`), because a serving path needs the pieces
- * above. Its one known debt is {@link toAgentEvent}: translating pi events straight to SPEC
- * `AgentEvent`s is the second parallel translation `docs/design/session-control.md` §6 forbids. It
- * retires the moment this L0 grows the observation plane — the rich `SessionEvent` layer comes back
- * with it, and the harness L0 goes away.
+ * Two disciplines this file exists to hold:
+ * - the turn's outcome comes from the EVENT STREAM, never from an index into session state, which
+ *   compaction and overflow recovery both rewrite mid-turn;
+ * - `run_started` is published BEFORE the session is bound, so a dispatch racing the build queues on
+ *   the run's controls instead of finding no run.
  */
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { SessionInheritance } from "./session-inheritance.ts";
 import { type Agent } from "../../agent.ts";
-import { type Lease } from "./turn-kit.ts";
-/** Open-or-create the session behind `sessionId` and bind an `AgentSession` to it, per invoke. */
-export type PiAgentSessionFactory = (sessionId: string) => Promise<AgentSession>;
+import { type Lease, type SessionObserver } from "./turn-kit.ts";
+/** Open-or-create the session behind `sessionId` and bind an `AgentSession` to it, per invoke.
+ *  `inherit` reaches the CREATE path only — an existing session ignores it. */
+export type PiAgentSessionFactory = (sessionId: string, inherit?: SessionInheritance) => Promise<AgentSession>;
 export interface CreatePiAgentFromSessionOptions {
     sessionFactory: PiAgentSessionFactory;
     /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
     lease?: Lease;
+    /** Observation-plane tap: every rich event of every run, plus the run's live {@link RunControls}
+     *  on `run_started`. Optional; the SPEC stream is identical with or without it. */
+    observer?: SessionObserver;
 }
 export declare function createPiAgentFromSession(options: CreatePiAgentFromSessionOptions): Agent;