@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/channel/action-readiness.js

@@ -0,0 +1,86 @@
+/** The ChannelState-facing half of the readiness cell is deliberately pure:
+ * one typed forwarding method per public action, with no service access. */
+export function createChannelActionMethods(getReadyActions) {
+    return {
+        commandCompletions: input => getReadyActions().commandCompletions(input),
+        loadOlder: () => getReadyActions().loadOlder(),
+        rewindTo: (row, mode = null) => getReadyActions().rewindTo(row, mode),
+        rewindToNode: (sessionId, seq, mode = 'rewind') => getReadyActions().rewindToNode(sessionId, seq, mode),
+        forkSession: () => getReadyActions().forkSession(),
+        resumeTo: sessionId => getReadyActions().resumeTo(sessionId),
+        newSession: () => getReadyActions().newSession(),
+        listWorkspaces: () => getReadyActions().listWorkspaces(),
+        listWorkspaceRegistry: () => getReadyActions().listWorkspaceRegistry(),
+        removeWorkspace: path => getReadyActions().removeWorkspace(path),
+        renameWorkspaceAt: (path, title) => getReadyActions().renameWorkspaceAt(path, title),
+        resolveWorkspace: uri => getReadyActions().resolveWorkspace(uri),
+        // Preserve ChannelUi's promise rejection contract after release: a caller
+        // which already received this async method must observe a rejected promise,
+        // not a synchronous throw from the readiness guard.
+        async switchWorkspace(target) { return getReadyActions().switchWorkspace(target); },
+        renameWorkspace: title => getReadyActions().renameWorkspace(title),
+        workspaceCommands: () => getReadyActions().workspaceCommands(),
+        runWorkspaceCommand: (name, input) => getReadyActions().runWorkspaceCommand(name, input),
+        switchModel: (provider, model) => getReadyActions().switchModel(provider, model),
+        listEfforts: () => getReadyActions().listEfforts(),
+        setEffort: id => getReadyActions().setEffort(id),
+        setDefaultEffort: id => getReadyActions().setDefaultEffort(id),
+        cycleMode: () => getReadyActions().cycleMode(),
+        runPermissionPreset: name => getReadyActions().runPermissionPreset(name),
+        clear: () => getReadyActions().clear(),
+        setActivityFrames: name => getReadyActions().setActivityFrames(name),
+        listPresets: () => getReadyActions().listPresets(),
+        switchPreset: presetId => getReadyActions().switchPreset(presetId),
+        listModels: () => getReadyActions().listModels(),
+        listProviders: () => getReadyActions().listProviders(),
+        invalidateModelCompletion: () => getReadyActions().invalidateModelCompletion(),
+        listSkills: () => getReadyActions().listSkills(),
+        describeCredential: ref => getReadyActions().describeCredential(ref),
+        balanceInfo: () => getReadyActions().balanceInfo(),
+        sideQuestion: (question, options) => getReadyActions().sideQuestion(question, options),
+        listFileCandidates: (query, options) => getReadyActions().listFileCandidates(query, options),
+        listFiles: () => getReadyActions().listFiles(),
+        listSessions: onEnriched => getReadyActions().listSessions(onEnriched),
+        previewSession: sessionId => getReadyActions().previewSession(sessionId),
+        bindApprovalStore: store => getReadyActions().bindApprovalStore(store),
+        agentViewRows: () => getReadyActions().agentViewRows(),
+        subscribeAgentView: listener => getReadyActions().subscribeAgentView(listener),
+        dispatchBackgroundAgent: prompt => getReadyActions().dispatchBackgroundAgent(prompt),
+        stopBackgroundAgent: sessionId => getReadyActions().stopBackgroundAgent(sessionId),
+        attachToAgent: sessionId => getReadyActions().attachToAgent(sessionId),
+        peekAgentSession: sessionId => getReadyActions().peekAgentSession(sessionId),
+        replyToAgent: (sessionId, text) => getReadyActions().replyToAgent(sessionId, text),
+        backgroundCurrent: () => getReadyActions().backgroundCurrent(),
+        setResumeTarget: sessionId => getReadyActions().setResumeTarget(sessionId),
+        renameSession: title => getReadyActions().renameSession(title),
+        setSessionColor: color => getReadyActions().setSessionColor(color),
+        recapRecent: options => getReadyActions().recapRecent(options),
+        deleteSession: sessionId => getReadyActions().deleteSession(sessionId),
+        renameSessionTo: (sessionId, title) => getReadyActions().renameSessionTo(sessionId, title),
+        compact: () => getReadyActions().compact(),
+        runExternalCommand: (name, rawInput) => getReadyActions().runExternalCommand(name, rawInput),
+        runExternalCommandOutcome: (name, rawInput, images) => getReadyActions().runExternalCommandOutcome(name, rawInput, images),
+        pushLocal: (title, lines) => getReadyActions().pushLocal(title, lines),
+        mcpStatus: () => getReadyActions().mcpStatus(),
+        exportSession: () => getReadyActions().exportSession(),
+        initWorkspace: () => getReadyActions().initWorkspace(),
+        doctorInfo: () => getReadyActions().doctorInfo(),
+        pluginsInfo: args => getReadyActions().pluginsInfo(args),
+        listSubagents: () => getReadyActions().listSubagents(),
+    };
+}
+export function createChannelActionReadiness() {
+    let delegates;
+    return {
+        install(next) {
+            if (delegates !== undefined)
+                throw new Error('dsh-tui: Channel actions are already installed');
+            delegates = Object.freeze(next);
+        },
+        getReadyActions() {
+            if (delegates === undefined)
+                throw new Error('dsh-tui: Channel actions are not installed');
+            return delegates;
+        },
+    };
+}

