@fastagent-sh/fastagent 0.20.0 → 0.21.0

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

@@ -29,7 +29,7 @@ export interface FastagentConfig {
      * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
      * binds all interfaces by default, so the routes are LAN-reachable with the token as the only
      * protection — bind loopback (`--bind 127.0.0.1`; not `http.host`, which travels into a deployed
-     * image), firewall the port, or wrap it for real exposure (design §14).
+     * image), firewall the port, or wrap it for real exposure (docs/design/session-control.md §14).
      */
     sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a

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

@@ -1,16 +1,4 @@
-/**
- * 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).
- */
-import { type ExecutionEnv, type Skill, type ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
@@ -66,19 +54,14 @@ export interface AssembleSystemPromptOptions {
         path: string;
         content: string;
     }>;
-    /** ③ Skills for the <available_skills> listing. */
-    skills?: Skill[];
-    /** ④ Env context, caller-provided (keeps this function pure). Omitted = segment omitted. */
-    cwd?: string;
 }
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
 /**
- * INTERNAL seam (workspace ↔ assembly): hands the hub-wiring consumer the assembly's live parts —
- * 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.
+ * The assembly, as a value: what every rung builds and what the agent runs on. The opener hands it to
+ * the control plane too — boundary mutations contend on the SAME lease and validate against the SAME
+ * registry the runs use, which is only true if there is one of each to hand over.
  */
-export type PiAssemblyParts = {
+export interface PiAssembly {
     lease: Lease;
     sessionFactory: PiAgentSessionFactory;
     /** The registry and configured model, resolved on first use (a credential read is async). */
@@ -88,8 +71,9 @@ export type PiAssemblyParts = {
     }>;
     /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
     thinkingLevel: ThinkingLevel;
-};
-type OnAssembly = (parts: PiAssemblyParts) => void;
+}
+/** The agent an assembly runs as: the L0 over its lease and session factory. */
+export declare function agentOf(assembly: PiAssembly, observer?: SessionObserver): Agent;
 /** 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}. */
