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

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"}