@4fu/arbor-agent-pi 2026.1106.0 → 2026.1107.0

package/README.md

@@ -27,9 +27,11 @@ everything that takes judgment, such as git, merges and conflicts, to the agent.
   guarantees what an agent cannot guarantee for itself - the record, isolation,
   exactly-once effects, the checks, dispatch. Everything that takes judgment,
   such as git, merges and conflicts, is the agent's.
-- **A directory per window.** Each window gets its own directory, and a
-  continuation keeps working in its predecessor's directory in place. It is not
-  bound to a repository; the agent clones and pushes what it needs.
+- **A shared workspace with per-window checkouts.** The default workspace is
+  ovnfs: one shared folder every window reads, and a window opens its own
+  copy-on-write checkout of the project it needs, works there and merges back
+  with `apply`. It falls back to a plain directory per window when ovnfs is not
+  installed. It is not a sandbox: ovnfs isolates files, not processes.
 - **A self-changing environment.** The model adds and changes skills, MCP
   servers and resident services itself; a `reload` validates the change and
   broadcasts it to every live window as a delta of names and descriptions.
@@ -54,7 +56,9 @@ npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
 ```
 
 `@4fu/arbor-plugin-http` is optional; it is the example plugin below.
-`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the lexical package, and
+`@4fu/arbor-search-zvec` an optional peer of the journal: absent either one, the
+journal searches lexically and nothing else changes.
 
 ## A minimal host
 
@@ -118,7 +122,10 @@ window gets, and how a continuation keeps working in it, are in
 | [`@4fu/arbor-journal-sqlite`](packages/journal-sqlite) | the default `Journal` and `BlobStore` on SQLite |
 | [`@4fu/arbor-notes-sqlite`](packages/notes-sqlite) | the default `NoteStore` on SQLite, beside the journal |
 | [`@4fu/arbor-segmenter-jieba`](packages/segmenter-jieba) | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
-| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-lexical`](packages/lexical) | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
+| [`@4fu/arbor-search-zvec`](packages/search-zvec) | the optional semantic channel: event text embedded and searched by meaning with zvec |
+| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the fallback `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-workspace-ovnfs`](packages/workspace-ovnfs) | the default `Workspace` when ovnfs is installed: one shared folder, per-window copy-on-write checkouts the model opens and applies back |
 | [`@4fu/arbor-environment-dir`](packages/environment-dir) | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
 | [`@4fu/arbor-supervisor-process`](packages/supervisor-process) | the default `Supervisor`: one host process per service, restart with backoff, logs |
 | [`@4fu/arbor-judge-jev`](packages/judge-jev) | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
@@ -151,7 +158,7 @@ deployment can see what it would be taking on before it adopts one.
 | [docs/coordination.md](docs/coordination.md) | the board, expectations, deliveries and broadcasts, staying current, effects |
 | [docs/environment.md](docs/environment.md) | skills, MCP servers and services: using, changing, reload, built-in skills, deltas |
 | [docs/memory.md](docs/memory.md) | notes, the active set, anchors, links |
-| [docs/workspaces.md](docs/workspaces.md) | per-window directories: isolation, continuity, what the agent does |
+| [docs/workspaces.md](docs/workspaces.md) | the shared folder and per-window checkouts: isolation, continuity, what the agent does |
 | [docs/tools.md](docs/tools.md) | direct tools and code mode modules |
 | [docs/prompting.md](docs/prompting.md) | how every model-facing text is written: layers, notes, deliveries, errors, judge questions, terms |
 | [docs/release.md](docs/release.md) | calendar versioning, the manual release steps, how a package is published |
@@ -168,6 +175,7 @@ tarball would contain ([docs/release.md](docs/release.md)).
 | `packages/errors` | the error shape every refusal uses: the rule and the next action |
 | `packages/journal-sqlite` | the default `Journal` and `BlobStore` on SQLite |
 | `packages/segmenter-jieba` | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| `packages/lexical` | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
 | `packages/notes-sqlite` | the default `NoteStore` on SQLite, beside the journal |
 | `packages/judge-jev` | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
 | `packages/workspace-dir` | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |

package/backend.d.ts

@@ -34,12 +34,25 @@ export interface PiBackendOptions {
     control?: WindowControl;
     /** The name this backend reports. */
     name?: string;
+    /**
+     * How long to wait before each retry of a transient model error. A run that
+     * fails with one pi classifies as transient is sent again, byte for byte, so
+     * the provider's cached prefix still holds
+     * (docs/windows.md#model-failures).
+     */
+    retryDelaysMs?: readonly number[];
+    /** How the backend waits between retries. Tests pass an immediate one. */
+    sleep?: (ms: number) => Promise<void>;
 }
+/** How long to wait before each retry of a transient model error. */
+export declare const DEFAULT_RETRY_DELAYS_MS: readonly number[];
 export declare class PiAgentBackend implements AgentBackend {
     readonly name: string;
     private readonly runtime;
     private readonly renderer;
     private control;
+    private readonly retryDelaysMs;
+    private readonly sleep;
     constructor(options?: PiBackendOptions);
     /**
      * Take the host's window control. A backend that runs windows in process
@@ -57,6 +70,19 @@ export declare class PiAgentBackend implements AgentBackend {
     login(request: LoginRequest): Promise<LoginResult>;
     /** Open one window and start its first turn. */
     open(request: OpenWindowRequest): Promise<WindowSession>;
+    /**
+     * The window's first turn, retried while the model service fails transiently.
+     *
+     * pi settles a failed run rather than throwing: the agent records an assistant
+     * message whose `stopReason` is `error`, and `isRetryableAssistantError` says
+     * whether that error is the transient kind. When it is, the failed message is
+     * dropped and the same request is sent again - the same bytes, in the same
+     * order, so the provider's cached prefix still holds and nothing the model
+     * already did is repeated. A run that fails any other way, or one that runs
+     * out of retries, rejects, which is how the session settles the window as
+     * failed for the host (docs/windows.md#model-failures).
+     */
+    private runWithRetry;
     /**
      * One direct tool call. The call is recorded at its event before it runs, and
      * the call itself goes through the host's tool groups - the same path a direct

package/backend.js

@@ -16,20 +16,27 @@
  */
 import { Agent } from "@earendil-works/pi-agent-core";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+import { isRetryableAssistantError } from "@earendil-works/pi-ai";
 import { arborError } from "@4fu/arbor-errors";
 import { Renderer } from "@4fu/arbor-prompt";
 import { PiWindowSession } from "./session.js";
 import { piTool } from "./tools.js";
+/** How long to wait before each retry of a transient model error. */
+export const DEFAULT_RETRY_DELAYS_MS = [2000, 8000, 30000];
 export class PiAgentBackend {
     name;
     runtime;
     renderer;
     control;
+    retryDelaysMs;
+    sleep;
     constructor(options = {}) {
         this.name = options.name ?? "pi";
         this.runtime = options.models ?? builtinModels();
         this.renderer = options.renderer ?? new Renderer();
         this.control = options.control;
+        this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     }
     /**
      * Take the host's window control. A backend that runs windows in process
@@ -89,6 +96,11 @@ export class PiAgentBackend {
             });
         }
         const results = new Map();
+        // The tools the window declares, built once here: the backend owns the call
+        // path, so it is the one that wires a spec to the host's catalog. A refresh
+        // while the window runs builds them again and replaces them on the agent's
+        // own state (docs/tools.md#external-tools-that-change).
+        const declareTools = (tools) => tools.map((tool) => piTool(tool, (args, callId) => this.callTool(request.window, tool.name, args, callId, results), this.renderer));
         const agent = new Agent({
             streamFn: (piModel, context, options) => this.runtime.streamSimple(piModel, context, options),
             getApiKey: async (provider) => {
@@ -98,7 +110,7 @@ export class PiAgentBackend {
             initialState: {
                 systemPrompt: systemPromptOf(request),
                 model,
-                tools: request.tools.map((tool) => piTool(tool, (args, callId) => this.callTool(request.window, tool.name, args, callId, results), this.renderer)),
+                tools: declareTools(request.tools),
             },
             steeringMode: "all",
             followUpMode: "all",
@@ -107,7 +119,7 @@ export class PiAgentBackend {
         const first = request.firstInput ?? "";
         const run = first === ""
             ? Promise.resolve()
-            : agent.prompt(first).then(() => undefined, () => undefined);
+            : this.runWithRetry(agent, first);
         return new PiWindowSession({
             agent,
             window: request.window,
@@ -115,8 +127,43 @@ export class PiAgentBackend {
             limits: { limit: request.limits.contextTokens, reserve: request.limits.reserveTokens },
             results,
             run,
+            refreshTools: (tools) => {
+                agent.state.tools = declareTools(tools);
+            },
         });
     }
+    /**
+     * The window's first turn, retried while the model service fails transiently.
+     *
+     * pi settles a failed run rather than throwing: the agent records an assistant
+     * message whose `stopReason` is `error`, and `isRetryableAssistantError` says
+     * whether that error is the transient kind. When it is, the failed message is
+     * dropped and the same request is sent again - the same bytes, in the same
+     * order, so the provider's cached prefix still holds and nothing the model
+     * already did is repeated. A run that fails any other way, or one that runs
+     * out of retries, rejects, which is how the session settles the window as
+     * failed for the host (docs/windows.md#model-failures).
+     */
+    async runWithRetry(agent, first) {
+        await agent.prompt(first);
+        for (let attempt = 0;; attempt += 1) {
+            const failed = failedMessageOf(agent);
+            if (failed === null)
+                return;
+            if (attempt >= this.retryDelaysMs.length || !isRetryableAssistantError(failed)) {
+                throw new Error(failed.errorMessage ?? "the model call failed");
+            }
+            const delay = this.retryDelaysMs[attempt];
+            if (delay !== undefined && delay > 0)
+                await this.sleep(delay);
+            // The failed turn is not an answer: dropping it leaves the transcript as
+            // it was, so the retry sends exactly what the first attempt sent.
+            agent.state.messages = agent.state.messages.filter((message) => message !== failed);
+            await agent.continue().catch(() => {
+                // The window was ended while the retry waited.
+            });
+        }
+    }
     /**
      * One direct tool call. The call is recorded at its event before it runs, and
      * the call itself goes through the host's tool groups - the same path a direct
@@ -164,3 +211,14 @@ function systemPromptOf(request) {
     const memory = request.prompt.memory.trim();
     return memory === "" ? request.prompt.system : `${request.prompt.system}\n\n${memory}`;
 }
+/**
+ * The assistant message a failed run left on the transcript, or null when the
+ * last message is not one. pi settles a provider failure by recording it, so
+ * this is where a run's failure is read from.
+ */
+function failedMessageOf(agent) {
+    const last = agent.state.messages.at(-1);
+    if (last === undefined || last.role !== "assistant")
+        return null;
+    return last.stopReason === "error" ? last : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4fu/arbor-agent-pi",
-  "version": "2026.1106.0",
+  "version": "2026.1107.0",
   "type": "module",
   "description": "The default AgentBackend: pi-agent-core in process, with its own system prompt and no pi type crossing the interface.",
   "exports": {
@@ -42,9 +42,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@4fu/arbor-errors": "2026.1106.0",
-    "@4fu/arbor-interfaces": "2026.1106.0",
-    "@4fu/arbor-prompt": "2026.1106.0",
+    "@4fu/arbor-errors": "2026.1107.0",
+    "@4fu/arbor-interfaces": "2026.1107.0",
+    "@4fu/arbor-prompt": "2026.1107.0",
     "@earendil-works/pi-agent-core": "1.5.0",
     "@earendil-works/pi-ai": "1.5.0"
   }

package/session.d.ts

@@ -5,9 +5,15 @@
  * boundary through pi's steering, queues follow-ups for after the run, ends the
  * run, and reads tool calls, results and usage as they happen. Nothing pi owns
  * crosses the interface.
+ *
+ * What the model is writing while it runs travels the same way: pi's
+ * `message_update` carries its own text and tool-call argument deltas, and this
+ * session reports them as the core's `StreamEvent`, so a host surface can show a
+ * window's output - above all what it is about to `send` - before the call is
+ * even complete (docs/windows.md#streaming).
  */
 import type { Agent } from "@earendil-works/pi-agent-core";
-import type { Delivery, Handoff, TokenUsage, ToolResult, WindowEndReason, WindowEvent, WindowOutcome, WindowRef, WindowSession, WindowState } from "@4fu/arbor-interfaces";
+import type { Delivery, DirectToolSpec, Handoff, TokenUsage, ToolResult, WindowEndReason, WindowEvent, WindowOutcome, WindowRef, WindowSession, WindowState } from "@4fu/arbor-interfaces";
 import type { Renderer } from "@4fu/arbor-prompt";
 export interface PiSessionOptions {
     agent: Agent;
@@ -21,6 +27,12 @@ export interface PiSessionOptions {
     results?: Map<string, ToolResult>;
     /** The first turn, already started by the backend. */
     run: Promise<void>;
+    /**
+     * Replace the tools this window declares, when the host's set changed while
+     * the window runs. The backend owns the call path, so it builds them
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refreshTools?: (tools: readonly DirectToolSpec[]) => void;
 }
 export declare class PiWindowSession implements WindowSession {
     readonly window: WindowRef;
@@ -34,10 +46,30 @@ export declare class PiWindowSession implements WindowSession {
     private paused;
     private current;
     private readonly results;
+    /**
+     * The arguments of the tool call being written, by content index. pi reports
+     * them as JSON text in pieces, and a call still being written is not valid
+     * JSON yet, so they are read with pi's own tolerant parser.
+     */
+    private readonly writing;
+    /**
+     * How this window's declared tools are replaced when the host's set changes.
+     * The backend owns the call path, so it builds them
+     * (docs/tools.md#external-tools-that-change).
+     */
+    private readonly refresh;
     constructor(options: PiSessionOptions);
     get state(): WindowState;
     steer(delivery: Delivery): Promise<void>;
     followUp(delivery: Delivery): Promise<void>;
+    /**
+     * The tools this window may call changed. pi keeps its declaration on the
+     * agent's own state, which may be replaced while the window runs, so a tool
+     * that appeared is callable from the next model request and one that was
+     * removed is not - and the window's prefix is never rebuilt for it
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refreshTools(tools: readonly DirectToolSpec[]): void;
     end(handoff?: Handoff, reason?: WindowEndReason): Promise<void>;
     pause(): Promise<void>;
     resume(): Promise<void>;
@@ -48,6 +80,15 @@ export declare class PiWindowSession implements WindowSession {
     /** Continue an idle window, so a queued delivery is picked up. */
     private continue_;
     private onAgentEvent;
+    /**
+     * One delta of what the model is writing, or nothing when this event is not
+     * one. pi's `message_update` carries the provider's own event: `text_delta`
+     * for assistant text, `toolcall_delta` for the arguments of a tool call as
+     * they are written. What stands so far is what the delta reports, so a
+     * surface that shows a window's output never reassembles the pieces itself
+     * (docs/windows.md#streaming).
+     */
+    private deltaOf;
     /**
      * The window's footprint: the last request's input, cache read and cache
      * write. A running total would resend the context on every turn and cross

package/session.js

@@ -5,7 +5,14 @@
  * boundary through pi's steering, queues follow-ups for after the run, ends the
  * run, and reads tool calls, results and usage as they happen. Nothing pi owns
  * crosses the interface.
+ *
+ * What the model is writing while it runs travels the same way: pi's
+ * `message_update` carries its own text and tool-call argument deltas, and this
+ * session reports them as the core's `StreamEvent`, so a host surface can show a
+ * window's output - above all what it is about to `send` - before the call is
+ * even complete (docs/windows.md#streaming).
  */
+import { ToolCallArgumentsStream } from "@earendil-works/pi-ai";
 import { arborError } from "@4fu/arbor-errors";
 import { renderDelivery } from "@4fu/arbor-prompt";
 /** A queue of window events the host drains as they happen. */
@@ -51,9 +58,22 @@ export class PiWindowSession {
     paused = false;
     current;
     results;
+    /**
+     * The arguments of the tool call being written, by content index. pi reports
+     * them as JSON text in pieces, and a call still being written is not valid
+     * JSON yet, so they are read with pi's own tolerant parser.
+     */
+    writing = new Map();
+    /**
+     * How this window's declared tools are replaced when the host's set changes.
+     * The backend owns the call path, so it builds them
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refresh;
     constructor(options) {
         this.window = options.window;
         this.agent = options.agent;
+        this.refresh = options.refreshTools;
         this.renderer = options.renderer;
         this.results = options.results ?? new Map();
         this.current = { used: 0, limit: options.limits.limit, reserve: options.limits.reserve };
@@ -91,6 +111,18 @@ export class PiWindowSession {
             return;
         this.enqueue(delivery, "followUp");
     }
+    /**
+     * The tools this window may call changed. pi keeps its declaration on the
+     * agent's own state, which may be replaced while the window runs, so a tool
+     * that appeared is callable from the next model request and one that was
+     * removed is not - and the window's prefix is never rebuilt for it
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refreshTools(tools) {
+        if (this.ended)
+            return;
+        this.refresh?.(tools);
+    }
     async end(handoff, reason = "model_ended") {
         if (this.ended)
             return;
@@ -131,6 +163,16 @@ export class PiWindowSession {
     }
     onAgentEvent(event) {
         switch (event.type) {
+            case "message_start":
+                // A new response numbers its content blocks from zero again.
+                this.writing.clear();
+                break;
+            case "message_update": {
+                const delta = this.deltaOf(event);
+                if (delta !== undefined)
+                    this.stream.push(delta);
+                break;
+            }
             case "tool_execution_start":
                 this.stream.push({
                     kind: "tool_call",
@@ -145,8 +187,16 @@ export class PiWindowSession {
                 });
                 break;
             case "message_end":
-                if (event.message.role === "assistant")
+                if (event.message.role === "assistant") {
                     this.trackUsage(event.message.usage);
+                    // What the model said in this turn, as one event on the window's
+                    // record: the host journals it, so `windows.show` replays it and a
+                    // continuation reads what its predecessor said. A message that only
+                    // carries tool calls says nothing and records nothing.
+                    const text = assistantText(event.message);
+                    if (text !== "")
+                        this.stream.push({ kind: "appended", event: text });
+                }
                 break;
             case "agent_end":
                 this.stream.push({ kind: "run_ended", outcome: this.outcomeOf("model_ended") });
@@ -155,6 +205,35 @@ export class PiWindowSession {
                 break;
         }
     }
+    /**
+     * One delta of what the model is writing, or nothing when this event is not
+     * one. pi's `message_update` carries the provider's own event: `text_delta`
+     * for assistant text, `toolcall_delta` for the arguments of a tool call as
+     * they are written. What stands so far is what the delta reports, so a
+     * surface that shows a window's output never reassembles the pieces itself
+     * (docs/windows.md#streaming).
+     */
+    deltaOf(event) {
+        const inner = event.assistantMessageEvent;
+        if (inner.type === "text_delta")
+            return { kind: "text_delta", delta: inner.delta };
+        // A provider reports the tool call's name and id on the chunk that opens it,
+        // which need not carry any argument text yet.
+        if (inner.type !== "toolcall_delta" || inner.delta === "")
+            return undefined;
+        const block = writingCall(event.message, inner.contentIndex);
+        if (block === undefined)
+            return undefined;
+        let arguments_ = this.writing.get(inner.contentIndex);
+        if (arguments_ === undefined) {
+            arguments_ = new ToolCallArgumentsStream();
+            this.writing.set(inner.contentIndex, arguments_);
+        }
+        return {
+            kind: "tool_call_delta",
+            call: { name: block.name, args: arguments_.append(inner.delta), callId: block.id },
+        };
+    }
     /**
      * The window's footprint: the last request's input, cache read and cache
      * write. A running total would resend the context on every turn and cross
@@ -215,3 +294,20 @@ export class PiWindowSession {
 function callOf(name, args, callId) {
     return { name, args: (args ?? {}), callId };
 }
+/** The text one assistant message carries, without its tool calls. */
+function assistantText(message) {
+    return message.content
+        .flatMap((block) => (block.type === "text" ? [block.text] : []))
+        .join("\n");
+}
+/**
+ * The tool call block at one content index of a message still being written.
+ * pi keeps the partial message's blocks in place, so the block a delta belongs
+ * to is the one at its own index; its name and id may still be filling in.
+ */
+function writingCall(message, index) {
+    if (message.role !== "assistant")
+        return undefined;
+    const block = message.content[index];
+    return block !== undefined && block.type === "toolCall" ? block : undefined;
+}

package/tools.d.ts

@@ -10,15 +10,27 @@
  * error block - the rule and the next action, one line.
  */
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { ParameterSpec, ToolResult } from "@4fu/arbor-interfaces";
+import type { JSONSchema, ParameterSpec, ToolResult } from "@4fu/arbor-interfaces";
 import type { Renderer } from "@4fu/arbor-prompt";
 /** One parameter's JSON Schema, from its `ParameterSpec`. */
 export declare function parameterSchema(parameter: ParameterSpec): Record<string, unknown>;
-/** The JSON Schema one tool declares to pi. */
-export declare function toolParameters(parameters: Record<string, ParameterSpec>): Record<string, unknown>;
 /**
- * What the model reads of one result. A refusal is rendered as the error block,
- * so the model always gets the rule and the next action, never an empty result.
+ * The JSON Schema one tool declares to pi.
+ *
+ * A tool declared from outside the core hands over the JSON Schema its own
+ * harness declared, and that is what pi sends: `enum`, `items`, `oneOf`, a
+ * nested object's own properties, all of it, because the model calls the tool
+ * with the schema it was given and a summary of it would only drop what it says
+ * (docs/tools.md#external-tools). A tool that declares none - arbor's own - is
+ * built from its `ParameterSpec`s, which is the declaration for those.
+ */
+export declare function toolParameters(parameters: Record<string, ParameterSpec>, schema?: JSONSchema): Record<string, unknown>;
+/**
+ * What the model reads of one result. A successful result is rendered as the
+ * `tool_result` block, so it is escaped and marked as data like every other
+ * block. A refusal is rendered as the error block, so the model always gets
+ * the rule and the next action, never an empty result; a failure that carries
+ * no error shape is marked as a failed result instead.
  */
 export declare function resultText(result: ToolResult, renderer: Renderer): string;
 /** The core's result as pi's. */
@@ -28,4 +40,5 @@ export declare function piTool(spec: {
     name: string;
     description: string;
     parameters: Record<string, ParameterSpec>;
+    schema?: JSONSchema;
 }, call: (args: Record<string, unknown>, callId: string) => Promise<ToolResult>, renderer: Renderer): AgentTool<Record<string, unknown>>;

package/tools.js

@@ -9,7 +9,7 @@
  * core's own `ToolResult`, and a refusal reaches the model as the renderer's
  * error block - the rule and the next action, one line.
  */
-import { errorBlock } from "@4fu/arbor-prompt";
+import { errorBlock, toolResultBlock } from "@4fu/arbor-prompt";
 /** One parameter's JSON Schema, from its `ParameterSpec`. */
 export function parameterSchema(parameter) {
     const schema = {
@@ -44,8 +44,19 @@ function jsonType(type) {
             return "string";
     }
 }
-/** The JSON Schema one tool declares to pi. */
-export function toolParameters(parameters) {
+/**
+ * The JSON Schema one tool declares to pi.
+ *
+ * A tool declared from outside the core hands over the JSON Schema its own
+ * harness declared, and that is what pi sends: `enum`, `items`, `oneOf`, a
+ * nested object's own properties, all of it, because the model calls the tool
+ * with the schema it was given and a summary of it would only drop what it says
+ * (docs/tools.md#external-tools). A tool that declares none - arbor's own - is
+ * built from its `ParameterSpec`s, which is the declaration for those.
+ */
+export function toolParameters(parameters, schema) {
+    if (schema !== undefined)
+        return schema;
     const properties = {};
     const required = [];
     for (const [name, parameter] of Object.entries(parameters)) {
@@ -56,23 +67,28 @@ export function toolParameters(parameters) {
     return { type: "object", properties, ...(required.length === 0 ? {} : { required }) };
 }
 /**
- * What the model reads of one result. A refusal is rendered as the error block,
- * so the model always gets the rule and the next action, never an empty result.
+ * What the model reads of one result. A successful result is rendered as the
+ * `tool_result` block, so it is escaped and marked as data like every other
+ * block. A refusal is rendered as the error block, so the model always gets
+ * the rule and the next action, never an empty result; a failure that carries
+ * no error shape is marked as a failed result instead.
  */
 export function resultText(result, renderer) {
-    if (result.ok)
-        return result.content;
-    const error = result.error;
-    if (error === undefined)
-        return result.content;
+    const name = result.tool ?? result.callId;
+    const error = result.ok ? undefined : result.error;
+    if (error !== undefined) {
+        return renderer.render([
+            errorBlock({
+                tool: name,
+                rule: error.rule,
+                message: error.message,
+                ...(error.nextAction === undefined ? {} : { nextAction: error.nextAction }),
+                ...(error.refs === undefined ? {} : { refs: error.refs }),
+            }),
+        ]);
+    }
     return renderer.render([
-        errorBlock({
-            tool: result.callId,
-            rule: error.rule,
-            message: error.message,
-            ...(error.nextAction === undefined ? {} : { nextAction: error.nextAction }),
-            ...(error.refs === undefined ? {} : { refs: error.refs }),
-        }),
+        toolResultBlock({ callId: result.callId, name }, result.content, result.ok ? "ok" : "failed"),
     ]);
 }
 /** The core's result as pi's. */
@@ -89,7 +105,7 @@ export function piTool(spec, call, renderer) {
         name: spec.name,
         label: spec.name,
         description: spec.description,
-        parameters: toolParameters(spec.parameters),
+        parameters: toolParameters(spec.parameters, spec.schema),
         execute: async (callId, params) => {
             const result = await call((params ?? {}), callId);
             return toolResultOf(result, renderer);