@fastagent-sh/fastagent 0.23.0 → 0.24.1

package/dist/engines/pi/agent-session-factory.js

@@ -3,45 +3,15 @@
  * durable record, per invoke.
  */
 import { dirname } from "node:path";
-import { readMachine, withMachine } from "./machine.js";
-import { ExtensionRunner, ModelRegistry, SessionManager, DefaultResourceLoader, createAgentSessionFromServices, getAgentDir, initTheme, } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_EXTENSIONS, DISCOVERY, readMachine, withMachine } from "./machine.js";
+import { ExtensionRunner, ModelRegistry, SessionManager, createAgentSessionServices, createCodemodeExtension, createToolSearchExtension, createAgentSessionFromServices, getAgentDir, initTheme, } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
-import { isDeferredTool } from "./tool.js";
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
+import { resolveModel } from "./config.js";
 import { activePath, resolveSessionSettings } from "./session-settings.js";
-import { DEFAULT_THINKING_LEVEL } from "./models.js";
+import { DEFAULT_THINKING_LEVEL, withModelRegistration } from "./models.js";
+import { registerAccountModels } from "./openai-account-models.js";
 import { agentSessionManager, sessionToolActivation, turnContext } from "./tool-context.js";
-/**
- * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred tools a loader
- * activated in that call.
- *
- * Not replaceable by pi's own transcript record. Since 0.86 the journal carries `toolsAdded` system messages and
- * `getCurrentTools()` replays them, but that answers a different question: it reports every tool ever DECLARED to
- * the model, which cannot tell a tool this conversation DISCOVERED from one that merely happened to be in the
- * initial set at the time. Restoring from it would keep a tool later flipped to `deferred` active in sessions that
- * never discovered it. This entry holds only what a loader activated, which is what makes the restore below
- * "today's non-deferred tools PLUS what this conversation found".
- */
-const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
-/** Every deferred tool this session has ever discovered, oldest first. */
-function recordedActivations(session) {
-    const names = [];
-    for (const entry of session.sessionManager.getBranch()) {
-        const record = entry;
-        if (record.type !== "custom" || record.customType !== TOOL_ACTIVATION_ENTRY)
-            continue;
-        if (Array.isArray(record.data?.names)) {
-            for (const name of record.data.names)
-                if (typeof name === "string")
-                    names.push(name);
-        }
-    }
-    return names;
-}
-/**
- * Warned once per session+missing set: a fresh session is built per invoke and channel sessions run for weeks, so an
- * un-deduped warn would repeat every turn and dilute its own signal.
- */
-const warnedDroppedActivations = new Set();
 /** fastagent's tools as pi tool definitions, bound to ONE session. */
 function toolDefinitions(tools, bound, sessionId) {
     return tools.map((tool) => ({
@@ -72,14 +42,22 @@ function toolDefinitions(tools, bound, sessionId) {
         },
     }));
 }
+/** The {@link DISCOVERY} tools the mounted tools' exposures need. A disabled extension's name is ignored by Pi. */
+function discoveryToolNames(tools) {
+    const names = new Set();
+    for (const tool of tools) {
+        if (tool.exposure === "codemode" || tool.exposure === "deferred")
+            names.add(DISCOVERY[tool.exposure].tool);
+    }
+    return [...names];
+}
 /**
- * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context, pi's own tool
- * copies kept off, and deferral applied.
+ * Bind ONE pi session to a record: authored tools replace same-name built-ins; Pi owns exposure and discovery.
  */
 export async function bindPiSession(options) {
-    const { services, sessionManager, model, thinkingLevel, tools, cwd, recordActivations } = options;
+    const { services, sessionManager, model, thinkingLevel, tools, cwd } = options;
     const excludedToolNames = options.excludedToolNames ?? [];
-    const deferred = tools.filter(isDeferredTool).map((t) => t.name);
+    const history = sessionManager.buildSessionContext().messages;
     const bound = {};
     const sessionId = options.sessionId ?? sessionManager.getSessionId();
     const result = await createAgentSessionFromServices({
@@ -88,8 +66,6 @@ export async function bindPiSession(options) {
         ...(options.sessionStartEvent ? { sessionStartEvent: options.sessionStartEvent } : {}),
         model,
         thinkingLevel,
-        // pi would otherwise mount its built-ins on top of fastagent's copies, offering duplicate names.
-        noTools: "builtin",
         ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
         customTools: toolDefinitions(tools, bound, sessionId),
     });
@@ -100,86 +76,59 @@ export async function bindPiSession(options) {
         context: {
             cwd,
             sessionManager: agentSessionManager(session, sessionId),
-            // Persist each discovery so a served session can restore it on its next turn.
-            tools: sessionToolActivation(session, recordActivations
-                ? (added) => session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added })
-                : undefined),
+            tools: sessionToolActivation(session),
         },
     };
