@fastagent-sh/fastagent 0.21.1 → 0.22.1

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

@@ -1,32 +1,25 @@
 /**
- * The AgentSession L0's engine binding: fastagent's assembled agent — model, prompt, skills, tools —
- * bound to one durable record, per invoke.
- *
- * The chat path builds the same pi class from the same assembly (session-builder.ts) but keeps ONE
- * resident session. What is specific here is the posture: many sessions, one turn each, nothing in
- * memory between turns.
- *
- * Shared once, rebuilt per turn:
- * - `services` (ResourceLoader, settings, model runtime) is built lazily and reused — it is the
- *   expensive half, and it holds nothing session-specific;
- * - the `AgentSession` and its tool bindings are per turn, because a tool's `execute` closes over the
- *   session it runs in and this posture has several in flight at once.
+ * The AgentSession L0's engine binding: fastagent's assembled agent — model, prompt, skills, tools — bound to one
+ * durable record, per invoke.
  */
-import { dirname, join } from "node:path";
-import { createAgentSessionFromServices, createAgentSessionServices, } from "@earendil-works/pi-coding-agent";
+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 { log } from "../../log.js";
 import { isDeferredTool } from "./tool.js";
 import { activePath, resolveSessionSettings } from "./session-settings.js";
 import { DEFAULT_THINKING_LEVEL } from "./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.
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred tools a loader
+ * activated in that call.
  *
- * A DEDICATED record, not pi's own `active_tools_change`: that one is a full SNAPSHOT of everything
- * active at the moment, so replaying it would keep a tool active in old sessions after the author
- * flips it to `deferred` — the session never discovered it. A delta carries only what was actually
- * found, and is layered onto whatever the workspace mounts TODAY.
+ * 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. */
@@ -44,17 +37,12 @@ function recordedActivations(session) {
     }
     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.
- *
- * `bound` is filled after the session exists — pi needs the definitions to build the session, and a
- * tool needs the session to reach the turn context. A tool that somehow runs before that binding
- * throws rather than executing outside the turn: a broken lifecycle must not look like a normal
- * out-of-turn call.
+ * 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) => ({
         ...tool,
@@ -85,12 +73,8 @@ function toolDefinitions(tools, bound, sessionId) {
     }));
 }
 /**
- * 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. The per-invoke factory and the resident chat
- * runtime both bind here — they differ in what they hand in (a shared vs a per-session `services`,
- * record-resolved vs configured settings) and in whether a discovered activation has a record to
- * land in, and in nothing else. Two copies of this drifted once (the tool adapter and the deferral
- * narrowing each existed twice, identical but for those parameters).
+ * 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.
  */
 export async function bindPiSession(options) {
     const { services, sessionManager, model, thinkingLevel, tools, cwd, recordActivations } = options;
@@ -105,16 +89,12 @@ export async function bindPiSession(options) {
         model,
         thinkingLevel,
         // pi would otherwise mount its built-ins on top of fastagent's copies, offering duplicate names.
-        // Lower-level callers with an explicit list also rely on omitted built-ins staying omitted. And
-        // NO `tools` allowlist: it would freeze the set at bind time, while pi lets an extension register
-        // from `session_start` — `noTools: "builtin"` gives the guarantee the allowlist was there for.
         noTools: "builtin",
         ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
         customTools: toolDefinitions(tools, bound, sessionId),
     });
     const { session } = result;
-    // One context for the whole session: it describes the SESSION, not the call. The activation
-    // bridge above all — a tool call has to see what the previous one activated.
+    // One context for the whole session: it describes the SESSION, not the call.
     bound.current = {
         session,
         context: {
@@ -126,15 +106,14 @@ export async function bindPiSession(options) {
                 : undefined),
         },
     };
-    // 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.
+    // 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: pi's setter
-        // THROWS on an unknown name, so replaying one would brick every future turn of this 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) {
@@ -150,135 +129,251 @@ export async function bindPiSession(options) {
     }
     return result;
 }
