super-dsh 0.1.6 → 0.1.10-e

package/superd-hub/dist/exec-pty-channel.js

@@ -0,0 +1,162 @@
+// PTY channels — the ONE seam spec §8.2 carves out of better-dsh's
+// PtySession: the session machinery (nonce injection, framing, two-stage
+// interrupt, idle TTL) is transport-agnostic; only {open, write, kill} differ
+// between "a local `script -qfec` subprocess" (this machine as target) and
+// "a WebSocket to the peer's dumb PTY executor" (a paired machine as target).
+//
+// The WS client follows mesh-gateway's crash-proofing lesson: an 'error'
+// listener is ALWAYS registered (ECONNREFUSED / a rejected 401 upgrade would
+// otherwise be an uncaught exception), and sends before 'open' queue in
+// order while post-close sends are swallowed (the session's death path owns
+// the teardown).
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+/** Local target: `script -qfec bash /dev/null` — host-side PTY, no node-pty (spec §8.2 / D12). */
+export class LocalScriptChannel {
+    argv;
+    diag = '';
+    proc = null;
+    deadCb;
+    constructor(argv = ['script', '-qfec', 'bash', '/dev/null']) {
+        this.argv = argv;
+    }
+    async open(onData) {
+        const proc = spawn(this.argv[0], this.argv.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+        this.proc = proc;
+        proc.stdout.setEncoding('utf8');
+        proc.stdout.on('data', (d) => onData(d));
+        proc.stderr.setEncoding('utf8').on('data', (d) => { this.diag = (this.diag + d).slice(-2_000); });
+        proc.once('close', () => this.deadCb?.());
+        proc.once('error', (err) => { this.diag = (this.diag + `\n[pty: spawn failed: ${err.message}]`).slice(-2_000); this.deadCb?.(); });
+    }
+    write(s) {
+        if (this.proc?.stdin?.writable !== true)
+            return;
+        try {
+            this.proc.stdin.write(s);
+        }
+        catch { /* dead: the death callback settles the session */ }
+    }
+    close() {
+        this.write('exit\n');
+        const pid = this.proc?.pid;
+        this.proc = null;
+        if (pid === undefined)
+            return;
+        setTimeout(() => { try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch { /* already gone */ } }, 1_000).unref();
+    }
+    kill() {
+        const pid = this.proc?.pid;
+        this.proc = null;
+        if (pid === undefined)
+            return;
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+        setTimeout(() => { try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch { /* already gone */ } }, 2_000).unref();
+    }
+    onDead(callback) { this.deadCb = callback; }
+}
+const WS_MODULE = 'ws';
+let wsConstructor;
+function loadWs() {
+    if (wsConstructor !== undefined)
+        return wsConstructor;
+    const require = createRequire(import.meta.url);
+    const mod = require(WS_MODULE);
+    const boxed = mod;
+    wsConstructor = (typeof mod === 'function' ? mod : boxed.default);
+    return wsConstructor;
+}
+/** Remote target: a WebSocket to the peer hub's dumb PTY executor, pairing Cookie riding the upgrade. */
+export class WsPtyChannel {
+    url;
+    headers;
+    wsCtor;
+    diag = '';
+    socket = null;
+    deadCb;
+    pending = [];
+    opened = false;
+    constructor(url, headers = {}, wsCtor = undefined) {
+        this.url = url;
+        this.headers = headers;
+        this.wsCtor = wsCtor;
+    }
+    open(onData) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let socket;
+            try {
+                socket = new (this.wsCtor ?? loadWs())(this.url, { headers: this.headers });
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            this.socket = socket;
+            // crash-proof by construction (mesh-gateway fix-round-1 lesson): 'error'
+            // ALWAYS has a listener; 'close' is guaranteed to follow and the dead
+            // path owns the teardown.
+            socket.on('error', (err) => { this.diag = (this.diag + `\n[pty-ws: ${err instanceof Error ? err.message : String(err)}]`).slice(-2_000); });
+            socket.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.opened = true;
+                for (const chunk of this.pending.splice(0))
+                    socket.send(chunk);
+                resolve();
+            });
+            socket.on('message', (data) => {
+                const text = typeof data === 'string'
+                    ? data
+                    : Array.isArray(data)
+                        ? Buffer.concat(data).toString('utf8')
+                        : Buffer.from(data).toString('utf8');
+                onData(text);
+            });
+            socket.on('close', () => {
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`pty-ws: socket closed before opening${this.diag !== '' ? `; ${this.diag}` : ''}`));
+                    return;
+                }
+                this.opened = false;
+                this.deadCb?.();
+            });
+        });
+    }
+    write(s) {
+        if (this.socket === null)
+            return;
+        if (!this.opened) {
+            this.pending.push(s);
+            return;
+        }
+        try {
+            this.socket.send(s);
+        }
+        catch { /* dead: the close path settles the session */ }
+    }
+    close() {
+        try {
+            this.socket?.close();
+        }
+        catch { /* already closing */ }
+    }
+    kill() {
+        try {
+            this.socket?.terminate();
+        }
+        catch { /* already gone */ }
+    }
+    onDead(callback) { this.deadCb = callback; }
+}

