@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/host/terminal/broker/conpty-broker-process.js

@@ -0,0 +1,147 @@
+import { timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:net';
+import { spawn } from '@lydell/node-pty';
+import { BoundedTerminalBuffer, ExclusiveAttachmentLease, createJsonLineParser, parseBrokerRequest, writeBrokerMessage, } from './conpty-broker-protocol.js';
+import { normalizeTerminalSize } from '../runtime-adapter.js';
+export function runConptyBroker(args) {
+    if (process.platform !== 'win32')
+        throw new Error('ConPTY broker 只能在 Windows 上运行');
+    const pty = spawn(args.shellPath, [...args.shellArgs], {
+        cwd: args.cwd,
+        env: process.env,
+        cols: 120,
+        rows: 30,
+        name: 'xterm-256color',
+    });
+    const outputBuffer = new BoundedTerminalBuffer();
+    const attachmentLease = new ExclusiveAttachmentLease();
+    const attachedSockets = new Set();
+    const terminationWaiters = new Set();
+    let exited = false;
+    const server = createServer((socket) => {
+        let attached = false;
+        const parser = createJsonLineParser((value) => {
+            const request = parseBrokerRequest(value);
+            if (request === null)
+                return fail(socket, 'INVALID_PROTOCOL', '无效的 broker 请求');
+            if (!sameSecret(request.auth, args.auth))
+                return fail(socket, 'UNAUTHORIZED', 'broker 认证失败');
+            if (request.type === 'inspect') {
+                writeBrokerMessage(socket, { version: 1, type: 'inspect-result', alive: !exited, brokerPid: process.pid, shellPid: pty.pid });
+                socket.end();
+                return;
+            }
+            if (request.type === 'terminate') {
+                if (exited) {
+                    writeBrokerMessage(socket, { version: 1, type: 'terminated' });
+                    socket.end();
+                    return;
+                }
+                terminationWaiters.add(socket);
+                try {
+                    pty.kill();
+                }
+                catch {
+                    terminationWaiters.delete(socket);
+                    fail(socket, 'TERMINATE_FAILED', 'ConPTY shell 终止失败');
+                }
+                return;
+            }
+            if (request.type === 'attach') {
+                const size = normalizeTerminalSize(request.cols, request.rows);
+                attached = true;
+                attachedSockets.add(socket);
+                attachmentLease.takeover(socket);
+                pty.resize(size.cols, size.rows);
+                writeBrokerMessage(socket, { version: 1, type: 'attached', brokerPid: process.pid, shellPid: pty.pid });
+                const buffered = outputBuffer.snapshot();
+                if (buffered !== '')
+                    writeBrokerMessage(socket, { version: 1, type: 'output', data: buffered });
+                return;
+            }
+            if (!attached || !attachmentLease.owns(socket))
+                return fail(socket, 'NOT_ATTACHED', '连接尚未 attach');
+            if (request.type === 'input')
+                pty.write(request.data);
+            if (request.type === 'resize') {
+                const size = normalizeTerminalSize(request.cols, request.rows);
+                pty.resize(size.cols, size.rows);
+            }
+            if (request.type === 'detach')
+                socket.end();
+        });
+        socket.on('data', (chunk) => {
+            try {
+                parser.push(chunk);
+            }
+            catch {
+                fail(socket, 'INVALID_PROTOCOL', 'broker 控制帧无法解析');
+            }
+        });
+        const release = () => {
+            attachmentLease.release(socket);
+            attachedSockets.delete(socket);
+        };
+        socket.once('close', release);
+        socket.once('error', release);
+    });
+    pty.onData((data) => {
+        outputBuffer.push(data);
+        for (const socket of attachedSockets)
+            writeBrokerMessage(socket, { version: 1, type: 'output', data });
+    });
+    pty.onExit(({ exitCode }) => {
+        exited = true;
+        for (const socket of attachedSockets) {
+            writeBrokerMessage(socket, { version: 1, type: 'exit', exitCode });
+            socket.end();
+        }
+        attachedSockets.clear();
+        for (const waiter of terminationWaiters) {
+            writeBrokerMessage(waiter, { version: 1, type: 'terminated' });
+            waiter.end();
+        }
+        terminationWaiters.clear();
+        server.close(() => undefined);
+    });
+    // readableAll/writableAll=false 明确要求 Windows 使用当前用户的默认 Named Pipe ACL。
+    server.listen({ path: args.pipeName, readableAll: false, writableAll: false });
+}
+function fail(socket, code, message) {
+    writeBrokerMessage(socket, { version: 1, type: 'error', code, message });
+    socket.end();
+}
+function sameSecret(actual, expected) {
+    const encoder = new TextEncoder();
+    const left = encoder.encode(actual);
+    const right = encoder.encode(expected);
+    return left.byteLength === right.byteLength && timingSafeEqual(left, right);
+}
+function readArguments(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 2) {
+        const name = argv[index];
+        const value = argv[index + 1];
+        if (name?.startsWith('--') && value !== undefined)
+            values.set(name.slice(2), value);
+    }
+    const pipeName = values.get('pipe');
+    const auth = values.get('auth') ?? process.env.CODINGNS4DSH_TERMINAL_AUTH;
+    const shellPath = values.get('shell');
+    const cwd = values.get('cwd');
+    const shellArgs = parseShellArgs(process.env.CODINGNS4DSH_TERMINAL_ARGS);
+    if (!pipeName || !auth || !shellPath || !cwd)
+        throw new Error('ConPTY broker 启动参数不完整');
+    return { pipeName, auth, shellPath, shellArgs, cwd };
+}
+function parseShellArgs(value) {
+    if (value === undefined)
+        return [];
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== 'string')) {
+        throw new Error('ConPTY shell 参数无效');
+    }
+    return parsed;
+}
+runConptyBroker(readArguments(process.argv.slice(2)));
+//# sourceMappingURL=conpty-broker-process.js.map

