@4fu/dsh-arbor-driver 0.0.0-stage → 2026.1110.0

package/inbox.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The durable agent inbox for arbor sessions.
+ *
+ * The projection definition mirrors
+ * `packages/core/agent-loop/src/inbox.ts` in deepseek-harness (key `inbox`,
+ * stateVersion 1): the official AgentLoop registers the same key, and
+ * `SessionProjectionRegistry.register` refcounts one definition per key, so
+ * both drivers share one projection table. The driver-side `Inbox`
+ * implementation mirrors `ReactLoopInbox`: splice, claim and clear record
+ * durable `agent/inbox/spliced` events exactly as the official loop does.
+ */
+import type { MessageId } from '@deepseek-ai/dsh-llm';
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session';
+import type { AgentEventDispatch, Inbox as InboxContract, InboxState, InboxTarget, InboxWireState } from '@deepseek-ai/dsh-agent';
+import { z } from 'zod';
+/** Wire validation for pending agent input reconstructed from durable inbox splices. */
+export declare const inboxProjectionSchema: z.ZodReadonly<z.ZodObject<{
+    'next-turn': z.ZodReadonly<z.ZodArray<z.ZodCustom<UserMessage, UserMessage>>>;
+    'next-step': z.ZodReadonly<z.ZodArray<z.ZodCustom<UserMessage, UserMessage>>>;
+}, z.core.$strip>>;
+/** Standard fold that reconstructs pending input and rejects invalid durable splice history. */
+export declare const inboxProjectionDefinition: {
+    key: "inbox";
+    stateSchema: z.ZodReadonly<z.ZodObject<{
+        'next-turn': z.ZodReadonly<z.ZodArray<z.ZodCustom<UserMessage, UserMessage>>>;
+        'next-step': z.ZodReadonly<z.ZodArray<z.ZodCustom<UserMessage, UserMessage>>>;
+    }, z.core.$strip>>;
+    init: () => InboxState;
+    apply(state: InboxState, event: import("@deepseek-ai/dsh-session").SessionEvent): InboxState;
+    wire: {
+        viewSchema: z.ZodType<InboxWireState>;
+        view: (state: InboxState) => InboxWireState;
+    };
+    stateVersion: number;
+};
+/** Driver-owned durable Inbox for arbor sessions; mirrors ReactLoopInbox. */
+export declare class ArborInbox implements InboxContract {
+    private readonly readState;
+    private readonly session;
+    private readonly dispatch;
+    constructor(readState: () => InboxState, session: Session, dispatch: AgentEventDispatch);
+    get nextTurn(): readonly UserMessage[];
+    get nextStep(): readonly UserMessage[];
+    get hasPending(): boolean;
+    clear(): void;
+    claim(target: InboxTarget, turn: number): UserMessage[];
+    append(target: InboxTarget, message: UserMessage): void;
+    prepend(target: InboxTarget, message: UserMessage): void;
+    replace(messageId: MessageId, newMessage: UserMessage): boolean;
+    remove(messageId: MessageId): boolean;
+    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];
+    private locate;
+    /** Commit one normalized mutation and publish its live events. */
+    private mutate;
+}

package/inbox.js

