@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/engines/pi/chat.js

@@ -3,271 +3,18 @@
  * engine-neutral channel: it drives pi's full session API (InteractiveMode) for fidelity, so it lives
  * under engines/pi/ and is not re-exported.
  *
- * FIDELITY: chat must run the SAME agent dev/start serve, not pi's vanilla discovery (which would walk
- * AGENTS.md up to the repo root and discover skills from pi's own global dirs). So fastagent's
- * assembly is INJECTED into pi's session:
- *   - 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).
- *
- * Cross-workspace session switches are rejected: `.env` is process-global, so one chat TUI is one
- * workspace.
- *
- * AUTH: chat is the one command that does NOT use fastagent's credential file. It drives pi's own
- * session services (`createAgentSessionServices`, auth from pi's `~/.pi` via `getAgentDir()`), so you
- * log in through pi's TUI, not `fastagent login`. `--auth-path`/`FASTAGENT_AUTH_PATH` therefore do not
- * apply here, and `createPiModels()` below is used only to RESOLVE the model descriptor (never for auth).
- */
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { InteractiveMode, SessionManager, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
-import { loadConfig, resolveAgentDir, resolveModel, resolveModelSpec } from "./config.js";
-import { assembleSystemPrompt, piBasePrompt, piDefaultTools, resolveTools } from "./create.js";
-import { createPiModels } from "./models.js";
-import { canonicalPath, loadAgentDefinition } from "./definition.js";
-import { isDeferredTool, loadTools, mergeDiscoveredTools } from "./tool.js";
-import { withSearchTool } from "./search-tools.js";
-import { additiveActivation, turnContext } from "./tool-context.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
-/**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
- * skills resolved exactly as the dev opener does). Split from {@link runPiChat} so the assembly —
- * the fidelity-critical part — is inspectable without launching the TUI.
- */
-export async function buildChatRuntime(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 chat 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 chatToolActivation(session) {
-        // Same serialization as invoke.ts's bridge (there per turn; here per session — chat turns are
-        // interactive, so per-session is 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) {
-        const { config } = await loadConfig(cwd);
-        const modelSpec = resolveModelSpec(options.model, config);
-        if (!modelSpec) {
-            throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
-        }
-        // Resolution only — the Models' auth is unused here; chat's auth is pi's own (~/.pi via the session
-        // services), so authPath is intentionally not threaded in. See the AUTH note in the header.
-        const model = resolveModel(createPiModels(), modelSpec);
-        const env = new NodeExecutionEnv({ cwd });
-        // Same agentDir/cwd split as dev/start: persona/skills/tools from agentDir, ② context walked from cwd.
-        const agentDir = resolveAgentDir(cwd, config);
-        const definition = await loadAgentDefinition(agentDir, { cwd, env });
-        reportDefinitionWarnings(definition.collisions, definition.diagnostics);
-        // Same tool resolution as the dev opener, then split: defaults go to pi by NAME (rebuilt cwd-bound
-        // for rich rendering); customs go through pi's `customTools` path so they survive /new, /resume, fork.
-        const discovered = await loadTools(agentDir);
-        const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-        // Chat EMULATES deferral, like serving (what you iterate is what you serve): the builtin loader
-        // mounts when a deferred tool exists, the initial active set excludes deferred tools (applied on
-        // the session in createRuntime below — pi's TUI session starts all-active), and the activation
-        // bridge below rides the same turn context the serving path uses, so the SAME search_tools works
-        // against pi's AgentSession instead of fastagent's harness.
-        const tools = withSearchTool(merged.tools);
-        const crossCollisions = merged.collisions;
-        reportToolCollisions([...discovered.collisions, ...crossCollisions]);
-        reportModuleLoadFailures(discovered.failures);
-        const defaultNames = piDefaultTools(cwd).map((t) => t.name);
-        const customTools = tools.filter((t) => !defaultNames.includes(t.name));
-        // 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) => ({
-            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("chat tool executed before its session was built (lifecycle invariant broken)");
-                return turnContext.run({ session: bound.session.sessionId, tools: bound.activation }, () => t.execute(id, params, signal));
-            },
-        }));
-        // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
-        // them here would duplicate them).
-        const systemPrompt = assembleSystemPrompt({
-            base: piBasePrompt({ tools, persona: definition.persona }),
-            contextFiles: definition.contextFiles,
-        });
-        return { model, definition, defaultNames, customTools, customToolDefs, systemPrompt };
-    }
-    // pi calls the factory again on /new, /resume, switch, and fork. Config/tools dynamic imports are
-    // ESM-cached, so treating same-cwd rebuilds as hot reload would yield a half-fresh agent (fresh
-    // AGENTS.md/skills, stale config/tools). Keep chat a coherent startup snapshot: restart to 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
-        // otherwise mismatch a non-realpath rootCwd.
-        const activeCwd = canonicalPath(cwd);
-        if (activeCwd !== rootCwd) {
-            throw workspaceScopeError(activeCwd);
-        }
-        assembly ??= resolveAssembly(rootCwd);
-        return assembly;
-    };
-    const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { model, definition, defaultNames, customTools, customToolDefs, systemPrompt } = await assemblyFor(cwd);
-        const services = await createAgentSessionServices({
-            cwd,
-            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 chat 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,
-                }),
-            },
-        });
-        const result = await createAgentSessionFromServices({
-            services,
-            sessionManager,
-            sessionStartEvent,
-            model,
-            tools: [...defaultNames, ...customTools.map((t) => t.name)],
-            customTools: customToolDefs,
-        });
-        sessionRef.current = { session: result.session, activation: chatToolActivation(result.session) };
-        // Deferral emulation: pi's TUI 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).
-        const deferredNames = customTools.filter(isDeferredTool).map((t) => t.name);
-        if (deferredNames.length > 0) {
-            const active = result.session.getActiveToolNames();
-            if (deferredNames.some((n) => active.includes(n))) {
-                result.session.setActiveToolsByName(active.filter((n) => !deferredNames.includes(n)));
-            }
-        }
-        return { ...result, services, diagnostics: services.diagnostics };
-    };
-    const runtime = await createAgentSessionRuntime(createRuntime, {
-        cwd: rootCwd,
-        agentDir: getAgentDir(),
-        sessionManager: sessionManager ?? SessionManager.create(rootCwd),
-    });
-    enforceWorkspaceScopedSessionSwitches(runtime, rootCwd);
-    return runtime;
-}
-function workspaceScopeError(targetCwd) {
-    return new Error(`fastagent chat is workspace-scoped: cannot switch to ${targetCwd}; run \`fastagent chat ${targetCwd}\` instead`);
-}
-function readSessionHeaderCwd(sessionPath) {
-    const resolvedPath = resolve(sessionPath);
-    if (!existsSync(resolvedPath))
-        return undefined;
-    for (const line of readFileSync(resolvedPath, "utf8").split(/\r?\n/)) {
-        if (!line.trim())
-            continue;
-        try {
-            const entry = JSON.parse(line);
-            if (entry.type === "session")
-                return typeof entry.cwd === "string" ? canonicalPath(entry.cwd) : undefined;
-        }
-        catch {
-            // Ignore malformed lines the same way pi's session loader does; no header cwd → caller pins root.
-        }
-    }
-    return undefined;
-}
-/**
- * Keep resume/import inside the chat's single workspace, deciding BEFORE delegating to pi. The chat
- * process is chdir'd into rootCwd, so a session with no cwd header already lands on rootCwd. The gap
- * is a session that EXPLICITLY records a different cwd: pi would bind it and the factory would reject
- * it — but only AFTER tearing the live session down. Reject such a switch up front.
+ * The TUI is ONE consumer of the shared definition-aware builder (session-builder.ts) — the same
+ * assembly, model surface, and fastagent auth that serving uses. Log in with `fastagent login` (or
+ * pi's TUI `/login`, which writes through the same credential store into the workspace auth file).
  */
