@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/engines/pi/search-tools.js

@@ -124,7 +124,7 @@ export function makeSearchToolsTool() {
                     .map((t) => t.name)
                     .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
             }
-            const activated = await ctx.tools.activate(inactiveMatches.map((t) => t.name));
+            const activated = ctx.tools.activate(inactiveMatches.map((t) => t.name));
             // Report what actually happened, not what was attempted: a parallel sibling call may have
             // activated the same matches first, leaving nothing new here — an empty "Activated:" would lie.
             if (activated.length === 0) {

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

@@ -6,7 +6,7 @@
  * 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";
+import { type AgentService, type MountAgentServiceOptions } from "../../service.ts";
 export interface CreateAgentServiceOptions extends MountAgentServiceOptions {
     model?: string;
     authPath?: string;

package/dist/engines/pi/service.js

@@ -1,3 +1,11 @@
+/**
+ * `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 { mountAgentService } from "../../service.js";
 import { createPiAgentFromDir } from "./open.js";
 /**

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

@@ -1,10 +1,9 @@
 /**
  * The shared definition-aware session builder: open a directory's assembled agent as a resident pi
- * `AgentSessionRuntime`. Extracted from chat.ts (session-control Phase 0) as the proof of the
- * assembly seam — independently instantiable, running the SAME agent that `dev`/`start` serve. The
- * TUI (chat.ts) is its one consumer: the session control plane (Phases 1–3) was built on the invoke
- * pipeline instead of this resident runtime, so control-plane observation covers invoke-driven runs
- * and deliberately not chat sessions (design §10/§15).
+ * `AgentSessionRuntime`, running the SAME agent that `dev`/`start` serve. The TUI (chat.ts) is its
+ * one consumer: the session control plane was built on the invoke pipeline instead of this resident
+ * runtime, so control-plane observation covers invoke-driven runs and deliberately not chat sessions
+ * (docs/design/session-control.md §10, §15).
  *
  * FIDELITY: pi's vanilla discovery (AGENTS.md walk to repo root, machine-global skills/extensions)
  * is suppressed; fastagent's assembly is INJECTED into pi's session:
@@ -28,18 +27,16 @@
  * workspace.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { 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 { SessionManager, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { bindPiSession, definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
 import { resolveModel } from "./config.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, agentSessionManager, turnContext, } from "./tool-context.js";
+import { createPiModelRuntime } from "./models.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "./report.js";
-import { reportModuleLoadFailures } from "../../log.js";
 import { resolveAgentAssembly } from "./open.js";
 /**
  * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
@@ -49,45 +46,12 @@ import { resolveAgentAssembly } from "./open.js";
 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
-     *  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) {
-        // Same serialization as invoke.ts's bridge (there per turn; here per session — interactive turns
-        // make per-session equivalent): the read-modify-write below is only race-free while nothing awaits
-        // between read and write, and pi's session setters happening to be synchronous today is not a
-        // contract worth betting parallel tool batches on. Built ONCE per session (createRuntime), so
-        // parallel calls actually share the chain.
-        let chain = Promise.resolve([]);
-        return {
-            active: () => session.getActiveToolNames(),
-            registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
-            activate(names) {
-                const run = async () => {
-                    const current = session.getActiveToolNames();
-                    const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
-                    if (added.length > 0)
-                        session.setActiveToolsByName([...current, ...added]);
-                    return added;
-                };
-                const result = chain.then(run, run); // run after the predecessor settles, success or failure
-                chain = result.catch(() => []); // the caller sees a rejection on `result`; the chain stays usable
-                return result;
-            },
-        };
-    }
     async function resolveAssembly(cwd) {
         // The shared front half — the SAME placement/config/model-spec/tool/auth resolution the serving
         // opener uses (open.ts); those inputs cannot drift between the two consumption shapes.
-        // (Definition→prompt assembly is NOT shared: serving re-reads live per invoke, this runtime is a
-        // startup snapshot and pi appends skills/env itself — see the header.) `tools` arrives with
-        // search_tools applied; deferral is EMULATED below like serving
-        // (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 the served one.
-        const { config, modelSpec, agentDir, authPath, stateRoot, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
+        // Serving re-reads the definition per invoke; chat keeps a startup snapshot. Both pass identity
+        // and project context to Pi, which appends skills/cwd. `tools` already includes search_tools.
+        const { config, modelSpec, agentDir, authPath, stateRoot, tools, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
         reportToolCollisions(toolCollisions);
         reportModuleLoadFailures(toolFailures);
         // ONE hub owns model resolution AND per-request auth; see models.ts.
@@ -100,33 +64,6 @@ sessionManager) {
         // 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 session.
-        const customToolDefs = tools.map((t) => ({
-            name: t.name,
-            label: t.name,
-            description: t.description ?? "",
-            parameters: t.parameters,
-            // Propagate the execution mode — an activating tool (the builtin loader) declares "sequential"
-            // so pi serializes its batch; without this, pi's outer active-set diff double-stamps parallels.
-            executionMode: t.executionMode,
-            execute: (id, params, signal) => {
-                const bound = sessionRef.current;
-                // Unreachable by construction (createRuntime sets sessionRef before any turn can run a tool).
-                // Throw rather than silently run outside the turn context — that would disguise a broken
-                // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
-                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 }, 
-                // 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 }));
-            },
-        }));
         // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
         // them here would duplicate them).
         const systemPrompt = assembleSystemPrompt({
@@ -136,14 +73,11 @@ sessionManager) {
         return {
             modelRuntime,
             modelSpec,
-            authPath,
             // Serving honors config.thinkingLevel (config → L2); the resident session must too (fidelity).
             thinkingLevel: config.thinkingLevel,
             definition,
             extensionPaths,
-            customTools: tools,
-            customToolDefs,
-            deferredToolNames,
+            tools,
             systemPrompt,
         };
     }
@@ -153,13 +87,6 @@ sessionManager) {
     // load edits. And keep it workspace-scoped — `.env` is process-global, so a switch to another cwd
     // would leak env or require mutating global env at runtime.
     const rootCwd = canonicalPath(dir);
-    // The CURRENT pi session + its activation bridge, BOUND TOGETHER — rebuilt on /new//resume/fork
-    // while the memoized assembly (and its tool execute closures) stays. The bridge must share the
-    // session's lifetime, NOT be rebuilt per tool call (a per-call chain serializes nothing). Note on
-    // parallel batches: pi wraps SDK customTools in its own before/after active-set diff, so an
-    // activating tool must carry `executionMode: "sequential"` (the builtin loader does) — pi then runs
-    // the whole batch serially and the outer diff sees correct snapshots.
-    const sessionRef = {};
     let assembly;
     const assemblyFor = (cwd) => {
         // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would
@@ -171,12 +98,8 @@ 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 { modelRuntime, modelSpec, authPath, thinkingLevel, definition, extensionPaths, customToolDefs, deferredToolNames, systemPrompt, } = await assemblyFor(cwd);
+        const { modelRuntime, modelSpec, thinkingLevel, definition, extensionPaths, tools, 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
@@ -199,62 +122,25 @@ sessionManager) {
         // 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`);
-        }
+        // own extension with a bare "unknown model".
         const model = resolveModel(modelRuntime, modelSpec);
-        const result = await createAgentSessionFromServices({
+        // The same bind serving performs, minus the activation record: pi's chat session has nowhere to
+        // put one, which is the documented divergence — a resumed chat re-discovers via search_tools.
+        // NOT bound to the host here: 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.
+        const result = await bindPiSession({
             services,
             sessionManager,
             sessionStartEvent,
             model,
             thinkingLevel,
-            // 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,
+            tools,
+            // A tool must see one spelling of the workspace, including when opened through a symlink.
+            cwd: rootCwd,
+            recordActivations: false,
         });
-        sessionRef.current = {
-            session: result.session,
-            sessionManager: agentSessionManager(result.session, result.session.sessionManager.getSessionId()),
-            activation: sessionToolActivation(result.session),
-        };
-        // 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))) {
-                result.session.setActiveToolsByName(active.filter((n) => !deferredToolNames.includes(n)));
-            }
-        }
         return { ...result, services, diagnostics: services.diagnostics };
     };
     const runtime = await createAgentSessionRuntime(createRuntime, {

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

@@ -1,22 +1,30 @@
+/**
+ * The pi implementation of the session control plane. `createPiSessionControl` returns the neutral
+ * `SessionControl` plus the {@link SessionObserver} to plug into the invoke pipeline
+ * (`createPiAgent({ observer })`).
+ *
+ * It holds no durable state of its own: live truth comes from the event stream (plus the
+ * {@link RunControls} a `run_started` carries), durable truth from {@link PiSessionRecordStore} —
+ * which is also what performs every write, so how a record takes a property is not knowledge this
+ * file has. What it owns is the vocabulary: capability gating, the lease, error codes, and the
+ * events its own writes emit.
+ *
+ * Writes take the same lease as runs. Without boundary wiring they reject before acceptance with
+ * `unsupported_capability` — a client gating on `capabilities()` never sends them.
+ */
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Models } from "@earendil-works/pi-ai";
+import { type Models } from "@earendil-works/pi-ai";
 import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import type { SessionObserver } from "./turn-kit.ts";
-import type { Lease } from "./turn-kit.ts";
+import type { SessionObserver, Lease } from "./turn-kit.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
- *  MB worst case per stuck connection) and its subscription marked closed. The close is observed
- *  via pulls — which a stalled connection by definition does not make — so a consumer that RESUMES
- *  pulling first drains the frozen backlog, then gets done (no buffered event dropped), while a
- *  permanently stalled one holds the frozen buffer until its TCP connection dies. Recovery either
- *  way is the standard reconnect+backfill, semantically lossless. */
+/** Per-subscriber backlog limits: event count and UTF-8 JSON bytes. Overflow freezes the accepted
+ *  prefix; the reader drains it before seeing done, then reconnects and backfills via entries(). */
 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 +
