@4fu/dsh-arbor-tools 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,108 @@
+/**
+ * Tool bridge: DSH's registered tools enter arbor as external tools and run
+ * through `ctx.tools.execute`.
+ *
+ * `AgentBackend.externalTools()` (arbor-interfaces/agent.d.ts) is the seam the
+ * plan names: the host registers what it is handed, and from there a DSH tool
+ * is a direct tool like any other — declared to the model under its own name
+ * and called through the same hooks, journaling, scrub and result cut as
+ * arbor's own. Execution lands back in DSH: `ctx.tools.execute` with the user
+ * session's agent, which is what routes a tool call that needs approval
+ * through DSH's approval path (`packages/core/tools/src/pipeline.ts`
+ * serviceAsk → `packages/interaction/user-approval`), and appends the durable
+ * `tool/call` + `tool/result` pair to the user session's log.
+ *
+ * Two things make that seam faithful rather than lossy:
+ *
+ *  - **The schema is carried verbatim.** A DSH tool declares its parameters as
+ *    JSON Schema; arbor's `ExternalTool.schema` is exactly that, so `enum`,
+ *    `items`, `oneOf`, `additionalProperties` and a nested object's own
+ *    properties all reach the model instead of being flattened away.
+ *  - **Every capability appears once.** {@link DSH_TOOLS_ARBOR_REPLACES} names
+ *    the DSH tools whose capability arbor already has, so they are neither
+ *    handed to the catalog nor offered by DSH's own pipeline: the driver
+ *    installs the same list as a `tools.restrict` in each arbor session's
+ *    scope, which is also what makes their `tool:*` prompt sections render
+ *    empty.
+ */
+import type { AgentRegistry } from '@deepseek-ai/dsh-agent';
+import type { ToolsService } from '@deepseek-ai/dsh-tools';
+import type { ExternalTool, DirectToolSpec } from '@4fu/arbor-interfaces';
+/**
+ * The DSH tools arbor's own replaces, one capability each.
+ *
+ * - `bash`, `pwsh` — arbor's `bash`, `bash_output`, `bash_stop`.
+ * - `read`, `write`, `edit`, `apply_patch` — arbor's file tools.
+ * - `glob`, `grep` — arbor's `workspace` module.
+ * - `job_start`, `job_output`, `job_kill`, `job_list` — arbor's
+ *   `bash_output` / `bash_stop`.
+ * - `subagent`, `subagent_fork` — arbor's windows, its broadcast and its
+ *   window messages.
+ * - `schedule`, `schedule_*` — arbor's own `schedule` module. DSH's scheduler
+ *   opens another DSH session, which fights arbor's source model.
+ * - `create_goal`, `get_goal`, `update_goal` — goals are closed for arbor
+ *   sessions.
+ * - `team_*`, `send_message`, `list_agents`, `interrupt_agent` — teams are
+ *   closed for arbor sessions.
+ * - `ralph` — closed for arbor sessions.
+ * - `workflow` — closed for arbor sessions.
+ * - `session_search`, `session_trace`, `session_event_search`,
+ *   `session_event_read`, `session_event_trace` — history is arbor's journal.
+ * - `structured_output` — only DSH's own subagents use it.
+ * - `run_code` — arbor has its own `code_exec`; DSH's PTC executor is not used.
+ * - `working_directory` — arbor owns the paths for an arbor session.
+ * - `skill` — reading the SKILL.md `<env>` names, which arbor's `read` does.
+ *
+ * `read_image` is deliberately absent: it returns the image itself, which
+ * arbor's text-only `read` cannot, so it is a capability of its own rather than
+ * a duplicate.
+ *
+ * The list is filtered against what the deployment actually registers before
+ * it is used, because `tools.restrict` rejects an unknown name.
+ */
+export declare const DSH_TOOLS_ARBOR_REPLACES: readonly string[];
+/**
+ * The subset of {@link DSH_TOOLS_ARBOR_REPLACES} the deployment registers.
+ *
+ * Filtered, because `tools.restrict` throws on a name that is not a known
+ * global tool, and a deployment mounts only part of DSH.
+ */
+export declare function replacedToolsRegistered(tools: ToolsService): readonly string[];
+/** One arbor direct-tool spec back to a DSH tool schema for the model request. */
+export declare function schemaOf(spec: DirectToolSpec): Record<string, unknown>;
+/**
+ * The live turn's abort signal, which a running session agent exposes so a
+ * tool call is aborted with the turn that asked for it. The arbor session
+ * agent implements it; any other agent simply does not, and the call then runs
+ * on a signal of its own, the way a standalone call does.
+ */
+export interface LiveTurnSignal {
+    currentSignal(): AbortSignal | undefined;
+}
+/** Inputs for {@link dshExternalTools}. */
+export interface DshExternalToolsOptions {
+    /** DSH's tool registry. */
+    readonly tools: ToolsService;
+    /**
+     * DSH's agent registry. One backend serves every session, so the agent a
+     * call runs as is read per call: the initiating agent of the turn executing
+     * it, which is the session whose window asked for the call.
+     */
+    readonly agents: AgentRegistry;
+}
+/**
+ * Every registered DSH tool arbor does not already have, as arbor external
+ * tools.
+ *
+ * The specs are host-level and session-free: the same declarations reach the
+ * model whichever session's window is running, and each call executes as the
+ * session whose turn is running it. With no initiating agent — a call outside
+ * any turn — DSH's own pipeline degrades the execution to a deny, which is the
+ * correct fail-closed answer.
+ *
+ * The execution carries no log position, so DSH's pipeline does not write the
+ * `tool/call` + `tool/result` pair: the driver's bridge writes one pair for
+ * every call the window runs, arbor's own tools included, because the session
+ * log is the history the next model request is derived from.
+ */
+export declare function dshExternalTools(options: DshExternalToolsOptions): readonly ExternalTool[];

