@4fu/arbor-agent-pi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4fuu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# arbor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+arbor is a framework for an agent without sessions: many context windows run
+at once over one shared record, so work moves in parallel, replies come fast,
+and every window can find everything that was ever done.
+
+A deployment composes the pieces it wants and registers plugins for the domains
+it serves. The framework guarantees what an agent cannot guarantee for itself -
+the record, isolation, exactly-once effects, the checks, dispatch - and leaves
+everything that takes judgment, such as git, merges and conflicts, to the agent.
+
+## Core ideas
+
+- **No sessions to manage.** Work runs in disposable context windows. Any
+  number run at the same time; none of them owns anything, and a window that
+  ends loses nothing. The model looks up what it needs instead of carrying it.
+- **One record, shared live.** Every input, tool call, result, send and note
+  revision goes into one journal and is visible to every window as
+  soon as it is written. Records never merge and are never lost.
+- **Dispatch by a judge.** A judge (Jev by default, replaceable) decides which
+  live window takes a new input, or opens a new one. There is no router session
+  and no main line.
+- **Current without locks.** Windows run in parallel. New events on a
+  conversation a window is in are steered into it as they arrive; only a note
+  write is checked against the revision the window read.
+- **Mechanisms in the framework, policy in the agent.** The framework
+  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 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.
+- **Minimal limits.** The framework sets no policy. Permissions, privacy
+  review, budgets and approvals belong to deployments built on it, through
+  hooks.
+- **Direct tools plus code mode.** Decisions are direct tools; everything else
+  is a module called from `code_exec`. There is no CLI.
+- **Every module is replaceable.** The agent backend (pi by default), the
+  journal, notes, workspaces, the judge, channels and the rest are interfaces
+  ([docs/architecture.md](docs/architecture.md#interfaces)).
+
+## Install
+
+Node 24 or newer. Every package is published separately, so a deployment
+installs the core and the defaults it wants:
+
+```sh
+npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
+  @4fu/arbor-environment-dir @4fu/arbor-supervisor-process @4fu/arbor-agent-pi \
+  @4fu/arbor-workspace-dir
+```
+
+`@4fu/arbor-plugin-http` is optional; it is the example plugin below.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+
+## A minimal host
+
+The smallest host needs a journal and a backend. Adding the defaults and one
+plugin is what a deployment usually starts from:
+
+```js
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Arbor } from "@4fu/arbor-core";
+import { DirectoryEnvironment } from "@4fu/arbor-environment-dir";
+import { SqliteJournal } from "@4fu/arbor-journal-sqlite";
+import { SqliteNoteStore } from "@4fu/arbor-notes-sqlite";
+import { ProcessSupervisor } from "@4fu/arbor-supervisor-process";
+import { DirectoryWorkspace } from "@4fu/arbor-workspace-dir";
+import { PiAgentBackend } from "@4fu/arbor-agent-pi";
+import { HttpChannel, httpPlugin } from "@4fu/arbor-plugin-http";
+
+const root = await mkdtemp(join(tmpdir(), "arbor-"));
+
+// Every module below is a default implementation of an interface. Replace any
+// one by passing your own; the host does not change.
+const journal = new SqliteJournal({ path: join(root, "journal.sqlite") });
+const notes = new SqliteNoteStore({ path: join(root, "notes.sqlite"), journal });
+const supervisor = new ProcessSupervisor({ root: join(root, "services") });
+const environment = new DirectoryEnvironment({ root: join(root, "env"), supervisor });
+const workspace = new DirectoryWorkspace({ root: join(root, "workspaces") });
+
+// A plugin adds; it never patches the core. This one is a chat channel: a
+// webhook in, a window's sends out, and a page that drives the whole host.
+let arbor;
+const channel = new HttpChannel({ host: "127.0.0.1", port: 8787, board: () => arbor.boardLines() });
+arbor = new Arbor({
+  journal,
+  notes,
+  backend: new PiAgentBackend(),
+  workspace,
+  environment,
+  supervisor,
+  plugins: [httpPlugin({ channel })],
+});
+
+await arbor.start();
+await channel.listen();
+```
+
+`arbor.open(task)` dispatches one task, and the journal is where everything that
+happened can be read back ([docs/journal.md](docs/journal.md)). The workspace a
+window gets, and how a continuation keeps working in it, are in
+[docs/workspaces.md](docs/workspaces.md).
+
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| [`@4fu/arbor-interfaces`](packages/interfaces) | every replaceable interface, plus the core's own shapes. Types only. |
+| [`@4fu/arbor-errors`](packages/errors) | the error shape every refusal uses: the rule and the next action |
+| [`@4fu/arbor-prompt`](packages/prompt) | typed blocks, the one deterministic renderer and the replaceable text table |
+| [`@4fu/arbor-tools`](packages/tools) | the entry points: direct tools, code mode modules, the host API |
+| [`@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-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 |
+| [`@4fu/arbor-agent-pi`](packages/agent-pi) | the default `AgentBackend`: pi-agent-core in process |
+| [`@4fu/arbor-plugin-http`](packages/plugin-http) | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| [`@4fu/arbor-core`](packages/core) | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects and schedules |
+
+### Defaults are examples
+
+Every default above is a reference implementation of its interface, written to
+be read and replaced. A real deployment is expected to swap out the ones that do
+not fit: the SQLite journal and notes, the directory workspace, the process
+supervisor, the environment directory, the HTTP test plugin and the Jev judge
+are all examples of what an interface can be satisfied by, not commitments.
+What a deployment keeps is its own choice, and the interfaces are the contract
+([docs/architecture.md](docs/architecture.md#interfaces)).
+
+Each package's own documentation holds the limits of that default, so a
+deployment can see what it would be taking on before it adopts one.
+
+## Documents
+
+| Page | Contents |
+| --- | --- |
+| [docs/overview.md](docs/overview.md) | goals, concepts, principles, routes considered |
+| [docs/architecture.md](docs/architecture.md) | layers, interfaces, stack, models, plugins, hooks, data placement |
+| [docs/journal.md](docs/journal.md) | events and their order, targets, watermarks, external ids, refs, tracing, media, redaction |
+| [docs/windows.md](docs/windows.md) | window lifecycle, prompt layout, reminders, continuation |
+| [docs/dispatch.md](docs/dispatch.md) | task sources, judge decisions, insertion timing, backpressure, scheduled tasks |
+| [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/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 |
+
+## Repository layout
+
+`pnpm check` typechecks and tests every package on its TypeScript sources.
+`pnpm build` emits the `dist` publishing needs, and `pnpm pack` shows what each
+tarball would contain ([docs/release.md](docs/release.md)).
+
+| Path | Layer |
+| --- | --- |
+| `packages/interfaces` | the interfaces layer: every replaceable interface, plus the core's own shapes. Types only. |
+| `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/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 |
+| `packages/environment-dir` | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
+| `packages/supervisor-process` | the default `Supervisor`: one host process per service, restart with backoff, logs |
+| `packages/plugin-http` | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| `packages/prompt` | typed blocks, the one deterministic renderer and the replaceable text table |
+| `packages/agent-pi` | the default `AgentBackend`: pi-agent-core in process |
+| `packages/tools` | the entry points: direct tools, code mode modules, the host API |
+| `packages/core` | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects, schedules and the snapshot epochs |
+
+`mise.toml` pins the toolchain - Node and pnpm - installed under
+`~/.local/share/mise`, and `.agents/setup` prepares a machine from it. A machine
+without mise is expected to carry Node 24 or newer and pnpm 12 already.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/backend.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The default `AgentBackend`: pi-agent-core in process
+ * (docs/architecture.md#interfaces).
+ *
+ * arbor uses pi's `Agent` with its own system prompt: pi's default coding
+ * prompt, context files and skills never reach the model
+ * (docs/prompting.md#no-built-in-pi-prompt). Reminders and deliveries are
+ * user-role text inside inputs, never system messages in the middle of a
+ * window, because some providers fold those into the leading system prompt and
+ * that breaks the cached prefix.
+ *
+ * No pi type crosses the interface. The backend takes the core's
+ * `OpenWindowRequest`, hands back the core's `WindowSession`, and reports the
+ * core's models, usage and outcomes. Everything it needs from the host - the
+ * catalog, the renderer, the call path - arrives through its options.
+ */
+import type { Models } from "@earendil-works/pi-ai";
+import type { AgentBackend, LoginRequest, LoginResult, ModelInfo, OpenWindowRequest, ToolCall, ToolResult, WindowSession } from "@4fu/arbor-interfaces";
+import { Renderer } from "@4fu/arbor-prompt";
+/** What the host gives the backend about the window it is running. */
+export interface WindowControl {
+    /** Record one call at an event, before it runs. */
+    recordToolCall(window: string, call: ToolCall): Promise<string | undefined>;
+    /** Run one call through the host's tool groups, the same path a direct call takes. */
+    runToolCall(window: string, call: ToolCall, at?: string): Promise<ToolResult>;
+    /** True once the window should end after the current turn. */
+    endRequested(window: string): boolean;
+}
+export interface PiBackendOptions {
+    /** pi's model runtime. Defaults to every built-in provider. */
+    models?: Models;
+    /** The one renderer, for deliveries steered into a window. */
+    renderer?: Renderer;
+    control?: WindowControl;
+    /** The name this backend reports. */
+    name?: string;
+}
+export declare class PiAgentBackend implements AgentBackend {
+    readonly name: string;
+    private readonly runtime;
+    private readonly renderer;
+    private control;
+    constructor(options?: PiBackendOptions);
+    /**
+     * Take the host's window control. A backend that runs windows in process
+     * needs it, and the host builds it after the backend exists, so the two are
+     * joined here rather than through a constructor argument.
+     */
+    attachControl(control: WindowControl): void;
+    /** The catalog this backend can run. Only models that take images. */
+    models(): Promise<ModelInfo[]>;
+    /**
+     * Log in to a provider. A key is never passed here: the request names a
+     * secret, and the deployment hands the value to pi outside arbor
+     * (docs/environment.md#what-the-model-can-change).
+     */
+    login(request: LoginRequest): Promise<LoginResult>;
+    /** Open one window and start its first turn. */
+    open(request: OpenWindowRequest): Promise<WindowSession>;
+    /**
+     * 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
+     * call takes (docs/tools.md#rules).
+     */
+    private callTool;
+    /** The model a request names, from the catalog. */
+    private modelOf;
+    private modelsOf;
+}

package/backend.js

@@ -0,0 +1,166 @@
+/**
+ * The default `AgentBackend`: pi-agent-core in process
+ * (docs/architecture.md#interfaces).
+ *
+ * arbor uses pi's `Agent` with its own system prompt: pi's default coding
+ * prompt, context files and skills never reach the model
+ * (docs/prompting.md#no-built-in-pi-prompt). Reminders and deliveries are
+ * user-role text inside inputs, never system messages in the middle of a
+ * window, because some providers fold those into the leading system prompt and
+ * that breaks the cached prefix.
+ *
+ * No pi type crosses the interface. The backend takes the core's
+ * `OpenWindowRequest`, hands back the core's `WindowSession`, and reports the
+ * core's models, usage and outcomes. Everything it needs from the host - the
+ * catalog, the renderer, the call path - arrives through its options.
+ */
+import { Agent } from "@earendil-works/pi-agent-core";
+import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+import { arborError } from "@4fu/arbor-errors";
+import { Renderer } from "@4fu/arbor-prompt";
+import { PiWindowSession } from "./session.js";
+import { piTool } from "./tools.js";
+export class PiAgentBackend {
+    name;
+    runtime;
+    renderer;
+    control;
+    constructor(options = {}) {
+        this.name = options.name ?? "pi";
+        this.runtime = options.models ?? builtinModels();
+        this.renderer = options.renderer ?? new Renderer();
+        this.control = options.control;
+    }
+    /**
+     * Take the host's window control. A backend that runs windows in process
+     * needs it, and the host builds it after the backend exists, so the two are
+     * joined here rather than through a constructor argument.
+     */
+    attachControl(control) {
+        this.control = control;
+    }
+    /** The catalog this backend can run. Only models that take images. */
+    async models() {
+        const found = [];
+        for (const model of this.runtime.getModels()) {
+            if (!model.input.includes("image"))
+                continue;
+            found.push({ id: model.id, provider: model.provider, name: model.name, images: true });
+        }
+        return found;
+    }
+    /**
+     * Log in to a provider. A key is never passed here: the request names a
+     * secret, and the deployment hands the value to pi outside arbor
+     * (docs/environment.md#what-the-model-can-change).
+     */
+    async login(request) {
+        const provider = this.runtime.getProvider(request.provider);
+        if (provider === undefined) {
+            return {
+                provider: request.provider,
+                state: "failed",
+                models: [],
+                error: `provider ${request.provider} is not registered`,
+            };
+        }
+        const check = await this.runtime.checkAuth(request.provider);
+        if (check !== undefined) {
+            return { provider: request.provider, state: "logged-in", models: this.modelsOf(request.provider) };
+        }
+        return {
+            provider: request.provider,
+            state: "logged-out",
+            models: this.modelsOf(request.provider),
+            error: request.secret === undefined
+                ? `provider ${request.provider} has no credential; name the secret that holds its key`
+                : `provider ${request.provider} has no credential; configure the secret ${request.secret}`,
+        };
+    }
+    /** Open one window and start its first turn. */
+    async open(request) {
+        const model = this.modelOf(request.model);
+        if (model === undefined) {
+            throw arborError({
+                code: "not_found",
+                rule: "backend.model.unknown",
+                message: `backend: 模型 ${request.model} 不在目录中`,
+                nextAction: "使用 backend.models() 列出的模型 id，或在设置中把该档位映射到另一个模型。",
+            });
+        }
+        const results = new Map();
+        const agent = new Agent({
+            streamFn: (piModel, context, options) => this.runtime.streamSimple(piModel, context, options),
+            getApiKey: async (provider) => {
+                const auth = await this.runtime.getAuth(provider);
+                return auth?.auth.apiKey;
+            },
+            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)),
+            },
+            steeringMode: "all",
+            followUpMode: "all",
+            finishTurn: () => this.control?.endRequested(request.window) === true ? { action: "end" } : undefined,
+        });
+        const first = request.firstInput ?? "";
+        const run = first === ""
+            ? Promise.resolve()
+            : agent.prompt(first).then(() => undefined, () => undefined);
+        return new PiWindowSession({
+            agent,
+            window: request.window,
+            renderer: this.renderer,
+            limits: { limit: request.limits.contextTokens, reserve: request.limits.reserveTokens },
+            results,
+            run,
+        });
+    }
+    /**
+     * 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
+     * call takes (docs/tools.md#rules).
+     */
+    async callTool(window, name, args, callId, results) {
+        const call = { name, args, callId };
+        if (this.control === undefined) {
+            return {
+                callId,
+                ok: false,
+                content: "",
+                error: {
+                    rule: "backend.call_path.missing",
+                    message: `backend: 没有提供 ${name} 的调用路径`,
+                    nextAction: "在 host 中注册工具组。",
+                },
+            };
+        }
+        let at;
+        try {
+            at = await this.control.recordToolCall(window, call);
+        }
+        catch {
+            at = undefined;
+        }
+        const result = await this.control.runToolCall(window, call, at);
+        results.set(callId, result);
+        return result;
+    }
+    /** The model a request names, from the catalog. */
+    modelOf(id) {
+        const wanted = id.includes("/") ? id.slice(id.indexOf("/") + 1) : id;
+        return this.runtime.getModels().find((model) => model.id === wanted);
+    }
+    modelsOf(provider) {
+        return this.runtime
+            .getModels(provider)
+            .filter((model) => model.input.includes("image"))
+            .map((model) => ({ id: model.id, provider: model.provider, name: model.name, images: true }));
+    }
+}
+/** The frozen prefix: the system prompt, then the memory snapshot. */
+function systemPromptOf(request) {
+    const memory = request.prompt.memory.trim();
+    return memory === "" ? request.prompt.system : `${request.prompt.system}\n\n${memory}`;
+}

package/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @4fu/arbor-agent-pi - the default `AgentBackend` on pi-agent-core.
+ *
+ * pi runs every window in process, so steering, tool hooks and code mode are
+ * direct calls (docs/architecture.md#stack). Nothing pi owns crosses the
+ * interface: the backend takes the core's `OpenWindowRequest` and hands back
+ * the core's `WindowSession`.
+ */
+export { PiAgentBackend, type PiBackendOptions, type WindowControl } from "./backend.ts";
+export { PiWindowSession, type PiSessionOptions } from "./session.ts";
+export { parameterSchema, piTool, toolParameters, toolResultOf } from "./tools.ts";
+export { emptyUsage, requestTokens, tokenUsage, usageChanged } from "./usage.ts";

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * @4fu/arbor-agent-pi - the default `AgentBackend` on pi-agent-core.
+ *
+ * pi runs every window in process, so steering, tool hooks and code mode are
+ * direct calls (docs/architecture.md#stack). Nothing pi owns crosses the
+ * interface: the backend takes the core's `OpenWindowRequest` and hands back
+ * the core's `WindowSession`.
+ */
+export { PiAgentBackend } from "./backend.js";
+export { PiWindowSession } from "./session.js";
+export { parameterSchema, piTool, toolParameters, toolResultOf } from "./tools.js";
+export { emptyUsage, requestTokens, tokenUsage, usageChanged } from "./usage.js";

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@4fu/arbor-agent-pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "default": "./testing.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "backend.d.ts",
+    "backend.js",
+    "index.d.ts",
+    "index.js",
+    "session.d.ts",
+    "session.js",
+    "testing.d.ts",
+    "testing.js",
+    "tools.d.ts",
+    "tools.js",
+    "usage.d.ts",
+    "usage.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/agent-pi"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "0.1.0",
+    "@4fu/arbor-interfaces": "0.1.0",
+    "@4fu/arbor-prompt": "0.1.0",
+    "@earendil-works/pi-agent-core": "1.5.0",
+    "@earendil-works/pi-ai": "1.5.0"
+  }
+}

package/session.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One running window, owned by pi (docs/windows.md#lifecycle).
+ *
+ * The host sees only the core's shapes: it inserts deliveries at a tool-call
+ * 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.
+ */
+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 { Renderer } from "@4fu/arbor-prompt";
+export interface PiSessionOptions {
+    agent: Agent;
+    window: WindowRef;
+    renderer: Renderer;
+    limits: {
+        limit: number;
+        reserve: number;
+    };
+    /** The full results, keyed by call id, so the host reads the core's shape. */
+    results?: Map<string, ToolResult>;
+    /** The first turn, already started by the backend. */
+    run: Promise<void>;
+}
+export declare class PiWindowSession implements WindowSession {
+    readonly window: WindowRef;
+    private readonly agent;
+    private readonly renderer;
+    private readonly stream;
+    private readonly outcomePromise;
+    private resolveOutcome;
+    private unsubscribe;
+    private ended;
+    private paused;
+    private current;
+    private readonly results;
+    constructor(options: PiSessionOptions);
+    get state(): WindowState;
+    steer(delivery: Delivery): Promise<void>;
+    followUp(delivery: Delivery): Promise<void>;
+    end(handoff?: Handoff, reason?: WindowEndReason): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    usage(): TokenUsage;
+    events(): AsyncIterable<WindowEvent>;
+    outcome(): Promise<WindowOutcome>;
+    private enqueue;
+    /** Continue an idle window, so a queued delivery is picked up. */
+    private continue_;
+    private onAgentEvent;
+    /**
+     * 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
+     * the reminder tiers within a few turns.
+     */
+    private trackUsage;
+    /** The core's result, kept by the backend when the call was made. */
+    private resultOf;
+    /** The outcome as it stands, for a run that ended. */
+    private outcomeOf;
+    private settle;
+}

package/session.js

@@ -0,0 +1,217 @@
+/**
+ * One running window, owned by pi (docs/windows.md#lifecycle).
+ *
+ * The host sees only the core's shapes: it inserts deliveries at a tool-call
+ * 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.
+ */
+import { arborError } from "@4fu/arbor-errors";
+import { renderDelivery } from "@4fu/arbor-prompt";
+/** A queue of window events the host drains as they happen. */
+class EventQueue {
+    pending = [];
+    waiting = [];
+    closed = false;
+    push(event) {
+        this.pending.push(event);
+        this.flush();
+    }
+    close() {
+        this.closed = true;
+        this.flush();
+    }
+    async *drain() {
+        for (;;) {
+            const next = this.pending.shift();
+            if (next !== undefined) {
+                yield next;
+                continue;
+            }
+            if (this.closed)
+                return;
+            await new Promise((resolve) => this.waiting.push(resolve));
+        }
+    }
+    flush() {
+        while (this.waiting.length > 0 && (this.pending.length > 0 || this.closed)) {
+            this.waiting.shift()?.();
+        }
+    }
+}
+export class PiWindowSession {
+    window;
+    agent;
+    renderer;
+    stream = new EventQueue();
+    outcomePromise;
+    resolveOutcome = () => { };
+    unsubscribe;
+    ended = false;
+    paused = false;
+    current;
+    results;
+    constructor(options) {
+        this.window = options.window;
+        this.agent = options.agent;
+        this.renderer = options.renderer;
+        this.results = options.results ?? new Map();
+        this.current = { used: 0, limit: options.limits.limit, reserve: options.limits.reserve };
+        this.outcomePromise = new Promise((resolve) => {
+            this.resolveOutcome = resolve;
+        });
+        this.unsubscribe = this.agent.subscribe((event) => this.onAgentEvent(event));
+        // A finished run is not a finished window: the window stays open for a
+        // related input until the host ends it (docs/windows.md#lifecycle).
+        void options.run.catch((error) => this.settle("failed", error));
+    }
+    get state() {
+        if (this.ended)
+            return "ended";
+        if (this.paused)
+            return "paused";
+        return this.agent.state.isStreaming ? "running" : "idle";
+    }
+    async steer(delivery) {
+        if (this.ended) {
+            throw arborError({
+                code: "refused",
+                rule: "window.ended",
+                message: `窗口 ${this.window} 已结束，无法再插入内容。`,
+                nextAction: "把内容发给一个还在运行的窗口，或为它开一个新窗口。",
+            });
+        }
+        this.enqueue(delivery, "steer");
+        if (!this.agent.state.isStreaming)
+            await this.continue_();
+        this.stream.push({ kind: "steered", delivery });
+    }
+    async followUp(delivery) {
+        if (this.ended)
+            return;
+        this.enqueue(delivery, "followUp");
+    }
+    async end(handoff, reason = "model_ended") {
+        if (this.ended)
+            return;
+        this.agent.abort();
+        this.settle(reason, undefined, handoff);
+    }
+    async pause() {
+        this.paused = true;
+    }
+    async resume() {
+        this.paused = false;
+    }
+    usage() {
+        return this.current;
+    }
+    events() {
+        return this.stream.drain();
+    }
+    outcome() {
+        return this.outcomePromise;
+    }
+    enqueue(delivery, how) {
+        const text = renderDelivery(delivery, this.renderer);
+        const message = { role: "user", content: [{ type: "text", text }], timestamp: Date.now() };
+        if (how === "steer")
+            this.agent.steer(message);
+        else
+            this.agent.followUp(message);
+    }
+    /** Continue an idle window, so a queued delivery is picked up. */
+    async continue_() {
+        try {
+            await this.agent.continue();
+        }
+        catch {
+            // Nothing queued any more, or the run already moved on.
+        }
+    }
+    onAgentEvent(event) {
+        switch (event.type) {
+            case "tool_execution_start":
+                this.stream.push({
+                    kind: "tool_call",
+                    call: callOf(event.toolName, event.args, event.toolCallId),
+                });
+                break;
+            case "tool_execution_end":
+                this.stream.push({
+                    kind: "tool_result",
+                    call: callOf(event.toolName, {}, event.toolCallId),
+                    result: this.resultOf(event),
+                });
+                break;
+            case "message_end":
+                if (event.message.role === "assistant")
+                    this.trackUsage(event.message.usage);
+                break;
+            case "agent_end":
+                this.stream.push({ kind: "run_ended", outcome: this.outcomeOf("model_ended") });
+                break;
+            default:
+                break;
+        }
+    }
+    /**
+     * 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
+     * the reminder tiers within a few turns.
+     */
+    trackUsage(usage) {
+        if (usage === undefined)
+            return;
+        const used = usage.input + usage.cacheRead + usage.cacheWrite;
+        if (used <= this.current.used)
+            return;
+        this.current = { ...this.current, used };
+        this.stream.push({ kind: "usage", usage: this.current });
+    }
+    /** The core's result, kept by the backend when the call was made. */
+    resultOf(event) {
+        const kept = this.results.get(event.toolCallId);
+        if (kept !== undefined)
+            return kept;
+        const content = (event.result?.content ?? [])
+            .map((block) => (block.type === "text" ? (block.text ?? "") : `[${block.type}]`))
+            .join("\n");
+        const isError = event.isError === true;
+        return {
+            callId: event.toolCallId,
+            ok: isError === false,
+            content,
+            ...(isError ? { error: { rule: "tool.execution", message: content.slice(0, 500) } } : {}),
+        };
+    }
+    /** The outcome as it stands, for a run that ended. */
+    outcomeOf(reason, handoff) {
+        return {
+            window: this.window,
+            reason,
+            ...(handoff === undefined ? {} : { handoff }),
+            usage: this.current,
+        };
+    }
+    settle(reason, error, handoff) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        const outcome = {
+            window: this.window,
+            reason,
+            ...(handoff === undefined ? {} : { handoff }),
+            usage: this.current,
+            ...(error === undefined ? {} : { error: error instanceof Error ? error.message : String(error) }),
+        };
+        this.stream.push({ kind: "ended", outcome });
+        this.stream.close();
+        this.resolveOutcome(outcome);
+    }
+}
+function callOf(name, args, callId) {
+    return { name, args: (args ?? {}), callId };
+}

package/testing.d.ts

@@ -0,0 +1,8 @@
+/**
+ * pi's scripted provider, for a test that runs a window without a model
+ * (docs/prompting.md#no-built-in-pi-prompt is about the prompt, not the tests).
+ *
+ * pi owns its own test doubles, so a package that tests against the pi backend
+ * reaches them through here rather than depending on pi itself.
+ */
+export { createModels, fauxAssistantMessage, fauxProvider, fauxText, fauxToolCall, type FauxModelDefinition, type FauxProviderHandle, type FauxResponseStep, type Models, } from "@earendil-works/pi-ai";

package/testing.js

@@ -0,0 +1,8 @@
+/**
+ * pi's scripted provider, for a test that runs a window without a model
+ * (docs/prompting.md#no-built-in-pi-prompt is about the prompt, not the tests).
+ *
+ * pi owns its own test doubles, so a package that tests against the pi backend
+ * reaches them through here rather than depending on pi itself.
+ */
+export { createModels, fauxAssistantMessage, fauxProvider, fauxText, fauxToolCall, } from "@earendil-works/pi-ai";

package/tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The tool declarations a window is opened with, as pi's tools
+ * (docs/tools.md#direct-tools).
+ *
+ * A direct tool is declared to the model and called in the turn. The core
+ * declares it once, as a `DirectToolSpec`; this mapping turns that one
+ * declaration into pi's JSON Schema, so the model, the host and the journal all
+ * read the same description. No pi type crosses back: `execute` answers with the
+ * 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 type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { 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.
+ */
+export declare function resultText(result: ToolResult, renderer: Renderer): string;
+/** The core's result as pi's. */
+export declare function toolResultOf(result: ToolResult, renderer: Renderer): AgentToolResult<undefined>;
+/** One direct tool, declared and wired to the core's call path. */
+export declare function piTool(spec: {
+    name: string;
+    description: string;
+    parameters: Record<string, ParameterSpec>;
+}, call: (args: Record<string, unknown>, callId: string) => Promise<ToolResult>, renderer: Renderer): AgentTool<Record<string, unknown>>;

package/tools.js

@@ -0,0 +1,98 @@
+/**
+ * The tool declarations a window is opened with, as pi's tools
+ * (docs/tools.md#direct-tools).
+ *
+ * A direct tool is declared to the model and called in the turn. The core
+ * declares it once, as a `DirectToolSpec`; this mapping turns that one
+ * declaration into pi's JSON Schema, so the model, the host and the journal all
+ * read the same description. No pi type crosses back: `execute` answers with the
+ * 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";
+/** One parameter's JSON Schema, from its `ParameterSpec`. */
+export function parameterSchema(parameter) {
+    const schema = {
+        type: jsonType(parameter.type),
+        description: parameter.description,
+    };
+    if (parameter.default !== undefined)
+        schema.default = parameter.default;
+    if (parameter.type === "refs" || parameter.type === "blocks" || parameter.type === "array") {
+        schema.items = { type: "string" };
+    }
+    if (parameter.type === "object") {
+        // A nested object carries whatever its own fields say, the way a tool
+        // schema from another system does.
+        schema.additionalProperties = true;
+    }
+    return schema;
+}
+function jsonType(type) {
+    switch (type) {
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "object":
+            return "object";
+        case "refs":
+        case "blocks":
+        case "array":
+            return "array";
+        default:
+            return "string";
+    }
+}
+/** The JSON Schema one tool declares to pi. */
+export function toolParameters(parameters) {
+    const properties = {};
+    const required = [];
+    for (const [name, parameter] of Object.entries(parameters)) {
+        properties[name] = parameterSchema(parameter);
+        if (parameter.required === true)
+            required.push(name);
+    }
+    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.
+ */
+export function resultText(result, renderer) {
+    if (result.ok)
+        return result.content;
+    const error = result.error;
+    if (error === undefined)
+        return result.content;
+    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 }),
+        }),
+    ]);
+}
+/** The core's result as pi's. */
+export function toolResultOf(result, renderer) {
+    return {
+        content: [{ type: "text", text: resultText(result, renderer) }],
+        details: undefined,
+        isError: result.ok === false,
+    };
+}
+/** One direct tool, declared and wired to the core's call path. */
+export function piTool(spec, call, renderer) {
+    return {
+        name: spec.name,
+        label: spec.name,
+        description: spec.description,
+        parameters: toolParameters(spec.parameters),
+        execute: async (callId, params) => {
+            const result = await call((params ?? {}), callId);
+            return toolResultOf(result, renderer);
+        },
+    };
+}