package/lib/types/dsh-adapter/channel/agent-view-projection.d.ts

@@ -0,0 +1,64 @@
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import { type SessionSummary } from '../sessions/index.js';
+import type { createChannelBinding } from './binding.js';
+import type { ChannelOwner } from './owner.js';
+import type { AgentViewDispatchResult, AgentViewRow, BackgroundResult, ResumeResult } from './types.js';
+import type { PreviewEntry } from '../sessions/index.js';
+type Binding = ReturnType<typeof createChannelBinding>;
+type ApprovalStore = {
+    pendingAgentIds(): readonly string[];
+    pendingAgentDetail(agentId: string): {
+        toolName: string;
+        reason?: string;
+        command?: string;
+    } | undefined;
+    subscribe(listener: () => void): () => void;
+};
+/** Owns detached background handles and the agent-view projection. */
+export declare function createAgentViewProjection(ctx: Context, deps: {
+    owner: Pick<ChannelOwner, 'current' | 'assertActive' | 'own'>;
+    binding: Pick<Binding, 'agent' | 'capture' | 'isCurrent' | 'prepare' | 'abandon' | 'waitForDisposal'>;
+    cwd(): string;
+    configuredPreset?: string;
+    configuredProvider?: string;
+    configuredModel?: string;
+    provider: string;
+    model: string;
+    notify(text: string, options?: {
+        color?: 'error' | 'warning';
+        timeoutMs?: number;
+    }): unknown;
+    listPersisted(): Promise<readonly SessionSummary[]>;
+    createDetached(create: () => Promise<AgentHandle>): Promise<{
+        handle: AgentHandle;
+        transfer(): void;
+        release(): Promise<void>;
+    }>;
+    sessionSwitchVetoed(kind: 'agent-view', targetSessionId?: string): Promise<boolean>;
+    adoptLive(target: Agent): Promise<ResumeResult>;
+    resumeInto(sessionId: string, kind: 'agent-view', keepCurrent: boolean): Promise<ResumeResult>;
+    /** The foreground binding transaction for `/bg`; the caller owns only
+     * resetting/binding the foreground projection, never the parked handle. */
+    backgroundCurrent?(): Promise<BackgroundResult>;
+    backgroundHandles?: Map<string, AgentHandle>;
+}): {
+    start: () => void;
+    backgroundHandles: Map<string, AgentHandle>;
+    notify: () => void;
+    schedule: () => void;
+    refreshPersisted: () => void;
+    bindApprovalStore: (store: ApprovalStore) => void;
+    rows: () => readonly AgentViewRow[];
+    subscribe(listener: () => void): () => boolean;
+    dispatch: (prompt: string) => Promise<AgentViewDispatchResult>;
+    stop: (sessionId: string) => Promise<boolean>;
+    attach: (sessionId: string) => Promise<ResumeResult>;
+    peek: (sessionId: string) => Promise<PreviewEntry[]>;
+    reply: (sessionId: string, text: string) => Promise<boolean>;
+    backgroundCurrent: () => Promise<BackgroundResult>;
+    setPersisted(rows: readonly SessionSummary[]): void;
+    forget(sessionId: string): void;
+};
+export {};
+//# sourceMappingURL=agent-view-projection.d.ts.map

