@fastagent-sh/fastagent 0.22.1 → 0.24.0

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

@@ -3,45 +3,14 @@
  * 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 { 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 +41,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 +65,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 +75,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 +147,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 +257,36 @@ 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,
+        },
+    }));
+    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 +305,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 +333,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.d.ts

@@ -8,15 +8,68 @@ export interface FastagentAuthOptions {
     /** Sink for non-fatal auth anomalies (unreadable/corrupt file). */
     warn?: (message: string) => void;
 }
+/**
+ * Where a caller's model credentials live: fastagent's JSON file (`authPath`, or the default layers when neither is
+ * given), or a {@link CredentialStore} the caller owns (an OS keychain, Electron `safeStorage`). A supplied store
+ * replaces the FILES: none is read or written, and no global layer applies. Env variables and `models.json` keys still
+ * apply, below a stored credential, exactly as with `authPath`. The store owns what the file store does
+ * for its file: `modify` for one provider must run one at a time, because an OAuth refresh happens inside it and a
+ * rotated refresh token must never be used twice; and a store it cannot parse must not be answered as empty, or the
+ * next write replaces every provider's credential.
+ */
+export interface CredentialSourceOptions {
+    /** fastagent's credentials file. Mutually exclusive with {@link credentialStore}. */
+    authPath?: string;
+    /** The caller's own store, read and written instead of any file. Mutually exclusive with {@link authPath}. */
+    credentialStore?: CredentialStore;
+}
+/** The one refusal for a caller that names both sources: silently preferring one would hide the other's mistake. */
+export declare function assertOneCredentialSource(options: CredentialSourceOptions): void;
+/** A credential store over fastagent's files, which can also say which file a provider belongs to. */
+export type FastagentCredentialStore = CredentialStore & {
+    /**
+     * The file this store reads a provider from and writes its refresh to: where it already is, else the primary. The
+     * one answer to "which file do I edit", so a report naming a file cannot disagree with the store that reads it.
+     */
+    layerOf(providerId: string): Promise<string>;
+};
 /**
  * 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.
+ * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file. A path is
+ * read like `FASTAGENT_AUTH_PATH` (`~` is the home directory, a relative one resolves against the cwd), so every
+ * caller that names a file names the same one.
  *
  * 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.
+ *
+ * The fallback also yields to `projectAuthenticates`: a provider the project authenticates some other way (an env key,
+ * its own models.json) never reaches it — for reading, listing or writing back.
  */
-export declare function fastagentCredentialStore(authPath?: string, options?: FastagentAuthOptions & {
+export declare function fastagentCredentialStore(path?: string, options?: FastagentAuthOptions & {
     fallbackPath?: string;
-}): CredentialStore;
+    /** Whether the project authenticates this provider without the fallback; then the fallback is not read for it. */
+    projectAuthenticates?: (providerId: string) => Promise<boolean>;
+}): FastagentCredentialStore;
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
+export declare function resolveAuthPath(dir: string, flag?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Which credentials files an agent reads: `path` first, then, per provider, `fallback`. One value because it is one
+ * decision, read through `agentModels` (agent-models.ts) by everything that reads an agent's credentials.
+ */
+export interface AuthLayers {
+    path: string;
+    fallback?: string;
+}
+/**
+ * The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file, and
+ * behind it the user-global store, because a login is a PERSON on a machine and not a project — one `login -g` then
+ * serves every agent here.
+ *
+ * No fallback when a path was named: "use this file" is an instruction, not a preference. BOTH knobs
+ * {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what the
+ * Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing else
+ * (the artifact is the truth).
+ */
+export declare function resolveAuthLayers(agentDir: string, authPath?: string, env?: NodeJS.ProcessEnv): AuthLayers;