@@ -0,0 +1,160 @@
+/**
+ * The durable agent inbox for arbor sessions.
+ *
+ * The projection definition mirrors
+ * `packages/core/agent-loop/src/inbox.ts` in deepseek-harness (key `inbox`,
+ * stateVersion 1): the official AgentLoop registers the same key, and
+ * `SessionProjectionRegistry.register` refcounts one definition per key, so
+ * both drivers share one projection table. The driver-side `Inbox`
+ * implementation mirrors `ReactLoopInbox`: splice, claim and clear record
+ * durable `agent/inbox/spliced` events exactly as the official loop does.
+ */
+import { z } from 'zod';
+/** Wire validation for pending agent input reconstructed from durable inbox splices. */
+export const inboxProjectionSchema = z.object({
+    'next-turn': z.array(z.custom()).readonly(),
+    'next-step': z.array(z.custom()).readonly(),
+}).readonly();
+/** Standard fold that reconstructs pending input and rejects invalid durable splice history. */
+export const inboxProjectionDefinition = {
+    key: 'inbox',
+    stateSchema: inboxProjectionSchema,
+    init: () => ({ 'next-turn': [], 'next-step': [] }),
+    apply(state, event) {
+        if (event.type !== 'agent/inbox/spliced')
+            return state;
+        const splice = event.data;
+        try {
+            const inbox = state[splice.target];
+            const removedCount = splice.removedCount ?? 0;
+            if (!Number.isSafeInteger(splice.start) || splice.start < 0 || splice.start > inbox.length
+                || !Number.isSafeInteger(removedCount) || removedCount < 0 || splice.start + removedCount > inbox.length) {
+                throw new Error('invalid inbox splice');
+            }
+            const next = inbox.toSpliced(splice.start, removedCount, ...splice.inserted);
+            const ids = new Set();
+            for (const message of splice.target === 'next-turn'
+                ? [...next, ...state['next-step']]
+                : [...state['next-turn'], ...next]) {
+                if (ids.has(message.id))
+                    throw new Error(`message "${message.id}" is already pending`);
+                ids.add(message.id);
+            }
+            return splice.target === 'next-turn'
+                ? { 'next-turn': next, 'next-step': state['next-step'] }
+                : { 'next-turn': state['next-turn'], 'next-step': next };
+        }
+        catch (error) {
+            throw new Error(`invalid persisted inbox splice at session seq ${event.seq}`, { cause: error });
+        }
+    },
+    wire: {
+        viewSchema: inboxProjectionSchema,
+        view: (state) => state,
+    },
+    stateVersion: 1,
+};
+/** Driver-owned durable Inbox for arbor sessions; mirrors ReactLoopInbox. */
+export class ArborInbox {
+    readState;
+    session;
+    dispatch;
+    constructor(readState, session, dispatch) {
+        this.readState = readState;
+        this.session = session;
+        this.dispatch = dispatch;
+    }
+    get nextTurn() {
+        return this.readState()['next-turn'];
+    }
+    get nextStep() {
+        return this.readState()['next-step'];
+    }
+    get hasPending() {
+        const state = this.readState();
+        return state['next-turn'].length > 0 || state['next-step'].length > 0;
+    }
+    clear() {
+        this.splice('next-step', 0, this.nextStep.length, []);
+        this.splice('next-turn', 0, this.nextTurn.length, []);
+    }
+    claim(target, turn) {
+        const claimed = this.mutate('next-step', 0, this.nextStep.length, [], false);
+        if (target === 'next-turn')
+            claimed.push(...this.mutate('next-turn', 0, 1, [], false));
+        for (const message of claimed)
+            this.dispatch.emit('agent/inbox/claimed', { message, turn });
+        return claimed;
+    }
+    append(target, message) {
+        this.splice(target, this.readState()[target].length, 0, [message]);
+    }
+    prepend(target, message) {
+        this.splice(target, 0, 0, [message]);
+    }
+    replace(messageId, newMessage) {
+        const location = this.locate(messageId);
+        if (location === undefined)
+            return false;
+        this.splice(location.target, location.index, 1, [newMessage]);
+        return true;
+    }
+    remove(messageId) {
+        const location = this.locate(messageId);
+        if (location === undefined)
+            return false;
+        this.splice(location.target, location.index, 1, []);
+        return true;
+    }
+    splice(target, start, deleteCount, inserted) {
+        return this.mutate(target, start, deleteCount, inserted, true);
+    }
+    locate(messageId) {
+        const state = this.readState();
+        for (const target of ['next-turn', 'next-step']) {
+            const index = state[target].findIndex(message => message.id === messageId);
+            if (index >= 0)
+                return { target, index };
+        }
+        return undefined;
+    }
+    /** Commit one normalized mutation and publish its live events. */
+    mutate(target, start, deleteCount, inserted, discardRemoved) {
+        const state = this.readState();
+        const inbox = state[target];
+        const truncatedStart = Math.trunc(start);
+        const offset = Number.isNaN(truncatedStart) ? 0 : truncatedStart;
+        const actualStart = offset < 0 ? Math.max(inbox.length + offset, 0) : Math.min(offset, inbox.length);
+        const truncatedDeleteCount = Math.trunc(deleteCount);
+        const actualDeleteCount = Math.min(Math.max(Number.isNaN(truncatedDeleteCount) ? 0 : truncatedDeleteCount, 0), inbox.length - actualStart);
+        if (actualDeleteCount === 0 && inserted.length === 0)
+            return [];
+        const candidate = inbox.toSpliced(actualStart, actualDeleteCount, ...inserted);
+        const ids = new Set();
+        for (const message of target === 'next-turn'
+            ? [...candidate, ...state['next-step']]
+            : [...state['next-turn'], ...candidate]) {
+            if (ids.has(message.id))
+                throw new Error(`message "${message.id}" is already pending`);
+            ids.add(message.id);
+        }
+        const outcome = discardRemoved && actualDeleteCount > 0 ? 'canceled' : undefined;
+        const splice = {
+            target,
+            start: actualStart,
+            ...(actualDeleteCount === 0 ? {} : { removedCount: actualDeleteCount }),
+            inserted,
+            ...(outcome === undefined ? {} : { outcome }),
+        };
+        const removed = inbox.slice(actualStart, actualStart + actualDeleteCount);
+        const event = this.session.append('agent/inbox/spliced', splice);
+        if (discardRemoved) {
+            for (const message of removed)
+                this.dispatch.emit('agent/inbox/discarded', { message });
+        }
+        for (const message of event.data.inserted) {
+            this.dispatch.emit('agent/inbox/inserted', { message });
+        }
+        return removed;
+    }
+}