+/** Each distinct load failure is said once per process: serving loads the extensions again for every session. */
+const reportedExtensionErrors = new Set();
 /**
- * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
- * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
- * A definition running without the extension it ships is exactly the "quietly missing" failure this
- * exists to remove. CHAT calls it, once per built services — serving does not load extensions at
- * all, and announces that instead (see PiAgentSessionFactoryOptions.extensionPaths).
+ * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and carries on with the
+ * rest.
  */
 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";
 /**
- * The resource posture a fastagent definition asks pi for — ONE definition of it, for both
- * assemblies. Serving (`piAgentSessionFactory`) and chat (`buildAgentSessionRuntime`) build
- * different sessions on top, but what pi is allowed to DISCOVER is not one of the differences:
- * everything comes from the definition, nothing from the machine that happens to be running it.
- *
- * Two copies of this drifted once already: `additionalExtensionPaths` was added to both, and only
- * one of them also passed the resulting tool names through pi's `tools` allowlist — so extensions
- * worked when served and vanished in chat. A difference between the two has to be visible AS a
- * difference, which is what the parameters are for: serving reads a prompt and skills that change
- * per turn and passes NO extension paths (it does not run them — see
- * {@link PiAgentSessionFactoryOptions.extensionPaths}); chat reads a fixed assembly and passes its
- * own. Both are arguments now, rather than two files that happen to disagree.
+ * 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.
+ */
+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;
+}
+/**
+ * What a command's `ctx` can do to the session when serving. Each turn binds its own session and disposes it, so
+ * there is no current session to replace, fork or reload; pi's unbound default would report `{ cancelled: false }`
+ * for all of them without doing anything.
  */