-    // Deferral, then restoration: pi starts every mounted tool active, so narrow by SUBTRACTING the deferred names
-    // (robust to pi mounting tools of its own, unlike an exact-set replacement), then add back what THIS session has
-    // already discovered.
-    if (deferred.length > 0) {
-        const active = session.getActiveToolNames();
-        const mounted = new Set(session.getAllTools().map((tool) => tool.name));
-        const recorded = recordActivations ? recordedActivations(session) : [];
-        // A recorded name that is no longer mounted is dropped rather than replayed.
-        const restored = recorded.filter((name) => mounted.has(name));
-        const dropped = recorded.filter((name) => !mounted.has(name));
-        if (dropped.length > 0) {
-            const key = `${sessionId}\u0000${[...new Set(dropped)].sort().join(",")}`;
-            const emit = warnedDroppedActivations.has(key) ? log.debug : log.warn;
-            warnedDroppedActivations.add(key);
-            emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${[...new Set(dropped)].join(", ")}`);
-        }
-        const next = [...new Set([...active.filter((name) => !deferred.includes(name)), ...restored])];
-        if (next.length !== active.length || next.some((name) => !active.includes(name))) {
-            session.setActiveToolsByName(next);
-        }
-    }
+    // The SDK always supplies an initial loadout (settings' defaultTools applied), bypassing AgentSession's native
+    // transcript restore. The loadout is the definition's defaults as they are NOW, plus whatever the transcript still
+    // declares and is still mounted (a discovery). Removals in the transcript are not honored: fastagent's own activation
+    // only adds, so a removal records a turn on which the definition did not mount the tool, not the conversation's
+    // choice, and honoring it would keep a tool out of a long-lived chat after a release that briefly lacked it.
+    // Replayed through Pi's public APIs, for serving and chat alike.
+    const defaults = [...session.getActiveToolNames(), ...discoveryToolNames(tools)];
+    const current = getCurrentSystemMessage(history);
+    const mounted = new Set(session.getAllTools().map((tool) => tool.name));
+    const declared = (current?.toolsAdded ?? []).map((tool) => tool.name);
+    const dropped = declared.filter((name) => !mounted.has(name));
+    // Debug, not warn: `session_start` handlers register their tools after this point, and Pi activates the
+    // default-active ones when they do (`_refreshToolRegistry`), so an absence here is routine on every such bind.
+    if (dropped.length)
+        log.debug(`[fastagent] session ${sessionId}: not mounted yet or removed: ${dropped.join(", ")}`);
+    session.setActiveToolsByName([...defaults, ...declared.filter((name) => mounted.has(name))]);
     return result;
 }
-/** Each distinct load failure is said once per process: serving loads the extensions again for every session. */
-const reportedExtensionErrors = new Set();
+let themeReady = false;
+/** Each distinct load diagnostic is said once per process: serving loads the extensions again for every session. */
+const reportedExtensionDiagnostics = new Set();
 /**
- * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and carries on with the
- * rest.
+ * Extension notifications said once per process at their own level, then at debug: every served turn starts the
+ * extensions again, so a notification from `session_start` would otherwise log the same line on every message.
  */
-export function reportExtensionErrors(services) {
-    for (const { path, error } of services.resourceLoader.getExtensions().errors) {
-        const key = `${path}\u0000${error}`;
-        if (reportedExtensionErrors.has(key))
-            continue;
-        reportedExtensionErrors.add(key);
-        log.warn(`[fastagent] extension ${path} failed to load: ${error}`);
-    }
-}
-const PROVIDER_REFUSAL = "extensions cannot register model providers when serving: a provider is process-wide, shared by every " +
-    "conversation, and never unregistered. Declare it in the agent's models.json";
+const reportedNotifications = new Set();
+// ponytail: cleared wholesale at this size, so a notification with a counter or id in it cannot grow the set for the
+// life of a `start` process; the price is one repeat at warn level after each clear. An LRU if that ever matters.
+const MAX_REPORTED_NOTIFICATIONS = 1000;
 /**
- * Serving refuses an extension that registers a provider while loading. pi would write it into the ONE `ModelRuntime`
- * every conversation resolves against, merge a re-registration into the old entry, and never drop one the code stopped
- * registering. The whole extension is left out, the way a tool file that fails to load is, and the refusal is its
- * load error.
+ * Announce extensions pi failed to load, and what it warned about while loading the rest: among them a definition
+ * extension that registers `codemode` or `tool_search`, which keeps pi's built-in of that name from loading. pi
+ * collects both into `LoadExtensionsResult` and carries on; only its own TUI shows them.
  */
-function refuseLoadTimeProviders(base) {
-    const offenders = new Set([
-        ...base.runtime.pendingProviderRegistrations.map((r) => r.extensionPath),
-        ...base.runtime.pendingNativeProviderRegistrations.map((r) => r.extensionPath),
-    ]);
-    if (offenders.size === 0)
-        return base;
-    base.runtime.pendingProviderRegistrations = [];
-    base.runtime.pendingNativeProviderRegistrations = [];
-    return {
-        ...base,
-        extensions: base.extensions.filter((extension) => !offenders.has(extension.path)),
-        errors: [...base.errors, ...[...offenders].map((path) => ({ path, error: PROVIDER_REFUSAL }))],
-    };
-}
-/**
- * ...and a registration made AFTER loading (from an event handler or a command), which pi applies to the shared
- * runtime directly. Must run after the session is created (pi installs its own actions then) and before
- * `bindExtensions` (which fires `session_start`).
- */
-function refuseLateProviders(services) {
-    const runtime = services.resourceLoader.getExtensions().runtime;
-    const refuse = () => {
-        throw new Error(PROVIDER_REFUSAL);
-    };
-    runtime.registerProvider = refuse;
-    runtime.registerNativeProvider = refuse;
-    runtime.unregisterProvider = refuse;
+function reportExtensionDiagnostics(services) {
+    for (const diagnostic of services.diagnostics) {
+        if (diagnostic.type === "error")
+            throw new Error(diagnostic.message);
+    }
+    const { errors, warnings = [] } = services.resourceLoader.getExtensions();
+    const said = [
+        ...errors.map(({ path, error }) => `extension ${path} failed to load: ${error}`),
+        ...warnings.map(({ path, warning }) => `extension ${path}: ${warning}`),
+    ];
+    for (const line of said) {
+        if (reportedExtensionDiagnostics.has(line))
+            continue;
+        reportedExtensionDiagnostics.add(line);
+        log.warn(`[fastagent] ${line}`);
+    }
 }
 /**
  * What a command's `ctx` can do to the session when serving. Each turn binds its own session and disposes it, so
@@ -199,14 +148,28 @@ function servingCommandActions(session) {
         reload: unavailable("reload"),
     };
 }
+const nativeFactories = {
+    codemode: createCodemodeExtension(),
+    "tool-search": createToolSearchExtension(),
+};
+const nativeExtensions = BUILTIN_EXTENSIONS.map((name) => ({
+    name,
+    factory: nativeFactories[name],
+    replaceable: true,
+    builtin: true,
+}));
 /** The resource posture a fastagent definition asks pi for — ONE definition of it, for both assemblies. */
 export function definitionResourceLoaderOptions(source) {
     return {
+        extensionFactories: [...nativeExtensions, compactAdmission],
         // The machine's extensions are its owner's setup, not this agent's.
         noExtensions: true,
-        // ...except the definition's OWN extensions/: pi honours additionalExtensionPaths even under noExtensions, which
-        // is exactly the split wanted here.
-        ...(source.extensionPaths?.length ? { additionalExtensionPaths: [...source.extensionPaths] } : {}),
+        // Explicit paths survive noExtensions, including Pi's built-ins; so they would also survive the machine's own
+        // `-builtin:<name>`, which is why only the enabled ones are named. Machine extensions stay out.
+        additionalExtensionPaths: [
+            ...source.machine.builtinExtensions.map((name) => `builtin:${name}`),
+            ...(source.extensionPaths ?? []),
+        ],
         // Not pi's: fastagent already loads the SAME files into segment ② (`loadProjectContextFiles` in
         // definition.ts). Leaving both on would put every AGENTS.md in the prompt twice.
         noContextFiles: true,
@@ -295,48 +258,40 @@ export function startCompaction(session, instructions, onAdmitted) {
     }, (error) => error instanceof Error && NOTHING_TO_COMPACT.test(error.message) ? "nothing_to_compact" : { refused: error });
     return { admission: Promise.race([admitted, settledFirst]), done };
 }
-/**
- * The resources ONE served session runs on: a fresh loader, so fresh extension instances.
- *
- * Assembled here rather than by pi's `createAgentSessionServices`, which ends by refreshing the model runtime it is
- * given — re-reading `models.json` and rebuilding every provider on the ONE runtime all conversations share. That is
- * there to fold in providers extensions registered, which serving refuses; per session it would be a full provider
- * rebuild per turn.
- */
-async function servingServices(options) {
+/** A fresh loader and Pi's native model registration, over a session-local runtime. */
+export async function definitionServices(options) {
     const { cwd, modelRuntime, definition, extensionPaths } = options;
     const machine = await readMachine(cwd);
-    const agentDir = getAgentDir();
-    // The machine's engine settings, as read at boot and without `packages` — a turn never resolves one.
-    const settingsManager = machine.settingsManager();
-    const resourceLoader = new DefaultResourceLoader({
-        ...definitionResourceLoaderOptions({
-            systemPrompt: () => definition.systemPrompt,
-            skills: () => definition.skills,
-            machine,
-            extensionPaths,
-        }),
-        extensionsOverride: (base) => admissionFirst(refuseLoadTimeProviders(base)),
-        extensionFactories: [compactAdmission],
+    const services = await withModelRegistration(modelRuntime, () => createAgentSessionServices({
         cwd,
-        agentDir,
-        settingsManager,
-    });
-    await resourceLoader.reload();
-    const services = { cwd, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] };
-    reportExtensionErrors(services);
+        agentDir: getAgentDir(),
+        modelRuntime,
+        settingsManager: machine.settingsManager(),
+        resourceLoaderOptions: {
+            ...definitionResourceLoaderOptions({
+                systemPrompt: () => definition.systemPrompt,
+                skills: () => definition.skills,
+                machine,
+                extensionPaths,
+            }),
+            extensionsOverride: admissionFirst,
+        },
+    }).then((services) => {
+        // AFTER the extensions: one that re-registers `openai` replaced the account-catalog wrapper.
+        registerAccountModels(modelRuntime);
+        return services;
+    }));
+    reportExtensionDiagnostics(services);
     return services;
 }
 /**
  * The `/name` commands a served session dispatches, named the way pi resolves them (a name two extensions share gets
- * a `:N` suffix). Loaded through the same {@link servingServices} a turn binds, so the menu and the dispatch cannot
+ * a `:N` suffix). Loaded through the same {@link definitionServices} a turn binds, so the menu and the dispatch cannot
  * disagree. Loading runs the extensions' factories; no session opens, so `session_start` does not fire, and the
  * instances are never bound (any action they call throws).
  */
 export async function servedExtensionCommands(options) {
-    if (options.extensionPaths.length === 0)
-        return [];
-    const services = await servingServices({ ...options, definition: { skills: [] } });
+    const services = await definitionServices({ ...options, definition: { skills: [] } });
     const { extensions, runtime } = services.resourceLoader.getExtensions();
     const runner = new ExtensionRunner(extensions, runtime, options.cwd, SessionManager.inMemory(options.cwd), new ModelRegistry(options.modelRuntime));
     return runner.getRegisteredCommands();
@@ -355,17 +310,19 @@ export function piAgentSessionFactory(options) {
     const extensionPaths = options.extensionPaths ?? [];
     const excludedToolNames = options.excludedToolNames ?? [];
     const tools = options.tools ?? [];
-    // `ctx.ui.theme` reads pi's global theme, which only pi's own entry points initialize.
-    if (extensionPaths.length > 0)
-        initTheme();
-    let engine;
     return async (sessionId, inherit) => {
-        const definition = await options.readDefinition();
-        engine ??= options.engine();
-        const { modelRuntime, model } = await engine;
-        // The record first: a control write that races this turn must find the session and be refused busy.
+        // `ctx.ui.theme` reads pi's global theme, which only pi's own entry points initialize. Serving only: chat's theme
+        // is InteractiveMode's, and resetting it on every session switch would drop the user's.
+        if (!themeReady) {
+            initTheme();
+            themeReady = true;
+        }
+        // Publish the record before loading resources: boundary writes must find it while binding is in flight.
         const sessionManager = await sessions.openOrCreate(sessionId, inherit);
-        const services = await servingServices({ cwd, modelRuntime, definition, extensionPaths });
+        const definition = await options.readDefinition();
+        const { modelRuntime } = await options.engine();
+        const services = await definitionServices({ cwd, modelRuntime, definition, extensionPaths });
+        const model = resolveModel(modelRuntime, options.modelSpec);
         // What the session RUNS on: the boundary plane records model/thinking overrides as entries, and pi does not read
         // them back.
         const settings = resolveSessionSettings(activePath(sessionManager), modelRuntime, {
@@ -381,9 +338,30 @@ export function piAgentSessionFactory(options) {
             cwd,
             excludedToolNames,
             sessionId,
-            recordActivations: true,
         });
-        refuseLateProviders(services);
+        // Pi's headless UI drops notifications. Keep dialogs cancelled and hasUI false, but surface diagnostics.
+        const runner = session.extensionRunner;
+        if (runner) {
+            const createContext = runner.createContext.bind(runner);
+            runner.createContext = () => {
+                const context = createContext();
+                // Pi clones own descriptors for before_agent_start; inherited fields would disappear there.
+                return Object.defineProperty(context, "ui", {
+                    value: {
+                        ...context.ui,
+                        notify: (message, type) => {
+                            const key = `${type ?? "info"}\u0000${message}`;
+                            const repeat = reportedNotifications.has(key);
+                            if (reportedNotifications.size >= MAX_REPORTED_NOTIFICATIONS)
+                                reportedNotifications.clear();
+                            reportedNotifications.add(key);
+                            const emit = repeat ? log.debug : type === "info" ? log.info : log.warn;
+                            emit(`[fastagent] session ${sessionId}: ${message}`);
+                        },
+                    },
+                });
+            };
+        }
         // `onError` is THE ONLY LISTENER for a fault pi reports nowhere else: `/skill:<name>` is expanded by reading
         // `filePath` at prompt time, and when that read fails pi raises `skill_expansion` on the extension error channel
         // and sends the line to the model unexpanded. The list can outlive the file: it is refreshed per invoke, so a

package/dist/engines/pi/auth.js

@@ -3,12 +3,11 @@
  * `Models` collection (models.ts), and which of those files an agent reads. The write path refuses to overwrite a
  * corrupt file, so a torn read never clobbers the other providers' credentials.
  */
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { globalHome, SECRETS_DIRNAME, SECRET_FILE_MODE, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
-import { writeFileAtomic } from "../../atomic-write.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalHome, SECRETS_DIRNAME, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 import { log } from "../../log.js";
-import lockfile from "proper-lockfile";
+import { withLockedFile } from "./locked-file.js";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery home
  * `~/.fastagent/`.
@@ -25,93 +24,6 @@ function pick(creds, providerId) {
     const cred = creds[providerId];
     return cred && (cred.type === "oauth" || cred.type === "api_key") ? cred : undefined;
 }
-const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: SECRET_FILE_MODE };
-/**
- * The file a write must land IN, which is not always the path it is addressed BY. pi writes the auth file in place,
- * so it follows a symlink to the target; an atomic rename would replace the link with a regular file instead, and
- * from then on the two tools would be editing different files — the same split the shared lock exists to prevent,
- * arriving one write later. A dangling link (a dotfile manager that has not checked the target out yet) still names
- * where the credentials belong, so it is followed too rather than overwritten.
- */
-function writeTarget(authPath) {
-    if (existsSync(authPath))
-        return realpathSync(authPath);
-    const link = lstatSync(authPath, { throwIfNoEntry: false });
-    // ponytail: one hop. A chain of dangling links would have its second link replaced; resolve iteratively if that
-    // ever shows up in a real layout.
-    return link?.isSymbolicLink() ? resolve(dirname(authPath), readlinkSync(authPath)) : authPath;
-}
-/** Serialized cross-process read-modify-write of the credentials file. */
-async function withLockedAuthFile(authPath, fn) {
-    mkdirSync(dirname(authPath), { recursive: true });
-    if (!existsSync(authPath)) {
-        try {
-            // `wx` makes this an exclusive CREATE, which is the one case `writeFileSync` honours `mode` in — so no chmod
-            // after it (unlike writeFileAtomic, whose temp may already exist from a crashed writer).
-            writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
-        }
-        catch (error) {
-            // EEXIST: the path IS taken, by something `existsSync` does not see through — either another process created
-            // the file just now (its credentials must not be clobbered) or the path is a dangling symlink. Both are left
-            // alone: the write below resolves where they belong.
-            if (error.code !== "EEXIST")
-                throw error;
-        }
-    }
-    let compromised;
-    const throwIfCompromised = () => {
-        if (compromised)
-            throw compromised;
-    };
-    const release = await lockfile.lock(authPath, {
-        // MUST match pi-coding-agent's `core/auth-storage.js`, which locks with `realpath: false`. When the auth file
-        // itself is a symlink (dotfile managers do this), the two settings name DIFFERENT lock files and both locks can
-        // be held at once — so `pi` and `fastagent` would refresh the same provider concurrently, and a rotated refresh
-        // token logs one of them out. Resolving the link would be the stronger rule, but only if BOTH sides did it, and
-        // we do not own the other side.
-        realpath: false,
-        retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
-        stale: 30_000,
-        onCompromised: (error) => {
-            compromised = error;
-        },
-    });
-    let result;
-    try {
-        throwIfCompromised();
-        const current = existsSync(authPath) ? readFileSync(authPath, "utf8") : undefined;
-        const out = await fn(current);
-        throwIfCompromised();
-        // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only spelling that applies
-        // the mode before the content is reachable.
-        if (out.next !== undefined) {
-            writeFileAtomic(writeTarget(authPath), out.next, SECRET_FILE_MODE);
-        }
-        throwIfCompromised();
-        result = out.result;
-    }
-    catch (error) {
-        // The primary failure stays the signal; unlock noise must not mask it.
-        try {
-            await release();
-        }
-        catch {
-            // Secondary: a compromised or stale-reclaimed lock often cannot release cleanly.
-        }
-        throw error;
-    }
-    // Success path: a failed release is a real cleanup failure (the leftover auth.json.lock stalls the next writer for
-    // the staleness window with zero diagnostics), so it surfaces instead of resolving a silently degraded operation.
-    try {
-        await release();
-    }
-    catch (releaseError) {
-        if (compromised === undefined)
-            throw releaseError;
-    }
-    throwIfCompromised();
-    return result;
-}
 /** Decode the credentials JSON, shared by the read and write paths. */
 function decodeCreds(raw) {
     let parsed;
@@ -223,7 +135,7 @@ export function fastagentCredentialStore(path, options = {}) {
         },
         async modify(providerId, fn) {
             const path = await owner(providerId);
-            return withLockedAuthFile(path, async (current) => {
+            return withLockedFile(path, async (current) => {
                 const creds = parseForWrite(current, path); // corrupt → throw → no clobber
                 const next = await fn(pick(creds, providerId));
                 if (next === undefined)
@@ -238,7 +150,7 @@ export function fastagentCredentialStore(path, options = {}) {
             // stored this provider.
             if (!existsSync(path))
                 return;
-            await withLockedAuthFile(path, async (current) => {
+            await withLockedFile(path, async (current) => {
                 const creds = parseForWrite(current, path);
                 if (!(providerId in creds))
                     return { result: undefined }; // absent: no write

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

@@ -19,6 +19,13 @@ import { type Lease, type SessionObserver } from "./turn-kit.ts";
  */
 export declare const CODING_TOOL_NAMES: readonly ["read", "grep", "find", "ls", "bash", "edit", "write"];
 export declare function piAllCodingTools(cwd: string): MountedTool[];
+/** How the model reaches a mounted tool it is not given up front. */
+export type ToolReach = "tool_search" | "codemode" | "hidden" | "inactive" | "unreachable";
+/** A mounted authored tool outside the default-active surface, and its way in. */
+export interface IndirectTool {
+    name: string;
+    reach: ToolReach;
+}
 /**
  * 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.
@@ -26,11 +33,8 @@ export declare function piAllCodingTools(cwd: string): MountedTool[];
 export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd: string): Promise<{
     tools: MountedTool[];
     toolNames: string[];
-    /**
-     * Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated via the built-in
-     * `search_tools` loader.
-     */
-    deferredToolNames: string[];
+    /** Mounted authored tools the model is not given up front, with how each is reached. */
+    indirectTools: IndirectTool[];
     toolCollisions: ToolCollision[];
     toolFailures: ModuleLoadFailure[];
     /** Env vars the MOUNTED tools declared they need, BY TOOL NAME — a discovered tool shadowed by a
@@ -45,6 +49,8 @@ export declare function resolveAgentTools(config: FastagentConfig, agentDir: str
 export declare function piBasePrompt(options?: {
     tools?: MountedTool[];
     persona?: string;
+    /** The {@link BUILTIN_EXTENSIONS} this machine leaves enabled (`Machine.builtinExtensions`); all by default. */
+    builtinExtensions?: readonly string[];
 }): string;
 export interface AssembleSystemPromptOptions {
     /**
@@ -66,11 +72,10 @@ export declare function assembleSystemPrompt(options: AssembleSystemPromptOption
 export interface PiAssembly {
     lease: Lease;
     sessionFactory: PiAgentSessionFactory;
-    /**
-     * The registry alone, with injected providers registered. `chat` resolves its model against it only after its
-     * extensions have loaded, because there an extension may register the provider (serving refuses that).
-     */
+    /** Extension-aware catalog for startup reporting and control-plane validation; never bound to a session. */
     modelRuntime: () => Promise<ModelRuntime>;
+    /** A fresh runtime for every session, before loading its extensions. */
+    createModelRuntime: () => Promise<ModelRuntime>;
     /** The registry and configured model, resolved on first use (a credential read is async). */
     engine: () => Promise<{
         modelRuntime: ModelRuntime;
@@ -80,6 +85,8 @@ export interface PiAssembly {
     thinkingLevel: ThinkingLevel;
     /** The tools every session mounts. */
     tools: MountedTool[];
+    /** Pi built-ins the mounted tools leave out, denied in every session so discovery cannot bring them back. */
+    excludedToolNames: readonly string[];
     /** The prompt and skills a session runs on, read when a session is bound. */
     readDefinition: PiAgentSessionFactoryOptions["readDefinition"];
     /** The extension entry points every session loads, discovered once with the assembly. */