@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/engines/pi/models.js

@@ -1,14 +1,17 @@
 /**
  * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId
  * lookup) AND auth (per-request credential resolution). fastagent builds one per opener and threads
- * it into the harness alongside the selected `model`; the two must come from the same collection so
+ * it into the engine alongside the selected `model`; the two must come from the same collection so
  * the model's provider auth is in scope.
  */
+import { join } from "node:path";
 import { defaultProviderAuthContext } from "@earendil-works/pi-ai";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { fastagentCredentialStore } from "./auth.js";
+import { providerOf } from "./config.js";
 import { interactiveLoginKind } from "./login.js";
+import { AGENT_MODELS_FILE, resolveStateRoot } from "../../paths.js";
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
@@ -25,21 +28,73 @@ export function createPiModels(options = {}) {
         models.setProvider(provider);
     return models;
 }
+/**
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the engine, whose fallback is "off": an author vibes
+ * at "medium" in pi and must get "medium" when served (fidelity), and pinning the value here means
+ * an upstream default change in either place cannot silently alter deployments. Models that do not
+ * support a level are clamped by pi per model.
+ */
+export const DEFAULT_THINKING_LEVEL = "medium";
 /**
  * The `ModelRuntime`-shaped sibling of {@link createPiModels} — the SAME hub semantics (built-in
  * providers + fastagent's credential store at `authPath`) in the type pi's session services require
- * (`createAgentSessionServices({ modelRuntime })`). Builtins only (`modelsPath: null` — pi's
- * machine-global models.json is definition-foreign) and no availability network, so the model
- * surface equals serving's. No `providers` option: `ModelRuntime` registers providers by config
- * record, not `Provider` instance — accepting the option and dropping it would be a silent no-op;
- * add the mapping when a consumer actually needs it.
+ * (`createAgentSessionServices({ modelRuntime })`). Built-ins PLUS the agent's own
+ * {@link AGENT_MODELS_FILE} when `agentDir` is given (a dir-less caller gets built-ins only), and no
+ * availability network, so the model surface equals serving's.
+ *
+ * `ModelRuntime` also takes `Provider` INSTANCES via `registerNativeProvider` (pi 0.83); the
+ * declarative file is what this rung wires because it is data that travels with the definition.
  */