package/data/build/dist/host/terminal/broker/conpty-broker-protocol.d.ts

@@ -0,0 +1,92 @@
+export declare const CONPTY_BROKER_PROTOCOL_VERSION: 1;
+export declare const CONPTY_BROKER_MAX_BUFFERED_BYTES: number;
+export type ConptyBrokerRequest = {
+    readonly version: 1;
+    readonly auth: string;
+    readonly type: 'inspect';
+} | {
+    readonly version: 1;
+    readonly auth: string;
+    readonly type: 'attach';
+    readonly cols: number;
+    readonly rows: number;
+} | {
+    readonly version: 1;
+    readonly auth: string;
+    readonly type: 'input';
+    readonly data: string;
+} | {
+    readonly version: 1;
+    readonly auth: string;
+    readonly type: 'resize';
+    readonly cols: number;
+    readonly rows: number;
+} | {
+    readonly version: 1;
+    readonly auth: string;
+    readonly type: 'detach';
+} | {
+    readonly version: 1;
+    readonly auth: string;
+    readonly type: 'terminate';
+};
+export type ConptyBrokerMessage = {
+    readonly version: 1;
+    readonly type: 'inspect-result';
+    readonly alive: boolean;
+    readonly brokerPid: number;
+    readonly shellPid: number;
+} | {
+    readonly version: 1;
+    readonly type: 'attached';
+    readonly brokerPid: number;
+    readonly shellPid: number;
+} | {
+    readonly version: 1;
+    readonly type: 'output';
+    readonly data: string;
+} | {
+    readonly version: 1;
+    readonly type: 'exit';
+    readonly exitCode: number | null;
+} | {
+    readonly version: 1;
+    readonly type: 'terminated';
+} | {
+    readonly version: 1;
+    readonly type: 'error';
+    readonly code: string;
+    readonly message: string;
+};
+export interface JsonLineTarget {
+    write(data: string): unknown;
+}
+/** broker 同时只允许一个 attach；重复连接不能抢占当前终端。 */
+export declare class ExclusiveAttachmentLease<T extends object> {
+    private owner;
+    acquire(candidate: T): boolean;
+    /** 新 attach 接管输入控制权；旧 attach 保持只读输出。 */
+    takeover(candidate: T): T | null;
+    release(candidate: T): void;
+    owns(candidate: T): boolean;
+    get current(): T | null;
+}
+/** 每条消息一个 JSON 行，避免终端输出与控制帧混在同一字节流中。 */
+export declare function writeBrokerMessage(target: JsonLineTarget, message: ConptyBrokerMessage | ConptyBrokerRequest): void;
+export declare function createJsonLineParser(onValue: (value: unknown) => void): {
+    push(chunk: string | Uint8Array): void;
+};
+export declare function parseBrokerRequest(value: unknown): ConptyBrokerRequest | null;
+export declare function parseBrokerMessage(value: unknown): ConptyBrokerMessage | null;
+/** 无 attach 时只保留最后一段有界输出，避免常驻 broker 无限吃内存。 */
+export declare class BoundedTerminalBuffer {
+    readonly maxBytes: number;
+    private value;
+    constructor(maxBytes?: number);
+    push(data: string): void;
+    drain(): string;
+    /** 返回有界输出副本但不清空，供 DSH 重启后的新 attach 回放。 */
+    snapshot(): string;
+    get byteLength(): number;
+}
+//# sourceMappingURL=conpty-broker-protocol.d.ts.map

