@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/engines/pi/open.js

@@ -16,7 +16,7 @@ import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
 import { loadAgentSkills } from "./definition.js";
 import { reportFindingsIfChanged } from "./report.js";
-import { jsonlSessionStore } from "./sessions.js";
+import { piSessionRecordStore } from "./session-store.js";
 export async function resolveAgentAssembly(dir, options = {}) {
     // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
     // its parent — the WORKSPACE — is what the agent works on: its cwd and the start of the ②-context
@@ -27,7 +27,7 @@ export async function resolveAgentAssembly(dir, options = {}) {
     if (!modelSpec) {
         throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
     }
-    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir);
+    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace);
     // The state root: sessions/channel state/schedule state derive from it (FASTAGENT_STATE_DIR moves it
     // in one knob — a container points it at its volume); the finer overrides below still win.
     const stateRoot = resolveStateRoot(agentDir);
@@ -62,13 +62,14 @@ export async function createPiAgentFromDir(dir, options = {}) {
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
     const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
     await mkdir(sessionsDir, { recursive: true });
-    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: workspace });
+    const sessions = piSessionRecordStore({ dir: sessionsDir, cwd: workspace });
     // The hub is wired HERE because the store is created here: chicken-and-egg otherwise (the hub
-    // needs the store; the agent needs the hub's observer). Boundary parts (models/factory/lease)
+    // needs the store; the agent needs the hub's observer). Boundary parts (factory/lease/registry)
     // only exist after the assembly below — the hub takes them as a lazy thunk, filled by the
     // assembly's onAssembly callback (assembly completes before this function returns, so every
     // dispatch sees them). An extra caller observer composes after the hub's (TRUSTED seam).
     let boundaryParts;
+    let assembled;
     const caller = options.observer;
     const wantControl = options.sessionControl ?? (config.sessionControl === true && options.serving === true);
     const hub = wantControl
@@ -94,7 +95,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
             },
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
             // and never cross the data plane's observer seam — without this, an audit tap wired here
-            // would miss exactly the mutations it most needs to see (set_model).
+            // would miss exactly the mutations it most needs to see (`update({ model })`).
             tap: caller ? (session, event) => caller(session, event) : undefined,
         })
         : undefined;
@@ -117,20 +118,29 @@ export async function createPiAgentFromDir(dir, options = {}) {
         observer,
         onAssembly: hub
             ? (parts) => {
-                boundaryParts = {
-                    lease: parts.lease,
-                    models: parts.models,
-                    harnessFactory: parts.harnessFactory,
-                    defaults: parts.defaults,
-                };
+                assembled = parts;
             }
             : undefined,
     });
+    if (hub && assembled) {
+        // The hub's surface is synchronous (`capabilities()` lists the allowed models), while building
+        // the registry reads credentials and is not. Resolve it ONCE here — the opener is async anyway,
+        // and the first turn would have paid the same read — so every boundary mutation validates
+        // against the same registry the runs use.
+        const { modelRuntime, model } = await assembled.engine();
+        boundaryParts = {
+            lease: assembled.lease,
+            models: modelRuntime,
+            sessionFactory: assembled.sessionFactory,
+            defaults: { model, thinkingLevel: assembled.thinkingLevel },
+        };
+    }
     return {
         agent,
         definition,
         sessions,
         sessionControl: hub?.control,
+        selfSchedule: config.selfSchedule ?? false,
         agentDir,
         workspace,
         config,

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

@@ -4,7 +4,6 @@
  */
 import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
 import type { SkillCollision } from "./definition.ts";
-import type { ModuleLoadFailure } from "../../loader.ts";
 import type { ToolCollision } from "./tool.ts";
 type Findings = {
     collisions: SkillCollision[];
@@ -23,7 +22,4 @@ type Findings = {
 export declare function reportFindingsIfChanged(dir: string, def: Findings): void;
 export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;
-/** Report per-file module failures. The caller decides whether they are degradations (tools/schedules)
- *  or fatal (declared channels on the serving path). */
-export declare function reportModuleLoadFailures(failures: ModuleLoadFailure[]): void;
 export {};

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/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

@@ -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, type 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,27 @@
+/**
+ * `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";
+/**
+ * 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,18 @@
  * 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 { log, reportModuleLoadFailures } from "../../log.js";
+import { agentSessionManager, sessionToolActivation, turnContext, } from "./tool-context.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "./report.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
@@ -62,34 +48,6 @@ function toolChatSessionManager(session) {
 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
-     *  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.
@@ -99,36 +57,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 +93,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 +105,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,
@@ -177,11 +125,13 @@ sessionManager) {
     // 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
+    // while the memoized assembly (and its tool execute closures) stays. The bridge shares the
+    // session's lifetime because a tool call has to see what the previous one activated. 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.
+    // NO activation record here: pi's chat session has nowhere to put one (see sessionToolActivation's
+    // `onActivated`), which is the documented divergence from serving — a resumed chat re-discovers.
     const sessionRef = {};
     let assembly;
     const assemblyFor = (cwd) => {
@@ -194,65 +144,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,24 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Models } from "@earendil-works/pi-ai";
+/**
+ * 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 AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import type { SessionObserver } from "./invoke.ts";
-import type { Lease } from "./turn-kit.ts";
-import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
-import { type PiSessionReader } from "./sessions.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
@@ -14,27 +28,27 @@ import { type PiSessionReader } from "./sessions.ts";
  *  permanently stalled one holds the frozen buffer until its TCP connection dies. Recovery either
  *  way is the standard reconnect+backfill, semantically lossless. */
 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
+/** 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). */
 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