-export function createPiModelRuntime(options = {}) {
-    return ModelRuntime.create({
+export async function createPiModelRuntime(options = {}) {
+    const { agentDir } = options;
+    const runtime = await ModelRuntime.create({
         credentials: fastagentCredentialStore(options.authPath, { warn: options.warn }),
-        modelsPath: null,
+        modelsPath: agentDir ? join(agentDir, AGENT_MODELS_FILE) : null,
+        // MUST be set whenever modelsPath is: pi defaults this to `<dirname(modelsPath)>/models-store.json`,
+        // which would write a generated cache INTO the author's agent dir — and `deploy` bakes the whole
+        // tree, so it would travel into the image as stale state. Machinery belongs under the state root.
+        ...(agentDir
+            ? { modelsStorePath: join(options.stateRoot ?? resolveStateRoot(agentDir), "models-store.json") }
+            : {}),
         allowModelNetwork: false,
     });
+    // A malformed models.json does NOT throw upstream — `create` resolves with the built-ins and parks the
+    // reason in getError(). Left unread, a typo'd endpoint would silently degrade to "provider not in
+    // registry" at model-resolution time, i.e. the silent fallback this codebase forbids. The upstream
+    // message already names both the reason and the file, so it is surfaced verbatim.
+    const error = runtime.getError();
+    if (error)
+        throw new Error(error);
+    for (const provider of options.providers ?? [])
+        runtime.registerNativeProvider(provider);
+    return runtime;
+}
+/**
+ * How a model's credential will REACH a deployed agent — the question `deploy` asks, which
+ * {@link probeAuthSource} cannot answer: it flattens every models.json endpoint to the display label
+ * "configured API key", so a self-hosted endpoint looks credential-less to the deploy gate even when
+ * its key is sitting in an env var.
+ *
+ * - `envVar`: an environment variable backs it, BY NAME — the shape `deploy` already understands, so
+ *   the value carries as a host secret with no extra declaration from the author.
+ * - `inDefinition`: the definition itself carries it (a literal `apiKey`, or a `!command` run on the
+ *   host). Nothing for `deploy` to carry — and nothing to gate on either, which is the point: the
+ *   `fastagent login` remedy is meaningless for a provider login cannot serve.
+ *
+ * Neither set = a stored credential or nothing at all; the existing auth.json / gate paths decide.
+ */
+export function modelCredentialCarry(runtime, spec) {
+    const status = runtime.getProviderAuthStatus(providerOf(spec));
+    if (!status.configured)
+        return { inDefinition: false };
+    // An env-var name is only useful downstream if it IS one: `"${A}_${B}"` interpolation resolves from
+    // the environment but has no single name to carry, so it falls through to the definition-carried
+    // branch, where the author's `deploy.secrets` is the mechanism.
+    if (status.source === "environment" && status.label && /^[A-Z][A-Z0-9_]*$/.test(status.label)) {
+        return { envVar: status.label, inDefinition: false };
+    }
+    return { inDefinition: status.source !== "stored" };
 }
 /**
  * Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe)

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

@@ -1,10 +1,10 @@
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import type { SessionControl } from "../../session.ts";
-import type { SessionObserver } from "./invoke.ts";
-import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
+import type { SessionObserver } from "./turn-kit.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type LoadedDefinition } from "./definition.ts";
+import { type PiSessionRecordStore } from "./session-store.ts";
 import type { ToolCollision } from "./tool.ts";
 import type { MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {
@@ -44,7 +44,7 @@ export interface CreatePiAgentFromDirOptions {
 }
 /**
  * The agent assembly FRONT HALF — everything that is independent of how pi consumes the
- * definition (transient harness for serving vs resident AgentSession for chat / session control):
+ * definition (a per-invoke session for serving vs a resident one for chat):
  * placement resolution → config → model spec → the full tool surface ({@link resolveAgentTools} — the
  * ONE place it is computed) → state root → auth path. Both {@link createPiAgentFromDir} and the
  * session builder (session-builder.ts) consume this, so THESE inputs cannot drift between the two
@@ -65,7 +65,7 @@ export interface AgentAssembly {
     stateRoot: string;
     /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <agentDir>/.secrets/auth.json). */
     authPath: string;
-    /** The full mounted tool surface (config.tools + discovered tools/, search_tools applied). */
+    /** The full mounted tool surface (all coding tools + config.tools + discovered tools/, search_tools applied). */
     tools: MountedTool[];
     toolNames: string[];
     deferredToolNames: string[];
@@ -99,10 +99,13 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     sessionsDir: string;
     /** Absolute credentials file in use (for the startup report). */
     authPath: string;
-    /** The session store in use — also a {@link PiSessionReader}. */
-    sessions: PiSessionStore & PiSessionReader;
+    /** The session store in use. */
+    sessions: PiSessionRecordStore;
     /** The observation plane over this agent's sessions; present iff `options.sessionControl`. */
     sessionControl?: SessionControl;
+    /** Whether the agent schedules its own follow-up turns — read from the config, so a caller
+     *  assembling a service does not have to reach back into it (MountableAgent). */
+    selfSchedule: boolean;
     /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
      *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */
     toolNames: string[];

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
@@ -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/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,34 +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.
-        const { config, modelSpec, agentDir, authPath, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
+        // 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.
-        const modelRuntime = await createPiModelRuntime({ authPath });
-        // 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);
+        // 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 });
         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 ?? "",
@@ -142,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 }));
             },
         }));
@@ -156,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,
@@ -192,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,9 +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 { Lease, SessionObserver } from "./invoke.ts";
-import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
-import { type PiSessionReader } from "./sessions.ts";
+import type { SessionObserver } from "./turn-kit.ts";
+import type { 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
@@ -15,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