-function enforceWorkspaceScopedSessionSwitches(runtime, rootCwd) {
-    const rejectForeignTarget = (sessionPath, cwdOverride) => {
-        const target = cwdOverride !== undefined ? canonicalPath(cwdOverride) : readSessionHeaderCwd(sessionPath);
-        if (target !== undefined && target !== rootCwd)
-            throw workspaceScopeError(target);
-    };
-    const switchSession = runtime.switchSession.bind(runtime);
-    runtime.switchSession = async (...args) => {
-        rejectForeignTarget(args[0], args[1]?.cwdOverride);
-        return switchSession(...args);
-    };
-    const importFromJsonl = runtime.importFromJsonl.bind(runtime);
-    runtime.importFromJsonl = async (...args) => {
-        rejectForeignTarget(args[0], args[1]);
-        return importFromJsonl(...args);
-    };
-}
+import { InteractiveMode } from "@earendil-works/pi-coding-agent";
+import { buildWorkspaceSessionRuntime } from "./session-builder.js";
 /**
  * Open the workspace's agent in pi's interactive TUI and run until the user exits. The agent is
- * fastagent's assembled agent (same model/tools/skills/prompt as dev/start serve); pi's TUI handles
- * login, rendering, and same-workspace sessions natively.
+ * fastagent's assembled agent (same model/tools/skills/prompt/auth as dev/start serve); pi's TUI
+ * handles login, rendering, and same-workspace sessions natively.
  */
 export async function runPiChat(dir, options = {}) {
-    const runtime = await buildChatRuntime(dir, options);
+    const runtime = await buildWorkspaceSessionRuntime(dir, options);
     await new InteractiveMode(runtime, {}).run();
 }

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