package/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@4fu/dsh-arbor-driver` — the DSH plugin that runs arbor as the agent driver.
+ *
+ * The default export is the routing `AgentRegistry` subclass the patch row
+ * mounts in place of the base `agent` row; `./driver` mounts the arbor driver
+ * that runs arbor-preset sessions on the process's one Arbor host.
+ */
+export { ArborAgentRegistry, ARBOR_PRESET } from './registry.js';
+export type { ArborRoutingFactory } from './registry.js';
+export { ArborSessionAgent } from './session-agent.js';
+export type { ArborWindowBridge, ModelCallInput, ModelCallOutcome } from './session-agent.js';
+export { ArborInbox, inboxProjectionDefinition } from './inbox.js';
+export { ArborStreamAttempt } from './assistant-stream.js';
+export { ArborDriver } from './driver.js';
+export type { Config as DriverConfig, SessionArborLike } from './driver.js';
+export { windowToolCalls, relayToolCalls } from './relay.js';
+export type { ArborToolCall } from './relay.js';
+export { default } from './registry.js';

package/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@4fu/dsh-arbor-driver` — the DSH plugin that runs arbor as the agent driver.
+ *
+ * The default export is the routing `AgentRegistry` subclass the patch row
+ * mounts in place of the base `agent` row; `./driver` mounts the arbor driver
+ * that runs arbor-preset sessions on the process's one Arbor host.
+ */
+export { ArborAgentRegistry, ARBOR_PRESET } from "./registry.js";
+export { ArborSessionAgent } from "./session-agent.js";
+export { ArborInbox, inboxProjectionDefinition } from "./inbox.js";
+export { ArborStreamAttempt } from "./assistant-stream.js";
+export { ArborDriver } from "./driver.js";
+export { windowToolCalls, relayToolCalls } from "./relay.js";
+export { default } from "./registry.js";

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@4fu/dsh-arbor-driver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1110.0",
+  "type": "module",
+  "description": "The arbor agent driver: per-preset routing over the embedded official AgentLoop, the arbor AgentFactory, the session agent, and resume from the arbor journal",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./driver": {
+      "types": "./driver.d.ts",
+      "default": "./driver.js"
+    },
+    "./relay": {
+      "types": "./relay.d.ts",
+      "default": "./relay.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@4fu/arbor-core": "2026.1109.1",
+    "@4fu/arbor-interfaces": "2026.1109.1",
+    "@4fu/arbor-prompt": "2026.1109.1",
+    "@4fu/dsh-arbor-host": "2026.1110.0",
+    "@4fu/dsh-arbor-llm": "2026.1110.0",
+    "@4fu/dsh-arbor-prompt": "2026.1110.0",
+    "@4fu/dsh-arbor-tools": "2026.1110.0",
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-brand": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-scope": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-working-directory": "0.2.2-rc.1",
+    "@deepseek-ai/schemastery": "~3.19.0",
+    "zod": "~4.4.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/dsh-arbor.git",
+    "directory": "packages/arbor-driver"
+  },
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": "0.2.2-rc.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "assistant-stream.d.ts",
+    "assistant-stream.js",
+    "driver.d.ts",
+    "driver.js",
+    "inbox.d.ts",
+    "inbox.js",
+    "index.d.ts",
+    "index.js",
+    "registry.d.ts",
+    "registry.js",
+    "relay.d.ts",
+    "relay.js",
+    "runtime-context.d.ts",
+    "runtime-context.js",
+    "session-agent.d.ts",
+    "session-agent.js"
+  ],
+  "types": "./index.d.ts",
+  "main": "./index.js"
+}

