@fastagent-sh/fastagent 0.16.0 → 0.16.2

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

@@ -1,24 +1,25 @@
-import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type ExecutionEnv, type Skill, type 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 AnyModel, 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 ToolCollision, type MountedTool } 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[];
+/** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
+ *  turn as the harness tool context — hence no argument here. */
+export declare function piDefaultTools(): MountedTool[];
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export declare function resolveTools(config: FastagentConfig, cwd: string): AgentTool[];
+export declare function resolveTools(config: FastagentConfig): MountedTool[];
 /**
  * The full tool set an agent mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
  * existing win), plus the non-default tool names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
-    tools: AgentTool[];
+export declare function resolveAgentTools(config: FastagentConfig, agentDir: string): Promise<{
+    tools: MountedTool[];
     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. */
@@ -33,7 +34,7 @@ export declare function resolveAgentTools(config: FastagentConfig, agentDir: str
  * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
  */
 export declare function piBasePrompt(options?: {
-    tools?: AgentTool[];
+    tools?: MountedTool[];
     persona?: string;
 }): string;
 export interface AssembleSystemPromptOptions {
@@ -63,6 +64,11 @@ type OnAssembly = (parts: {
     models: Models;
     harnessFactory: ReturnType<typeof piHarnessFactory>;
     lease: Lease;
+    /** The resolved configured pair — what a session without overrides runs on. */
+    defaults: {
+        model: AnyModel;
+        thinkingLevel: ThinkingLevel;
+    };
 }) => void;
 /** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
 export interface CreatePiAgentOptions {
@@ -76,8 +82,10 @@ export interface CreatePiAgentOptions {
      * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
      */
     instructions?: string | (() => string);
-    /** `FastagentTool` = AgentTool plus the optional `deferred` marker (see {@link DefineToolOptions}). */
-    tools?: FastagentTool[];
+    /** The tool set to mount. `FastagentTool` (AgentTool plus the optional `deferred` marker, see
+     *  {@link DefineToolOptions}) widens into {@link MountedTool}, which additionally admits pi's default
+     *  coding tools — they read the turn's ExecutionEnv as a fifth `execute` parameter. */
+    tools?: MountedTool[];
     skills?: Skill[];
     /**
      * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint /
@@ -93,8 +101,10 @@ export interface CreatePiAgentOptions {
     authPath?: string;
     /** Session persistence. Defaults to in-memory; inject jsonlSessionStore for restart-surviving continuity. */
     sessions?: PiSessionStore;
-    /** Harness filesystem/process environment. Defaults to local NodeExecutionEnv (cwd). This is not yet
-     *  a sandbox boundary for pi's cwd-bound coding tools; a sandbox adapter must wire those tools too. */
+    /** Filesystem/process environment. Defaults to a local NodeExecutionEnv at `process.cwd()`, and its
+     *  cwd is the agent's. The default coding tools (read/bash/edit/write) take it as the turn's tool
+     *  context, so injecting a constrained one narrows where the agent reads, writes and shells. It does
+     *  NOT constrain author-written `tools/`, which are code and can import anything. */
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
@@ -116,9 +126,9 @@ export interface CreatePiAgentFromDefinitionOptions {
     /** 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). `FastagentTool` =
-     *  AgentTool plus the optional `deferred` marker. */
-    tools?: FastagentTool[];
+    /** Override tools. Defaults to {@link piDefaultTools} (lock down with a custom list). An authored
+     *  `FastagentTool[]` (AgentTool plus the optional `deferred` marker) widens into {@link MountedTool}. */
+    tools?: MountedTool[];
     /**
      * The agent's working directory: where the default tools operate AND whose ancestors are walked for
      * ② project context (AGENTS.md). Defaults to `dir`. Set it to the enclosing repo so a coding agent
@@ -135,8 +145,11 @@ export interface CreatePiAgentFromDefinitionOptions {
      */
     authPath?: string;
     sessions?: PiSessionStore;
-    /** Harness environment; see {@link CreatePiAgentOptions.env}. The default coding tools and project-
-     *  context loader remain local today, so injecting this alone does not sandbox a directory agent. */
+    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. At THIS rung it does more
+     *  than root the default tools: persona.md and skills/ are read through it too. Two surfaces stay
+     *  OUTSIDE it — ② project context (pi's loadProjectContextFiles uses node fs directly; see
+     *  definition.ts) and author-written `tools/`, which are code and can import anything. Injecting an
+     *  env narrows the blast radius rather than closing it. */
     env?: ExecutionEnv;
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */

package/dist/engines/pi/create.js

@@ -11,12 +11,13 @@
  * they come from the definition; the openers own model/tools — from config resolution).
  */
 import { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
+import { createBashTool, createEditTool, createReadTool, createWriteTool, } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { createCodingTools } from "@earendil-works/pi-coding-agent";
+import { readImageProcessor } from "./read-image.js";
 import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
-import { piHarnessFactory } from "./harness.js";
+import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
 import { reportDefinitionWarnings } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
@@ -26,15 +27,36 @@ 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
-// fewer tools is behavior drift. Isolation is the K-side ExecutionEnv/sandbox's job, not the tool
-// layer's; locking down for public exposure = passing a restricted `tools` list (a deployment posture).
-/** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
-export function piDefaultTools(cwd) {
-    return createCodingTools(cwd);
+// fewer tools is behavior drift. Locking down for public exposure = passing a restricted `tools` list
+// (a deployment posture).
+//
+// These are pi-agent-core's tools, which reach the filesystem and the shell through the
+// {@link ExecutionEnv} the harness hands them per turn — NOT pi-coding-agent's, which are the same four
+// tools wired to `node:fs` directly. Going through the env is the point, and the whole of it: it makes
+// {@link CreatePiAgentOptions.env} the one seam a sandbox adapter has to implement, instead of a knob
+// that governed everything except the tools that actually touch the machine. (It buys no decoupling
+// from pi-coding-agent — definition.ts, models.ts and read-image.ts all import it regardless.)
+//
+// The swap holds only while the two behave alike, which they do NOT for free: core's `read` does
+// nothing with images unless a processor is injected (read-image.ts), and both families are compared
+// on every path in test/tools-parity.test.ts.
+//
+// `chat` is unaffected: it takes these NAMES only and lets pi's own runtime rebuild the tools it
+// renders (see session-builder.ts).
+/** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
+ *  turn as the harness tool context — hence no argument here. */
+export function piDefaultTools() {
+    // `read` needs its image pipeline INJECTED (core ships none); see read-image.ts for what is at stake.
+    return [
+        createReadTool({ imageProcessor: readImageProcessor }),
+        createBashTool(),
+        createEditTool(),
+        createWriteTool(),
+    ];
 }
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export function resolveTools(config, cwd) {
-    const defaults = piDefaultTools(cwd);
+export function resolveTools(config) {
+    const defaults = piDefaultTools();
     return config.tools ? [...defaults, ...config.tools] : defaults;
 }
 /**
@@ -42,11 +64,12 @@ export function resolveTools(config, cwd) {
  * existing win), plus the non-default tool names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export async function resolveAgentTools(config, agentDir, cwd = agentDir) {
-    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the workspace the agent operates
-    // on); discovered `tools/` come from `agentDir` (the agent's own surface).
+export async function resolveAgentTools(config, agentDir) {
+    // Discovered `tools/` come from `agentDir` (the agent's own surface); the default coding tools carry
+    // no root of their own — they operate through the ExecutionEnv handed to them per turn, whose cwd is
+    // the workspace.
     const discovered = await loadTools(agentDir);
-    const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+    const merged = mergeDiscoveredTools(resolveTools(config), discovered.tools);
     // The built-in `search_tools` loader mounts here — the one place the agent's full tool set is
     // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; an
     // agent-defined search_tools wins).
@@ -59,7 +82,7 @@ export async function resolveAgentTools(config, agentDir, cwd = agentDir) {
     // 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 defaultNames = new Set(piDefaultTools().map((t) => t.name));
     const toolNames = tools
         .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
         .map((t) => t.name);
@@ -146,18 +169,24 @@ function buildPiAgent(opts) {
     // 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();
+    // The assembly's configured PAIR — handed to the factory and to the control plane as ONE value, so
+    // there is no wiring in which they could disagree (which levels exist depends on the model).
+    const defaults = {
+        model: resolveModel(models, opts.model),
+        thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+    };
     const harnessFactory = piHarnessFactory({
         sessions: opts.sessions ?? inMemorySessionStore(),
         env,
         models,
-        model: resolveModel(models, opts.model),
+        model: defaults.model,
         thinkingLevel: opts.thinkingLevel,
         systemPrompt: opts.systemPrompt,
         tools: opts.tools,
         skills: opts.skills,
         live: opts.live,
     });
-    opts.onAssembly?.({ models, harnessFactory, lease });
+    opts.onAssembly?.({ models, harnessFactory, lease, defaults });
     return createPiAgentFromHarness({ lease, observer: opts.observer, cwd: env.cwd, harnessFactory });
 }
 /**
@@ -216,7 +245,7 @@ export async function createPiAgentFromDefinition(dir, options) {
     let reportedFindings = findingsSignature(definition);
     // 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 tools = withSearchTool(options.tools ?? piDefaultTools());
     const agent = buildPiAgent({
         model: options.model,
         thinkingLevel: options.thinkingLevel,

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

@@ -7,9 +7,11 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
-import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
-import type { PiSessionStore } from "./sessions.ts";
+import { type PiSessionStore } from "./sessions.ts";
+import { type MountedTool } from "./tool.ts";
+import { type OverrideEntryLike } from "./session-settings.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
@@ -19,18 +21,30 @@ import type { PiSessionStore } from "./sessions.ts";
  * carry only what was actually discovered.
  */
 export declare 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. */
+type AnyHarness = AgentHarness<any>;
 export type PiSession = Awaited<ReturnType<PiSessionStore["openOrCreate"]>>;
-export declare function harnessSession(harness: AgentHarness): PiSession | undefined;
+export declare function harnessSession(harness: AnyHarness): 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.
  */
 export type AnyModel = Model<any>;
 /** Builds a pi harness bound to the given session — called once per invoke. */
-export type PiHarnessFactory = (session: string) => AgentHarness | Promise<AgentHarness>;
+/** The harness fastagent builds: context-typed on {@link ExecutionToolContext}, because that is what
+ *  pi's env-backed default tools read (pi 0.83). Custom tools are context-FREE and stay assignable — a
+ *  four-parameter `execute` satisfies the five-parameter one, so `defineTool` is untouched by this. */
+type PiHarness = AgentHarness<ExecutionToolContext>;
+export type PiHarnessFactory = (session: string) => PiHarness | Promise<PiHarness>;
 export interface PiHarnessFactoryOptions {
     /** Session persistence. Continuity = same backing store + same session id. */
     sessions: PiSessionStore;
+    /** Filesystem/process environment for the default coding tools. Handed to the harness as the TURN's
+     *  tool context (pi 0.83), which is how read/bash/edit/write reach the machine at all — so this is the
+     *  ONE seam a sandbox adapter implements, not a knob beside the tools that ignore it. */
     env: ExecutionEnv;
     /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
     models: Models;
@@ -38,7 +52,7 @@ export interface PiHarnessFactoryOptions {
     /** 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[];
+    tools?: MountedTool[];
     /**
      * Final assembled prompt, or a SYNC factory re-evaluated per invoke (how L1 serves dynamic
      * `instructions` + the skills listing). Distinct from {@link live}, which is the directory rung's
@@ -71,36 +85,19 @@ export declare const SUMMARIZATION_RETRY_POLICY: {
     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.
+ * 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.
  */
-export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
-    model?: {
-        provider: string;
-        modelId: string;
-    };
-    thinkingLevel?: string;
-};
+export declare const DEFAULT_THINKING_LEVEL: 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.
+ * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
+ * being executable with no control-plane command involved (pi appends these entries itself; a
+ * deployment's configured model can change between restarts). Deduped per session+cause — it would
+ * otherwise repeat every turn.
  */
 export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
     model: AnyModel;
@@ -109,6 +106,7 @@ export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], mo
     model: AnyModel;
     thinkingLevel: ThinkingLevel;
 };
-export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: AgentTool[], sessionId: string): string[] | undefined;
+export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: MountedTool[], 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;
+export {};

package/dist/engines/pi/harness.js

@@ -8,7 +8,9 @@
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import { log } from "../../log.js";
+import { activePathEntries } from "./sessions.js";
 import { isDeferredTool } from "./tool.js";
+import { resolveSessionSettings } from "./session-settings.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
@@ -18,10 +20,6 @@ import { isDeferredTool } from "./tool.js";
  * 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);
@@ -52,7 +50,7 @@ export const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDe
  * 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";
+export 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
@@ -76,83 +74,30 @@ const DEFAULT_THINKING_LEVEL = "medium";
  * (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.
+ * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
+ * being executable with no control-plane command involved (pi appends these entries itself; a
+ * deployment's configured model can change between restarts). Deduped per session+cause — it would
+ * otherwise repeat every turn.
  */
 export function resolveHarnessOverrides(entries, models, defaults, sessionId) {
-    let model = defaults.model;
-    let thinkingLevel = defaults.thinkingLevel;
+    const settings = resolveSessionSettings(entries, models, defaults);
     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`);
-        }
+    const dropped = settings.dropped;
+    if (dropped?.model) {
+        warnOnce(`${sessionId}\u0000model\u0000${dropped.model}`, `[fastagent] session ${sessionId}: recorded model override ${dropped.model} 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`);
-        }
+    if (dropped?.thinkingLevel) {
+        const { recorded, running, known } = dropped.thinkingLevel;
+        warnOnce(`${sessionId}\u0000thinking\u0000${settings.model.provider}/${settings.model.id}\u0000${recorded}`, known
+            ? `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is not supported by ${settings.model.provider}/${settings.model.id} — running at "${running}"`
+            : `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is unknown — using the configured default`);
     }
-    return { model, thinkingLevel };
+    return { model: settings.model, thinkingLevel: settings.thinkingLevel };
 }
 export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     const anyDeferred = tools.some(isDeferredTool);
@@ -174,9 +119,10 @@ 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();
+        // call, same trade as L2's per-invoke definition re-read. The walk is over the ACTIVE PATH, not
+        // the flat journal: `navigate` moves the leaf, so the tree can hold an abandoned branch whose
+        // activations and overrides this session has left behind.
+        const entries = await activePathEntries(session);
         const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
             ? (e.data?.names ?? [])
             : []);
@@ -187,7 +133,9 @@ export function piHarnessFactory(options) {
         // 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,
+            // Static, not a per-turn provider: the env is fixed for the agent's lifetime, and resolving a
+            // constant per turn would only add a promise to the turn's critical path.
+            toolContext: { env: options.env },
             session,
             models: options.models,
             model: overrides.model,

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

@@ -1,4 +1,3 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import type { SessionControl } from "../../session.ts";
@@ -7,6 +6,7 @@ import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import type { LoadedDefinition } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
+import type { MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {
     /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;
@@ -66,7 +66,7 @@ export interface AgentAssembly {
     /** 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). */
-    tools: AgentTool[];
+    tools: MountedTool[];
     toolNames: string[];
     deferredToolNames: string[];
     toolCollisions: ToolCollision[];

package/dist/engines/pi/open.js

@@ -25,7 +25,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, workspace);
+    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir);
     // 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);
@@ -102,6 +102,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
                     lease: parts.lease,
                     models: parts.models,
                     harnessFactory: parts.harnessFactory,
+                    defaults: parts.defaults,
                 };
             }
             : undefined,

package/dist/engines/pi/read-image.d.ts

@@ -0,0 +1,4 @@
+import type { ReadImageProcessor } from "@earendil-works/pi-agent-core";
+/** The `read` tool's image processor. Matches pi-coding-agent's messages verbatim: they reach the model
+ *  as tool output, so a reworded one is a different prompt, not a different implementation detail. */
+export declare const readImageProcessor: ReadImageProcessor;

package/dist/engines/pi/read-image.js

@@ -0,0 +1,62 @@
+/**
+ * The image pipeline pi's `read` tool needs: normalize an unsupported format to PNG, resize below the
+ * inline limit, and hand back the hints that tell the model what it is looking at.
+ *
+ * pi-agent-core's `createReadTool` takes this as an INJECTED processor and does nothing without one —
+ * unlike pi-coding-agent's, which wires its private `processImage` internally. That function is not
+ * exported (nor reachable: the package's `exports` map has no deep paths), so this rebuilds it from the
+ * two halves that ARE public, `convertToPng` and `resizeImage`/`formatDimensionNote`.
+ *
+ * It is upstream logic restated, which is a real cost — without it `read` on a screenshot sends the raw
+ * bytes (measured: 7.48 MB of base64 where pi-coding-agent sends 3.48 MB, and no dimension note for the
+ * model's coordinate math), and a bmp is dropped entirely while the tool's own description still
+ * advertises it. test/tools-parity.test.ts compares this against pi-coding-agent's real `read` on both
+ * paths, so upstream changing the pipeline surfaces as a failing test rather than as drift.
+ */
+import { convertToPng, formatDimensionNote, resizeImage } from "@earendil-works/pi-coding-agent";
+/** Formats a provider takes inline as-is; everything else has to become a PNG first. */
+const INLINE_MIME = {
+    "image/png": "image/png",
+    "image/jpeg": "image/jpeg",
+    "image/jpg": "image/jpeg",
+    "image/gif": "image/gif",
+    "image/webp": "image/webp",
+};
+/** The `read` tool's image processor. Matches pi-coding-agent's messages verbatim: they reach the model
+ *  as tool output, so a reworded one is a different prompt, not a different implementation detail. */
+export const readImageProcessor = async (bytes, mimeType, options) => {
+    const base = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+    const inline = INLINE_MIME[base];
+    let normalized;
+    if (inline) {
+        normalized = { bytes, mimeType: inline };
+    }
+    else {
+        const png = await convertToPng(Buffer.from(bytes).toString("base64"), base);
+        if (!png)
+            return { ok: false, message: "[Image omitted: could not be converted to a supported inline image format.]" };
+        normalized = { bytes: Buffer.from(png.data, "base64"), mimeType: png.mimeType, convertedFrom: base };
+    }
+    const hints = [];
+    const converted = (to) => normalized.convertedFrom && normalized.convertedFrom !== to
+        ? `[Image converted from ${normalized.convertedFrom} to ${to}.]`
+        : undefined;
+    if (!options.autoResizeImages) {
+        const hint = converted(normalized.mimeType);
+        if (hint)
+            hints.push(hint);
+        return { ok: true, data: Buffer.from(normalized.bytes).toString("base64"), mimeType: normalized.mimeType, hints };
+    }
+    const resized = await resizeImage(normalized.bytes, normalized.mimeType);
+    if (!resized)
+        return { ok: false, message: "[Image omitted: could not be resized below the inline image size limit.]" };
+    const hint = converted(resized.mimeType);
+    if (hint)
+        hints.push(hint);
+    // The scale factor the model needs to map coordinates back onto the original — dropping it is what
+    // makes a resized screenshot unusable for anything positional.
+    const note = formatDimensionNote(resized);
+    if (note)
+        hints.push(note);
+    return { ok: true, data: resized.data, mimeType: resized.mimeType, hints };
+};

package/dist/engines/pi/search-tools.d.ts

@@ -1,10 +1,12 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
-export declare function withSearchTool(tools: AgentTool[]): AgentTool[];
+import { type MountedTool } from "./tool.ts";
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own.
+ *  Typed on the MOUNTED tool, not the authored one: it inspects names and deferral and never executes,
+ *  so narrowing here would reject the very set it is handed (pi's defaults take the turn's context). */
+export declare function withSearchTool(tools: MountedTool[]): MountedTool[];
 /** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
  *
  * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
  * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
  * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
  * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
-export declare function makeSearchToolsTool(): AgentTool;
+export declare function makeSearchToolsTool(): MountedTool;