@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/engines/pi/config.js

@@ -14,10 +14,11 @@ 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";
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
@@ -56,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)}`);
@@ -70,17 +78,25 @@ export async function loadConfig(dir) {
     // (`modle:`) must not silently degrade to zero-config.
     for (const key of Object.keys(c)) {
         if (key !== "model" &&
+            key !== "thinkingLevel" &&
             key !== "agentDir" &&
             key !== "tools" &&
             key !== "http" &&
             key !== "deploy" &&
-            key !== "selfSchedule") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, 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.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)`);
     }
@@ -174,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("/");
@@ -212,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. */
@@ -253,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 } from "@earendil-works/pi-agent-core";
-import type { Provider } from "@earendil-works/pi-ai";
+import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+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 ToolCollision } from "./tool.ts";
-import { type Lease } from "./invoke.ts";
+import { type FastagentTool, type ToolCollision } from "./tool.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. */
@@ -19,6 +20,9 @@ export declare function resolveTools(config: FastagentConfig, cwd: string): Agen
 export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
     tools: AgentTool[];
     toolNames: string[];
+    /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
+     *  via the built-in `search_tools` loader. Surfaced so the operator can see deferral took effect. */
+    deferredToolNames: string[];
     toolCollisions: ToolCollision[];
     toolFailures: ModuleLoadFailure[];
 }>;
@@ -49,17 +53,31 @@ 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}. */
     model: string;
+    /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
+    thinkingLevel?: ThinkingLevel;
     /**
      * The system prompt itself — verbatim, no engine base and no wrapping (unlike the directory path,
      * which assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string
      * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
      */
     instructions?: string | (() => string);
-    tools?: AgentTool[];
+    /** `FastagentTool` = AgentTool plus the optional `deferred` marker (see {@link DefineToolOptions}). */
+    tools?: FastagentTool[];
     skills?: Skill[];
     /**
      * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint /
@@ -80,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;
@@ -90,11 +111,14 @@ export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
 export interface CreatePiAgentFromDefinitionOptions {
     /** Model spec "provider/modelId", resolved against {@link models}. */
     model: string;
+    /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
+    thinkingLevel?: ThinkingLevel;
     /** Override the engine base prompt (segment ①). Defaults to piBasePrompt({ tools, persona }) using the
      *  live-read persona.md; pass base to fully opt out of persona.md. */
     base?: string;