package/registry.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The routing agent registry for arbor.
+ *
+ * DSH allows exactly one AgentFactory per process: `AgentRegistry.setFactory`
+ * throws `'an agent factory is already registered'` on a second call
+ * (packages/core/agent/src/index.ts, setFactory ~L383-399), and AgentLoop
+ * claims that single slot in its own `[Service.init]`
+ * (packages/core/agent-loop/src/index.ts L336). A bundle patch also cannot
+ * swap which package a row mounts — `applyPatches` treats a patch's `name` as
+ * a check only (vendor/include/src/patch.ts) — so the base `agent` row is
+ * disabled and this subclass is inserted in its place.
+ *
+ * The subclass keeps TWO factories:
+ *
+ *  - the official AgentLoop, captured when it registers itself through the
+ *    overridden `setFactory` (never passed to the base class, so the base
+ *    slot stays free and nothing throws); and
+ *  - the arbor driver, registered through {@link useArborFactory}.
+ *
+ * `create` routes on `meta.agentPreset === 'arbor'`; `resume` asks the arbor
+ * driver whether the persisted session is an arbor session and routes
+ * accordingly. Both paths delegate exactly the way the base class does
+ * (`getTraceable` + `Reflect.apply` through the caller-traced receiver), so
+ * the embedded loop keeps creating its agents into this same registry
+ * instance: ordinary DSH sessions keep working, including every consumer that
+ * reads `ctx.agents` (session-controller routing, UI liveness, the subagent
+ * tool).
+ */
+import AgentRegistry from '@deepseek-ai/dsh-agent';
+import type { AgentFactory, AgentHandle, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** The agent-preset value that routes a session to arbor. */
+export declare const ARBOR_PRESET = "arbor";
+/** An agent factory that can also say whether a persisted session is its own. */
+export interface ArborRoutingFactory extends AgentFactory {
+    /** Whether the persisted session with this id runs under the arbor driver. */
+    ownsSession?(sessionId: SessionId): Promise<boolean>;
+}
+/** The agent registry with per-preset routing over an embedded AgentLoop. */
+export declare class ArborAgentRegistry extends AgentRegistry {
+    private embeddedFactory;
+    private arborFactory;
+    /**
+     * Capture the official loop's self-registration instead of claiming the
+     * base class's single factory slot. AgentLoop calls this from its
+     * `[Service.init]`; the returned disposer clears the capture on unload.
+     */
+    setFactory(factory: AgentFactory): () => void;
+    /** Register the arbor routing factory. Returns its disposer. */
+    useArborFactory(factory: ArborRoutingFactory): () => void;
+    /** The captured official AgentLoop, when one is mounted. */
+    get embedded(): AgentFactory | undefined;
+    create(options: CreateAgentOptions): Promise<AgentHandle>;
+    resume(options: ResumeAgentOptions): Promise<AgentHandle>;
+    private requireEmbedded;
+}
+export default ArborAgentRegistry;

package/registry.js

@@ -0,0 +1,95 @@
+/**
+ * The routing agent registry for arbor.
+ *
+ * DSH allows exactly one AgentFactory per process: `AgentRegistry.setFactory`
+ * throws `'an agent factory is already registered'` on a second call
+ * (packages/core/agent/src/index.ts, setFactory ~L383-399), and AgentLoop
+ * claims that single slot in its own `[Service.init]`
+ * (packages/core/agent-loop/src/index.ts L336). A bundle patch also cannot
+ * swap which package a row mounts — `applyPatches` treats a patch's `name` as
+ * a check only (vendor/include/src/patch.ts) — so the base `agent` row is
+ * disabled and this subclass is inserted in its place.
+ *
+ * The subclass keeps TWO factories:
+ *
+ *  - the official AgentLoop, captured when it registers itself through the
+ *    overridden `setFactory` (never passed to the base class, so the base
+ *    slot stays free and nothing throws); and
+ *  - the arbor driver, registered through {@link useArborFactory}.
+ *
+ * `create` routes on `meta.agentPreset === 'arbor'`; `resume` asks the arbor
+ * driver whether the persisted session is an arbor session and routes
+ * accordingly. Both paths delegate exactly the way the base class does
+ * (`getTraceable` + `Reflect.apply` through the caller-traced receiver), so
+ * the embedded loop keeps creating its agents into this same registry
+ * instance: ordinary DSH sessions keep working, including every consumer that
+ * reads `ctx.agents` (session-controller routing, UI liveness, the subagent
+ * tool).
+ */
+import { getTraceable, symbols } from '@deepseek-ai/cordis';
+import AgentRegistry from '@deepseek-ai/dsh-agent';
+/** The agent-preset value that routes a session to arbor. */
+export const ARBOR_PRESET = 'arbor';
+/** Delegate to one factory exactly the way `AgentRegistry.create/resume` do. */
+function delegate(ownerCtx, factory, method, options) {
+    const target = factory[symbols.original] ?? factory;
+    const receiver = getTraceable(ownerCtx, target);
+    return Reflect.apply(target[method], receiver, [ownerCtx, options]);
+}
+/** The agent registry with per-preset routing over an embedded AgentLoop. */
+export class ArborAgentRegistry extends AgentRegistry {
+    embeddedFactory;
+    arborFactory;
+    /**
+     * Capture the official loop's self-registration instead of claiming the
+     * base class's single factory slot. AgentLoop calls this from its
+     * `[Service.init]`; the returned disposer clears the capture on unload.
+     */
+    setFactory(factory) {
+        this.embeddedFactory = factory;
+        return () => {
+            if (this.embeddedFactory === factory)
+                this.embeddedFactory = undefined;
+        };
+    }
+    /** Register the arbor routing factory. Returns its disposer. */
+    useArborFactory(factory) {
+        this.arborFactory = factory;
+        return () => {
+            if (this.arborFactory === factory)
+                this.arborFactory = undefined;
+        };
+    }
+    /** The captured official AgentLoop, when one is mounted. */
+    get embedded() {
+        return this.embeddedFactory;
+    }
+    async create(options) {
+        // Every session is created through the arbor driver while it is mounted: the
+        // driver runs arbor sessions itself and keeps the embedded loop's handle for
+        // the others, which is what lets a preset selection re-route a session that
+        // has not started a turn (see ArborDriver's `agent-preset/selected` seam).
+        // Without the driver every session keeps running on the embedded loop, which
+        // is what a deployment that loads neither row gets.
+        const arbor = this.arborFactory;
+        if (arbor !== undefined)
+            return delegate(this.ctx, arbor, 'createAgent', options);
+        return delegate(this.ctx, this.requireEmbedded(), 'createAgent', options);
+    }
+    async resume(options) {
+        // The driver decides per session: it owns the persisted session when the log
+        // records arbor, and hands everything else to the embedded loop. Both paths
+        // keep their handle, for the same reason `create` does.
+        const arbor = this.arborFactory;
+        if (arbor !== undefined)
+            return delegate(this.ctx, arbor, 'resume', options);
+        return delegate(this.ctx, this.requireEmbedded(), 'resume', options);
+    }
+    requireEmbedded() {
+        if (this.embeddedFactory === undefined) {
+            throw new Error('no agent factory registered (load an agent-loop plugin)');
+        }
+        return this.embeddedFactory;
+    }
+}
+export default ArborAgentRegistry;

package/relay.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The relay: arbor's journal onto the DSH session log.
+ *
+ * A window's own record lives in the arbor journal, and the user-visible one
+ * lives in the DSH session log. The driver mirrors the second from the first:
+ * while a turn runs, every tool call is recorded in the journal before it runs
+ * and its result after, and DSH appends the matching `tool/call` +
+ * `tool/result` pair to the session log. A process that stops in between
+ * leaves the journal holding a call the log never saw.
+ *
+ * On resume the relay reads the session's window chain out of the journal and
+ * appends the `tool/call` events the log is missing, so DSH's own
+ * `interruptedTurnClosers` can then close them with an outcome-unknown result
+ * instead of a not-started one — the model is told the call may have had side
+ * effects, which is the truth.
+ *
+ * The cursor is the DSH session log itself: the journal's calls are matched,
+ * in order, against the calls the log's assistant messages asked for, and
+ * whatever the log already carries is left alone. There is no second cursor to
+ * keep in step, and nothing is replayed twice.
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { Journal, WindowRef } from '@4fu/arbor-interfaces';
+/** One tool call the arbor window recorded, read back from the journal. */
+export interface ArborToolCall {
+    /** The tool the window called. */
+    readonly name: string;
+    /** The arguments as the journal recorded them. */
+    readonly args: string;
+    /** Whether the window recorded this call's result as well. */
+    readonly settled: boolean;
+}
+/**
+ * The tool calls one window chain recorded, in journal order.
+ *
+ * The chain is every window of one session: the first, its continuations, and
+ * the one a restart opened for it. A `tool_result` names the `tool_call` it
+ * answers in its refs, which is how a call is known to be settled.
+ */
+export declare function windowToolCalls(journal: Journal, windows: readonly WindowRef[]): Promise<ArborToolCall[]>;
+/**
+ * The `tool/call` events the arbor journal recorded and this log lost.
+ *
+ * Arbor runs the calls it recorded, in order, so they are the prefix of the
+ * calls the log's assistant messages asked for; a mismatch stops the replay
+ * rather than guessing. Calls the log already answers, and calls an
+ * interrupted attempt left behind (which arbor never ran), are left out.
+ */
+export declare function relayToolCalls(log: readonly SessionEvent[], calls: readonly ArborToolCall[]): Extract<SessionEvent, {
+    type: 'tool/call';
+}>[];