package/usage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What one window's tokens are (docs/windows.md#usage-reminders).
+ *
+ * `used` is the footprint of the window's context, not a running total: the
+ * last request's input, cache read and cache write. A running total would
+ * resend the context on every turn and cross the reminder tiers in the first
+ * few turns; the footprint is what the tiers and the hard limit are about.
+ */
+import type { TokenUsage } from "@4fu/arbor-interfaces";
+import type { Usage as PiUsage } from "@earendil-works/pi-ai";
+/** The tokens one provider request carried. */
+export declare function requestTokens(usage: PiUsage | undefined): number;
+/** The window's usage, from the last assistant message. */
+export declare function tokenUsage(usage: PiUsage | undefined, limit: number, reserve: number, previous?: TokenUsage): TokenUsage;
+/** True when the reported usage moved the window forward. */
+export declare function usageChanged(before: TokenUsage, after: TokenUsage): boolean;
+/** The core's usage shape, for a window that never reached a model. */
+export declare function emptyUsage(limit: number, reserve: number): TokenUsage;

package/usage.js

@@ -0,0 +1,27 @@
+/**
+ * What one window's tokens are (docs/windows.md#usage-reminders).
+ *
+ * `used` is the footprint of the window's context, not a running total: the
+ * last request's input, cache read and cache write. A running total would
+ * resend the context on every turn and cross the reminder tiers in the first
+ * few turns; the footprint is what the tiers and the hard limit are about.
+ */
+/** The tokens one provider request carried. */
+export function requestTokens(usage) {
+    if (usage === undefined)
+        return 0;
+    return usage.input + usage.cacheRead + usage.cacheWrite;
+}
+/** The window's usage, from the last assistant message. */
+export function tokenUsage(usage, limit, reserve, previous) {
+    const used = Math.max(requestTokens(usage), previous?.used ?? 0);
+    return { used, limit, reserve };
+}
+/** True when the reported usage moved the window forward. */
+export function usageChanged(before, after) {
+    return before.used !== after.used;
+}
+/** The core's usage shape, for a window that never reached a model. */
+export function emptyUsage(limit, reserve) {
+    return { used: 0, limit, reserve };
+}