@@ -99,16 +83,15 @@ export interface CreatePiAgentOptions {
     /**
      * 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.
+     * a factory evaluated once per invoke, never during construction. Pi appends the skills listing
+     * when read is active.
      *
      * 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 — those bind their workspace at construction rather than reading a turn context. */
+    /** The tool set to mount: authored tools or pi's cwd-bound coding tools, both AgentTool. */
     tools?: MountedTool[];
     skills?: Skill[];
     /**
@@ -126,12 +109,9 @@ export interface CreatePiAgentOptions {
     /** 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. */
+    /** Supplies the working directory at L1 (default: process.cwd()), which loads no definition.
+     *  At L2 it also reads persona.md and skills/.
+     *  Tools and project-context discovery use the local process directly; this is not a sandbox. */
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
@@ -180,15 +160,18 @@ export interface CreatePiAgentFromDefinitionOptions {
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */
     observer?: SessionObserver;
-    /** INTERNAL seam for hub wiring; see {@link OnAssembly}. */
-    onAssembly?: OnAssembly;
 }
 /**
- * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
- * call. Returns the definition so callers can surface diagnostics/collisions.
+ * 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.
  */
+export declare function assemblePiFromDefinition(dir: string, options: Omit<CreatePiAgentFromDefinitionOptions, "observer">): Promise<{
+    assembly: PiAssembly;
+    definition: LoadedDefinition;
+}>;
+/** L2: "point at a directory → agent": {@link assemblePiFromDefinition} under the L0. */
 export declare function createPiAgentFromDefinition(dir: string, options: CreatePiAgentFromDefinitionOptions): Promise<{
     agent: Agent;
     definition: LoadedDefinition;
 }>;
-export {};

package/dist/engines/pi/create.js

@@ -9,15 +9,20 @@
  * 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.
  */
-import { formatSkillsForSystemPrompt, } from "@earendil-works/pi-agent-core";
+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 { 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 { withSearchTool } from "./search-tools.js";
 import { createPiAgentFromSession } from "./invoke-session.js";
 import { piAgentSessionFactory } from "./agent-session-factory.js";
@@ -50,7 +55,21 @@ import { inProcessLease } from "./turn-kit.js";
  */
 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");
+    const mutating = createCodingTools(cwd, {
+        bash: {
+            spawnHook(context) {
+                const { env } = context;
+                const id = env.PI_SESSION_ID;
+                delete env.PI_SESSION_ID_ENCODING;
+                // OS environment strings cannot preserve NUL or unpaired UTF-16 surrogates.
+                if (id !== undefined && (id.includes("\u0000") || toUSVString(id) !== id)) {
+                    env.PI_SESSION_ID = JSON.stringify(id);
+                    env.PI_SESSION_ID_ENCODING = "json";
+                }
+                return context;
+            },
+        },
+    }).filter((tool) => tool.name !== "read");
     return [...createReadOnlyTools(cwd), ...mutating];
 }
 /**
@@ -119,18 +138,7 @@ export async function resolveAgentTools(config, agentDir, cwd) {
         toolFailures: discovered.failures,
     };
 }
-// ── §2 prompt: four-segment systemPrompt assembly ───────────────────────────
-//
-//   systemPrompt = ① base (engine asset; a persona.md persona overrides its identity line)
-//                + ② project context (AGENTS.md files via pi's loadProjectContextFiles, <project_context>-wrapped)
-//                + ③ skills listing + ④ env context (cwd)
-//
-// AGENTS.md ≠ system prompt. Pure functions: segment ④ input (cwd) is caller-provided, so the
-// same inputs always produce the same prompt (testable, reproducible). No date: a date line would
-// invalidate the provider prompt cache (a prefix cache) for every session at each day boundary —
-// channel sessions routinely live for weeks (pi ≥0.80.7 dropped it from its default prompt for the
-// same reason). The model gets the date when it needs it: `bash date`, and the wake tool takes
-// relative delays ("30m") / cron — never an absolute now-derived instant.
+// 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
@@ -147,7 +155,7 @@ export function piBasePrompt(options = {}) {
     const deferredCount = mounted.length - tools.length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
-    // (core.md §11), keeping the tools list + guidelines below. Preserve pi's coding identity only for
+    // (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.
@@ -182,30 +190,23 @@ export function assembleSystemPrompt(options) {
         }
         prompt += `</project_context>\n`;
     }
-    if (options.skills && options.skills.length > 0) {
-        prompt += `\n${formatSkillsForSystemPrompt(options.skills)}\n`;
-    }
-    if (options.cwd)
-        prompt += `\nCurrent working directory: ${options.cwd}`;
     return prompt;
 }
-// ── §3 the reusable assembly ladder: L1 / L2 ────────────────────────────────
 /**
  * Shared low-level wiring: resolve the model spec against the collection, default the K ports, build
- * the agent. Internal — the public rungs decide the systemPrompt (L1 from instructions, L2 from the
+ * the parts. Internal — the public rungs decide the systemPrompt (L1 from instructions, L2 from the
  * directory) and route through here.
  */
-function buildPiAgent(opts) {
-    const env = opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() });
-    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.
+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.
     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 by the factory, and shared with the control plane below so a
