@deepseek-harness-tui/dsh-tui 0.10.0 → 0.10.2

package/lib/types/dsh-adapter/channel/binding-events.d.ts

@@ -0,0 +1,65 @@
+import type { AssistantStreamFrame, ModelSelectionRef } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { InputConvergence } from './input-actions.js';
+import type { ChannelBinding } from './binding.js';
+import type { ChannelOwner } from './owner.js';
+import { type createChannelProjection } from './projection.js';
+import type { ChannelState } from './types.js';
+/**
+ * The binding event router is the sole subscriber for a foreground Agent.
+ * It captures the binding generation at every listener entry; teardown is
+ * incremental and retained callbacks check that captured Agent/session pair
+ * before touching state. Transcript presentation remains exclusively owned by
+ * ChannelProjection.
+ */
+export declare function createBindingEvents(ctx: Context, deps: {
+    owner: ChannelOwner;
+    binding: ChannelBinding;
+    state: ChannelState;
+    activity: {
+        start(agent: ChannelBinding['agent']): void;
+        stop(): void;
+        onAgentStatus(status: ChannelBinding['agent']['status']): unknown;
+        onSessionEvent(event: unknown): unknown;
+    };
+    inputConvergence: InputConvergence;
+    selection: ModelSelectionRef;
+    modelActions: {
+        applyPreferredEffort(): Promise<void>;
+        selection: ModelSelectionRef;
+    };
+    modeActions: {
+        refreshMode(): void;
+        onSessionEvent(session: unknown, event: unknown): void;
+    };
+    projector: ReturnType<typeof createChannelProjection>;
+    subagents: {
+        onSessionEvent(session: unknown, event: unknown): boolean;
+        onStreamFrame?(agent: unknown, frame: AssistantStreamFrame): boolean;
+        onStart(info: {
+            id: string;
+            runId?: string;
+            provider: string;
+            local?: boolean;
+        }): void;
+        onEnd(info: {
+            id: string;
+            stopReason: string;
+            lastAssistantMessage?: unknown[];
+        }): void;
+    };
+    agentView: {
+        schedule(): void;
+    };
+    messageObserver?: {
+        publish(session: unknown, event: unknown): void;
+    };
+    /** Drop a pre-step attachment registered by this channel for one message id
+     *  (input-delivery's `retireAttachment`); see the discard hook below.
+     *  Optional for direct/embed constructors that never emit inbox discards;
+     *  channel.ts always wires it. */
+    retireAttachment?(messageId: string): void;
+}): {
+    bind: () => void;
+};
+//# sourceMappingURL=binding-events.d.ts.map

package/lib/types/dsh-adapter/channel/binding-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-events.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/binding-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;IACtD,KAAK,EAAE,YAAY,CAAA;IACnB,OAAO,EAAE,cAAc,CAAA;IACvB,KAAK,EAAE,YAAY,CAAA;IACnB,QAAQ,EAAE;QACR,KAAK,CAAC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;QAC3C,IAAI,IAAI,IAAI,CAAA;QACZ,aAAa,CAAC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAA;QACjE,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAA;KACxC,CAAA;IACD,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,YAAY,EAAE;QAAE,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,SAAS,EAAE,iBAAiB,CAAA;KAAE,CAAA;IACrF,WAAW,EAAE;QAAE,WAAW,IAAI,IAAI,CAAC;QAAC,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;IAC5F,SAAS,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;IACrD,SAAS,EAAE;QAAE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAC,aAAa,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAA;IAC/T,SAAS,EAAE;QAAE,QAAQ,IAAI,IAAI,CAAA;KAAE,CAAA;IAC/B,eAAe,CAAC,EAAE;QAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;IACrE;;;sCAGkC;IAClC,gBAAgB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3C;gBAYkB,IAAI;EAgItB"}

package/lib/types/dsh-adapter/channel/binding-events.js