package/index.js

@@ -0,0 +1,220 @@
+/**
+ * Tool bridge: DSH's registered tools enter arbor as external tools and run
+ * through `ctx.tools.execute`.
+ *
+ * `AgentBackend.externalTools()` (arbor-interfaces/agent.d.ts) is the seam the
+ * plan names: the host registers what it is handed, and from there a DSH tool
+ * is a direct tool like any other — declared to the model under its own name
+ * and called through the same hooks, journaling, scrub and result cut as
+ * arbor's own. Execution lands back in DSH: `ctx.tools.execute` with the user
+ * session's agent, which is what routes a tool call that needs approval
+ * through DSH's approval path (`packages/core/tools/src/pipeline.ts`
+ * serviceAsk → `packages/interaction/user-approval`), and appends the durable
+ * `tool/call` + `tool/result` pair to the user session's log.
+ *
+ * Two things make that seam faithful rather than lossy:
+ *
+ *  - **The schema is carried verbatim.** A DSH tool declares its parameters as
+ *    JSON Schema; arbor's `ExternalTool.schema` is exactly that, so `enum`,
+ *    `items`, `oneOf`, `additionalProperties` and a nested object's own
+ *    properties all reach the model instead of being flattened away.
+ *  - **Every capability appears once.** {@link DSH_TOOLS_ARBOR_REPLACES} names
+ *    the DSH tools whose capability arbor already has, so they are neither
+ *    handed to the catalog nor offered by DSH's own pipeline: the driver
+ *    installs the same list as a `tools.restrict` in each arbor session's
+ *    scope, which is also what makes their `tool:*` prompt sections render
+ *    empty.
+ */
+/**
+ * The DSH tools arbor's own replaces, one capability each.
+ *
+ * - `bash`, `pwsh` — arbor's `bash`, `bash_output`, `bash_stop`.
+ * - `read`, `write`, `edit`, `apply_patch` — arbor's file tools.
+ * - `glob`, `grep` — arbor's `workspace` module.
+ * - `job_start`, `job_output`, `job_kill`, `job_list` — arbor's
+ *   `bash_output` / `bash_stop`.
+ * - `subagent`, `subagent_fork` — arbor's windows, its broadcast and its
+ *   window messages.
+ * - `schedule`, `schedule_*` — arbor's own `schedule` module. DSH's scheduler
+ *   opens another DSH session, which fights arbor's source model.
+ * - `create_goal`, `get_goal`, `update_goal` — goals are closed for arbor
+ *   sessions.
+ * - `team_*`, `send_message`, `list_agents`, `interrupt_agent` — teams are
+ *   closed for arbor sessions.
+ * - `ralph` — closed for arbor sessions.
+ * - `workflow` — closed for arbor sessions.
+ * - `session_search`, `session_trace`, `session_event_search`,
+ *   `session_event_read`, `session_event_trace` — history is arbor's journal.
+ * - `structured_output` — only DSH's own subagents use it.
+ * - `run_code` — arbor has its own `code_exec`; DSH's PTC executor is not used.
+ * - `working_directory` — arbor owns the paths for an arbor session.
+ * - `skill` — reading the SKILL.md `<env>` names, which arbor's `read` does.
+ *
+ * `read_image` is deliberately absent: it returns the image itself, which
+ * arbor's text-only `read` cannot, so it is a capability of its own rather than
+ * a duplicate.
+ *
+ * The list is filtered against what the deployment actually registers before
+ * it is used, because `tools.restrict` rejects an unknown name.
+ */
+export const DSH_TOOLS_ARBOR_REPLACES = [
+    // bash / pwsh
+    'bash',
+    'pwsh',
+    // read / write / edit / apply_patch
+    'read',
+    'write',
+    'edit',
+    'apply_patch',
+    // glob / grep
+    'glob',
+    'grep',
+    // job_*
+    'job_start',
+    'job_output',
+    'job_kill',
+    'job_list',
+    // subagent / subagent_fork
+    'subagent',
+    'subagent_fork',
+    // schedule_*
+    'schedule',
+    'schedule_create',
+    'schedule_edit',
+    'schedule_list',
+    'schedule_view',
+    'schedule_delete',
+    'schedule_execution_pending',
+    // goal
+    'create_goal',
+    'get_goal',
+    'update_goal',
+    // team
+    'team_task_create',
+    'team_task_get',
+    'team_task_list',
+    'team_task_update',
+    'send_message',
+    'list_agents',
+    'interrupt_agent',
+    // ralph
+    'ralph',
+    // workflow
+    'workflow',
+    // session-query
+    'session_search',
+    'session_trace',
+    'session_event_search',
+    'session_event_read',
+    'session_event_trace',
+    // structured output and PTC
+    'structured_output',
+    'run_code',
+    // DSH's project management, which arbor owns for an arbor session: the
+    // paths are arbor's own `<workspace>` section's — the shared folder — so a
+    // `cd` would move ground the section does not describe. A UI switch still
+    // lands as a `working-directory/change` event, but an arbor session is not
+    // bound to one cwd: its window works in the shared folder and its checkouts,
+    // so the event moves the session's cwd display and nothing a window does.
+    'working_directory',
+    // DSH's skill loader, which is `read` of the SKILL.md `<env>` already names:
+    // the skill's body is a file under /env, and arbor's own `read` reaches it.
+    // `read_image` is NOT here: it returns the image itself, which arbor's
+    // text-only `read` cannot do.
+    'skill',
+];
+/**
+ * The subset of {@link DSH_TOOLS_ARBOR_REPLACES} the deployment registers.
+ *
+ * Filtered, because `tools.restrict` throws on a name that is not a known
+ * global tool, and a deployment mounts only part of DSH.
+ */
+export function replacedToolsRegistered(tools) {
+    const registered = new Set(tools.schemas().map(schema => schema.name));
+    return DSH_TOOLS_ARBOR_REPLACES.filter(name => registered.has(name));
+}
+/** One arbor direct-tool spec back to a DSH tool schema for the model request. */
+export function schemaOf(spec) {
+    // A tool declared from outside the core carries DSH's own JSON Schema
+    // verbatim, and that is what the model reads. Arbor's own tools declare
+    // none: their `parameters` are the declaration, and the shape is built here.
+    if (spec.schema !== undefined) {
+        return { name: spec.name, description: spec.description, parameters: spec.schema };
+    }
+    const properties = {};
+    const required = [];
+    for (const [name, parameter] of Object.entries(spec.parameters)) {
+        properties[name] = {
+            type: parameter.type === 'number' ? 'number'
+                : parameter.type === 'boolean' ? 'boolean'
+                    : parameter.type === 'array' ? 'array'
+                        : parameter.type === 'object' ? 'object'
+                            : 'string',
+            description: parameter.description,
+        };
+        if (parameter.required === true)
+            required.push(name);
+    }
+    return {
+        name: spec.name,
+        description: spec.description,
+        parameters: { type: 'object', properties, ...required.length > 0 ? { required } : {} },
+    };
+}
+/**
+ * Every registered DSH tool arbor does not already have, as arbor external
+ * tools.
+ *
+ * The specs are host-level and session-free: the same declarations reach the
+ * model whichever session's window is running, and each call executes as the
+ * session whose turn is running it. With no initiating agent — a call outside
+ * any turn — DSH's own pipeline degrades the execution to a deny, which is the
+ * correct fail-closed answer.
+ *
+ * The execution carries no log position, so DSH's pipeline does not write the
+ * `tool/call` + `tool/result` pair: the driver's bridge writes one pair for
+ * every call the window runs, arbor's own tools included, because the session
+ * log is the history the next model request is derived from.
+ */
+export function dshExternalTools(options) {
+    const { tools, agents } = options;
+    const replaced = new Set(DSH_TOOLS_ARBOR_REPLACES);
+    return tools.schemas()
+        .filter(schema => !replaced.has(schema.name))
+        .map(schema => ({
+        name: schema.name,
+        description: schema.description,
+        // DSH's own JSON Schema, carried verbatim: what the model reads is what
+        // DSH declared, not a summary of it.
+        schema: schema.parameters,
+        execute: async (request) => {
+            const agent = agents.currentInitiator();
+            const live = agent;
+            const signal = live?.currentSignal?.() ?? new AbortController().signal;
+            const call = {
+                type: 'tool-call',
+                id: request.callId,
+                name: request.name,
+                arguments: JSON.stringify(request.args),
+            };
+            const batch = await tools.execute({
+                calls: [call],
+                ...agent === undefined ? {} : { agent },
+                signal,
+            });
+            const settled = batch.results.find(result => result.callId === request.callId) ?? batch.results[0];
+            const result = settled?.result;
+            if (result === undefined) {
+                return { callId: request.callId, ok: false, content: `tool "${request.name}" produced no result`, tool: request.name };
+            }
+            const text = result.content.map(block => ('text' in block ? block.text : '')).join('');
+            return {
+                callId: request.callId,
+                ok: !result.isError,
+                content: text,
+                tool: request.name,
+                ...result.isError ? { error: { rule: 'tool.failed', message: text } } : {},
+            };
+        },
+    }));
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@4fu/dsh-arbor-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1110.1",
+  "type": "module",
+  "description": "Tool bridge: DSH tools enter arbor as external tools with their own JSON Schema, the ones arbor replaces are restricted away, and calls run through ctx.tools.execute",
+  "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"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "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-tools"
+  },
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": "0.2.2-rc.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js"
+}