-    // boundary mutation validates against the registry the runs actually use.
+    // caller's constructor. Memoized, and shared with the control plane so a boundary mutation
+    // validates against the registry the runs actually use.
     let engine;
     const resolveEngine = () => {
         engine ??= (async () => {
@@ -225,71 +226,56 @@ function buildPiAgent(opts) {
         engine: resolveEngine,
         thinkingLevel: opts.thinkingLevel,
         tools: opts.tools,
-        systemPrompt: opts.systemPrompt,
-        skills: opts.skills,
-        live: opts.live,
+        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.
         excludedToolNames: omittedBuiltinNames(opts.tools ?? [], cwd),
-        env,
     });
-    opts.onAssembly?.({
+    return {
         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,
-    });
-    return createPiAgentFromSession({ lease, observer: opts.observer, sessionFactory });
-}
-/**
- * L1 system prompt: `instructions` ARE the prompt (no engine base, no wrapping); the skills listing
- * is appended only when skills are mounted (the model must know what it can invoke). A factory so a
- * dynamic `instructions` and per-invoke freshness both work; undefined when there is nothing to send.
- */
-function instructionsPrompt(instructions, skills) {
-    const hasSkills = skills !== undefined && skills.length > 0;
-    if (instructions === undefined && !hasSkills)
-        return undefined;
-    return () => {
-        const prose = typeof instructions === "function" ? instructions() : (instructions ?? "");
-        const listing = hasSkills ? formatSkillsForSystemPrompt(skills) : "";
-        return [prose, listing].filter((s) => s !== "").join("\n");
     };
 }
+/** The agent an assembly runs as: the L0 over its lease and session factory. */
+export function agentOf(assembly, observer) {
+    return createPiAgentFromSession({ lease: assembly.lease, observer, sessionFactory: assembly.sessionFactory });
+}
 /** L1: assemble from typed parts. */
 export function createPiAgent(options) {
-    return buildPiAgent({
+    const { instructions, skills = [] } = options;
+    return agentOf(assemblePi({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
         providers: options.providers,
         authPath: options.authPath,
-        systemPrompt: instructionsPrompt(options.instructions, options.skills),
+        readDefinition: () => ({
+            systemPrompt: typeof instructions === "function" ? instructions() : instructions,
+            skills,
+        }),
         // Deferred tools need their loader on every rung (idempotent; the caller's own search_tools wins).
         tools: options.tools ? withSearchTool(options.tools) : options.tools,
-        skills: options.skills,
         sessions: options.sessions,
         env: options.env,
         lease: options.lease,
-        observer: options.observer,
-    });
+    }), options.observer);
 }
 /**
- * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
- * call. Returns the definition so callers can surface diagnostics/collisions.
+ * 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.
  */
-export async function createPiAgentFromDefinition(dir, options) {
+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.
     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 does NOT close over it — see `live` below.
+    // 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.
@@ -308,7 +294,7 @@ export async function createPiAgentFromDefinition(dir, options) {
     // 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({
+    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,
@@ -326,7 +312,7 @@ export async function createPiAgentFromDefinition(dir, options) {
         // 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.
-        live: async () => {
+        readDefinition: async () => {
             const def = await loadAgentDefinition(dir, { cwd, env });
             reportFindingsIfChanged(def.dir, def);
             return {
@@ -336,10 +322,6 @@ export async function createPiAgentFromDefinition(dir, options) {
                     base: options.base ?? piBasePrompt({ tools, persona: def.persona }),
                     // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
                     contextFiles: def.contextFiles,
-                    skills: def.skills,
-                    // 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,
             };
@@ -348,13 +330,16 @@ export async function createPiAgentFromDefinition(dir, options) {
         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.
+        // change without a restart, which is why this sits outside readDefinition above.
         extensionPaths: await loadExtensionPaths(dir, { cwd, env }),
         cwd,
         env,
         lease: options.lease,
-        observer: options.observer,
-        onAssembly: options.onAssembly,
     });
-    return { agent, definition };
+    return { assembly, definition };
+}
+/** L2: "point at a directory → agent": {@link assemblePiFromDefinition} under the L0. */
+export async function createPiAgentFromDefinition(dir, options) {
+    const { assembly, definition } = await assemblePiFromDefinition(dir, options);
+    return { agent: agentOf(assembly, options.observer), definition };
 }

package/dist/engines/pi/definition.js

@@ -15,7 +15,7 @@
  */
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { loadSkills } from "@earendil-works/pi-agent-core";
+import { BACKGROUND_CONTEXT, 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";
@@ -26,7 +26,7 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     // never diverge if a caller passes a relative agentDir.
     const cwd = options.cwd ?? agentDir;
     const e = options.env ?? new NodeExecutionEnv({ cwd });
-    const rootResult = await e.absolutePath(agentDir);
+    const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
     if (!rootResult.ok) {
         throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
     }
@@ -38,7 +38,7 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     // persona.md → segment ① persona (overrides the identity line). Same error policy as AGENTS.md:
     // only not_found means "absent"; any other read error surfaces rather than silently dropping the persona.
     const personaPath = join(root, "persona.md");
-    const personaRead = await e.readTextFile(personaPath);
+    const personaRead = await e.readTextFile(personaPath, BACKGROUND_CONTEXT);
     if (!personaRead.ok && personaRead.error.code !== "not_found") {
         throw new Error(`cannot read ${personaPath}: ${personaRead.error.message}`);
     }
@@ -86,13 +86,13 @@ export async function loadAgentDefinition(agentDir, options = {}) {
 export async function loadExtensionPaths(agentDir, options = {}) {
     const cwd = options.cwd ?? agentDir;
     const e = options.env ?? new NodeExecutionEnv({ cwd });
-    const rootResult = await e.absolutePath(agentDir);
+    const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
     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);
+    const listed = await e.listDir(dir, BACKGROUND_CONTEXT);
     if (!listed.ok) {
         if (listed.error.code === "not_found")
             return [];
@@ -138,7 +138,7 @@ export async function loadExtensionPaths(agentDir, options = {}) {
 async function firstRealFile(e, candidates) {
     let refused = false;
     for (const candidate of candidates) {
-        const info = await e.fileInfo(candidate);
+        const info = await e.fileInfo(candidate, BACKGROUND_CONTEXT);
         if (!info.ok) {
             if (info.error.code === "not_found")
                 continue;
@@ -164,7 +164,7 @@ async function readSkills(e, root) {
     // definition loads the same skills on every machine — and, like tools/channels/schedules, a symlink
     // that escapes the agent dir is refused rather than followed (the fourth of four surfaces).
     await assertInsideAgentDir(root, "skills");
-    const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")]);
+    const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")], BACKGROUND_CONTEXT);
     const byName = new Map();
     const collisions = [];
     for (const skill of raw) {
@@ -187,7 +187,7 @@ async function readSkills(e, root) {
 export async function loadAgentSkills(agentDir, options = {}) {
     const cwd = options.cwd ?? agentDir;
     const e = options.env ?? new NodeExecutionEnv({ cwd });
-    const rootResult = await e.absolutePath(agentDir);
+    const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
     if (!rootResult.ok)
         throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
     // `dir` is the RESOLVED root, like {@link LoadedDefinition.dir}: readers key per-definition state

package/dist/engines/pi/invoke-session.js

@@ -1,4 +1,5 @@
 import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { toRetryScheduledEvent } from "./retry-event.js";
 import { cancellableStream } from "../../collect.js";
 import { log } from "../../log.js";
 import { EventQueue, errorToTerminal, inProcessLease, projectAgentEvent, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
@@ -65,36 +66,9 @@ function toSessionEvent(event, runId) {
                 runId,
                 data: { steering: event.steering.length, followUp: event.followUp.length },
             };
-        case "auto_retry_start": {
-            const retry = {
-                type: "retry_scheduled",
-                timestamp: at,
-                runId,
-                data: {
-                    operation: "assistant",
-                    attempt: event.attempt,
-                    maxAttempts: event.maxAttempts,
-                    delayMs: event.delayMs,
-                    error: event.errorMessage,
-                },
-            };
-            return retry;
-        }
-        case "summarization_retry_scheduled": {
-            const retry = {
-                type: "retry_scheduled",
-                timestamp: at,
-                runId,
-                data: {
-                    operation: "compaction",
-                    attempt: event.attempt,
-                    maxAttempts: event.maxAttempts,
-                    delayMs: event.delayMs,
-                    error: event.errorMessage,
-                },
-            };
-            return retry;
-        }
+        case "auto_retry_start":
+        case "summarization_retry_scheduled":
+            return toRetryScheduledEvent(event, runId);
         default:
             return null;
     }
@@ -240,6 +214,15 @@ export function createPiAgentFromSession(options) {
                         return; // decided; the retry's output is not ours
                     if (event.type === "message_end" && event.message.role === "assistant") {
                         finalAssistant = event.message;
+                        // Error messages and details can contain provider payloads; log only diagnostic metadata.
+                        for (const diagnostic of finalAssistant.diagnostics ?? []) {
+                            log.warn(`[fastagent] provider diagnostic ${diagnostic.type} (${finalAssistant.provider}/${finalAssistant.model}, session ${scope.session}, run ${runId})`);
+                        }
+                    }
+                    if (event.type === "compaction_end" && event.reason !== "manual") {
+                        const status = event.aborted ? "aborted" : event.errorMessage ? "failed" : "completed";
+                        const emit = event.errorMessage && !event.aborted ? log.warn : log.debug;
+                        emit(`[fastagent] automatic compaction ${event.reason} (session ${scope.session}, run ${runId}): ${status}`);
                     }
                     // pi retries a failed assistant request by DISCARDING that attempt's assistant message and
                     // asking again. Everything the turn achieved before it survives — executed tools keep

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

@@ -36,8 +36,8 @@ export interface CreatePiAgentFromDirOptions {
     sessionControl?: boolean;
     /** Additional raw tap with the FULL vocabulary: run events composed after the
      *  {@link sessionControl} hub's observer, plus the hub's own boundary-mutation events
-     *  (`state_changed`/`compaction_*`) via the hub's tap. TRUSTED seam: since Phase 2a an observer
-     *  receives each run's live modulation handles (see `SessionObserver`) — for read-only consumers
+     *  (`state_changed`/`compaction_*`) via the hub's tap. TRUSTED seam: an observer receives each
+     *  run's live modulation handles (see `SessionObserver`) — for read-only consumers
      *  use the hub's `events()` stream instead. */
     observer?: SessionObserver;
 }

package/dist/engines/pi/open.js

@@ -11,7 +11,7 @@
 import { mkdir } from "node:fs/promises";
 import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, } from "./config.js";
 import { resolveStateRoot, resolvePlacement } from "../../paths.js";
-import { createPiAgentFromDefinition, resolveAgentTools } from "./create.js";
+import { agentOf, assemblePiFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
 import { loadAgentSkills } from "./definition.js";
@@ -63,19 +63,36 @@ export async function createPiAgentFromDir(dir, options = {}) {
     const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
     await mkdir(sessionsDir, { recursive: true });
     const sessions = piSessionRecordStore({ dir: sessionsDir, cwd: workspace });
-    // The hub is wired HERE because the store is created here: chicken-and-egg otherwise (the hub
-    // needs the store; the agent needs the hub's observer). Boundary parts (factory/lease/registry)
-    // only exist after the assembly below — the hub takes them as a lazy thunk, filled by the
-    // assembly's onAssembly callback (assembly completes before this function returns, so every
-    // dispatch sees them). An extra caller observer composes after the hub's (TRUSTED seam).
-    let boundaryParts;
-    let assembled;
+    const { assembly, definition } = await assemblePiFromDefinition(agentDir, {
+        model: modelSpec,
+        thinkingLevel: config.thinkingLevel,
+        cwd: workspace,
+        tools: mountedTools,
+        authPath,
+        // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
+        sessions,
+    });
+    // The hub is wired HERE because the store is created here (an external `createPiSessionControl`
+    // cannot exist before the store does). Its writes contend on the assembly's own lease and validate
+    // against its own registry — the value above is what makes "same" true. An extra caller observer
+    // composes after the hub's (TRUSTED seam).
     const caller = options.observer;
     const wantControl = options.sessionControl ?? (config.sessionControl === true && options.serving === true);
-    const hub = wantControl
-        ? createPiSessionControl({
+    let hub;
+    if (wantControl) {
+        // The hub's surface is synchronous (`capabilities()` lists the allowed models), while building
+        // the registry reads credentials and is not. Resolve it ONCE here — the opener is async anyway,
+        // and the first turn would have paid the same read — so every boundary mutation validates
+        // against the same registry the runs use.
+        const { modelRuntime, model } = await assembly.engine();
+        hub = createPiSessionControl({
             sessions,
-            boundary: () => boundaryParts,
+            boundary: {
+                lease: assembly.lease,
+                models: modelRuntime,
+                sessionFactory: assembly.sessionFactory,
+                defaults: { model, thinkingLevel: assembly.thinkingLevel },
+            },
             // Skills ARE the names a client offers — the resolved set, after collisions were decided
             // first-wins, which a client cannot reconstruct from the directory. Read LIVE (the directory
             // is the agent: a skill added while serving is in play on the next turn, so it must be
@@ -97,8 +114,8 @@ export async function createPiAgentFromDir(dir, options = {}) {
             // and never cross the data plane's observer seam — without this, an audit tap wired here
             // would miss exactly the mutations it most needs to see (`update({ model })`).
             tap: caller ? (session, event) => caller(session, event) : undefined,
-        })
-        : undefined;
+        });
+    }
     const observer = hub
         ? caller
             ? (session, event, run) => {
@@ -107,34 +124,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
             }
             : hub.observer
         : caller;
-    const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
-        model: modelSpec,
-        thinkingLevel: config.thinkingLevel,
-        cwd: workspace,
-        tools: mountedTools,
-        authPath,
-        // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
-        sessions,
-        observer,
-        onAssembly: hub
-            ? (parts) => {
-                assembled = parts;
-            }
-            : undefined,
-    });
-    if (hub && assembled) {
-        // The hub's surface is synchronous (`capabilities()` lists the allowed models), while building
-        // the registry reads credentials and is not. Resolve it ONCE here — the opener is async anyway,
-        // and the first turn would have paid the same read — so every boundary mutation validates
-        // against the same registry the runs use.
-        const { modelRuntime, model } = await assembled.engine();
-        boundaryParts = {
-            lease: assembled.lease,
-            models: modelRuntime,
-            sessionFactory: assembled.sessionFactory,
-            defaults: { model, thinkingLevel: assembled.thinkingLevel },
-        };
-    }
+    const agent = agentOf(assembly, observer);
     return {
         agent,
         definition,

package/dist/engines/pi/retry-event.d.ts

@@ -0,0 +1,6 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { RetryScheduledEvent } from "../../session.ts";
+/** Manual compaction retries are session-scoped; retries inside an invoke carry its runId. */
+export declare function toRetryScheduledEvent(event: Extract<AgentSessionEvent, {
+    type: "auto_retry_start" | "summarization_retry_scheduled";
+}>, runId?: string): RetryScheduledEvent;