@moxxy/plugin-terminal 0.27.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { buildTerminalSurface, buildTerminalTool, closeAllTerminals, } from './terminal.js';
+export { createTerminalProcess, type TerminalProcess } from './pty.js';
+export declare function buildTerminalPlugin(): import("@moxxy/sdk").Plugin;
+export declare const terminalPlugin: import("@moxxy/sdk").Plugin;
+export default terminalPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAEvE,wBAAgB,mBAAmB,gCAalC;AAED,eAAO,MAAM,cAAc,6BAAwB,CAAC;AAEpD,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+import { definePlugin } from '@moxxy/sdk';
+import { buildTerminalSurface, buildTerminalTool, closeAllTerminals } from './terminal.js';
+export { buildTerminalSurface, buildTerminalTool, closeAllTerminals, } from './terminal.js';
+export { createTerminalProcess } from './pty.js';
+export function buildTerminalPlugin() {
+    return definePlugin({
+        name: '@moxxy/plugin-terminal',
+        version: '0.0.0',
+        surfaces: [buildTerminalSurface()],
+        tools: [buildTerminalTool()],
+        hooks: {
+            onShutdown: () => {
+                // Kill the shared shell(s) with the session so no orphan PTY lingers.
+                closeAllTerminals();
+            },
+        },
+    });
+}
+export const terminalPlugin = buildTerminalPlugin();
+export default terminalPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAwB,MAAM,UAAU,CAAC;AAEvE,MAAM,UAAU,mBAAmB;IACjC,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,wBAAwB;QAC9B,OAAO,EAAE,OAAO;QAChB,QAAQ,EAAE,CAAC,oBAAoB,EAAE,CAAC;QAClC,KAAK,EAAE,CAAC,iBAAiB,EAAE,CAAC;QAC5B,KAAK,EAAE;YACL,UAAU,EAAE,GAAG,EAAE;gBACf,sEAAsE;gBACtE,iBAAiB,EAAE,CAAC;YACtB,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,mBAAmB,EAAE,CAAC;AAEpD,eAAe,cAAc,CAAC"}

