@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/create.js

@@ -1,28 +1,16 @@
 /**
- * Agent assembly (configuration-time): the engine assets (tools, prompt) plus the reusable ladder
- * that puts a pi agent together.
- *
- *   L2  createPiAgentFromDefinition(dir, options)   — load a definition directory, assemble, then L1.
- *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
- *   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).
- *
- * Every rung assembles the same VALUE first — a {@link PiAssembly}: the lease, the session factory
- * and the engine thunk — and the agent is that value under the L0. The opener needs the value
- * itself (the control plane contends on the same lease and validates against the same registry), so
- * `assemblePiFromDefinition` hands it out and `createPiAgentFromDefinition` is it plus the L0.
+ * Agent assembly (configuration-time): the engine assets (tools, prompt) plus the reusable ladder that puts a pi agent
+ * together.
  */
 import { toUSVString } from "node:util";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { createCodingTools, createPowerShellTool, createReadOnlyTools, } from "@earendil-works/pi-coding-agent";
-import { defaultAuthPath, resolveModel } from "./config.js";
-import { resolveSecretsDir } from "../../paths.js";
+import { resolveAuthLayers, resolveModel } from "./config.js";
+import { isAgentcoreRuntime, isDeployedWorkspace } from "../../paths.js";
 import { loadAgentDefinition, loadExtensionPaths } from "./definition.js";
 import { reportFindingsIfChanged } from "./report.js";
-import { isDeferredTool, loadTools, mergeDiscoveredTools } from "./tool.js";
+import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
+import { readSecretDeclaration } from "../../declared-secrets.js";
 import { withSearchTool } from "./search-tools.js";
 import { createPiAgentFromSession } from "./invoke-session.js";
 import { piAgentSessionFactory } from "./agent-session-factory.js";
@@ -31,27 +19,10 @@ import { piInMemorySessionRecordStore } from "./session-store.js";
 import { inProcessLease } from "./turn-kit.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
