@fastagent-sh/fastagent 0.15.0 → 0.16.1

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

@@ -7,9 +7,10 @@
  * 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 MountedTool } from "./tool.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 +20,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 +51,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
@@ -109,6 +122,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

@@ -18,10 +18,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);
@@ -187,7 +183,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/login.d.ts

@@ -1,6 +1,6 @@
 /**
  * `fastagent login`: authenticate a MODEL PROVIDER into the resolved auth file (project-level
- * `<dir>/.fastagent/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
+ * `<root>/.secrets/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
  * {@link fastagentCredentialStore} the runtime uses (one writer, one lock/corruption semantics).
  *
  * Flow (pi-ai's unified `ProviderAuth` API): pick a method (OAuth or API key), then a provider that

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

@@ -9,8 +9,8 @@ import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type FastagentAuthOptions } from "./auth.ts";
 import { type InteractiveLoginKind } from "./login.ts";
 export interface CreatePiModelsOptions extends FastagentAuthOptions {
-    /** Credentials file path. Defaults to the global `~/.fastagent/auth.json`; the directory opener passes
-     *  the project-level `<dir>/.fastagent/auth.json`. */
+    /** Credentials file path. Defaults to the global `~/.fastagent/.secrets/auth.json`; the directory opener passes
+     *  the project-level `<root>/.secrets/auth.json`. */
     authPath?: string;
     /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
     providers?: Provider[];
@@ -18,7 +18,7 @@ export interface CreatePiModelsOptions extends FastagentAuthOptions {
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
- * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * `~/.fastagent/.secrets/auth.json` unless the opener passes a project-level path), then ambient env vars. A
  * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
  * is upstream-owned).
  */

package/dist/engines/pi/models.js

@@ -12,7 +12,7 @@ import { interactiveLoginKind } from "./login.js";
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
- * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * `~/.fastagent/.secrets/auth.json` unless the opener passes a project-level path), then ambient env vars. A
  * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
  * is upstream-owned).
  */

package/dist/engines/pi/{workspace.d.ts → open.d.ts}

@@ -1,25 +1,25 @@
-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";
 import type { SessionObserver } from "./invoke.ts";
 import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import { type LoadedDefinition } from "./definition.ts";
