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

package/lib/types/stream.js

@@ -0,0 +1,78 @@
+/** A bounded output queue for one Remote stream generation. */
+import { Deque } from '@deepseek-ai/dsh-deque';
+/** Slow followers fail explicitly; a later attachment recovers from the screen. */
+export class TerminalFollower {
+    maxBytes;
+    queue = new Deque();
+    bytes = 0;
+    wake;
+    closed = false;
+    finished = false;
+    failure;
+    /** @param maxBytes - maximum queued UTF-8 bytes for this follower. */
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    /**
+     * Queue a frame or fail this follower when its byte limit is exceeded.
+     * @param frame - next ordered frame.
+     */
+    push(frame) {
+        if (this.closed || this.finished)
+            return;
+        const bytes = Buffer.byteLength(JSON.stringify(frame), 'utf8');
+        if (this.bytes + bytes > this.maxBytes) {
+            this.failure = new Error('Terminal output consumer exceeded its buffer; reconnect to recover the current screen');
+            this.close();
+            return;
+        }
+        this.queue.pushBack({ frame, bytes });
+        this.bytes += bytes;
+        this.wake?.();
+    }
+    /** Finish after delivering every queued frame, including the final exit state. */
+    finish() {
+        this.finished = true;
+        this.wake?.();
+    }
+    /** Stop this follower without stopping its terminal. */
+    close() {
+        this.closed = true;
+        this.queue.clear();
+        this.bytes = 0;
+        this.wake?.();
+    }
+    /**
+     * Drain until detached or failed.
+     * @param signal - Remote generation cancellation.
+     * @returns ordered terminal frames.
+     */
+    async *read(signal) {
+        const abort = () => { this.close(); };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        try {
+            while (!this.closed) {
+                const next = this.queue.popFront();
+                if (next !== undefined) {
+                    this.bytes -= next.bytes;
+                    yield next.frame;
+                }
+                else {
+                    if (this.finished)
+                        break;
+                    await new Promise((resolve) => { this.wake = resolve; });
+                    this.wake = undefined;
+                }
+            }
+            if (this.failure !== undefined)
+                throw this.failure;
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+            this.close();
+        }
+    }
+}
+//# sourceMappingURL=stream.js.map

package/lib/types/terminal.d.ts