package/lib/types/dsh-adapter/channel/agent-view-projection.d.ts.map

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

package/lib/types/dsh-adapter/channel/agent-view-projection.js

@@ -0,0 +1,312 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { randomUUID } from 'node:crypto';
+import { resolveModelRoute, validateModelRoute } from '../../modelRoute.js';
+import { readModelPref } from '../../modelPrefs.js';
+import { readPresetPref } from '../../presetPrefs.js';
+import { forgetAgentViewSession, readAgentViewSessions, touchAgentViewSession, touchSession } from '../../sessionHistory.js';
+import { t } from '../../i18n.js';
+import { AGENT_VIEW_STATUS_ORDER, agentViewLivePreview, agentViewStatusOf, foldAgentViewEvents, oneLine, sessionTitleFallback, } from '../agent-view.js';
+import { snapshotLiveSessionEvents } from '../compat/liveSession.js';
+import { composePreset } from '../presets.js';
+import { reserveNewSession } from '../../sessionMounts.js';
+import { locateSession, previewSession } from '../sessions/index.js';
+import { attachSessionToWorkspace } from '../workspace.js';
+import { logForDebugging } from '../../utils/debug.js';
+/** Owns detached background handles and the agent-view projection. */
+export function createAgentViewProjection(ctx, deps) {
+    const backgroundHandles = deps.backgroundHandles ?? new Map();
+    let approvalStore;
+    const listeners = new Set();
+    let rowsCache;
+    let refreshTimer;
+    let persistedRows = [];
+    const folds = new Map();
+    let disposed = false;
+    const notify = () => {
+        if (disposed)
+            return;
+        rowsCache = undefined;
+        for (const listener of listeners)
+            listener();
+    };
+    const schedule = () => {
+        if (disposed || refreshTimer !== undefined)
+            return;
+        refreshTimer = setTimeout(() => {
+            refreshTimer = undefined;
+            notify();
+        }, 300);
+    };
+    const refreshPersisted = () => {
+        void deps.listPersisted().then(rows => {
+            if (disposed || !deps.owner.current())
+                return;
+            persistedRows = rows;
+            notify();
+        }).catch(() => undefined);
+    };
+    const foldOf = (agent) => {
+        const events = snapshotLiveSessionEvents(agent.session);
+        const cached = folds.get(String(agent.id));
+        const base = {
+            hasTurns: false, firstPrompt: '', summary: '', summaryKind: 'none', title: '',
+            updatedAt: agent.session.header.createdAt, lastTurnFailed: false,
+        };
+        if (cached === undefined) {
+            const fold = foldAgentViewEvents(events, 0, base);
+            folds.set(String(agent.id), { events, fold });
+            return fold;
+        }
+        if (cached.events === events)
+            return cached.fold;
+        const fold = foldAgentViewEvents(events, cached.events.length, cached.fold);
+        folds.set(String(agent.id), { events, fold });
+        return fold;
+    };
+    const agents = () => ctx.get('agents');
+    let started = false;
+    let disposeStatus;
+    let disposeCreated;
+    let disposeDisposed;
+    const start = () => {
+        if (started || disposed)
+            return;
+        started = true;
+        // These process-wide roster observations still belong to this channel
+        // owner. Revoke them so a retained Context cannot wake a dead projection.
+        disposeStatus = ctx.on('agent/status', () => schedule());
+        disposeCreated = ctx.on('agent/created', () => { notify(); });
+        disposeDisposed = ctx.on('agent/disposed', ({ agent }) => {
+            folds.delete(String(agent.id ?? ''));
+            backgroundHandles.delete(String(agent.id ?? ''));
+            notify();
+        });
+        refreshPersisted();
+    };
+    const rows = () => {
+        if (rowsCache !== undefined)
+            return rowsCache;
+        const pending = new Set(approvalStore?.pendingAgentIds() ?? []);
+        const live = [];
+        for (const agent of agents()?.list?.() ?? []) {
+            if (agent.session.header.origin === 'subagent')
+                continue;
+            const fold = foldOf(agent);
+            const id = String(agent.id);
+            const current = id === String(deps.binding.agent.session.id);
+            if (!fold.hasTurns && !current)
+                continue;
+            const ask = pending.has(id) ? approvalStore?.pendingAgentDetail(id) : undefined;
+            live.push({
+                id,
+                title: fold.title.length > 0 ? fold.title : sessionTitleFallback(fold, agent.session.header.cwd),
+                cwd: agent.session.header.cwd ?? deps.cwd(),
+                summary: ask !== undefined ? oneLine(ask.reason ?? ask.command ?? ask.toolName ?? '') : fold.summaryKind === 'prompt' ? '' : fold.summary,
+                status: agentViewStatusOf(agent.status, fold, ask !== undefined),
+                live: true,
+                current,
+                createdAt: agent.session.header.createdAt,
+                updatedAt: fold.updatedAt,
+            });
+        }
+        const liveIds = new Set(live.map(row => row.id));
+        const ledger = readAgentViewSessions();
+        const stopped = persistedRows.filter(summary => !liveIds.has(summary.id) && summary.kind.kind !== 'subagent' && ledger[summary.id] !== undefined && summary.hasPrompt).map(summary => ({
+            id: summary.id, title: summary.title.text, cwd: summary.cwd,
+            summary: summary.label === undefined ? '' : oneLine(summary.label), status: 'stopped', live: false, current: false,
+            createdAt: summary.createdAt, updatedAt: summary.updatedAt,
+        }));
+        const rank = (row) => {
+            const index = AGENT_VIEW_STATUS_ORDER.indexOf(row.status);
+            return index < 0 ? AGENT_VIEW_STATUS_ORDER.length : index;
+        };
+        rowsCache = [...live, ...stopped].sort((a, b) => rank(a) - rank(b) || b.updatedAt - a.updatedAt || b.createdAt - a.createdAt || a.id.localeCompare(b.id));
+        return rowsCache;
+    };
+    const dispatch = async (prompt) => {
+        const text = prompt.trim();
+        if (text === '')
+            return { ok: false, reason: 'failed', error: t('agentview-empty-prompt') };
+        const service = agents();
+        if (!service) {
+            deps.notify(t('agentview-dispatch-unavailable'), { color: 'error' });
+            return { ok: false, reason: 'unavailable' };
+        }
+        const sessionId = SessionId(randomUUID());
+        // Announce the id before the factory: the background session's log is
+        // created here, and the publisher only learns the id from the registry on
+        // its next beat.
+        const { reservation } = await reserveNewSession(String(sessionId));
+        let detached;
+        try {
+            deps.owner.assertActive();
+            const composed = await composePreset(ctx, deps.configuredPreset ?? readPresetPref());
+            const resolved = resolveModelRoute({ provider: deps.configuredProvider, model: deps.configuredModel }, readModelPref(), { provider: deps.provider, model: deps.model });
+            const llm = ctx.get('llm');
+            const { route } = await validateModelRoute(llm, resolved, { provider: deps.provider, model: deps.model });
+            deps.owner.assertActive();
+            detached = await deps.createDetached(() => service.create({
+                sessionId,
+                meta: { cwd: deps.cwd(), ...(composed.agentPreset === undefined ? {} : { agentPreset: composed.agentPreset }) },
+                agentOptions: route,
+                ...(composed.setup === undefined ? {} : { setup: composed.setup }),
+            }));
+        }
+        catch (error) {
+            reservation.abandon();
+            const message = error instanceof Error ? error.message : String(error);
+            deps.notify(t('agentview-dispatch-failed', { err: message }), { color: 'error', timeoutMs: 8000 });
+            return { ok: false, reason: 'failed', error: message };
+        }
+        if (!deps.owner.current()) {
+            await detached.release();
+            reservation.abandon();
+            return { ok: false, reason: 'failed', error: 'Channel lifetime ended' };
+        }
+        try {
+            await attachSessionToWorkspace(ctx, deps.cwd(), sessionId);
+        }
+        catch { /* optional ledger */ }
+        if (!deps.owner.current()) {
+            await detached.release();
+            reservation.abandon();
+            return { ok: false, reason: 'failed', error: 'Channel lifetime ended' };
+        }
+        detached.transfer();
+        backgroundHandles.set(String(sessionId), detached.handle);
+        // The session is this process's background handle from here on, so the
+        // reservation has done its job: the registry is the authority now.
+        reservation.settle();
+        touchAgentViewSession(String(sessionId));
+        touchSession(sessionId);
+        // transfer intentionally moves disposal to the background ledger; check
+        // once more before delivery so revocation cannot create a late turn.
+        if (!deps.owner.current()) {
+            backgroundHandles.delete(String(sessionId));
+            await detached.handle.dispose().catch(() => undefined);
+            return { ok: false, reason: 'failed', error: 'Channel lifetime ended' };
+        }
+        try {
+            detached.handle.agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            deps.notify(t('agentview-dispatch-failed', { err: message }), { color: 'error', timeoutMs: 8000 });
+            return { ok: false, reason: 'failed', error: message };
+        }
+        notify();
+        return { ok: true, sessionId: String(sessionId) };
+    };
+    const stop = async (sessionId) => {
+        if (sessionId === String(deps.binding.agent.session.id))
+            return false;
+        const handle = backgroundHandles.get(sessionId);
+        if (handle === undefined)
+            return false;
+        backgroundHandles.delete(sessionId);
+        try {
+            handle.agent.cancel({ kind: 'user' });
+            await handle.dispose();
+        }
+        catch (error) {
+            logForDebugging(`agent view: stop of "${sessionId}" failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        folds.delete(sessionId);
+        refreshPersisted();
+        notify();
+        return true;
+    };
+    const attach = async (sessionId) => {
+        if (sessionId === String(deps.binding.agent.session.id))
+            return { ok: true };
+        const capture = deps.binding.capture();
+        // A retiring Agent can remain in the registry until its JSONL writer has
+        // drained. Read the live target only after that close, just like /resume.
+        await deps.binding.waitForDisposal(sessionId);
+        if (!deps.binding.isCurrent(capture))
+            return { ok: false, reason: 'cancelled' };
+        // Capture the exact live target before the async host decision. If the
+        // registry replaces it while parked, never silently adopt that arbitrary
+        // replacement; a later user action can make a fresh, explicit choice.
+        const live = agents()?.get(SessionId(sessionId));
+        if (await deps.sessionSwitchVetoed('agent-view', sessionId))
+            return { ok: false, reason: 'cancelled' };
+        if (!deps.binding.isCurrent(capture) || agents()?.get(SessionId(sessionId)) !== live)
+            return { ok: false, reason: 'cancelled' };
+        return live === undefined ? deps.resumeInto(sessionId, 'agent-view', true) : deps.adoptLive(live);
+    };
+    const peek = async (sessionId) => {
+        const live = agents()?.get(SessionId(sessionId));
+        if (live !== undefined)
+            return agentViewLivePreview(snapshotLiveSessionEvents(live.session), 8);
+        const persistence = ctx.get('sessionPersistence');
+        if (!persistence)
+            return [];
+        const path = await locateSession(persistence, sessionId);
+        return path === undefined ? [] : previewSession(path, 8);
+    };
+    const reply = async (sessionId, text) => {
+        const trimmed = text.trim();
+        if (trimmed === '') {
+            deps.notify(t('agentview-reply-empty'), { color: 'warning' });
+            return false;
+        }
+        const live = agents()?.get(SessionId(sessionId));
+        if (live === undefined) {
+            deps.notify(t('agentview-reply-stopped'), { color: 'warning' });
+            return false;
+        }
+        if (!deps.owner.current())
+            return false;
+        live.followup(createUserMessage({ content: [{ type: 'text', text: trimmed }], source: { kind: 'user' } }));
+        notify();
+        return true;
+    };
+    const bindApprovalStore = (store) => {
+        approvalStore = store;
+        const unsubscribe = store.subscribe(notify);
+        deps.owner.own(unsubscribe);
+        notify();
+    };
+    const dispose = () => {
+        disposed = true;
+        const failures = [];
+        for (const cleanup of [disposeStatus, disposeCreated, disposeDisposed]) {
+            try {
+                cleanup?.();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        disposeStatus = undefined;
+        disposeCreated = undefined;
+        disposeDisposed = undefined;
+        if (refreshTimer !== undefined)
+            clearTimeout(refreshTimer);
+        refreshTimer = undefined;
+        listeners.clear();
+        for (const handle of backgroundHandles.values()) {
+            // Handle disposal is asynchronous by contract; initiate every release
+            // even if a subscription disposer above fails.
+            void handle.dispose().catch(() => undefined);
+        }
+        backgroundHandles.clear();
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'dsh-tui: agent-view cleanup failed');
+    };
+    deps.owner.own(dispose);
+    return {
+        start, backgroundHandles, notify, schedule, refreshPersisted, bindApprovalStore, rows,
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        dispatch, stop, attach, peek, reply,
+        backgroundCurrent: () => deps.backgroundCurrent?.() ?? Promise.resolve({ ok: false }),
+        setPersisted(rows) { persistedRows = rows; notify(); },
+        // Forgetting persisted metadata must not discard an in-process handle:
+        // stop and owner teardown continue to own the live background session.
+        forget(sessionId) { folds.delete(sessionId); forgetAgentViewSession(sessionId); notify(); },
+    };
+}

package/lib/types/dsh-adapter/channel/background-action.d.ts

@@ -0,0 +1,41 @@
+import type { AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import { resetSessionProjection } from './session-reset.js';
+import type { createChannelBinding } from './binding.js';
+import type { ChannelOwner } from './owner.js';
+import type { BackgroundResult, ChannelState } from './types.js';
+type Binding = ReturnType<typeof createChannelBinding>;
+/** `/bg` foreground handoff. The binding remains the sole identity writer;
+ * this action only parks the exact previous handle passed by its transaction. */
+export declare function createBackgroundCurrentAction(ctx: Context, state: Pick<ChannelState, 'cwd' | 'status' | 'agentId' | 'sessionId' | 'loadedContext' | 'contextWindow' | 'effortLevels' | 'reasoningEffort' | 'emit' | 'notify'> & Parameters<typeof resetSessionProjection>[0], options: {
+    configuredPreset?: string;
+    configuredProvider?: string;
+    configuredModel?: string;
+    provider: string;
+    model: string;
+}, deps: {
+    owner: Pick<ChannelOwner, 'current'>;
+    binding: Pick<Binding, 'capture' | 'isCurrent' | 'prepare' | 'abandon' | 'adopt'>;
+    backgroundHandles: Map<string, AgentHandle>;
+    rowIds: {
+        value: number;
+    };
+    resetProjector(): void;
+    resetSubagents(): void;
+    resetJobs(): void;
+    refreshEffortLevels(): void;
+    bindAgent(): void;
+    refreshCommands(): void;
+    refreshLoadedContext(): Promise<void>;
+    refreshSkillCommands(): Promise<void>;
+    clearStagedImages(): void;
+    notifySessionSwitched(kind: 'background', sessionId: string, previousSessionId: string): void;
+    /** Owner-guarded channel notification; never call raw state.notify here. */
+    notify(text: string, options?: {
+        color?: 'error' | 'warning';
+        timeoutMs?: number;
+    }): unknown;
+    notifyAgentView(): void;
+}): () => Promise<BackgroundResult>;
+export {};
+//# sourceMappingURL=background-action.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"background-action.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/background-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,wBAAwB,CAAA;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAYlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEhE,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEtD;iFACiF;AACjF,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,IAAI,CAAC,YAAY,EACtB,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,GAC9E,cAAc,GAAG,iBAAiB,GAAG,MAAM,GAAG,QAAQ,CAAC,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,EACxG,OAAO,EAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAC9H,IAAI,EAAE;IACJ,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAA;IACpC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,CAAA;IACjF,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IAC3C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACzB,cAAc,IAAI,IAAI,CAAA;IACtB,cAAc,IAAI,IAAI,CAAA;IACtB,SAAS,IAAI,IAAI,CAAA;IACjB,mBAAmB,IAAI,IAAI,CAAA;IAC3B,SAAS,IAAI,IAAI,CAAA;IACjB,eAAe,IAAI,IAAI,CAAA;IACvB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,iBAAiB,IAAI,IAAI,CAAA;IACzB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7F,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAA;IAC5F,eAAe,IAAI,IAAI,CAAA;CACxB,GACA,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAyFjC"}

package/lib/types/dsh-adapter/channel/background-action.js

@@ -0,0 +1,110 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { randomUUID } from 'node:crypto';
+import { resolveModelRoute, validateModelRoute } from '../../modelRoute.js';
+import { readModelPref } from '../../modelPrefs.js';
+import { readPresetPref } from '../../presetPrefs.js';
+import { clearResumeTarget, touchAgentViewSession, touchSession } from '../../sessionHistory.js';
+import { t } from '../../i18n.js';
+import { reserveMount } from '../../sessionMounts.js';
+import { mountFailureText } from '../../sessions/resumeFailure.js';
+import { composePreset } from '../presets.js';
+import { attachSessionToWorkspace } from '../workspace.js';
+import { resetSessionProjection } from './session-reset.js';
+/** `/bg` foreground handoff. The binding remains the sole identity writer;
+ * this action only parks the exact previous handle passed by its transaction. */
+export function createBackgroundCurrentAction(ctx, state, options, deps) {
+    return async () => {
+        const adoption = deps.binding.capture();
+        const agents = ctx.get('agents');
+        if (!agents) {
+            deps.notify(t('agentview-dispatch-unavailable'), { color: 'error' });
+            return { ok: false, reason: 'unavailable' };
+        }
+        const sessionId = SessionId(randomUUID());
+        // Reserve before the factory: from the moment `agents.create` returns this
+        // process holds the only write handle on a log the publisher has not named
+        // yet, and a peer listing sessions in that gap would be told it is free.
+        const reserved = await reserveMount(sessionId);
+        if (!reserved.ok && reserved.reason !== 'occupied')
+            deps.notify(mountFailureText(reserved), { color: 'warning', timeoutMs: 8000 });
+        const reservation = reserved.ok ? reserved.reservation : { settle: () => { }, abandon: () => { } };
+        try {
+            const composed = await composePreset(ctx, options.configuredPreset ?? readPresetPref());
+            const route = await validateModelRoute(ctx.get('llm'), resolveModelRoute({ provider: options.configuredProvider, model: options.configuredModel }, readModelPref(), { provider: options.provider, model: options.model }), { provider: options.provider, model: options.model });
+            const handle = await deps.binding.prepare(adoption, () => agents.create({
+                sessionId,
+                meta: { cwd: state.cwd, ...(composed.agentPreset === undefined ? {} : { agentPreset: composed.agentPreset }) },
+                agentOptions: route.route,
+                ...(composed.setup === undefined ? {} : { setup: composed.setup }),
+            }));
+            if (!deps.binding.isCurrent(adoption)) {
+                await deps.binding.abandon(handle);
+                reservation.abandon();
+                return { ok: false, reason: 'failed', error: 'Channel lifetime ended' };
+            }
+            try {
+                await attachSessionToWorkspace(ctx, state.cwd, sessionId);
+            }
+            catch (error) {
+                // The workspace ledger is optional bookkeeping, but preserve the
+                // baseline stderr warning for operators diagnosing a degraded host.
+                ctx.logger.warn('dsh-tui: background session attachment failed: %o', error);
+            }
+            // Do not adopt after attachment unless the exact captured foreground is
+            // still current. A replacement is not a license to target that newer
+            // agent; the prepared candidate is abandoned instead.
+            if (!deps.binding.isCurrent(adoption)) {
+                await deps.binding.abandon(handle);
+                reservation.abandon();
+                return { ok: false, reason: 'failed', error: 'Channel lifetime ended' };
+            }
+            let committed = false;
+            try {
+                const result = deps.binding.adopt(handle, adoption, (previous, disposePrevious) => {
+                    const previousSessionId = String(previous.agent.session.id);
+                    if (previous.handle !== undefined) {
+                        deps.backgroundHandles.set(previousSessionId, previous.handle);
+                        disposePrevious('park');
+                    }
+                    resetSessionProjection(state, deps.rowIds, deps.resetProjector, deps.resetSubagents, deps.resetJobs);
+                    state.status = handle.agent.status;
+                    state.agentId = handle.agent.id;
+                    state.sessionId = handle.agent.session.id;
+                    state.loadedContext = undefined;
+                    state.contextWindow = undefined;
+                    state.effortLevels = undefined;
+                    state.reasoningEffort = undefined;
+                    deps.refreshEffortLevels();
+                    // Reset the input FIFO and pending-decision indicators BEFORE the first
+                    // emit (main's bind → clear → refresh order).
+                    deps.clearStagedImages();
+                    deps.bindAgent();
+                    deps.refreshCommands();
+                    void deps.refreshLoadedContext();
+                    void deps.refreshSkillCommands();
+                    clearResumeTarget();
+                    touchSession(handle.agent.id);
+                    touchAgentViewSession(previousSessionId);
+                    touchAgentViewSession(String(handle.agent.id));
+                    deps.notifySessionSwitched('background', String(handle.agent.id), previousSessionId);
+                    deps.notifyAgentView();
+                    return { ok: true, backgroundedSessionId: previousSessionId };
+                });
+                committed = true;
+                return result;
+            }
+            finally {
+                if (committed)
+                    reservation.settle();
+                else
+                    reservation.abandon();
+            }
+        }
+        catch (error) {
+            reservation.abandon();
+            const message = error instanceof Error ? error.message : String(error);
+            deps.notify(t('agentview-dispatch-failed', { err: message }), { color: 'error', timeoutMs: 8000 });
+            return { ok: false, reason: 'failed', error: message };
+        }
+    };
+}