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

package/driver.js

@@ -0,0 +1,885 @@
+/**
+ * The arbor driver: the AgentFactory that runs arbor-preset sessions, and the
+ * Cordis plugin row that mounts it.
+ *
+ * One DSH user session is one conversation target of the process's single Arbor
+ * host (`@4fu/dsh-arbor-host`): the journal, the note store and the board are
+ * shared by every session, and each session is one source of that one host.
+ * Arbor's own model is what a session's windows follow — a window ends when its
+ * run ends and the session's next turn opens the next window of its chain, so
+ * several windows serve one session and none of them is the session. Per
+ * session the driver owns
+ *
+ *  - the window, opened through `host.dispatch` on the session's first turn and
+ *    taken back — not reopened — when the session already has a live one, which
+ *    is what a restart's continuation is;
+ *  - the bridge the session agent drives: `ensureWindow`, `modelCall`,
+ *    `runToolCall` (arbor's tool path into `ctx.tools.execute`), `publish`,
+ *    `finishRun`, `close`; and
+ *  - the window's DSH agent registration, which keeps it out of the session
+ *    list (`meta.origin: 'subagent'`, owned by the session's agent).
+ *
+ * `resume` loads the persisted session, replays onto its log what the arbor
+ * journal recorded and the log lost, and binds the session back to the window
+ * the journal says is its own — the window the host continued at boot.
+ *
+ * The creation lifecycle mirrors `AgentLoop.createAgent`
+ * (packages/core/agent-loop/src/index.ts): prepare the session, take
+ * persistence ownership when a backend is mounted, run setup while the agent
+ * is unpublished, then enter and announce the session and the agent through
+ * the same registries the official loop uses.
+ *
+ * B1 scope, per the plan: compaction, goals, agentTeams, retry and fork are
+ * off for arbor sessions.
+ */
+import { randomUUID } from 'node:crypto';
+import { getTraceable, Service, symbols } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { modelSelectionProjectionDefinition } from '@deepseek-ai/dsh-agent';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { SessionPreparation, interruptedTurnClosers } from '@deepseek-ai/dsh-session';
+import { createToolResultMessage } from '@deepseek-ai/dsh-llm';
+import { sessionTarget } from '@4fu/dsh-arbor-host';
+import { replacedToolsRegistered } from '@4fu/dsh-arbor-tools';
+import { dataBlock } from '@4fu/arbor-prompt';
+import { ARBOR_PRESET, ArborAgentRegistry } from "./registry.js";
+import { ArborSessionAgent } from "./session-agent.js";
+import { inboxProjectionDefinition } from "./inbox.js";
+import { relayToolCalls, windowToolCalls } from "./relay.js";
+/** One session's arbor world: its window, its bridge, its window agent. */
+class SessionArbor {
+    window;
+    windowAgent;
+    bridgeCache;
+    /** The session's write handle onto its durable log, once persistence is mounted. */
+    stored;
+    agent;
+    /** The create/resume options a re-route replays, so a session keeps its own. */
+    agentOptions;
+    agentSetup;
+    driver;
+    constructor(driver, agent, agentOptions, agentSetup) {
+        this.driver = driver;
+        this.agent = agent;
+        this.agentOptions = agentOptions;
+        this.agentSetup = agentSetup;
+    }
+    /** Hand this world the session's write handle, once it has one. */
+    keepStored(stored) {
+        this.stored = stored;
+    }
+    /**
+     * End this session's arbor world: unbind its window, unwind the agent's own
+     * scope — which detaches the agent and its session and closes the bridge — and
+     * release the session's write handle so another driver can open the log.
+     *
+     * This is the teardown a re-route needs in either direction, and it is the
+     * mirror of the embedded loop's own `AgentHandle.dispose`: the window itself is
+     * the host's and lives out arbor's own idle policy, so only the binding goes.
+     */
+    async dispose() {
+        await this.agent.scope.dispose();
+        await this.stored?.handle.close().catch(() => { });
+        this.stored = undefined;
+    }
+    /** The one Arbor host of this process, and the backend every window runs through. */
+    get hostService() {
+        return this.driver.hostService;
+    }
+    /** The window this session's work runs in, once it has one. */
+    get windowRef() {
+        return this.window;
+    }
+    /** Whether the window this session holds is still the host's. */
+    isLive(window) {
+        if (window === undefined)
+            return false;
+        return this.hostService.host.live().some(record => record.window === window && record.state !== 'ended');
+    }
+    /** Open the window on first use, through arbor's dispatch. */
+    async ensureWindow(request) {
+        const held = this.window;
+        if (held !== undefined && this.isLive(held))
+            return held;
+        // A window this session already has is taken back, not answered by a second
+        // one: a restart continues the session's window under a new ref, and an
+        // earlier turn's window is still open while it waits out its idle period.
+        const existing = await this.hostService.windowFor(this.agent.session.id);
+        const window = existing ?? await this.dispatchWindow(request);
+        this.window = window;
+        this.hostService.backend.bind(window, this.agent);
+        await this.hostService.backend.whenOpen(window);
+        await this.registerWindowAgent(window);
+        return window;
+    }
+    /**
+     * The user's request, as the window's first board line.
+     *
+     * A window opens before the turn's input reaches the model, so the board's
+     * first title cannot come from the task alone. The user message is already
+     * on the session log when the task dispatches; use its text, one line and
+     * bounded, instead of the driver's internal placeholder. A window with no
+     * user text yet falls back to the same neutral description.
+     */
+    requestText() {
+        for (const event of this.agent.session.snapshotEvents().toReversed()) {
+            if (event.type !== 'user/message')
+                continue;
+            const content = event.data.content ?? [];
+            const text = content
+                .filter(block => block.type === 'text')
+                .map(block => block.text ?? '')
+                .join(' ')
+                .replace(/\s+/g, ' ')
+                .trim();
+            if (text !== '')
+                return text.length > 120 ? `${text.slice(0, 119)}…` : text;
+        }
+        return 'DeepSeek Harness session turn';
+    }
+    /** Dispatch this session's task, which opens the window that takes it. */
+    async dispatchWindow(request) {
+        const session = this.agent.session;
+        const reason = request === undefined ? this.requestText() : request.replace(/\s+/g, ' ').trim();
+        const task = {
+            kind: 'batch',
+            reason: reason.length > 120 ? `${reason.slice(0, 119)}…` : reason,
+            targets: [sessionTarget(session.id)],
+            // The label is what the host carries onto every window this task opens,
+            // its continuations and the journal's record of both. A read-only surface
+            // finds a session's windows by it, with no map of its own.
+            label: session.id,
+            time: Date.now(),
+            content: [dataBlock(`dsh session ${session.id}`)],
+            explicit: true,
+            source: 'dsh',
+        };
+        const result = await this.hostService.host.dispatch(task);
+        if (result.window === null) {
+            throw new Error(`arbor driver: dispatch opened no window for session "${session.id}" (route ${result.route})`);
+        }
+        return result.window;
+    }
+    /**
+     * Register the window as a DSH agent with `meta.origin: 'subagent'`, the
+     * convention `packages/subagent/subagent/src/child-agent.ts` uses for
+     * delegated children: the registry and the agent-team tools see the window,
+     * and the sidebar's `sessionVisible`
+     * (packages/client/ui-workspace/src/client/tree.ts) leaves it out. The agent
+     * is owned by this session's agent, so it is not a registry root.
+     */
+    async registerWindowAgent(window) {
+        if (this.windowAgent !== undefined)
+            return;
+        const sessionId = brandString(`window-${window}-${randomUUID()}`);
+        const { agent } = await this.driver.driverContext.agents.create({
+            sessionId,
+            parentAgent: this.agent,
+            meta: {
+                origin: 'subagent',
+                parentSession: this.agent.session.id,
+                // The window works in the arbor shared folder, so its hidden agent's cwd
+                // is that folder rather than the DSH process's own directory.
+                cwd: this.hostService.sharedFolder,
+            },
+            agentOptions: {},
+        });
+        this.windowAgent = agent;
+    }
+    /** The agent registered for this session's window, once one exists. */
+    get windowAgentOf() {
+        return this.windowAgent;
+    }
+    /** The bridge the session agent drives. */
+    bridge() {
+        this.bridgeCache ??= {
+            ensureWindow: request => this.ensureWindow(request),
+            systemPrompt: window => this.hostService.backend.systemPrompt(window),
+            modelCall: input => this.hostService.backend.modelCall({ ...input, agent: this.agent }),
+            runToolCall: async (call, position) => {
+                const window = await this.ensureWindow();
+                const control = this.hostService.host.windowControl();
+                const args = safeArgs(call.arguments);
+                const at = await control.recordToolCall(window, { name: call.name, args, callId: call.id });
+                // The call is mirrored onto the session log here, for every tool the
+                // window runs — arbor's own and DSH's alike. The log is the history the
+                // next model request is derived from, and a provider refuses a history
+                // whose assistant message asks for a tool call that has no result, so a
+                // window that runs only arbor's own tools still leaves a valid log.
+                // DSH's pipeline is not asked to log (the external tools carry no log
+                // position), which is what keeps this the one pair per call.
+                const callSeq = this.agent.session.append('tool/call', {
+                    ...position,
+                    callId: call.id,
+                    name: call.name,
+                    arguments: call.arguments,
+                }).seq;
+                const result = await control.runToolCall(window, { name: call.name, args, callId: call.id }, at ?? undefined);
+                this.agent.session.append('tool/result', {
+                    ...position,
+                    message: createToolResultMessage({
+                        callId: call.id,
+                        // Arbor 2026.1107.1 fills a refusal's wording into `content` as well
+                        // as into `error` — the rule, the message and the next action, in the
+                        // one form the journal records a refusal with — so the result is
+                        // written through as it stands. DSH's own tools put a denial's
+                        // reason in the content too, and without this the model would read
+                        // an empty tool result and never learn why a call was refused.
+                        content: [{ type: 'text', text: result.content }],
+                        isError: !result.ok,
+                    }),
+                    ...result.ok ? {} : { error: toolErrorOf(result) },
+                }, { surfaceOp: 'append', sourceEventSeqs: [callSeq] });
+                return result;
+            },
+            publish: (window, event) => { this.hostService.backend.publish(window, event); },
+            flushSends: () => { this.hostService.flushSends(); },
+            finishRun: window => { this.hostService.backend.finishRun(window); },
+            close: async () => {
+                // The window is the host's, not this session's: it stays open for the
+                // session's next turn and ends on arbor's own idle policy, exactly like
+                // a window whose model went quiet. Only the binding is dropped.
+                if (this.window !== undefined)
+                    this.hostService.backend.unbind(this.window);
+            },
+        };
+        return this.bridgeCache;
+    }
+}
+/** The arbor agent factory and Cordis plugin. */
+export class ArborDriver extends Service {
+    static inject = ['agents', 'sessions', 'sessionProjections', 'arborHost', 'tools', 'systemPrompt'];
+    static Config = z.object({});
+    config;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    runtime;
+    sessions = new Map();
+    /**
+     * Sessions the embedded AgentLoop is running, with the handle its creation
+     * returned. The driver created every one of them — the registry routes every
+     * session through this factory — so it holds the only thing that can end one:
+     * that is what lets a preset selection re-route a session that has not started
+     * a turn. An ordinary session is never touched unless its user picks arbor.
+     */
+    embedded = new Map();
+    modelProjectionHandle;
+    inboxProjectionHandle;
+    constructor(ctx, config = {}) {
+        super(ctx, 'arborDriver');
+        this.config = config;
+        this.runtime = { ctx };
+    }
+    async [Service.init]() {
+        const ctx = this.runtime.ctx;
+        // Refcounted alongside the embedded AgentLoop's own registrations of the
+        // same keys (SessionProjectionRegistry.register shares one definition per
+        // key), so an arbor agent reads its projections with or without the
+        // official loop mounted.
+        this.modelProjectionHandle = await ctx.sessionProjections.register(modelSelectionProjectionDefinition);
+        this.inboxProjectionHandle = await ctx.sessionProjections.register(inboxProjectionDefinition);
+        ctx.effect(() => ctx.agents.useArborFactory(this), 'arborDriver.useArborFactory()');
+        // The seam that makes picking Arbor in a composer actually run arbor. DSH's
+        // own preset registry commits a blank session's pick by appending
+        // `agent-preset/selected` and re-mounting the session's composition, which is
+        // all a preset whose presets share one driver needs; a preset that changes the
+        // driver has to act on the same event. The log event is observed rather than
+        // the registry's own `agent-preset/selected` emit, because that one is
+        // dispatched on the registry's context and reaches nobody outside it, while
+        // `session/event` is the session-scoped observer channel every host row can
+        // listen on. A session that has started a turn never gets here — the registry
+        // refuses that selection before it is committed — so the only case is a
+        // session still waiting for its first turn, which is exactly the hero.
+        // The event carries the OTHER direction too, and it has to be honoured for a
+        // session that SELECTED arbor: DSH's session controller re-selects the
+        // default preset whenever a blank session is reused (`reuseLive` calls
+        // `presets.select` with the resolved default, and `reuseSetup` appends the
+        // event itself), so a session the user opened in another workspace is
+        // relabelled `standard` while it still runs arbor. Following the event back
+        // is what keeps the label and the driver saying the same thing. A session
+        // CREATED under arbor is the exception, and the gate is in
+        // {@link rerouteToEmbedded}: that session is never switched in place by any
+        // surface that knows what the user clicked, so the only selection that can
+        // reach it is the controller's default.
+        ctx.on('session/event', (session, event) => {
+            if (event.type !== 'agent-preset/selected')
+                return;
+            const selected = event.data.agentPreset;
+            if (selected === ARBOR_PRESET) {
+                void this.rerouteToArbor(session.id).catch((error) => {
+                    this.runtime.ctx.logger.warn(`arbor driver: re-routing session ${session.id} to arbor failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+                return;
+            }
+            void this.rerouteToEmbedded(session.id, typeof selected === 'string' ? selected : undefined).catch((error) => {
+                this.runtime.ctx.logger.warn(`arbor driver: re-routing session ${session.id} off arbor failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        });
+    }
+    /**
+     * Re-route one session from the embedded AgentLoop to arbor.
+     *
+     * The loop's agent is ended with the handle its creation returned — which
+     * unregisters the agent and detaches the session from the store, leaving the
+     * durable log exactly as it stands — and the session is then opened again
+     * under arbor, the way a restart opens it. The session keeps its identity, its
+     * log and every event it already committed, so the composer that is bound to
+     * it keeps working; what changes is which driver its next turn runs.
+     */
+    async rerouteToArbor(sessionId) {
+        const hold = this.embedded.get(sessionId);
+        if (hold === undefined)
+            return;
+        this.embedded.delete(sessionId);
+        // A session that has started a turn keeps the driver it began with. DSH's
+        // preset registry refuses such a selection before it is committed, so this
+        // is a guard rather than a path; it is here because the alternative —
+        // silently keeping the old driver — is the one thing the owner ruled out.
+        const boundary = this.runtime.ctx.agents.turnBoundaryOf(hold.handle.agent.session);
+        if (boundary.openTurnStartSeq !== null || boundary.lastTurn > 0) {
+            this.runtime.ctx.logger.warn(`arbor driver: session ${sessionId} selected arbor after its first turn and keeps the embedded loop`);
+            return;
+        }
+        // The re-routed session keeps the cwd it was created with — the directory the
+        // user picked for it in DSH's own project picker — and arbor works in the
+        // shared folder, so the picked directory is what the pointer names. It is
+        // read before the embedded agent is ended, and recorded once, at the moment
+        // the session becomes an arbor session: that is the ask, and it is not
+        // repeated on a later resume.
+        const requested = hold.handle.agent.session.header.cwd;
+        const cwd = await this.hostService.resolveArborCwd(requested);
+        await hold.handle.dispose();
+        await this.resumeArbor(this.runtime.ctx, {
+            resumeSessionId: sessionId,
+            agentOptions: hold.agentOptions,
+            setup: hold.setup,
+            cwd,
+        });
+        this.noteExternalProject(requested, sessionId);
+        // The session kept its identity and its log, but its cwd is now arbor's own
+        // directory, so it moves to the workspace that owns that directory: DSH
+        // filters a workspace's members by the session's stored cwd, and a session
+        // left in the workspace it was created in reads as a member of nowhere —
+        // which is what leaves the hero composer with no workspace to name.
+        await this.hostService.attachArborWorkspace(sessionId, cwd);
+    }
+    /**
+     * Record a directory an arbor session named as an external pointer for that
+     * session, when the user had added the directory through DSH's own
+     * add-workspace action.
+     *
+     * The host answers whether the directory was added, because that is a fact
+     * about the project list rather than about this session; a directory that was
+     * never added — a cwd the session inherited — is left alone, which is the
+     * mistake the earlier resolve-time recording made.
+     */
+    noteExternalProject(requested, sessionId) {
+        if (requested === undefined)
+            return;
+        try {
+            if (this.hostService.isAddedArborDirectory(requested)) {
+                this.hostService.pointerArborProject(requested, sessionId);
+            }
+        }
+        catch (error) {
+            this.runtime.ctx.logger.warn(`arbor driver: recording an external pointer for session ${sessionId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Re-route one session from arbor back to the embedded AgentLoop.
+     *
+     * The mirror of {@link rerouteToArbor}, and it exists for one case only: a
+     * session that SELECTED arbor while it was blank can select something else
+     * again while it is still blank, and the label and the driver under it must
+     * say the same thing. That is the SDK or remote `agent-preset/select` path —
+     * every surface that knows what the user clicked creates the session under
+     * the picked preset instead (the hero mint, the adopt at create), so nothing
+     * in the web profile switches a blank in place. The arbor agent is ended with
+     * the handle this driver holds, the window keeps running out arbor's own idle
+     * policy, and the session is opened again on the embedded loop with the same
+     * id, the same log and the same cwd it was created with.
+     *
+     * **A session created under arbor is never moved off it here.** Its creation
+     * header says `agentPreset: 'arbor'`, which is a frozen creation fact
+     * (`@deepseek-ai/dsh-agent-preset-registry`, `lib/types/session.js`), and the
+     * one selection that can still arrive on it is DSH's own: the session
+     * controller re-selects the resolved deployment default whenever a blank is
+     * reused with no preset named — `reuseLive` calls `presets.select` with
+     * `composition.agentPreset` and `reuseSetup` appends the event itself
+     * (`@deepseek-ai/dsh-api-session-controller`, `lib/index.js`). The log cannot
+     * tell that re-select from a user's pick, because `presets.select` is the
+     * single writer of `agent-preset/selected` (`lib/index.js`), so the
+     * attribution has to come from the header instead: a session created as arbor
+     * keeps arbor, and its label is put back through the registry's own select so
+     * the projection and the driver agree ({@link reassertArbor}). The client side
+     * of the same guarantee is that the restore names the recorded preset, so the
+     * re-select is never written in the first place — this gate is what stands
+     * behind it.
+     *
+     * A session that has started a turn keeps the driver it began with: DSH refuses
+     * that selection before it is committed, so this is the same defensive guard the
+     * arbor direction carries, and the alternative — silently keeping the old driver
+     * — is the one outcome the owner ruled out.
+     */
+    async rerouteToEmbedded(sessionId, selected) {
+        const arbor = this.sessions.get(sessionId);
+        if (arbor === undefined)
+            return;
+        if (arbor.agent.session.header.agentPreset === ARBOR_PRESET) {
+            this.runtime.ctx.logger.warn(`arbor driver: session ${sessionId} was created under arbor and keeps it; `
+                + `a selection of ${selected ?? '(unnamed)'} is not followed off a creation header`);
+            await this.reassertArbor(arbor);
+            return;
+        }
+        this.sessions.delete(sessionId);
+        const boundary = this.runtime.ctx.agents.turnBoundaryOf(arbor.agent.session);
+        if (boundary.openTurnStartSeq !== null || boundary.lastTurn > 0) {
+            this.runtime.ctx.logger.warn(`arbor driver: session ${sessionId} selected another preset after its first turn and keeps arbor`);
+            return;
+        }
+        const options = {
+            resumeSessionId: sessionId,
+            agentOptions: arbor.agentOptions,
+            setup: arbor.agentSetup,
+        };
+        await arbor.dispose();
+        await this.resumeEmbedded(this.runtime.ctx, options);
+    }
+    /**
+     * Put a session's label back on arbor, through the registry's own select.
+     *
+     * The selection being refused has already been appended to the log, so the
+     * session's `agentPreset` projection now names another preset while this
+     * driver still runs arbor — a label that says one thing while the driver does
+     * another, which is the untruth the gate exists to prevent. `presets.select`
+     * is the single writer of that event (`@deepseek-ai/dsh-agent-preset-registry`,
+     * `lib/index.js`), and it appends only when the projection does not already
+     * name the preset, so this writes one honest event and nothing else: the
+     * registry's `bind` is a no-op when the agent's context already holds the
+     * preset's generation. The event reaches this driver's own observer, which
+     * finds the session already running arbor and does nothing.
+     */
+    async reassertArbor(arbor) {
+        const presets = this.runtime.ctx.get('agentPresets');
+        if (presets === undefined)
+            return;
+        try {
+            await presets.select(arbor.agent, ARBOR_PRESET);
+        }
+        catch (error) {
+            this.runtime.ctx.logger.warn(`arbor driver: re-asserting arbor on session ${arbor.agent.session.id} failed: `
+                + `${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** The driver's own DSH context, for the per-session arbor worlds. */
+    get driverContext() {
+        return this.runtime.ctx;
+    }
+    /** The one Arbor host of this process. */
+    get hostService() {
+        const host = this.runtime.ctx.get('arborHost');
+        if (host === undefined) {
+            throw new Error('arbor driver: no arborHost service (load @4fu/dsh-arbor-host)');
+        }
+        return host;
+    }
+    /** The per-session arbor world, for tests and diagnostics. */
+    sessionArbor(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /** The agent registered for a session's arbor window, once one exists. */
+    windowAgentOf(sessionId) {
+        return this.sessions.get(sessionId)?.windowAgentOf;
+    }
+    /** The system prompt the session's arbor window rendered, once it opened. */
+    systemPromptOf(sessionId) {
+        const window = this.sessions.get(sessionId)?.windowRef;
+        return window === undefined ? undefined : this.hostService.backend.systemPrompt(window);
+    }
+    /**
+     * Whether a persisted session runs under arbor.
+     *
+     * The creation header names the preset a session STARTED with and is frozen
+     * because it is a creation fact; a session may still select another while it
+     * is blank, and DSH's own reconstruction rule for exactly this reason reads
+     * the `agentPreset` projection, "never the header alone"
+     * (`@deepseek-ai/dsh-agent-preset-registry`, `lib/types/session.js`). So the
+     * log's `agent-preset/selected` events are folded over the header's value:
+     * that is what makes a re-routed session come back as arbor after a restart
+     * instead of silently resuming on the embedded loop.
+     */
+    async ownsSession(sessionId) {
+        const persistence = this.runtime.ctx.get('sessionPersistence');
+        if (persistence === undefined)
+            return false;
+        try {
+            const handle = await persistence.open(sessionId, 'read');
+            try {
+                let preset = handle.header.agentPreset;
+                const page = await handle.read(0);
+                // The event type is declared by the preset registry's module
+                // augmentation; read it structurally so building this package alone does
+                // not depend on that augmentation being in the program.
+                const events = page.events;
+                for (const event of events) {
+                    if (event.type !== 'agent-preset/selected')
+                        continue;
+                    const selected = event.data.agentPreset;
+                    if (typeof selected === 'string')
+                        preset = selected;
+                }
+                return preset === ARBOR_PRESET;
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    async createAgent(ownerCtx, options) {
+        // A session created under the arbor preset runs arbor; every other session
+        // runs the embedded AgentLoop. The registry routes both here, because the
+        // driver has to hold the embedded handle to be able to re-route a session
+        // whose user picks arbor before its first turn.
+        if (options.meta?.agentPreset === ARBOR_PRESET)
+            return this.createArborAgent(ownerCtx, options);
+        const hold = await this.createEmbedded(ownerCtx, options);
+        return {
+            agent: hold.handle.agent,
+            dispose: async () => {
+                this.embedded.delete(hold.handle.agent.id);
+                await hold.handle.dispose();
+            },
+        };
+    }
+    /** Create the agent of a session that runs arbor. */
+    async createArborAgent(ownerCtx, options) {
+        // An arbor session is not bound to the caller's directory: it works in the
+        // arbor shared folder, and a requested directory outside it joins the shared
+        // folder only through explicit adoption (see @4fu/dsh-arbor-workspace). The
+        // session's cwd is therefore resolved into the shared folder before the
+        // session is prepared, so the DSH session, its cwd display and the project
+        // picker all name a folder that is really there.
+        const requested = options.meta?.cwd;
+        const cwd = await this.hostService.resolveArborCwd(requested);
+        const meta = options.meta === undefined
+            ? { cwd }
+            : { ...options.meta, cwd };
+        const preparation = SessionPreparation.create(this.runtime.ctx.sessions.prepare(options.sessionId, {
+            ...options.seed === undefined ? {} : { seed: options.seed },
+            meta,
+            ...options.inheritedEventCount === undefined ? {} : { inheritedEventCount: options.inheritedEventCount },
+        }));
+        const id = preparation.session.id;
+        // A directory the user added through DSH's own add-workspace action, named by
+        // a session that is starting under arbor, is a pointer for that session: the
+        // user chose the directory for this session, and arbor's prompt names it so
+        // the model can work in the user's own files. A cwd the session merely
+        // inherited is not, which is why the question is asked of the host rather
+        // than assumed here.
+        this.noteExternalProject(requested, id);
+        const agent = this.agentFor(preparation.session, options.agentOptions);
+        const arbor = new SessionArbor(this, agent, options.agentOptions, options.setup);
+        agent.attachBridge(arbor.bridge());
+        this.sessions.set(id, arbor);
+        let stored;
+        try {
+            ownerCtx.fiber.assertActive();
+            stored = await this.createStoredSession(preparation.session, options.signal);
+            arbor.keepStored(stored);
+            await this.publish(ownerCtx, arbor, agent, preparation.session, stored, options.setup, 'startup', options.parentAgent, options.signal);
+        }
+        catch (error) {
+            this.sessions.delete(id);
+            await arbor.bridge().close();
+            await stored?.handle.close().catch(() => { });
+            throw error;
+        }
+        finally {
+            preparation[Symbol.dispose]();
+        }
+        // The session is stored and published, so its header is readable: it now
+        // belongs to the workspace that owns the directory it works in, which is
+        // what keeps DSH's hero composer live for it.
+        await this.hostService.attachArborWorkspace(id, cwd);
+        return {
+            agent,
+            dispose: async () => {
+                this.sessions.delete(id);
+                await arbor.dispose();
+            },
+        };
+    }
+    /**
+     * Create an agent for a session the embedded AgentLoop will run.
+     *
+     * The embedded factory is delegated to exactly the way the base
+     * `AgentRegistry` delegates, so an ordinary session's agent, its ownership and
+     * its teardown are the official loop's own. The one difference is that this
+     * driver keeps the handle: a session whose user later picks arbor is re-routed
+     * by ending the loop's agent and opening the session's arbor window, and
+     * ending an agent needs the handle its creation returned.
+     */
+    async createEmbedded(ownerCtx, options) {
+        const registry = this.runtime.ctx.agents;
+        const factory = registry.embedded;
+        if (factory === undefined) {
+            throw new Error('no agent factory registered (load an agent-loop plugin)');
+        }
+        const handle = await delegateFactory(ownerCtx, factory, 'createAgent', options);
+        const hold = {
+            handle,
+            agentOptions: options.agentOptions,
+            setup: options.setup,
+        };
+        this.embedded.set(handle.agent.id, hold);
+        return hold;
+    }
+    /** Resume an agent for a session the embedded AgentLoop will run. */
+    async resumeEmbedded(ownerCtx, options) {
+        const registry = this.runtime.ctx.agents;
+        const factory = registry.embedded;
+        if (factory === undefined) {
+            throw new Error('no agent factory registered (load an agent-loop plugin)');
+        }
+        const handle = await delegateFactory(ownerCtx, factory, 'resume', options);
+        const hold = { handle, agentOptions: options.agentOptions, setup: options.setup };
+        this.embedded.set(handle.agent.id, hold);
+        return hold;
+    }
+    /**
+     * Resume a persisted arbor session.
+     *
+     * The session's log is loaded the way the official loop loads it, with two
+     * arbor-specific steps around it: the window chain the journal holds is read
+     * back and the `tool/call` events the log lost are replayed onto it, so DSH's
+     * own `interruptedTurnClosers` closes them as outcome-unknown rather than
+     * not-started; and the session is bound to the window the host continued at
+     * boot, so its next turn drives that window instead of opening a new chain.
+     */
+    async resume(ownerCtx, options) {
+        // A persisted session runs arbor when its log says so — the creation header
+        // names the preset it started with and a blank session may still have
+        // selected another, which is why the log is folded rather than the header
+        // read. Everything else runs the embedded AgentLoop, with its handle kept
+        // for the same reason `createAgent` keeps one.
+        if (await this.ownsSession(options.resumeSessionId)) {
+            // A restart resolves the stored cwd the way a creation resolves a requested
+            // one, so the session comes back naming the shared folder or the project
+            // the user pointed it at — never the directory it happened to be created
+            // in before it selected arbor.
+            const persistence = this.runtime.ctx.get('sessionPersistence');
+            const stored = persistence === undefined ? undefined : await this.storedCwd(persistence, options.resumeSessionId);
+            return this.resumeArbor(ownerCtx, {
+                ...options,
+                cwd: await this.hostService.resolveArborCwd(stored),
+            });
+        }
+        const hold = await this.resumeEmbedded(ownerCtx, options);
+        return {
+            agent: hold.handle.agent,
+            dispose: async () => {
+                this.embedded.delete(hold.handle.agent.id);
+                await hold.handle.dispose();
+            },
+        };
+    }
+    /**
+     * The cwd a persisted session was created with, read without taking its write
+     * ownership: the resume path needs it to resolve the session's cwd before it
+     * opens the log for writing.
+     */
+    async storedCwd(persistence, sessionId) {
+        try {
+            const handle = await persistence.open(sessionId, 'read');
+            try {
+                return handle.header.cwd;
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Resume a persisted session that runs arbor. */
+    async resumeArbor(ownerCtx, options) {
+        const ctx = this.runtime.ctx;
+        const persistence = ctx.get('sessionPersistence');
+        if (persistence === undefined) {
+            throw new Error('cannot resume: session persistence is not configured (load a dsh-session-persistence backend)');
+        }
+        const id = options.resumeSessionId;
+        // The directory this session works in, read from its stored header before
+        // the log is opened for writing: the resume resolves it the same way a
+        // creation does, and the workspace attach below names it.
+        let open;
+        let preparation;
+        let stored;
+        let agent;
+        let arbor;
+        let cwd = options.cwd;
+        try {
+            open = await persistence.open(id, 'write', {
+                ...options.signal === undefined ? {} : { signal: options.signal },
+            });
+            cwd ??= open.header.cwd;
+            const coldRead = await open.read(0);
+            const windows = await this.hostService.windowChainOf(id);
+            const recorded = await windowToolCalls(this.hostService.journal, windows);
+            const relayed = relayToolCalls(coldRead.events, recorded);
+            if (relayed.length > 0)
+                await open.append(relayed);
+            const closers = interruptedTurnClosers([...coldRead.events, ...relayed]);
+            if (closers.length > 0)
+                await open.append(closers);
+            const seed = [...coldRead.events, ...relayed, ...closers];
+            preparation = SessionPreparation.create(ctx.sessions.prepare(id, {
+                seed,
+                // The cwd a persisted session resumes with is resolved into the shared
+                // folder exactly as a creation resolves it, so a session created under
+                // arbor, one re-routed onto it and one resumed after a restart all name
+                // the same directory: the shared folder, or the project subfolder the
+                // user pointed the session at. The stored header keeps what creation
+                // wrote; the live session is what the model, the cwd display and the
+                // project line all read.
+                meta: { ...structuredClone(open.header), cwd: options.cwd ?? open.header.cwd },
+                inheritedEventCount: open.inheritedEventCount,
+                eventState: coldRead.eventState,
+            }));
+            stored = { handle: open, storedCount: seed.length };
+            open = undefined;
+            await this.appendUnstoredSuffix(stored, preparation.session);
+            agent = this.agentFor(preparation.session, options.agentOptions);
+            arbor = new SessionArbor(this, agent, options.agentOptions, options.setup);
+            agent.attachBridge(arbor.bridge());
+            this.sessions.set(id, arbor);
+            arbor.keepStored(stored);
+            await this.publish(ownerCtx, arbor, agent, preparation.session, stored, options.setup, 'resume', options.parentAgent, options.signal);
+        }
+        catch (error) {
+            if (agent !== undefined)
+                this.sessions.delete(id);
+            await arbor?.bridge().close();
+            await stored?.handle.close().catch(() => { });
+            throw error;
+        }
+        finally {
+            preparation?.[Symbol.dispose]();
+            await open?.close().catch(() => { });
+        }
+        // The session is back and its log is open for writing, so its header is
+        // readable: it belongs to the workspace that owns the directory it works in,
+        // the same one it belonged to before the restart.
+        if (cwd !== undefined)
+            await this.hostService.attachArborWorkspace(id, cwd);
+        const live = { agent, arbor };
+        return {
+            agent: live.agent,
+            dispose: async () => {
+                this.sessions.delete(id);
+                await live.arbor?.dispose();
+            },
+        };
+    }
+    /** Build the session agent for one prepared session, create or resume. */
+    agentFor(session, options) {
+        return new ArborSessionAgent(this.runtime.ctx, session.id, options ?? {}, session, {
+            modelSelection: this.modelProjectionHandle.readerFor(session),
+            inbox: this.inboxProjectionHandle.readerFor(session),
+        }, this.runtime.ctx.agents.turnBoundaryOf(session).lastTurn);
+    }
+    /** Take a fresh session's write ownership when persistence is mounted. */
+    async createStoredSession(session, signal) {
+        const persistence = this.runtime.ctx.get('sessionPersistence');
+        if (persistence === undefined)
+            return undefined;
+        const handle = await persistence.create(session.header, {
+            inheritedEventCount: session.inheritedEventCount,
+            ...signal === undefined ? {} : { signal },
+        });
+        return { handle, storedCount: 0 };
+    }
+    /** Durably store the session events appended since the last stored cursor. */
+    async appendUnstoredSuffix(stored, session) {
+        if (stored === undefined)
+            return;
+        const suffix = session.snapshotEvents(stored.storedCount);
+        if (suffix.length > 0)
+            await stored.handle.append(suffix);
+        stored.storedCount += suffix.length;
+    }
+    /** Enter and announce the session and the agent, exactly like AgentLoop does. */
+    async publish(ownerCtx, arbor, agent, session, stored, setup, source, parentAgent, signal) {
+        const loopCtx = this.runtime.ctx;
+        await agent.runMaintenance(async () => {
+            if (stored !== undefined) {
+                const suffix = session.snapshotEvents(stored.storedCount);
+                if (suffix.length > 0)
+                    await stored.handle.append(suffix);
+                stored.storedCount += suffix.length;
+            }
+            const detachSession = agent.ctx.sessions.enter(session);
+            agent.ctx.sessions.announce(session);
+            // Every capability appears once: the DSH tools arbor's own replaces are
+            // denied in this session's scope, so DSH's own pipeline refuses them and
+            // their `tool:*` prompt sections render empty. The same list keeps them
+            // out of what the backend hands arbor's catalog
+            // (`@4fu/dsh-arbor-tools` DSH_TOOLS_ARBOR_REPLACES). The restriction is
+            // scoped to this agent — `tools.restrict` refuses a global one — and is
+            // disposed with the agent's own context.
+            const liftRestriction = agent.ctx.tools.restrict({
+                deny: replacedToolsRegistered(loopCtx.tools),
+            });
+            const commit = await setup?.(agent.ctx, agent);
+            commit?.commit();
+            // A `tool:*` section's text reads whether its tool is registered, and the
+            // restriction moves that without a registration change, so the prompt
+            // bridge is told the prompt moved.
+            this.hostService.noteDshPromptChange();
+            const detachAgent = loopCtx.agents.enter(agent, parentAgent);
+            await loopCtx.agents.announce(agent, source, signal);
+            agent.ctx.effect(function* () {
+                yield () => {
+                    detachAgent();
+                    detachSession();
+                };
+                yield async () => { await arbor.bridge().close(); };
+            }, 'arborDriver.detach()');
+            agent.ctx.effect(() => liftRestriction, 'arborDriver.restrictTools()');
+        });
+    }
+}
+/**
+ * Delegate to one factory exactly the way the base `AgentRegistry` does, so an
+ * embedded-loop session's agent, ownership and teardown stay the official loop's
+ * own even though this driver is the one calling it.
+ */
+function delegateFactory(ownerCtx, factory, method, options) {
+    const target = factory[symbols.original] ?? factory;
+    const receiver = getTraceable(ownerCtx, target);
+    return Reflect.apply(target[method], receiver, [ownerCtx, options]);
+}
+/** Parse a model-produced arguments string; invalid JSON becomes an empty object. */
+function safeArgs(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** One refused tool call as the session log's error shape. */
+function toolErrorOf(result) {
+    return {
+        name: result.error?.rule ?? 'ToolCallFailed',
+        code: 'TOOL_CALL_FAILED',
+        ...result.error === undefined ? {} : { reason: result.error.message },
+    };
+}
+export default ArborDriver;