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

package/relay.js

@@ -0,0 +1,144 @@
+/**
+ * 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 { isDeepStrictEqual } from 'node:util';
+import { SessionSeq } from '@deepseek-ai/dsh-session';
+import { MAX_PAGE_LIMIT } from '@4fu/arbor-interfaces';
+/** Split a journal `tool_call` body (`name {args}`) into its two parts. */
+function splitCall(body) {
+    const at = body.indexOf(' ');
+    if (at <= 0)
+        return undefined;
+    return { name: body.slice(0, at), args: body.slice(at + 1) };
+}
+/** Whether two argument strings carry the same JSON value. */
+function sameArgs(left, right) {
+    try {
+        return isDeepStrictEqual(JSON.parse(left), JSON.parse(right));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 async function windowToolCalls(journal, windows) {
+    const chain = new Set(windows);
+    const calls = [];
+    const index = new Map();
+    for (let offset = 0;; offset += MAX_PAGE_LIMIT) {
+        const page = await journal.list({ kinds: ['tool_call', 'tool_result'], limit: MAX_PAGE_LIMIT, offset });
+        for (const event of page.items) {
+            if (event.window === null || !chain.has(event.window))
+                continue;
+            if (event.kind === 'tool_call') {
+                const split = splitCall(event.body ?? '');
+                if (split === undefined)
+                    continue;
+                index.set(event.ref, calls.length);
+                calls.push({ ...split, settled: false });
+                continue;
+            }
+            const answered = event.refs[0];
+            if (answered === undefined)
+                continue;
+            const at = index.get(answered);
+            if (at !== undefined)
+                calls[at] = { ...calls[at], settled: true };
+        }
+        if (page.items.length < MAX_PAGE_LIMIT)
+            break;
+    }
+    return calls;
+}
+/**
+ * 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 function relayToolCalls(log, calls) {
+    const asked = [];
+    const answered = new Set();
+    const started = new Set();
+    for (const event of log) {
+        switch (event.type) {
+            case 'assistant/message':
+                // An interrupted attempt's blocks were never run, so they are not part
+                // of the order arbor's calls follow.
+                if (event.data.interrupted === true)
+                    break;
+                for (const block of event.data.message.content) {
+                    if (block.type !== 'tool-call')
+                        continue;
+                    asked.push({
+                        callId: block.id,
+                        name: block.name,
+                        arguments: block.arguments,
+                        turn: event.data.turn,
+                        step: event.data.step,
+                    });
+                }
+                break;
+            case 'tool/call':
+                started.add(event.data.callId);
+                break;
+            case 'tool/result':
+                answered.add(event.data.message.toolCallId);
+                break;
+            default:
+                break;
+        }
+    }
+    const last = log.at(-1);
+    const relayed = [];
+    let seq = last?.seq ?? 0;
+    const time = last?.time ?? Date.now();
+    for (const [position, call] of calls.entries()) {
+        const wanted = asked[position];
+        if (wanted === undefined)
+            break;
+        if (wanted.name !== call.name || !sameArgs(wanted.arguments, call.args))
+            break;
+        // A call the log answers is complete, and one it has already recorded as
+        // started needs only the result DSH's own repair supplies: replaying
+        // either would duplicate an event the log already holds.
+        if (answered.has(wanted.callId) || started.has(wanted.callId))
+            continue;
+        const data = {
+            turn: wanted.turn,
+            step: wanted.step,
+            callId: wanted.callId,
+            name: wanted.name,
+            arguments: wanted.arguments,
+        };
+        seq += 1;
+        relayed.push({ type: 'tool/call', seq: SessionSeq(seq), time, data });
+    }
+    return relayed;
+}

package/runtime-context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The per-session runtime-context snapshot.
+ *
+ * Arbor's system prompt is frozen per epoch and shared by every window of that
+ * epoch, so a fact that belongs to one session cannot be written into a section:
+ * a section would tell every other session in the epoch the wrong value. The
+ * official loop solves the same problem with a snapshot message it appends at
+ * every step and replaces when it changes
+ * (`@deepseek-ai/dsh-agent-loop` RuntimeContextProjection), and this is that
+ * projection for the arbor path: the same source kind, the same "none" line,
+ * and the same rule that a message which is not exactly one text block is never
+ * treated as a retained snapshot, so a snapshot a window received before a
+ * restart is recognised as one on replay.
+ *
+ * What it carries is deliberately narrow — see
+ * {@link snapshotContextNames} in `@4fu/dsh-arbor-prompt`. Only a third party's
+ * runtime context travels here, because nothing else can carry per-session
+ * state from outside the framework. The approval policy and plan mode are
+ * written into the `<harness>` section instead, in dsh-arbor's own wording, and
+ * reach a running window as a `prompt_delta` carrying only the changed lines;
+ * the paths are arbor's own `<workspace>` section's.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'runtime-context': {
+            kind: 'runtime-context';
+        } & ContextFormed;
+    }
+}
+/** Tracks the last retained runtime-context snapshot without owning its commit. */
+export declare class RuntimeContextProjection {
+    /** `undefined` means no snapshot ever existed; `null` means none is retained. */
+    private retained;
+    /**
+     * Restore projection state once, then follow authoritative session events.
+     * @param ctx - agent-scoped event context
+     * @param session - session receiving projected messages
+     */
+    constructor(ctx: Context, session: Session);
+    /**
+     * Create an uncommitted snapshot only when the retained value differs.
+     * @param current - fully rendered dynamic context
+     * @returns a candidate user message, or `undefined` when no update is needed
+     */
+    project(current: string): UserMessage | undefined;
+}

package/runtime-context.js

@@ -0,0 +1,86 @@
+/**
+ * The per-session runtime-context snapshot.
+ *
+ * Arbor's system prompt is frozen per epoch and shared by every window of that
+ * epoch, so a fact that belongs to one session cannot be written into a section:
+ * a section would tell every other session in the epoch the wrong value. The
+ * official loop solves the same problem with a snapshot message it appends at
+ * every step and replaces when it changes
+ * (`@deepseek-ai/dsh-agent-loop` RuntimeContextProjection), and this is that
+ * projection for the arbor path: the same source kind, the same "none" line,
+ * and the same rule that a message which is not exactly one text block is never
+ * treated as a retained snapshot, so a snapshot a window received before a
+ * restart is recognised as one on replay.
+ *
+ * What it carries is deliberately narrow — see
+ * {@link snapshotContextNames} in `@4fu/dsh-arbor-prompt`. Only a third party's
+ * runtime context travels here, because nothing else can carry per-session
+ * state from outside the framework. The approval policy and plan mode are
+ * written into the `<harness>` section instead, in dsh-arbor's own wording, and
+ * reach a running window as a `prompt_delta` carrying only the changed lines;
+ * the paths are arbor's own `<workspace>` section's.
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/** The fixed text an empty snapshot carries, so a cleared one supersedes too. */
+const CLEARED = 'Current runtime context: none. Earlier runtime-context snapshots no longer apply.';
+/** Whether one message is a snapshot this projection owns. */
+function isOwned(message) {
+    return message.source.kind === 'runtime-context';
+}
+/** The text of a message that is exactly one text block, else `undefined`. */
+function textOf(message) {
+    const [block] = message.content;
+    return message.content.length === 1 && block?.type === 'text' ? block.text : undefined;
+}
+/** Whether one event replaces a surface node the retained snapshot lives in. */
+function isReplacementSurfaceEvent(event) {
+    return event.type === 'system/message' || event.type === 'user/message';
+}
+/** Tracks the last retained runtime-context snapshot without owning its commit. */
+export class RuntimeContextProjection {
+    /** `undefined` means no snapshot ever existed; `null` means none is retained. */
+    retained;
+    /**
+     * Restore projection state once, then follow authoritative session events.
+     * @param ctx - agent-scoped event context
+     * @param session - session receiving projected messages
+     */
+    constructor(ctx, session) {
+        const surface = new Set(session.surface.nodes);
+        for (const event of session.snapshotEvents().toReversed()) {
+            if (event.type !== 'user/message' || !isOwned(event.data))
+                continue;
+            this.retained ??= null;
+            if (surface.has(event.seq)) {
+                this.retained = { seq: event.seq, text: textOf(event.data) ?? '' };
+                break;
+            }
+        }
+        ctx.on('session/event', (subject, event) => {
+            if (subject !== session)
+                return;
+            if (event.type === 'user/message' && isOwned(event.data)) {
+                this.retained = { seq: event.seq, text: textOf(event.data) ?? '' };
+            }
+            else if (this.retained && isReplacementSurfaceEvent(event) && event.sourceEventSeqs?.includes(this.retained.seq) === true) {
+                this.retained = null;
+            }
+        });
+    }
+    /**
+     * Create an uncommitted snapshot only when the retained value differs.
+     * @param current - fully rendered dynamic context
+     * @returns a candidate user message, or `undefined` when no update is needed
+     */
+    project(current) {
+        if (this.retained === undefined && current.length === 0)
+            return;
+        const snapshot = current.length === 0 ? CLEARED : current;
+        if (this.retained?.text === snapshot)
+            return;
+        return createUserMessage({
+            content: [{ type: 'text', text: snapshot }],
+            source: { kind: 'runtime-context' },
+        });
+    }
+}

package/session-agent.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The arbor session agent: one DSH user session driven through one arbor
+ * window.
+ *
+ * It implements the full `Agent` contract that
+ * `packages/core/agent/src/runtime-types.ts` augments onto `Agent` — the same
+ * surface `ReactLoopAgent` implements — but the model call and every tool call
+ * run through the arbor window instead of the in-process loop:
+ *
+ *  - `followup()`/`steer()`/`inject()` splice the durable inbox and wake the
+ *    driver, exactly like the official loop (inbox.ts in dsh-agent-loop).
+ *  - The driver runs turns and steps over the arbor window: `turn/start`,
+ *    `step/start`, `user/message`, streamed `agent/assistant-stream` frames,
+ *    `assistant/message`, `ctx.tools.execute` through arbor's tool path,
+ *    `step/end`, `agent/turn-stopping`, `turn/end`.
+ *  - Model requests are derived from the session log (`session.deriveMessages()`)
+ *    exactly like `ReactLoopAgent.buildRequest`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget, ModelSelection, ModelSelectionProjectionState } from '@deepseek-ai/dsh-agent';
+import { AgentModel } from '@deepseek-ai/dsh-agent';
+import type { InboxState } from '@deepseek-ai/dsh-agent';
+import type { StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { ToolCallBlock } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { ToolResult, WindowEvent } from '@4fu/arbor-interfaces';
+import type { WindowRef } from '@4fu/arbor-interfaces';
+import { ArborInbox } from './inbox.js';
+/** One model call's inputs, supplied by the DSH-side session agent. */
+export interface ModelCallInput {
+    /** The window whose frozen epoch this call runs under. */
+    readonly window: WindowRef;
+    /** The session agent whose log the request is derived from. */
+    readonly agent: Agent;
+    readonly selection: Readonly<ModelSelection>;
+    readonly maxTokens?: number;
+    readonly position: {
+        turn: number;
+        step: number;
+    };
+    readonly signal: AbortSignal;
+    /** One streamed chunk, for the durable attempt and the window's live output. */
+    readonly onChunk: (chunk: StreamChunk) => void;
+}
+/** One model call's settled facts. */
+export interface ModelCallOutcome {
+    readonly usage?: TokenUsage;
+    readonly finish: string;
+}
+/**
+ * The arbor window this session drives. Implemented by the driver, which owns
+ * the Arbor host; the agent never imports arbor-core directly. Every method
+ * that touches the window takes its ref, because the session's window changes
+ * over its life: arbor ends a window that goes quiet and the next turn drives
+ * the window that follows it.
+ */
+export interface ArborWindowBridge {
+    /** Open the window on first use and return its ref. */
+    ensureWindow(request?: string): Promise<WindowRef>;
+    /** The system prompt rendered for this window's epoch. */
+    systemPrompt(window: WindowRef): string;
+    /** One model call through DSH's `ctx.llm`. */
+    modelCall(input: ModelCallInput): Promise<ModelCallOutcome>;
+    /** Run one model-produced tool call through arbor's tool path into `ctx.tools.execute`. */
+    runToolCall(call: ToolCallBlock, position: {
+        turn: number;
+        step: number;
+    }): Promise<ToolResult>;
+    /** Publish one window event to the arbor window. */
+    publish(window: WindowRef, event: WindowEvent): void;
+    /** Write a step's sends after its tool results have been appended. */
+    flushSends(): void;
+    /** The turn's work settled: the window's run ends and it goes idle. */
+    finishRun(window: WindowRef): void;
+    /** Release the session's hold on its window. */
+    close(): Promise<void>;
+}
+/** One DSH session driven through one arbor window. */
+export declare class ArborSessionAgent implements Agent {
+    readonly model: AgentModel;
+    readonly inbox: ArborInbox;
+    readonly scope: Scope;
+    readonly ctx: Context;
+    private readonly dispatch;
+    private bridge;
+    private phase;
+    private activityDone;
+    private assistantStreamRevision;
+    private assistantAttemptCounter;
+    private systemPromptLogged;
+    private readonly loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    /** The window the live step drives, so the turn can end its run. */
+    private currentWindow;
+    /**
+     * The session's runtime-context snapshot: the working directory and any
+     * third-party runtime context, appended when it changes and never rewritten
+     * into the frozen prefix.
+     */
+    private readonly runtimeContext;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, projections: {
+        readonly modelSelection: () => ModelSelectionProjectionState;
+        readonly inbox: () => InboxState;
+    }, lastTurn: number);
+    /** Attach the arbor window bridge; the driver calls this once the host exists. */
+    attachBridge(bridge: ArborWindowBridge): void;
+    get status(): AgentStatus;
+    /** The turn/step position the live model step logs its tool events at. */
+    currentLogPosition(): {
+        turn: number;
+        step: number;
+    } | undefined;
+    /** The live turn's abort signal, for tool execution. */
+    currentSignal(): AbortSignal | undefined;
+    private setPhase;
+    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;
+    followup(input: UserMessage): void;
+    steer(input: UserMessage): void;
+    inject(input: UserMessage): void;
+    cancel(cause: AgentCancelCause, options?: CancelOptions): void;
+    runMaintenance<T>(job: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    private wakeDriver;
+    whenIdle(): Promise<void>;
+    private throwError;
+    private kick;
+    private turn;
+    /**
+     * The session's runtime-context snapshot for this step, or `undefined` when
+     * nothing changed since the last one.
+     *
+     * DSH's own assembly supplies the text, so the wording stays DSH's: the
+     * snapshot is the one the official loop would have appended for this session.
+     * Only a third party's context is carried — the paths are arbor's own
+     * `<workspace>` section's, and the policies are `<harness>`'s.
+     */
+    private runtimeContextSnapshot;
+    /** One model call plus the tool executions it requested. */
+    private step;
+}