@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/engines/pi/report.js

@@ -42,10 +42,3 @@ export function reportToolCollisions(collisions) {
         log.warn(`[fastagent] tool "${c.name}" (${c.source}) dropped — a default/config tool already uses that name`);
     }
 }
-/** Report per-file module failures. The caller decides whether they are degradations (tools/schedules)
- *  or fatal (declared channels on the serving path). */
-export function reportModuleLoadFailures(failures) {
-    for (const f of failures) {
-        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
-    }
-}

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

@@ -0,0 +1,23 @@
+/**
+ * `createAgentService` — the product as one call, with pi supplying the engine.
+ *
+ * The ASSEMBLY is engine-neutral and lives in `src/service.ts`: it takes a {@link MountableAgent}
+ * (the SPEC contract plus three paths) and knows nothing about how that agent was built. What is
+ * pi-specific is opening a DIRECTORY into one, which is why this shortcut lives here and the
+ * assembly does not. A second engine ships its own opener and reuses `mountAgentService` unchanged.
+ */
+import type { AgentService, MountAgentServiceOptions } from "../../service.ts";
+export interface CreateAgentServiceOptions extends MountAgentServiceOptions {
+    model?: string;
+    authPath?: string;
+    sessionsDir?: string;
+}
+/**
+ * Open an agent directory as a live service: one handler, mounted wherever you serve.
+ *
+ * ```ts
+ * const service = await createAgentService("./my-agent");
+ * app.use("/agent", nodeListener(service.handler));
+ * ```
+ */
+export declare function createAgentService(dir: string, options?: CreateAgentServiceOptions): Promise<AgentService>;

package/dist/engines/pi/service.js

@@ -0,0 +1,19 @@
+import { mountAgentService } from "../../service.js";
+import { createPiAgentFromDir } from "./open.js";
+/**
+ * Open an agent directory as a live service: one handler, mounted wherever you serve.
+ *
+ * ```ts
+ * const service = await createAgentService("./my-agent");
+ * app.use("/agent", nodeListener(service.handler));
+ * ```
+ */
+export async function createAgentService(dir, options = {}) {
+    const opened = await createPiAgentFromDir(dir, {
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.authPath !== undefined ? { authPath: options.authPath } : {}),
+        ...(options.sessionsDir !== undefined ? { sessionsDir: options.sessionsDir } : {}),
+        serving: true, // a mounted service is long-running: the scheduler poller runs
+    });
+    return mountAgentService(opened, options);
+}

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