@@ -0,0 +1,61 @@
+import type { SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess';
+import type { TerminalAttachmentId, TerminalFrame, WebTerminalInfo } from './types.ts';
+/** Process lifetime is independent of follower and component lifetimes. */
+export declare class BrowserTerminal {
+    private readonly handle;
+    info: WebTerminalInfo;
+    private readonly maxBufferedBytes;
+    private readonly screen;
+    private readonly serializer;
+    private readonly followers;
+    private sequence;
+    private operations;
+    private readonly drained;
+    private closing;
+    private controller;
+    /**
+     * @param handle - allocated terminal process range.
+     * @param info - initial metadata.
+     * @param scrollback - maximum retained scrollback rows.
+     * @param maxBufferedBytes - per-follower queue cap.
+     */
+    constructor(handle: SubprocessTerminalHandle, info: WebTerminalInfo, scrollback: number, maxBufferedBytes: number);
+    /**
+     * Attach with exclusive input control; an older attachment becomes read-only.
+     * @param id - browser attachment identity.
+     * @param signal - attachment cancellation; never terminates the process.
+     * @returns a consistent screen followed by ordered output and state changes.
+     */
+    follow(id: TerminalAttachmentId, signal: AbortSignal): AsyncIterable<TerminalFrame>;
+    /**
+     * Send raw terminal input without command interpretation.
+     * @param id - current writable attachment.
+     * @param data - UTF-8 input, including shell completion/control keys.
+     * @returns when the provider accepts the input.
+     */
+    write(id: TerminalAttachmentId, data: string): Promise<void>;
+    /**
+     * Resize the PTY and recovery screen in the same operation order as output.
+     * @param id - current writable attachment.
+     * @param cols - validated column count.
+     * @param rows - validated row count.
+     * @returns when the provider and emulator use the new dimensions.
+     */
+    resize(id: TerminalAttachmentId, cols: number, rows: number): Promise<void>;
+    /**
+     * Publish a display name to every attached view.
+     * @param title - validated user title.
+     */
+    rename(title: string): void;
+    /**
+     * Terminate the complete provider-owned process range before releasing its screen.
+     * @returns after process cleanup and final output drainage; failures remain retryable.
+     */
+    close(): Promise<void>;
+    private requireController;
+    private broadcast;
+    private enqueue;
+    private consume;
+    private output;
+}
+//# sourceMappingURL=terminal.d.ts.map

package/lib/types/terminal.js

@@ -0,0 +1,168 @@
+/** 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 { 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 };
+}
+/** Process lifetime is independent of follower and component lifetimes. */
+export class BrowserTerminal {
+    handle;
+    info;
+    maxBufferedBytes;
+    screen;
+    serializer;
+    followers = new Set();
+    sequence = 0;
+    operations = Promise.resolve();
+    drained;
+    closing;
+    controller;
+    /**
+     * @param handle - allocated terminal process range.
+     * @param info - initial metadata.
+     * @param scrollback - maximum retained scrollback rows.
+     * @param maxBufferedBytes - per-follower queue cap.
+     */
+    constructor(handle, info, scrollback, maxBufferedBytes) {
+        this.handle = handle;
+        this.info = info;
+        this.maxBufferedBytes = maxBufferedBytes;
+        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();
+    }
+    /**
+     * Attach with exclusive input control; an older attachment becomes read-only.
+     * @param id - browser attachment identity.
+     * @param signal - attachment cancellation; never terminates the process.
+     * @returns a consistent screen followed by ordered output and state changes.
+     */
+    async *follow(id, signal) {
+        signal.throwIfAborted();
+        const follower = new TerminalFollower(this.maxBufferedBytes);
+        const baseline = await this.enqueue(() => {
+            signal.throwIfAborted();
+            this.controller = { id, follower };
+            this.info = { ...this.info, controllerId: id };
+            this.broadcast({ type: 'state', info: this.info });
+            const snapshot = { type: 'snapshot', sequence: this.sequence, screen: this.serializer.serialize(), info: this.info };
+            this.followers.add(follower);
+            return snapshot;
+        });
+        try {
+            yield baseline;
+            yield* follower.read(signal);
+        }
+        finally {
+            this.followers.delete(follower);
+            follower.close();
+            if (this.controller?.follower === follower) {
+                this.controller = undefined;
+                const { controllerId: _controllerId, ...info } = this.info;
+                this.info = info;
+                this.broadcast({ type: 'state', info });
+            }
+        }
+    }
+    /**
+     * Send raw terminal input without command interpretation.
+     * @param id - current writable attachment.
+     * @param data - UTF-8 input, including shell completion/control keys.
+     * @returns when the provider accepts the input.
+     */
+    write(id, data) {
+        return this.enqueue(async () => { this.requireController(id); await this.handle.write(data); });
+    }
+    /**
+     * Resize the PTY and recovery screen in the same operation order as output.
+     * @param id - current writable attachment.
+     * @param cols - validated column count.
+     * @param rows - validated row count.
+     * @returns when the provider and emulator use the new dimensions.
+     */
+    resize(id, cols, rows) {
+        return this.enqueue(async () => {
+            this.requireController(id);
+            await this.handle.resize(cols, rows);
+            this.screen.resize(cols, rows);
+            this.info = { ...this.info, cols, rows };
+            this.broadcast({ type: 'state', info: this.info });
+        });
+    }
+    /**
+     * Publish a display name to every attached view.
+     * @param title - validated user title.
+     */
+    rename(title) {
+        this.info = { ...this.info, title };
+        this.broadcast({ type: 'state', info: this.info });
+    }
+    /**
+     * Terminate the complete provider-owned process range before releasing its screen.
+     * @returns after process cleanup and final output drainage; failures remain retryable.
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.closing = (async () => {
+            await this.handle.terminate();
+            await this.drained;
+            for (const follower of this.followers)
+                follower.finish();
+            this.followers.clear();
+            this.screen.dispose();
+        })().catch((error) => { this.closing = undefined; throw error; });
+        return this.closing;
+    }
+    requireController(id) {
+        if (this.closing !== undefined || this.info.state !== 'running')
+            throw new RemoteError('terminal/control-unavailable', 'Terminal is not running', { reason: 'not-running' });
+        if (this.controller?.id !== id)
+            throw new RemoteError('terminal/control-unavailable', 'Terminal input is controlled by another attachment', { reason: 'read-only' });
+    }
+    broadcast(frame) {
+        for (const follower of this.followers)
+            follower.push(frame);
+    }
+    enqueue(operation) {
+        const pending = this.operations.then(operation);
+        this.operations = pending.catch(() => { });
+        return pending;
+    }
+    async consume() {
+        const decoder = new TextDecoder('utf-8', { ignoreBOM: true });
+        const outcome = this.handle.done.then(value => ({ value }), (error) => ({ error }));
+        try {
+            for await (const chunk of this.handle.output) {
+                // Node Readable's iterator is untyped; this provider explicitly emits Buffer chunks.
+                const data = decoder.decode(chunk, { stream: true });
+                await this.output(data);
+            }
+            await this.output(decoder.decode());
+            const result = await outcome;
+            if ('error' in result)
+                throw result.error;
+            this.info = { ...this.info, state: 'exited', exitCode: result.value.exitCode };
+        }
+        catch (error) {
+            this.info = { ...this.info, state: 'failed', error: error instanceof Error ? error.message : String(error) };
+        }
+        this.broadcast({ type: 'state', info: this.info });
+    }
+    async output(data) {
+        if (data.length === 0)
+            return;
+        await this.enqueue(async () => {
+            await new Promise((resolve) => { this.screen.write(data, resolve); });
+            this.broadcast({ type: 'output', sequence: ++this.sequence, data });
+        });
+    }
+}
+//# sourceMappingURL=terminal.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,69 @@
+/** Browser terminal identities, metadata and screen-stream frames. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** Input or resize was refused without invalidating the output attachment. */
+        'terminal/control-unavailable': {
+            readonly reason: 'read-only' | 'not-running';
+        };
+        /** Retained screens and pending allocations consume the Session's terminal quota. */
+        'terminal/limit-reached': {
+            readonly limit: number;
+        };
+    }
+}
+/** A terminal identity scoped to one Session and one Host lifetime. */
+export type WebTerminalId = Branded<'WebTerminalId'>;
+/** An attachment allowed to write and resize one terminal. */
+export type TerminalAttachmentId = Branded<'TerminalAttachmentId'>;
+/** An executable shell verified in the subprocess provider's execution environment. */
+export interface TerminalShell {
+    readonly path: string;
+    readonly args: readonly string[];
+    readonly name: string;
+}
+/** Working directory and limits shared by new and restored terminals. */
+export interface TerminalEnvironment {
+    readonly cwd: string;
+    readonly maxInputBytes: number;
+    readonly maxCols: number;
+    readonly maxRows: number;
+    readonly scrollback: number;
+}
+/** Host-owned terminal state; process exit never creates a replacement shell. */
+export interface WebTerminalInfo {
+    readonly id: WebTerminalId;
+    readonly title: string;
+    readonly shell: TerminalShell;
+    /** Initial working directory; shell directory changes do not update this field. */
+    readonly cwd: string;
+    readonly cols: number;
+    readonly rows: number;
+    readonly state: 'running' | 'exited' | 'failed';
+    readonly exitCode: number | null;
+    readonly error?: string;
+    readonly controllerId?: TerminalAttachmentId;
+}
+/** Create is idempotent for an open identity; closed identities cannot be recreated. */
+export interface TerminalCreateRequest {
+    /** A path returned by shell discovery; absent selects the execution default. */
+    readonly shellPath?: string;
+    readonly id: WebTerminalId;
+    readonly cols: number;
+    readonly rows: number;
+}
+/** Every attachment begins with a complete bounded screen, then ordered output. */
+export type TerminalFrame = {
+    readonly type: 'snapshot';
+    readonly sequence: number;
+    readonly screen: string;
+    readonly info: WebTerminalInfo;
+} | {
+    readonly type: 'output';
+    readonly sequence: number;
+    readonly data: string;
+} | {
+    readonly type: 'state';
+    readonly info: WebTerminalInfo;
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,93 @@
+{
+  "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",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/api/terminal-controller"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway"
+      ],
+      "external": [
+        "@deepseek-ai/dsh-api-gateway/client"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@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/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
+    "@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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}