package/dist/pty.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The shared terminal process behind the `terminal` surface + tool.
+ *
+ * Two backends, picked at open time:
+ *   1. **node-pty** (preferred) — a real PTY, so interactive programs (vim, top,
+ *      a REPL) and prompts render correctly. Lazy-loaded; absent in a default
+ *      install (it is an OPTIONAL peer dep — native, so CI never has to build
+ *      it).
+ *   2. **piped child shell** (fallback, dependency-free) — spawns the user's
+ *      shell with piped stdio. Commands run and output streams live, which is
+ *      enough for "run a command for the user"; full TTY apps are degraded.
+ *
+ * One process is shared per cwd (a module singleton map), so the agent's
+ * `terminal` tool and the desktop pane drive the SAME session — the user sees
+ * the agent's commands appear live and can take over typing.
+ */
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+/** Minimal slice of node-pty we use — declared locally so typecheck never needs
+ *  `@types/node-pty` (the dep is optional). */
+interface NodePtyModule {
+    spawn(file: string, args: string[] | string, opts: {
+        name?: string;
+        cols?: number;
+        rows?: number;
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+    }): NodePtyProcess;
+}
+interface NodePtyProcess {
+    onData(cb: (data: string) => void): void;
+    onExit(cb: (e: {
+        exitCode: number;
+    }) => void): void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+}
+/**
+ * Resolve a usable NodePtyModule from whatever `import('node-pty')` yields, or
+ * null. Handles ESM/CJS interop (`.spawn` on the namespace OR on `.default`) and
+ * — critically — REQUIRES a callable `spawn` on whichever we pick. A malformed /
+ * partially-shimmed module (a `default` that lacks `spawn`, a non-function
+ * `spawn`) must degrade to the piped fallback HERE rather than be returned and
+ * blow up later as `pty.spawn is not a function` inside `createTerminalProcess`.
+ * Exported for tests — the optional dep is never present in CI, so the
+ * shape-resolution logic is unit-tested against hand-built module objects.
+ */
+export declare function resolveNodePtyModule(m: unknown): NodePtyModule | null;
+/** Add the executable bit (u+x,g+x,o+x) to a file if it lacks it. Returns true
+ *  when the file now has it (was already +x, or we just set it). Exported for
+ *  tests — the chmod logic is the load-bearing fix, so it's unit-tested directly
+ *  without needing node-pty present. */
+export declare function makeExecutable(filePath: string): boolean;
+export type TerminalBackend = 'pty' | 'pipe';
+export interface TerminalProcess {
+    readonly backend: TerminalBackend;
+    /** When `backend === 'pipe'`, the reason the real PTY couldn't start (so the
+     *  surface can show an honest "degraded" status instead of a silently-dead
+     *  box). Null when a real PTY is in use. */
+    readonly ptyError: string | null;
+    /** Subscribe to output (utf8). Returns an unsubscribe fn. */
+    onData(cb: (data: string) => void): () => void;
+    /** Subscribe to process exit. */
+    onExit(cb: (code: number) => void): () => void;
+    /** Recent output for a late-joining viewer. */
+    scrollback(): string;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    readonly alive: boolean;
+}
+/** Exported for tests: lets a suite drive `emitData`/`scrollback` directly
+ *  without spawning a real shell. Not part of the plugin's public surface. */
+export declare class TerminalProcessImpl implements TerminalProcess {
+    readonly backend: TerminalBackend;
+    private readonly pty;
+    private readonly child;
+    readonly ptyError: string | null;
+    private readonly dataListeners;
+    private readonly exitListeners;
+    private buffer;
+    private warnedListenerLeak;
+    alive: boolean;
+    constructor(backend: TerminalBackend, pty: NodePtyProcess | null, child: ChildProcessWithoutNullStreams | null, ptyError?: string | null);
+    /** Warn once when a listener Set grows past the leak threshold (a viewer whose
+     *  close() never ran keeps its subscription for the shell's whole life). */
+    private checkListenerLeak;
+    private emitData;
+    private emitExit;
+    onData(cb: (d: string) => void): () => void;
+    onExit(cb: (c: number) => void): () => void;
+    scrollback(): string;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    /**
+     * Terminate the piped shell AND its descendants. The child is spawned
+     * `detached` (its own process group), so a negative-pid signal reaches the
+     * whole tree — otherwise a running grandchild (a `sleep`, a dev server, a
+     * `tail -f`, a build) is reparented to init and leaks past session teardown,
+     * holding ports/files. Escalate SIGTERM → SIGKILL after a grace period.
+     */
+    private killChildTree;
+}
+/** Spawn a fresh shared terminal in `cwd`, preferring a real PTY. */
+export declare function createTerminalProcess(cwd: string): Promise<TerminalProcess>;
+export {};
+//# sourceMappingURL=pty.d.ts.map

package/dist/pty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../src/pty.ts"],"names":[],"mappings":"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"}

package/dist/pty.js

