@fastagent-sh/fastagent 0.19.0 → 0.21.0

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 { 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.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+import { type ExecutionEnv, type Skill, type SkillDiagnostic } from "@earendil-works/pi-agent-core";
 /** A same-name skill collision (the discarded side). Surfaced, never swallowed. */
 export interface SkillCollision {
     name: string;

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 [];
@@ -131,15 +131,14 @@ export async function loadExtensionPaths(agentDir, options = {}) {
     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 candidate that is a REAL file, and whether one was found but REFUSED as a symlink.
+ * `exists` would follow the link, 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);
+        const info = await e.fileInfo(candidate, BACKGROUND_CONTEXT);
         if (!info.ok) {
             if (info.error.code === "not_found")
                 continue;
@@ -165,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) {
@@ -188,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/login.js

@@ -30,6 +30,18 @@ function authCallbacks(io, userSignal, doneSignal) {
         signal: userSignal ?? new AbortController().signal,
         prompt: async (p) => {
             if (p.type === "select") {
+                // This branch is UNCANCELLABLE: `LoginIO.select` takes no signal, so all three the line
+                // below composes — the provider's own, the caller's `loginFlow({ signal })`, and the
+                // pending-prompt backstop — are dropped here.
+                //
+                // It costs nothing against pi 0.84's providers, where every `select` is the FIRST call of
+                // `login()` (bedrock, vertex, openai-codex, radius — all of them asking which login method
+                // to use). Nothing is racing it: no callback server is up yet, and `doneSignal` fires when
+                // `auth.login()` RETURNS, which it cannot do while blocked on this await.
+                //
+                // That is a property of the providers, not a guarantee, and nothing here holds it. A
+                // provider that ever issues a `select` after starting its callback server shows up as the
+                // CLI parked on stdin — widen `LoginIO.select` with a signal then.
                 const v = await io.select(p.message, p.options.map((o) => ({ value: o.id, label: o.label, hint: o.description })));
                 if (v === undefined)
                     throw new LoginCancelled("cancelled");
@@ -94,9 +106,14 @@ async function selectProvider(io, providers, method, store) {
         return { value: p.id, label: auth?.name ?? p.name, hint: cred ? `configured (${cred.type})` : undefined };
     }));
     const id = await io.select("Select a provider", options);
-    if (!id)
+    // Answers the PROVIDER, not its id: the caller needs the object, and resolving it here means the
+    // one place that can fail to is the one that just offered the list. Cancel and an id that was
+    // never offered are the same answer — nothing was chosen — and `find` gives both, since a
+    // provider id is always a string and `undefined` matches none of them.
+    const chosen = candidates.find((p) => p.id === id);
+    if (!chosen)
         throw new LoginCancelled("no provider selected");
-    return id;
+    return chosen;
 }
 /**
  * Resolve method + provider (asking only what is not given), run the login flow, and persist. A no-op
@@ -106,26 +123,25 @@ export async function loginFlow(io, options = {}) {
     const store = options.store ?? fastagentCredentialStore(options.authPath ?? GLOBAL_AUTH_PATH);
     const providers = options.providers ?? builtinProviders();
     let method;
-    let providerId;
+    let provider;
     if (options.provider) {
-        providerId = options.provider;
-        const p = providers.find((x) => x.id === providerId);
-        if (!p)
-            throw new Error(`unknown provider "${providerId}"`);
-        method = options.method ?? (await methodForProvider(io, p));
+        const named = providers.find((x) => x.id === options.provider);
+        if (!named)
+            throw new Error(`unknown provider "${options.provider}"`);
+        provider = named;
+        method = options.method ?? (await methodForProvider(io, provider));
     }
     else {
         method = options.method ?? (await selectMethod(io));
-        providerId = await selectProvider(io, providers, method, store);
+        provider = await selectProvider(io, providers, method, store);
     }
     // Preflight: a no-op modify runs the refuse-corrupt / writability check BEFORE the flow.
-    await store.modify(providerId, async () => undefined);
-    const provider = providers.find((p) => p.id === providerId);
-    if (!provider)
-        throw new Error(`unknown provider "${providerId}"`);
+    await store.modify(provider.id, async () => undefined);
+    // Reachable even though both branches above resolved a provider: an explicit `method` bypasses
+    // methodForProvider, so `{ provider: "openai-codex", method: "api_key" }` arrives here.
     const auth = method === "oauth" ? provider.auth.oauth : provider.auth.apiKey;
     if (!auth?.login)
-        throw new Error(`provider "${providerId}" has no ${method} login`);
+        throw new Error(`provider "${provider.id}" has no ${method} login`);
     // `done` cancels any prompt left pending when login resolves (manual-code race backstop).
     const done = new AbortController();
     let credential;
@@ -135,6 +151,6 @@ export async function loginFlow(io, options = {}) {
     finally {
         done.abort();
     }
-    await store.modify(providerId, async () => credential);
-    return { provider: providerId, method };
+    await store.modify(provider.id, async () => credential);
+    return { provider: provider.id, method };
 }

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

@@ -5,8 +5,7 @@ import type { SessionObserver } from "./turn-kit.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import { type PiSessionRecordStore } from "./session-store.ts";
-import type { ToolCollision } from "./tool.ts";
-import type { MountedTool } from "./tool.ts";
+import type { ToolCollision, MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {
     /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;
@@ -37,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
@@ -95,10 +112,10 @@ export async function createPiAgentFromDir(dir, options = {}) {
             },
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
             // 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 (set_model).
+            // 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;

package/dist/engines/pi/retry-event.js

@@ -0,0 +1,15 @@
+/** Manual compaction retries are session-scoped; retries inside an invoke carry its runId. */
+export function toRetryScheduledEvent(event, runId) {
+    return {
+        type: "retry_scheduled",
+        timestamp: Date.now(),
+        ...(runId === undefined ? {} : { runId }),
+        data: {
+            operation: event.type === "auto_retry_start" ? "assistant" : "compaction",
+            attempt: event.attempt,
+            maxAttempts: event.maxAttempts,
+            delayMs: event.delayMs,
+            error: event.errorMessage,
+        },
+    };
+}