-    /** Override tools. Defaults to piDefaultTools (lock down with a custom list). */
-    tools?: AgentTool[];
+    /** Override tools. Defaults to piDefaultTools (lock down with a custom list). `FastagentTool` =
+     *  AgentTool plus the optional `deferred` marker. */
+    tools?: FastagentTool[];
     /**
      * The agent's working directory: where the default tools operate AND whose ancestors are walked for
      * ② project context (AGENTS.md). Defaults to `dir` (flat: the definition dir is also the run root).
@@ -115,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
@@ -124,3 +152,4 @@ export declare function createPiAgentFromDefinition(dir: string, options: Create
     agent: Agent;
     definition: LoadedDefinition;
 }>;
+export {};

package/dist/engines/pi/create.js

@@ -19,8 +19,9 @@ import { piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
 import { reportDefinitionWarnings } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
-import { loadTools, mergeDiscoveredTools } from "./tool.js";
-import { createPiAgentFromHarness } from "./invoke.js";
+import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
+import { withSearchTool } from "./search-tools.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
@@ -44,11 +45,30 @@ export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
     // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the run root the agent operates on);
     // discovered `tools/` come from `agentDir` (the agent's own surface). They coincide in the flat case.
     const discovered = await loadTools(agentDir);
-    const { tools, collisions } = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-    const toolCollisions = [...discovered.collisions, ...collisions];
+    const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+    // The built-in `search_tools` loader mounts here — the one place the workspace's full tool set is
+    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; a
+    // workspace-defined search_tools wins).
+    const tools = withSearchTool(merged.tools);
+    // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire
+    // on the deferred-authored-loader case, where withSearchTool returns a new array without adding one).
+    const builtinLoaderMounted = !merged.tools.some((t) => t.name === "search_tools") && tools.some((t) => t.name === "search_tools");
+    const toolCollisions = [...discovered.collisions, ...merged.collisions];
+    // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/): exclude pi
+    // defaults, the builtin loader (like wake, a builtin gets its own report line, not an anonymous
+    // slot in the author's list — an author-DEFINED search_tools still shows), and deferred tools —
+    // each name lives in exactly ONE report slot, and deferred names live in `deferredToolNames`.
     const defaultNames = new Set(piDefaultTools(cwd).map((t) => t.name));
-    const toolNames = tools.map((t) => t.name).filter((n) => !defaultNames.has(n));
-    return { tools, toolNames, toolCollisions, toolFailures: discovered.failures };
+    const toolNames = tools
+        .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
+        .map((t) => t.name);
+    return {
+        tools,
+        toolNames,
+        deferredToolNames: tools.filter(isDeferredTool).map((t) => t.name),
+        toolCollisions,
+        toolFailures: discovered.failures,
+    };
 }
 // ── §2 prompt: four-segment systemPrompt assembly ───────────────────────────
 //
@@ -69,16 +89,25 @@ export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
  * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
  */
 export function piBasePrompt(options = {}) {
-    const tools = options.tools ?? [];
+    const mounted = options.tools ?? [];
+    // Deferred tools stay OUT of the list: their schemas are not in the request until activated, so
+    // naming them here would invite calls to tools that don't exist yet; discovery is search_tools' job
+    // (which IS listed — it's active). Computed from the static mounted set, so the prompt — the cached
+    // context prefix — does not change when a tool is activated mid-session.
+    const tools = mounted.filter((t) => !isDeferredTool(t));
+    const deferredCount = mounted.length - tools.length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
     // (the standalone×code-repo cell's persona; core.md §11), keeping the tools list + guidelines below.
     const identity = options.persona?.trim() ||
         "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
+    const deferredNote = deferredCount > 0
+        ? `\n\n${deferredCount} additional tool(s) are registered but inactive — use search_tools to discover and activate them before concluding a capability is missing.`
+        : "";
     return `${identity}
 
 Available tools:
-${toolsList}
+${toolsList}${deferredNote}
 
 In addition to the tools above, you may have access to other custom tools depending on the project.
 
@@ -112,19 +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),
-            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
@@ -145,14 +178,17 @@ function instructionsPrompt(instructions, skills) {
 export function createPiAgent(options) {
     return buildPiAgent({
         model: options.model,
+        thinkingLevel: options.thinkingLevel,
         providers: options.providers,
         authPath: options.authPath,
         systemPrompt: instructionsPrompt(options.instructions, options.skills),
-        tools: options.tools,
+        // Deferred tools need their loader on every rung (idempotent; the caller's own search_tools wins).
+        tools: options.tools ? withSearchTool(options.tools) : options.tools,
         skills: options.skills,
         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). */
@@ -177,9 +213,12 @@ export async function createPiAgentFromDefinition(dir, options) {
     // runtime-written bad skill surfaces the moment it appears, while a static finding does not spam
     // every turn's log. A log-dedup memo, not session state (stateless invoke holds).
     let reportedFindings = findingsSignature(definition);
-    const tools = options.tools ?? piDefaultTools(env.cwd);
+    // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
+    // it; a caller's own search_tools wins).
+    const tools = withSearchTool(options.tools ?? piDefaultTools(env.cwd));
     const agent = buildPiAgent({
         model: options.model,
+        thinkingLevel: options.thinkingLevel,
         providers: options.providers,
         // Dir-aware default: the same state-root-derived file the opener uses for this dir (the opener
         // passes an explicit authPath, so this only affects direct L2 callers).
@@ -218,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

@@ -7,9 +7,20 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
-import type { AgentTool, ExecutionEnv, Skill } from "@earendil-works/pi-agent-core";
+import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
 import type { PiSessionStore } from "./sessions.ts";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
+ * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
+ * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
+ * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
+ * carry only what was actually discovered.
+ */
+export declare const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+export type PiSession = Awaited<ReturnType<PiSessionStore["openOrCreate"]>>;
+export declare function harnessSession(harness: AgentHarness): PiSession | undefined;
 /**
  * pi's Model with the API-shape generic erased — fastagent only passes models through to the
  * harness, so the generic carries no information. One alias keeps the `any` auditable.
@@ -24,6 +35,9 @@ export interface PiHarnessFactoryOptions {
     /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
     models: Models;
     model: AnyModel;
+    /** Reasoning effort for the model (pi's scale). Unset = fastagent's pinned default ("medium", pi
+     *  TUI parity — see {@link DEFAULT_THINKING_LEVEL}); unsupported levels are clamped by pi per model. */
+    thinkingLevel?: ThinkingLevel;
     tools?: AgentTool[];
     /**
      * Final assembled prompt, or a SYNC factory re-evaluated per invoke (how L1 serves dynamic
@@ -46,5 +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;

package/dist/engines/pi/harness.js

@@ -7,6 +7,25 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
+import { log } from "../../log.js";
+import { isDeferredTool } from "./tool.js";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
+ * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
+ * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
+ * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
+ * carry only what was actually discovered.
+ */
+export const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+/** The session a factory-built harness is bound to — the seam the activation bridge (invoke.ts) uses
+ *  to write {@link TOOL_ACTIVATION_ENTRY} deltas (pi's harness keeps its session private). Absent for
+ *  a harness built outside {@link piHarnessFactory}: activation still works in-turn there, but is not
+ *  recorded — the factory owns persistence. */
+const harnessSessions = new WeakMap();
+export function harnessSession(harness) {
+    return harnessSessions.get(harness);
+}
 /**
  * Provider request retries. The OpenAI-family / Anthropic / Azure / Codex pi-ai adapters
  * implement client-side retries (429/5xx/request-phase network failures with backoff, honoring
@@ -19,23 +38,168 @@ import { AgentHarness } from "@earendil-works/pi-agent-core";
  * so a mid-stream failure surfaces as a `failed` event.
  */
 const PROVIDER_MAX_RETRIES = 2;
+/**
+ * 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 const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDelayMs: 2000 };
+/**
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own 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 don't support a level are clamped by pi per model.
+ */
+const DEFAULT_THINKING_LEVEL = "medium";
+/**
+ * Resolve the active-tool set for a fresh harness — the ONE place both fallbacks live. pi's harness
+ * WRITES active-tool changes to the session (`setActiveTools` → `active_tools_change`) but its
+ * constructor never reads them back — pi's long-lived TUI harness keeps the set in memory, while
+ * fastagent builds a FRESH harness per invoke, which would silently reset the session's active set
+ * every turn.
+ *
+ * No record (`null`) → the INITIAL set: every non-deferred tool; undefined when nothing is deferred
+ * (pi's default — all active — applies, and no session entry is ever written; tool-sets without
+ * deferral behave exactly as before deferral existed).
+ *
+ * A record is NOT replayed as a frozen snapshot — the active set is rebuilt as the UNION of the
+ * initial set and the recorded names (filtered to the mounted tools: the constructor THROWS on
+ * unknown names, so a recorded-but-removed tool would otherwise brick every future invoke of that
+ * session). On the serving path only the additive activation bridge writes records, so a record's
+ * real semantic is "which deferred tools this session activated" — layered on top of whatever the
+ * workspace mounts TODAY. A snapshot replay would silently freeze a later-added non-deferred tool
+ * out of every session the loader ever touched. Missing recorded names are logged (fail visibly) —
+ * ONCE per session+missing set: a fresh harness is built per invoke and channel sessions live for
+ * weeks, so an un-deduped warn would repeat every turn and dilute its own signal. A log-dedup memo
+ * (like L2's findings memo), not session state — the resolve stays derived from the session.
+ */
+const warnedRestores = new Set();
+/** pi's ThinkingLevel scale as a checkable set — THE single source for fastagent (session entries
+ *  store plain strings; session-control's dispatch validation and capabilities derive from this).
+ *  The `satisfies Record<ThinkingLevel, …>` anchor makes it EXHAUSTIVE against pi's union: pi
+ *  adding a level turns this into a type error instead of a silent drift where `set_thinking`
+ *  rejects a value pi supports. */
+const ALL_THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
+/**
+ * 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 function lastOverrideEntries(entries) {
+    let model;
+    let modelSeen = false;
+    let thinkingLevel;
+    let thinkingSeen = false;
+    for (let i = entries.length - 1; i >= 0 && !(modelSeen && thinkingSeen); i--) {
+        const e = entries[i];
+        if (!modelSeen && e?.type === "model_change") {
+            modelSeen = true;
+            if (e.provider !== undefined && e.modelId !== undefined)
+                model = { provider: e.provider, modelId: e.modelId };
+        }
+        if (!thinkingSeen && e?.type === "thinking_level_change") {
+            thinkingSeen = true;
+            if (e.thinkingLevel !== undefined)
+                thinkingLevel = e.thinkingLevel;
+        }
+    }
+    return { model, thinkingLevel };
+}
+/**
+ * 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 function resolveHarnessOverrides(entries, models, defaults, sessionId) {
+    let model = defaults.model;
+    let thinkingLevel = defaults.thinkingLevel;
+    const warnOnce = (key, message) => {
+        const emit = warnedRestores.has(key) ? log.debug : log.warn;
+        warnedRestores.add(key);
+        emit(message);
+    };
+    const recorded = lastOverrideEntries(entries);
+    if (recorded.model) {
+        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
+        if (found)
+            model = found;
+        else {
+            warnOnce(`${sessionId}\u0000model\u0000${recorded.model.provider}/${recorded.model.modelId}`, `[fastagent] session ${sessionId}: recorded model override ${recorded.model.provider}/${recorded.model.modelId} is not in this deployment's registry — using the configured default`);
+        }
+    }
+    if (recorded.thinkingLevel !== undefined) {
+        if (THINKING_LEVELS.has(recorded.thinkingLevel)) {
+            thinkingLevel = recorded.thinkingLevel;
+        }
+        else {
+            warnOnce(`${sessionId}\u0000thinking\u0000${recorded.thinkingLevel}`, `[fastagent] session ${sessionId}: recorded thinking level "${recorded.thinkingLevel}" is unknown — using the configured default`);
+        }
+    }
+    return { model, thinkingLevel };
+}
+export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
+    const anyDeferred = tools.some(isDeferredTool);
+    const initial = tools.filter((t) => !isDeferredTool(t)).map((t) => t.name);
+    if (recorded === null)
+        return anyDeferred ? initial : undefined;
+    const mounted = new Set(tools.map((t) => t.name));
+    const known = recorded.filter((name) => mounted.has(name));
+    const missing = recorded.filter((name) => !mounted.has(name));
+    if (missing.length > 0) {
+        const emit = warnedRestores.has(`${sessionId}\u0000${missing.join(",")}`) ? log.debug : log.warn;
+        warnedRestores.add(`${sessionId}\u0000${missing.join(",")}`);
+        emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${missing.join(", ")}`);
+    }
+    return [...new Set([...initial, ...known])];
+}
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export function piHarnessFactory(options) {
     return async (sessionId) => {
         const session = await options.sessions.openOrCreate(sessionId);
+        // One extra entry walk per invoke to collect the activation deltas — negligible against the model
+        // call, same trade as L2's per-invoke definition re-read. Serving sessions never branch, so a flat
+        // getEntries() read (no leaf-path walk) is correct.
+        const entries = await session.getEntries();
+        const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
+            ? (e.data?.names ?? [])
+            : []);
         const fresh = options.live ? await options.live() : undefined;
         const { systemPrompt } = options;
         const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
         const skills = fresh ? fresh.skills : options.skills;
-        return new AgentHarness({
+        // Session overrides (set_model / set_thinking) win over the assembly defaults — same entry walk.
+        const overrides = resolveHarnessOverrides(entries, options.models, { model: options.model, thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL }, sessionId);
+        const harness = new AgentHarness({
             env: options.env,
             session,
             models: options.models,
-            model: options.model,
+            model: overrides.model,
+            thinkingLevel: overrides.thinkingLevel,
             tools: options.tools,
+            activeToolNames: resolveHarnessActiveToolNames(activated.length > 0 ? activated : null, options.tools ?? [], sessionId),
             systemPrompt: prompt,
             resources: skills ? { skills } : undefined,
             streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
+            retry: SUMMARIZATION_RETRY_POLICY,
         });
+        harnessSessions.set(harness, session);
+        return harness;
     };
 }