@@ -1,10 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import type { AnyModel } from "./harness.ts";
-/** pi's thinking levels (types.d.ts `ThinkingLevel`), as a runtime list for config validation — pi
- *  exports only the type. A level the selected model does not support is clamped by pi per model. */
-export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+import { type AnyModel } from "./harness.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
@@ -30,6 +27,15 @@ export interface FastagentConfig {
      *  Off by default — self-scheduling is an autonomy capability, opt in when you want it. Only takes
      *  effect on the serving path (`dev`/`start`, where the scheduler poller honors a wake-up). */
     selfSchedule?: boolean;
+    /**
+     * Serve the session control plane over HTTP (`/control/*`: state/entries/events + dispatch —
+     * steer/abort/compact/set_model…) for remote consumers: a Web panel, a desktop app, `fastagent
+     * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
+     * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
+     * binds all interfaces, so the routes are LAN-reachable with the token as the only protection —
+     * firewall the port, or wrap it for real exposure (design §14).
+     */
+    sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a
      *  Dockerfile / hand-set variables. */
     deploy?: {
@@ -65,6 +71,10 @@ export declare function loadConfig(dir: string): Promise<LoadedConfig>;
  * already validated that agentDir stays under `dir`.
  */
 export declare function resolveAgentDir(dir: string, config: FastagentConfig): string;
+/** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
+ *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
+ *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
+export declare function providerOf(spec: string): string;
 /** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
@@ -93,11 +103,6 @@ export declare function resolveSessionsDirOverride(flag: string | undefined, env
  * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
  */
 export declare function resolveAuthPathOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
- * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
- */
-export declare function projectStateDir(dir: string): string;
 /**
  * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
  * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels

package/dist/engines/pi/config.js

@@ -14,22 +14,12 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * live in persona.md + skills, with AGENTS.md as project context). Deleting the config still leaves a
  * zero-config agent runnable with a model supplied by --model / FASTAGENT_MODEL.
  */
-import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
+import { THINKING_LEVELS } from "./harness.js";
 import { moduleLoadHint } from "../../loader.js";
-/** pi's thinking levels (types.d.ts `ThinkingLevel`), as a runtime list for config validation — pi
- *  exports only the type. A level the selected model does not support is clamped by pi per model. */
-export const THINKING_LEVELS = [
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max",
-];
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
@@ -67,7 +57,14 @@ export async function loadConfig(dir) {
     const path = found[0];
     let mod;
     try {
-        mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+        // Cache-bust on file change: ESM `import()` caches by URL, so a config REWRITTEN in this process
+        // (the first-run picker's write-back) would otherwise read back stale — deploy's model-travel gate
+        // then contradicts the "saved model" line it just printed. mtime keeps unchanged files cached;
+        // its resolution is the ceiling — a rewrite within the same timestamp tick reads stale (fine for
+        // the write-back: sub-tick only on coarse-mtime filesystems, and the next process starts fresh).
+        const url = pathToFileURL(path);
+        url.searchParams.set("v", String(statSync(path).mtimeMs));
+        mod = (await import(__rewriteRelativeImportExtension(url.href)));
     }
     catch (error) {
         throw new Error(`${path}: ${error.message}${moduleLoadHint(error)}`);
@@ -86,15 +83,19 @@ export async function loadConfig(dir) {
             key !== "tools" &&
             key !== "http" &&
             key !== "deploy" &&
-            key !== "selfSchedule") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, agentDir, tools, http, deploy, selfSchedule)`);
+            key !== "selfSchedule" &&
+            key !== "sessionControl") {
+            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, agentDir, tools, http, deploy, selfSchedule, sessionControl)`);
         }
     }
     if (c.model !== undefined && typeof c.model !== "string") {
         throw new Error(`${path}: "model" must be a "provider/modelId" string`);
     }
