dsh-bash-terminal-ts 0.2.5

package/lib/terminal.d.ts

@@ -0,0 +1,87 @@
+import type { BashTerminalContext, ResolvedPaths, TerminalHandle } from "./dsh-types.js";
+declare const TERMINAL_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGKILL", "SIGTSTP", "SIGHUP"];
+export type TerminalSignal = (typeof TERMINAL_SIGNALS)[number];
+interface TerminalBufferRead {
+    delta: string;
+    nextOffset: number;
+}
+interface TerminalBuffer {
+    append(chunk: string): void;
+    readFrom(offset: number): TerminalBufferRead;
+    snapshot(): string;
+}
+/** Interactive-shell argv (no -c: the terminal itself is the session). */
+export declare function terminalArgv(shell: string, paths: ResolvedPaths, distro?: string): Array<string | undefined>;
+interface TerminalSession {
+    id: string;
+    handle: TerminalHandle;
+    buffer: TerminalBuffer;
+    shell: string;
+    distro?: string;
+    closed: boolean;
+}
+export interface TerminalOpenOptions {
+    argv: string[];
+    shell: string;
+    cwd: string;
+    env: Record<string, string | undefined>;
+    rows: number;
+    cols: number;
+    distro?: string;
+    initial?: string;
+}
+export interface TerminalRegistry {
+    open(options: TerminalOpenOptions): Promise<TerminalSession>;
+    get(id: string): TerminalSession;
+    send(id: string, input: string): Promise<TerminalBufferRead>;
+    read(id: string): TerminalBufferRead;
+    signal(id: string, sig: string): Promise<TerminalBufferRead>;
+    close(id: string): Promise<boolean>;
+}
+/**
+ * Terminal-session registry owned by the plugin fiber: opens PTYs through
+ * the official seam, forwards output into a capped buffer, and tears every
+ * session down on plugin disposal.
+ */
+export declare function createTerminalRegistry(ctx: BashTerminalContext): TerminalRegistry;
+/** The terminal tool's arguments after runtime validation (discriminated by action). */
+export type ValidatedTerminalArgs = {
+    action: "open";
+    sessionId?: string;
+    command?: string;
+    distro?: string;
+    workdir?: string;
+} | {
+    action: "send";
+    sessionId: string;
+    input: string;
+} | {
+    action: "read";
+    sessionId: string;
+} | {
+    action: "signal";
+    sessionId: string;
+    signal: TerminalSignal;
+} | {
+    action: "close";
+    sessionId: string;
+};
+export declare function validateArgs(args: Record<string, unknown>): asserts args is ValidatedTerminalArgs;
+export interface TerminalOpenResult {
+    kind: "open";
+    sessionId: string;
+    pid: number;
+    shell: string;
+    output: string;
+}
+export interface TerminalSessionResult {
+    kind: "session";
+    output: string;
+}
+export interface TerminalClosedResult {
+    kind: "closed";
+    sessionId: string;
+}
+export type TerminalToolResult = TerminalOpenResult | TerminalSessionResult | TerminalClosedResult;
+export declare function terminalTool(ctx: BashTerminalContext, registry: TerminalRegistry, paths: ResolvedPaths, defaultShell: () => string): import("./dsh-types.js").ToolDefinition;
+export {};

package/lib/terminal.js

