@4fu/arbor-agent-pi 0.1.0 → 2026.1106.1

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.
@@ -118,7 +120,8 @@ 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-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 +154,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 |

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
@@ -107,7 +114,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,
@@ -117,6 +124,38 @@ export class PiAgentBackend {
             run,
         });
     }
+    /**
+     * 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 +203,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": "0.1.0",
+  "version": "2026.1106.1",
   "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": "0.1.0",
-    "@4fu/arbor-interfaces": "0.1.0",
-    "@4fu/arbor-prompt": "0.1.0",
+    "@4fu/arbor-errors": "2026.1106.1",
+    "@4fu/arbor-interfaces": "2026.1106.1",
+    "@4fu/arbor-prompt": "2026.1106.1",
     "@earendil-works/pi-agent-core": "1.5.0",
     "@earendil-works/pi-ai": "1.5.0"
   }

package/session.d.ts

@@ -5,6 +5,12 @@
  * 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";
@@ -34,6 +40,12 @@ 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;
     constructor(options: PiSessionOptions);
     get state(): WindowState;
     steer(delivery: Delivery): Promise<void>;
@@ -48,6 +60,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,6 +58,12 @@ 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();
     constructor(options) {
         this.window = options.window;
         this.agent = options.agent;
@@ -131,6 +144,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 +168,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 +186,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 +275,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

@@ -17,8 +17,11 @@ export declare function parameterSchema(parameter: ParameterSpec): Record<string
 /** 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.
+ * 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. */

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 = {
@@ -56,23 +56,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. */