dsh-bash-terminal-ts 0.4.1 → 0.4.2

package/lib/terminal.js

@@ -3,271 +3,425 @@
 // 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.
+//
+// Windows note: the official seam's process inspector is POSIX-only
+// (createProcessInspector throws on win32), so on Windows the PTY is
+// allocated directly through node-pty. Session readiness here is
+// output-quiet based (waitSettled), which needs no process inspection.
+
+import { defineTool, TOOL_ABORTED } from "@deepseek-ai/dsh-tools";
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+// 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. The shell tool shares this exact helper.
+import { buildEnv } from "./index.js";
 import { randomUUID } from "node:crypto";
 import { isAbsolute, resolve } from "node:path";
-import { TOOL_ABORTED, defineTool, HarnessError } from "./dsh.js";
-import { buildEnv } from "./index.js";
+import { PassThrough } from "node:stream";
+
 const MAX_BUFFER_BYTES = 1024 * 1024;
-const READ_SETTLE_MS = 800;
 const DEFAULT_ROWS = 30;
 const DEFAULT_COLS = 110;
+const DEFAULT_IDLE_MS = 10 * 60 * 1000;
+const MAX_SESSIONS = 8;
 const TERMINAL_SIGNALS = ["SIGINT", "SIGTERM", "SIGKILL", "SIGTSTP", "SIGHUP"];