@@ -0,0 +1,273 @@
+// dsh-bash-terminal-ts: interactive terminal tool over the official PTY seam.
+// ctx.subprocess.spawnTerminal (node-pty under the hood) allocates a real
+// terminal; this module owns model-facing sessions: open / send / read /
+// signal (Ctrl+C etc.) / close. The backend follows the user's default
+// terminal setting, exactly like the shell tool.
+import { randomUUID } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { TOOL_ABORTED, defineTool, HarnessError } from "./dsh.js";
+import { buildEnv } from "./index.js";
+const MAX_BUFFER_BYTES = 1024 * 1024;
+const READ_SETTLE_MS = 800;
+const DEFAULT_ROWS = 30;
+const DEFAULT_COLS = 110;
+const TERMINAL_SIGNALS = ["SIGINT", "SIGTERM", "SIGKILL", "SIGTSTP", "SIGHUP"];
+function delay(ms) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+/** Interactive-shell argv (no -c: the terminal itself is the session). */
+export function terminalArgv(shell, paths, distro) {
+    switch (shell) {
+        case "powershell": return [paths.pwsh, "-NoLogo", "-NoProfile"];
+        case "gitbash": return [paths.gitbash, "-i"];
+        case "msys2": return [paths.msys2, "-l"];
+        case "wsl": {
+            const distroArg = distro !== undefined && distro.trim().length > 0 ? ["-d", distro.trim()] : [];
+            return [paths.wsl, ...distroArg, "-e", "bash", "-i"];
+        }
+        default: throw new Error("invalid shell: " + JSON.stringify(shell));
+    }
+}
+/** In-memory output ring for one session (drop-oldest at the cap). */
+function createBuffer() {
+    let text = "";
+    return {
+        append(chunk) {
+            text += chunk;
+            if (text.length > MAX_BUFFER_BYTES)
+                text = text.slice(text.length - MAX_BUFFER_BYTES);
+        },
+        readFrom(offset) {
+            const delta = offset >= text.length ? "" : text.slice(offset);
+            return { delta, nextOffset: text.length };
+        },
+        snapshot: () => text
+    };
+}
+/**
+ * Terminal-session registry owned by the plugin fiber: opens PTYs through
+ * the official seam, forwards output into a capped buffer, and tears every
+ * session down on plugin disposal.
+ */
+export function createTerminalRegistry(ctx) {
+    const sessions = new Map();
+    ctx.effect(() => () => {
+        for (const session of sessions.values()) {
+            void session.handle.terminate().catch(() => { });
+        }
+        sessions.clear();
+    }, "bash-terminal: terminal sessions teardown");
+    async function open(options) {
+        const { argv, shell, cwd, env, rows, cols, distro, initial } = options;
+        const spawnTerminal = ctx.subprocess?.spawnTerminal;
+        if (spawnTerminal === undefined) {
+            throw new Error("terminal: ctx.subprocess.spawnTerminal seam unavailable");
+        }
+        const handle = await spawnTerminal({
+            argv,
+            cwd,
+            env,
+            rows,
+            cols,
+            graceMs: 3000
+        });
+        const buffer = createBuffer();
+        handle.output.on("data", (chunk) => buffer.append(typeof chunk === "string" ? chunk : String(chunk)));
+        const session = {
+            id: randomUUID(),
+            handle,
+            buffer,
+            shell,
+            distro,
+            closed: false
+        };
+        sessions.set(session.id, session);
+        if (initial !== undefined && initial.length > 0) {
+            await handle.write(initial);
+            await delay(READ_SETTLE_MS);
+        }
+        return session;
+    }
+    function get(id) {
+        const session = sessions.get(id);
+        if (session === undefined)
+            throw new Error("terminal session not found: " + JSON.stringify(id));
+        if (session.closed)
+            throw new Error("terminal session is closed: " + JSON.stringify(id));
+        return session;
+    }
+    async function send(id, input) {
+        const session = get(id);
+        await session.handle.write(input);
+        await delay(READ_SETTLE_MS);
+        return read(id);
+    }
+    function read(id) {
+        const session = get(id);
+        const { delta, nextOffset } = session.buffer.readFrom(0);
+        return { delta, nextOffset };
+    }
+    async function signal(id, sig) {
+        const session = get(id);
+        if (!TERMINAL_SIGNALS.includes(sig)) {
+            throw new Error("invalid terminal signal: " + JSON.stringify(sig));
+        }
+        await session.handle.signalForeground(sig);
+        await delay(READ_SETTLE_MS);
+        return read(id);
+    }
+    async function close(id) {
+        const session = get(id);
+        session.closed = true;
+        sessions.delete(id);
+        await session.handle.terminate();
+        return true;
+    }
+    return { open, get, send, read, signal, close };
+}
+export function validateArgs(args) {
+    const action = args.action;
+    if (typeof action !== "string" || ["open", "send", "read", "signal", "close"].indexOf(action) === -1) {
+        throw new Error("invalid action: expected open, send, read, signal, or close");
+    }
+    if ((action === "send" || action === "read" || action === "signal" || action === "close") && (typeof args.sessionId !== "string" || args.sessionId.length === 0)) {
+        throw new Error("invalid sessionId: required for " + action);
+    }
+    if (action === "send" && (typeof args.input !== "string" || args.input.length === 0)) {
+        throw new Error("invalid input: expected a non-empty string for send");
+    }
+    if (action === "signal" && (typeof args.signal !== "string" || TERMINAL_SIGNALS.indexOf(args.signal) === -1)) {
+        throw new Error("invalid signal: expected one of " + TERMINAL_SIGNALS.join(", "));
+    }
+}
+export function terminalTool(ctx, registry, paths, defaultShell) {
+    return defineTool({
+        name: "terminal",
+        description: "Interactive terminal session over the user's default terminal (Settings -> General -> Default terminal: powershell / gitbash / msys2 / wsl). A real PTY hosts a persistent shell: open a session, send input and read output across turns, deliver signals (Ctrl+C = SIGINT) to the foreground process, and close when done. Backend and env follow the shell tool exactly; the session survives between calls until closed. Use this for interactive programs (REPLs, ssh, databases, TUI tools) or when you need shell state (cwd, variables, aliases) to persist across calls.",
+        parameters: {
+            action: {
+                type: "string",
+                enum: ["open", "send", "read", "signal", "close"],
+                required: true,
+                description: "open: create a session and return its id. send: write input and read new output. read: read new output without writing. signal: send a signal to the foreground process (SIGINT for Ctrl+C). close: terminate the session."
+            },
+            sessionId: {
+                type: "string",
+                description: "Session id returned by open; required for send/read/signal/close."
+            },
+            command: {
+                type: "string",
+                description: "With action open: optional command to run immediately in the fresh shell (Enter appended). Default starts an interactive shell."
+            },
+            distro: {
+                type: "string",
+                description: "WSL distribution (only when the configured default terminal is wsl)."
+            },
+            input: {
+                type: "string",
+                description: "With action send: the input to write (no implicit newline; append \\n or \\r for Enter)."
+            },
+            signal: {
+                type: "string",
+                enum: TERMINAL_SIGNALS,
+                description: "With action signal: signal to the foreground process group (SIGINT = Ctrl+C, SIGKILL, SIGTERM, SIGTSTP, SIGHUP)."
+            },
+            workdir: {
+                type: "string",
+                description: "Working directory for the session (open only). Defaults to the session workspace."
+            }
+        },
+        output: {
+            schema: {
+                oneOf: [
+                    {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: "string", required: true, const: "open" },
+                            sessionId: { type: "string", required: true },
+                            pid: { type: "integer", required: true },
+                            shell: { type: "string", required: true },
+                            output: { type: "string" }
+                        }
+                    },
+                    {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: "string", required: true, const: "session" },
+                            output: { type: "string", required: true }
+                        }
+                    },
+                    {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: "string", required: true, const: "closed" },
+                            sessionId: { type: "string", required: true }
+                        }
+                    }
+                ]
+            },
+            render: (_args, value) => [{
+                    type: "text",
+                    text: value.kind === "open"
+                        ? "terminal session " + value.sessionId + " (pid " + value.pid + ", " + value.shell + ")" + (value.output ? "\n" + value.output : "")
+                        : value.kind === "closed"
+                            ? "terminal session " + value.sessionId + " closed"
+                            : value.output
+                }]
+        },
+        async execute(args, exec) {
+            validateArgs(args);
+            if (exec.signal.aborted) {
+                const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+                error.name = "AbortError";
+                throw error;
+            }
+            const headerCwd = exec.agent?.session.header.cwd;
+            switch (args.action) {
+                case "open": {
+                    const shell = defaultShell();
+                    const argv0 = terminalArgv(shell, paths, args.distro);
+                    if (argv0[0] === undefined)
+                        throw new Error("terminal: " + shell + " backend unavailable - executable not found");
+                    // Only element 0 (the resolved executable) can be undefined; guarded above.
+                    const argv = argv0;
+                    const cwd = args.workdir !== undefined ? (headerCwd !== undefined && !isAbsolute(args.workdir) ? resolve(headerCwd, args.workdir) : args.workdir) : (headerCwd ?? process.cwd());
+                    // buildEnv, not an inline duplicate: the msys2 backend needs its
+                    // MSYSTEM=MINGW64 injection here too, or the login shell sources
+                    // /etc/profile with the default MSYS environment and /mingw64/bin
+                    // (gcc, make) never joins PATH. DSH's spawnTerminal replaces the child
+                    // environment with exactly this object (childEnv(spec.env)), so the
+                    // inherited WSLENV is passed through explicitly for the WSL allow-list;
+                    // for every other backend buildEnv ignores the third argument.
+                    const env = buildEnv(shell, ctx.shellEnv.collect(exec), process.env.WSLENV);
+                    const session = await registry.open({ argv, shell, cwd, env, rows: DEFAULT_ROWS, cols: DEFAULT_COLS, distro: args.distro, initial: args.command !== undefined ? args.command + "\r" : undefined });
+                    return { kind: "open", sessionId: session.id, pid: session.handle.pid, shell, output: session.buffer.snapshot() };
+                }
+                case "send": {
+                    const { delta } = await registry.send(args.sessionId, args.input);
+                    return { kind: "session", output: delta };
+                }
+                case "read": {
+                    const { delta } = registry.read(args.sessionId);
+                    return { kind: "session", output: delta };
+                }
+                case "signal": {
+                    const { delta } = await registry.signal(args.sessionId, args.signal);
+                    return { kind: "session", output: delta };
+                }
+                case "close": {
+                    await registry.close(args.sessionId);
+                    return { kind: "closed", sessionId: args.sessionId };
+                }
+            }
+        },
+        presentCall: (args) => ({
+            card: "terminal",
+            title: "terminal " + String(args.action) + (args.sessionId !== undefined ? " " + String(args.sessionId) : ""),
+            ...(args.input !== undefined ? { description: args.input } : {})
+        })
+    });
+}

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "dsh-bash-terminal-ts",
+  "version": "0.2.5",
+  "description": "DSH plugin: one shell tool that runs commands through PowerShell, Git Bash, MSYS2, or WSL on Windows, with a user-chosen default terminal in the Web UI settings. TypeScript rewrite of MAXeaglet/dsh-bash-terminal with working MSYS2/MINGW64 support.",
+  "author": "drscrewdriver",
+  "contributors": [
+    "MAXeaglet (original dsh-bash-terminal)"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drscrewdriver/dsh-bash-terminal-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/drscrewdriver/dsh-bash-terminal-ts/issues"
+  },
+  "homepage": "https://github.com/drscrewdriver/dsh-bash-terminal-ts#readme",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "terminal",
+    "shell",
+    "powershell",
+    "git-bash",
+    "msys2",
+    "mingw64",
+    "wsl",
+    "windows",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.1.2-rc.1 <0.2.0-0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./dist/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "dist",
+    "src",
+    "scripts",
+    "tsconfig.json",
+    "tsconfig.client.json",
+    "tsconfig.test.json",
+    "README.md",
+    "README.en.md",
+    "README.ja.md",
+    "README.ko.md",
+    "LICENSE",
+    "cordis.patch.yml",
+    "dsh.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs && tsc -p tsconfig.test.json",
+    "build:client": "node scripts/build-client.mjs",
+    "test": "node test-dist/unit.js && node test-dist/apply.js && node test-dist/client.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-store",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.2-rc.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": { "optional": true },
+    "@deepseek-ai/dsh-tools": { "optional": true },
+    "@deepseek-ai/dsh-settings": { "optional": true },
+    "@deepseek-ai/dsh-llm": { "optional": true },
+    "@deepseek-ai/dsh-shell": { "optional": true },
+    "@deepseek-ai/dsh-timeout": { "optional": true },
+    "@deepseek-ai/dsh-client-store": { "optional": true },
+    "@deepseek-ai/dsh-client-locale": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-settings": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-slots": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-primitives": { "optional": true },
+    "@deepseek-ai/dsh-sandbox": { "optional": true },
+    "react": { "optional": true }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.0"
+  }
+}

