@deepseek-ai/dsh-api-terminal-controller 0.1.6-alpha.1 → 0.1.7-alpha.1

package/lib/types/client/bindings.js

@@ -0,0 +1,71 @@
+const PREFIX = 'dsh.terminal.binding.v1.';
+/** Saved recovery targets keyed by Session and globally unique terminal content identity. */
+export class TerminalBindings {
+    memory = new Map();
+    /**
+     * Read a saved target, retaining this window's value when storage is unavailable.
+     * @param sessionId - owning Session.
+     * @param contentId - terminal content identity, shared only by deliberate copies.
+     * @returns the existing Host identity, if one has been saved.
+     */
+    get(sessionId, contentId) {
+        const key = this.key(sessionId, contentId);
+        const known = this.memory.get(key);
+        if (known !== undefined)
+            return known;
+        if (typeof localStorage === 'undefined')
+            return undefined;
+        try {
+            const raw = localStorage.getItem(key);
+            if (raw === null)
+                return undefined;
+            const value = JSON.parse(raw);
+            if (typeof value !== 'string' || !/^[\w-]{1,128}$/u.test(value))
+                return undefined;
+            this.memory.set(key, value);
+            return value;
+        }
+        catch (_storageUnavailable) {
+            return undefined;
+        }
+    }
+    /**
+     * Save an identity before its Host allocation begins.
+     * @param sessionId - owning Session.
+     * @param contentId - globally unique terminal content identity.
+     * @param id - existing or newly allocated Host identity.
+     */
+    set(sessionId, contentId, id) {
+        const key = this.key(sessionId, contentId);
+        this.memory.set(key, id);
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            localStorage.setItem(key, JSON.stringify(id));
+        }
+        catch (error) {
+            console.error('Terminal binding persistence failed:', error);
+        }
+    }
+    /**
+     * Remove this content's target after its close intent has been saved.
+     * @param sessionId - owning Session.
+     * @param contentId - closing terminal content identity.
+     */
+    delete(sessionId, contentId) {
+        const key = this.key(sessionId, contentId);
+        this.memory.delete(key);
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            localStorage.removeItem(key);
+        }
+        catch (error) {
+            console.error('Terminal binding cleanup failed:', error);
+        }
+    }
+    /** Release cached values when the Client service is disposed. */
+    clear() { this.memory.clear(); }
+    key(sessionId, contentId) { return PREFIX + JSON.stringify([sessionId, contentId]); }
+}
+//# sourceMappingURL=bindings.js.map

package/lib/types/client/index.d.ts