@@ -0,0 +1,169 @@
+/**
+ * The binding event router is the sole subscriber for a foreground Agent.
+ * It captures the binding generation at every listener entry; teardown is
+ * incremental and retained callbacks check that captured Agent/session pair
+ * before touching state. Transcript presentation remains exclusively owned by
+ * ChannelProjection.
+ */
+export function createBindingEvents(ctx, deps) {
+    const reconcileRetiredProjection = (status) => {
+        if (!deps.state.working)
+            return;
+        ctx.logger.warn(`dsh-tui: agent became ${status} while the channel still projected an open turn; releasing volatile UI gates`);
+        deps.inputConvergence.cancelInFlight = false;
+        deps.state.cancelPending = false;
+        deps.state.working = false;
+        deps.state.activeToolCount = 0;
+        deps.projector.settleStreaming();
+        deps.projector.updateSpinnerMode();
+    };
+    const bind = () => {
+        try {
+            deps.state.agentBindingGeneration = deps.binding.bind();
+            deps.inputConvergence.cancelInFlight = false;
+            deps.inputConvergence.interruptSeq += 1;
+            deps.activity.start(deps.binding.agent);
+            deps.modelActions.selection.current = undefined;
+            deps.modelActions.selection.assembled = undefined;
+            if (deps.binding.agent.options?.model === undefined && deps.state.provider !== '' && deps.state.model !== '') {
+                deps.modelActions.selection.current = { provider: deps.state.provider, model: deps.state.model };
+            }
+            void deps.modelActions.applyPreferredEffort();
+            deps.modeActions.refreshMode();
+            const capture = deps.binding.capture();
+            const session = capture.agent.session;
+            const current = () => deps.owner.current() && deps.binding.isCurrent(capture);
+            const register = (dispose) => {
+                deps.binding.subscribe(dispose);
+                return dispose;
+            };
+            const on = (...args) => register(ctx.on(...args));
+            // Keep the upstream assembly/request pairing, but own each listener as
+            // soon as it is installed. The upstream combined disposer is too late
+            // if request registration throws, and its post-await assembly write is
+            // unsafe after a rebind (including A→B→A ABA).
+            const disposeAssembly = capture.agent.ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+                const selected = deps.selection.current;
+                const assembled = await next();
+                if (!current())
+                    return assembled;
+                deps.selection.assembled = selected;
+                if (selected === undefined)
+                    return assembled;
+                return {
+                    ...assembled,
+                    variables: {
+                        ...assembled.variables,
+                        provider: selected.provider,
+                        model: selected.model,
+                    },
+                };
+            });
+            register(disposeAssembly);
+            const disposeRequest = capture.agent.ctx.on('agent/request', async (_payload, next) => {
+                const resolved = await next();
+                if (!current())
+                    return resolved;
+                const selected = deps.selection.assembled;
+                if (selected === undefined)
+                    return resolved;
+                const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = resolved;
+                return {
+                    ...withoutInheritedEffort,
+                    provider: selected.provider,
+                    model: selected.model,
+                    ...(selected.reasoningEffort === undefined ? {} : { reasoningEffort: selected.reasoningEffort }),
+                };
+            });
+            register(disposeRequest);
+            on('agent/status', ({ agent: subject, status }) => {
+                if (!current() || subject !== capture.agent)
+                    return;
+                deps.state.status = status;
+                deps.activity.onAgentStatus(status);
+                if (status === 'idle')
+                    reconcileRetiredProjection('idle');
+                deps.state.emit();
+            });
+            on('agent/disposed', ({ agent: subject }) => {
+                if (!current() || subject !== capture.agent)
+                    return;
+                deps.state.status = 'disposed';
+                deps.activity.stop();
+                reconcileRetiredProjection('disposed');
+                deps.state.emit();
+            });
+            /**
+             * The inbox removed one message. Both events retire the pending
+             * preview, but ONLY a discard retires an attached-context entry:
+             * `agent/inbox/claimed` fires while the loop claims the batch, BEFORE
+             * the resident `agent/pre-step` listener can append the attachment —
+             * retiring there would delete the context before it is ever injected
+             * (dsh-agent-loop: `inbox.claim()` → claimed event → `agent/pre-step`).
+             */
+            const retirePending = (payload, alsoRetireAttachment = false) => {
+                if (!current() || payload.agent !== capture.agent)
+                    return;
+                const messageId = payload.message?.id;
+                if (typeof messageId !== 'string')
+                    return;
+                if (alsoRetireAttachment)
+                    deps.retireAttachment?.(messageId);
+                const before = deps.state.pending.length;
+                deps.state.pending = deps.state.pending.filter(item => item.id !== messageId);
+                if (deps.state.pending.length !== before)
+                    deps.state.emit();
+            };
+            on('agent/inbox/claimed', retirePending);
+            on('agent/inbox/discarded', payload => retirePending(payload, true));
+            on('session/event', (subject, event) => {
+                if (!current())
+                    return;
+                const isMainSession = subject === session;
+                if (!isMainSession && deps.subagents.onSessionEvent(subject, event))
+                    return;
+                if (!isMainSession)
+                    return;
+                deps.messageObserver?.publish(subject, event);
+                deps.activity.onSessionEvent(event);
+                deps.modeActions.onSessionEvent(subject, event);
+                deps.projector.renderEvent(event);
+                if (event.type === 'assistant/chunk')
+                    deps.state.emitStream();
+                else
+                    deps.state.emit();
+            });
+            // 0.1.5 live streaming: per-token chunks are transient attempt frames
+            // on this agent-scoped channel; the durable settlement still arrives
+            // through `session/event` above. Pre-0.1.5 hosts never emit it — the
+            // subscription simply stays silent there and chunks keep arriving as
+            // `assistant/chunk` session events.
+            on('agent/assistant-stream', ({ agent: subject, frame }) => {
+                if (!current())
+                    return;
+                if (subject !== capture.agent) {
+                    deps.subagents.onStreamFrame?.(subject, frame);
+                    return;
+                }
+                deps.projector.renderStreamFrame(frame);
+                if (frame.type === 'chunk')
+                    deps.state.emitStream();
+                else if (frame.type === 'end')
+                    deps.state.emit();
+            });
+            on('subagent/start', (info) => {
+                if (current())
+                    deps.subagents.onStart(info);
+            });
+            on('subagent/end', (info) => {
+                if (current())
+                    deps.subagents.onEnd(info);
+            });
+        }
+        catch (error) {
+            deps.owner.dispose();
+            throw error;
+        }
+    };
+    return { bind };
+}