package/scripts/build-client.mjs

@@ -0,0 +1,46 @@
+// Build the browser client bundle for dsh-bash-terminal-ts.
+// Output: dist/client.js — a __ModuleLoader__.load({ id, factory }) wrapper
+// around the esbuild CJS bundle; shared deps (react, @deepseek-ai/*) resolve
+// through the loader's require.
+
+import { build } from "esbuild";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+mkdirSync(join(root, "dist"), { recursive: true });
+
+await build({
+  entryPoints: [join(root, "src", "client.tsx")],
+  bundle: true,
+  format: "cjs",
+  platform: "browser",
+  outfile: join(root, "dist", "client.core.js"),
+  external: ["react", "react/jsx-runtime", "react-dom", "@deepseek-ai/*"],
+  jsx: "automatic",
+  // Pin the TS options instead of letting esbuild discover a tsconfig by walking
+  // up from the entry point. The repo root has a tsconfig.json, so in-repo builds
+  // silently inherited it and emitted a leading "use strict"; while a byte-for-byte
+  // identical build from a worktree outside the repo (no tsconfig above it) did not
+  // — same source, two different committed artifacts. These values are what the
+  // root tsconfig actually supplied. The one observable delta is that stray
+  // "use strict"; (inert: the core is wrapped in a function expression by the
+  // loader shim below, so it was never a directive prologue), now gone everywhere.
+  tsconfigRaw: { compilerOptions: { target: "ES2022", useDefineForClassFields: true } },
+  logLevel: "warning"
+});
+
+const core = readFileSync(join(root, "dist", "client.core.js"), "utf8");
+const wrapper = `window.__ModuleLoader__.load({
+	id: "dsh-bash-terminal-ts",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+${core}
+		return module.exports;
+	}
+});
+`;
+writeFileSync(join(root, "dist", "client.js"), wrapper);
+console.log("built dist/client.js (" + wrapper.length + " bytes)");