package/superd-hub/dist/exec-pty-framing.d.ts

@@ -0,0 +1,32 @@
+/** 收帧帧体：退出码 + 只读回传的 cwd（Non-Goal ②：报告不重建）。 */
+export interface PtyFrame {
+    exit: number;
+    cwd: string | null;
+}
+/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
+export declare function genNonce(bytes?: number): string;
+/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
+export declare function wrapPtyCommand(cmd: string, nonce: string): string;
+/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
+export declare function buildInitCommand(nonce: string): string;
+export declare function stripAnsi(s: string): string;
+export declare function normalizePtyText(s: string): string;
+export declare function tailWindow(text: string, cap: number): {
+    text: string;
+    truncated?: number;
+};
+export interface FrameParserEvents {
+    /** 输出文本：feed 路径经 normalize（剥 ANSI/规整换行）；flush 路径为**裸放出**（残余字节原样，勿假设已剥洗）。 */
+    onOutput?(text: string): void;
+    onFrame(frame: PtyFrame): void;
+}
+export interface NonceFrameParser {
+    feed(chunk: string): void;
+    flush(): void;
+}
+/**
+ * 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
+ * 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
+ * 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
+ */
+export declare function createNonceFrameParser(nonce: string, events: FrameParserEvents): NonceFrameParser;

package/superd-hub/dist/exec-pty-framing.js

