super-dsh 0.1.9 → 0.1.10

package/agent-omp-sdk/dist/agent.js

@@ -0,0 +1,1178 @@
+import { agentEvents } from "@deepseek-ai/dsh-agent";
+import { Inbox } from "./inbox.js";
+import { LlmAttemptId, ToolCallId, QUOTA_EXCEEDED_CODE, createAssistantMessage, createSystemMessage, createToolResultMessage, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { createScope } from "@deepseek-ai/dsh-scope";
+import { ompPermissionCommand } from "./permission.js";
+import { getBridgeStore } from "./store/index.js";
+import { withSystemHead } from "../../superd-hub/dist/index.js";
+/**
+ * v2 live assistant-stream publication for the OMP bridge — the same frame
+ * protocol the reference loop's AssistantStreamAttempt speaks (start marker,
+ * dense zero-based chunks, terminal settlement) emitted over this agent's own
+ * dispatch, so the session-controller folds OMP's stream into its reconnect
+ * baseline. Chunks also accumulate as raw durable records embedded in the
+ * final assistant/message.
+ */
+class AssistantStreamBridge {
+    attemptId;
+    records = [];
+    #nextRevision;
+    #emit;
+    #index = 0;
+    #terminal = false;
+    constructor(sessionId, attempt, nextRevision, emit) {
+        this.attemptId = LlmAttemptId(`${sessionId}:${attempt}`);
+        this.#nextRevision = nextRevision;
+        this.#emit = emit;
+    }
+    /** Whether the terminal frame already fired. */
+    get ended() {
+        return this.#terminal;
+    }
+    /** Opening marker before the first delivered chunk. */
+    start(turn, step) {
+        this.#emit({ type: "start", attemptId: this.attemptId, revision: this.#nextRevision(), turn, step });
+    }
+    /** One live chunk: durable record plus dense process-local frame. */
+    push(chunk) {
+        const time = Date.now();
+        this.records.push({ type: "chunk", time, chunk });
+        this.#emit({ type: "chunk", attemptId: this.attemptId, revision: this.#nextRevision(), index: this.#index++, time, chunk });
+    }
+    /** Terminal settlement after the durable assistant/message committed. */
+    settle(seq) {
+        this.#terminal = true;
+        this.#emit({ type: "end", attemptId: this.attemptId, revision: this.#nextRevision(), index: this.#index, outcome: { kind: "committed", eventType: "assistant/message", seq } });
+    }
+    /** No durable attempt event will commit. */
+    abandon() {
+        this.#terminal = true;
+        this.#emit({ type: "end", attemptId: this.attemptId, revision: this.#nextRevision(), index: this.#index, outcome: { kind: "abandoned" } });
+    }
+}
+/** Diagnostic trace (set OMP_TRACE=1 on the dsh process to enable). */
+const TRACE = process.env.OMP_TRACE === "1";
+const trace = (...parts) => {
+    if (TRACE)
+        process.stderr.write(`[omp-agent ${Date.now() % 1_000_000}] ${parts.join(" ")}\n`);
+};
+export function convertContent(blocks) {
+    if (blocks === undefined)
+        return [];
+    const result = [];
+    for (const block of blocks) {
+        switch (block.type) {
+            case "text":
+                if (typeof block.text === "string")
+                    result.push({ type: "text", text: block.text });
+                break;
+            case "thinking":
+                if (typeof block.thinking === "string")
+                    result.push({ type: "reasoning", text: block.thinking });
+                break;
+            case "toolCall": {
+                const id = typeof block.id === "string" ? block.id : "";
+                const name = typeof block.name === "string" ? block.name : "";
+                const args = typeof block.arguments === "string" ? block.arguments : JSON.stringify(block.arguments ?? {});
+                result.push({ type: "tool-call", id: ToolCallId(id), name, arguments: args });
+                break;
+            }
+            default:
+                // images / unknown blocks are not bridged in Phase 2.
+                break;
+        }
+    }
+    return result;
+}
+/**
+ * Classify OMP's `stopReason: "error"` assistant message into a Dash `failure`
+ * (`{ message, code }`). This is the same taxonomy the harness adapters use for
+ * `turn/end` reasons — `AUTH`, `RATE_LIMIT`, `QUOTA`, `SERVER` — so the Web UI
+ * renders it through its own error path (the red "API key is invalid" alert,
+ * turn-positioned failure feedback) instead of an empty assistant bubble.
+ * Quota/usage wording is checked before the generic 403→AUTH because OMP's
+ * providers (e.g. kimi) report an exhausted billing quota as HTTP 403.
+ */
+export function ompFailure(message) {
+    if (message.stopReason !== "error")
+        return undefined;
+    const status = typeof message.errorStatus === "number" ? message.errorStatus : undefined;
+    const text = typeof message.errorMessage === "string" && message.errorMessage.trim() !== ""
+        ? message.errorMessage.trim()
+        : undefined;
+    const detail = text ?? "";
+    let code;
+    if (/\b(?:usage|rate)\s*limit\b/i.test(detail) || /\bquota\b/i.test(detail) || /\bbilling\b/i.test(detail) || /\binsufficient\b/i.test(detail)) {
+        code = QUOTA_EXCEEDED_CODE;
+    }
+    else if (status === 401 || status === 403) {
+        code = "AUTH";
+    }
+    else if (status === 429) {
+        code = "RATE_LIMIT";
+    }
+    else if (status !== undefined && status >= 500) {
+        code = "SERVER";
+    }
+    else {
+        code = "UNKNOWN";
+    }
+    return { message: text ?? (status !== undefined ? `HTTP ${status}` : "model request failed"), code };
+}
+/** Map OMP's usage accounting into Dash `TokenUsage` (disjoint field names). */
+export function convertUsage(usage) {
+    if (usage === null || typeof usage !== "object")
+        return undefined;
+    const u = usage;
+    const inputTokens = typeof u.input === "number" ? u.input : 0;
+    const outputTokens = typeof u.output === "number" ? u.output : 0;
+    if (inputTokens === 0 && outputTokens === 0)
+        return undefined;
+    const result = { inputTokens, outputTokens };
+    if (typeof u.cacheRead === "number")
+        result.cacheReadTokens = u.cacheRead;
+    if (typeof u.cacheWrite === "number")
+        result.cacheWriteTokens = u.cacheWrite;
+    if (typeof u.reasoningTokens === "number")
+        result.reasoningTokens = u.reasoningTokens;
+    return result;
+}
+/** Join the visible text blocks of a Dash user message into the OMP prompt string. */
+function userMessageText(message) {
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === "text")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+/**
+ * Dash-host plugin narration from the approval service: the policy-change
+ * notice `agent.inject` carries when `/permission` switches a live session's
+ * approval policy. OMP has no runtime approval control (its `--approval-mode`
+ * is pinned at launch, with no RPC to change it mid-session), so forwarding
+ * the text would steer it into an in-flight turn (interrupting tool work) and
+ * echo it into history as a fake user prompt. Detect and drop it.
+ */
+function isApprovalNarration(message) {
+    // 0.1.7: the shared `plugin` source kind is gone (MessageSourceMap is
+    // merge-extensible; each producer declares its own kind) — user-approval
+    // now carries the dedicated `user-approval` kind.
+    return message.source.kind === "user-approval";
+}
+/**
+ * Reconstruct a Dash user message from an OMP `message_start(role=user)`
+ * payload. Used only as a defensive fallback when a queued delivery's retained
+ * message is missing (OMP echoes text, so the visible content is preserved).
+ */
+function userMessageFromOmp(message) {
+    return createUserMessage({
+        content: convertContent(message.content).filter((block) => block.type === "text"),
+        source: { kind: "user" },
+    });
+}
+/** Extract every tool call an OMP assistant message names, in order, for approval correlation. */
+function toolCalls(blocks) {
+    if (blocks === undefined)
+        return [];
+    const result = [];
+    for (const block of blocks) {
+        if (block.type === "toolCall" && typeof block.id === "string") {
+            result.push({ callId: block.id, name: typeof block.name === "string" ? block.name : "" });
+        }
+    }
+    return result;
+}
+/** Parse the tool name out of an OMP approval-card title (`Allow tool: <name>…`). */
+function approvalToolName(title) {
+    const match = /Allow tool:\s*(\S+)/.exec(title);
+    return match?.[1] ?? "tool";
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Approval answer timeout: fail closed (Deny) after this long so a headless or
+ * server run can't hang forever waiting on a card nobody answers. `0` disables
+ * the timeout. Default: 5 minutes.
+ */
+const OMP_IDLE_EXIT_MS = parseIdleExit(process.env.OMP_IDLE_EXIT_MS);
+/**
+ * How long an agent may sit idle before its SDK sidecar session is torn down.
+ * The Dash host keeps resumed agents registered forever (nothing else disposes
+ * them), and every idle agent pins a live sidecar session. Tearing the agent
+ * down at idle costs nothing observable — the next prompt re-attaches it from
+ * the dsh session log (of record) plus the OMP app-home session file.
+ * `0` disables the exit.
+ */
+function parseIdleExit(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return 600_000;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : 600_000;
+}
+const OMP_APPROVAL_TIMEOUT_MS = parseApprovalTimeout(process.env.OMP_APPROVAL_TIMEOUT_MS);
+function parseApprovalTimeout(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return 300_000;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : 300_000;
+}
+/**
+ * Race an approval request against the configured timeout. On timeout the
+ * signal aborts (withdrawing the question) and we fail closed as `"cancelled"`.
+ */
+async function raceApproval(request, controller, timeoutMs) {
+    if (timeoutMs <= 0)
+        return request;
+    let timer;
+    try {
+        return await Promise.race([
+            request,
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    resolve("cancelled");
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class OmpAgent {
+    id;
+    options;
+    session;
+    inbox;
+    ctx;
+    #rpc;
+    #loopCtx;
+    #scope;
+    #dispatch;
+    #streaming = false;
+    #activityDone = Promise.resolve();
+    #resolveActivityDone = () => { };
+    #dashTurn = 0;
+    #step = 0;
+    #lastTurn = 0;
+    #turnOpen = false;
+    #cancelCause = null;
+    /** Terminal model failure of the open turn (`message_end` stopReason "error"); consumed by `agent_end`. */
+    #pendingFailure = null;
+    /** Live v2 assistant-stream publication for the in-flight OMP message. */
+    #streamBridge;
+    #assistantAttemptCounter = 0;
+    #assistantStreamRevision = 0;
+    /** The current turn's user/message was appended locally and OMP's echo is still awaited. */
+    #localUserPending = false;
+    /** A `turn_start` arrived; `step/start` is deferred until the step's owning turn is known. */
+    #stepStartPending = false;
+    /**
+     * Deliveries forwarded through OMP's own queue, in submission order. OMP
+     * echoes each as `message_start(role=user)`; the bridge maps it by transport:
+     * a `followUp` echo closes the current Dash turn and opens a fresh one
+     * (OMP queues it and auto-generates the next turn — connection layer
+     * hardcodes `resumeIfIdle: true`), a `steer` echo appends a `user/message`
+     * step to the current turn. `sent` marks entries already dispatched to OMP
+     * (a parked injection flushes at agent_start).
+     */
+    #remoteQueue = [];
+    #bridgedToolResults = new Set();
+    #pendingToolCalls = [];
+    #approvalAborts = new Set();
+    /** The last selection already synced to OMP via `set_model`, as `provider/model`. */
+    #lastSyncedModel = null;
+    /** Fires when the agent has been idle past OMP_IDLE_EXIT_MS (tears down the rpc child). */
+    #onIdleExit;
+    #idleExitTimer = undefined;
+    #disposed = false;
+    /** Last OMP-reported session title mirrored into this log (dedupe). */
+    #mirroredTitle;
+    /** One-shot guard for the first-turn session-identity commit (#bootstrapSessionIdentity). */
+    #sessionIdentityCommitted = false;
+    constructor(loopCtx, id, options, session, rpc, onIdleExit) {
+        this.#loopCtx = loopCtx;
+        this.id = id;
+        this.options = options;
+        this.session = withSystemHead(session, () => createSystemMessage(""));
+        this.#rpc = rpc;
+        this.#onIdleExit = onIdleExit;
+        this.#dispatch = agentEvents(loopCtx, this);
+        this.inbox = new Inbox();
+        this.#scope = createScope(loopCtx, this);
+        this.ctx = this.#scope.ctx.extend({ agent: this });
+        this.#lastTurn = session.snapshotEvents().findLast((event) => event.type === "turn/start")?.data.turn ?? 0;
+        rpc.on((event) => this.#handleEvent(event));
+        // OMP's own title arrives on its own frame (the session event stream carries
+        // no title event), so it is applied whenever OMP reports it.
+        rpc.onTitle((title) => this.#applyOmpTitle(title));
+        rpc.onFailure((error) => this.#fail(error));
+        // Session-identity events (the agent-preset stamp and the surface-node-0
+        // system prompt) are committed on the FIRST turn by
+        // #bootstrapSessionIdentity — only once the lazy child actually exists —
+        // so a freshly created session announces completely blank, exactly like
+        // the native agent-loop factory's: the backend takes zero part in the
+        // UI's browser-local new-session draft.
+        // `/permission` — a launch fact, so the shadow routes it by child state:
+        // OMP pins `--approval-mode` at spawn and no RPC moves it mid-session, so
+        // an accepted switch only exists while this session's child does NOT. This
+        // agent-scoped registration (a child of `agent.ctx`) shadows the global
+        // command; before the first prompt it writes the same durable preset the
+        // global handler would (`permissionPresets.set`, no live-agent narration),
+        // and afterwards it refuses instead of appending a preset the running
+        // `omp` cannot honor. The spawn reads exactly those events
+        // (`resolveSpawnPermission`), so the pick reaches the child's argv.
+        this.ctx.inject(["commands"], (cmdCtx) => cmdCtx.commands.register({
+            name: "permission",
+            description: "Switch the permission preset (takes effect at the OMP child's launch)",
+            input: { hint: "<preset>" },
+            handler: (invocation) => this.#handlePermissionCommand(invocation.rawInput),
+        }));
+        // `/compact` parity (route 1): OMP owns context compaction — the Dash log
+        // is only the UI's scrollback projection, so no compaction/* events are
+        // fabricated and the surface is never replaced. Shadowing the loop-owned
+        // global name keeps the (disabled) native pipeline from receiving it; the
+        // command node renders the lifecycle and outcome natively.
+        this.ctx.inject(["commands"], (cmdCtx) => cmdCtx.commands.register({
+            name: "compact",
+            description: "Compact the OMP session context (OMP-native compaction)",
+            input: { hint: "[instructions]" },
+            handler: (invocation) => this.#handleCompactCommand(invocation),
+        }));
+    }
+    get status() {
+        return this.#streaming ? "running" : "idle";
+    }
+    send(message, target, wakeup) {
+        this.#deliver(message, target, wakeup);
+    }
+    followup(message) {
+        // The Web UI's `session.prompt` (mode "queue") routes through followup.
+        // Idle → `prompt` (opens the Dash turn locally, before OMP's ~2s cold
+        // start); busy → `follow_up` (OMP's own queue: delivered as the next
+        // turn's user message and auto-generated). Mirrors dsh-agent-loop's
+        // `followup = send(input, "next-turn", true)`.
+        this.#deliver(message, "next-turn", true);
+    }
+    steer(message) {
+        // Mirrors dsh-agent-loop's `steer = send(input, "next-step", true)`: an
+        // idle driver starts a turn; a running driver consumes it at the next step.
+        this.#deliver(message, "next-step", true);
+    }
+    inject(message) {
+        // Dash-host approval-policy narrations have no OMP runtime equivalent
+        // (OMP pins `--approval-mode` at launch; no RPC changes it mid-session).
+        // Forwarding the text would steer it into an in-flight turn — interrupting
+        // tool work — and echo it into history as a fake user prompt. Drop it; the
+        // accompanying `approval/policy` session event stays recorded so the UI's
+        // permission state remains truthful.
+        if (isApprovalNarration(message)) {
+            trace("inject: dropped approval-policy narration (OMP lacks runtime approval control)");
+            return;
+        }
+        // Mirrors dsh-agent-loop's `inject = send(input, "next-step", false)`:
+        // queued without waking; idle drivers leave it pending until a later
+        // follow-up/steer wakes them (flushed at the next agent_start).
+        this.#deliver(message, "next-step", false);
+    }
+    cancel(cause, _options) {
+        // No active run → no-op: arming `#cancelCause` here would misreport a later,
+        // unrelated completed turn as aborted. First cause wins: later cancels must
+        // not overwrite an earlier cause (dash contract).
+        if (!this.#streaming)
+            return;
+        if (this.#cancelCause === null)
+            this.#cancelCause = cause;
+        void this.#rpc.abort().catch(() => { });
+    }
+    async whenIdle() {
+        // Event-driven: wait for the current activity to settle (agent_end), then
+        // confirm OMP reports quiescence via get_state (the mapping's poll).
+        let activity;
+        do {
+            activity = this.#activityDone;
+            await activity;
+        } while (activity !== this.#activityDone);
+        for (;;) {
+            const state = await this.#rpc.getState().catch(() => null);
+            if (state === null || !state.isStreaming)
+                return;
+            await delay(50);
+        }
+    }
+    runMaintenance(task) {
+        // OMP has no maintenance concept; run the task directly.
+        return task(new AbortController().signal);
+    }
+    /** Stop OMP and unwind the scoped world. Idempotent. */
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        clearTimeout(this.#idleExitTimer);
+        this.#idleExitTimer = undefined;
+        for (const controller of this.#approvalAborts)
+            controller.abort();
+        this.#approvalAborts.clear();
+        this.#rpc.close();
+        await this.#scope.dispose();
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    /**
+     * Route one message by the reference loop's (target, wakeup) semantics:
+     * an idle waking delivery starts a fresh local turn (`prompt`); a follow-up
+     * sent while a turn is open is forwarded to OMP's own queue (`follow_up`:
+     * OMP delivers it as the next turn's user message and auto-generates that
+     * turn); steering/injection goes through `steer` (consumed at the next
+     * step, or parked until agent_start when not yet streaming).
+     *
+     * Busy is the LOCAL turn state (`#turnOpen`), not OMP's `#streaming` flag:
+     * OMP needs a moment (cold child start) to emit `agent_start` after a
+     * prompt, and in that gap a bare `prompt` would be rejected by OMP while
+     * `follow_up` is state-safe (it queues and resumes from either state).
+     */
+    #deliver(message, target, wakeup) {
+        if (this.#disposed)
+            return;
+        const busy = this.#turnOpen || this.#streaming;
+        trace(`#deliver target=${target} wakeup=${wakeup} busy=${busy} (turnOpen=${this.#turnOpen} streaming=${this.#streaming})`);
+        if (busy && target === "next-turn") {
+            this.#queueRemote(message, "followUp");
+            return;
+        }
+        if (busy || !wakeup) {
+            this.#queueRemote(message, "steer");
+            return;
+        }
+        this.#deliverPrompt(message);
+    }
+    #deliverPrompt(message) {
+        if (this.#disposed)
+            return;
+        trace(`#deliverPrompt turn=${this.#dashTurn + 1} text="${userMessageText(message).slice(0, 40)}"`);
+        // Reserve the turn synchronously: busy-flag semantics stay identical to
+        // the eager line (a second delivery during the cold start queues
+        // remotely), but NOTHING is appended yet — the log stays empty until the
+        // lazy child exists, so a failed cold start leaves no orphan turn.
+        this.#reserveTurn();
+        clearTimeout(this.#idleExitTimer);
+        this.#idleExitTimer = undefined;
+        this.#beginActivity();
+        void this.#startTurn(message);
+    }
+    /**
+     * Cold-start path for one reserved turn: spawn the lazy child (first prompt
+     * only), commit the session-identity events ahead of the turn (surface node
+     * 0 = system prompt — the native loop's step() ordering), sync the model,
+     * then append turn/start + user/message and dispatch. A failed cold start
+     * synthesizes the failed turn (turn/end with the error reason) so the UI's
+     * error path renders it, then unwinds the reservation.
+     */
+    async #startTurn(message) {
+        try {
+            await this.#rpc.ensureStarted();
+            await this.#bootstrapSessionIdentity();
+            await this.#syncModelSelection();
+        }
+        catch (error) {
+            trace(`#startTurn cold start failed: ${String(error)}`);
+            if (this.#turnOpen) {
+                this.session.append("turn/start", { turn: this.#dashTurn });
+                this.session.append("user/message", message, { surfaceOp: "append" });
+                this.#closeTurn({ kind: "error", error: { message: String(error), code: "UNKNOWN" } });
+            }
+            this.#endActivity();
+            return;
+        }
+        if (this.#disposed)
+            return;
+        this.session.append("turn/start", { turn: this.#dashTurn });
+        this.session.append("user/message", message, { surfaceOp: "append" });
+        void this.#rpc.prompt(userMessageText(message)).catch((error) => this.#fail(error));
+    }
+    /**
+     * One-shot first-turn identity commit, right after the lazy child spawns:
+     * the agent-preset stamp (idempotent) and the live system prompt as surface
+     * node 0. This is now the ONLY system-prompt emitter — cold replay emits
+     * none (the OMP JSONL never records a system prompt), so a resumed session
+     * gets the RPC prompt appended immediately before its first live
+     * `turn/start` (timeline-tail semantics), while a fresh session gets it as
+     * node 0 (that render IS turn-1). The guard — skip when the seed already
+     * carries a `system/message` — stays.
+     */
+    async #bootstrapSessionIdentity() {
+        if (this.#sessionIdentityCommitted)
+            return;
+        this.#sessionIdentityCommitted = true;
+        if (!this.session.snapshotEvents().some((event) => event.type === "agent-preset/selected" && event.data?.agentPreset === "omp")) {
+            this.session.append("agent-preset/selected", { agentPreset: "omp" });
+        }
+        {
+            const systemPrompt = await this.#rpc.getSystemPrompt();
+            if (systemPrompt !== undefined && systemPrompt !== "") {
+                // dsh session v3 requires positive turn/step coordinates on surface
+                // events (`turn must be positive`); native fresh sessions use 1/1 for the
+                // node-0 system prompt. 0/0 made the native jsonl writer reject the whole
+                // live batch, stalling every append before turn/start.
+                // 0.1.7: createSystemMessage dropped its origin parameter (the source
+                // kind is fixed at `system-prompt`).
+                // v4 protected-head posture: node-0 on a fresh surface (append), or a
+                // replacement of the placeholder when a user message raced the async
+                // prompt fetch — both shapes the 0.1.7 reader accepts.
+                this.session.stampSystemPrompt(1, 1, createSystemMessage(systemPrompt));
+            }
+        }
+    }
+    /**
+     * `/permission` handler: mirror the global command's write for a session whose
+     * `omp` child does not exist yet (the pick then lands in the launch flag via
+     * {@link resolveSpawnPermission}), and refuse it once the child does — the
+     * policy is a launch flag, so accepting later would desync UI from runtime.
+     * Uses `permissionPresets.set` (log-only preset + knob events) rather than the
+     * global handler's `approval.setPolicy`, which would inject a narration user
+     * message into the OMP session for a change OMP never sees.
+     */
+    #handlePermissionCommand(rawInput) {
+        const presets = this.#loopCtx.get("permissionPresets");
+        if (presets === undefined) {
+            return { kind: "error", text: "permission presets are not available on this host" };
+        }
+        const decision = ompPermissionCommand({
+            rawInput,
+            spawned: this.#rpc.spawned,
+            names: presets.names,
+            current: presets.current(this.session),
+        });
+        if (decision.action === "apply")
+            presets.set(this.session, decision.preset);
+        return decision.result;
+    }
+    /**
+     * /compact handler (route 1): run OMP's own compaction on the live child
+     * and report its real metering as the command outcome. No compaction/*
+     * events are appended and the Dash surface is never replaced — the Dash log
+     * is the UI's scrollback projection; only OMP's own context shrinks.
+     */
+    async #handleCompactCommand(invocation) {
+        if (this.#disposed)
+            return { kind: "error", text: "Session is disposed." };
+        if (!this.#rpc.spawned) {
+            return { kind: "success", text: "Session context is empty — nothing to compact yet." };
+        }
+        const instructions = invocation.rawInput.trim();
+        const before = await this.#rpc.contextUsage();
+        try {
+            await this.#rpc.compact(instructions === "" ? undefined : instructions);
+        }
+        catch (error) {
+            return { kind: "error", text: `Compaction failed: ${String(error)}` };
+        }
+        const after = await this.#rpc.contextUsage();
+        if (before?.tokens === undefined || after?.tokens === undefined) {
+            return { kind: "success", text: "Compaction complete." };
+        }
+        const saved = before.tokens - after.tokens;
+        return {
+            kind: "success",
+            text: `Compaction complete. Context tokens: ${before.tokens.toLocaleString("en-US")} → ${after.tokens.toLocaleString("en-US")} (saved ${saved.toLocaleString("en-US")}).`,
+        };
+    }
+    /**
+     * Queue a message for OMP-side delivery. `followUp` dispatches immediately
+     * (state-safe whether or not OMP is streaming); `steer` dispatches now when
+     * already streaming, otherwise parks until agent_start.
+     */
+    #queueRemote(message, transport) {
+        if (this.#disposed)
+            return;
+        clearTimeout(this.#idleExitTimer);
+        this.#idleExitTimer = undefined;
+        this.#remoteQueue.push({ message, sent: false, transport });
+        if (this.#streaming || transport === "followUp")
+            this.#flushRemote();
+    }
+    #flushRemote() {
+        void this.#syncModelSelection().finally(() => {
+            for (const entry of this.#remoteQueue) {
+                if (entry.sent)
+                    continue;
+                entry.sent = true;
+                const text = userMessageText(entry.message);
+                const sent = entry.transport === "followUp" ? this.#rpc.followUp(text) : this.#rpc.steer(text);
+                trace(`-> ${entry.transport} "${text.slice(0, 40)}"`);
+                void sent.catch((error) => this.#fail(error));
+            }
+        });
+    }
+    /**
+     * The selection a turn should run under, resolved exactly as the native
+     * loop resolves it (`buildRequest`): the base is the session's logged
+     * `request/header` (the replay synthesizes it from OMP's transcript, so a
+     * resumed session keeps ITS last model) falling back to the global default;
+     * the `system-prompt/assemble` → `agent/request` waterfall pair then applies
+     * the apiproxy's installed selection, so a switch made in the Web UI this
+     * process still wins. OMP itself already restores the transcript's model on
+     `--resume`, which is why {@link #syncModelSelection} only pushes when the
+     * resolved target differs from OMP's live state.
+     */
+    async #effectiveModelSelection() {
+        const base = this.#baseModelSelection();
+        const systemPrompt = this.ctx.get("systemPrompt");
+        if (systemPrompt !== undefined) {
+            try {
+                await systemPrompt.assemble({ agent: this, scope: this });
+            }
+            catch (error) {
+                trace(`model selection assemble failed: ${String(error)}`);
+            }
+        }
+        try {
+            const resolved = await this.#dispatch.waterfall("agent/request", { turn: this.#dashTurn, step: this.#step, signal: new AbortController().signal }, () => Promise.resolve(base));
+            if (resolved.provider !== "" && resolved.model !== "") {
+                return { provider: resolved.provider, model: resolved.model };
+            }
+        }
+        catch (error) {
+            trace(`model selection waterfall failed: ${String(error)}`);
+        }
+        return base;
+    }
+    /** Tier-2/3 base: the session's logged header config, else the global default, else agent options. */
+    #baseModelSelection() {
+        const persisted = this.session.requestHeader()?.config;
+        if (persisted !== undefined && persisted.provider !== "" && persisted.model !== "") {
+            return { provider: persisted.provider, model: persisted.model };
+        }
+        const service = this.ctx.get("agentDefaultModel");
+        const selection = service?.currentSelection();
+        if (selection !== undefined && selection.provider !== "" && selection.model !== "")
+            return selection;
+        return { provider: this.options.provider ?? "", model: this.options.model ?? "" };
+    }
+    /**
+     * Sync the effective model selection into OMP before a turn is dispatched.
+     * `set_model` fires only when the resolved target differs from OMP's live
+     * model, so a plain resume (OMP already restored the transcript's model, and
+     * the replayed header names the same one) performs no round-trip at all.
+     */
+    async #syncModelSelection() {
+        const target = await this.#effectiveModelSelection();
+        const key = `${target.provider}/${target.model}`;
+        if (key === this.#lastSyncedModel)
+            return;
+        const state = await this.#rpc.getState().catch(() => null);
+        const ompModel = state?.model;
+        if (ompModel?.provider === target.provider && ompModel?.id === target.model) {
+            this.#lastSyncedModel = key;
+            this.#recordModel(target);
+            return;
+        }
+        await this.#rpc.setModel(target.provider, target.model).catch((error) => {
+            trace(`set_model ${key} failed: ${String(error)}`);
+        });
+        this.#lastSyncedModel = key;
+        this.#recordModel(target);
+    }
+    /** Event-driven index update: mirror the live model switch immediately (D5.3). */
+    #recordModel(target) {
+        const store = getBridgeStore();
+        if (store === undefined)
+            return;
+        store.updateModel(String(this.session.id), target.provider, target.model);
+    }
+    /**
+     * Reserve a turn WITHOUT appending anything: the prompt path reserves
+     * synchronously, then commits turn/start + user/message only after the lazy
+     * cold start (#startTurn). #openTurn keeps the eager append for paths that
+     * run against an already-live child (#bridgeRemoteUser echoes).
+     */
+    #reserveTurn() {
+        if (this.#turnOpen)
+            return;
+        this.#dashTurn = ++this.#lastTurn;
+        this.#step = 0;
+        this.#turnOpen = true;
+        this.#localUserPending = true;
+    }
+    #openTurn(message, localUser = true) {
+        trace(`#openTurn turnOpen=${this.#turnOpen} -> turn=${this.#dashTurn + 1} localUser=${localUser}`);
+        if (this.#turnOpen)
+            return;
+        this.#reserveTurn();
+        this.#localUserPending = localUser;
+        this.session.append("turn/start", { turn: this.#dashTurn });
+        this.session.append("user/message", message, { surfaceOp: "append" });
+    }
+    #closeTurn(reason) {
+        if (!this.#turnOpen)
+            return;
+        this.#turnOpen = false;
+        this.#localUserPending = false;
+        this.session.append("turn/end", { turn: this.#dashTurn, reason });
+        void this.#mirrorOmpTitle();
+    }
+    /**
+     * Mirror OMP's own session title into a `session/title` event. Dash does not
+     * generate titles for OMP sessions (the native title rows are disabled in the
+     * bundle patch); OMP owns the title and only reports it through the SDK. Empty
+     * or unchanged titles are ignored, so a session with no OMP title keeps its
+     * creation value.
+     */
+    async #mirrorOmpTitle() {
+        if (!this.#rpc.spawned)
+            return;
+        try {
+            const state = await this.#rpc.getState();
+            this.#applyOmpTitle(state.title);
+        }
+        catch {
+            // fail-soft: a missing title never affects the turn
+        }
+    }
+    /**
+     * Record a title OMP reported. OMP is a title *provider* (source.kind:
+     * "provider"), not Dash's built-in fallback. The event belongs to the
+     * `session-title` package's vocabulary, which the bridge does not import, so
+     * the append is cast; it is synchronous and never throws into the turn.
+     */
+    #applyOmpTitle(title) {
+        if (typeof title !== "string" || title.trim() === "")
+            return;
+        if (title === this.#mirroredTitle)
+            return;
+        this.#mirroredTitle = title;
+        try {
+            this.session.append("session/title", {
+                title,
+                messageSeqs: [],
+                source: { kind: "provider", provider: "omp" },
+            });
+        }
+        catch {
+            // fail-soft: a title is never allowed to affect the turn
+        }
+    }
+    /**
+     * Append the deferred `step/start` now that the step's first message has
+     * revealed which Dash turn owns it (a queued follow-up opens a fresh turn).
+     */
+    #commitStepStart() {
+        if (!this.#stepStartPending)
+            return;
+        this.#stepStartPending = false;
+        if (!this.#turnOpen)
+            return;
+        this.#step += 1;
+        this.session.append("step/start", { turn: this.#dashTurn, step: this.#step });
+    }
+    /**
+     * Bridge an OMP `message_start(role=user)` that was NOT appended locally.
+     * A `followUp` echo closes the current Dash turn and opens a fresh one with
+     * the retained message (OMP queued it and is now generating its turn); a
+     * steering/injection echo adds a `user/message` step to the current turn.
+     * Falls back to OMP's own content if no retained message matches.
+     */
+    #bridgeRemoteUser(ompMessage) {
+        const entry = this.#remoteQueue.shift();
+        if (entry === undefined) {
+            this.#closeTurn({ kind: "completed" });
+            this.#openTurn(userMessageFromOmp(ompMessage), false);
+            return;
+        }
+        if (entry.transport === "followUp") {
+            this.#closeTurn({ kind: "completed" });
+            this.#openTurn(entry.message, false);
+            return;
+        }
+        this.session.append("user/message", entry.message, { surfaceOp: "append" });
+    }
+    #beginActivity() {
+        // Settle any prior in-flight activity first: `send()` can inject a prompt
+        // mid-stream (streamingBehavior followUp/steer), superseding the current
+        // activity promise. Without settling the old one, whenIdle()'s do-while
+        // would await an orphaned promise that never resolves.
+        this.#resolveActivityDone();
+        this.#activityDone = new Promise((resolve) => {
+            this.#resolveActivityDone = resolve;
+        });
+    }
+    #endActivity() {
+        this.#resolveActivityDone();
+    }
+    #markRunning() {
+        clearTimeout(this.#idleExitTimer);
+        this.#idleExitTimer = undefined;
+        if (this.#streaming)
+            return;
+        this.#streaming = true;
+        this.#dispatch.emit("agent/status", { status: "running" });
+    }
+    #markIdle() {
+        if (!this.#streaming)
+            return;
+        this.#streaming = false;
+        this.#dispatch.emit("agent/status", { status: "idle" });
+        this.#armIdleExit();
+    }
+    /**
+     * Schedule the idle exit. Skipped while deliveries are still queued (an
+     * unanswered parked injection means work is pending, not idle) or when the
+     * exit is disabled. Any later activity restarts or cancels the timer.
+     */
+    #armIdleExit() {
+        if (this.#disposed || this.#onIdleExit === undefined || OMP_IDLE_EXIT_MS === 0)
+            return;
+        if (this.#remoteQueue.some((entry) => !entry.sent))
+            return;
+        clearTimeout(this.#idleExitTimer);
+        this.#idleExitTimer = setTimeout(() => {
+            this.#idleExitTimer = undefined;
+            void this.#revalidateIdleExit();
+        }, OMP_IDLE_EXIT_MS);
+        this.#idleExitTimer.unref?.();
+    }
+    /**
+     * Five-fold quiescence re-validation at fire time. The idle timer is only a
+     * hint: before teardown, re-confirm no live work via local signals and OMP's
+     * own self-attestation (get_state streaming/compacting/queued, get_subagents
+     * liveness). Any busy signal re-arms instead of killing; a query failure
+     * fail-softs to the local signals rather than forcing a teardown.
+     */
+    async #revalidateIdleExit() {
+        if (this.#disposed || this.#streaming)
+            return this.#armIdleExit();
+        // Never-spawned draft: no child exists and no work is possible — drop the
+        // exit instead of re-arming timers or querying the rpc (passive queries
+        // must never conjure a child).
+        if (!this.#rpc.spawned)
+            return;
+        if (this.#remoteQueue.some((entry) => !entry.sent))
+            return this.#armIdleExit();
+        if (this.#approvalAborts.size > 0)
+            return this.#armIdleExit();
+        try {
+            const state = await this.#rpc.getState();
+            if (this.#streaming)
+                return this.#armIdleExit();
+            if (state.isStreaming)
+                return this.#armIdleExit();
+            if (state.isCompacting === true)
+                return this.#armIdleExit();
+            if (typeof state.queuedMessageCount === "number" && state.queuedMessageCount > 0)
+                return this.#armIdleExit();
+        }
+        catch {
+            // Self-attestation unavailable: local signals remain authoritative.
+        }
+        try {
+            const subagents = await this.#rpc.getSubagents();
+            if (this.#streaming)
+                return this.#armIdleExit();
+            if (subagents.length > 0)
+                return this.#armIdleExit();
+        }
+        catch {
+            // getSubagents fail-softs already; belt-and-suspenders.
+        }
+        if (this.#streaming)
+            return this.#armIdleExit();
+        trace(`idle exit after ${OMP_IDLE_EXIT_MS}ms — disposing agent ${this.id}`);
+        this.#onIdleExit?.();
+    }
+    #fail(error) {
+        this.#abandonStreamBridge();
+        if (this.#disposed)
+            return;
+        trace(`#fail ${String(error).slice(0, 200)}`);
+        this.#closeTurn({ kind: "error", error: { message: String(error), code: "UNKNOWN" } });
+        this.#markIdle();
+        this.#endActivity();
+    }
+    #handleEvent(event) {
+        switch (event.type) {
+            case "agent_start":
+                trace("event agent_start");
+                this.#markRunning();
+                this.#flushRemote();
+                break;
+            case "turn_start":
+                // Defer `step/start`: the step's owning turn is only known once its
+                // first message arrives (a queued follow-up opens a fresh turn).
+                trace("event turn_start");
+                this.#stepStartPending = true;
+                this.#pendingFailure = null;
+                break;
+            case "message_start": {
+                const message = event.message;
+                if (message?.role === "user") {
+                    if (this.#localUserPending) {
+                        // OMP is echoing the user message #openTurn already appended.
+                        this.#localUserPending = false;
+                    }
+                    else {
+                        // A queued follow-up / steering message delivered by OMP.
+                        this.#bridgeRemoteUser(message);
+                    }
+                }
+                else if (message?.role === "assistant") {
+                    // Reset per-message streaming accumulators.
+                    this.#abandonStreamBridge();
+                }
+                // role === "toolResult" is bridged in message_end (deduped vs tool_execution_end).
+                this.#commitStepStart();
+                break;
+            }
+            case "message_update": {
+                const delta = event.assistantMessageEvent;
+                if (delta !== undefined)
+                    this.#handleUpdate(delta);
+                break;
+            }
+            case "message_end": {
+                const message = event.message;
+                if (message === undefined)
+                    break;
+                const role = message.role;
+                if (role === "assistant") {
+                    const failure = ompFailure(message);
+                    if (failure !== undefined) {
+                        this.#pendingFailure = failure;
+                        this.#abandonStreamBridge();
+                    }
+                    else {
+                        this.#appendAssistantMessage(message);
+                    }
+                }
+                else if (role === "toolResult") {
+                    this.#appendToolResultMessage(message);
+                }
+                else if (role !== "user") {
+                    process.stderr.write(`omp rpc: unhandled message_end role "${role}"\n`);
+                }
+                break;
+            }
+            case "tool_execution_start": {
+                const callId = String(event.toolCallId ?? "");
+                const name = String(event.toolName ?? "");
+                this.session.append("tool/call", {
+                    turn: this.#dashTurn,
+                    step: this.#step,
+                    callId: ToolCallId(callId),
+                    name,
+                    arguments: JSON.stringify(event.args ?? {}),
+                });
+                // The assistant's pending tool call is now materialized as a running call.
+                this.#pendingToolCalls = this.#pendingToolCalls.filter((pending) => pending.callId !== callId);
+                break;
+            }
+            case "extension_ui_request":
+                void this.#handleExtensionUiRequest(event);
+                break;
+            case "tool_execution_end":
+                this.#appendToolResult(event);
+                break;
+            case "turn_end":
+                trace("event turn_end");
+                if (this.#turnOpen) {
+                    this.session.append("step/end", { turn: this.#dashTurn, step: this.#step });
+                }
+                break;
+            case "agent_end": {
+                trace(`event agent_end cancelCause=${String(this.#cancelCause)}`);
+                const pendingFailure = this.#pendingFailure;
+                this.#pendingFailure = null;
+                this.#closeTurn(this.#cancelCause !== null
+                    ? { kind: "aborted", reason: this.#cancelCause }
+                    : pendingFailure !== null
+                        ? { kind: "error", error: pendingFailure }
+                        : { kind: "completed" });
+                this.#cancelCause = null;
+                this.#markIdle();
+                this.#endActivity();
+                // Live metadata the Dash surface has no projection seam for yet:
+                // surface OMP's own accounting (tokens, contextUsage, cost) in the
+                // diagnostic trace so it is observable per completed turn.
+                void this.#rpc
+                    .getSessionStats()
+                    .then((stats) => {
+                    trace(`sessionStats tokens=${JSON.stringify(stats.tokens ?? {})} contextUsage=${String(stats.contextUsage)} cost=${JSON.stringify(stats.cost ?? {})}`);
+                })
+                    .catch(() => { });
+                break;
+            }
+        }
+    }
+    /** The open stream bridge for this message, starting one on first use. */
+    #ensureStreamBridge() {
+        if (this.#streamBridge === undefined || this.#streamBridge.ended) {
+            this.#streamBridge = new AssistantStreamBridge(this.session.id, ++this.#assistantAttemptCounter, () => ++this.#assistantStreamRevision, (frame) => this.#dispatch.emit("agent/assistant-stream", { frame }));
+            this.#streamBridge.start(this.#dashTurn, this.#step);
+        }
+        return this.#streamBridge;
+    }
+    /** Abandon any open stream bridge — failure paths never settle. */
+    #abandonStreamBridge() {
+        if (this.#streamBridge !== undefined && !this.#streamBridge.ended)
+            this.#streamBridge.abandon();
+        this.#streamBridge = undefined;
+    }
+    #handleUpdate(delta) {
+        switch (delta.type) {
+            case "text_delta":
+                if (typeof delta.delta === "string" && delta.delta !== "") {
+                    const chunk = { type: "text-delta", index: delta.contentIndex ?? 0, text: delta.delta };
+                    // v2: live text no longer appends `assistant/chunk` log events — the
+                    // stream publishes as dense agent frames and embeds durably in the
+                    // final assistant/message.
+                    this.#ensureStreamBridge().push(chunk);
+                }
+                break;
+            default:
+                // text_start/text_end/thinking_*/toolcall_* are folded into the final message.
+                break;
+        }
+    }
+    /**
+     * Bridge an OMP `extension_ui_request`. Approval cards (`select` with an
+     * "Approve" option) round-trip through the Dash approval seam
+     * (`ctx.get("approval").request()`), which the Web UI renders as an
+     * ApprovalPanel. Every OTHER blocking dialog (confirm/input/editor, or a
+     * select lacking "Approve") gets the universal cancellation so OMP never
+     * blocks forever.
+     */
+    async #handleExtensionUiRequest(event) {
+        const id = String(event.id ?? "");
+        if (id === "")
+            return;
+        const method = String(event.method ?? "");
+        const options = Array.isArray(event.options) ? event.options : [];
+        if (method !== "select" || !options.includes("Approve")) {
+            // Not an approval card: cancel the dialog so OMP can keep going.
+            this.#rpc.sendRaw({ type: "extension_ui_response", id, cancelled: true });
+            return;
+        }
+        const title = typeof event.title === "string" ? event.title : "";
+        const pending = this.#matchPendingToolCall(title);
+        const toolName = pending !== null && pending.name !== "" ? pending.name : approvalToolName(title);
+        const callId = pending !== null ? ToolCallId(pending.callId) : undefined;
+        const reason = title !== "" ? title : undefined;
+        // `ctx.approval` is provided by a sibling fiber in the real profile, so a
+        // property read throws "cannot get property ... without inject"; `ctx.get`
+        // resolves the store from any ctx instead.
+        const approval = this.ctx.get("approval");
+        if (approval === undefined) {
+            // Fail closed: without an answerer the tool must not run.
+            this.#rpc.sendRaw({ type: "extension_ui_response", id, value: "Deny" });
+            return;
+        }
+        const controller = new AbortController();
+        this.#approvalAborts.add(controller);
+        try {
+            const outcome = await raceApproval(approval.request({
+                agent: this,
+                toolName,
+                ...(callId === undefined ? {} : { callId }),
+                ...(reason === undefined ? {} : { reason }),
+                signal: controller.signal,
+            }), controller, OMP_APPROVAL_TIMEOUT_MS);
+            // Fail closed: only an explicit one-shot grant approves.
+            this.#rpc.sendRaw({
+                type: "extension_ui_response",
+                id,
+                value: outcome === "allowed-once" ? "Approve" : "Deny",
+            });
+        }
+        catch {
+            // A synchronous throw (no open turn / audit append failure) still denies
+            // rather than hanging OMP.
+            this.#rpc.sendRaw({ type: "extension_ui_response", id, value: "Deny" });
+        }
+        finally {
+            this.#approvalAborts.delete(controller);
+        }
+    }
+    /**
+     * Match an approval card to its pending tool call, preferring the pending
+     * call whose name equals the card title's tool name and falling back to the
+     * first pending call. Consumes the match so a denied card (which never emits
+     * `tool_execution_start`) can't be re-matched by a later card.
+     */
+    #matchPendingToolCall(title) {
+        if (this.#pendingToolCalls.length === 0)
+            return null;
+        const titleName = approvalToolName(title);
+        let index = this.#pendingToolCalls.findIndex((pending) => pending.name !== "" && pending.name === titleName);
+        if (index === -1)
+            index = 0;
+        const [matched] = this.#pendingToolCalls.splice(index, 1);
+        return matched ?? null;
+    }
+    #appendAssistantMessage(message) {
+        this.#pendingToolCalls = toolCalls(message.content);
+        const content = convertContent(message.content);
+        const usage = convertUsage(message.usage);
+        const assistant = createAssistantMessage({
+            content,
+            source: {
+                provider: String(message.provider ?? this.options.provider ?? ""),
+                model: String(message.model ?? this.options.model ?? ""),
+            },
+        });
+        const bridge = this.#streamBridge;
+        // v2: the attempt's timed chunks embed in the event itself;
+        // `sourceEventSeqs` is forbidden on assistant/message in v2.
+        const event = this.session.append("assistant/message", {
+            turn: this.#dashTurn,
+            step: this.#step,
+            message: assistant,
+            stream: bridge?.records ?? [],
+            ...(usage === undefined ? {} : { usage }),
+        }, {
+            surfaceOp: "append",
+        });
+        if (bridge !== undefined && !bridge.ended)
+            bridge.settle(event.seq);
+        this.#streamBridge = undefined;
+    }
+    #appendToolResult(event) {
+        const callId = String(event.toolCallId ?? "");
+        this.#bridgedToolResults.add(callId);
+        const result = event.result;
+        const isError = Boolean(event.isError ?? result?.isError ?? false);
+        const message = createToolResultMessage({
+            callId: ToolCallId(callId),
+            content: convertContent(result?.content),
+            isError,
+        });
+        this.session.append("tool/result", {
+            turn: this.#dashTurn,
+            step: this.#step,
+            message,
+            ...(isError ? { error: { name: "ToolExecutionError", code: "TOOL_ERROR" } } : {}),
+        }, {
+            surfaceOp: "append",
+        });
+    }
+    #appendToolResultMessage(message) {
+        const callId = String(message.toolCallId ?? "");
+        // The normal path bridges via `tool_execution_end` first; skip the
+        // `message_end(toolResult)` duplicate OMP always also emits.
+        if (this.#bridgedToolResults.has(callId))
+            return;
+        this.#bridgedToolResults.add(callId);
+        const isError = Boolean(message.isError ?? false);
+        const result = createToolResultMessage({
+            callId: ToolCallId(callId),
+            content: convertContent(message.content),
+            isError,
+        });
+        this.session.append("tool/result", {
+            turn: this.#dashTurn,
+            step: this.#step,
+            message: result,
+            ...(isError ? { error: { name: "ToolExecutionError", code: "TOOL_ERROR" } } : {}),
+        }, {
+            surfaceOp: "append",
+        });
+    }
+}