@4fu/dsh-arbor-llm 0.0.0-stage → 2026.1110.1

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,250 @@
-# Temporary Holding Version
+# dsh-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.
+Run [arbor](https://github.com/4fuu/arbor) as the agent driver inside
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).
+
+DSH gives a user a session, a transcript, approvals, plugins, skills and a model
+picker. arbor gives an agent disposable context windows over one shared journal,
+note store and workspace, instead of one long conversation. dsh-arbor connects
+them: one arbor host runs inside the DSH process, each DSH session that selects
+**Arbor** is served by that host, and the window's reply is written back to the
+DSH session as an ordinary assistant message. A DSH session that does not select
+Arbor keeps running on DSH's own embedded AgentLoop, in the same process.
+
+> **Status.** This is a research-grade integration, not a DSH release. It is
+> pinned to one DSH version and relies on DSH internals. Read
+> [Versions and compatibility](docs/versions.md) before installing it on
+> anything you care about. The packages are published under `@4fu` at
+> `2026.1110.1`; the bundle and the font plugin install independently from npm.
+
+## What an arbor session changes
+
+Choosing **Arbor** in a DSH composer creates the session under the `arbor` agent
+preset. That session then runs on arbor, and the following are true for it:
+
+- **One window per turn, one chain per session.** A DSH session is one arbor
+  conversation: its first turn opens a window, a window that ends hands off to a
+  continuation, and the next turn drives the chain. The journal and note store
+  live under `$DSH_HOME/arbor/` and survive a restart.
+- **arbor's workspace, not DSH's sandbox.** A window works in arbor's shared
+  folder (`$DSH_HOME/arbor/shared`). When the `ovnfs` binary is available a
+  window opens a copy-on-write checkout and merges back with `apply`; otherwise
+  arbor uses a plain directory. **There is no DSH sandbox for an arbor session:**
+  arbor's file tools and commands run on the host, and arbor's own secret scrub
+  is the only protection on what reaches the model.
+- **arbor's projects.** The shared folder's project folders are the DSH project
+  list for arbor composers. A directory the user adds outside the shared folder
+  is recorded as an external pointer for that session and used in place.
+- **arbor's prompt and tools.** DSH's official prompt sections are decided one by
+  one; the ones arbor replaces are absent, third-party sections go into a
+  `<dsh>` data block, and a trusted `<harness>` section says what remains true of
+  DSH. DSH tools are offered to the model as arbor external tools, and arbor's
+  own tools replace DSH tools with the same capability.
+- **The Arbor page.** A permanent **Arbor** entry in DSH's left navigation opens
+  the whole-host overview and one tab per arbor session: windows, chains,
+  handoffs, projects, the board, notes, `/env`, schedules and arbor's search.
+  An arbor composer hides DSH's sandbox access-mode switch, because that switch
+  does not apply to it.
+
+## What stays untouched in ordinary DSH sessions
+
+A session that does not select Arbor is an ordinary DSH session. It keeps:
+
+- DSH's embedded AgentLoop, session format, turn boundaries and streaming path;
+- DSH's sandbox policy and its `ctx.fs` / `ctx.shell` file and command tools;
+- DSH's project management, working directory and prompt assembly;
+- its composer, sandbox access-mode switch, header and sidebar behavior.
+
+It gets **no Arbor tab** and no arbor windows. The only shared surface is the
+permanent Arbor entry in the left navigation, which simply does not list that
+session. The routing registry replaces DSH's base `agent` row so it can send
+`agentPreset: 'arbor'` sessions to arbor; every other session goes to the
+official loop. Approvals still use DSH's approval path for both kinds of
+session, and arbor's windows are registered so DSH's sidebar leaves them out.
+
+## Screenshots
+
+| Overview, light | Overview, dark |
+| --- | --- |
+| ![Arbor overview in light mode](docs/screenshots/overview-light.png) | ![Arbor overview in dark mode](docs/screenshots/overview-dark.png) |
+| **Session tab, light** | **Session tab, dark** |
+| ![An arbor session tab in light mode](docs/screenshots/session-light.png) | ![An arbor session tab in dark mode](docs/screenshots/session-dark.png) |
+
+These are the web profile at 1440 px wide with the optional
+[font plugin](https://github.com/4fuu/dsh-arbor-fonts) installed: ChillDIN
+Gothic for labels and ChillDIN for numerals, while body text and code keep
+DSH's fonts. The same overview without the plugin is
+[here](docs/screenshots/overview-without-fonts.png).
+
+## Install
+
+Requirements: Node.js 24.9 or newer and DeepSeek Harness `dsh-v0.2.2-rc.1`.
+The bundle is published with all packages it depends on; nothing has to be
+built or linked.
+
+```bash
+npm install -g @deepseek-ai/dsh@0.2.2-rc.1
+dsh plugin --profile web add @4fu/dsh-arbor-bundle@2026.1110.1
+dsh web
+```
+
+`dsh plugin` adds the bundle to the profile's `dsh.profile.bundles` and installs
+its packages into the profile. The packages declare DSH's runtime packages as
+peer dependencies, so the profile keeps DSH's own copies rather than installing
+a second set. Pick **Arbor** in a composer and send a message.
+The optional [font plugin](https://github.com/4fuu/dsh-arbor-fonts) installs the
+same way, but it is a Host row rather than a bundle. Add the row to the
+profile's `cordis.patch.yml` after installing it:
+
+```bash
+dsh plugin --profile web add @4fu/dsh-arbor-fonts@2026.1110.0
+```
+
+```yaml
+- insert:
+    - id: arbor-fonts
+      name: '@4fu/dsh-arbor-fonts'
+```
+
+Replace the default `[]` in that file with the entry, then restart the profile.
+
+### From a checkout
+
+The proofs and development use the TypeScript sources directly; that checkout is
+what the scripts and the pin check run against.
+
+```bash
+git clone https://github.com/4fuu/dsh-arbor
+cd dsh-arbor
+pnpm install --frozen-lockfile
+pnpm check                 # tsc --noEmit over every package and proof
+pnpm proofs                # 29 proofs against the scripted model
+```
+
+The first install may ask pnpm to approve dependency build scripts. Do not
+approve them by hand: the repository's `pnpm-workspace.yaml` already denies the
+six scripts it pulls in, each with the reason, and `pnpm install` finishes
+cleanly with that policy.
+
+### Hand the install to a model
+
+[docs/install-for-agents.md](docs/install-for-agents.md) is a step-by-step guide
+written for an AI agent: install from npm or a checkout, run the proofs, drive a
+live turn with a restart, boot the web profile, and inspect what ran. Give a
+model this prompt, editing the bracketed parts or dropping them:
+
+```text copy Copy Install Prompt
+Install dsh-arbor (https://github.com/4fuu/dsh-arbor) in this environment [in a
+scratch DSH home under /tmp] and show me that it works: follow
+docs/install-for-agents.md, install @4fu/dsh-arbor-bundle@2026.1110.1 into a DSH
+web profile, pick Arbor for one session, and [also run the proof suite from a
+checkout with pnpm install --frozen-lockfile, pnpm check and pnpm proofs]. Report
+which checks passed, what the live session answered, and anything that did not
+work. Fix only what is yours to fix and tell me what you changed.
+```
+
+## Use it in DSH
+
+The npm install above adds the bundle to a DSH web profile. Pick **Arbor** in a
+composer and send a message: the session is created under the preset, its window
+and chain appear under the **Arbor** entry, and an ordinary session started
+beside it keeps DSH's own composer and sandbox behavior. A checkout can also be
+wired by hand; [section 7 of the install guide](docs/install-for-agents.md#7-wiring-the-bundle-into-a-real-dsh-installation)
+shows the profile layout.
+
+The one-shot `dsh <task>` runner cannot drive an arbor-preset session: DSH's
+runner refuses to adopt a session that runs under a preset. Use the web client,
+the SDK path the proofs use, or a remote `agent-preset/select` on a blank.
+
+## Pinned DSH version
+
+DSH is pinned to **`dsh-v0.2.2-rc.1`** (npm
+`@deepseek-ai/dsh@0.2.2-rc.1`, commit `66491b05e3` of
+`deepseek-ai/deepseek-harness`). Every `@deepseek-ai/dsh*` dependency is an
+exact version, every package under `packages/` declares
+`engines.dsh: 0.2.2-rc.1`, and `pnpm check:pin` checks both plus the prompt
+bridge's `DSH_PINNED_VERSION`. DSH's runtime packages are peer dependencies, and
+`pnpm check:profile` installs the packed packages into a fresh DSH web profile to
+prove the profile keeps one copy and can create both kinds of session.
+
+A different DSH version is unsupported. The bundle depends on DSH's row names,
+its one-`AgentFactory` rule, its prompt-section registry, its client slot
+registration and its exact Fetch registry; a move in any of them can fail the
+boot, leave an official prompt section undecided, or stop the Arbor page from
+registering. `proofs/12-official-sections.ts` and `proofs/18-picker-pin.ts`
+are the behavioral checks. The canonical pin and the upgrade procedure are in
+[Versions and compatibility](docs/versions.md).
+
+## Optional: the font plugin
+
+[dsh-arbor-fonts](https://github.com/4fuu/dsh-arbor-fonts) is a separate DSH
+client plugin that changes only the typography of the Arbor page. It sets
+ChillDIN Gothic for display labels and ChillDIN for numerals, leaves body text
+and code on DSH's fonts, and does nothing on ordinary pages. It is optional and
+installs into the same DSH profile:
+
+```bash
+dsh plugin --profile web add @4fu/dsh-arbor-fonts@2026.1110.0
+```
+
+The fonts are licensed under the SIL Open Font License 1.1; the plugin ships the
+license text, per-file hashes and attribution. The plugin is a Host row rather
+than a bundle: after installing it, add the `arbor-fonts` entry described under
+[Install](#install) to `cordis.patch.yml` and restart the profile.
+
+## Limits worth knowing
+
+- The judge is off: a model-based judge cannot run through the DSH backend yet.
+- The 12 bundle packages are published together at one version; install and
+  upgrade the bundle as a unit, because its packages name each other exactly.
+- `ovnfs` is optional. Without it arbor uses the plain-directory workspace, and a
+  window no longer gets a copy-on-write checkout.
+- The web page's numbers and layout are read from arbor's journal and API; it is
+  not a generic DSH dashboard, and it deliberately shows only arbor sessions.
+- The prompt bridge, the UI and the picker filter are pinned to DSH's internals,
+  not to a stable public API. See [Versions and compatibility](docs/versions.md).
+
+## Documentation
+
+- [Installing and inspecting dsh-arbor](docs/install-for-agents.md) — the
+  agent-facing install, proof, live-turn, web-profile and wiring guide.
+- [Versions and compatibility](docs/versions.md) — the DSH and arbor pins, and
+  what breaks on another DSH version.
+- [B0 findings](docs/b0-findings.md), [B3 findings](docs/b3-findings.md) and
+  [B3b projects and sandbox](docs/b3b-projects-and-sandbox.md) — historical
+  records of the integration's decisions, with the DSH source locations each
+  one rests on. They describe earlier stages; the install guide is the current
+  status.
+- [Layout and proofs](#layout) below for a quick map of the packages.
+
+## Layout
+
+```text
+packages/
+  arbor-host/       one Arbor host per process: SQLite journal and notes,
+                    settings, window lifecycle, workspace and environment
+  arbor-driver/     the routing AgentRegistry, AgentFactory, session agent,
+                    inbox and stream mirrors, and the journal relay
+  arbor-llm/        the arbor AgentBackend over DSH's ctx.llm and ctx.tools
+  arbor-prompt/     <harness>, the <dsh> data block, and the section table
+  arbor-tools/      DSH tools as arbor external tools, same-name replacement
+  arbor-workspace/  arbor's workspace over the shared folder (ovnfs or dir)
+  arbor-env/        /env, with DSH's skills and MCP servers mounted read-only
+  arbor-bundle/     the installable patch that mounts the rows and UI
+  arbor-facts/      the read face behind the Arbor page and its Fetch routes
+  arbor-ui/         the Arbor page, session tabs, copy and composer gate
+  arbor-ui-workspace/
+                    the per-preset hero project picker
+  arbor-preset/     the agent-preset row that puts Arbor in the roster
+  arbor-testkit/    the boot harness, memory journal and scripted model
+patches/            overlay layers a proof applies above the shipped profile
+proofs/             one runnable proof per integration point
+docs/               install, versions, screenshots and historical findings
+scripts/            the pin and profile checks, the release build and packing
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE). The optional font plugin vendors fonts under the
+SIL Open Font License 1.1; its repository carries the license text and
+attribution.

package/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The arbor `AgentBackend` that runs each window through DSH.
+ *
+ * One DSH process mounts one Arbor host (see `@4fu/dsh-arbor-host`), so this
+ * backend is one object that serves every session's windows. Per window it
+ * holds the frozen epoch the host opened it with — the rendered system prompt
+ * and the declared direct tools, DSH's among them — plus the window's live
+ * event bus. Per window it also holds the DSH session agent whose turns drive
+ * it, bound by the driver when the session is created or resumed.
+ *
+ * This is the seam where arbor's window lifecycle meets DSH's services:
+ *
+ *  - `open(request)` captures the window's frozen epoch and returns the window
+ *    session the host watches. It needs no agent: a window a restart continued
+ *    opens before any session is resumed onto it.
+ *  - `modelCall` — used by the DSH-side session agent for each of its steps —
+ *    resolves the route, logs the `request/header`, and streams through
+ *    `ctx.llm.stream`; the request itself is derived from the session log by
+ *    the agent's owner.
+ *  - `externalTools()` hands DSH's registered tools to arbor, so the model
+ *    declares and calls them like any other direct tool; execution lands back
+ *    in `ctx.tools.execute` with the session agent of the turn that is running,
+ *    which is what routes approvals through DSH's approval path and appends the
+ *    durable `tool/call` + `tool/result` pair to that session's log.
+ *
+ * The window session is a live event bus: the agent publishes text deltas,
+ * tool calls and run boundaries, and the host's `watch` loop consumes them
+ * like any backend's.
+ */
+import type { Agent, AgentRegistry, ModelSelection } from '@deepseek-ai/dsh-agent';
+import type { LlmRuntime, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { ToolsService } from '@deepseek-ai/dsh-tools';
+import type { AgentBackend, DirectToolSpec, ExternalTool, LoginResult, ModelInfo, OpenWindowRequest, WindowEndReason, WindowEvent, WindowRef, WindowSession } from '@4fu/arbor-interfaces';
+import type { Renderer } from '@4fu/arbor-prompt';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'arbor-delivery': {
+            kind: 'arbor-delivery';
+        } & ContextFormed;
+    }
+}
+/** One model call's inputs, supplied by the DSH-side session agent. */
+export interface DshModelCall {
+    /** The window whose frozen epoch this call runs under. */
+    readonly window: WindowRef;
+    /** The session agent whose log the request is derived from. */
+    readonly agent: Agent;
+    readonly selection: Readonly<ModelSelection>;
+    readonly maxTokens?: number;
+    readonly position: {
+        turn: number;
+        step: number;
+    };
+    readonly signal: AbortSignal;
+    /** One streamed chunk, for the durable attempt and the window's live output. */
+    readonly onChunk: (chunk: StreamChunk) => void;
+}
+/** One model call's settled facts. */
+export interface DshModelOutcome {
+    readonly usage?: TokenUsage;
+    readonly finish: string;
+}
+/** Inputs for {@link createDshBackend}. */
+export interface DshBackendOptions {
+    /** DSH's LLM runtime (`ctx.llm`). */
+    readonly llm: LlmRuntime;
+    /** DSH's tool registry (`ctx.tools`). */
+    readonly tools: ToolsService;
+    /**
+     * DSH's agent registry (`ctx.agents`). One backend serves every session, so
+     * the agent a tool call runs as is read per call from the initiating agent of
+     * the turn executing it — the same attribution DSH itself uses.
+     */
+    readonly agents: AgentRegistry;
+    /**
+     * The host's one renderer, read lazily because the host is built after this
+     * backend is. A delivery's blocks were built by the host with its own table
+     * and block kinds, so rendering them with any other renderer would drop the
+     * fixed lines and the kinds a plugin registered.
+     */
+    readonly renderer: () => Renderer;
+}
+/** The DSH-backed arbor agent backend: one per process, one entry per window. */
+export declare class DshBackend implements AgentBackend {
+    readonly name = "dsh";
+    private readonly windows;
+    private readonly waiting;
+    private readonly headers;
+    private readonly options;
+    constructor(options: DshBackendOptions);
+    /** Resolves once `open` has captured this window's frozen epoch. */
+    whenOpen(window: WindowRef): Promise<void>;
+    models(): Promise<ModelInfo[]>;
+    login(): Promise<LoginResult>;
+    externalTools(): readonly ExternalTool[];
+    /**
+     * The names of the DSH tools this backend hands to arbor, for the
+     * `<harness>` section's revision and its tool-usage lines. The same filter
+     * {@link externalTools} applies, so a name here is a name the model can call.
+     */
+    externalToolNames(): readonly string[];
+    open(request: OpenWindowRequest): Promise<WindowSession>;
+    /**
+     * Bind the DSH session agent whose turns drive this window. A window a
+     * restart continued opens before its session is resumed, so the binding is
+     * made when the session comes back, not when the window does.
+     */
+    bind(window: WindowRef, agent: Agent): void;
+    /**
+     * Drop one window's binding, the way a session's disposal does: the window
+     * itself is the host's and lives out arbor's own idle policy.
+     */
+    unbind(window: WindowRef): void;
+    /** Drop one ended window's state, so nothing retains its agent or its bus. */
+    private release;
+    /** The window's live events, observable beside the host's own watch loop. */
+    events(window: WindowRef): AsyncIterable<WindowEvent>;
+    /** The system prompt this window's epoch rendered. */
+    systemPrompt(window: WindowRef): string;
+    /** The direct tools declared to the model for this window, as they stand now. */
+    toolSpecs(window: WindowRef): readonly DirectToolSpec[];
+    /** Publish one live stream event to the window. */
+    publish(window: WindowRef, event: WindowEvent): void;
+    /** The turn's work settled: the window's run ends and it stays open for more. */
+    finishRun(window: WindowRef): void;
+    /** End the window, the way a host shutdown does. */
+    endWindow(window: WindowRef, reason?: WindowEndReason): Promise<void>;
+    private requireEntry;
+    /**
+     * One model call for the DSH-side agent's current step: resolve the route,
+     * log the request header, and stream through `ctx.llm`. The request's
+     * messages come from the session log, exactly like the official loop's
+     * `buildRequest`.
+     */
+    modelCall(input: DshModelCall): Promise<DshModelOutcome>;
+    /** Log the resolved request header the way `ReactLoopAgent.buildRequest` does. */
+    private logRequestHeader;
+}
+/** Create the DSH-backed arbor agent backend. */
+export declare function createDshBackend(options: DshBackendOptions): DshBackend;

package/index.js

@@ -0,0 +1,514 @@
+/**
+ * The arbor `AgentBackend` that runs each window through DSH.
+ *
+ * One DSH process mounts one Arbor host (see `@4fu/dsh-arbor-host`), so this
+ * backend is one object that serves every session's windows. Per window it
+ * holds the frozen epoch the host opened it with — the rendered system prompt
+ * and the declared direct tools, DSH's among them — plus the window's live
+ * event bus. Per window it also holds the DSH session agent whose turns drive
+ * it, bound by the driver when the session is created or resumed.
+ *
+ * This is the seam where arbor's window lifecycle meets DSH's services:
+ *
+ *  - `open(request)` captures the window's frozen epoch and returns the window
+ *    session the host watches. It needs no agent: a window a restart continued
+ *    opens before any session is resumed onto it.
+ *  - `modelCall` — used by the DSH-side session agent for each of its steps —
+ *    resolves the route, logs the `request/header`, and streams through
+ *    `ctx.llm.stream`; the request itself is derived from the session log by
+ *    the agent's owner.
+ *  - `externalTools()` hands DSH's registered tools to arbor, so the model
+ *    declares and calls them like any other direct tool; execution lands back
+ *    in `ctx.tools.execute` with the session agent of the turn that is running,
+ *    which is what routes approvals through DSH's approval path and appends the
+ *    durable `tool/call` + `tool/result` pair to that session's log.
+ *
+ * The window session is a live event bus: the agent publishes text deltas,
+ * tool calls and run boundaries, and the host's `watch` loop consumes them
+ * like any backend's.
+ */
+import { BlockAssembler, createDeveloperMessage, createUserMessage, markAgentLoopRequest } from '@deepseek-ai/dsh-llm';
+import { canonicalHeader, headerEquals } from '@deepseek-ai/dsh-session';
+import { renderDelivery } from '@4fu/arbor-prompt';
+import { dshExternalTools, schemaOf } from '@4fu/dsh-arbor-tools';
+/** A minimal publish/subscribe bus for one window's events. */
+class WindowEventBus {
+    queues = new Set();
+    closed = false;
+    publish(event) {
+        if (this.closed)
+            return;
+        for (const queue of [...this.queues])
+            queue.push(event);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const queue of [...this.queues])
+            queue.close();
+        this.queues.clear();
+    }
+    subscribe() {
+        const queues = this.queues;
+        const pending = [];
+        const waiters = [];
+        let done = false;
+        const wake = () => {
+            const next = waiters.shift();
+            if (next !== undefined)
+                next();
+        };
+        const queue = {
+            push: (event) => {
+                pending.push(event);
+                wake();
+            },
+            close: () => {
+                done = true;
+                wake();
+            },
+        };
+        this.queues.add(queue);
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        while (true) {
+                            const event = pending.shift();
+                            if (event !== undefined)
+                                return { value: event, done: false };
+                            if (done)
+                                return { value: undefined, done: true };
+                            await new Promise(resolve => { waiters.push(resolve); });
+                        }
+                    },
+                    async return() {
+                        queues.delete(queue);
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+}
+/** One running arbor window backed by a DSH session. */
+class DshWindowSession {
+    window;
+    bus;
+    ended = Promise.withResolvers();
+    /**
+     * The backend session's own state, not the host's window record.
+     *
+     * Arbor opens a window idle: opening it starts no run, and a continuation a
+     * restart opened before its session resumed stays idle until one does. This
+     * session starts a DSH turn when the bridge calls `modelCall`, so the turn is
+     * what makes this state running, and the turn's end returns it to idle. The
+     * host's record moves on the events this session publishes; the two are
+     * related but never copied from one another, because a host that says idle
+     * does not mean this session cannot accept a delivery.
+     */
+    currentState = 'idle';
+    /** The state a paused session returns to when the host resumes it. */
+    resumeState = 'idle';
+    usageValue = { used: 0, limit: 0, reserve: 0 };
+    onEnd;
+    /** The window's frozen epoch, whose declared tools a `refreshTools` replaces. */
+    epoch;
+    /** The DSH session agent whose turns drive this window, once one is bound. */
+    driver;
+    /** How a delivery is rendered into the one user-role input the model reads. */
+    render;
+    constructor(window, bus, onEnd, render) {
+        this.window = window;
+        this.bus = bus;
+        this.onEnd = onEnd;
+        this.render = render;
+    }
+    get state() {
+        return this.currentState;
+    }
+    /** Capture the window's frozen epoch: its prompt, its declared tools, its limits. */
+    open(request) {
+        this.epoch = request;
+        this.usageValue.limit = request.limits.contextTokens;
+        this.usageValue.reserve = request.limits.reserveTokens;
+    }
+    /** Bind the DSH session agent whose turns drive this window. */
+    bind(agent) {
+        this.driver = agent;
+    }
+    /** Drop the binding, the way a session's disposal does. */
+    unbind() {
+        this.driver = undefined;
+    }
+    /** One live event of this window, from the session agent that drives it. */
+    publish(event) {
+        if (this.currentState === 'ended')
+            return;
+        // The run's own events are what make the backend session running. Usage is
+        // not one of them: it is reported when a message ends, which can be the
+        // last thing before the run's end, so it must not wake a quiet window.
+        if (event.kind !== 'usage' && event.kind !== 'run_ended' && event.kind !== 'ended') {
+            this.beginRun();
+        }
+        this.bus.publish(event);
+    }
+    /**
+     * The DSH agent started a turn in this window. The host learns a run is
+     * active from the first event this session publishes; this state is the
+     * backend's own, and starts the window's `state` at running before that
+     * first event arrives.
+     */
+    beginRun() {
+        if (this.currentState === 'ended' || this.currentState === 'paused')
+            return;
+        this.currentState = 'running';
+    }
+    /**
+     * The turn ended and no turn is in progress now. The window stays open for
+     * the session's next turn, exactly as arbor's own record returns to idle.
+     */
+    finishRun() {
+        if (this.currentState === 'ended' || this.currentState === 'paused')
+            return;
+        this.currentState = 'idle';
+    }
+    /**
+     * Insert at the next tool-call boundary, through DSH's own steering.
+     *
+     * The mapping is the one arbor's `AgentBackend` contract names for a backend
+     * that is not pi: `agent.inject` for a step boundary and the agent's steering
+     * for the next turn. `agent.steer` covers both, because it splices into the
+     * next step while a turn runs and starts one when the window is idle — which
+     * is what a delivery arriving for a quiet window wants.
+     */
+    async steer(delivery) {
+        this.deliver(delivery, 'steer');
+    }
+    /** Queue for after the run ends: the delivery becomes the next turn's input. */
+    async followUp(delivery) {
+        this.deliver(delivery, 'followUp');
+    }
+    deliver(delivery, how) {
+        // The host never steers into a window it has ended or paused, and a window
+        // whose session is not bound yet has no inbox to splice into: a restart
+        // continuation opens before its session comes back. An idle window is not
+        // one of those: the host sends its related input through `followUp`, which
+        // starts the next turn, so only an ended window drops a delivery.
+        if (this.currentState === 'ended')
+            return;
+        const agent = this.driver;
+        if (agent === undefined)
+            return;
+        const text = this.render(delivery);
+        if (text === '')
+            return;
+        const message = createUserMessage({
+            content: [{ type: 'text', text }],
+            source: { kind: 'arbor-delivery' },
+        });
+        // Arbor marks every delivery with what it is to the turn it enters: a
+        // context delivery is read by the next request and must never start one, and
+        // an input delivery is what continues a quiet window. The mark is
+        // authoritative; the delivery kind is not consulted. Steering context into
+        // a quiet window would wake its session to read a diff, which is a turn the
+        // user did not ask for and the model has nothing to do in.
+        //
+        // An input while this session is idle is the next turn's input: DSH's
+        // `followup` is what wakes a quiet agent, and its steering target belongs
+        // to a turn that is already running. A delivery that arrives while a turn
+        // runs goes in at the next step (`steer`), or after the run (`followUp`).
+        if (delivery.role === 'context')
+            agent.inject(message);
+        else if (how === 'steer' && this.currentState === 'running')
+            agent.steer(message);
+        else
+            agent.followup(message);
+    }
+    /**
+     * Replace the tools this window declared, so a tool that appeared is callable
+     * here and one that was removed is not. The window's prefix is not rebuilt:
+     * the `tools_delta` it is steered tells it what moved.
+     */
+    async refreshTools(tools) {
+        if (this.epoch === undefined)
+            return;
+        this.epoch = { ...this.epoch, tools };
+    }
+    /** The tools declared to the model for this window, as they stand now. */
+    toolSpecs() {
+        return this.epoch?.tools ?? [];
+    }
+    /** The system prompt this window's epoch rendered. */
+    systemPrompt() {
+        return this.epoch?.prompt.system ?? '';
+    }
+    /**
+     * Add one model call's tokens to the window's running total, and publish the
+     * usage event.
+     *
+     * The event is what makes a running window current: the host asks every
+     * plugin section's revision and re-reads the external tools on it, once per
+     * step, so a `prompt_delta` and a `tools_delta` are delivered here rather than
+     * never.
+     */
+    addUsage(usage) {
+        if (usage === undefined)
+            return;
+        this.usageValue.used += (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+        this.publish({ kind: 'usage', usage: { ...this.usageValue } });
+    }
+    async end(handoff, reason = 'model_ended') {
+        if (this.currentState === 'ended')
+            return;
+        this.currentState = 'ended';
+        const outcome = this.outcomeOf(reason, handoff);
+        this.bus.publish({ kind: 'ended', outcome });
+        this.bus.close();
+        this.ended.resolve(outcome);
+        this.onEnd();
+    }
+    async pause() {
+        if (this.currentState === 'ended' || this.currentState === 'paused')
+            return;
+        this.resumeState = this.currentState;
+        this.currentState = 'paused';
+    }
+    async resume() {
+        if (this.currentState !== 'paused')
+            return;
+        this.currentState = this.resumeState;
+    }
+    usage() {
+        return this.usageValue;
+    }
+    events() {
+        return this.bus.subscribe();
+    }
+    outcome() {
+        return this.ended.promise;
+    }
+    outcomeOf(reason, handoff) {
+        return {
+            window: this.window,
+            reason,
+            ...handoff === undefined ? {} : { handoff },
+            usage: this.usageValue,
+        };
+    }
+}
+/** The DSH-backed arbor agent backend: one per process, one entry per window. */
+export class DshBackend {
+    name = 'dsh';
+    windows = new Map();
+    waiting = new Map();
+    headers = new WeakMap();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Resolves once `open` has captured this window's frozen epoch. */
+    whenOpen(window) {
+        const waiting = this.waiting.get(window);
+        if (waiting !== undefined)
+            return waiting.promise;
+        const entry = this.windows.get(window);
+        if (entry !== undefined)
+            return Promise.resolve();
+        const deferred = Promise.withResolvers();
+        this.waiting.set(window, deferred);
+        return deferred.promise;
+    }
+    async models() {
+        return [{ id: 'dsh-session', provider: 'dsh', images: true, name: 'DSH session' }];
+    }
+    async login() {
+        return { provider: 'dsh', state: 'logged-in', models: await this.models() };
+    }
+    externalTools() {
+        return dshExternalTools({
+            tools: this.options.tools,
+            agents: this.options.agents,
+        });
+    }
+    /**
+     * The names of the DSH tools this backend hands to arbor, for the
+     * `<harness>` section's revision and its tool-usage lines. The same filter
+     * {@link externalTools} applies, so a name here is a name the model can call.
+     */
+    externalToolNames() {
+        return this.externalTools().map(tool => tool.name).sort();
+    }
+    async open(request) {
+        const bus = new WindowEventBus();
+        const session = new DshWindowSession(request.window, bus, () => { this.release(request.window); }, delivery => renderDelivery(delivery, this.options.renderer()));
+        session.open(request);
+        this.windows.set(request.window, { session, agent: undefined });
+        this.waiting.get(request.window)?.resolve();
+        this.waiting.delete(request.window);
+        return session;
+    }
+    /**
+     * Bind the DSH session agent whose turns drive this window. A window a
+     * restart continued opens before its session is resumed, so the binding is
+     * made when the session comes back, not when the window does.
+     */
+    bind(window, agent) {
+        const entry = this.windows.get(window);
+        if (entry === undefined)
+            return;
+        entry.agent = agent;
+        entry.session.bind(agent);
+    }
+    /**
+     * Drop one window's binding, the way a session's disposal does: the window
+     * itself is the host's and lives out arbor's own idle policy.
+     */
+    unbind(window) {
+        const entry = this.windows.get(window);
+        if (entry === undefined)
+            return;
+        entry.agent = undefined;
+        entry.session.unbind();
+    }
+    /** Drop one ended window's state, so nothing retains its agent or its bus. */
+    release(window) {
+        this.windows.delete(window);
+        this.waiting.get(window)?.resolve();
+        this.waiting.delete(window);
+    }
+    /** The window's live events, observable beside the host's own watch loop. */
+    events(window) {
+        return this.requireEntry(window).session.events();
+    }
+    /** The system prompt this window's epoch rendered. */
+    systemPrompt(window) {
+        return this.requireEntry(window).session.systemPrompt();
+    }
+    /** The direct tools declared to the model for this window, as they stand now. */
+    toolSpecs(window) {
+        return this.requireEntry(window).session.toolSpecs();
+    }
+    /** Publish one live stream event to the window. */
+    publish(window, event) {
+        this.windows.get(window)?.session.publish(event);
+    }
+    /** The turn's work settled: the window's run ends and it stays open for more. */
+    finishRun(window) {
+        const session = this.windows.get(window)?.session;
+        if (session === undefined || session.state === 'ended')
+            return;
+        // The run is over before its end is published, so the next delivery this
+        // window takes is the next turn's input rather than this run's.
+        session.finishRun();
+        session.publish({
+            kind: 'run_ended',
+            outcome: { window, reason: 'model_ended', usage: session.usage() },
+        });
+    }
+    /** End the window, the way a host shutdown does. */
+    async endWindow(window, reason = 'host_restart') {
+        await this.windows.get(window)?.session.end(undefined, reason);
+    }
+    requireEntry(window) {
+        const entry = this.windows.get(window);
+        if (entry === undefined) {
+            throw new Error(`arbor backend: no open window "${window}"`);
+        }
+        return entry;
+    }
+    /**
+     * One model call for the DSH-side agent's current step: resolve the route,
+     * log the request header, and stream through `ctx.llm`. The request's
+     * messages come from the session log, exactly like the official loop's
+     * `buildRequest`.
+     */
+    async modelCall(input) {
+        const { agent } = input;
+        const llm = this.options.llm;
+        const { signal } = input;
+        // A model call is this backend session's turn at work: its state is
+        // running from here, before the first streamed event the host sees.
+        this.requireEntry(input.window).session.beginRun();
+        const proposed = {
+            provider: input.selection.provider,
+            model: input.selection.model,
+            ...input.selection.reasoningEffort === undefined ? {} : { reasoningEffort: input.selection.reasoningEffort },
+            ...input.maxTokens === undefined ? {} : { maxTokens: input.maxTokens },
+        };
+        const prepared = await llm.prepareCall(proposed, signal);
+        signal.throwIfAborted();
+        const config = prepared.config;
+        const tools = this.toolSpecs(input.window).map(schemaOf);
+        this.logRequestHeader(agent, config, tools, input.position);
+        const messages = agent.session.deriveMessages();
+        const request = markAgentLoopRequest({
+            ...config,
+            messages,
+            toolHistory: agent.session.toolHistory(),
+            ...tools.length > 0 ? { tools: tools } : {},
+            sessionId: agent.session.id,
+            signal,
+        });
+        const assembler = new BlockAssembler();
+        const stream = prepared.stream(request);
+        for await (const chunk of stream) {
+            signal.throwIfAborted();
+            input.onChunk(chunk);
+            assembler.push(chunk);
+        }
+        signal.throwIfAborted();
+        // The window's token total moves, which is also the host's cue to ask every
+        // plugin section's revision and re-read the external tools: a prompt delta
+        // and a tools delta are delivered on this event.
+        this.windows.get(input.window)?.session.addUsage(assembler.usage);
+        return { ...assembler.usage === undefined ? {} : { usage: assembler.usage }, finish: assembler.finish.kind };
+    }
+    /** Log the resolved request header the way `ReactLoopAgent.buildRequest` does. */
+    logRequestHeader(agent, config, tools, position) {
+        const header = canonicalHeader({
+            config,
+            ...tools.length > 0 ? { tools: tools } : {},
+        });
+        const baseline = agent.session.requestHeader();
+        const log = this.headers.get(agent);
+        let headerSeq;
+        if (log === undefined || !log.logged) {
+            headerSeq = agent.session.append('request/header', {
+                header,
+                reason: baseline === undefined ? 'initial' : 'resume',
+            }).seq;
+            this.headers.set(agent, { logged: true, toolNames: tools.map(tool => String(tool['name'])) });
+        }
+        else if (baseline === undefined || !headerEquals(baseline, header)) {
+            headerSeq = agent.session.append('request/header', { header, reason: 'change' }).seq;
+            // The tool set is diffed against the previous header rather than against
+            // this process's own record of it, so a window a restart continued reports
+            // the same additions the log already implies. Without that, the second
+            // process's first change would re-report tools the first one added.
+            const previousNames = new Set((baseline?.tools ?? []).map(tool => String(tool.name)));
+            const currentNames = new Set(tools.map(tool => String(tool['name'])));
+            const additions = [...currentNames].filter(name => !previousNames.has(name))
+                .map(name => ({ type: 'tool-addition', toolName: name }));
+            const removals = [...previousNames].filter(name => !currentNames.has(name))
+                .map(name => ({ type: 'tool-removal', toolName: name }));
+            if (additions.length > 0 || removals.length > 0) {
+                // A `developer/message` that activates a tool must name the header that
+                // declares it, which is the one just appended: DSH's own append refuses
+                // the event otherwise, and the refusal lands on the turn that asked for
+                // the model call.
+                agent.session.append('developer/message', {
+                    ...position,
+                    message: createDeveloperMessage({ source: { kind: 'tool-registry' }, content: [...additions, ...removals] }),
+                    ...additions.length > 0 ? { headerSeq } : {},
+                }, { surfaceOp: 'append' });
+            }
+            this.headers.set(agent, { logged: true, toolNames: tools.map(tool => String(tool['name'])) });
+        }
+    }
+}
+/** Create the DSH-backed arbor agent backend. */
+export function createDshBackend(options) {
+    return new DshBackend(options);
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@4fu/dsh-arbor-llm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1110.1",
+  "type": "module",
+  "description": "arbor AgentBackend that runs each window's turns through DSH's ctx.llm and ctx.tools",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.d.ts",
+    "index.js"
+  ],
+  "dependencies": {
+    "@4fu/arbor-interfaces": "2026.1109.1",
+    "@4fu/arbor-prompt": "2026.1109.1",
+    "@4fu/dsh-arbor-tools": "2026.1110.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/dsh-arbor.git",
+    "directory": "packages/arbor-llm"
+  },
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": "0.2.2-rc.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js"
+}