+export declare const SUBSCRIBER_BUFFER_BYTES: number;
+/** What the plane's writes (`update` / `compact` / `fork` / `delete`) need — the SAME instances the
+ *  agent assembly uses: the lease (a write must not race a run), the model registry (validation +
  *  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). */
@@ -36,15 +44,12 @@ export interface PiBoundaryWiring {
 export interface CreatePiSessionControlOptions {
     /** 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
-     *  are gated off in `capabilities()` and rejected `unsupported_capability`. */
-    boundary?: () => PiBoundaryWiring | undefined;
-    /** The definition's names, as a LAZY thunk for the same reason {@link boundary} is one (the hub
-     *  exists before the assembly that can read a definition) — and async because the definition is
-     *  live: this must re-read it, not close over a boot snapshot, or `commands()` would advertise a
-     *  list the next turn no longer runs.
+    /** Boundary-mutation wiring — the assembly's own parts. Absent → boundary commands are gated off
+     *  in `capabilities()` and rejected `unsupported_capability`. */
+    boundary?: PiBoundaryWiring;
+    /** The definition's names, as an async thunk because the definition is live: this must re-read it,
+     *  not close over a boot snapshot, or `commands()` would advertise a list the next turn no longer
+     *  runs.
      *
      *  OPTIONAL because absence is a TRUE answer for the assembly that omits it: a hub over an L1
      *  agent (`createPiAgent({ model, instructions, tools })`) has no definition and therefore no