package/lib/types/dsh-adapter/channel/binding.d.ts

@@ -0,0 +1,41 @@
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { ChannelOwner } from './owner.js';
+export interface BindingCapture {
+    readonly agent: Agent;
+    readonly generation: number;
+}
+export interface BindingCommit {
+    readonly agent: Agent;
+    readonly handle: AgentHandle | undefined;
+    readonly generation: number;
+}
+type PreviousDisposition = 'dispose' | 'park';
+/**
+ * Sole writer of the attached Agent/handle identity and binding generation.
+ *
+ * A prepared handle remains owned by this cell until its synchronous adoption
+ * tail returns.  The tail is deliberately callback-shaped: it cannot leave a
+ * committed identity waiting for a microtask watchdog to infer whether setup
+ * completed, and a throw always revokes the transaction immediately.
+ */
+export declare function createChannelBinding(initial: Agent, handle: AgentHandle | undefined, owner: ChannelOwner): {
+    readonly agent: Agent;
+    readonly handle: AgentHandle | undefined;
+    readonly generation: number;
+    capture(): BindingCapture;
+    isCurrent(capture: BindingCapture): boolean;
+    /** Create a candidate without giving it authority over the live binding. */
+    prepare(capture: BindingCapture, create: () => Promise<AgentHandle>): Promise<AgentHandle>;
+    /** Dispose an uncommitted candidate exactly once. Live handles are inert. */
+    abandon(candidate: AgentHandle): Promise<void>;
+    /** Perform one explicit synchronous prepared-handle adoption transaction. */
+    adopt: <T>(candidate: AgentHandle, capture: BindingCapture, tail: (previous: BindingCommit, disposition: (next: PreviousDisposition) => void) => T) => T;
+    /** Perform one explicit synchronous already-live-agent adoption transaction. */
+    switchTo: <T>(agent: Agent, nextHandle: AgentHandle | undefined, tail: (previous: BindingCommit, disposition: (next: PreviousDisposition) => void) => T) => T;
+    bind(): number;
+    subscribe(dispose: () => void): void;
+    clearSubscriptions: (afterEach?: () => void) => unknown;
+};
+export type ChannelBinding = ReturnType<typeof createChannelBinding>;
+export {};
+//# sourceMappingURL=binding.d.ts.map