@@ -0,0 +1,81 @@
+// PTY nonce framing — PORTED VERBATIM from better-dsh src/remote/nonce-framing.ts
+// (spec §8.2 / D12 "原样照抄"; only the import specifiers were adapted to this
+// package's ESM convention). Command wrap = brace compound + OSC-133;D nonce
+// tail carrying exit + cwd; parser holds back possible marker prefixes and
+// flushes leftovers raw.
+import { randomBytes } from 'node:crypto';
+/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
+export function genNonce(bytes = 8) {
+    return randomBytes(bytes).toString('hex');
+}
+/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
+export function wrapPtyCommand(cmd, nonce) {
+    return `{\n${cmd}\n} ; printf '\\033]133;D;${nonce};%s;%s\\007' "$?" "$PWD"\n`;
+}
+/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
+export function buildInitCommand(nonce) {
+    return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
+}
+const ANSI_RE = /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)?|\[[0-9;?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+export function stripAnsi(s) {
+    return s.replace(ANSI_RE, '');
+}
+export function normalizePtyText(s) {
+    return stripAnsi(s).replace(/\r\n/g, '\n').replace(/\r/g, '');
+}
+export function tailWindow(text, cap) {
+    if (text.length <= cap)
+        return { text };
+    return { text: `[truncated: showing last ${cap} of ${text.length} chars]\n${text.slice(text.length - cap)}`, truncated: text.length };
+}
+const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/; // cwd 是尾字段：合法路径可含 `;`，只有 BEL/ESC 终止它
+/**
+ * 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
+ * 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
+ * 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
+ */
+export function createNonceFrameParser(nonce, events) {
+    const prefix = `\x1b]133;D;${nonce};`;
+    let buf = '';
+    let done = false;
+    const emit = (raw) => {
+        const text = normalizePtyText(raw);
+        if (text.length > 0)
+            events.onOutput?.(text);
+    };
+    const holdback = () => {
+        const max = Math.min(buf.length, prefix.length - 1);
+        for (let k = max; k > 0; k--)
+            if (buf.endsWith(prefix.slice(0, k)))
+                return k;
+        return 0;
+    };
+    const consume = () => {
+        if (done)
+            return;
+        const i = buf.indexOf(prefix);
+        if (i < 0) {
+            const keep = holdback();
+            emit(buf.slice(0, buf.length - keep));
+            buf = buf.slice(buf.length - keep);
+            return;
+        }
+        emit(buf.slice(0, i));
+        const rest = buf.slice(i + prefix.length);
+        const m = FRAME_BODY_RE.exec(rest);
+        if (m === null) {
+            buf = buf.slice(i);
+            return;
+        } // 帧体未到齐，整段扣留
+        events.onFrame({ exit: Number(m[1]), cwd: m[2].length > 0 ? m[2] : null });
+        done = true; // 帧后字节一律丢弃（下一轮是新解析器）
+        buf = '';
+    };
+    return {
+        feed(chunk) { buf += chunk; consume(); },
+        // 流结束 = 裸放出扣留的残余（含未完成的 marker 前缀）：不经过 ANSI 剥洗——
+        // stripAnsi 会把未闭合 OSC 整段吃掉，扣留字节就此蒸发，违背 flush 语义。
+        flush() { if (buf.length > 0)
+            events.onOutput?.(buf); buf = ''; },
+    };
+}

package/superd-hub/dist/exec-pty-rpc.d.ts

@@ -0,0 +1,21 @@
+import type { A2aLogFn } from './a2a-log.js';
+/** The exact upgrade path this executor claims. */
+export declare const PTY_EXEC_PATH = "/api/superd/exec/pty";
+export interface PtyExecutorOptions {
+    /** The ctx0 auth gate (connection.authorizeIndex) — cookie auth comes first. */
+    authorize(req: unknown, res: unknown): boolean;
+    /** The ctx0 browser-trust fence (connection.requestRejection): Host/Origin policy. */
+    requestRejection?(req: unknown): number | undefined;
+    log?: A2aLogFn;
+}
+/**
+ * Register the PTY executor's upgrade route on the REAL webserver face
+ * (ctx0 only — gateway.ts's `webServer` inject scope, the /hub family's
+ * sibling). @returns the dispose fn.
+ */
+export declare function registerPtyExecutor(real: {
+    registerUpgrade(route: {
+        path: string;
+        handler: (req: unknown, socket: unknown, head: Buffer) => void;
+    }): unknown;
+}, opts: PtyExecutorOptions): Promise<() => void>;

package/superd-hub/dist/exec-pty-rpc.js

@@ -0,0 +1,128 @@
+// The remote PTY executor — the DUMB side of spec §8.2 (~a hundred lines by
+// design): one accepted WebSocket = one `script -qfec bash /dev/null` (host
+// PTY, no node-pty) with a bidirectional byte pump. All session intelligence
+// (nonce init/framing, two-stage interrupt, idle TTL) lives on the INITIATOR
+// side (exec-pty-session.ts over exec-pty-channel.ts) — the executor never
+// parses the stream. Protocol: text frames carry stdin/stdout bytes; the
+// child's exit is announced as one JSON control frame `{"op":"exit","code":N}`
+// before the socket closes; WS close (any reason) group-kills the child.
+//
+// Auth/trust: the same gate as the /hub family — connection.authorizeIndex
+// (cookie) FIRST, then the browser-trust fence (requestRejection) — an
+// upgrade is never weaker than its sibling HTTP routes (hub-route precedent).
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+/** The exact upgrade path this executor claims. */
+export const PTY_EXEC_PATH = '/api/superd/exec/pty';
+const WS_MODULE = 'ws';
+async function loadWsServer() {
+    const require = createRequire(import.meta.url);
+    const mod = require(WS_MODULE);
+    const boxed = mod;
+    return typeof mod.WebSocketServer === 'function' ? mod : boxed.default;
+}
+const REASON_PHRASE = { 401: 'Unauthorized', 403: 'Forbidden', 404: 'Not Found' };
+function rejectUpgrade(socket, status, body) {
+    const writable = socket;
+    writable.write?.(`HTTP/1.1 ${status} ${REASON_PHRASE[status] ?? 'Rejected'}\r\n`
+        + 'Connection: close\r\n'
+        + `Content-Type: application/json\r\n`
+        + `Content-Length: ${String(Buffer.byteLength(body, 'utf8'))}\r\n\r\n`
+        + body);
+    writable.destroy?.();
+}
+/** One connection = one dumb PTY pump. */
+function runPump(client, log) {
+    let child = null;
+    let closed = false;
+    const killTree = () => {
+        const pid = child?.pid;
+        child = null;
+        if (pid === undefined)
+            return;
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+        setTimeout(() => { try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch { /* already gone */ } }, 2_000).unref();
+    };
+    try {
+        child = spawn('script', ['-qfec', 'bash', '/dev/null'], { stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+    }
+    catch (err) {
+        log?.('warn', 'exec.pty.spawn-failed', { error: err instanceof Error ? err.message : String(err) });
+        try {
+            client.send(JSON.stringify({ op: 'spawn-error', error: 'script spawn failed' }));
+            client.close();
+        }
+        catch { /* closing */ }
+        return;
+    }
+    const started = Date.now();
+    log?.('info', 'exec.pty.start', { pid: child.pid ?? 'none' });
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (d) => { if (!closed) {
+        try {
+            client.send(d);
+        }
+        catch { /* closing */ }
+    } });
+    child.stderr?.setEncoding('utf8');
+    child.once('close', (code) => {
+        if (closed)
+            return;
+        closed = true;
+        log?.('info', 'exec.pty.exit', { code: code ?? 'none', durationMs: Date.now() - started });
+        try {
+            client.send(JSON.stringify({ op: 'exit', code }));
+            client.close();
+        }
+        catch { /* already closing */ }
+        killTree();
+    });
+    client.on('message', (data) => {
+        const text = typeof data === 'string' ? data : Buffer.from(data).toString('utf8');
+        if (child?.stdin?.writable === true) {
+            try {
+                child.stdin.write(text);
+            }
+            catch { /* dead */ }
+        }
+    });
+    const shutdown = () => { closed = true; killTree(); };
+    client.on('close', shutdown);
+    client.on('error', shutdown);
+}
+/**
+ * Register the PTY executor's upgrade route on the REAL webserver face
+ * (ctx0 only — gateway.ts's `webServer` inject scope, the /hub family's
+ * sibling). @returns the dispose fn.
+ */
+export async function registerPtyExecutor(real, opts) {
+    const ws = await loadWsServer();
+    const server = new ws.WebSocketServer({ noServer: true });
+    const handler = (req, socket, head) => {
+        // auth first, then trust fence — identical ordering to the /hub family
+        let status = 401;
+        let body = '';
+        const admitted = opts.authorize(req, {
+            writeHead: (answered) => { status = answered; },
+            end: (chunk) => { if (chunk !== undefined && chunk !== null)
+                body = String(chunk); },
+        });
+        if (!admitted) {
+            rejectUpgrade(socket, status, body !== '' ? body : JSON.stringify({ error: 'unauthorized' }));
+            return;
+        }
+        const rejection = opts.requestRejection?.(req);
+        if (rejection !== undefined) {
+            rejectUpgrade(socket, rejection, JSON.stringify({ error: rejection === 401 ? 'unauthorized' : 'forbidden' }));
+            return;
+        }
+        server.handleUpgrade(req, socket, head, (client) => runPump(client, opts.log));
+    };
+    return real.registerUpgrade({ path: PTY_EXEC_PATH, handler });
+}

package/superd-hub/dist/exec-pty-session.d.ts

@@ -0,0 +1,76 @@
+import type { PtyChannel } from './exec-pty-channel.js';
+/** spec §五.2 逐字。 */
+export declare const RECONNECT_NOTICE = "[remote: session reconnected to fresh shell; cwd reset to default]";
+export interface PtySessionOptions {
+    key: string;
+    channel: PtyChannel;
+    idleTtlSec: number;
+    initTimeoutSec?: number;
+    /** 池回调：会话彻底出池（dispose）时触发；进程意外死亡不出池（Ruling 7）。 */
+    onDead?: () => void;
+}
+export interface PtyDispatchOptions {
+    stdin?: string;
+    timeoutSec?: number;
+}
+export interface PtyDispatchResult {
+    output: string;
+    exit: number | null;
+    cwd: string | null;
+    timedOut: boolean;
+    reconnected: boolean;
+    durationMs: number;
+}
+export type PtyState = 'cold' | 'starting' | 'ready' | 'dead' | 'disposed';
+/** 会话运行时快照（status 面消费，Ruling 16 词汇源）。 */
+export interface SessionSnapshot {
+    state: PtyState;
+    busy: boolean;
+    idleMs: number | null;
+}
+export declare class PtySession {
+    private readonly opts;
+    private state;
+    private startPromise;
+    private queue;
+    private idleTimer;
+    private onChunk;
+    private deathWaiters;
+    private inFlight;
+    private lastSettleAt;
+    constructor(opts: PtySessionOptions);
+    get sessionState(): PtyState;
+    /** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）。 */
+    get snapshot(): SessionSnapshot;
+    /** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。 */
+    dispatch(cmd: string, dOpts?: PtyDispatchOptions): Promise<PtyDispatchResult>;
+    /** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
+    dispose(): Promise<void>;
+    private write;
+    private start;
+    private doStart;
+    private diag;
+    private markDead;
+    private resetIdleTimer;
+    private clearIdleTimer;
+}
+export interface PtyPoolDefaults {
+    idleTtlSec: number;
+    initTimeoutSec?: number;
+}
+/** 会话池：键 → 会话。意外死亡的会话留在池内（下次 dispatch 带 reconnect 提示）。 */
+export declare class PtyPool {
+    private readonly defaults;
+    private readonly sessions;
+    constructor(defaults: PtyPoolDefaults);
+    get size(): number;
+    /** status 面：键上的会话快照（无会话 = undefined → "none — dials on first exec"）。 */
+    inspect(key: string): SessionSnapshot | undefined;
+    /** roster 面：池内全部会话。 */
+    list(): Array<{
+        key: string;
+        snapshot: SessionSnapshot;
+    }>;
+    getOrCreate(key: string, channelOf: () => PtyChannel): PtySession;
+    disposeAll(): Promise<void>;
+}