@@ -0,0 +1,415 @@
+/**
+ * The shared terminal process behind the `terminal` surface + tool.
+ *
+ * Two backends, picked at open time:
+ *   1. **node-pty** (preferred) — a real PTY, so interactive programs (vim, top,
+ *      a REPL) and prompts render correctly. Lazy-loaded; absent in a default
+ *      install (it is an OPTIONAL peer dep — native, so CI never has to build
+ *      it).
+ *   2. **piped child shell** (fallback, dependency-free) — spawns the user's
+ *      shell with piped stdio. Commands run and output streams live, which is
+ *      enough for "run a command for the user"; full TTY apps are degraded.
+ *
+ * One process is shared per cwd (a module singleton map), so the agent's
+ * `terminal` tool and the desktop pane drive the SAME session — the user sees
+ * the agent's commands appear live and can take over typing.
+ */
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import * as nodePath from 'node:path';
+/**
+ * Upper bound on output/exit listeners on a single shared process. A surface
+ * whose `close()` never runs (the viewer disconnects abnormally, the desktop
+ * crashes mid-stream) leaks its subscription for the life of the shared shell.
+ * Past this many live listeners we warn once — a runaway count is a leak, not a
+ * legitimate fan-out (only a handful of viewers + the per-command reader are
+ * ever expected). The set is not hard-capped (dropping a real viewer's stream
+ * is worse than the warning), but the diagnostic makes the leak visible.
+ */
+const LISTENER_WARN_THRESHOLD = 64;
+/**
+ * Grace period before escalating a kill() from SIGTERM to SIGKILL. An
+ * interactive shell that ignores/handles SIGTERM (or is wedged) would otherwise
+ * never die; after this we force it.
+ */
+const KILL_ESCALATION_MS = 2_000;
+/**
+ * Resolve a usable NodePtyModule from whatever `import('node-pty')` yields, or
+ * null. Handles ESM/CJS interop (`.spawn` on the namespace OR on `.default`) and
+ * — critically — REQUIRES a callable `spawn` on whichever we pick. A malformed /
+ * partially-shimmed module (a `default` that lacks `spawn`, a non-function
+ * `spawn`) must degrade to the piped fallback HERE rather than be returned and
+ * blow up later as `pty.spawn is not a function` inside `createTerminalProcess`.
+ * Exported for tests — the optional dep is never present in CI, so the
+ * shape-resolution logic is unit-tested against hand-built module objects.
+ */
+export function resolveNodePtyModule(m) {
+    const hasSpawn = (v) => typeof v === 'object' && v !== null && typeof v.spawn === 'function';
+    if (hasSpawn(m))
+        return m;
+    const def = m?.default;
+    if (hasSpawn(def))
+        return def;
+    return null;
+}
+let nodePtyPromise;
+/** Lazy-load node-pty; resolves to null when it isn't installed/usable. */
+function loadNodePty() {
+    if (!nodePtyPromise) {
+        nodePtyPromise = import('node-pty')
+            .then((m) => resolveNodePtyModule(m))
+            .catch(() => null);
+    }
+    return nodePtyPromise;
+}
+/** Add the executable bit (u+x,g+x,o+x) to a file if it lacks it. Returns true
+ *  when the file now has it (was already +x, or we just set it). Exported for
+ *  tests — the chmod logic is the load-bearing fix, so it's unit-tested directly
+ *  without needing node-pty present. */
+export function makeExecutable(filePath) {
+    try {
+        const st = statSync(filePath);
+        if (st.mode & 0o111)
+            return true; // already executable
+        chmodSync(filePath, st.mode | 0o111);
+        return true;
+    }
+    catch {
+        return false; // not present / not permitted — caller treats as best-effort
+    }
+}
+/**
+ * node-pty ships a prebuilt `spawn-helper` binary on macOS that it exec()s to
+ * launch the shell inside the PTY. Several install/repack paths (notably
+ * `npm install` into the desktop's writable CLI prefix, and pnpm's content store)
+ * drop the executable bit on it — node-pty then loads fine but `pty.spawn`
+ * throws `posix_spawnp failed`, which used to be swallowed into the (effectively
+ * dead) piped fallback. So before we spawn, ensure the helper is executable.
+ * Best-effort: never throws; the spawn itself is the real test.
+ */
+function ensureSpawnHelperExecutable() {
+    if (process.platform === 'win32')
+        return; // Windows uses conpty/winpty, no spawn-helper
+    try {
+        const root = nodePtyPackageRoot();
+        if (!root)
+            return;
+        const candidates = [
+            // prebuildify layout (the published npm package)
+            nodePath.join(root, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper'),
+            // build-from-source layout (no prebuild for this platform)
+            nodePath.join(root, 'build', 'Release', 'spawn-helper'),
+        ];
+        for (const c of candidates)
+            makeExecutable(c);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Resolve node-pty's package directory (the one containing `prebuilds/`),
+ *  resolving from THIS module so it works whether node-pty sits in a hoisted
+ *  root, a nested, or a pnpm store layout. */
+function nodePtyPackageRoot() {
+    try {
+        const require = createRequire(import.meta.url);
+        try {
+            return nodePath.dirname(require.resolve('node-pty/package.json'));
+        }
+        catch {
+            // `exports` may hide package.json; resolve the entry and walk up to the
+            // first ancestor that has a `prebuilds/` (or `build/`) dir.
+            let dir = nodePath.dirname(require.resolve('node-pty'));
+            for (let i = 0; i < 6; i += 1) {
+                if (existsSync(nodePath.join(dir, 'prebuilds')) || existsSync(nodePath.join(dir, 'build'))) {
+                    return dir;
+                }
+                const parent = nodePath.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/** Pick the user's interactive shell per platform. */
+function defaultShell() {
+    if (process.platform === 'win32')
+        return process.env['COMSPEC'] ?? 'powershell.exe';
+    return process.env['SHELL'] ?? '/bin/bash';
+}
+/** Cap retained scrollback so a chatty process can't grow the buffer forever. */
+const MAX_SCROLLBACK = 200_000;
+/**
+ * Hysteresis margin: let the live buffer grow this far past the cap before
+ * trimming back down to it, so we amortize the (expensive) slice over many
+ * chunks instead of copying ~MAX_SCROLLBACK bytes on every chunk once
+ * saturated. `scrollback()` masks the slack by always returning the last
+ * MAX_SCROLLBACK chars.
+ */
+const SCROLLBACK_SLACK = 100_000;
+/** Upper bound on a PTY dimension. A viewer/relay could request an absurd
+ *  cols/rows (off the wire, unvalidated upstream); node-pty/conpty allocates
+ *  per-cell and can throw or wedge on extreme values, so cap to a generous but
+ *  finite ceiling. Far larger than any real terminal. */
+const MAX_DIMENSION = 10_000;
+/** Floor to an integer and clamp into [1, MAX_DIMENSION]; non-finite → 1. */
+function clampDimension(n) {
+    if (!Number.isFinite(n))
+        return 1;
+    return Math.min(MAX_DIMENSION, Math.max(1, Math.floor(n)));
+}
+/** Exported for tests: lets a suite drive `emitData`/`scrollback` directly
+ *  without spawning a real shell. Not part of the plugin's public surface. */
+export class TerminalProcessImpl {
+    backend;
+    pty;
+    child;
+    ptyError;
+    dataListeners = new Set();
+    exitListeners = new Set();
+    buffer = '';
+    warnedListenerLeak = false;
+    alive = true;
+    constructor(backend, pty, child, ptyError = null) {
+        this.backend = backend;
+        this.pty = pty;
+        this.child = child;
+        this.ptyError = ptyError;
+        if (pty) {
+            pty.onData((d) => this.emitData(d));
+            pty.onExit((e) => this.emitExit(e.exitCode));
+        }
+        else if (child) {
+            // The shared child is long-lived and may be (re)subscribed by several
+            // viewers over its lifetime; make the intent explicit so Node never emits
+            // a false-positive "possible EventEmitter memory leak detected" warning on
+            // its streams. Our own fan-out Sets are the real bound (see addListener).
+            child.stdout.setMaxListeners(0);
+            child.stderr.setMaxListeners(0);
+            child.stdin.setMaxListeners(0);
+            child.setMaxListeners(0);
+            child.stdout.on('data', (b) => this.emitData(b.toString('utf8')));
+            child.stderr.on('data', (b) => this.emitData(b.toString('utf8')));
+            child.on('exit', (code) => this.emitExit(code ?? 0));
+            child.on('error', () => this.emitExit(1));
+            // The child can exit (closing stdin) before the async 'exit' event flips
+            // `alive` — a write in that window can emit a broken-pipe 'error' on
+            // stdin. Swallow it here so it never goes unhandled and crashes the host.
+            child.stdin.on('error', () => {
+                /* broken pipe after shell exit — ignored */
+            });
+        }
+    }
+    /** Warn once when a listener Set grows past the leak threshold (a viewer whose
+     *  close() never ran keeps its subscription for the shell's whole life). */
+    checkListenerLeak() {
+        if (this.warnedListenerLeak)
+            return;
+        if (this.dataListeners.size + this.exitListeners.size > LISTENER_WARN_THRESHOLD) {
+            this.warnedListenerLeak = true;
+            console.warn(`[plugin-terminal] shared terminal has ${this.dataListeners.size} data + ` +
+                `${this.exitListeners.size} exit listeners — likely a viewer that never closed.`);
+        }
+    }
+    emitData(d) {
+        // Append, and only trim when we exceed the cap by a hysteresis margin —
+        // trimming all the way back to the cap. The previous code sliced the full
+        // 200KB buffer on EVERY chunk once saturated (O(total_output * cap) churn);
+        // amortizing the trim makes appends ~O(1). `scrollback()` always returns the
+        // last MAX_SCROLLBACK chars, so the observable tail is unchanged.
+        this.buffer += d;
+        if (this.buffer.length > MAX_SCROLLBACK + SCROLLBACK_SLACK) {
+            this.buffer = this.buffer.slice(-MAX_SCROLLBACK);
+        }
+        for (const cb of this.dataListeners) {
+            try {
+                cb(d);
+            }
+            catch {
+                /* a bad viewer must not break the stream */
+            }
+        }
+    }
+    emitExit(code) {
+        if (!this.alive)
+            return;
+        this.alive = false;
+        for (const cb of this.exitListeners) {
+            try {
+                cb(code);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    onData(cb) {
+        this.dataListeners.add(cb);
+        this.checkListenerLeak();
+        return () => this.dataListeners.delete(cb);
+    }
+    onExit(cb) {
+        this.exitListeners.add(cb);
+        this.checkListenerLeak();
+        return () => this.exitListeners.delete(cb);
+    }
+    scrollback() {
+        // The buffer may hold up to MAX_SCROLLBACK + SCROLLBACK_SLACK chars between
+        // trims (see emitData); always hand back exactly the last MAX_SCROLLBACK so
+        // a late-joining viewer sees the same tail as before the hysteresis change.
+        return this.buffer.length > MAX_SCROLLBACK
+            ? this.buffer.slice(-MAX_SCROLLBACK)
+            : this.buffer;
+    }
+    write(data) {
+        if (!this.alive)
+            return;
+        try {
+            if (this.pty)
+                this.pty.write(data);
+            else
+                this.child?.stdin.write(data);
+        }
+        catch {
+            // The child may have exited between `alive` flipping and now, leaving a
+            // closed stdin pipe — a synchronous EPIPE here must not crash the host.
+        }
+    }
+    resize(cols, rows) {
+        if (this.pty && this.alive) {
+            // Coerce to a sane integer in [1, MAX_DIMENSION]. Callers SHOULD pre-validate
+            // (terminal.ts isValidDimension), but a float/huge value reaching node-pty
+            // can throw or wedge conpty, so clamp defensively here too.
+            try {
+                this.pty.resize(clampDimension(cols), clampDimension(rows));
+            }
+            catch {
+                /* resize on a dead pty — ignore */
+            }
+        }
+        // The piped fallback has no TTY to resize.
+    }
+    kill() {
+        if (!this.alive)
+            return;
+        try {
+            if (this.pty) {
+                // node-pty kills the conpty/pty session; on POSIX it signals the shell.
+                // Send SIGTERM, then escalate to SIGKILL after a grace period if the
+                // shell ignores/handles it (a wedged shell would otherwise never die).
+                this.pty.kill();
+                const pty = this.pty;
+                setTimeout(() => {
+                    try {
+                        pty.kill('SIGKILL');
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }, KILL_ESCALATION_MS).unref?.();
+            }
+            if (this.child)
+                this.killChildTree(this.child);
+        }
+        catch {
+            /* already gone */
+        }
+        this.emitExit(0);
+    }
+    /**
+     * Terminate the piped shell AND its descendants. The child is spawned
+     * `detached` (its own process group), so a negative-pid signal reaches the
+     * whole tree — otherwise a running grandchild (a `sleep`, a dev server, a
+     * `tail -f`, a build) is reparented to init and leaks past session teardown,
+     * holding ports/files. Escalate SIGTERM → SIGKILL after a grace period.
+     */
+    killChildTree(child) {
+        const pid = child.pid;
+        const signalGroup = (signal) => {
+            try {
+                if (pid !== undefined && process.platform !== 'win32') {
+                    // Negative pid = the whole process group (requires detached spawn).
+                    process.kill(-pid, signal);
+                }
+                else {
+                    // Windows / unknown pid: node handles its own tree (taskkill /T-like).
+                    child.kill(signal);
+                }
+            }
+            catch {
+                // No such process group (already dead) or not permitted — fall back to
+                // signaling just the child so we never leave it running.
+                try {
+                    child.kill(signal);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        };
+        signalGroup('SIGTERM');
+        setTimeout(() => signalGroup('SIGKILL'), KILL_ESCALATION_MS).unref?.();
+    }
+}
+/** Spawn a fresh shared terminal in `cwd`, preferring a real PTY. */
+export async function createTerminalProcess(cwd) {
+    const shell = defaultShell();
+    const cols = 80;
+    const rows = 24;
+    // SECURITY: the shared shell deliberately inherits the runner's full
+    // environment (API keys, tokens, MOXXY_* signing keys). This mirrors a real
+    // user shell so the agent's commands behave as the user expects (a script
+    // that needs $GITHUB_TOKEN works). The trade-off is that `env`/`printenv` can
+    // surface secrets into captured output and scrollback — acceptable because the
+    // terminal is a deliberately user-facing, user-controllable surface. Do NOT
+    // strip vars here (it would silently break legitimate commands); gate any
+    // scrubbing behind an explicit opt-in if ever needed.
+    const env = { ...process.env, TERM: 'xterm-256color' };
+    const pty = await loadNodePty();
+    let ptyError = pty ? null : 'node-pty is not installed';
+    if (pty) {
+        const trySpawn = () => pty.spawn(shell, [], { name: 'xterm-256color', cols, rows, cwd, env });
+        // Make sure the prebuilt spawn-helper is executable, then spawn. If the first
+        // spawn still fails (e.g. the bit was only just lost), repair + retry ONCE
+        // before giving up — most "posix_spawnp failed" cases clear on the retry.
+        ensureSpawnHelperExecutable();
+        try {
+            return new TerminalProcessImpl('pty', trySpawn(), null);
+        }
+        catch {
+            ensureSpawnHelperExecutable();
+            try {
+                return new TerminalProcessImpl('pty', trySpawn(), null);
+            }
+            catch (err2) {
+                // Don't swallow it: record WHY so the surface can show an honest status
+                // instead of a silently-dead piped terminal.
+                ptyError = err2 instanceof Error ? err2.message : String(err2);
+            }
+        }
+    }
+    // Dependency-free fallback: an interactive shell with piped stdio. `-i` keeps
+    // it from exiting immediately; non-Windows only — cmd/powershell are already
+    // interactive when stdin is piped. NOTE: this has no TTY line discipline (a
+    // viewer's `\r` is never turned into `\n`, nothing echoes), so it is NOT a
+    // usable interactive terminal — `ptyError` is surfaced to the user so the pane
+    // reports the degraded state rather than appearing to ignore every keystroke.
+    const args = process.platform === 'win32' ? [] : ['-i'];
+    const child = spawn(shell, args, {
+        cwd,
+        env: { ...env, PS1: '$ ' },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // Own process group (POSIX) so kill() can signal the WHOLE tree by negative
+        // pid — otherwise grandchildren (a dev server, a `tail -f`, a build) outlive
+        // the session. No-op semantics on Windows; node-pty handles its own tree.
+        detached: process.platform !== 'win32',
+    });
+    return new TerminalProcessImpl('pipe', null, child, ptyError);
+}
+//# sourceMappingURL=pty.js.map

package/dist/pty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty.js","sourceRoot":"","sources":["../src/pty.ts"],"names":[],"mappings":"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"}

package/dist/terminal.d.ts

@@ -0,0 +1,33 @@
+import { type TerminalProcess } from './pty.js';
+export declare function getSharedTerminal(cwd: string, create?: (cwd: string) => Promise<TerminalProcess>): Promise<TerminalProcess>;
+/** Dispose every shared terminal (plugin shutdown / session close). */
+export declare function closeAllTerminals(): void;
+/** The `terminal` surface: streams the shared PTY's output and feeds a viewer's
+ *  keystrokes / resizes back into it. */
+export declare function buildTerminalSurface(): import("@moxxy/sdk").SurfaceDef;
+/**
+ * The `terminal` tool runs a command in the SHARED terminal the user sees. It
+ * appends a unique sentinel that echoes the exit code, then reads output until
+ * the sentinel returns — reliable completion detection in an interactive,
+ * input-echoing shell. The command and its output stay visible to the user, who
+ * can take over at any time.
+ */
+export declare function buildTerminalTool(): import("@moxxy/sdk").ToolDef;
+/**
+ * Write `command` then a sentinel `printf` to a shared shell and collect output
+ * until the sentinel line appears. Returns the captured output (best-effort
+ * stripped of the echoed sentinel command) + the exit code parsed from it.
+ *
+ * Serialized per shared process: a command writes only once the previous one on
+ * the same shell finishes, so concurrent callers never interleave their writes
+ * on the single stdin and each `$?` reflects its OWN command.
+ */
+export declare function runCommand(proc: TerminalProcess, command: string, marker: string, timeoutMs: number, 
+/** Optional turn-abort signal; firing it finishes the command immediately
+ *  (timedOut=false) without waiting for the sentinel or the timeout. */
+signal?: AbortSignal): Promise<{
+    output: string;
+    exitCode: number | null;
+    timedOut: boolean;
+}>;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAmCvE,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAyB,GACxE,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,IAAI,CASxC;AAWD;yCACyC;AACzC,wBAAgB,oBAAoB,oCAyEnC;AAmBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,iCAkChC;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM;AACjB;wEACwE;AACxE,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAkBzE"}