+
 function delay(ms) {
-    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/**
+ * Wait until the terminal output goes quiet (no new bytes for quietMs) or the
+ * cap elapses. Reads after interactive input then return the complete reply
+ * instead of a fixed-delay slice.
+ */
+async function waitSettled(buffer, quietMs = 300, timeoutMs = 5000) {
+  const start = Date.now();
+  let last = buffer.lastAppendAt();
+  while (Date.now() - start < timeoutMs) {
+    await delay(80);
+    const now = buffer.lastAppendAt();
+    if (now > last) {
+      last = now;
+      continue;
+    }
+    if (Date.now() - last >= quietMs) return;
+  }
+}
+
 /** 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));
+  switch (shell) {
+    case "powershell": return [paths.pwsh, "-NoLogo", "-NoProfile"];
+    case "gitbash": return [paths.gitbash, "-i"];
+    case "msys2": return [paths.msys2, "-l"];
+    case "wsl": {
+      // Verified under ConPTY: 'wsl -e bash -i' on the DEFAULT distro fails with
+      // a WSL service RPC error (0x8007072c), while 'wsl -- bash -i' works;
+      // with an explicit -d distro, '-e bash -i' also works.
+      if (distro !== undefined && distro.trim().length > 0) {
+        return [paths.wsl, "-d", distro.trim(), "-e", "bash", "-i"];
+      }
+      return [paths.wsl, "--", "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
-    };
+  let text = "";
+  let truncated = false;
+  let lastAppendAt = Date.now();
+  return {
+    append(chunk) {
+      text += chunk;
+      lastAppendAt = Date.now();
+      if (text.length > MAX_BUFFER_BYTES) {
+        text = text.slice(text.length - MAX_BUFFER_BYTES);
+        truncated = true;
+      }
+    },
+    readFrom(offset) {
+      const delta = offset >= text.length ? "" : text.slice(offset);
+      return { delta, nextOffset: text.length, truncated };
+    },
+    snapshot: () => text,
+    wasTruncated: () => truncated,
+    lastAppendAt: () => lastAppendAt
+  };
+}
+
+/**
+ * Direct node-pty handle with the same surface the official seam returns:
+ * output (stream), pid, done, write / signalForeground / terminate. Used on
+ * win32 where the official spawnTerminal's process inspector is unsupported.
+ */
+async function spawnPtyHandle({ argv, cwd, env, rows, cols }) {
+  const mod = await import("node-pty");
+  const nodePty = mod.default ?? mod;
+  const term = nodePty.spawn(argv[0], argv.slice(1), {
+    name: "dumb",
+    cols,
+    rows,
+    cwd,
+    env: { ...env, TERM: "dumb", NO_COLOR: "1" }
+  });
+  const output = new PassThrough();
+  term.onData((chunk) => output.write(Buffer.from(chunk, "utf8")));
+  const done = new Promise((resolve) => term.onExit(({ exitCode, signal }) => resolve({ exitCode, signal })));
+  return {
+    pid: term.pid,
+    output,
+    done,
+    write: (data) => term.write(data),
+    // node-pty accepts no named signals on Windows: Ctrl+C is the \x03 byte
+    // (ConPTY delivers it to the foreground process), other signals degrade
+    // to terminating the session.
+    signalForeground: (sig) => {
+      if (sig === "SIGINT") { term.write("\x03"); return; }
+      term.kill();
+    },
+    terminate: async () => { try { term.kill(); } catch {} }
+  };
 }
+
 /**
  * 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;
+  const sessions = new Map();
+  ctx.effect(() => () => {
+    for (const session of sessions.values()) {
+      void session.handle.terminate().catch(() => {});
     }
-    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);
+    sessions.clear();
+  }, "bash-terminal: terminal sessions teardown");
+
+  async function open({ argv, shell, cwd, env, rows, cols, distro, initial, idleMs }) {
+    if (sessions.size >= MAX_SESSIONS) {
+      throw new Error("terminal: too many open sessions (" + MAX_SESSIONS + "); close one before opening another");
     }
-    async function close(id) {
-        const session = get(id);
+    const handle = process.platform === "win32"
+      ? await spawnPtyHandle({ argv, cwd, env, rows, cols })
+      : await ctx.subprocess.spawnTerminal({ argv, cwd, env, rows, cols, graceMs: 3000 });
+    const buffer = createBuffer();
+    handle.output.on("data", (chunk) => buffer.append(typeof chunk === "string" ? chunk : chunk.toString("utf8")));
+    const session = {
+      id: randomUUID(),
+      handle,
+      buffer,
+      shell,
+      distro,
+      closed: false,
+      idleMs: idleMs ?? DEFAULT_IDLE_MS
+    };
+    // Idle guard: any read/send/signal touches the timer; expiry terminates the
+    // session so an abandoned PTY never leaks a process tree.
+    const touch = () => {
+      if (session.closed) return;
+      clearTimeout(session.idleTimer);
+      session.idleTimer = setTimeout(() => {
+        if (session.closed) return;
         session.closed = true;
-        sessions.delete(id);
-        await session.handle.terminate();
-        return true;
+        sessions.delete(session.id);
+        void session.handle.terminate().catch(() => {});
+      }, session.idleMs);
+    };
+    session.touch = touch;
+    touch();
+    sessions.set(session.id, session);
+    if (initial !== undefined && initial.length > 0) {
+      await handle.write(initial);
+      await waitSettled(buffer);
     }
-    return { open, get, send, read, signal, close };
+    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));
+    session.touch();
+    return session;
+  }
+
+  async function send(id, input) {
+    const session = get(id);
+    await session.handle.write(input);
+    await waitSettled(session.buffer);
+    return read(id);
+  }
+  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 waitSettled(session.buffer);
+    return read(id);
+  }
+
+  function read(id) {
+    const session = get(id);
+    const { delta, nextOffset, truncated } = session.buffer.readFrom(0);
+    return { delta, nextOffset, truncated };
+  }
+
+  async function close(id) {
+    const session = get(id);
+    session.closed = true;
+    clearTimeout(session.idleTimer);
+    sessions.delete(id);
+    await session.handle.terminate();
+    return true;
+  }
+
+  function list() {
+    return [...sessions.values()].map((session) => ({
+      sessionId: session.id,
+      shell: session.shell,
+      pid: session.handle.pid,
+      closed: session.closed
+    }));
+  }
+
+  return { open, get, send, read, signal, close, list };
 }
-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(", "));
-    }
+
+function validateArgs(args) {
+  if (typeof args.action !== "string" || ["open", "send", "read", "signal", "close", "list"].indexOf(args.action) === -1) {
+    throw new Error("invalid action: expected open, send, read, signal, close, or list");
+  }
+  if ((args.action === "send" || args.action === "read" || args.action === "signal" || args.action === "close") && (typeof args.sessionId !== "string" || args.sessionId.length === 0)) {
+    throw new Error("invalid sessionId: required for " + args.action);
+  }
+  if (args.action === "send" && (typeof args.input !== "string" || args.input.length === 0)) {
+    throw new Error("invalid input: expected a non-empty string for send");
+  }
+  if (args.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."
+  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 and is managed as a background job (job_kill / job_output work on it); idle sessions close automatically. 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", "list"],
+        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. list: list live sessions."
+      },
+      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."
+      },
+      idleMs: {
+        type: "number",
+        description: "Idle timeout in ms (open only): the session closes automatically after this long without send/read/signal. Default 600000 (10 min)."
+      }
+    },
+    output: {
+      schema: {
+        oneOf: [
+          {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              kind: { type: "string", required: true, const: "open" },
+              sessionId: { type: "string", required: true },
+              jobId: { type: "string" },
+              pid: { type: "integer", required: true },
+              shell: { type: "string", required: true },
+              output: { type: "string" }
             }
-        },
-        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;
+          },
+          {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              kind: { type: "string", required: true, const: "session" },
+              output: { type: "string", required: true },
+              truncated: { type: "boolean" }
             }
-            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 };
+          },
+          {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              kind: { type: "string", required: true, const: "closed" },
+              sessionId: { type: "string", required: true }
+            }
+          },
+          {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              kind: { type: "string", required: true, const: "list" },
+              sessions: {
+                type: "array",
+                items: {
+                  type: "object",
+                  additionalProperties: false,
+                  properties: {
+                    sessionId: { type: "string", required: true },
+                    shell: { type: "string", required: true },
+                    pid: { type: "integer", required: true },
+                    closed: { type: "boolean" }
+                  }
                 }
+              }
             }
-        },
-        presentCall: (args) => ({
-            card: "terminal",
-            title: "terminal " + String(args.action) + (args.sessionId !== undefined ? " " + String(args.sessionId) : ""),
-            ...(args.input !== undefined ? { description: args.input } : {})
-        })
-    });
+          }
+        ]
+      },
+      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.kind === "list"
+              ? (value.sessions.length === 0 ? "no open terminal sessions" : value.sessions.map((s) => s.sessionId + " (" + s.shell + ", pid " + s.pid + ")").join("\n"))
+              : value.truncated === true
+                ? (value.output.length === 0 ? "[terminal buffer overflowed; oldest output dropped]" : value.output + "\n[terminal buffer overflowed; oldest output dropped]")
+                : 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 argv = terminalArgv(shell, paths, args.distro);
+          if (argv[0] === undefined) throw new Error("terminal: " + shell + " backend unavailable - executable not found");
+          const cwd = args.workdir !== undefined ? (headerCwd !== undefined && !isAbsolute(args.workdir) ? resolve(headerCwd, args.workdir) : args.workdir) : (headerCwd ?? process.cwd());
+          const dshEnv = ctx.shellEnv.collect(exec);
+          // Shared helper, not an inline duplicate: it injects MSYSTEM=MINGW64
+          // for msys2 (without it the login shell sources /etc/profile with the
+          // default MSYS environment and /mingw64/bin never joins PATH) and
+          // layers the DSH_* keys onto the inherited WSLENV allow-list for wsl.
+          // A PTY session therefore gets exactly the environment a one-shot
+          // shell command gets - no second copy to drift. The inherited WSLENV
+          // is passed explicitly because DSH's spawnTerminal replaces the child
+          // env wholesale, so an ambient value would otherwise be lost here.
+          const env = buildEnv(shell, dshEnv, 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, idleMs: args.idleMs });
+          const jobs = ctx.get("jobs");
+          const jobId = jobs === undefined ? undefined : jobs.start({
+            kind: "terminal/session",
+            label: "terminal " + session.id.slice(0, 8) + " (" + shell + ")",
+            ...(exec.agent ? { owner: exec.agent } : {}),
+            run: () => ({
+              cancel: () => void session.handle.terminate().catch(() => {}),
+              done: session.handle.done,
+              readOutput: () => registry.read(session.id).delta
+            })
+          });
+          return { kind: "open", sessionId: session.id, ...(jobId !== undefined ? { jobId } : {}), pid: session.handle.pid, shell, output: session.buffer.snapshot() };
+        }
+        case "send": {
+          const { delta, truncated } = await registry.send(args.sessionId, args.input);
+          return { kind: "session", output: delta, ...(truncated ? { truncated } : {}) };
+        }
+        case "read": {
+          const { delta, truncated } = registry.read(args.sessionId);
+          return { kind: "session", output: delta, ...(truncated ? { truncated } : {}) };
+        }
+        case "signal": {
+          const { delta, truncated } = await registry.signal(args.sessionId, args.signal);
+          return { kind: "session", output: delta, ...(truncated ? { truncated } : {}) };
+        }
+        case "close": {
+          await registry.close(args.sessionId);
+          return { kind: "closed", sessionId: args.sessionId };
+        }
+        case "list": {
+          return { kind: "list", sessions: registry.list() };
+        }
+        default: throw new Error("unreachable terminal action");
+      }
+    },
+    presentCall: (args) => ({
+      card: "terminal",
+      title: "terminal " + args.action + (args.sessionId !== undefined ? " " + args.sessionId : ""),
+      ...(args.input !== undefined ? { description: args.input } : {})
+    })
+  });
 }
+
+function pathResolve(base, rel) {
+  const { resolve } = require("node:path");
+  return resolve(base, rel);
+}