@@ -32,6 +32,10 @@ export declare class ClientTerminals extends Service {
     private readonly closed;
     private disposed;
     private readonly views;
+    private readonly bindings;
+    private readonly holds;
+    private readonly releasing;
+    private openTabs;
     /**
      * @param ctx - Client root Context with Gateway and terminal Remote namespace.
      * @param remote - generated terminal namespace.
@@ -41,11 +45,12 @@ export declare class ClientTerminals extends Service {
      * Return the stable model for one sidebar occurrence.
      * @param sessionId - owning Session.
      * @param key - sidebar occurrence key.
-     * @param terminalId - existing Host identity when restoring a listed terminal.
+     * @param contentId - globally unique content identity; layout-local tab ids are not persistence keys.
+     * @param terminalId - existing Host identity when restoring a listed terminal; otherwise reuse the saved content identity.
      * @param shellPath - explicit shell for a new terminal; restored terminals retain their own shell.
      * @returns its observable state and terminal commands.
      */
-    view(sessionId: SessionId, key: string, terminalId?: WebTerminalId, shellPath?: string): TerminalView;
+    view(sessionId: SessionId, key: string, contentId: string, terminalId?: WebTerminalId, shellPath?: string): TerminalView;
     /**
      * Discover available launch choices on demand without allocating a PTY.
      * @param sessionId - target Session.
@@ -62,11 +67,24 @@ export declare class ClientTerminals extends Service {
      * Save a close intent and release the tab immediately; cleanup outlives DOM unmount and reload.
      * @param sessionId - owning Session.
      * @param key - sidebar occurrence key, including an inactive restored tab.
+     * @param contentId - globally unique content identity whose binding is removed.
      * @param terminalId - restored identity if the tab has no model yet.
      */
-    close(sessionId: SessionId, key: string, terminalId?: WebTerminalId): void;
+    close(sessionId: SessionId, key: string, contentId: string, terminalId?: WebTerminalId): void;
     /**
-     * Query Host terminals that have neither a tab in this page nor an unfinished close.
+     * Reconcile this window's open terminal occurrences, including dormant saved Sessions.
+     * @param tabs - terminal-kind membership supplied by the sidebar layout owner.
+     */
+    retainTabs(tabs: readonly {
+        sessionId: SessionId;
+        tabId: string;
+        contentId: string;
+    }[]): void;
+    private hold;
+    private reconcileHolds;
+    private release;
+    /**
+     * Query Host terminals without a live view or unfinished close.
      * @param sessionId - Session being displayed.
      * @returns terminals available for opening as recovered tabs.
      */

package/lib/types/client/index.js

@@ -6,6 +6,8 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store';
 import { randomUUID } from '@deepseek-ai/dsh-util-crypto';
 import { preferredShell, rememberShell } from "./shell-preference.js";
 import { TerminalCloseRequests } from "./close-requests.js";
+import { TerminalWindowHold } from "./retention.js";
+import { TerminalBindings } from "./bindings.js";
 /** Session and occurrence lookup, independent tab and terminal identities and background cleanup. */
 export class ClientTerminals extends Service {
     remote;
@@ -16,6 +18,10 @@ export class ClientTerminals extends Service {
     closed = new Set(this.requests.pending().map(request => request.id));
     disposed = false;
     views = new Map();
+    bindings = new TerminalBindings();
+    holds = new Map();
+    releasing = new Set();
+    openTabs = [];
     /**
      * @param ctx - Client root Context with Gateway and terminal Remote namespace.
      * @param remote - generated terminal namespace.
@@ -27,7 +33,10 @@ export class ClientTerminals extends Service {
             this.disposed = true;
             const detaching = [...this.views.values()].flatMap(views => [...views.values()].map(view => view.dispose()));
             this.views.clear();
-            await Promise.all([...detaching, ...this.closing.values()]);
+            this.bindings.clear();
+            const holds = [...this.holds.values()].flatMap(holds => [...holds.values()].map(hold => hold.dispose()));
+            this.holds.clear();
+            await Promise.all([...detaching, ...holds, ...this.releasing, ...this.closing.values()]);
         }, 'terminal-controller.client.views');
         for (const request of this.requests.pending())
             this.cleanup(request);
@@ -36,11 +45,12 @@ export class ClientTerminals extends Service {
      * Return the stable model for one sidebar occurrence.
      * @param sessionId - owning Session.
      * @param key - sidebar occurrence key.
-     * @param terminalId - existing Host identity when restoring a listed terminal.
+     * @param contentId - globally unique content identity; layout-local tab ids are not persistence keys.
+     * @param terminalId - existing Host identity when restoring a listed terminal; otherwise reuse the saved content identity.
      * @param shellPath - explicit shell for a new terminal; restored terminals retain their own shell.
      * @returns its observable state and terminal commands.
      */
-    view(sessionId, key, terminalId, shellPath) {
+    view(sessionId, key, contentId, terminalId, shellPath) {
         let views = this.views.get(sessionId);
         if (views === undefined) {
             views = new Map();
@@ -48,9 +58,12 @@ export class ClientTerminals extends Service {
         }
         let view = views.get(key);
         if (view === undefined) {
-            const id = terminalId ?? randomUUID();
-            view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, terminalId === undefined, shellPath);
+            const saved = terminalId ?? this.bindings.get(sessionId, contentId);
+            const id = saved ?? randomUUID();
+            this.bindings.set(sessionId, contentId, id);
+            view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, saved === undefined, shellPath, signal => this.hold(sessionId, id).ready(signal));
             views.set(key, view);
+            this.reconcileHolds();
             void view.refresh();
         }
         return view;
@@ -77,24 +90,86 @@ export class ClientTerminals extends Service {
      * Save a close intent and release the tab immediately; cleanup outlives DOM unmount and reload.
      * @param sessionId - owning Session.
      * @param key - sidebar occurrence key, including an inactive restored tab.
+     * @param contentId - globally unique content identity whose binding is removed.
      * @param terminalId - restored identity if the tab has no model yet.
      */
-    close(sessionId, key, terminalId) {
+    close(sessionId, key, contentId, terminalId) {
         const views = this.views.get(sessionId);
         const view = views?.get(key);
-        const id = view?.id ?? terminalId;
+        const id = view?.id ?? terminalId ?? this.bindings.get(sessionId, contentId);
         if (id === undefined)
             return;
         const request = { sessionId, id, title: view?.state.getSnapshot().title ?? key };
         this.closed.add(id);
         this.requests.save(request);
+        this.bindings.delete(sessionId, contentId);
         views?.delete(key);
         if (views?.size === 0)
             this.views.delete(sessionId);
         this.cleanup(request, view);
+        this.reconcileHolds();
     }
     /**
-     * Query Host terminals that have neither a tab in this page nor an unfinished close.
+     * Reconcile this window's open terminal occurrences, including dormant saved Sessions.
+     * @param tabs - terminal-kind membership supplied by the sidebar layout owner.
+     */
+    retainTabs(tabs) {
+        this.openTabs = tabs;
+        this.reconcileHolds();
+    }
+    hold(sessionId, id) {
+        let holds = this.holds.get(sessionId);
+        if (holds === undefined) {
+            holds = new Map();
+            this.holds.set(sessionId, holds);
+        }
+        let hold = holds.get(id);
+        if (hold === undefined || hold.failed) {
+            if (hold !== undefined)
+                this.release(hold);
+            hold = new TerminalWindowHold(this.ctx.remote, this.remote, sessionId, id);
+            holds.set(id, hold);
+        }
+        return hold;
+    }
+    reconcileHolds() {
+        if (this.disposed)
+            return;
+        const wanted = new Map();
+        for (const tab of this.openTabs) {
+            const id = this.bindings.get(tab.sessionId, tab.contentId);
+            if (id === undefined || this.closed.has(id))
+                continue;
+            let ids = wanted.get(tab.sessionId);
+            if (ids === undefined) {
+                ids = new Set();
+                wanted.set(tab.sessionId, ids);
+            }
+            ids.add(id);
+            const view = this.views.get(tab.sessionId)?.get(tab.tabId);
+            if (view === undefined || view.state.getSnapshot().info !== undefined) {
+                if (!this.holds.get(tab.sessionId)?.has(id))
+                    this.hold(tab.sessionId, id);
+            }
+        }
+        for (const [sessionId, holds] of this.holds) {
+            for (const [id, hold] of holds) {
+                if (!wanted.get(sessionId)?.has(id)) {
+                    holds.delete(id);
+                    this.release(hold);
+                }
+            }
+            if (holds.size === 0)
+                this.holds.delete(sessionId);
+        }
+    }
+    release(hold) {
+        const releasing = hold.dispose().finally(() => { this.releasing.delete(releasing); });
+        this.releasing.add(releasing);
+        void releasing.catch((error) => { this.ctx.logger.warn('Terminal hold release failed', error); });
+    }
+    /**
+     * Query Host terminals without a live view or unfinished close.
      * @param sessionId - Session being displayed.
      * @returns terminals available for opening as recovered tabs.
      */

package/lib/types/client/model.d.ts

@@ -40,6 +40,7 @@ export declare class TerminalView {
     readonly id: WebTerminalId;
     private readonly createWhenMissing;
     private readonly shellPath?;
+    private readonly retain?;
     /** Observable controls, process metadata and the next screen update awaiting acknowledgement. */
     readonly state: SnapshotStore<TerminalViewState>;
     private readonly lifetime;
@@ -61,8 +62,9 @@ export declare class TerminalView {
      * @param id - Host terminal identity, reused when recovering an item from its Session list.
      * @param createWhenMissing - allow allocation only for a new tab, never a listed terminal.
      * @param shellPath - explicit shell chosen at the guide; omission uses the remembered available shell.
+     * @param retain - window hold acknowledgement required before output attachment.
      */
-    constructor(sessionId: SessionId, remote: TerminalRemote, gateway: Pick<ClientRemote, '$stream'>, id: WebTerminalId, createWhenMissing?: boolean, shellPath?: string | undefined);
+    constructor(sessionId: SessionId, remote: TerminalRemote, gateway: Pick<ClientRemote, '$stream'>, id: WebTerminalId, createWhenMissing?: boolean, shellPath?: string | undefined, retain?: ((signal: AbortSignal) => Promise<void>) | undefined);
     /**
      * Attach the DOM lifetime, starting the chosen shell or reconnecting the saved process.
      * @returns a detach callback that leaves the terminal process alive.

package/lib/types/client/model.js

@@ -15,6 +15,7 @@ export class TerminalView {
     id;
     createWhenMissing;
     shellPath;
+    retain;
     /** Observable controls, process metadata and the next screen update awaiting acknowledgement. */
     state = createSnapshotStore({ phase: 'idle', writable: false });
     lifetime = new AbortController();
@@ -36,14 +37,16 @@ export class TerminalView {
      * @param id - Host terminal identity, reused when recovering an item from its Session list.
      * @param createWhenMissing - allow allocation only for a new tab, never a listed terminal.
      * @param shellPath - explicit shell chosen at the guide; omission uses the remembered available shell.
+     * @param retain - window hold acknowledgement required before output attachment.
      */
-    constructor(sessionId, remote, gateway, id, createWhenMissing = true, shellPath) {
+    constructor(sessionId, remote, gateway, id, createWhenMissing = true, shellPath, retain) {
         this.sessionId = sessionId;
         this.remote = remote;
         this.gateway = gateway;
         this.id = id;
         this.createWhenMissing = createWhenMissing;
         this.shellPath = shellPath;
+        this.retain = retain;
     }
     /**
      * Attach the DOM lifetime, starting the chosen shell or reconnecting the saved process.
@@ -117,8 +120,16 @@ export class TerminalView {
     }
     adopt(info) {
         this.patch({ info, title: info.title });
-        if (this.mounted && this.closing === undefined)
-            this.connect();
+        if (this.retain === undefined) {
+            if (this.mounted && this.closing === undefined)
+                this.connect();
+            return;
+        }
+        void this.retain(this.lifetime.signal).then(() => {
+            if (this.mounted && this.closing === undefined)
+                this.connect();
+        }).catch((error) => { if (!this.stopped())
+            this.fail(error); });
     }
     /** Reattach with a fresh screen and regain input control. */
     connect() {
@@ -128,11 +139,13 @@ export class TerminalView {
         this.detach();
         const stream = this.gateway.$stream({
             name: 'Browser terminal output',
-            open: (signal) => {
+            open: async function* (signal) {
+                await this.retain?.(signal);
+                signal.throwIfAborted();
                 const attachmentId = randomUUID();
                 this.attachmentId = attachmentId;
-                return this.remote.follow(this.sessionId, info.id, attachmentId, signal);
-            },
+                yield* this.remote.follow(this.sessionId, info.id, attachmentId, signal);
+            }.bind(this),
             ended: () => new TerminalViewError('attachmentEnded'),
             carrierFailed: () => { if (this.stream === stream)
                 this.patch({ phase: 'disconnected', writable: false }); },
@@ -311,7 +324,7 @@ export class TerminalView {
             this.patch({ writable: false, error: undefined, issue: undefined });
             return;
         }
-        const issue = failure?.code === 'terminal/view' ? failure.details.issue : failure?.code === 'terminal/limit-reached' ? 'terminalLimit' : undefined;
+        const issue = failure?.code === 'terminal/view' ? failure.details.issue : failure?.code === 'terminal/limit-reached' ? 'terminalLimit' : failure?.code === 'terminal/unavailable' ? 'missingTerminal' : undefined;
         this.patch({ phase: error instanceof RemoteStreamCarrierError ? 'disconnected' : 'failed', writable: false, issue, error: error instanceof Error ? error.message : String(error) });
     }
 }

package/lib/types/client/retention.d.ts

@@ -0,0 +1,35 @@
+/** One reconnecting window hold, shared by all occurrences of a terminal. */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { WebTerminalId } from '../types.ts';
+import type { TerminalRemote } from './model.ts';
+/** A stream acknowledgement gates output attachment for each physical connection. */
+export declare class TerminalWindowHold {
+    private readonly stream;
+    private readonly waiters;
+    private generation;
+    private failure;
+    /**
+     * @param gateway - reconnecting stream owner.
+     * @param remote - typed terminal namespace.
+     * @param sessionId - saved layout's Session, without Agent activation.
+     * @param id - existing Host terminal.
+     */
+    constructor(gateway: Pick<ClientRemote, '$stream'>, remote: TerminalRemote, sessionId: SessionId, id: WebTerminalId);
+    /** Whether a terminal-domain failure ended this hold, allowing an explicit retry. */
+    get failed(): boolean;
+    /**
+     * Wait for an acknowledged current physical hold before following its screen.
+     * @param signal - output request or view lifetime.
+     * @returns after acknowledgement, or rejects on cancellation/unavailability.
+     */
+    ready(signal: AbortSignal): Promise<void>;
+    /**
+     * Release this window's stream and all acknowledgement waiters.
+     * @returns after the stream consumer closes.
+     */
+    dispose(): Promise<void>;
+    private consume;
+    private reject;
+}
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/client/retention.js

@@ -0,0 +1,77 @@
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+/** A stream acknowledgement gates output attachment for each physical connection. */
+export class TerminalWindowHold {
+    stream;
+    waiters = new Set();
+    generation;
+    failure;
+    /**
+     * @param gateway - reconnecting stream owner.
+     * @param remote - typed terminal namespace.
+     * @param sessionId - saved layout's Session, without Agent activation.
+     * @param id - existing Host terminal.
+     */
+    constructor(gateway, remote, sessionId, id) {
+        this.stream = gateway.$stream({
+            name: 'Browser terminal window hold',
+            open: signal => remote.retain(sessionId, id, signal),
+            ended: () => new RemoteError('terminal/unavailable', 'Terminal hold ended', {}),
+        });
+        void this.consume();
+    }
+    /** Whether a terminal-domain failure ended this hold, allowing an explicit retry. */
+    get failed() { return this.failure !== undefined; }
+    /**
+     * Wait for an acknowledged current physical hold before following its screen.
+     * @param signal - output request or view lifetime.
+     * @returns after acknowledgement, or rejects on cancellation/unavailability.
+     */
+    async ready(signal) {
+        signal.throwIfAborted();
+        if (this.failure !== undefined)
+            throw this.failure;
+        if (this.generation !== undefined && !this.generation.aborted)
+            return;
+        const waiting = Promise.withResolvers();
+        const abort = () => { waiting.reject(signal.reason); };
+        this.waiters.add(waiting);
+        signal.addEventListener('abort', abort, { once: true });
+        try {
+            await waiting.promise;
+        }
+        finally {
+            this.waiters.delete(waiting);
+            signal.removeEventListener('abort', abort);
+        }
+    }
+    /**
+     * Release this window's stream and all acknowledgement waiters.
+     * @returns after the stream consumer closes.
+     */
+    dispose() {
+        this.reject(new Error('Terminal window hold released'));
+        return this.stream.dispose();
+    }
+    async consume() {
+        try {
+            for await (const item of this.stream) {
+                item.accept();
+                this.generation = item.signal;
+                for (const waiter of this.waiters)
+                    waiter.resolve();
+                this.waiters.clear();
+            }
+        }
+        catch (error) {
+            this.reject(error);
+        }
+    }
+    reject(error) {
+        this.failure = error instanceof Error ? error : new Error('Terminal window hold failed', { cause: error });
+        this.generation = undefined;
+        for (const waiter of this.waiters)
+            waiter.reject(error);
+        this.waiters.clear();
+    }
+}
+//# sourceMappingURL=retention.js.map

package/lib/types/index.d.ts

@@ -1,10 +1,10 @@
-/** Session-scoped browser terminals over the composed subprocess and sandbox providers. */
+/** Session-owned user terminals with the execution environment's system-user permissions. */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { TerminalShell, TerminalAttachmentId, TerminalCreateRequest, TerminalEnvironment, TerminalFrame, WebTerminalId, WebTerminalInfo } from './types.ts';
+import type { TerminalShell, TerminalAttachmentId, TerminalCreateRequest, TerminalEnvironment, TerminalFrame, TerminalRetentionFrame, WebTerminalId, WebTerminalInfo } from './types.ts';
 export type * from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -39,6 +39,12 @@ export interface Config {
     readonly maxInputBytes: number;
     /** Provider process-termination grace period in milliseconds. */
     readonly disposeGraceMs: number;
+    /** Continuous confirmed idle time without window holds before reclamation; zero disables reclamation. */
+    readonly unattendedTimeoutMs: number;
+    /** Interval between unattended shell and process observations. */
+    readonly activityPollIntervalMs: number;
+    /** Delay before retrying failed owned terminal cleanup. */
+    readonly cleanupRetryMs: number;
 }
 /** Typed Remote control of transient Session-owned terminal processes. */
 export declare class TerminalController extends TypertRemoteService {
@@ -73,13 +79,21 @@ export declare class TerminalController extends TypertRemoteService {
      */
     list(sessionId: SessionId): WebTerminalInfo[];
     /**
-     * Allocate an interactive shell once for a caller-generated identity.
+     * Allocate a user shell once for a caller-generated identity, without Agent sandbox or approval restrictions.
      * @param agent - Session owner supplied by the Gateway.
      * @param request - initial dimensions and idempotency identity.
      * @param signal - allocation cancellation; committed terminals survive disconnection.
      * @returns the existing or newly committed terminal.
      */
     create(agent: Agent, request: TerminalCreateRequest, signal: AbortSignal): Promise<WebTerminalInfo>;
+    /**
+     * Retain an existing terminal for a window without activating its Agent or taking input control.
+     * @param sessionId - owning Session identity, including an inactive saved layout.
+     * @param id - retained Host terminal identity.
+     * @param signal - physical Remote stream cancellation.
+     * @returns a hold acknowledgement followed by an open lifetime stream.
+     */
+    retain(sessionId: SessionId, id: WebTerminalId, signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>;
     /**
      * Attach to a terminal without binding its process lifetime to the transport.
      * @param agent - Session owner supplied by the Gateway.