+function servingCommandActions(session) {
+    const unavailable = (action) => async () => {
+        throw new Error(`ctx.${action}() is not available when serving: every turn runs on its own session`);
+    };
+    return {
+        waitForIdle: () => session.waitForIdle(),
+        newSession: unavailable("newSession"),
+        fork: unavailable("fork"),
+        navigateTree: unavailable("navigateTree"),
+        switchSession: unavailable("switchSession"),
+        reload: unavailable("reload"),
+    };
+}
+/** The resource posture a fastagent definition asks pi for — ONE definition of it, for both assemblies. */
 export function definitionResourceLoaderOptions(source) {
     return {
-        // Definition-only, like dev/start: pi's machine-global discovery (the operator's own ~/.pi
-        // extensions, slash commands, global AGENTS.md, APPEND_SYSTEM.md) stays out, so the agent that
-        // runs is the artifact, not the artifact plus whoever's laptop it is.
+        // 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 — the artifact travels with its
-        // extensions, the machine's stay out.
+        // ...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] } : {}),
-        noPromptTemplates: true,
+        // 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,
-        // A SPACE, not "", when the assembly has no prompt: pi treats an empty custom prompt as absent
-        // and substitutes its own coding-assistant identity, which an L1 agent
-        // (`createPiAgent({ model, tools })`) never asked for. pi appends its own working-directory line
-        // either way — that is engine behaviour this binding does not fight.
+        // The IDENTITY is the definition's, whatever the machine thinks. Inheriting skills is inheriting capability;
+        // inheriting a system prompt would be the agent becoming someone else's agent.
         systemPromptOverride: () => source.systemPrompt() || " ",
         appendSystemPromptOverride: () => [],
-        skillsOverride: (base) => ({
-            skills: toPiSkills(source.skills()),
-            diagnostics: base.diagnostics,
+        /**
+         * THE DEFINITION'S SKILLS, PLUS THE MACHINE'S — an agent inherits the box it runs on (machine.ts), and the
+         * definition wins a name collision.
+         *
+         * NO DISCOVERY OF ITS OWN: the machine's half is the process's single read, so a bound session and `commands()`
+         * describe the same box. A loader discovering for itself is what made the menu live while a session was not.
+         */
+        noSkills: true,
+        skillsOverride: () => ({
+            skills: withMachine(toPiSkills(source.skills()), source.machine.skills),
+            diagnostics: [],
         }),
+        noPromptTemplates: true,
+        promptsOverride: () => ({ prompts: [...source.machine.prompts], diagnostics: [] }),
     };
 }
-/** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
+/** Manual compactions waiting for pi's admission, keyed by the session's record (what an extension's `ctx` names). */
+const compactAdmissions = new WeakMap();
+const COMPACT_ADMISSION = "fastagent-compact-admission";
+/**
+ * pi's own admission signal for a manual compaction: `session_before_compact` fires only once `prepareCompaction`
+ * found work, and before the model call. It must be the FIRST listener ({@link admissionFirst}): pi awaits each
+ * handler in turn, and a definition's own handler (a custom summarizer, a cancel) runs after admission, like the
+ * model call it may replace.
+ */
+const compactAdmission = {
+    name: COMPACT_ADMISSION,
+    hidden: true,
+    factory: (pi) => {
+        pi.on("session_before_compact", (event, ctx) => {
+            if (event.reason === "manual")
+                admitCompaction(ctx.sessionManager);
+        });
+    },
+};
+/**
+ * pi loads path extensions first and appends inline factories after them, so {@link compactAdmission} arrives last.
+ * Moved to the front here, since pi dispatches handlers in extension order.
+ */
+function admissionFirst(base) {
+    const path = `<inline:${COMPACT_ADMISSION}>`;
+    const admission = base.extensions.filter((extension) => extension.path === path);
+    return { ...base, extensions: [...admission, ...base.extensions.filter((extension) => extension.path !== path)] };
+}
+/** Tell a waiting {@link startCompaction} that pi admitted the compaction on this record. */
+export function admitCompaction(record) {
+    compactAdmissions.get(record)?.();
+}
+/**
+ * pi's refusals when `prepareCompaction` finds nothing. They are plain Errors, so their text is the only way to tell
+ * them from any other error pi raises before admission. If pi rewords them, the refusal still fails visibly, as
+ * `boundary_command_failed` instead of `nothing_to_compact`, and the admission tests in session-control.test.ts,
+ * which run pi's real refusal, fail with it.
+ */
+const NOTHING_TO_COMPACT = /^(Nothing to compact|Already compacted)\b/;
+/**
+ * Start pi's manual compaction on a bound session. `onAdmitted` runs INSIDE pi's admission event, so everything it
+ * publishes precedes anything pi does next (the model call, its retries). `admission` settles before the model call.
+ * pi's own pre-admission failures come back as `refused` rather than a rejection: the caller answers them to its
+ * Caller as a result. `done` is the compaction itself.
+ */
+export function startCompaction(session, instructions, onAdmitted) {
+    const record = session.sessionManager;
+    const admitted = new Promise((resolve) => {
+        compactAdmissions.set(record, () => {
+            try {
+                onAdmitted();
+            }
+            finally {
+                resolve("admitted");
+            }
+        });
+    });
+    const done = session.compact(instructions);
+    const forget = () => void compactAdmissions.delete(record);
+    done.then(forget, forget);
+    const settledFirst = done.then(() => {
+        throw new Error("pi finished a compaction without announcing its admission (session_before_compact)");
+    }, (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) {
+    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],
+        cwd,
+        agentDir,
+        settingsManager,
+    });
+    await resourceLoader.reload();
+    const services = { cwd, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] };
+    reportExtensionErrors(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
+ * 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 { extensions, runtime } = services.resourceLoader.getExtensions();
+    const runner = new ExtensionRunner(extensions, runtime, options.cwd, SessionManager.inMemory(options.cwd), new ModelRegistry(options.modelRuntime));
+    return runner.getRegisteredCommands();
+}
+/**
+ * Open-or-create the record, then bind a fresh session to it — on a fresh resource loader.
+ *
+ * ONE LOADER PER SESSION, because pi's extension runtime belongs to its loader: a loader shared across concurrent
+ * turns would let one conversation's extension act on another's session. It also makes the definition live with no
+ * bookkeeping: every bind reads the prompt and skills this invoke read. The machine's half is the process's one read
+ * (machine.ts). Extension CODE is imported once per process, so an edit to `extensions/` needs a restart, which is
+ * what `dev` does on one.
+ */
 export function piAgentSessionFactory(options) {
     const { sessions, thinkingLevel, cwd } = options;
     const extensionPaths = options.extensionPaths ?? [];
     const excludedToolNames = options.excludedToolNames ?? [];
-    if (extensionPaths.length > 0) {
-        log.warn(`[fastagent] ${extensionPaths.length} extension(s) in the definition are NOT loaded when serving ` +
-            "(they run in `fastagent chat`): pi's extension runtime is shared across sessions, and serving " +
-            "runs concurrent turns for different conversations. See docs/configuration.md#extensions.");
-    }
     const tools = options.tools ?? [];
-    // What the shared ResourceLoader serves, refreshed per turn before the session is built.
-    let definition;
-    let services;
+    // `ctx.ui.theme` reads pi's global theme, which only pi's own entry points initialize.
+    if (extensionPaths.length > 0)
+        initTheme();
     let engine;
-    const buildServices = async (modelRuntime) => createAgentSessionServices({
-        cwd,
-        agentDir: options.agentDir ?? join(cwd, ".fastagent", "pi"),
-        modelRuntime,
-        // No extensionPaths: serving does not run them (see PiAgentSessionFactoryOptions), which is
-        // the one resource question the two assemblies answer differently. The accessors read the
-        // CURRENT prompt/skills — serving refreshes both per turn, so a snapshot taken here would
-        // serve a stale definition after the first edit.
-        resourceLoaderOptions: definitionResourceLoaderOptions({
-            systemPrompt: () => definition.systemPrompt,
-            skills: () => definition.skills,
-        }),
-    });
     return async (sessionId, inherit) => {
-        const next = await options.readDefinition();
+        const definition = await options.readDefinition();
         engine ??= options.engine();
         const { modelRuntime, model } = await engine;
-        if (services === undefined) {
-            definition = next;
-            services = buildServices(modelRuntime); // assigned before any await: concurrent turns share it
-        }
-        else {
-            // The ResourceLoader reads the overrides once and caches, so a re-read of the definition only
-            // reaches the model after a reload. Reload only when the definition ACTUALLY changed — an
-            // author edits persona.md far less often than the agent takes a turn, and a reload costs ~5ms
-            // against ~0.6ms to bind a session.
-            //
-            // "Changed" is measured against the LOADER, not against what this factory last wrote. Serving
-            // is concurrent across sessions, and a shared variable makes the check lie: one turn writes
-            // its new prompt, awaits before reloading, and the next turn sees that value already present,
-            // concludes nothing changed, and skips the reload — so the edit reaches neither the loader nor
-            // any error. Asking the loader what it is actually serving cannot go stale that way. The cost
-            // of losing the race is one redundant reload, not a swallowed edit.
-            //
-            // Skill CONTENT is not part of this — pi reads a skill from its file at invocation time, so
-            // only the declared set matters.
-            //
-            // What this deliberately does NOT provide is a per-turn snapshot. The definition is an AGENT
-            // property, not a session one: two turns running either side of an edit each get a definition
-            // that genuinely existed, and the product promise — an edit is live on the next turn — holds
-            // for both. Pinning a snapshot per turn would cost either a loader per turn or a queue in
-            // front of every bind, to buy a guarantee nothing asks for.
-            const loader = (await services).resourceLoader;
-            const definitionChanged = loader.getSystemPrompt() !== (next.systemPrompt || " ") ||
-                skillSet(loader.getSkills().skills) !== skillSet(next.skills);
-            if (definitionChanged) {
-                definition = next;
-                await loader.reload();
-            }
-        }
+        // The record first: a control write that races this turn must find the session and be refused busy.
         const sessionManager = await sessions.openOrCreate(sessionId, inherit);
-        // What the session RUNS on: the boundary plane records model/thinking overrides as entries, and
-        // pi does not read them back — a binding that ignored them would silently run every turn on the
-        // assembly default, and `state()` would report a setting no turn uses.
-        // The SAME read the control plane performs, including its integrity check: a record whose chain
-        // is broken must not run on assembly defaults while `state()` rejects it — one of the two planes
-        // would be lying. A throw here becomes this turn's `failed` event, which is where the fault has
-        // a channel to be reported through.
+        const services = await servingServices({ cwd, modelRuntime, definition, extensionPaths });
+        // 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, {
             model,
             thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
         });
         const { session } = await bindPiSession({
-            services: await services,
+            services,
             sessionManager,
             model: settings.model,
             thinkingLevel: settings.thinkingLevel,
@@ -288,15 +383,23 @@ export function piAgentSessionFactory(options) {
             sessionId,
             recordActivations: true,
         });
+        refuseLateProviders(services);
+        // `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
+        // steer or follow-up inside a run, or a definition replaced under a running container (`src/deploy/workspace.ts`),
+        // reaches exactly that state. The same channel carries every extension handler's failure.
+        //
+        // No `uiContext`: a served turn has no human at a terminal, and pi's default is what extensions are written to
+        // detect (`ctx.hasUI === false`; dialogs resolve as cancelled). This call fires `session_start`.
+        await session.bindExtensions({
+            onError: ({ extensionPath, event, error }) => log.warn(`[fastagent] session ${sessionId}: ${event} failed for ${extensionPath}: ${error}`),
+            commandContextActions: servingCommandActions(session),
+            shutdownHandler: () => log.warn(`[fastagent] session ${sessionId}: an extension called ctx.shutdown(); a served process is stopped by its host, not by a turn`),
+        });
         return session;
     };
 }