-// 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`.
-//
-// 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.
-//
-// 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 receives the same tool objects through pi's `customTools` path; pi's builtin copies stay off.
+// A directory agent gets every pi coding tool.
 /**
- * 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.
+ * 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.
  */
 export const CODING_TOOL_NAMES = ["read", "grep", "find", "ls", "bash", "edit", "write"];
 export function piAllCodingTools(cwd) {
@@ -72,14 +43,7 @@ export function piAllCodingTools(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.
- */
+/** Every tool an `AgentSession` registers on its own, whether or not a directory agent mounts it. */
 function piRegisteredToolNames(cwd) {
     return [
         ...createReadOnlyTools(cwd).map((tool) => tool.name),
@@ -87,24 +51,26 @@ function piRegisteredToolNames(cwd) {
         createPowerShellTool(cwd).name,
     ];
 }
-/** Built-ins omitted by an explicit lower-level tool list. A reused name stays mounted. */
+/** Built-ins omitted by an explicit lower-level tool list. */
 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 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.
+ * 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.
  */
 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.
+    // Discovered `tools/` come from `agentDir` (the agent's own surface); the coding tools are rooted at `cwd`, the
+    // WORKSPACE.
     const discovered = await loadTools(agentDir);
     const configured = piAllCodingTools(cwd);
     const configuredNames = new Set(configured.map((tool) => tool.name));
     const configuredCollisions = [];
+    // The config.tools that actually MOUNT — collected here rather than re-derived from `config.tools`
+    // afterwards, so a tool dropped for sharing a coding tool's name cannot contribute a declaration
+    // (its body never runs, and gating a start on its secret would refuse to serve for nothing).
+    const mountedConfigTools = [];
     for (const tool of config.tools ?? []) {
         if (configuredNames.has(tool.name)) {
             configuredCollisions.push({ name: tool.name, source: "config.tools" });
@@ -112,20 +78,19 @@ export async function resolveAgentTools(config, agentDir, cwd) {
         }
         configuredNames.add(tool.name);
         configured.push(tool);
+        mountedConfigTools.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).
+    // The built-in `search_tools` loader mounts here.
     const tools = withSearchTool(merged.tools);
-    // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire
-    // on the deferred-authored-loader case, where withSearchTool returns a new array without adding one).
+    // 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, ...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`.
+    // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/).
+    // The discovered tools that were DROPPED (a coding tool or config.tools already owns the name):
+    // asking the mounted set instead would read the winner's name as proof the loser is mounted.
+    const shadowed = new Set(merged.collisions.map((c) => c.name));
     const defaultNames = new Set(CODING_TOOL_NAMES);
     const toolNames = tools
         .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
@@ -136,29 +101,35 @@ export async function resolveAgentTools(config, agentDir, cwd) {
         deferredToolNames: tools.filter(isDeferredTool).map((t) => t.name),
         toolCollisions,
         toolFailures: discovered.failures,
+        // Mounted only, and config.tools are FastagentTools too, so a programmatic tool declares the
+        // same way a file does.
+        toolSecrets: new Map([
+            ...[...discovered.secrets].filter(([name]) => !shadowed.has(name)),
+            // A programmatic tool declares the same way a file does. The source names the ENTRY, not just
+            // the list: `source` has to point at something the author can find, and "config.tools" alone
+            // locates nothing when the list has several tools. The shape was already refused by config
+            // validation (config.ts), so a throw here means a FastagentConfig assembled in code bypassed
+            // it — still the caller's own object, so it fails loudly rather than being isolated.
+            ...mountedConfigTools.map((tool) => {
+                const declaration = readSecretDeclaration(tool, `config.tools "${tool.name}"`);
+                if (declaration.error !== undefined)
+                    throw new Error(declaration.error);
+                return [tool.name, declaration.secrets];
+            }),
+        ]),
     };
 }
 // Fastagent owns identity and project context; Pi appends skills and cwd for both serving and chat.
-/**
- * The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two
- * deviations: the pi-TUI docs section is dropped (those paths don't exist in deployments), and the
- * tool list is generated from the actually-mounted tools (base and toolset must agree). An authored
- * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
- */
+/** The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two deviations. */
 export function piBasePrompt(options = {}) {
     const mounted = options.tools ?? [];
-    // Deferred tools stay OUT of the list: their schemas are not in the request until activated, so
-    // naming them here would invite calls to tools that don't exist yet; discovery is search_tools' job
-    // (which IS listed — it's active). Computed from the static mounted set, so the prompt — the cached
-    // context prefix — does not change when a tool is activated mid-session.
+    // Deferred tools stay OUT of the list: their schemas are not in the request until activated, so naming them here
+    // would invite calls to tools that don't exist yet.
     const tools = mounted.filter((t) => !isDeferredTool(t));
     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 §2), 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.
+    // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line (core.md §2),
+    // keeping the tools list + guidelines below.
     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() ||
@@ -168,6 +139,23 @@ export function piBasePrompt(options = {}) {
     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.`
         : "";
+    // What takes effect when, and the agent's own path to a new capability, are the same on every host; only how long
+    // the storage lives differs, below. The skill it writes lives in the definition directory, which the next
+    // deployment replaces (or, on AgentCore, erases with everything else) — so the sentence says so, and where a skill
+    // that should outlast it has to go. A skill outside the definition would survive, but it is machine state, read
+    // once per process (machine.ts), so it would not be live.
+    const RUNTIME_CHANGES = ` Markdown definition files are read each turn; changes to tools, channels or configuration take effect when the service restarts. To give yourself a new capability now, write a skill — a SKILL.md in your definition's skills/ directory, with any script it needs run through bash. It lasts until the next deployment replaces that directory, so a capability that should outlast it belongs in the author's release: propose it to them.${
+    // Named only when mounted (a serve; not a one-shot invoke), like the deferred tools above: naming a tool the model does not
+    // have invites calls to it.
+    mountedNames.has("wake") ? " To schedule your own follow-up work, use the wake tool." : ""}`;
+    // How long the storage lives is the HOST's answer, not a deployment-wide one: AgentCore's managed
+    // mount is reset by every deploy, so telling that agent to keep work "outside the definition" would
+    // name a location its next deploy erases.
+    const deploymentNote = !isDeployedWorkspace()
+        ? ""
+        : isAgentcoreRuntime()
+            ? `\n\nYour workspace survives restarts, including uncommitted work; /tmp does not. Every deployment of a new version resets this host's storage entirely, so anything that must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database).${RUNTIME_CHANGES}`
+            : `\n\nYour workspace survives restarts and deployments, including uncommitted work; /tmp does not. A new deployment replaces your definition directory with the author's release, so keep ongoing project work outside it.${RUNTIME_CHANGES}`;
     return `${identity}
 
 Available tools:
@@ -177,7 +165,7 @@ In addition to the tools above, you may have access to other custom tools depend
 
 Guidelines:
 - Be concise in your responses
-- Show file paths clearly when working with files`;
+- Show file paths clearly when working with files${deploymentNote}`;
 }
 export function assembleSystemPrompt(options) {
     let prompt = options.base;
@@ -192,29 +180,22 @@ export function assembleSystemPrompt(options) {
     }
     return prompt;
 }
-/**
- * Shared low-level wiring: resolve the model spec against the collection, default the K ports, build
- * the parts. Internal — the public rungs decide the systemPrompt (L1 from instructions, L2 from the
- * directory) and route through here.
- */
+/** Shared low-level wiring: resolve the model spec against the collection, default the K ports, build the parts. */
 function assemblePi(opts) {
     const cwd = opts.cwd ?? opts.env?.cwd ?? process.cwd();
-    // Materialized here (not defaulted inside the L0) so the value carries the SAME lease instance the
-    // agent runs under — boundary mutations must contend on it.
+    // Materialized here (not defaulted inside the L0) so the value carries the SAME lease instance the agent runs under
+    // — boundary mutations must contend on it.
     const lease = opts.lease ?? inProcessLease();
     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, and shared with the control plane so a boundary mutation
-    // validates against the registry the runs actually use.
+    // The model and its runtime resolve on FIRST 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.
+            // 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({ auth: opts.auth }));
+            // 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) };
@@ -228,10 +209,9 @@ function assemblePi(opts) {
         tools: opts.tools,
         readDefinition: opts.readDefinition,
         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.
+        // `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),
     });
     return {
@@ -239,6 +219,7 @@ function assemblePi(opts) {
         sessionFactory,
         engine: resolveEngine,
         thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+        extensionPaths: opts.extensionPaths ?? [],
     };
 }
 /** The agent an assembly runs as: the L0 over its lease and session factory. */
@@ -252,7 +233,7 @@ export function createPiAgent(options) {
         model: options.model,
         thinkingLevel: options.thinkingLevel,
         providers: options.providers,
-        authPath: options.authPath,
+        ...(options.authPath !== undefined ? { auth: { path: options.authPath } } : {}),
         readDefinition: () => ({
             systemPrompt: typeof instructions === "function" ? instructions() : instructions,
             skills,
@@ -265,60 +246,49 @@ export function createPiAgent(options) {
     }), options.observer);
 }
 /**
- * L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. Returns the
- * definition so callers can surface diagnostics/collisions. The opener consumes this form because
- * the control plane needs the parts; {@link createPiAgentFromDefinition} is it plus the L0.
+ * THE model registry an agent directory runs on: pi's built-ins, the directory's own `models.json` (custom endpoints
+ * are definition data and travel with the artifact) layered over the machine's `~/.fastagent/models.json` (environment,
+ * which does not travel), and any injected Provider instance, over the given credentials.
+ * The directory rung assembles from it and `availableModelsFromDir` lists from it, so a layer added here reaches both.
  */
-export async function assemblePiFromDefinition(dir, options) {
-    // `dir` = the agent-definition dir (persona.md/skills/); `cwd` (default = dir) is the run root where
-    // tools operate and whose ancestors are walked for ② context.
+export function definitionModelRuntime(dir, options) {
+    return createPiModelRuntime({ agentDir: dir, ...options });
+}
+/** L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. */
+export async function assemblePiFromDefinition(dir, 
+/** `auth` is the opener's already-resolved layers, which take the place of `authPath`. */
+options) {
+    // `dir` = the agent-definition dir (persona.md/skills/); `cwd` (default = dir) is the run root where tools operate
+    // and whose ancestors are walked for ② context.
     const cwd = options.cwd ?? dir;
     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 re-reads it through readDefinition below.
-    // `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.
+    // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to report
+    // (skills/diagnostics/collisions).
     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.
+    // 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 ?? 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).
+    // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by the resolved
+    // dir).
     reportFindingsIfChanged(definition.dir, definition);
-    // 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 auth = options.auth ?? (options.authPath === undefined ? resolveAuthLayers(dir) : { path: options.authPath });
     const assembly = assemblePi({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        // 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).
-        // One read yields prompt AND skills (they can never diverge), and the
-        // fs cost is a few reads against a model call. Broken edits stay visible: a throw-class problem
-        // (unreadable AGENTS.md) fails that turn's invoke, and the loader's NON-fatal findings (bad
-        // SKILL.md frontmatter, name collisions — returned as data, not thrown) are warned the moment
-        // the finding set changes (boot findings are the baseline) — a runtime-written bad skill must
-        // not silently vanish from the agent, and a static one must not spam every turn's log. The
-        // next good edit heals both.
+        models: await definitionModelRuntime(dir, {
+            auth,
+            ...(options.providers ? { providers: options.providers } : {}),
+        }),
+        // 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).
         readDefinition: async () => {
             const def = await loadAgentDefinition(dir, { cwd, env });
             reportFindingsIfChanged(def.dir, def);
             return {
                 systemPrompt: assembleSystemPrompt({
-                    // Segment ①: an authored persona (persona.md, def.persona) overrides the engine identity,
-                    // re-read per turn like AGENTS.md so edits go live; options.base still wins for full control.
+                    // Segment ①: an authored persona (persona.md, def.persona) overrides the engine identity, re-read per turn
+                    // like AGENTS.md so edits go live.
                     base: options.base ?? piBasePrompt({ tools, persona: def.persona }),
                     // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
                     contextFiles: def.contextFiles,
@@ -328,9 +298,6 @@ export async function assemblePiFromDefinition(dir, options) {
         },
         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 readDefinition above.
         extensionPaths: await loadExtensionPaths(dir, { cwd, env }),
         cwd,
         env,

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

@@ -1,25 +1,21 @@
 import { type ExecutionEnv, type Skill, type SkillDiagnostic } from "@earendil-works/pi-agent-core";
-/** A same-name skill collision (the discarded side). Surfaced, never swallowed. */
+/** A same-name skill collision (the discarded side). */
 export interface SkillCollision {
     name: string;
     winnerPath: string;
     loserPath: string;
 }
-/** Result of loading a definition directory. Produced by {@link loadAgentDefinition}. */
+/** Result of loading a definition directory. */
 export interface LoadedDefinition {
-    /**
-     * Project-context files feeding segment ② `<project_context>`, sourced via pi's `loadProjectContextFiles`:
-     * the agentDir's own AGENTS.md/CLAUDE.md FIRST, then every AGENTS.md from root down to `cwd` (so the
-     * file nearest `cwd` comes LAST — pi's array order). Empty when none exist. This WALKS cwd's ancestors (pi's coding-agent behaviour) — see core.md §6.
-     */
+    /** Project-context files feeding segment ② `<project_context>`, sourced via pi's `loadProjectContextFiles`. */
     contextFiles: Array<{
         path: string;
         content: string;
     }>;
     /**
-     * Verbatim `persona.md` content — the authored persona that OVERRIDES segment ①'s identity line
-     * (piBasePrompt keeps the tool list + guidelines; NOT a full system-prompt replacement — that is L1
-     * createPiAgent's `instructions`). undefined when absent → segment ① is the default engine identity.
+     * Verbatim `persona.md` content — the authored persona that OVERRIDES segment ①'s identity line (piBasePrompt keeps
+     * the tool list + guidelines; NOT a full system-prompt replacement — that is L1 createPiAgent's `instructions`).
+     * undefined when absent → segment ① is the default engine identity.
      */
     persona?: string;
     skills: Skill[];
@@ -31,62 +27,23 @@ export interface LoadedDefinition {
     dir: string;
 }
 export interface LoadAgentDefinitionOptions {
-    /**
-     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`.
-     * The opener passes the workspace instead, so an agent that lives in `agentDir` picks up the
-     * project's AGENTS.md up the tree (core.md scenario grid).
-     */
+    /** Working directory whose ancestors are walked for context files (segment ②). */
     cwd?: string;
     env?: ExecutionEnv;
 }
-/** 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.
+ * 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. */
 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
- * names and must not pay the full load's ② context walk (every AGENTS.md from cwd to root) for them.
- * The control plane's `commands()` is that reader, called when a composer opens its completion list.
+ * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same loader, same
+ * containment guard, same first-wins collision rule).
  */
 export declare function loadAgentSkills(agentDir: string, options?: {
     cwd?: string;
@@ -97,6 +54,5 @@ export declare function loadAgentSkills(agentDir: string, options?: {
     collisions: SkillCollision[];
     dir: string;
 }>;
-/** 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. */
+/** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath. */
 export declare function canonicalPath(p: string): string;