@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

package/lib/types/dsh-adapter/approvals.d.ts

@@ -12,13 +12,21 @@
  * Outcomes are the protocol's closed set — `'allowed-once'` and
  * `'rejected'` from the panel, `'cancelled'` on abort/teardown; there is
  * no allow-always or feedback channel in the protocol.
+ *
+ * The store presents its asks through the shared permission-panel shape
+ * (`src/channel/permissions.ts`), so the one approval panel renders DSH and
+ * backend prompts alike: a DSH ask offers exactly the protocol's two
+ * options (allow once / reject), and the DSH-only facts (the `external`
+ * source badge, the background-session id) ride along on the snapshot.
  */
 import { compositionRoot } from './host-access.js';
 import { type AdapterRuntimeOptions } from '../adapter/kernel/runtime.js';
 import type { ApprovalOutcome, ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-/** What the TUI renders while an approval is pending. */
-export interface ApprovalSnapshot {
+import { type PermissionPanelDecision, type PermissionPanelOutcome, type PermissionPanelSnapshot, type PermissionPanelSource } from '../channel/permissions.js';
+/** What the TUI renders while an approval is pending (the shared panel
+ *  shape plus the DSH facts it documents below). */
+export interface ApprovalSnapshot extends PermissionPanelSnapshot {
     /** Stable key so the panel remounts (fresh focus state) per request. */
     readonly key: string;
     readonly toolName: string;
@@ -49,6 +57,8 @@ export interface ApprovalSnapshot {
      * "needs input" instead of hanging on a fail-closed answer).
      */
     readonly agentId: string;
+    /** The protocol's two choices: allow once / reject. */
+    readonly options: PermissionPanelSnapshot['options'];
 }
 /** Host-only registration used by the TUI plugin bootstrap. */
 export declare function bindApprovalStore(ctx: Parameters<typeof compositionRoot>[0], store: ApprovalStore): void;
@@ -60,7 +70,7 @@ export declare function getApprovalStore(ctx: Parameters<typeof compositionRoot>
  * the ask is withdrawn. The TUI subscribes for re-renders and decides via
  * {@link ApprovalStore.decide}.
  */
-export declare class ApprovalStore {
+export declare class ApprovalStore implements PermissionPanelSource {
     private readonly runtime;
     constructor(runtime?: AdapterRuntimeOptions);
     private readonly queue;
@@ -193,9 +203,12 @@ export declare class ApprovalStore {
     /**
      * The user decided on the current approval; settles it and drains the
      * next queued ask if any. No-op when nothing is pending.
-     * @param outcome - `'allowed-once'` or `'rejected'`.
+     * @param outcome - `'allowed-once'` or `'rejected'`. The protocol has no
+     *   allow-always and the panel never offers it for a DSH ask; one arriving
+     *   anyway is refused (fail closed). The panel's option detail carries
+     *   nothing the protocol can use beyond its panel key.
      */
-    decide(outcome: 'allowed-once' | 'rejected'): void;
+    decide(outcome: PermissionPanelOutcome, decision?: PermissionPanelDecision): void;
     /**
      * Settle the active and all queued asks (plugin teardown). The panel
      * unmounts as the snapshot clears.

package/lib/types/dsh-adapter/approvals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/approvals.ts"],"names":[],"mappings":"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"}

package/lib/types/dsh-adapter/approvals.js

@@ -12,10 +12,17 @@
  * Outcomes are the protocol's closed set — `'allowed-once'` and
  * `'rejected'` from the panel, `'cancelled'` on abort/teardown; there is
  * no allow-always or feedback channel in the protocol.
+ *
+ * The store presents its asks through the shared permission-panel shape
+ * (`src/channel/permissions.ts`), so the one approval panel renders DSH and
+ * backend prompts alike: a DSH ask offers exactly the protocol's two
+ * options (allow once / reject), and the DSH-only facts (the `external`
+ * source badge, the background-session id) ride along on the snapshot.
  */
 import { compositionRoot } from './host-access.js';
 import { assertCapabilityShadowPolicy, defaultAdapterRuntime, } from '../adapter/kernel/runtime.js';
 import { snapshotLiveSessionEvents } from './compat/liveSession.js';
+import { DEFAULT_PERMISSION_OPTIONS, } from '../channel/permissions.js';
 const approvalStores = new WeakMap();
 /** Host-only registration used by the TUI plugin bootstrap. */
 export function bindApprovalStore(ctx, store) {
@@ -221,7 +228,7 @@ export class ApprovalStore {
         const pending = this.active;
         this.snapshotCache = pending === undefined
             ? null
-            : { key: pending.key, ...pending.snapshot };
+            : { key: pending.key, ...pending.snapshot, options: DEFAULT_PERMISSION_OPTIONS };
     }
     /**
      * Re-run the source-badge verdict for the active ask (P-4).
@@ -388,16 +395,22 @@ export class ApprovalStore {
     /**
      * The user decided on the current approval; settles it and drains the
      * next queued ask if any. No-op when nothing is pending.
-     * @param outcome - `'allowed-once'` or `'rejected'`.
+     * @param outcome - `'allowed-once'` or `'rejected'`. The protocol has no
+     *   allow-always and the panel never offers it for a DSH ask; one arriving
+     *   anyway is refused (fail closed). The panel's option detail carries
+     *   nothing the protocol can use beyond its panel key.
      */
-    decide(outcome) {
+    decide(outcome, decision) {
         const pending = this.active;
         if (pending === undefined)
             return;
+        // A keystroke the withdrawn panel still handled answers nothing.
+        if (decision?.key !== undefined && decision.key !== pending.key)
+            return;
         this.noteConsumed(pending);
         this.active = undefined;
         this.rebuildSnapshot();
-        pending.resolve(outcome);
+        pending.resolve(outcome === 'allowed-once' ? 'allowed-once' : 'rejected');
         this.startNext();
         this.emit();
     }

package/lib/types/dsh-adapter/backend/session.d.ts

@@ -0,0 +1,64 @@
+/**
+ * DSH backend session: one `Agent` (plus the `AgentHandle` that owns its
+ * lifetime, when this process created or resumed it) presented as an
+ * `AgentSession`. Each session has its own `createDshTranslator` instance, so
+ * translator state (frame fence, open calls) lives as long as the session.
+ * Inbox, status and compaction-stream bus events become `pending.changed`,
+ * `session.status` and `compaction.progress`.
+ *
+ * DSH features that have no typed capability yet reach the agent through
+ * `capabilities.native.dsh` (only `src/dsh-adapter/**` may read it).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { AgentEvent } from '../../agent/events.js';
+import type { AgentSession } from '../../agent/session.js';
+import { type DshTranslator } from './translate.js';
+declare module '../../agent/capabilities.js' {
+    interface DshNative {
+        /** The live DSH agent this session drives. */
+        readonly agent: Agent;
+        /** The lifetime handle, when this session owns the agent's lifetime;
+         *  absent for a borrowed registry agent (agent-view attachment). */
+        readonly handle: AgentHandle | undefined;
+        /** The plugin context the session's listeners are installed on. */
+        readonly ctx: Context;
+        /** Raw durable events of the main session, in arrival order. Raw
+         *  listeners registered before `subscribe` run before the projector sees
+         *  the same event. */
+        subscribeRaw(listener: (event: SessionEvent) => void): () => void;
+        /** The durable session log snapshot (`/trace`, fold restore, seeds). */
+        rawHistory(): readonly SessionEvent[];
+        /**
+         * Synchronously translate a durable replay seed with this session's
+         * translator. The channel's adoption transactions replay inside a
+         * synchronous tail, which the async `history()` cannot serve.
+         */
+        translateReplay(events: readonly SessionEvent[]): readonly AgentEvent[];
+        /** Forget the translator's per-session state (paired with a projector reset). */
+        resetTranslation(): void;
+        /** The dsh-tools presenters, scoped to this session's agent. */
+        readonly presentCallView: DshTranslator['presentCallView'];
+        readonly presentResultView: DshTranslator['presentResultView'];
+    }
+}
+/** What a DSH session wraps: an owned handle, or an agent plus the handle
+ *  this process holds for it (`undefined` = a borrowed registry agent). */
+export type DshSessionTarget = AgentHandle | {
+    readonly agent: Agent;
+    readonly handle: AgentHandle | undefined;
+};
+/** Whether a value is an `AgentSession` rather than a raw DSH agent. */
+export declare function isAgentSession(value: unknown): value is AgentSession;
+/**
+ * Wrap a DSH agent (and the handle that owns it, if any) as an
+ * `AgentSession`. Creating the wrapper acquires nothing: listeners exist only
+ * while `subscribe`/`subscribeRaw` subscriptions are live, and only `dispose()`
+ * releases the handle.
+ */
+export declare function createDshSession(ctx: Context, target: DshSessionTarget): AgentSession;
+/** The lifetime handle of a DSH session this process created or resumed;
+ *  throws when the session borrows its agent (or is not a DSH session). */
+export declare function dshHandleOf(session: AgentSession): AgentHandle;
+//# sourceMappingURL=session.d.ts.map

package/lib/types/dsh-adapter/backend/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/backend/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,UAAU,EAA+B,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAc,YAAY,EAAoD,MAAM,wBAAwB,CAAA;AAIxH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAExE,OAAO,QAAQ,6BAA6B,CAAC;IAC3C,UAAU,SAAS;QACjB,8CAA8C;QAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;QACrB;4EACoE;QACpE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;QACxC,mEAAmE;QACnE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;QACrB;;8BAEsB;QACtB,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;QACjE,wEAAwE;QACxE,UAAU,IAAI,SAAS,YAAY,EAAE,CAAA;QACrC;;;;WAIG;QACH,eAAe,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,UAAU,EAAE,CAAA;QACvE,iFAAiF;QACjF,gBAAgB,IAAI,IAAI,CAAA;QACxB,gEAAgE;QAChE,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAA;QAC1D,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAA;KAC/D;CACF;AAED;2EAC2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,CAAA;AAUhH,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAIpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,YAAY,CA2OrF;AAED;2EAC2E;AAC3E,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAI9D"}

package/lib/types/dsh-adapter/backend/session.js

@@ -0,0 +1,291 @@
+import { createUserMessage, MessageId } from '@deepseek-ai/dsh-llm';
+import { isTokenDelta, tokenDeltaChars } from '../channel/usage.js';
+import { snapshotLiveSessionEvents } from '../compat/liveSession.js';
+import { createDshTranslator } from './translate.js';
+const SYNC = { replay: false, wake: 'sync' };
+const FRAME = { replay: false, wake: 'frame' };
+const QUIET = { replay: false, wake: 'none' };
+// The borrowed form always names its `handle` slot (possibly undefined);
+// anything else is the handle itself.
+const isHandle = (target) => !('handle' in target);
+/** Whether a value is an `AgentSession` rather than a raw DSH agent. */
+export function isAgentSession(value) {
+    return typeof value === 'object' && value !== null &&
+        typeof value.subscribe === 'function' &&
+        typeof value.capabilities === 'object';
+}
+/**
+ * Wrap a DSH agent (and the handle that owns it, if any) as an
+ * `AgentSession`. Creating the wrapper acquires nothing: listeners exist only
+ * while `subscribe`/`subscribeRaw` subscriptions are live, and only `dispose()`
+ * releases the handle.
+ */
+export function createDshSession(ctx, target) {
+    const agent = target.agent;
+    const handle = isHandle(target) ? target : target.handle;
+    // The tools registry is read lazily, once per session, on the first
+    // presenter call, so wrapping an agent touches no host service.
+    let tools;
+    const translatorDeps = {
+        tools: () => (tools ??= { registry: ctx.get('tools') }).registry,
+        scope: () => agent,
+        attachments: () => ctx.get('attachments'),
+    };
+    const translator = createDshTranslator(translatorDeps);
+    let disposed = false;
+    /** Inputs this session queued that the inbox has not claimed or discarded. */
+    const pending = new Map();
+    /**
+     * One `session/event` listener per subscription period, shared by raw and
+     * translated subscribers. Raw subscribers (the DSH extensions) see each
+     * main-session event before the translated batch reaches the projector, and
+     * the bus only ever sees one foreground listener. A removed install is
+     * inert.
+     */
+    const rawListeners = new Set();
+    const eventListeners = new Set();
+    let eventTap;
+    const tapEvents = () => {
+        if (eventTap !== undefined)
+            return;
+        let live = true;
+        const dispose = ctx.on('session/event', (subject, event) => {
+            if (!live || subject !== agent.session)
+                return;
+            for (const listener of [...rawListeners])
+                listener(event);
+            for (const listener of [...eventListeners])
+                listener(event);
+        });
+        eventTap = { dispose: () => { live = false; dispose(); } };
+    };
+    const untapEvents = () => {
+        if (rawListeners.size > 0 || eventListeners.size > 0 || eventTap === undefined)
+            return;
+        const tap = eventTap;
+        eventTap = undefined;
+        tap.dispose();
+    };
+    /** Every listener install is owned at once; a throwing unsubscriber does not
+     *  stop the rest (the first failure is rethrown after all ran). */
+    const disposeAll = (disposers) => {
+        let failure;
+        for (const dispose of disposers.splice(0)) {
+            try {
+                dispose();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (failure !== undefined)
+            throw failure;
+    };
+    const messageFor = (input) => {
+        // The channel's DSH input pipeline already built the durable message; its
+        // id is the clientMessageId the channel tracks pending/selection/context
+        // under. Any other caller gets a fresh message from its blocks.
+        const native = input.native;
+        if (native !== undefined && native.id === input.clientMessageId)
+            return native;
+        return createUserMessage({
+            content: (input.blocks ?? [{ type: 'text', text: input.text }]),
+            source: { kind: 'user' },
+        });
+    };
+    const native = {
+        kind: 'dsh',
+        agent,
+        handle,
+        ctx,
+        subscribeRaw(listener) {
+            const entry = (event) => listener(event);
+            rawListeners.add(entry);
+            try {
+                tapEvents();
+            }
+            catch (error) {
+                rawListeners.delete(entry);
+                throw error;
+            }
+            return () => {
+                rawListeners.delete(entry);
+                untapEvents();
+            };
+        },
+        rawHistory: () => snapshotLiveSessionEvents(agent.session),
+        translateReplay: (events) => translator.translateReplay(events),
+        resetTranslation: () => translator.reset(),
+        presentCallView: translator.presentCallView,
+        presentResultView: translator.presentResultView,
+    };
+    const session = {
+        get ref() { return { backendId: 'dsh', sessionId: String(agent.session.id) }; },
+        get cwd() {
+            return agent.session.header?.cwd ?? '';
+        },
+        get status() {
+            if (disposed)
+                return 'disposed';
+            return agent.status === 'running' ? 'running' : 'idle';
+        },
+        capabilities: {
+            pendingRetraction: {
+                remove(clientMessageId) {
+                    const removed = agent.inbox.remove(MessageId(clientMessageId));
+                    if (removed)
+                        pending.delete(clientMessageId);
+                    return removed;
+                },
+            },
+            native: { dsh: native },
+        },
+        // A throwaway translator: `history()` is a read, so it must neither reset
+        // the live translator's frame fence nor leave the replay's open calls in
+        // the live open-call ledger. (Adoption seeds still go through
+        // `native.translateReplay`, which is a deliberate live reset.)
+        history: () => Promise.resolve(createDshTranslator(translatorDeps).translateReplay(snapshotLiveSessionEvents(agent.session))),
+        subscribe(listener) {
+            // A callback the bus retained past unsubscription (a dispatch already
+            // in flight, an ABA rebind) is inert: nothing is translated for it.
+            let active = true;
+            const disposers = [() => { active = false; }];
+            const own = (dispose) => { disposers.push(dispose); };
+            try {
+                own(ctx.on('agent/status', ({ agent: subject, status }) => {
+                    if (!active || subject !== agent)
+                        return;
+                    listener([{ type: 'session.status', status }], QUIET);
+                }));
+                own(ctx.on('agent/disposed', ({ agent: subject }) => {
+                    if (!active || subject !== agent)
+                        return;
+                    disposed = true;
+                    listener([{ type: 'session.status', status: 'disposed' }], QUIET);
+                }));
+                /**
+                 * The inbox removed one message. Both events retire the pending entry;
+                 * the channel retires attached context only for a discard.
+                 * `agent/inbox/claimed` fires while the loop claims the batch, before
+                 * the resident `agent/pre-step` listener can append the attachment
+                 * (dsh-agent-loop: `inbox.claim()` → claimed event → `agent/pre-step`).
+                 */
+                const retire = (payload, how) => {
+                    if (!active || payload.agent !== agent)
+                        return;
+                    const messageId = payload.message?.id;
+                    if (typeof messageId !== 'string')
+                        return;
+                    pending.delete(messageId);
+                    const items = [...pending.values()];
+                    listener([how === 'claimed'
+                            ? { type: 'pending.changed', items, claimed: [messageId] }
+                            : { type: 'pending.changed', items, discarded: [messageId] }], QUIET);
+                };
+                own(ctx.on('agent/inbox/claimed', payload => retire(payload, 'claimed')));
+                own(ctx.on('agent/inbox/discarded', payload => retire(payload, 'discarded')));
+                const onEvent = (event) => {
+                    if (!active)
+                        return;
+                    // Legacy per-token chunks arrive as session events; they wake the
+                    // renderer frame-coalesced like live stream frames.
+                    listener(translator.translateEvent(event), event.type === 'assistant/chunk' ? FRAME : SYNC);
+                };
+                eventListeners.add(onEvent);
+                own(() => {
+                    eventListeners.delete(onEvent);
+                    untapEvents();
+                });
+                tapEvents();
+                // Live streaming (dsh 0.1.5+; older hosts never emit this): per-token
+                // chunks are transient attempt frames on this agent-scoped event, and
+                // the durable result still arrives through `session/event`. A start
+                // frame alone changes nothing visible, so it does not wake the
+                // renderer.
+                own(ctx.on('agent/assistant-stream', ({ agent: subject, frame }) => {
+                    if (!active || subject !== agent)
+                        return;
+                    listener(translator.translateFrame(frame), frame.type === 'chunk' ? FRAME : frame.type === 'end' ? SYNC : QUIET);
+                }));
+                // Live compaction progress. The summarizer is one `ctx.llm.stream()`
+                // call, so its chunks are the only sign of work between
+                // `compaction/start` and `compaction/end`. dsh-llm tags that call
+                // `purpose: 'compaction'`, and a manual compaction runs while the
+                // session is idle, so it cannot be mixed up with a turn's stream. Any
+                // other purpose or session gets the original iterable back.
+                // A summary stream that started while subscribed keeps reporting until
+                // it ends; the channel decides what a late report may still touch.
+                own(ctx.on('llm/stream', (options, next) => {
+                    const stream = next();
+                    if (!active || options.purpose !== 'compaction')
+                        return stream;
+                    if (options.sessionId === undefined || String(options.sessionId) !== String(agent.session.id))
+                        return stream;
+                    return (async function* compactionStream() {
+                        for await (const chunk of stream) {
+                            if (isTokenDelta(chunk))
+                                listener([{ type: 'compaction.progress', outputChars: tokenDeltaChars(chunk) }], FRAME);
+                            yield chunk;
+                        }
+                    })();
+                }));
+            }
+            catch (error) {
+                try {
+                    disposeAll(disposers);
+                }
+                catch { /* the install failure stays primary */ }
+                throw error;
+            }
+            return () => disposeAll(disposers);
+        },
+        // Synchronous by contract for DSH: steer/followup run before this returns,
+        // and a synchronous throw reaches the caller synchronously (the input
+        // pipeline rolls its bookkeeping back on it).
+        submit(input, placement) {
+            const message = messageFor(input);
+            const queued = placement === 'steer' ? 'steer' : 'followup';
+            pending.set(message.id, { id: message.id, text: input.text, placement: queued });
+            try {
+                if (placement === 'now')
+                    agent.cancel({ kind: 'user' });
+                if (placement === 'steer')
+                    agent.steer(message);
+                else
+                    agent.followup(message);
+            }
+            catch (error) {
+                pending.delete(message.id);
+                throw error;
+            }
+            return Promise.resolve({ accepted: true });
+        },
+        cancel(cause) {
+            // `user` keeps the queue, so queued/steered inputs run as the next turn.
+            // Every other cause drops it: after `interrupt` the channel parks those
+            // inputs in a dock and re-delivers nothing until the user sends it, and
+            // a switch/dispose never resumes the old queue. keepInbox is only for
+            // the user-cancel and normal turn-end paths.
+            if (cause === 'user')
+                agent.cancel({ kind: 'user' }, { keepInbox: true });
+            else
+                agent.cancel({ kind: 'user' });
+            // The kernel cancel settles its bookkeeping synchronously: the answer
+            // is definitive either way (kept ids for a 'user' cancel, an emptied
+            // queue otherwise).
+            return Promise.resolve({ stillQueued: cause === 'user' ? [...pending.keys()] : [], outcome: 'confirmed' });
+        },
+        dispose() {
+            return handle === undefined ? Promise.resolve() : handle.dispose();
+        },
+    };
+    return session;
+}
+/** The lifetime handle of a DSH session this process created or resumed;
+ *  throws when the session borrows its agent (or is not a DSH session). */
+export function dshHandleOf(session) {
+    const handle = session.capabilities.native.dsh?.handle;
+    if (handle === undefined)
+        throw new Error(`dsh-tui: session ${session.ref.backendId}:${session.ref.sessionId} owns no DSH handle`);
+    return handle;
+}

package/lib/types/dsh-adapter/backend/translate.d.ts

@@ -0,0 +1,58 @@
+/**
+ * DSH to Agent Domain translator: decodes durable DSH `SessionEvent`s and
+ * transient `agent/assistant-stream` frames into `AgentEvent`s for the shared
+ * projector (`src/channel/projection.ts`). All DSH-specific knowledge the
+ * projector needs lives here: message source kinds, compaction checkpoint
+ * sources, the 0.1.7 tool result payload shape, goal payloads,
+ * `request/header` model/effort, the optional todo/preset/colour/compaction
+ * plugin events, subagent and `ask_user_question` tool names, `job_output`
+ * reads and background-start acks, durable image attachments and the
+ * dsh-tools presenters.
+ *
+ * State is kept small: the frame revision fence (transport-level dedupe) and
+ * the open calls whose results still need a presenter. Attempt binding and
+ * `seq` idempotency belong to the projector, so a projector reset (`/clear`)
+ * does not depend on translator state.
+ */
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type AgentEvent, type AgentEventType } from '../../agent/events.js';
+import type { PricingWindow } from '../../channel/usage.js';
+import type { ToolCallView, ToolResultView, ToolsRegistryLike } from '../channel/types.js';
+export interface DshTranslatorDeps {
+    /** The host-plane tools registry (dsh-tools); absent in bare embedders,
+     *  where every presenter call falls back to a plain text card. Read per
+     *  presenter call (a session wrapper memoizes it). */
+    tools(): ToolsRegistryLike | undefined;
+    /** Presenter scope: the live agent, so preset-owned tool definitions
+     *  resolve (the dsh-host-apiproxy presenter pattern). Read per call. */
+    scope(): unknown;
+    /** DSH attachment service, resolved at call time (a late-mounted provider
+     *  must still serve images for rows projected earlier). */
+    attachments(): unknown;
+}
+/**
+ * DeepSeek's rate windows, injected into the shared projector as its
+ * `pricingWindow`: each usage buckets by the time its request ran.
+ */
+export declare function dshPricingWindow(time: number): PricingWindow;
+/**
+ * The DSH backend's decision for every Agent Domain event type: whether this
+ * translator (or its session, for the bus-derived `session.status`,
+ * `pending.changed` and `compaction.progress`) ever emits it. The exhaustive
+ * switch is the point: a new `AgentEvent` variant fails `tsc` here until the
+ * DSH side decides, and `verify:agent-domain` checks every translated fixture
+ * event against it.
+ */
+export declare function dshEmits(type: AgentEventType): boolean;
+/** Create one translator; it serves exactly one session's event stream. */
+export declare function createDshTranslator(deps: DshTranslatorDeps): {
+    translateEvent: (event: SessionEvent) => readonly AgentEvent[];
+    translateFrame: (frame: AssistantStreamFrame) => readonly AgentEvent[];
+    translateReplay: (events: readonly SessionEvent[]) => readonly AgentEvent[];
+    reset: () => void;
+    presentCallView: (name: string, rawArgs: string) => ToolCallView | undefined;
+    presentResultView: (name: string, rawArgs: string, data: SessionEvent<"tool/result">["data"]) => ToolResultView | undefined;
+};
+export type DshTranslator = ReturnType<typeof createDshTranslator>;
+//# sourceMappingURL=translate.d.ts.map

package/lib/types/dsh-adapter/backend/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/backend/translate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,0BAA0B,CAAA;AAC/F,OAAO,EAAa,KAAK,UAAU,EAAqB,KAAK,cAAc,EAA0D,MAAM,uBAAuB,CAAA;AAElK,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAI3D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAI1F,MAAM,WAAW,iBAAiB;IAChC;;0DAEsD;IACtD,KAAK,IAAI,iBAAiB,GAAG,SAAS,CAAA;IACtC;4EACwE;IACxE,KAAK,IAAI,OAAO,CAAA;IAChB;+DAC2D;IAC3D,WAAW,IAAI,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAkEtD;AA6FD,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB;4BAgI1B,YAAY,KAAG,SAAS,UAAU,EAAE;4BAsJpC,oBAAoB,KAAG,SAAS,UAAU,EAAE;8BAmB1C,SAAS,YAAY,EAAE,KAAG,SAAS,UAAU,EAAE;iBAU9D,IAAI;4BAnSS,MAAM,WAAW,MAAM,KAAG,YAAY,GAAG,SAAS;8BAYhD,MAAM,WAAW,MAAM,QAAQ,YAAY,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAG,cAAc,GAAG,SAAS;EA6RjI;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}