@fastagent-sh/fastagent 0.16.0 → 0.16.1

package/dist/deploy/agentcore/plan.js

@@ -538,7 +538,7 @@ function template(input, translated) {
         ...envLines,
     ];
     if (needsForwarder) {
-        lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # mint the presigned URLs the container uses for its state snapshot`, `                Action: [s3:GetObject, s3:PutObject]`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}/${STATE_KEY}`, ...(input.selfSchedule
+        lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # mint the presigned URLs the container uses for its state snapshot`, `                Action: [s3:GetObject, s3:PutObject]`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}/${STATE_KEY}`, `              # Without s3:ListBucket, S3 folds "key absent" into 403 (anti-enumeration), which is`, `              # indistinguishable from a broken signature — so the container's restore contract`, `              # (agentcore-state.ts: ONLY 404 means first deploy) would dead-end every first deploy.`, `              # Scoped to the snapshot prefix: this grants "may know whether the snapshot exists",`, `              # not a listing of the whole deployment bucket.`, `              - Effect: Allow`, `                Action: s3:ListBucket`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}`, `                Condition:`, `                  StringLike: { s3:prefix: state/* }`, ...(input.selfSchedule
             ? [
                 `              - Effect: Allow # wake alarms: mirror pending wake-ups into one-shot schedules`,
                 `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule]`,

package/dist/deploy/preflight.js

@@ -12,6 +12,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
+import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
 import { inspectChannels } from "../engines/pi/channel.js";
@@ -341,6 +342,23 @@ export async function preflightDeploy(input) {
         shipsGit,
     };
     const port = config.http?.port ?? 8787;
+    // `http.host` travels in the artifact (config is what deploy ships), and any non-wildcard value that
+    // is right on a laptop is wrong in a container: the wildcard bind is what makes the published port,
+    // the health check and webhook ingress reachable at all. `--bind` is the local-only knob; config is not.
+    const configBind = classifyBind(config.http?.host);
+    if (configBind !== "wildcard") {
+        const issue = `fastagent.config.ts sets http.host: "${config.http?.host}" — it travels into the image, where ` +
+            (configBind === "loopback"
+                ? `nothing outside the container can reach the serve (published port, health check, webhooks).`
+                : `that address does not exist, so the container fails to bind at start.`) +
+            ` Drop it and use \`--bind ${config.http?.host}\` locally instead.`;
+        // Same disposition as the model-travel issue: warn when producing artifacts (the operator may be
+        // deploying somewhere that fronts the port), gate `--run` — which would otherwise ship a box that
+        // answers nothing, or crash-loops on a bind that cannot resolve inside the container.
+        if (run)
+            return { ok: false, gate: issue };
+        messages.push({ level: "warn", text: issue });
+    }
     // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
     // secrets: listed in the runbook, set from the local env under --run, gated if a value is missing.
     const extraSecrets = config.deploy?.secrets ?? [];

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

@@ -12,8 +12,11 @@ export interface FastagentConfig {
     /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
      *  plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
+    /** `host` is the bind address: unset (or `0.0.0.0`) binds all interfaces — what containers need;
+     *  `127.0.0.1` keeps the serve (including `/control/*`) off the LAN. Precedence: `--bind` > this. */
     http?: {
         port?: number;
+        host?: string;
     };
     /** Mount the built-in `wake` tool so the agent can schedule its OWN follow-up turns (self-scheduling).
      *  Off by default — self-scheduling is an autonomy capability, opt in when you want it. Only takes
@@ -24,8 +27,9 @@ export interface FastagentConfig {
      * steer/abort/compact/set_model…) for remote consumers: a Web panel, a desktop app, `fastagent
      * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
      * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
-     * binds all interfaces, so the routes are LAN-reachable with the token as the only protection —
-     * firewall the port, or wrap it for real exposure (design §14).
+     * binds all interfaces by default, so the routes are LAN-reachable with the token as the only
+     * protection — bind loopback (`--bind 127.0.0.1`; not `http.host`, which travels into a deployed
+     * image), firewall the port, or wrap it for real exposure (design §14).
      */
     sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a

package/dist/engines/pi/config.js

@@ -21,6 +21,7 @@ import { existsSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { THINKING_LEVELS } from "./harness.js";
+import { isBindAddress } from "../../bind.js";
 import { moduleLoadHint } from "../../loader.js";
 import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
@@ -116,13 +117,18 @@ export async function loadConfig(dir) {
         throw new Error(`${path}: "http" must be an object`);
     }
     for (const key of Object.keys(c.http ?? {})) {
-        if (key !== "port") {
-            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port)`);
+        if (key !== "port" && key !== "host") {
+            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port, host)`);
         }
     }
     if (c.http?.port !== undefined && (typeof c.http.port !== "number" || !isValidPort(c.http.port))) {
         throw new Error(`${path}: "http.port" must be an integer 0-65535`);
     }
+    // Validated as strictly as http.port: an unbindable string ("banana") must fail HERE, not surface
+    // later as a topology diagnostic about "the interface you bound".
+    if (c.http?.host !== undefined && (typeof c.http.host !== "string" || !isBindAddress(c.http.host))) {
+        throw new Error(`${path}: "http.host" must be an IP address or "localhost" (e.g. "127.0.0.1", "0.0.0.0")`);
+    }
     if (c.deploy !== undefined && (typeof c.deploy !== "object" || c.deploy === null)) {
         throw new Error(`${path}: "deploy" must be an object`);
     }

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

@@ -1,4 +1,4 @@
-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";
@@ -6,19 +6,20 @@ import { type LoadedDefinition } from "./definition.ts";
 import { piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import { type FastagentTool, type ToolCollision } from "./tool.ts";
+import { type 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 {
@@ -76,8 +77,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 +96,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 +121,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 +140,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,8 +11,9 @@
  * 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";
@@ -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);
@@ -216,7 +239,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,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/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);

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.js

@@ -120,7 +120,7 @@ sessionManager) {
         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

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

@@ -1,4 +1,4 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { AgentHarnessTool, ExecutionToolContext, AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
 import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
@@ -34,6 +34,14 @@ export interface DefineToolOptions<I extends z.ZodType> {
     executionMode?: "sequential" | "parallel";
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
+/**
+ * A tool as MOUNTED: what the harness actually runs. Wider than the authored {@link AgentTool} on
+ * purpose — pi's default coding tools read the turn's tool context (its ExecutionEnv) as a fifth
+ * `execute` parameter, while fastagent's own tools take four and are assignable to it unchanged.
+ * Naming the wider type is what lets `defineTool` stay context-free for authors while both families
+ * live in one array; every helper that only inspects or reorders tools is typed on THIS.
+ */
+export type MountedTool = AgentHarnessTool<ExecutionToolContext>;
 /** An AgentTool with fastagent's deferral marker — the type for raw tools handed to fastagent
  *  (`config.tools`, L1/L2 `tools`): plain `AgentTool` has no `deferred`, so an object literal with the
  *  marker would fail excess-property checking against upstream's type. `defineTool` produces it. */
@@ -42,10 +50,10 @@ export type FastagentTool = AgentTool & {
 };
 /** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
  *  AgentTool object — pi ignores it). */
-export declare function isDeferredTool(tool: AgentTool): boolean;
+export declare function isDeferredTool(tool: MountedTool): boolean;
 /** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
  *  could never be activated and would strand every deferred tool). */
-export declare function stripDeferredMarker(tool: AgentTool): AgentTool;
+export declare function stripDeferredMarker(tool: MountedTool): MountedTool;
 export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): FastagentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
 export interface ToolCollision {
@@ -68,7 +76,7 @@ export declare function loadTools(dir: string): Promise<{
  * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
-export declare function mergeDiscoveredTools(existing: AgentTool[], discovered: AgentTool[]): {
-    tools: AgentTool[];
+export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {
+    tools: MountedTool[];
     collisions: ToolCollision[];
 };

package/dist/engines/pi/wake-tool.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type MountedTool } from "./tool.ts";
 /**
  * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"`
  * ("30m", "2h", "1d"). Undefined for anything else, INCLUDING a bare numeric string like "120": one
@@ -12,6 +12,6 @@ export declare function parseDelayMs(input: string | number): number | undefined
  * scheduler poller honors a wake-up) and only when the workspace hasn't defined its own `wake` (that
  * wins, like any tool collision). The single place the mount decision + collision rule run.
  */
-export declare function withWakeTool(tools: AgentTool[], stateRoot: string, enabled: boolean): AgentTool[];
+export declare function withWakeTool(tools: MountedTool[], stateRoot: string, enabled: boolean): MountedTool[];
 /** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
-export declare function makeWakeTool(stateRoot: string, now?: () => Date): AgentTool;
+export declare function makeWakeTool(stateRoot: string, now?: () => Date): MountedTool;

package/dist/host/node.d.ts

@@ -48,9 +48,11 @@ export declare function router(routes: Routes): ChannelHandler;
  * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
  * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
  * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
+ * `host` is the bind address; unset means all interfaces (what containers need).
  */
 export declare function serveNode(handler: ChannelHandler, options: {
     port: number;
+    host?: string;
 }): {
     listening: Promise<number>;
     close: () => Promise<void>;

package/dist/host/node.js

@@ -35,12 +35,13 @@ export function router(routes) {
  * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
  * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
  * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
+ * `host` is the bind address; unset means all interfaces (what containers need).
  */
 export function serveNode(handler, options) {
     const server = createServer(nodeListener(async (req) => handler(req)));
     const listening = new Promise((resolve, reject) => {
         server.once("error", reject); // a bind failure surfaces here, before "listening"
-        server.listen(options.port, () => {
+        server.listen({ port: options.port, host: options.host }, () => {
             server.off("error", reject);
             resolve(server.address().port);
         });