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

package/lib/types/retention.d.ts

@@ -0,0 +1,53 @@
+import type { SubprocessTerminalActivity } from '@deepseek-ai/dsh-subprocess';
+import type { TerminalRetentionFrame } from './types.ts';
+/** Validated Host timing policy for unattended terminal cleanup. */
+export interface TerminalRetentionPolicy {
+    readonly unattendedTimeoutMs: number;
+    readonly activityPollIntervalMs: number;
+    readonly cleanupRetryMs: number;
+}
+/** Exactly one owner orders holds, observation, and retryable process cleanup. */
+export declare class TerminalRetention {
+    private readonly policy;
+    private readonly inspect;
+    private readonly terminate;
+    private readonly failed;
+    private readonly lifetime;
+    private readonly holders;
+    private epoch;
+    private timer;
+    private observation;
+    private idle;
+    private closing;
+    private disposed;
+    private cleanup;
+    /**
+     * @param policy - deployment timing choices.
+     * @param inspect - fresh shell and owned-job observation.
+     * @param terminate - mark the identity closed, await process quiescence, and remove its owner record.
+     * @param failed - diagnostic sink for failed automatic cleanup.
+     */
+    constructor(policy: TerminalRetentionPolicy, inspect: () => Promise<SubprocessTerminalActivity>, terminate: () => Promise<void>, failed: (error: unknown) => void);
+    /**
+     * Hold one terminal for one physical Remote stream, independently of screen subscriptions.
+     * @param signal - transport generation lifetime.
+     * @returns acknowledgement followed by an open stream until cancellation or terminal closure.
+     */
+    retain(signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>;
+    /** Invalidate outstanding idle observations before accepting input. */
+    invalidate(): void;
+    /**
+     * Start or join cleanup; failure keeps the identity closed and schedules one retry.
+     * @returns after owned process cleanup succeeds, or rejects with its failure.
+     */
+    close(): Promise<void>;
+    /**
+     * Stop timers and streams and await both observation and final cleanup.
+     * @returns after process quiescence; cleanup failure is reported to the disposing owner.
+     */
+    dispose(): Promise<void>;
+    private cancelTimer;
+    private schedule;
+    private observe;
+}
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/retention.js

@@ -0,0 +1,153 @@
+/** Window holds and conservative idle reclamation for one terminal owner. */
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+/** Exactly one owner orders holds, observation, and retryable process cleanup. */
+export class TerminalRetention {
+    policy;
+    inspect;
+    terminate;
+    failed;
+    lifetime = new AbortController();
+    holders = new Set();
+    epoch = 0;
+    timer;
+    observation;
+    idle;
+    closing = false;
+    disposed = false;
+    cleanup;
+    /**
+     * @param policy - deployment timing choices.
+     * @param inspect - fresh shell and owned-job observation.
+     * @param terminate - mark the identity closed, await process quiescence, and remove its owner record.
+     * @param failed - diagnostic sink for failed automatic cleanup.
+     */
+    constructor(policy, inspect, terminate, failed) {
+        this.policy = policy;
+        this.inspect = inspect;
+        this.terminate = terminate;
+        this.failed = failed;
+        this.schedule(0);
+    }
+    /**
+     * Hold one terminal for one physical Remote stream, independently of screen subscriptions.
+     * @param signal - transport generation lifetime.
+     * @returns acknowledgement followed by an open stream until cancellation or terminal closure.
+     */
+    async *retain(signal) {
+        signal.throwIfAborted();
+        if (this.closing || this.disposed)
+            throw new RemoteError('terminal/unavailable', 'Terminal is closing or unavailable', {});
+        const holder = {};
+        const ended = Promise.withResolvers();
+        const combined = AbortSignal.any([signal, this.lifetime.signal]);
+        const release = () => {
+            if (!this.holders.delete(holder))
+                return;
+            combined.removeEventListener('abort', release);
+            this.invalidate();
+            ended.resolve();
+            this.schedule(0);
+        };
+        this.holders.add(holder);
+        this.invalidate();
+        this.cancelTimer();
+        combined.addEventListener('abort', release, { once: true });
+        try {
+            yield { type: 'retained' };
+            await ended.promise;
+        }
+        finally {
+            release();
+        }
+    }
+    /** Invalidate outstanding idle observations before accepting input. */
+    invalidate() { this.epoch++; this.idle = undefined; }
+    /**
+     * Start or join cleanup; failure keeps the identity closed and schedules one retry.
+     * @returns after owned process cleanup succeeds, or rejects with its failure.
+     */
+    close() {
+        if (this.cleanup !== undefined)
+            return this.cleanup;
+        this.closing = true;
+        this.invalidate();
+        this.lifetime.abort(new Error('Terminal closed'));
+        this.cancelTimer();
+        this.cleanup = this.terminate().catch((error) => {
+            this.cleanup = undefined;
+            this.schedule(this.policy.cleanupRetryMs);
+            throw error;
+        });
+        return this.cleanup;
+    }
+    /**
+     * Stop timers and streams and await both observation and final cleanup.
+     * @returns after process quiescence; cleanup failure is reported to the disposing owner.
+     */
+    async dispose() {
+        this.disposed = true;
+        this.cancelTimer();
+        const observation = this.observation;
+        try {
+            await this.close();
+        }
+        finally {
+            await observation;
+        }
+    }
+    cancelTimer() { clearTimeout(this.timer); this.timer = undefined; }
+    schedule(delay) {
+        if (this.disposed || this.timer !== undefined)
+            return;
+        if (!this.closing && (this.holders.size > 0 || this.policy.unattendedTimeoutMs === 0))
+            return;
+        const due = performance.now() + delay;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            const remaining = due - performance.now();
+            if (remaining > 0) {
+                this.schedule(remaining);
+                return;
+            }
+            if (this.closing) {
+                void this.close().catch(this.failed);
+                return;
+            }
+            this.observe();
+        }, Math.min(delay, 2_147_483_647));
+        this.timer.unref();
+    }
+    observe() {
+        if (this.observation !== undefined)
+            return;
+        const epoch = this.epoch;
+        this.observation = (async () => {
+            let activity;
+            try {
+                activity = await this.inspect();
+            }
+            catch (_activityUnavailable) {
+                activity = { state: 'unknown', revision: 0 };
+            }
+            if (this.disposed || this.closing || this.holders.size > 0 || epoch !== this.epoch)
+                return;
+            const now = performance.now();
+            if (activity.state !== 'idle') {
+                this.idle = undefined;
+                return;
+            }
+            if (this.idle?.revision !== activity.revision || now - this.idle.observedAt > this.policy.activityPollIntervalMs * 2) {
+                this.idle = { since: now, observedAt: now, revision: activity.revision };
+            }
+            else
+                this.idle.observedAt = now;
+            if (now - this.idle.since >= this.policy.unattendedTimeoutMs)
+                await this.close();
+        })().catch(this.failed).finally(() => {
+            this.observation = undefined;
+            if (!this.closing)
+                this.schedule(this.policy.activityPollIntervalMs);
+        });
+    }
+}
+//# sourceMappingURL=retention.js.map