-    if (c.thinkingLevel !== undefined && !THINKING_LEVELS.includes(c.thinkingLevel)) {
-        throw new Error(`${path}: "thinkingLevel" must be one of ${THINKING_LEVELS.join(", ")}`);
+    if (c.sessionControl !== undefined && typeof c.sessionControl !== "boolean") {
+        throw new Error(`${path}: "sessionControl" must be a boolean`);
+    }
+    if (c.thinkingLevel !== undefined && !THINKING_LEVELS.has(c.thinkingLevel)) {
+        throw new Error(`${path}: "thinkingLevel" must be one of ${[...THINKING_LEVELS].join(", ")}`);
     }
     if (c.agentDir !== undefined && typeof c.agentDir !== "string") {
         throw new Error(`${path}: "agentDir" must be a string (a subdirectory relative to the config file)`);
@@ -189,6 +190,13 @@ export async function loadConfig(dir) {
 export function resolveAgentDir(dir, config) {
     return resolve(dir, config.agentDir ?? ".");
 }
+/** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
+ *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
+ *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
+export function providerOf(spec) {
+    const slash = spec.indexOf("/");
+    return slash > 0 ? spec.slice(0, slash) : spec;
+}
 /** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
 export function resolveModel(models, spec) {
     const slash = spec.indexOf("/");
@@ -227,6 +235,13 @@ export function rewriteConfigModel(src, spec) {
         return src.replace(commented, line);
     if (active.test(src))
         return src.replace(active, line);
+    // No model line at all — the natural state after "picked once, then hand-deleted the line to reset".
+    // Re-INSERT at the top of the default-export object while the config still has the scaffold's block
+    // shape; anything else (a wrapper call, a one-liner, a computed export) is hand-shaped — leave it
+    // untouched (the caller prints the set-it-yourself hint).
+    const opener = /^export default[ \t]*\{[ \t]*$/m;
+    if (opener.test(src))
+        return src.replace(opener, (open) => `${open}\n${line}`);
     return null;
 }
 /** Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. */
@@ -268,7 +283,7 @@ export function resolveAuthPathOverride(flag, env = process.env) {
  * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
  * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
  */
-export function projectStateDir(dir) {
+function projectStateDir(dir) {
     return join(dir, ".fastagent");
 }
 /**

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

@@ -1,12 +1,13 @@
 import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Provider } from "@earendil-works/pi-ai";
+import type { Models, Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
+import { piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type FastagentTool, type ToolCollision } from "./tool.ts";
-import { type Lease } from "./invoke.ts";
+import { type Lease, type SessionObserver } from "./invoke.ts";
 /** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
 export declare function piDefaultTools(cwd: string): AgentTool[];
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
@@ -52,6 +53,17 @@ export interface AssembleSystemPromptOptions {
     cwd?: string;
 }
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
+/**
+ * INTERNAL seam (workspace ↔ assembly): hands the hub-wiring consumer the assembly's live parts —
+ * the SAME models collection, harness factory, and lease the agent runs with — so boundary
+ * mutations (session-control.ts) contend on the real lease and validate against the real registry.
+ * Called synchronously, exactly once, before the agent is returned. Not part of the public surface.
+ */
+type OnAssembly = (parts: {
+    models: Models;
+    harnessFactory: ReturnType<typeof piHarnessFactory>;
+    lease: Lease;
+}) => void;
 /** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
 export interface CreatePiAgentOptions {
     /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
@@ -86,6 +98,9 @@ export interface CreatePiAgentOptions {
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
+    /** Observation-plane tap (session control): every rich session event of every run. Wire the one
+     *  returned by `createPiSessionControl` to serve `state`/`entries`/`events` for this agent. */
+    observer?: SessionObserver;
 }
 /** L1: assemble from typed parts. */
 export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
@@ -124,6 +139,10 @@ export interface CreatePiAgentFromDefinitionOptions {
      *  context loader remain local today, so injecting this alone does not sandbox a directory agent. */
     env?: ExecutionEnv;
     lease?: Lease;
+    /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */
+    observer?: SessionObserver;
+    /** INTERNAL seam for hub wiring; see {@link OnAssembly}. */
+    onAssembly?: OnAssembly;
 }
 /**
  * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
@@ -133,3 +152,4 @@ export declare function createPiAgentFromDefinition(dir: string, options: Create
     agent: Agent;
     definition: LoadedDefinition;
 }>;
+export {};

package/dist/engines/pi/create.js

@@ -21,7 +21,7 @@ import { reportDefinitionWarnings } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
-import { createPiAgentFromHarness } from "./invoke.js";
+import { createPiAgentFromHarness, inProcessLease } from "./invoke.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
 // The full pi toolset is the default for fidelity: authors vibe in local pi with it, so serving with
@@ -141,20 +141,23 @@ export function assembleSystemPrompt(options) {
  */
 function buildPiAgent(opts) {
     const models = createPiModels({ providers: opts.providers, authPath: opts.authPath });
-    return createPiAgentFromHarness({
-        lease: opts.lease,
-        harnessFactory: piHarnessFactory({
-            sessions: opts.sessions ?? inMemorySessionStore(),
-            env: opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() }),
-            models,
-            model: resolveModel(models, opts.model),
-            thinkingLevel: opts.thinkingLevel,
-            systemPrompt: opts.systemPrompt,
-            tools: opts.tools,
-            skills: opts.skills,
-            live: opts.live,
-        }),
+    const env = opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() });
+    // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
+    // the SAME lease instance the agent runs under — boundary mutations must contend on it.
+    const lease = opts.lease ?? inProcessLease();
+    const harnessFactory = piHarnessFactory({
+        sessions: opts.sessions ?? inMemorySessionStore(),
+        env,
+        models,
+        model: resolveModel(models, opts.model),
+        thinkingLevel: opts.thinkingLevel,
+        systemPrompt: opts.systemPrompt,
+        tools: opts.tools,
+        skills: opts.skills,
+        live: opts.live,
     });
+    opts.onAssembly?.({ models, harnessFactory, lease });
+    return createPiAgentFromHarness({ lease, observer: opts.observer, cwd: env.cwd, harnessFactory });
 }
 /**
  * L1 system prompt: `instructions` ARE the prompt (no engine base, no wrapping); the skills listing
@@ -185,6 +188,7 @@ export function createPiAgent(options) {
         sessions: options.sessions,
         env: options.env,
         lease: options.lease,
+        observer: options.observer,
     });
 }
 /** Stable identity of a definition's non-fatal findings, for change-detection in `live` (dedup only). */
@@ -253,6 +257,8 @@ export async function createPiAgentFromDefinition(dir, options) {
         sessions: options.sessions,
         env,
         lease: options.lease,
+        observer: options.observer,
+        onAssembly: options.onAssembly,
     });
     return { agent, definition };
 }

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

@@ -60,6 +60,55 @@ export interface PiHarnessFactoryOptions {
         skills?: Skill[];
     }>;
 }
+/**
+ * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
+ * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
+ * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
+ * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
+ */
+export declare const SUMMARIZATION_RETRY_POLICY: {
+    readonly enabled: true;
+    readonly maxRetries: 3;
+    readonly baseDelayMs: 2000;
+};
+export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
+/** The shape both override consumers walk — a session entry, structurally. */
+export interface OverrideEntryLike {
+    type: string;
+    provider?: string;
+    modelId?: string;
+    thinkingLevel?: string;
+}
+/**
+ * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
+ * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
+ * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
+ * skipped over to an earlier record: the reporting surface and the execution surface must agree on
+ * which record is "the" override.
+ */
+export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    thinkingLevel?: string;
+};
+/**
+ * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
+ * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
+ * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
+ * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
+ * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
+ * back to the default with a deduped warn (fail visibly without bricking the session — the
+ * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ */
+export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel;
+}, sessionId: string): {
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel;
+};
 export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: AgentTool[], sessionId: string): string[] | undefined;
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;