+import type { LoadedDefinition } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
-export interface CreatePiAgentFromWorkspaceOptions {
+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;
     /**
-     * Session store directory. Default `<dir>/.fastagent/sessions` (gitignored machine state). `start`
+     * Session store directory. Default `<agentDir>/.state/sessions` (machine state). `start`
      * overrides it (--sessions-dir / FASTAGENT_SESSIONS_DIR / a mounted volume) so production continuity
      * survives redeploys.
      */
     sessionsDir?: string;
     /**
-     * Credentials file override. Default `<dir>/.fastagent/auth.json` (project-level, gitignored under
-     * the same `*`-ignored `.fastagent`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
-     * `~/.fastagent/auth.json` to share one credential across projects.
+     * Credentials file override. Default `<agentDir>/.secrets/auth.json` (project-level, under the
+     * `.secrets/`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
+     * the global `~/.fastagent/.secrets/auth.json` to share one credential across projects.
      */
     authPath?: string;
     /**
@@ -28,7 +28,7 @@ export interface CreatePiAgentFromWorkspaceOptions {
      * and never poll). The built-in `wake` tool mounts only when this is set AND `config.selfSchedule` is on.
      */
     serving?: boolean;
-    /** Assemble the session control plane over this workspace's session store and return it as
+    /** Assemble the session control plane over this agent's session store and return it as
      *  {@link sessionControl} — the store is created inside this opener, so the hub must be wired
      *  here too (an external `createPiSessionControl` cannot exist before the store does).
      *  Default: `config.sessionControl` AND {@link serving} — the config key means "serve the control
@@ -43,51 +43,57 @@ export interface CreatePiAgentFromWorkspaceOptions {
     observer?: SessionObserver;
 }
 /**
- * The workspace assembly FRONT HALF — everything that is independent of how pi consumes the
+ * The agent assembly FRONT HALF — everything that is independent of how pi consumes the
  * definition (transient harness for serving vs resident AgentSession for chat / session control):
- * config → model spec → agentDir → the full tool surface ({@link resolveWorkspaceTools} — the ONE
- * place it is computed) → state root → auth path. Both {@link createPiAgentFromWorkspace} and the
+ * placement resolution → config → model spec → the full tool surface ({@link resolveAgentTools} — the
+ * ONE place it is computed) → state root → auth path. Both {@link createPiAgentFromDir} and the
  * session builder (session-builder.ts) consume this, so THESE inputs cannot drift between the two
  * consumption shapes. (Definition loading and prompt assembly stay per-consumer: serving re-reads
  * them live per invoke, the session builder snapshots at startup and lets pi append skills/env.)
  */
-export interface WorkspaceAssembly {
+export interface AgentAssembly {
     config: FastagentConfig;
     configPath?: string;
     /** The resolved "provider/modelId" spec in use. */
     modelSpec: string;
-    /** Absolute agent-definition dir (config.agentDir resolved against dir; = dir when unset). */
+    /** Absolute agent dir — definition + config + machinery live here (resolvePlacement().agentDir). */
     agentDir: string;
-    /** Absolute state root (FASTAGENT_STATE_DIR > <dir>/.fastagent). */
+    /** Absolute workspace — the agent's cwd and the start of the ②-context walk: the agent dir's parent
+     *  when the agent sits inside it, the agent dir ITSELF when you point at the agent. */
+    workspace: string;
+    /** Absolute state root (FASTAGENT_STATE_DIR > <agentDir>/.state). */
     stateRoot: string;
-    /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <stateRoot>/auth.json). */
+    /** 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[];
     toolFailures: ModuleLoadFailure[];
 }
-export declare function resolveWorkspaceAssembly(dir: string, options?: {
+export declare function resolveAgentAssembly(dir: string, options?: {
     model?: string;
     authPath?: string;
-}): Promise<WorkspaceAssembly>;
+}): Promise<AgentAssembly>;
 /**
- * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
- * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
- * to report what it assembled.
+ * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or
+ * the agent dir itself), load the config, resolve model and tools, then L2. Throws a clear error when
+ * no model source is set (fail visibly at startup). Returns everything an entry point needs to report
+ * what it assembled.
  */
-export declare function createPiAgentFromWorkspace(dir: string, options?: CreatePiAgentFromWorkspaceOptions): Promise<{
+export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgentFromDirOptions): Promise<{
     agent: Agent;
     definition: LoadedDefinition;
     config: FastagentConfig;
     configPath?: string;
     /** The resolved "provider/modelId" spec actually in use. */
     modelSpec: string;
-    /** Absolute agent-definition dir in use (config.agentDir resolved against dir; = dir when unset). Channels/tools/persona come from here. */
+    /** Absolute agent dir in use — channels/tools/persona come from here. */
     agentDir: string;
-    /** Absolute state root in use (FASTAGENT_STATE_DIR > <dir>/.fastagent) — the ChannelContext's stateRoot. */
+    /** Absolute workspace in use — the agent's cwd: ALWAYS the directory that was pointed at. */
+    workspace: string;
+    /** Absolute state root in use (FASTAGENT_STATE_DIR > <agentDir>/.state) — the ChannelContext's stateRoot. */
     stateRoot: string;
     /** Absolute session store directory in use (for the startup report). */
     sessionsDir: string;
@@ -95,7 +101,7 @@ export declare function createPiAgentFromWorkspace(dir: string, options?: Create
     authPath: string;
     /** The session store in use — also a {@link PiSessionReader}. */
     sessions: PiSessionStore & PiSessionReader;
-    /** The observation plane over this workspace's sessions; present iff `options.sessionControl`. */
+    /** The observation plane over this agent's sessions; present iff `options.sessionControl`. */
     sessionControl?: SessionControl;
     /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
      *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */

package/dist/engines/pi/{workspace.js → open.js}

@@ -1,5 +1,5 @@
 /**
- * Open a definition directory into an agent — the single workspace opener BOTH `fastagent dev` and
+ * Open a definition directory into an agent — the single agent opener BOTH `fastagent dev` and
  * `fastagent start` drive.
  *
  * A thin command-posture composition over L2 `createPiAgentFromDefinition`: open the directory →
@@ -9,39 +9,35 @@
  * watch and can point sessions at a mounted volume.
  */
 import { mkdir } from "node:fs/promises";
-import { defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPath, resolveModelSpec, resolveStateRoot, } from "./config.js";
-import { createPiAgentFromDefinition, resolveWorkspaceTools } from "./create.js";
+import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, } from "./config.js";
+import { resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { createPiAgentFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
-import { ensureStateRootSelfIgnored } from "./definition.js";
 import { jsonlSessionStore } from "./sessions.js";
-export async function resolveWorkspaceAssembly(dir, options = {}) {
-    const { config, path: configPath } = await loadConfig(dir);
+export async function resolveAgentAssembly(dir, options = {}) {
+    // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
+    // its parent — the WORKSPACE — is what the agent works on: its cwd and the start of the ②-context
+    // walk (that is where it reads the project's AGENTS.md from).
+    const { agentDir, workspace } = resolvePlacement(dir);
+    const { config, path: configPath } = await loadConfig(agentDir);
     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")`);
     }
-    // The run root is `dir` (cwd — where config lives, whose AGENTS.md is ② context); the agent's own
-    // surface (persona/skills/tools/channels) lives in `agentDir` (config.agentDir, or `dir` when flat).
-    const agentDir = resolveAgentDir(dir, config);
-    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
-    // The state root: auth/sessions/channel state all derive from it, so FASTAGENT_STATE_DIR moves the
-    // whole machine-state home in one knob (a container mounts one volume); the finer overrides below
-    // still win for their specific path.
-    const stateRoot = resolveStateRoot(dir);
-    // The credentials file: project-level by default (under the state root); only resolved here, never
+    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);
+    // The credentials file: project-level by default (under `<agentDir>/.secrets`); only resolved here, never
     // created (a missing file reads as not-configured — `fastagent login` creates it).
-    const authPath = resolveAuthPath(dir, options.authPath);
-    // Self-ignore the state root iff it lands in-tree — which covers everything under it (sessions, auth,
-    // every channel's `channels/<kind>` home). HERE, not in the serving opener: every consumer of this
-    // assembly can WRITE under the state root (serving: sessions/channels; the session builder: pi's
-    // `/login` writing auth.json), so resolving a workspace's state root must make it leak-safe.
-    await ensureStateRootSelfIgnored(dir, stateRoot);
+    const authPath = resolveAuthPath(agentDir, options.authPath);
     return {
         config,
         configPath,
         modelSpec,
         agentDir,
+        workspace,
         stateRoot,
         authPath,
         tools,
@@ -52,18 +48,19 @@ export async function resolveWorkspaceAssembly(dir, options = {}) {
     };
 }
 /**
- * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
- * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
- * to report what it assembled.
+ * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or
+ * the agent dir itself), load the config, resolve model and tools, then L2. Throws a clear error when
+ * no model source is set (fail visibly at startup). Returns everything an entry point needs to report
+ * what it assembled.
  */
-export async function createPiAgentFromWorkspace(dir, options = {}) {
-    const { config, configPath, modelSpec, agentDir, stateRoot, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveWorkspaceAssembly(dir, options);
+export async function createPiAgentFromDir(dir, options = {}) {
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveAgentAssembly(dir, options);
     // Mount the built-in `wake` tool only when BOTH: this is a long-running serve (the poller honors it) AND
-    // the author opted into self-scheduling (config.selfSchedule). The workspace's own `wake` wins if defined.
+    // the author opted into self-scheduling (config.selfSchedule). The agent's own `wake` wins if defined.
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
     const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
     await mkdir(sessionsDir, { recursive: true });
-    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: dir });
+    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: workspace });
     // The hub is wired HERE because the store is created here: chicken-and-egg otherwise (the hub
     // needs the store; the agent needs the hub's observer). Boundary parts (models/factory/lease)
     // only exist after the assembly below — the hub takes them as a lazy thunk, filled by the
@@ -93,7 +90,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
         model: modelSpec,
         thinkingLevel: config.thinkingLevel,
-        cwd: dir,
+        cwd: workspace,
         tools: mountedTools,
         authPath,
         // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
@@ -115,6 +112,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
         sessions,
         sessionControl: hub?.control,
         agentDir,
+        workspace,
         config,
         configPath,
         modelSpec,

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;

package/dist/engines/pi/search-tools.js

@@ -8,7 +8,9 @@
 import { z } from "zod";
 import { log } from "../../log.js";
 import { defineTool, isDeferredTool, stripDeferredMarker } from "./tool.js";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+/** 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 function withSearchTool(tools) {
     if (!tools.some(isDeferredTool))
         return tools;

package/dist/engines/pi/session-builder.d.ts

@@ -3,7 +3,7 @@ export interface BuildSessionRuntimeOptions {
     /** Model spec override (the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;
     /** Credentials file override (the CLI --auth-path flag). Precedence: this > FASTAGENT_AUTH_PATH >
-     *  the workspace default `<stateRoot>/auth.json`. */
+     *  the agent's default `<agentDir>/.secrets/auth.json`. */
     authPath?: string;
 }
 /**
@@ -11,6 +11,6 @@ export interface BuildSessionRuntimeOptions {
  * skills, and auth resolved exactly as the serving opener does). Split from the TUI launcher so the
  * assembly — the fidelity-critical part — is inspectable and reusable without launching a TUI.
  */
-export declare function buildWorkspaceSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
+export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
 /** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
 sessionManager?: SessionManager): Promise<AgentSessionRuntime>;

package/dist/engines/pi/session-builder.js

@@ -1,5 +1,5 @@
 /**
- * The shared definition-aware session builder: open a workspace's assembled agent as a resident pi
+ * The shared definition-aware session builder: open a directory's assembled agent as a resident pi
  * `AgentSessionRuntime`. Extracted from chat.ts (session-control Phase 0) as the proof of the
  * assembly seam — independently instantiable, running the SAME agent that `dev`/`start` serve. The
  * TUI (chat.ts) is its one consumer: the session control plane (Phases 1–3) was built on the invoke
@@ -16,8 +16,8 @@
  *   - models  → a ModelRuntime with builtins only (`modelsPath: null`, no availability network), so
  *               the model surface equals serving's `createPiModels()` — pi's machine-global
  *               models.json does not leak in.
- *   - auth    → fastagent's credential store at the workspace auth path (same resolution as the
- *               serving opener: `--auth-path`/`FASTAGENT_AUTH_PATH`, else `<stateRoot>/auth.json`).
+ *   - auth    → fastagent's credential store at the AGENT's auth path (same resolution as the
+ *               serving opener: `--auth-path`/`FASTAGENT_AUTH_PATH`, else `<root>/.secrets/auth.json`).
  *               pi's TUI `/login` writes through the injected store into the SAME file, so `fastagent
  *               login` and chat share one credential lifecycle. pi's `~/.pi` auth is not consulted.
  *
@@ -38,7 +38,7 @@ import { createPiModelRuntime, probeAuthSource } from "./models.js";
 import { log } from "../../log.js";
 import { additiveActivation, turnContext } from "./tool-context.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
-import { resolveWorkspaceAssembly } from "./workspace.js";
+import { resolveAgentAssembly } from "./open.js";
 /** Adapt coding-agent's resident SessionManager to FastAgent's shared tool-runtime manager port. */
 function toolChatSessionManager(session) {
     return {
@@ -59,7 +59,7 @@ function toolChatSessionManager(session) {
  * skills, and auth resolved exactly as the serving opener does). Split from the TUI launcher so the
  * assembly — the fidelity-critical part — is inspectable and reusable without launching a TUI.
  */
-export async function buildWorkspaceSessionRuntime(dir, options = {}, 
+export async function buildAgentSessionRuntime(dir, options = {}, 
 /** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
 sessionManager) {
     /** The turn's {@link ToolActivation} over pi's AgentSession — the counterpart of invoke.ts's
@@ -91,8 +91,8 @@ sessionManager) {
         };
     }
     async function resolveAssembly(cwd) {
-        // The shared front half — the SAME config/model-spec/agentDir/tool/auth resolution the serving
-        // opener uses (workspace.ts); those inputs cannot drift between the two consumption shapes.
+        // The shared front half — the SAME placement/config/model-spec/tool/auth resolution the serving
+        // opener uses (open.ts); those inputs cannot drift between the two consumption shapes.
         // (Definition→prompt assembly is NOT shared: serving re-reads live per invoke, this runtime is a
         // startup snapshot and pi appends skills/env itself — see the header.) `tools` arrives with
         // search_tools applied; deferral is EMULATED below like serving
@@ -100,27 +100,27 @@ sessionManager) {
         // on the session in createRuntime — pi's session starts all-active), and the activation bridge
         // above rides the same turn context, so the SAME search_tools works against pi's AgentSession
         // instead of fastagent's harness.
-        const { config, modelSpec, agentDir, authPath, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveWorkspaceAssembly(cwd, options);
+        const { config, modelSpec, agentDir, authPath, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
         reportToolCollisions(toolCollisions);
         reportModuleLoadFailures(toolFailures);
         // ONE hub owns model resolution AND per-request auth — the ModelRuntime-shaped sibling of
         // serving's createPiModels; see models.ts.
         const modelRuntime = await createPiModelRuntime({ authPath });
         // MIGRATION HINT (deliberate breaking change): chat historically used pi's own `~/.pi` auth;
-        // it now reads the workspace credential file like every other command. Probe the RESOLVED
+        // it now reads the agent's credential file like every other command. Probe the RESOLVED
         // model's provider through the normal resolution path (stored credential OR env var — an
         // env-authed user is fine and must not be warned): only when that provider has no usable auth
         // AND pi's old file exists does the bare provider error get its cause named.
         if ((await probeAuthSource(modelRuntime, modelSpec)) === undefined &&
             existsSync(join(getAgentDir(), "auth.json"))) {
             log.warn(`[fastagent] no credentials for ${modelSpec} in ${authPath} — this runtime no longer reads ` +
-                `pi's ~/.pi auth; run \`fastagent login\` (or /login in the TUI) to store credentials for this workspace`);
+                `pi's ~/.pi auth; run \`fastagent login\` (or /login in the TUI) to store credentials for this agent`);
         }
         const model = resolveModel(modelRuntime, modelSpec);
         const env = new NodeExecutionEnv({ cwd });
         const definition = await loadAgentDefinition(agentDir, { cwd, env });
         reportDefinitionWarnings(definition.collisions, definition.diagnostics);
-        const defaultNames = piDefaultTools(cwd).map((t) => t.name);
+        const defaultNames = piDefaultTools().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
@@ -141,7 +141,12 @@ sessionManager) {
                 // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
                 if (!bound)
                     throw new Error("tool executed before its session was built (lifecycle invariant broken)");
-                return turnContext.run({ cwd, sessionManager: bound.sessionManager, tools: bound.activation }, () => t.execute(id, params, signal));
+                return turnContext.run({ cwd, sessionManager: bound.sessionManager, tools: bound.activation }, 
+                // pi's per-turn TOOL context (5th parameter) is read only by its default coding tools, and
+                // those are filtered out of `customTools` above; fastagent's own take theirs from
+                // `turnContext` (AsyncLocalStorage). So this env exists to satisfy the shape, and it is the
+                // chat cwd's — the same root a default tool would have got, had one reached here.
+                () => t.execute(id, params, signal, undefined, { env }));
             },
         }));
         // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
@@ -153,7 +158,7 @@ sessionManager) {
         return {
             model,
             modelRuntime,
-            // Serving honors config.thinkingLevel (workspace → L2); the resident session must too (fidelity).
+            // Serving honors config.thinkingLevel (config → L2); the resident session must too (fidelity).
             thinkingLevel: config.thinkingLevel,
             definition,
             defaultNames,