package/data/build/dist/host/terminal/broker/conpty-broker-protocol.js

@@ -0,0 +1,134 @@
+export const CONPTY_BROKER_PROTOCOL_VERSION = 1;
+export const CONPTY_BROKER_MAX_BUFFERED_BYTES = 1024 * 1024;
+/** broker 同时只允许一个 attach；重复连接不能抢占当前终端。 */
+export class ExclusiveAttachmentLease {
+    owner = null;
+    acquire(candidate) {
+        if (this.owner !== null && this.owner !== candidate)
+            return false;
+        this.owner = candidate;
+        return true;
+    }
+    /** 新 attach 接管输入控制权；旧 attach 保持只读输出。 */
+    takeover(candidate) {
+        const previous = this.owner;
+        this.owner = candidate;
+        return previous;
+    }
+    release(candidate) {
+        if (this.owner === candidate)
+            this.owner = null;
+    }
+    owns(candidate) {
+        return this.owner === candidate;
+    }
+    get current() {
+        return this.owner;
+    }
+}
+/** 每条消息一个 JSON 行，避免终端输出与控制帧混在同一字节流中。 */
+export function writeBrokerMessage(target, message) {
+    target.write(`${JSON.stringify(message)}\n`);
+}
+export function createJsonLineParser(onValue) {
+    const decoder = new TextDecoder();
+    let pending = '';
+    return {
+        push(chunk) {
+            pending += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+            let boundary = pending.indexOf('\n');
+            while (boundary >= 0) {
+                const line = pending.slice(0, boundary).trim();
+                pending = pending.slice(boundary + 1);
+                if (line !== '')
+                    onValue(JSON.parse(line));
+                boundary = pending.indexOf('\n');
+            }
+            if (pending.length > 2 * 1024 * 1024)
+                throw new Error('broker 控制帧超过限制');
+        },
+    };
+}
+export function parseBrokerRequest(value) {
+    if (!isRecord(value) || value.version !== 1 || typeof value.auth !== 'string' || typeof value.type !== 'string')
+        return null;
+    if (value.type === 'inspect' || value.type === 'detach' || value.type === 'terminate') {
+        return { version: 1, auth: value.auth, type: value.type };
+    }
+    if (value.type === 'attach' || value.type === 'resize') {
+        if (typeof value.cols !== 'number' || typeof value.rows !== 'number')
+            return null;
+        return { version: 1, auth: value.auth, type: value.type, cols: value.cols, rows: value.rows };
+    }
+    if (value.type === 'input' && typeof value.data === 'string') {
+        return { version: 1, auth: value.auth, type: 'input', data: value.data };
+    }
+    return null;
+}
+export function parseBrokerMessage(value) {
+    if (!isRecord(value) || value.version !== 1 || typeof value.type !== 'string')
+        return null;
+    if (value.type === 'output' && typeof value.data === 'string')
+        return { version: 1, type: 'output', data: value.data };
+    if (value.type === 'exit' && (typeof value.exitCode === 'number' || value.exitCode === null)) {
+        return { version: 1, type: 'exit', exitCode: value.exitCode };
+    }
+    if (value.type === 'terminated')
+        return { version: 1, type: 'terminated' };
+    if (value.type === 'error' && typeof value.code === 'string' && typeof value.message === 'string') {
+        return { version: 1, type: 'error', code: value.code, message: value.message };
+    }
+    if ((value.type === 'inspect-result' || value.type === 'attached')
+        && typeof value.brokerPid === 'number' && typeof value.shellPid === 'number') {
+        if (value.type === 'inspect-result' && typeof value.alive === 'boolean') {
+            return { version: 1, type: 'inspect-result', alive: value.alive, brokerPid: value.brokerPid, shellPid: value.shellPid };
+        }
+        if (value.type === 'attached') {
+            return { version: 1, type: 'attached', brokerPid: value.brokerPid, shellPid: value.shellPid };
+        }
+    }
+    return null;
+}
+/** 无 attach 时只保留最后一段有界输出，避免常驻 broker 无限吃内存。 */
+export class BoundedTerminalBuffer {
+    maxBytes;
+    value = '';
+    constructor(maxBytes = CONPTY_BROKER_MAX_BUFFERED_BYTES) {
+        this.maxBytes = maxBytes;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+            throw new Error('缓冲上限必须是正整数');
+    }
+    push(data) {
+        this.value += data;
+        while (byteLength(this.value) > this.maxBytes && this.value.length > 0) {
+            const overflow = byteLength(this.value) - this.maxBytes;
+            // 先按 UTF-16 字符估计裁剪，再校正；不会从半个代理对开始输出。
+            let cut = Math.max(1, Math.min(this.value.length, overflow));
+            if (cut < this.value.length && isLowSurrogate(this.value.charCodeAt(cut)))
+                cut += 1;
+            this.value = this.value.slice(cut);
+        }
+    }
+    drain() {
+        const output = this.value;
+        this.value = '';
+        return output;
+    }
+    /** 返回有界输出副本但不清空，供 DSH 重启后的新 attach 回放。 */
+    snapshot() {
+        return this.value;
+    }
+    get byteLength() {
+        return byteLength(this.value);
+    }
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function isLowSurrogate(value) {
+    return value >= 0xdc00 && value <= 0xdfff;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=conpty-broker-protocol.js.map

package/data/build/dist/host/terminal/controller-factory.d.ts

@@ -0,0 +1,37 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { TerminalEnhancementSettings } from '../../shared/contracts/config.js';
+import { CodingNsTerminalController, type DshTerminalAgent } from './terminal-controller.js';
+import type { TerminalRuntimeAdapter } from './runtime-adapter.js';
+import { CodingNsTerminalService } from './terminal-service.js';
+import { TerminalProcessService } from './terminal-process-service.js';
+interface TerminalControllerFactoryCommonOptions {
+    readonly settings: () => TerminalEnhancementSettings;
+    readonly platform?: string;
+    readonly generation?: (agent: DshTerminalAgent, attachmentId: string) => string;
+    readonly workspaceId?: (agent: DshTerminalAgent, cwd: string) => string;
+    readonly resolveWorkspaceRoot?: (workspaceId: string) => string | null;
+}
+export type TerminalControllerFactoryOptions = TerminalControllerFactoryCommonOptions & ({
+    readonly enhancedEnabled: false;
+    readonly baselineBackend?: TerminalRuntimeAdapter;
+} | {
+    readonly enhancedEnabled: true;
+    readonly hostId: string;
+    readonly storeFilename: string;
+    readonly processStoreFilename?: string;
+});
+export interface TerminalControllerFactoryResult {
+    readonly mode: 'baseline' | 'enhanced';
+    readonly controller: CodingNsTerminalController;
+    readonly service: CodingNsTerminalService;
+    readonly processService: TerminalProcessService;
+}
+/**
+ * 启动时一次性选择 controller 模式。
+ *
+ * 开关写入只影响下一次调用；当前进程绝不热切同名 Cordis 服务。两个模式共用
+ * 插件自有 controller，区别只在 backend 和 store 的生命周期。
+ */
+export declare function createTerminalController(ctx: Context, options: TerminalControllerFactoryOptions): Promise<TerminalControllerFactoryResult>;
+export {};
+//# sourceMappingURL=controller-factory.d.ts.map

package/data/build/dist/host/terminal/controller-factory.js

@@ -0,0 +1,82 @@
+import { ConptyTerminalBackend } from './backends/conpty-backend.js';
+import { LocalPtyTerminalBackend } from './backends/local-pty-backend.js';
+import { TmuxTerminalBackend } from './backends/tmux-backend.js';
+import { CodingNsTerminalController } from './terminal-controller.js';
+import { TerminalRuntimeManager } from './runtime-manager.js';
+import { CodingNsTerminalService } from './terminal-service.js';
+import { CodingNsTerminalStore, InMemoryTerminalStorePersistence, JsonFileTerminalStorePersistence, } from './terminal-store.js';
+import { InMemoryTerminalProcessStorePersistence, JsonFileTerminalProcessStorePersistence, TerminalProcessStore, } from './terminal-process-store.js';
+import { TerminalProcessService } from './terminal-process-service.js';
+/**
+ * 启动时一次性选择 controller 模式。
+ *
+ * 开关写入只影响下一次调用；当前进程绝不热切同名 Cordis 服务。两个模式共用
+ * 插件自有 controller，区别只在 backend 和 store 的生命周期。
+ */
+export async function createTerminalController(ctx, options) {
+    const platform = options.platform ?? process.platform;
+    if (!options.enhancedEnabled) {
+        const backend = options.baselineBackend ?? new LocalPtyTerminalBackend({ platform });
+        return assembleController(ctx, {
+            mode: 'baseline',
+            hostId: 'local-baseline',
+            store: new CodingNsTerminalStore(new InMemoryTerminalStorePersistence()),
+            backend,
+            processStore: new TerminalProcessStore(new InMemoryTerminalProcessStorePersistence()),
+            settings: options.settings,
+            platform,
+            runtimeType: () => 'local-pty',
+            ...(options.generation === undefined ? {} : { generation: options.generation }),
+            ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+            ...(options.resolveWorkspaceRoot === undefined ? {} : { resolveWorkspaceRoot: options.resolveWorkspaceRoot }),
+        });
+    }
+    const backend = platform === 'win32'
+        ? new ConptyTerminalBackend({ platform })
+        : new TmuxTerminalBackend({ platform });
+    return assembleController(ctx, {
+        mode: 'enhanced',
+        hostId: options.hostId,
+        store: new CodingNsTerminalStore(new JsonFileTerminalStorePersistence(options.storeFilename)),
+        processStore: new TerminalProcessStore(new JsonFileTerminalProcessStorePersistence(options.processStoreFilename ?? `${options.storeFilename}.processes`)),
+        backend,
+        settings: options.settings,
+        platform,
+        ...(options.generation === undefined ? {} : { generation: options.generation }),
+        ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+        ...(options.resolveWorkspaceRoot === undefined ? {} : { resolveWorkspaceRoot: options.resolveWorkspaceRoot }),
+    });
+}
+async function assembleController(ctx, options) {
+    const service = new CodingNsTerminalService(options.store, new TerminalRuntimeManager([options.backend]));
+    await service.initialize();
+    if (options.mode === 'enhanced')
+        await service.recover();
+    const controller = new CodingNsTerminalController(ctx, {
+        hostId: options.hostId,
+        service,
+        settings: options.settings,
+        ...(options.platform === undefined ? {} : { platform: options.platform }),
+        ...(options.generation === undefined ? {} : { generation: options.generation }),
+        ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+        ...(options.runtimeType === undefined ? {} : { runtimeType: options.runtimeType }),
+    });
+    const processService = new TerminalProcessService(options.processStore, {
+        hostId: options.hostId,
+        terminalService: service,
+        resolveWorkspaceRoot: options.resolveWorkspaceRoot ?? ((workspaceId) => workspaceId),
+    });
+    await processService.initialize();
+    if (options.mode === 'enhanced')
+        await processService.recover();
+    ctx.effect(() => () => service.dispose(), options.mode === 'baseline'
+        ? 'codingns4dsh: 本机 PTY 与终端 attach 清理'
+        : 'codingns4dsh: 持久终端 attach 清理');
+    return {
+        mode: options.mode,
+        controller,
+        service,
+        processService,
+    };
+}
+//# sourceMappingURL=controller-factory.js.map

package/data/build/dist/host/terminal/index.d.ts

@@ -0,0 +1,17 @@
+export * from './runtime-adapter.js';
+export * from './runtime-manager.js';
+export * from './attachment-registry.js';
+export * from './terminal-store.js';
+export * from './terminal-service.js';
+export * from './terminal-process-store.js';
+export * from './terminal-process-service.js';
+export * from './terminal-controller.js';
+export * from './controller-factory.js';
+export * from './startup.js';
+export * from './shell-detection.js';
+export * from './backends/tmux-backend.js';
+export * from './backends/conpty-backend.js';
+export * from './backends/local-pty-backend.js';
+export * from './broker/conpty-broker-client.js';
+export * from './broker/conpty-broker-protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/data/build/dist/host/terminal/index.js

@@ -0,0 +1,17 @@
+export * from './runtime-adapter.js';
+export * from './runtime-manager.js';
+export * from './attachment-registry.js';
+export * from './terminal-store.js';
+export * from './terminal-service.js';
+export * from './terminal-process-store.js';
+export * from './terminal-process-service.js';
+export * from './terminal-controller.js';
+export * from './controller-factory.js';
+export * from './startup.js';
+export * from './shell-detection.js';
+export * from './backends/tmux-backend.js';
+export * from './backends/conpty-backend.js';
+export * from './backends/local-pty-backend.js';
+export * from './broker/conpty-broker-client.js';
+export * from './broker/conpty-broker-protocol.js';
+//# sourceMappingURL=index.js.map

package/data/build/dist/host/terminal/runtime-adapter.d.ts

@@ -0,0 +1,77 @@
+import type { CodingNsTerminalRuntimeType } from '../../shared/contracts/terminal.js';
+/** Host backend 直接复用共享持久记录的运行时枚举，避免 controller 做无意义转换。 */
+export type TerminalRuntimeType = CodingNsTerminalRuntimeType;
+/** 持久运行时只保存可在 DSH 重启后重新定位会话的字段。 */
+export interface TerminalRuntimeSession {
+    readonly runtimeSessionKey: string;
+    readonly runtimeType: TerminalRuntimeType;
+    readonly shellPath: string;
+    readonly shellArgs: readonly string[];
+    /** 启动项 PTY 的实际命令；未设置时使用 shellPath/shellArgs。 */
+    readonly commandPath?: string;
+    readonly commandArgs?: readonly string[];
+    readonly commandEnv?: Readonly<Record<string, string>>;
+    readonly cwd: string;
+}
+export interface TerminalRuntimeIdentity {
+    readonly alive: boolean;
+    readonly runtimeSessionKey: string;
+    readonly runtimePid: number | null;
+    readonly shellPid: number | null;
+    readonly detail?: string;
+}
+export interface TerminalRuntimeCreateInput {
+    readonly session: TerminalRuntimeSession;
+    readonly cols?: number;
+    readonly rows?: number;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export interface TerminalRuntimeAttachInput {
+    readonly session: TerminalRuntimeSession;
+    readonly cols: number;
+    readonly rows: number;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly onData: (data: string) => void;
+    readonly onExit?: (exitCode: number | null) => void;
+}
+export interface TerminalRuntimeAttachment {
+    readonly attachmentId: string;
+    readonly identity: TerminalRuntimeIdentity;
+}
+export interface TerminalRuntimeWriteInput {
+    readonly attachmentId: string;
+    readonly data: string;
+}
+export interface TerminalRuntimeResizeInput {
+    readonly attachmentId: string;
+    readonly cols: number;
+    readonly rows: number;
+}
+/**
+ * controller 只依赖这个接口。持久 session 与短命 attachment 使用不同标识，
+ * 因而卸载插件或切换 generation 时不会误杀 tmux/ConPTY。
+ */
+export interface TerminalRuntimeAdapter {
+    readonly runtimeTypes: readonly TerminalRuntimeType[];
+    create(input: TerminalRuntimeCreateInput): Promise<TerminalRuntimeIdentity>;
+    inspect(session: TerminalRuntimeSession): Promise<TerminalRuntimeIdentity>;
+    attach(input: TerminalRuntimeAttachInput): Promise<TerminalRuntimeAttachment>;
+    write(input: TerminalRuntimeWriteInput): Promise<void>;
+    resize(input: TerminalRuntimeResizeInput): Promise<void>;
+    detach(attachmentId: string): Promise<void>;
+    terminate(session: TerminalRuntimeSession): Promise<void>;
+    /** 仅供进程内 backend 释放自身拥有的运行时；持久 backend 不实现此方法。 */
+    dispose?(): Promise<void>;
+}
+export type TerminalRuntimeErrorCode = 'TERMINAL_PLATFORM_UNSUPPORTED' | 'TERMINAL_RUNTIME_UNAVAILABLE' | 'TERMINAL_RUNTIME_CREATE_FAILED' | 'TERMINAL_RUNTIME_LOST' | 'TERMINAL_ATTACHMENT_NOT_FOUND' | 'TERMINAL_ALREADY_ATTACHED' | 'TERMINAL_BROKER_PROTOCOL_INVALID' | 'TERMINAL_BROKER_UNAUTHORIZED';
+export declare class TerminalRuntimeError extends Error {
+    readonly code: TerminalRuntimeErrorCode;
+    constructor(code: TerminalRuntimeErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export declare function normalizeTerminalSize(cols: number, rows: number): {
+    cols: number;
+    rows: number;
+};
+//# sourceMappingURL=runtime-adapter.d.ts.map

package/data/build/dist/host/terminal/runtime-adapter.js

@@ -0,0 +1,18 @@
+export class TerminalRuntimeError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'TerminalRuntimeError';
+    }
+}
+export function normalizeTerminalSize(cols, rows) {
+    return {
+        cols: normalizeDimension(cols, 20, 500, 120),
+        rows: normalizeDimension(rows, 5, 300, 30),
+    };
+}
+function normalizeDimension(value, minimum, maximum, fallback) {
+    return Number.isFinite(value) ? Math.min(maximum, Math.max(minimum, Math.trunc(value))) : fallback;
+}
+//# sourceMappingURL=runtime-adapter.js.map

package/data/build/dist/host/terminal/runtime-manager.d.ts

@@ -0,0 +1,41 @@
+import type { PersistentTerminalRecord, TerminalRecordIdentity } from '../../shared/contracts/terminal.js';
+import { type ManagedTerminalAttachment } from './attachment-registry.js';
+import type { TerminalRuntimeAdapter, TerminalRuntimeIdentity } from './runtime-adapter.js';
+export interface RuntimeAttachmentInput {
+    readonly identity: TerminalRecordIdentity;
+    readonly generation: string;
+    readonly streamId: string;
+    readonly requestedAttachmentId: string;
+    readonly cols: number;
+    readonly rows: number;
+    readonly onData: (data: string) => void;
+    readonly onExit: (exitCode: number | null) => void;
+}
+/** 统一选择 backend，并确保停用插件时只清理 attach，不结束持久进程。 */
+export declare class TerminalRuntimeManager {
+    private readonly adapters;
+    private readonly registry;
+    private readonly monitors;
+    constructor(adapters: readonly TerminalRuntimeAdapter[]);
+    create(record: PersistentTerminalRecord): Promise<TerminalRuntimeIdentity>;
+    inspect(record: PersistentTerminalRecord): Promise<TerminalRuntimeIdentity>;
+    attach(record: PersistentTerminalRecord, input: RuntimeAttachmentInput): Promise<ManagedTerminalAttachment>;
+    write(subscriptionId: string, data: string): Promise<void>;
+    /**
+     * 在不抢占浏览器 attach 控制权的前提下，向持久终端写入一次启动命令。
+     * 这是调试快捷启动所需的“先开 Shell、再发送命令”路径。
+     */
+    writeSession(record: PersistentTerminalRecord, data: string): Promise<void>;
+    resize(subscriptionId: string, cols: number, rows: number): Promise<void>;
+    detach(subscriptionId: string): Promise<void>;
+    detachGeneration(generation: string): Promise<void>;
+    detachTerminal(identity: TerminalRecordIdentity): Promise<void>;
+    /** 为 Host 进程状态提供退出监听，不获取终端输入控制权。 */
+    monitor(record: PersistentTerminalRecord, onExit: (exitCode: number | null) => void): Promise<void>;
+    detachMonitor(record: PersistentTerminalRecord): Promise<void>;
+    dispose(): Promise<void>;
+    terminate(record: PersistentTerminalRecord): Promise<void>;
+    private adapter;
+    private requireAttachment;
+}
+//# sourceMappingURL=runtime-manager.d.ts.map