package/lib/types/dsh-adapter/channel/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,KAAK,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAAA;AAE7C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,KAAK,EAAE,YAAY;;;;eAiK1F,cAAc;uBACN,cAAc;IAEjC,4EAA4E;qBACrD,cAAc,UAAU,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBhG,6EAA6E;uBACpD,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAEpD,6EAA6E;YAvIhE,CAAC,aACH,WAAW,WACb,cAAc,QACjB,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,KAAK,CAAC,KACrF,CAAC;IAqIF,gFAAgF;eA5EhE,CAAC,SACV,KAAK,cACA,WAAW,GAAG,SAAS,QAC7B,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,KAAK,CAAC,KACrF,CAAC;;uBAsFiB,MAAM,IAAI;qCAvLS,MAAM,IAAI,KAAG,OAAO;EA0L7D;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA"}

package/lib/types/dsh-adapter/channel/binding.js

@@ -0,0 +1,227 @@
+/**
+ * Sole writer of the attached Agent/handle identity and binding generation.
+ *
+ * A prepared handle remains owned by this cell until its synchronous adoption
+ * tail returns.  The tail is deliberately callback-shaped: it cannot leave a
+ * committed identity waiting for a microtask watchdog to infer whether setup
+ * completed, and a throw always revokes the transaction immediately.
+ */
+export function createChannelBinding(initial, handle, owner) {
+    let currentAgent = initial;
+    let currentHandle = handle;
+    let generation = 0;
+    let started = false;
+    let subscriptions = [];
+    let handoff;
+    const pending = new Map();
+    const disposed = new WeakSet();
+    const dispose = (candidate) => {
+        if (disposed.has(candidate))
+            return;
+        disposed.add(candidate);
+        void candidate.dispose().catch(() => undefined);
+    };
+    const disposePending = (candidate) => {
+        if (!pending.delete(candidate))
+            return;
+        dispose(candidate);
+    };
+    const clearSubscriptions = (afterEach) => {
+        const active = subscriptions.splice(0);
+        let failure;
+        // A bad unsubscriber must not prevent the rest of a binding's cleanup.
+        for (const unsubscribe of active) {
+            try {
+                unsubscribe();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+            // Every unsubscriber is external code and can revoke the owner or try a
+            // rival handoff. Record that state before running the next cleanup.
+            try {
+                afterEach?.();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        return failure;
+    };
+    const isCaptureCurrent = (capture) => owner.current() && capture.agent === currentAgent && capture.generation === generation;
+    const assertPrepared = (candidate, capture) => {
+        if (pending.get(candidate) !== capture || !isCaptureCurrent(capture)) {
+            disposePending(candidate);
+            throw new Error('dsh-tui: Channel binding changed before adoption');
+        }
+    };
+    const settlePrevious = (previous, disposition) => {
+        // Parking deliberately transfers ownership to the caller's background
+        // ledger. Disposal is centralised here so no adoption tail can double-call
+        // an old handle while its transaction is being revoked.
+        if (disposition === 'dispose' && previous.handle !== undefined && previous.handle !== currentHandle) {
+            dispose(previous.handle);
+        }
+    };
+    owner.own(clearSubscriptions);
+    owner.own(() => { for (const candidate of [...pending.keys()])
+        disposePending(candidate); });
+    const adopt = (candidate, capture, tail) => {
+        if (handoff !== undefined) {
+            // Mark the outer transaction superseded as well as rejecting this one;
+            // letting its tail return success after a reentrant handoff attempt
+            // would publish a binding whose cleanup authority was contested.
+            handoff = undefined;
+            disposePending(candidate);
+            throw new Error('dsh-tui: Channel binding handoff is already in progress');
+        }
+        assertPrepared(candidate, capture);
+        const token = Symbol('channel-binding-handoff');
+        handoff = token;
+        const previous = { agent: currentAgent, handle: currentHandle, generation };
+        let disposition;
+        const decidePrevious = (next) => {
+            if (disposition === undefined || disposition === next) {
+                disposition = next;
+                return;
+            }
+            throw new Error('dsh-tui: Channel binding previous disposition changed');
+        };
+        let succeeded = false;
+        try {
+            const cleanupFailure = clearSubscriptions(() => {
+                if (handoff !== token || !isCaptureCurrent(capture) || pending.get(candidate) !== capture) {
+                    throw new Error('dsh-tui: Channel binding changed before adoption');
+                }
+            });
+            if (cleanupFailure !== undefined)
+                throw cleanupFailure;
+            // Unsubscription is external code: it can revoke the owner or attempt a
+            // rival adoption. Never write a candidate after either event.
+            if (handoff !== token)
+                throw new Error('dsh-tui: Channel binding handoff was superseded');
+            assertPrepared(candidate, capture);
+            pending.delete(candidate);
+            currentAgent = candidate.agent;
+            currentHandle = candidate;
+            generation += 1;
+            const result = tail(previous, decidePrevious);
+            // Tail callbacks include notifier/listener code and therefore remain a
+            // synchronous reentrancy boundary even though they contain no await.
+            if (handoff !== token || !owner.current() || currentHandle !== candidate) {
+                throw new Error('dsh-tui: Channel binding changed during adoption');
+            }
+            succeeded = true;
+            return result;
+        }
+        catch (error) {
+            // This candidate is transaction-owned, unlike the baseline live handle
+            // which ordinary UI owner teardown only unsubscribes from.
+            if (currentHandle === candidate) {
+                currentHandle = undefined;
+            }
+            dispose(candidate);
+            owner.dispose();
+            throw error;
+        }
+        finally {
+            settlePrevious(previous, succeeded ? disposition ?? 'dispose' : 'dispose');
+            if (handoff === token)
+                handoff = undefined;
+        }
+    };
+    const switchTo = (agent, nextHandle, tail) => {
+        owner.assertActive();
+        if (handoff !== undefined) {
+            handoff = undefined;
+            throw new Error('dsh-tui: Channel binding handoff is already in progress');
+        }
+        const token = Symbol('channel-binding-handoff');
+        handoff = token;
+        const previous = { agent: currentAgent, handle: currentHandle, generation };
+        let disposition;
+        const decidePrevious = (next) => {
+            if (disposition === undefined || disposition === next) {
+                disposition = next;
+                return;
+            }
+            throw new Error('dsh-tui: Channel binding previous disposition changed');
+        };
+        let succeeded = false;
+        try {
+            const cleanupFailure = clearSubscriptions(() => {
+                if (handoff !== token || !owner.current())
+                    throw new Error('dsh-tui: Channel binding changed during adoption');
+            });
+            if (cleanupFailure !== undefined)
+                throw cleanupFailure;
+            if (handoff !== token || !owner.current())
+                throw new Error('dsh-tui: Channel binding changed during adoption');
+            currentAgent = agent;
+            currentHandle = nextHandle;
+            generation += 1;
+            const result = tail(previous, decidePrevious);
+            if (handoff !== token || !owner.current() || currentAgent !== agent || currentHandle !== nextHandle) {
+                throw new Error('dsh-tui: Channel binding changed during adoption');
+            }
+            succeeded = true;
+            return result;
+        }
+        catch (error) {
+            // An already-live agent is not a prepared candidate.  Revocation leaves
+            // its owner to decide disposal, preserving the baseline teardown rule.
+            owner.dispose();
+            throw error;
+        }
+        finally {
+            settlePrevious(previous, succeeded ? disposition ?? 'dispose' : 'dispose');
+            if (handoff === token)
+                handoff = undefined;
+        }
+    };
+    return {
+        get agent() { return currentAgent; },
+        get handle() { return currentHandle; },
+        get generation() { return generation; },
+        capture() { return { agent: currentAgent, generation }; },
+        isCurrent(capture) { return isCaptureCurrent(capture); },
+        /** Create a candidate without giving it authority over the live binding. */
+        async prepare(capture, create) {
+            owner.assertActive();
+            if (!isCaptureCurrent(capture))
+                throw new Error('dsh-tui: Channel binding changed before preparation');
+            const candidate = await create();
+            if (!isCaptureCurrent(capture)) {
+                dispose(candidate);
+                throw new Error('dsh-tui: Channel binding changed during preparation');
+            }
+            pending.set(candidate, capture);
+            // Owner disposal may synchronously occur through embedding hooks while
+            // ownership is registered; verify the pending entry itself as well.
+            if (!isCaptureCurrent(capture) || pending.get(candidate) !== capture) {
+                disposePending(candidate);
+                throw new Error('dsh-tui: Channel binding changed during preparation');
+            }
+            return candidate;
+        },
+        /** Dispose an uncommitted candidate exactly once. Live handles are inert. */
+        async abandon(candidate) { disposePending(candidate); },
+        /** Perform one explicit synchronous prepared-handle adoption transaction. */
+        adopt,
+        /** Perform one explicit synchronous already-live-agent adoption transaction. */
+        switchTo,
+        // bindAgent is still responsible for constructing the typed subscriptions.
+        // Initial activation establishes generation 1; later rebinds have already
+        // advanced the generation inside their adoption transaction.
+        bind() {
+            owner.assertActive();
+            if (!started) {
+                started = true;
+                generation += 1;
+            }
+            return generation;
+        },
+        subscribe(dispose) { subscriptions.push(dispose); },
+        clearSubscriptions,
+    };
+}

package/lib/types/dsh-adapter/channel/command-completions.d.ts

@@ -0,0 +1,29 @@
+import { type CommandCompletionNode } from '../../commands.js';
+import { listThemeCatalog } from '../../themeCatalog.js';
+import type { ChannelState } from './types.js';
+/** Owns slash completion composition and cache warming; it has no lifecycle effects. */
+export declare function createCommandCompletions(deps: {
+    state: () => ChannelState;
+    themeHost: Parameters<typeof listThemeCatalog>[0];
+    commandTrees?: {
+        children(path: readonly string[]): readonly CommandCompletionNode[];
+    };
+    workspaceCommands(): readonly {
+        name: string;
+        aliases?: readonly string[];
+        description?: string;
+    }[];
+    model: {
+        warmModelNodes(): void;
+        modelNodes(): readonly CommandCompletionNode[];
+        warmPresetOptions(): void;
+        presetOptions(): readonly {
+            id: string;
+            description?: string;
+            name?: string;
+            isDefault?: boolean;
+        }[];
+        warmEffortLevels(): void;
+    };
+}): (input: string) => import("../../commands.js").CommandCompletion[];
+//# sourceMappingURL=command-completions.d.ts.map

package/lib/types/dsh-adapter/channel/command-completions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-completions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/command-completions.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAI1G,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,KAAK,EAAE,MAAM,YAAY,CAAA;IACzB,SAAS,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;IACjD,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;KAAE,CAAA;IACtF,iBAAiB,IAAI,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACnG,KAAK,EAAE;QACL,cAAc,IAAI,IAAI,CAAA;QACtB,UAAU,IAAI,SAAS,qBAAqB,EAAE,CAAA;QAC9C,iBAAiB,IAAI,IAAI,CAAA;QACzB,aAAa,IAAI,SAAS;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,OAAO,CAAA;SAAE,EAAE,CAAA;QACpG,gBAAgB,IAAI,IAAI,CAAA;KACzB,CAAA;CACF,IAES,OAAO,MAAM,qDAyEtB"}

package/lib/types/dsh-adapter/channel/command-completions.js

@@ -0,0 +1,94 @@
+import { completeCommands, isCommandCompletionToken } from '../../commands.js';
+import { SESSION_COLOR_NAMES } from '../../terminal-utils/sessionColors.js';
+import { getLang, LANGS } from '../../i18n.js';
+import { AUTO_THEME_NAME } from '../../theme.js';
+import { listThemeCatalog } from '../../themeCatalog.js';
+import { PRESET_NAMES } from '../../components/activityFrames.js';
+/** Owns slash completion composition and cache warming; it has no lifecycle effects. */
+export function createCommandCompletions(deps) {
+    const { themeHost, commandTrees, workspaceCommands, model } = deps;
+    return (input) => {
+        const state = deps.state();
+        const head = input.slice(1).split(/[\t ]/)[0]?.toLowerCase() ?? '';
+        if (head !== '') {
+            if ('model'.startsWith(head))
+                model.warmModelNodes();
+            if ('preset'.startsWith(head))
+                model.warmPresetOptions();
+            if ('effort'.startsWith(head))
+                model.warmEffortLevels();
+        }
+        return completeCommands(input, state.commandList, path => {
+            if (path.length === 1 && path[0] === 'model') {
+                model.warmModelNodes();
+                return model.modelNodes();
+            }
+            if (path.length === 1 && path[0] === 'lang')
+                return [
+                    { name: 'status', description: 'Show the current UI language', descriptionKey: 'sugg-status-desc' },
+                    ...LANGS.map(lang => ({ name: lang, description: `Switch the UI language to ${lang}`, descriptionKey: lang === 'zh' ? 'sugg-lang-zh-desc' : 'sugg-lang-en-desc', ...(getLang() === lang ? { tag: 'current' } : {}) })),
+                ];
+            if (path.length === 1 && path[0] === 'theme')
+                return [
+                    { name: 'status', description: 'Show the current theme', descriptionKey: 'sugg-status-desc' },
+                    { name: AUTO_THEME_NAME, description: 'Follow the terminal background', descriptionKey: 'sugg-theme-auto-desc' },
+                    ...listThemeCatalog(themeHost).filter(entry => entry.name !== AUTO_THEME_NAME).map(entry => {
+                        const base = entry.base ?? 'dark';
+                        if (entry.source === 'builtin')
+                            return { name: entry.name, description: `Built-in theme ${entry.name}`, descriptionKey: 'sugg-theme-builtin-desc' };
+                        if (entry.source === 'runtime')
+                            return { name: entry.name, description: `Plugin theme (${base} base)`, descriptionKey: 'sugg-theme-plugin-desc' };
+                        return { name: entry.name, description: `User theme (${base} base)`, descriptionKey: 'sugg-theme-user-desc' };
+                    }),
+                ];
+            if (path.length === 1 && path[0] === 'color')
+                return [
+                    { name: 'status', description: 'Show the current session color', descriptionKey: 'sugg-status-desc' },
+                    { name: 'reset', description: 'Clear the session color', descriptionKey: 'sugg-color-reset-desc' },
+                    ...SESSION_COLOR_NAMES.map(name => ({ name, description: 'Session accent color', descriptionKey: 'sugg-color-name-desc', ...(state.sessionColor === name ? { tag: 'current' } : {}) })),
+                ];
+            if (path.length === 1 && path[0] === 'effort') {
+                model.warmEffortLevels();
+                return [{ name: 'status', description: 'Show the current reasoning effort', descriptionKey: 'sugg-status-desc' }, ...(state.effortLevels ?? []).map(id => ({ name: id, description: 'Reasoning effort level', descriptionKey: 'sugg-effort-level-desc', ...(state.reasoningEffort === id ? { tag: 'current' } : {}) }))];
+            }
+            if (path.length === 1 && path[0] === 'preset') {
+                model.warmPresetOptions();
+                return [{ name: 'status', description: 'Show the current agent preset', descriptionKey: 'sugg-status-desc' }, ...model.presetOptions().map(preset => ({ name: preset.id, description: preset.description ?? preset.name ?? preset.id, ...(preset.id === state.agentPreset ? { tag: 'current' } : preset.isDefault ? { tag: 'default' } : {}) }))];
+            }
+            if (path.length === 1 && path[0] === 'activity')
+                return [
+                    { name: 'status', description: 'Show the current activity preset', descriptionKey: 'sugg-status-desc' },
+                    { name: 'frames', description: 'List or switch frame presets', descriptionKey: 'sugg-activity-frames-desc' },
+                ];
+            if (path.length === 2 && path[0] === 'activity' && path[1] === 'frames')
+                return PRESET_NAMES.map(name => ({ name, description: 'Animation frame preset', descriptionKey: 'sugg-activity-frame-desc', ...(state.activityFrames === name ? { tag: 'current' } : {}) }));
+            if (path.length === 1 && path[0] === 'workspace') {
+                const builtins = [
+                    { name: 'resume', description: 'Switch to another workspace', descriptionKey: 'cmd-desc-workspace-resume' },
+                    { name: 'rename', description: 'Rename the current workspace', descriptionKey: 'cmd-desc-workspace-rename' },
+                    { name: 'open', description: 'Open a path or workspace URI', descriptionKey: 'cmd-desc-workspace-open' },
+                ];
+                const reserved = new Set(builtins.map(command => command.name));
+                return [...builtins, ...workspaceCommands().filter(command => !reserved.has(command.name.toLowerCase())).map(command => ({
+                        name: command.name,
+                        ...(command.aliases === undefined ? {} : { aliases: command.aliases }),
+                        description: command.description ?? '',
+                    }))];
+            }
+            if (path.length === 1 && path[0] === 'permission') {
+                const snapshot = state.permissionPresets();
+                return snapshot.options.filter(option => isCommandCompletionToken(option.value)).map(option => ({
+                    name: option.value, description: option.description ?? option.name,
+                    ...(option.value === 'read-only' ? { descriptionKey: 'permission-preset-readonly-desc' } : option.value === 'workspace-write' ? { descriptionKey: 'permission-preset-workspace-write-desc' } : option.value === 'danger-full-access' ? { descriptionKey: 'permission-preset-full-access-desc' } : {}),
+                    ...(snapshot.current?.kind === 'preset' && snapshot.current.value === option.value ? { tag: 'current' } : {}),
+                }));
+            }
+            if (path.length === 1 && path[0] === 'plan')
+                return [
+                    { name: 'on', description: 'Enter plan mode: read-only, plan before acting', descriptionKey: 'plan-mode-on-desc' },
+                    { name: 'off', description: 'Exit plan mode, back to normal execution', descriptionKey: 'plan-mode-off-desc' },
+                ];
+            return commandTrees?.children(path) ?? [];
+        });
+    };
+}

package/lib/types/dsh-adapter/channel/commands.d.ts

@@ -0,0 +1,8 @@
+/** Internal command composition follows the same production UI dispatcher.
+ * A bare createChannel embedder intentionally keeps its direct local API.
+ */
+import type { ChannelUi } from '../../adapter/channel/ui-policy.js';
+import type { ChannelState } from './types.js';
+export declare function bindChannelCommands(state: ChannelState, commands: ChannelUi): void;
+export declare function channelCommands(state: ChannelState): ChannelUi | ChannelState;
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/dsh-adapter/channel/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/commands.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAI9C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI,CAIlF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,CAE7E"}