@@ -11,8 +11,8 @@
  *   - prompt  → systemPromptOverride = base + instructions ONLY; pi appends the skill section and env
  *               (cwd) itself (including it here would duplicate it).
  *   - skills  → skillsOverride (fastagent's skills, for the section + invocation).
- *   - tools   → default coding tools by NAME (pi rebuilds them cwd-bound for rich rendering) +
- *               fastagent's custom tools via pi's customTools path (so they survive /new, /resume, fork).
+ *   - tools   → all seven coding tools plus authored tools through pi's customTools path; pi's builtin
+ *               copies are suppressed, and the injected set survives /new, /resume, and fork.
  *   - models  → a ModelRuntime with builtins only (`modelsPath: null`, no availability network), so
  *               the model surface equals serving's `createPiModels()` — pi's machine-global
  *               models.json does not leak in.
@@ -28,32 +28,19 @@
  * workspace.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { SessionManager, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
 import { resolveModel } from "./config.js";
-import { assembleSystemPrompt, piBasePrompt, piDefaultTools } from "./create.js";
-import { canonicalPath, loadAgentDefinition } from "./definition.js";
+import { assembleSystemPrompt, piBasePrompt } from "./create.js";
+import { canonicalPath, loadAgentDefinition, loadExtensionPaths } from "./definition.js";
 import { createPiModelRuntime, probeAuthSource } from "./models.js";
 import { log } from "../../log.js";
-import { additiveActivation, turnContext } from "./tool-context.js";
-import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
+import { additiveActivation, agentSessionManager, turnContext, } from "./tool-context.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "./report.js";
+import { reportModuleLoadFailures } from "../../log.js";
 import { resolveAgentAssembly } from "./open.js";
-/** Adapt coding-agent's resident SessionManager to FastAgent's shared tool-runtime manager port. */
-function toolChatSessionManager(session) {
-    return {
-        getSessionId: () => session.sessionManager.getSessionId(),
-        async getHeader() {
-            const header = session.sessionManager.getHeader();
-            if (!header)
-                throw new Error("chat session has no metadata header");
-            return { id: header.id, timestamp: header.timestamp };
-        },
-        async getBranch() {
-            return session.sessionManager.getBranch();
-        },
-    };
-}
 /**
  * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
  * skills, and auth resolved exactly as the serving opener does). Split from the TUI launcher so the
@@ -63,7 +50,7 @@ export async function buildAgentSessionRuntime(dir, options = {},
 /** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
 sessionManager) {
     /** The turn's {@link ToolActivation} over pi's AgentSession — the counterpart of invoke.ts's
-     *  harness bridge, so the SAME builtin search_tools serves both paths. Additive; unknown names
+     *  serving bridge, so the SAME builtin search_tools serves both paths. Additive; unknown names
      *  filtered (`setActiveToolsByName` is authoritative on the session and rebuilds its prompt — our
      *  static override keeps the prompt identical to serving). */
     function sessionToolActivation(session) {
@@ -99,36 +86,27 @@ sessionManager) {
         // (what you iterate is what you serve): the initial active set excludes deferred tools (applied
         // on the session in createRuntime — pi's session starts all-active), and the activation bridge
         // above rides the same turn context, so the SAME search_tools works against pi's AgentSession
-        // instead of fastagent's harness.
+        // instead of the served one.
         const { config, modelSpec, agentDir, authPath, stateRoot, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
         reportToolCollisions(toolCollisions);
         reportModuleLoadFailures(toolFailures);
-        // ONE hub owns model resolution AND per-request auth — the ModelRuntime-shaped sibling of
-        // serving's createPiModels; see models.ts.
+        // ONE hub owns model resolution AND per-request auth; see models.ts.
         // agentDir carries the agent's own models.json (custom endpoints); stateRoot keeps pi's generated
         // catalog cache out of the definition dir. See createPiModelRuntime.
         const modelRuntime = await createPiModelRuntime({ authPath, agentDir, stateRoot });
-        // MIGRATION HINT (deliberate breaking change): chat historically used pi's own `~/.pi` auth;
-        // it now reads the agent's credential file like every other command. Probe the RESOLVED
-        // model's provider through the normal resolution path (stored credential OR env var — an
-        // env-authed user is fine and must not be warned): only when that provider has no usable auth
-        // AND pi's old file exists does the bare provider error get its cause named.
-        if ((await probeAuthSource(modelRuntime, modelSpec)) === undefined &&
-            existsSync(join(getAgentDir(), "auth.json"))) {
-            log.warn(`[fastagent] no credentials for ${modelSpec} in ${authPath} — this runtime no longer reads ` +
-                `pi's ~/.pi auth; run \`fastagent login\` (or /login in the TUI) to store credentials for this agent`);
-        }
-        const model = resolveModel(modelRuntime, modelSpec);
         const env = new NodeExecutionEnv({ cwd });
         const definition = await loadAgentDefinition(agentDir, { cwd, env });
         reportFindingsIfChanged(definition.dir, definition);
-        const defaultNames = piDefaultTools().map((t) => t.name);
-        const customTools = tools.filter((t) => !defaultNames.includes(t.name));
+        // Assembly-time, like serving's: this whole function is memoized, so the scan and its warnings
+        // happen once per runtime rather than per session rebuild (/new, /resume, fork).
+        const extensionPaths = await loadExtensionPaths(agentDir, { cwd, env });
+        // fastagent mounts pi's complete coding set itself; `noTools: "builtin"` below keeps the runtime
+        // from adding duplicate copies.
         // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts
         // it). Each execute runs inside the turn context with the CURRENT session's activation bridge — the
         // assembly is memoized across /new//resume/fork rebuilds while the session changes, so the bridge
-        // resolves through sessionRef at call time, exactly like the serving path resolves its harness.
-        const customToolDefs = customTools.map((t) => ({
+        // resolves through sessionRef at call time, exactly like the serving path resolves its session.
+        const customToolDefs = tools.map((t) => ({
             name: t.name,
             label: t.name,
             description: t.description ?? "",
@@ -144,10 +122,8 @@ sessionManager) {
                 if (!bound)
                     throw new Error("tool executed before its session was built (lifecycle invariant broken)");
                 return turnContext.run({ cwd, sessionManager: bound.sessionManager, tools: bound.activation }, 
-                // pi's per-turn TOOL context (5th parameter) is read only by its default coding tools, and
-                // those are filtered out of `customTools` above; fastagent's own take theirs from
-                // `turnContext` (AsyncLocalStorage). So this env exists to satisfy the shape, and it is the
-                // chat cwd's — the same root a default tool would have got, had one reached here.
+                // Lower-level MountedTools may consume the fifth-argument env. Directory coding tools are
+                // cwd-bound and ignore it; authored tools read FastAgent's turnContext instead.
                 () => t.execute(id, params, signal, undefined, { env }));
             },
         }));
@@ -158,13 +134,14 @@ sessionManager) {
             contextFiles: definition.contextFiles,
         });
         return {
-            model,
             modelRuntime,
+            modelSpec,
+            authPath,
             // Serving honors config.thinkingLevel (config → L2); the resident session must too (fidelity).
             thinkingLevel: config.thinkingLevel,
             definition,
-            defaultNames,
-            customTools,
+            extensionPaths,
+            customTools: tools,
             customToolDefs,
             deferredToolNames,
             systemPrompt,
@@ -194,65 +171,84 @@ sessionManager) {
         assembly ??= resolveAssembly(rootCwd);
         return assembly;
     };
+    // The credential hint belongs to the RUNTIME, not to each session it builds: model resolution
+    // moved into createRuntime (extensions must load first), and repeating this on every /new,
+    // /resume and fork would nag about a setting that did not change.
+    let credentialHintShown = false;
     const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { model, modelRuntime, thinkingLevel, definition, defaultNames, customTools, customToolDefs, deferredToolNames, systemPrompt, } = await assemblyFor(cwd);
+        const { modelRuntime, modelSpec, authPath, thinkingLevel, definition, extensionPaths, customToolDefs, deferredToolNames, systemPrompt, } = await assemblyFor(cwd);
+        // Per session, NOT memoized with the assembly: pi replaces the session on /new, /resume and
+        // fork, and its extension contract is that the replacement gets freshly loaded extensions
+        // rather than the previous session's objects. The expensive halves (model hub, auth) are shared
+        // through the assembly; only the resource loader is rebuilt.
         const services = await createAgentSessionServices({
             cwd,
             // fastagent's models + auth hub replaces pi's default (~/.pi-backed) one — the auth
             // unification point; see the header.
             modelRuntime,
-            resourceLoaderOptions: {
-                // Definition-only, like dev/start: suppress pi's machine-global discovery (the developer's own
-                // ~/.pi extensions, slash commands, global AGENTS.md, APPEND_SYSTEM.md) so this runtime runs
-                // the same agent that gets served, not the authoring machine's pi setup on top.
-                noExtensions: true,
-                noPromptTemplates: true,
-                noContextFiles: true,
-                systemPromptOverride: () => systemPrompt,
-                appendSystemPromptOverride: () => [],
-                // Replace pi's discovered skills with fastagent's. fastagent's Skill (content inline) is
-                // reshaped to pi-coding-agent's (read from filePath/baseDir at invocation time).
-                skillsOverride: (base) => ({
-                    skills: definition.skills.map((s) => ({
-                        name: s.name,
-                        description: s.description,
-                        filePath: s.filePath,
-                        baseDir: dirname(s.filePath),
-                        sourceInfo: {
-                            path: s.filePath,
-                            source: "fastagent",
-                            scope: "project",
-                            origin: "top-level",
-                            baseDir: dirname(s.filePath),
-                        },
-                        disableModelInvocation: s.disableModelInvocation ?? false,
-                    })),
-                    diagnostics: base.diagnostics,
-                }),
-            },
+            // Chat's assembly is fixed for the life of the runtime (a rebuild makes a new one), so these
+            // read constants — where serving passes accessors that change per turn — and it DOES pass its
+            // extension paths: chat runs them.
+            resourceLoaderOptions: definitionResourceLoaderOptions({
+                systemPrompt: () => systemPrompt,
+                skills: () => definition.skills,
+                extensionPaths,
+            }),
         });
+        reportExtensionErrors(services);
+        // AFTER the services, because an extension may be what defines the model. `registerProvider()`
+        // is pi's documented way for one to add providers, and extensions do not execute until the
+        // services are built — resolving first fails a definition whose configured model comes from its
+        // own extension with a bare "unknown model", after warning about credentials for a provider
+        // that does not exist yet.
+        //
+        // MIGRATION HINT (deliberate breaking change): chat historically used pi's own `~/.pi` auth; it
+        // now reads the agent's credential file like every other command. Probe the RESOLVED model's
+        // provider through the normal resolution path (stored credential OR env var — an env-authed
+        // user is fine and must not be warned): only when that provider has no usable auth AND pi's old
+        // file exists does the bare provider error get its cause named.
+        if (!credentialHintShown &&
+            (await probeAuthSource(modelRuntime, modelSpec)) === undefined &&
+            existsSync(join(getAgentDir(), "auth.json"))) {
+            credentialHintShown = true;
+            log.warn(`[fastagent] no credentials for ${modelSpec} in ${authPath} — this runtime no longer reads ` +
+                `pi's ~/.pi auth; run \`fastagent login\` (or /login in the TUI) to store credentials for this agent`);
+        }
+        const model = resolveModel(modelRuntime, modelSpec);
         const result = await createAgentSessionFromServices({
             services,
             sessionManager,
             sessionStartEvent,
             model,
             thinkingLevel,
-            tools: [...defaultNames, ...customTools.map((t) => t.name)],
+            // NO `tools` allowlist. It would freeze the tool set at build time, and pi lets an extension
+            // register from `session_start`, a command, or any handler — those names would not be in a
+            // startup snapshot, so `refreshTools()` would filter them straight back out and the extension
+            // would look like it did nothing. `noTools: "builtin"` gets the same guarantee the allowlist
+            // was really there for (the machine's `defaultTools` setting cannot add pi's own copies on top
+            // of ours) without freezing anything.
+            noTools: "builtin",
             customTools: customToolDefs,
         });
         sessionRef.current = {
             session: result.session,
-            sessionManager: toolChatSessionManager(result.session),
+            sessionManager: agentSessionManager(result.session, result.session.sessionManager.getSessionId()),
             activation: sessionToolActivation(result.session),
         };
-        // Deferral emulation: pi's session starts with everything active — narrow it by SUBTRACTING
-        // the deferred names from whatever is active (robust to pi mounting tools of its own; an
-        // exact-set-equality gate would silently stop narrowing the day pi adds one). Applied on EVERY
-        // build including /resume: pi's chat session does not record activations (its SessionContext has
-        // no activeToolNames), so "restore prior activations" is not implementable here — deferral stays
-        // consistently ON and a resumed conversation re-discovers via search_tools (documented divergence
-        // from serving, where activations persist in the session). The deferred SET comes from the shared
-        // assembly (one definition of "deferred"), never recomputed here.
+        // NOT bound here: the HOST does it. InteractiveMode.bindCurrentSessionExtensions() calls
+        // session.bindExtensions() with the TUI's uiContext, abort handler and command actions — binding
+        // here too would emit session_start twice per chat, so an extension opening a resource on start
+        // would open two.
+        // Deferral emulation: pi starts THIS agent's tools active — every coding tool it mounted, plus
+        // every custom and extension tool. So narrow by SUBTRACTING the deferred names from whatever is
+        // active, rather than stating a set: an exact-set-equality gate would silently stop narrowing the
+        // day pi activates one more.
+        //
+        // Applied on EVERY build including /resume: pi's chat session does not record activations (its
+        // SessionContext has no activeToolNames), so "restore prior activations" is not implementable
+        // here — deferral stays consistently ON and a resumed conversation re-discovers via search_tools
+        // (a documented divergence from serving, where activations persist in the session). The deferred
+        // SET comes from the shared assembly (one definition of "deferred"), never recomputed here.
         if (deferredToolNames.length > 0) {
             const active = result.session.getActiveToolNames();
             if (deferredToolNames.some((n) => active.includes(n))) {

package/dist/engines/pi/session-control.d.ts

@@ -1,10 +1,11 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Models } from "@earendil-works/pi-ai";
 import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import type { SessionObserver } from "./invoke.ts";
+import type { SessionObserver } from "./turn-kit.ts";
 import type { Lease } from "./turn-kit.ts";
-import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
-import { type PiSessionReader } from "./sessions.ts";
+import type { AnyModel } from "./models.ts";
+import type { PiAgentSessionFactory } from "./invoke-session.ts";
+import type { PiSessionRecordStore } from "./session-store.ts";
 /** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
  *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
  *  has its buffer FROZEN at the cap (memory bounded — the actual goal: ≈10k small events ≈ a few
@@ -16,25 +17,25 @@ import { type PiSessionReader } from "./sessions.ts";
 export declare const SUBSCRIBER_BUFFER_CAP = 10000;
 /** What boundary mutations (compact / set_model / set_thinking / navigate) need — the SAME instances the
  *  agent assembly uses: the lease (mutations must not race a run), the model registry (validation +
- *  allowedModels), and the harness factory (compaction is a model call). Writes go through the
- *  session the hub's reader opened — after an existence check, so the control plane never creates
+ *  allowedModels), and the session factory (compaction is a model call). Writes go through the
+ *  record the hub's reader opened — after an existence check, so the control plane never creates
  *  a session (that is the data plane's monopoly). */
 export interface PiBoundaryWiring {
     lease: Lease;
     models: Models;
-    harnessFactory: PiHarnessFactory;
+    sessionFactory: PiAgentSessionFactory;
     /** The assembly's configured PAIR — what a session with no overrides runs on. One field because
      *  model and thinking level are one setting: which levels exist is a property of the model, so a
      *  wiring that could carry them apart could carry a pair no run uses. Must be what
-     *  {@link harnessFactory} was built with. */
+     *  {@link sessionFactory} was built with. */
     defaults: {
         model: AnyModel;
         thinkingLevel: ThinkingLevel;
     };
 }
 export interface CreatePiSessionControlOptions {
-    /** Read-only access to the durable session repository (the same root the agent writes). */
-    sessions: PiSessionReader;
+    /** Read-only access to the durable session records (the same root the agent writes). */
+    sessions: PiSessionRecordStore;
     /** Boundary-mutation wiring, as a LAZY thunk: the hub's observer must exist before the agent
      *  assembly that produces these parts, so the hub asks for them at dispatch time instead
      *  (assembly completes before any dispatch can arrive). Absent / undefined → boundary commands