package/lib/types/terminal.d.ts

@@ -1,5 +1,6 @@
 import type { SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess';
-import type { TerminalAttachmentId, TerminalFrame, WebTerminalInfo } from './types.ts';
+import { type TerminalRetentionPolicy } from './retention.ts';
+import type { TerminalAttachmentId, TerminalFrame, TerminalRetentionFrame, WebTerminalInfo } from './types.ts';
 /** Process lifetime is independent of follower and component lifetimes. */
 export declare class BrowserTerminal {
     private readonly handle;
@@ -12,6 +13,7 @@ export declare class BrowserTerminal {
     private operations;
     private readonly drained;
     private closing;
+    private retention;
     private controller;
     /**
      * @param handle - allocated terminal process range.
@@ -20,6 +22,20 @@ export declare class BrowserTerminal {
      * @param maxBufferedBytes - per-follower queue cap.
      */
     constructor(handle: SubprocessTerminalHandle, info: WebTerminalInfo, scrollback: number, maxBufferedBytes: number);
+    /**
+     * Start monitoring after this allocation is committed to its Session owner.
+     * @param policy - validated Host timing policy.
+     * @param closing - closes the id before any asynchronous termination.
+     * @param closed - removes the exact successfully terminated owner record.
+     * @param failed - diagnostic sink for background cleanup failure.
+     */
+    monitor(policy: TerminalRetentionPolicy, closing: () => void, closed: () => void, failed: (error: unknown) => void): void;
+    /**
+     * Retain this committed process independently of output attachment.
+     * @param signal - physical window stream lifetime.
+     * @returns its hold acknowledgement and lifetime.
+     */
+    retain(signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>;
     /**
      * Attach with exclusive input control; an older attachment becomes read-only.
      * @param id - browser attachment identity.
@@ -52,6 +68,12 @@ export declare class BrowserTerminal {
      * @returns after process cleanup and final output drainage; failures remain retryable.
      */
     close(): Promise<void>;
+    /**
+     * Stop unattended cleanup scheduling and await final process cleanup.
+     * @returns after terminal and monitor quiescence.
+     */
+    dispose(): Promise<void>;
+    private closeProcess;
     private requireController;
     private broadcast;
     private enqueue;

package/lib/types/terminal.js

@@ -1,15 +1,10 @@
 /** One PTY, a bounded terminal emulator and its detachable browser followers. */
-import { createRequire } from 'node:module';
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+import { createLazyRequire } from '@deepseek-ai/dsh-lazy-require';
 import { TerminalFollower } from "./stream.js";
-const { Terminal, SerializeAddon } = loadXterm();
-function loadXterm() {
-    // The Preview's CommonJS wrapper owns its outer require binding; these literal calls also retain the CJS entries.
-    const require = createRequire(import.meta.url);
-    const { Terminal } = require('@xterm/headless');
-    const { SerializeAddon } = require('@xterm/addon-serialize');
-    return { Terminal, SerializeAddon };
-}
+import { TerminalRetention } from "./retention.js";
+const requireHeadless = createLazyRequire('@xterm/headless', import.meta.url);
+const requireSerialize = createLazyRequire('@xterm/addon-serialize', import.meta.url);
 /** Process lifetime is independent of follower and component lifetimes. */
 export class BrowserTerminal {
     handle;
@@ -22,6 +17,7 @@ export class BrowserTerminal {
     operations = Promise.resolve();
     drained;
     closing;
+    retention;
     controller;
     /**
      * @param handle - allocated terminal process range.
@@ -33,11 +29,37 @@ export class BrowserTerminal {
         this.handle = handle;
         this.info = info;
         this.maxBufferedBytes = maxBufferedBytes;
+        const { Terminal } = requireHeadless();
+        const { SerializeAddon } = requireSerialize();
         this.screen = new Terminal({ cols: info.cols, rows: info.rows, scrollback, allowProposedApi: true });
         this.serializer = new SerializeAddon();
         this.screen.loadAddon(this.serializer);
         this.drained = this.consume();
     }
+    /**
+     * Start monitoring after this allocation is committed to its Session owner.
+     * @param policy - validated Host timing policy.
+     * @param closing - closes the id before any asynchronous termination.
+     * @param closed - removes the exact successfully terminated owner record.
+     * @param failed - diagnostic sink for background cleanup failure.
+     */
+    monitor(policy, closing, closed, failed) {
+        this.retention = new TerminalRetention(policy, () => this.handle.inspectActivity(), async () => {
+            closing();
+            await this.closeProcess();
+            closed();
+        }, failed);
+    }
+    /**
+     * Retain this committed process independently of output attachment.
+     * @param signal - physical window stream lifetime.
+     * @returns its hold acknowledgement and lifetime.
+     */
+    retain(signal) {
+        if (this.retention === undefined)
+            throw new Error('Terminal has not been committed');
+        return this.retention.retain(signal);
+    }
     /**
      * Attach with exclusive input control; an older attachment becomes read-only.
      * @param id - browser attachment identity.
@@ -78,6 +100,7 @@ export class BrowserTerminal {
      * @returns when the provider accepts the input.
      */
     write(id, data) {
+        this.retention?.invalidate();
         return this.enqueue(async () => { this.requireController(id); await this.handle.write(data); });
     }
     /**
@@ -109,6 +132,14 @@ export class BrowserTerminal {
      * @returns after process cleanup and final output drainage; failures remain retryable.
      */
     close() {
+        return this.retention?.close() ?? this.closeProcess();
+    }
+    /**
+     * Stop unattended cleanup scheduling and await final process cleanup.
+     * @returns after terminal and monitor quiescence.
+     */
+    dispose() { return this.retention?.dispose() ?? this.closeProcess(); }
+    closeProcess() {
         if (this.closing !== undefined)
             return this.closing;
         this.closing = (async () => {

package/lib/types/types.d.ts

@@ -2,6 +2,8 @@
 import type { Branded } from '@deepseek-ai/dsh-brand';
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {
+        /** The terminal identity is missing or has begun process cleanup. */
+        'terminal/unavailable': Record<string, never>;
         /** Input or resize was refused without invalidating the output attachment. */
         'terminal/control-unavailable': {
             readonly reason: 'read-only' | 'not-running';
@@ -16,6 +18,10 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
 export type WebTerminalId = Branded<'WebTerminalId'>;
 /** An attachment allowed to write and resize one terminal. */
 export type TerminalAttachmentId = Branded<'TerminalAttachmentId'>;
+/** Acknowledges one physical window hold without taking screen or input control. */
+export interface TerminalRetentionFrame {
+    readonly type: 'retained';
+}
 /** An executable shell verified in the subprocess provider's execution environment. */
 export interface TerminalShell {
     readonly path: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-terminal-controller",
   "description": "Session-owned interactive terminals with shell discovery, screen recovery and typed Remote control",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -53,28 +53,29 @@
     "@xterm/headless": "^6.0.0",
     "@xterm/addon-serialize": "^0.14.0",
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-deque": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-deque": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-lazy-require": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-util-crypto": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-util-crypto": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2"
   },
   "files": [
     "lib/index.js",