-/** What a reload has to notice: the declared set, not the files behind it. */
-function skillSet(skills) {
-    return skills
-        .map((s) => `${s.name}\u0000${s.filePath ?? ""}\u0000${s.description}\u0000${s.disableModelInvocation ?? false}`)
-        .join("\u0001");
-}
 /** fastagent's Skill (content inline) as pi's (read from filePath at invocation time). */
 function toPiSkills(skills) {
     return skills.map((skill) => {

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

@@ -1,18 +1,22 @@
 import type { CredentialStore } from "@earendil-works/pi-ai";
 /**
- * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery
- * home `~/.fastagent/` — which carries the same unified shape as a workspace (`.secrets/auth.json`).
- * The project-level default is `<agentDir>/.secrets/auth.json` (computed by the opener and by
- * `fastagent login`); this is only the `loginFlow()` PROGRAMMATIC fallback (when a caller omits
- * `authPath`) and the path to point `--auth-path`/`FASTAGENT_AUTH_PATH` at to deliberately share ONE
- * credential file across projects (safe — one file, one lock-serialized refresh lifecycle). The
- * `fastagent login` CLI is project-level by default, never this.
+ * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery home
+ * `~/.fastagent/`.
  */
 export declare const GLOBAL_AUTH_PATH: string;
 export interface FastagentAuthOptions {
-    /** Sink for non-fatal auth anomalies (unreadable/corrupt file). Defaults to the process logger (warn). */
+    /** Sink for non-fatal auth anomalies (unreadable/corrupt file). */
     warn?: (message: string) => void;
 }
-/** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
- *  the directory opener passes the project-level `<root>/.secrets/auth.json`). */
-export declare function fastagentCredentialStore(authPath?: string, options?: FastagentAuthOptions): CredentialStore;
+/**
+ * A read-write `CredentialStore` over the given credentials file (default {@link GLOBAL_AUTH_PATH}; the directory
+ * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file.
+ *
+ * The fallback is PER PROVIDER, not per file: logging one provider into a project must not hide the others a person
+ * already has globally. And the layer a credential was READ from is the layer its refresh is written back to —
+ * anything else would conjure a second holder of the same OAuth grant, which is the failure this whole area exists
+ * to avoid. A provider present in neither layer is new, and new credentials belong to the primary.
+ */
+export declare function fastagentCredentialStore(authPath?: string, options?: FastagentAuthOptions & {
+    fallbackPath?: string;
+}): CredentialStore;