@theokit/sdk-pty 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 usetheo.dev
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,17 @@
+# @theokit/sdk-pty
+
+Local, `node-pty`-backed implementation of `@theokit/sdk`'s `InteractiveBackend`.
+
+Opt-in and **terminal-surface only** — this is the ONLY package in the theokit
+ecosystem that depends on `node-pty` (optionally, so install never fails on a
+native build). Core / `@theokit/sdk-tools` / cluster / desktop backends never
+touch it.
+
+```ts
+import { PtyInteractiveBackend } from "@theokit/sdk-pty";
+// inject into an interactive shell tool that depends on InteractiveBackend
+const interactive = new PtyInteractiveBackend();
+```
+
+When `node-pty` is unavailable (or a spawn fails), every method throws the SDK's
+typed `InteractiveUnavailableError` so the caller falls back to non-interactive exec.

package/dist/index.cjs

@@ -0,0 +1,157 @@
+'use strict';
+
+var crypto = require('crypto');
+var fs = require('fs');
+var module$1 = require('module');
+var interactive = require('@theokit/sdk/interactive');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// src/pty-interactive-backend.ts
+var nodeRequire = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+var YIELD_MIN_MS = 250;
+var YIELD_MAX_MS = 3e4;
+var DEFAULT_YIELD_MS = 500;
+var DEFAULT_TTL_MS = 3e5;
+var DEFAULT_MAX_BYTES = 1e5;
+function clampYield(ms) {
+  const v = ms ?? DEFAULT_YIELD_MS;
+  return Math.max(YIELD_MIN_MS, Math.min(YIELD_MAX_MS, v));
+}
+function capTail(buf, max) {
+  return buf.length > max ? `\u2026(truncated)
+${buf.slice(-max)}` : buf;
+}
+var PtyInteractiveBackend = class extends interactive.InteractiveBackend {
+  sessions = /* @__PURE__ */ new Map();
+  ptyModule;
+  exitReaperArmed = false;
+  /** Lazy, cached node-pty load — a failed native build must degrade, not crash at import time. */
+  loadPty() {
+    if (this.ptyModule !== void 0) return this.ptyModule;
+    try {
+      this.ptyModule = nodeRequire("node-pty");
+    } catch {
+      this.ptyModule = null;
+    }
+    return this.ptyModule;
+  }
+  /** Whether the interactive (PTY) path is usable in this environment. */
+  available() {
+    return this.loadPty() !== null;
+  }
+  /** Reap orphaned PTYs when the host process exits. ONLY the `exit` event — installing SIGINT/SIGTERM
+   *  handlers would remove Node's default terminate-on-signal behavior. Armed once, lazily. */
+  armExitReaper() {
+    if (this.exitReaperArmed) return;
+    this.exitReaperArmed = true;
+    process.on("exit", () => this.killAll());
+  }
+  async collect(session, yieldMs, maxBytes) {
+    await new Promise((r) => setTimeout(r, clampYield(yieldMs)));
+    const out = session.pending;
+    session.pending = "";
+    return capTail(out, maxBytes);
+  }
+  armTtl(session, ttlMs) {
+    clearTimeout(session.ttlTimer);
+    session.ttlTimer = setTimeout(() => this.kill(session.id), ttlMs);
+  }
+  async startInteractive(command, opts) {
+    const pty = this.loadPty();
+    if (pty === null) {
+      throw new interactive.InteractiveUnavailableError(
+        "interactive shell unavailable: node-pty native module failed to load; use non-interactive exec"
+      );
+    }
+    this.armExitReaper();
+    const shell = process.env.SHELL ?? "/bin/bash";
+    const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+    const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const cwd = opts?.cwd ?? process.cwd();
+    if (!fs.existsSync(cwd)) {
+      throw new interactive.InteractiveUnavailableError(`interactive shell unavailable: cwd does not exist: ${cwd}`);
+    }
+    let proc;
+    try {
+      proc = pty.spawn(shell, ["-c", command], {
+        name: "xterm-color",
+        cols: opts?.cols ?? 80,
+        rows: opts?.rows ?? 24,
+        cwd,
+        env: process.env
+      });
+    } catch (err) {
+      throw new interactive.InteractiveUnavailableError(
+        `interactive shell unavailable: failed to spawn a PTY (${err instanceof Error ? err.message : String(err)})`
+      );
+    }
+    const id = `pty-${crypto.randomUUID()}`;
+    const session = {
+      id,
+      pty: proc,
+      pending: "",
+      alive: true,
+      ttlTimer: setTimeout(() => this.kill(id), ttlMs),
+      writeChain: Promise.resolve()
+    };
+    proc.onData((data) => {
+      session.pending = capTail(session.pending + data, maxBytes);
+    });
+    proc.onExit(() => {
+      session.alive = false;
+      clearTimeout(session.ttlTimer);
+      this.sessions.delete(id);
+    });
+    this.sessions.set(id, session);
+    const output = await this.collect(session, opts?.yieldMs ?? DEFAULT_YIELD_MS, maxBytes);
+    return { sessionId: id, output };
+  }
+  async writeStdin(sessionId, chars, opts) {
+    const session = this.sessions.get(sessionId);
+    if (session === void 0 || !session.alive) throw new interactive.NoSuchSessionError(sessionId);
+    const run = session.writeChain.then(async () => {
+      if (!session.alive) throw new interactive.NoSuchSessionError(sessionId);
+      this.armTtl(session, opts?.ttlMs ?? DEFAULT_TTL_MS);
+      if (chars.length > 0) session.pty.write(chars);
+      const output = await this.collect(
+        session,
+        opts?.yieldMs ?? DEFAULT_YIELD_MS,
+        opts?.maxBytes ?? DEFAULT_MAX_BYTES
+      );
+      return { output, alive: session.alive };
+    });
+    session.writeChain = run.catch(() => void 0);
+    return run;
+  }
+  /** Kill a single session (idempotent). Kills the whole process GROUP so a detached grandchild dies too. */
+  kill(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session === void 0) return;
+    clearTimeout(session.ttlTimer);
+    session.alive = false;
+    this.sessions.delete(sessionId);
+    try {
+      process.kill(-session.pty.pid, "SIGKILL");
+    } catch {
+      try {
+        session.pty.kill();
+      } catch {
+      }
+    }
+  }
+  /** Reap every session — used by the process-exit reaper; also callable on `/clear`. */
+  killAll() {
+    for (const id of [...this.sessions.keys()]) this.kill(id);
+  }
+  /** Live session count — for observability / tests. */
+  activeSessionCount() {
+    return this.sessions.size;
+  }
+};
+
+exports.PtyInteractiveBackend = PtyInteractiveBackend;
+exports.YIELD_MAX_MS = YIELD_MAX_MS;
+exports.YIELD_MIN_MS = YIELD_MIN_MS;
+exports.clampYield = clampYield;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pty-interactive-backend.ts"],"names":["createRequire","InteractiveBackend","InteractiveUnavailableError","existsSync","randomUUID","NoSuchSessionError"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * `PtyInteractiveBackend` — the LOCAL implementation of `@theokit/sdk`'s\n * `InteractiveBackend`, backed by `node-pty`. This is the terminal-surface\n * backend: it allocates a real pseudo-terminal so REPLs, `git rebase -i`, and\n * prompting commands can be driven to completion. Ported from the AgentBuilder\n * Codex clone (M11) into the ecosystem (M14) so any terminal agent injects it.\n *\n * `node-pty` is an OPTIONAL dependency of this package — the ONLY place in the\n * theokit ecosystem that touches it. Core / sdk-tools / cluster / desktop never\n * do. When the native module is unavailable (or a spawn fails), every method\n * throws the SDK's typed {@link InteractiveUnavailableError} so the caller falls\n * back to non-interactive exec.\n *\n * Safety (mirrors M11): graceful typed degradation; per-session write\n * serialization (concurrent writes never steal each other's output); idle TTL\n * reaper; process-GROUP kill so detached grandchildren die; a process-exit\n * reaper; tail-capped output (the live prompt, not the stale banner).\n */\nimport { randomUUID } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\n\nimport {\n  InteractiveBackend,\n  InteractiveUnavailableError,\n  NoSuchSessionError,\n  type StartInteractiveOptions,\n  type StartInteractiveResult,\n  type WriteStdinOptions,\n  type WriteStdinResult,\n} from \"@theokit/sdk/interactive\";\n\nconst nodeRequire = createRequire(import.meta.url);\n\nexport const YIELD_MIN_MS = 250;\nexport const YIELD_MAX_MS = 30_000;\nconst DEFAULT_YIELD_MS = 500;\nconst DEFAULT_TTL_MS = 300_000; // 5 min idle → reap\nconst DEFAULT_MAX_BYTES = 100_000;\n\n/** The minimal `node-pty` surface driven here (kept structural so the import stays lazy). */\ninterface PtyProcess {\n  readonly pid: number;\n  write(data: string): void;\n  kill(signal?: string): void;\n  onData(cb: (data: string) => void): void;\n  onExit(cb: (e: { exitCode: number }) => void): void;\n}\ninterface PtyModule {\n  spawn(file: string, args: string[], opts: Record<string, unknown>): PtyProcess;\n}\n\ninterface PtySession {\n  id: string;\n  pty: PtyProcess;\n  pending: string;\n  alive: boolean;\n  ttlTimer: ReturnType<typeof setTimeout>;\n  writeChain: Promise<unknown>;\n}\n\n/** Bound the yield window to [{@link YIELD_MIN_MS}, {@link YIELD_MAX_MS}]. */\nexport function clampYield(ms: number | undefined): number {\n  const v = ms ?? DEFAULT_YIELD_MS;\n  return Math.max(YIELD_MIN_MS, Math.min(YIELD_MAX_MS, v));\n}\n\n/** Keep the TAIL of output — the newest bytes carry the live prompt. */\nfunction capTail(buf: string, max: number): string {\n  return buf.length > max ? `…(truncated)\\n${buf.slice(-max)}` : buf;\n}\n\nexport class PtyInteractiveBackend extends InteractiveBackend {\n  private readonly sessions = new Map<string, PtySession>();\n  private ptyModule: PtyModule | null | undefined;\n  private exitReaperArmed = false;\n\n  /** Lazy, cached node-pty load — a failed native build must degrade, not crash at import time. */\n  private loadPty(): PtyModule | null {\n    if (this.ptyModule !== undefined) return this.ptyModule;\n    try {\n      this.ptyModule = nodeRequire(\"node-pty\") as PtyModule;\n    } catch {\n      this.ptyModule = null;\n    }\n    return this.ptyModule;\n  }\n\n  /** Whether the interactive (PTY) path is usable in this environment. */\n  available(): boolean {\n    return this.loadPty() !== null;\n  }\n\n  /** Reap orphaned PTYs when the host process exits. ONLY the `exit` event — installing SIGINT/SIGTERM\n   *  handlers would remove Node's default terminate-on-signal behavior. Armed once, lazily. */\n  private armExitReaper(): void {\n    if (this.exitReaperArmed) return;\n    this.exitReaperArmed = true;\n    process.on(\"exit\", () => this.killAll());\n  }\n\n  private async collect(session: PtySession, yieldMs: number, maxBytes: number): Promise<string> {\n    await new Promise((r) => setTimeout(r, clampYield(yieldMs)));\n    const out = session.pending;\n    session.pending = \"\";\n    return capTail(out, maxBytes);\n  }\n\n  private armTtl(session: PtySession, ttlMs: number): void {\n    clearTimeout(session.ttlTimer);\n    session.ttlTimer = setTimeout(() => this.kill(session.id), ttlMs);\n  }\n\n  async startInteractive(\n    command: string,\n    opts?: StartInteractiveOptions,\n  ): Promise<StartInteractiveResult> {\n    const pty = this.loadPty();\n    if (pty === null) {\n      throw new InteractiveUnavailableError(\n        \"interactive shell unavailable: node-pty native module failed to load; use non-interactive exec\",\n      );\n    }\n    this.armExitReaper();\n    const shell = process.env.SHELL ?? \"/bin/bash\";\n    const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;\n    const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;\n    // Validate cwd at the boundary: node-pty does NOT throw on a non-existent cwd (it spawns a broken\n    // session), so fail-fast to the typed fallback the caller expects.\n    const cwd = opts?.cwd ?? process.cwd();\n    if (!existsSync(cwd)) {\n      throw new InteractiveUnavailableError(`interactive shell unavailable: cwd does not exist: ${cwd}`);\n    }\n    let proc: PtyProcess;\n    try {\n      proc = pty.spawn(shell, [\"-c\", command], {\n        name: \"xterm-color\",\n        cols: opts?.cols ?? 80,\n        rows: opts?.rows ?? 24,\n        cwd,\n        env: process.env,\n      });\n    } catch (err) {\n      throw new InteractiveUnavailableError(\n        `interactive shell unavailable: failed to spawn a PTY (${err instanceof Error ? err.message : String(err)})`,\n      );\n    }\n    const id = `pty-${randomUUID()}`;\n    const session: PtySession = {\n      id,\n      pty: proc,\n      pending: \"\",\n      alive: true,\n      ttlTimer: setTimeout(() => this.kill(id), ttlMs),\n      writeChain: Promise.resolve(),\n    };\n    proc.onData((data) => {\n      session.pending = capTail(session.pending + data, maxBytes);\n    });\n    proc.onExit(() => {\n      session.alive = false;\n      clearTimeout(session.ttlTimer);\n      this.sessions.delete(id);\n    });\n    this.sessions.set(id, session);\n    const output = await this.collect(session, opts?.yieldMs ?? DEFAULT_YIELD_MS, maxBytes);\n    return { sessionId: id, output };\n  }\n\n  async writeStdin(\n    sessionId: string,\n    chars: string,\n    opts?: WriteStdinOptions,\n  ): Promise<WriteStdinResult> {\n    const session = this.sessions.get(sessionId);\n    if (session === undefined || !session.alive) throw new NoSuchSessionError(sessionId);\n    // Serialize per session: chain onto the previous write so two concurrent calls run strictly in\n    // order and each reads only its own output window (no stolen output).\n    const run = session.writeChain.then(async () => {\n      if (!session.alive) throw new NoSuchSessionError(sessionId);\n      this.armTtl(session, opts?.ttlMs ?? DEFAULT_TTL_MS);\n      if (chars.length > 0) session.pty.write(chars);\n      const output = await this.collect(\n        session,\n        opts?.yieldMs ?? DEFAULT_YIELD_MS,\n        opts?.maxBytes ?? DEFAULT_MAX_BYTES,\n      );\n      return { output, alive: session.alive };\n    });\n    session.writeChain = run.catch(() => undefined);\n    return run;\n  }\n\n  /** Kill a single session (idempotent). Kills the whole process GROUP so a detached grandchild dies too. */\n  kill(sessionId: string): void {\n    const session = this.sessions.get(sessionId);\n    if (session === undefined) return;\n    clearTimeout(session.ttlTimer);\n    session.alive = false;\n    this.sessions.delete(sessionId);\n    try {\n      process.kill(-session.pty.pid, \"SIGKILL\");\n    } catch {\n      try {\n        session.pty.kill();\n      } catch {\n        // already dead — nothing to do\n      }\n    }\n  }\n\n  /** Reap every session — used by the process-exit reaper; also callable on `/clear`. */\n  killAll(): void {\n    for (const id of [...this.sessions.keys()]) this.kill(id);\n  }\n\n  /** Live session count — for observability / tests. */\n  activeSessionCount(): number {\n    return this.sessions.size;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import { InteractiveBackend, StartInteractiveOptions, StartInteractiveResult, WriteStdinOptions, WriteStdinResult } from '@theokit/sdk/interactive';
+
+declare const YIELD_MIN_MS = 250;
+declare const YIELD_MAX_MS = 30000;
+/** Bound the yield window to [{@link YIELD_MIN_MS}, {@link YIELD_MAX_MS}]. */
+declare function clampYield(ms: number | undefined): number;
+declare class PtyInteractiveBackend extends InteractiveBackend {
+    private readonly sessions;
+    private ptyModule;
+    private exitReaperArmed;
+    /** Lazy, cached node-pty load — a failed native build must degrade, not crash at import time. */
+    private loadPty;
+    /** Whether the interactive (PTY) path is usable in this environment. */
+    available(): boolean;
+    /** Reap orphaned PTYs when the host process exits. ONLY the `exit` event — installing SIGINT/SIGTERM
+     *  handlers would remove Node's default terminate-on-signal behavior. Armed once, lazily. */
+    private armExitReaper;
+    private collect;
+    private armTtl;
+    startInteractive(command: string, opts?: StartInteractiveOptions): Promise<StartInteractiveResult>;
+    writeStdin(sessionId: string, chars: string, opts?: WriteStdinOptions): Promise<WriteStdinResult>;
+    /** Kill a single session (idempotent). Kills the whole process GROUP so a detached grandchild dies too. */
+    kill(sessionId: string): void;
+    /** Reap every session — used by the process-exit reaper; also callable on `/clear`. */
+    killAll(): void;
+    /** Live session count — for observability / tests. */
+    activeSessionCount(): number;
+}
+
+export { PtyInteractiveBackend, YIELD_MAX_MS, YIELD_MIN_MS, clampYield };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { InteractiveBackend, StartInteractiveOptions, StartInteractiveResult, WriteStdinOptions, WriteStdinResult } from '@theokit/sdk/interactive';
+
+declare const YIELD_MIN_MS = 250;
+declare const YIELD_MAX_MS = 30000;
+/** Bound the yield window to [{@link YIELD_MIN_MS}, {@link YIELD_MAX_MS}]. */
+declare function clampYield(ms: number | undefined): number;
+declare class PtyInteractiveBackend extends InteractiveBackend {
+    private readonly sessions;
+    private ptyModule;
+    private exitReaperArmed;
+    /** Lazy, cached node-pty load — a failed native build must degrade, not crash at import time. */
+    private loadPty;
+    /** Whether the interactive (PTY) path is usable in this environment. */
+    available(): boolean;
+    /** Reap orphaned PTYs when the host process exits. ONLY the `exit` event — installing SIGINT/SIGTERM
+     *  handlers would remove Node's default terminate-on-signal behavior. Armed once, lazily. */
+    private armExitReaper;
+    private collect;
+    private armTtl;
+    startInteractive(command: string, opts?: StartInteractiveOptions): Promise<StartInteractiveResult>;
+    writeStdin(sessionId: string, chars: string, opts?: WriteStdinOptions): Promise<WriteStdinResult>;
+    /** Kill a single session (idempotent). Kills the whole process GROUP so a detached grandchild dies too. */
+    kill(sessionId: string): void;
+    /** Reap every session — used by the process-exit reaper; also callable on `/clear`. */
+    killAll(): void;
+    /** Live session count — for observability / tests. */
+    activeSessionCount(): number;
+}
+
+export { PtyInteractiveBackend, YIELD_MAX_MS, YIELD_MIN_MS, clampYield };

package/dist/index.js

@@ -0,0 +1,151 @@
+import { randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { createRequire } from 'module';
+import { InteractiveBackend, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
+
+// src/pty-interactive-backend.ts
+var nodeRequire = createRequire(import.meta.url);
+var YIELD_MIN_MS = 250;
+var YIELD_MAX_MS = 3e4;
+var DEFAULT_YIELD_MS = 500;
+var DEFAULT_TTL_MS = 3e5;
+var DEFAULT_MAX_BYTES = 1e5;
+function clampYield(ms) {
+  const v = ms ?? DEFAULT_YIELD_MS;
+  return Math.max(YIELD_MIN_MS, Math.min(YIELD_MAX_MS, v));
+}
+function capTail(buf, max) {
+  return buf.length > max ? `\u2026(truncated)
+${buf.slice(-max)}` : buf;
+}
+var PtyInteractiveBackend = class extends InteractiveBackend {
+  sessions = /* @__PURE__ */ new Map();
+  ptyModule;
+  exitReaperArmed = false;
+  /** Lazy, cached node-pty load — a failed native build must degrade, not crash at import time. */
+  loadPty() {
+    if (this.ptyModule !== void 0) return this.ptyModule;
+    try {
+      this.ptyModule = nodeRequire("node-pty");
+    } catch {
+      this.ptyModule = null;
+    }
+    return this.ptyModule;
+  }
+  /** Whether the interactive (PTY) path is usable in this environment. */
+  available() {
+    return this.loadPty() !== null;
+  }
+  /** Reap orphaned PTYs when the host process exits. ONLY the `exit` event — installing SIGINT/SIGTERM
+   *  handlers would remove Node's default terminate-on-signal behavior. Armed once, lazily. */
+  armExitReaper() {
+    if (this.exitReaperArmed) return;
+    this.exitReaperArmed = true;
+    process.on("exit", () => this.killAll());
+  }
+  async collect(session, yieldMs, maxBytes) {
+    await new Promise((r) => setTimeout(r, clampYield(yieldMs)));
+    const out = session.pending;
+    session.pending = "";
+    return capTail(out, maxBytes);
+  }
+  armTtl(session, ttlMs) {
+    clearTimeout(session.ttlTimer);
+    session.ttlTimer = setTimeout(() => this.kill(session.id), ttlMs);
+  }
+  async startInteractive(command, opts) {
+    const pty = this.loadPty();
+    if (pty === null) {
+      throw new InteractiveUnavailableError(
+        "interactive shell unavailable: node-pty native module failed to load; use non-interactive exec"
+      );
+    }
+    this.armExitReaper();
+    const shell = process.env.SHELL ?? "/bin/bash";
+    const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+    const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const cwd = opts?.cwd ?? process.cwd();
+    if (!existsSync(cwd)) {
+      throw new InteractiveUnavailableError(`interactive shell unavailable: cwd does not exist: ${cwd}`);
+    }
+    let proc;
+    try {
+      proc = pty.spawn(shell, ["-c", command], {
+        name: "xterm-color",
+        cols: opts?.cols ?? 80,
+        rows: opts?.rows ?? 24,
+        cwd,
+        env: process.env
+      });
+    } catch (err) {
+      throw new InteractiveUnavailableError(
+        `interactive shell unavailable: failed to spawn a PTY (${err instanceof Error ? err.message : String(err)})`
+      );
+    }
+    const id = `pty-${randomUUID()}`;
+    const session = {
+      id,
+      pty: proc,
+      pending: "",
+      alive: true,
+      ttlTimer: setTimeout(() => this.kill(id), ttlMs),
+      writeChain: Promise.resolve()
+    };
+    proc.onData((data) => {
+      session.pending = capTail(session.pending + data, maxBytes);
+    });
+    proc.onExit(() => {
+      session.alive = false;
+      clearTimeout(session.ttlTimer);
+      this.sessions.delete(id);
+    });
+    this.sessions.set(id, session);
+    const output = await this.collect(session, opts?.yieldMs ?? DEFAULT_YIELD_MS, maxBytes);
+    return { sessionId: id, output };
+  }
+  async writeStdin(sessionId, chars, opts) {
+    const session = this.sessions.get(sessionId);
+    if (session === void 0 || !session.alive) throw new NoSuchSessionError(sessionId);
+    const run = session.writeChain.then(async () => {
+      if (!session.alive) throw new NoSuchSessionError(sessionId);
+      this.armTtl(session, opts?.ttlMs ?? DEFAULT_TTL_MS);
+      if (chars.length > 0) session.pty.write(chars);
+      const output = await this.collect(
+        session,
+        opts?.yieldMs ?? DEFAULT_YIELD_MS,
+        opts?.maxBytes ?? DEFAULT_MAX_BYTES
+      );
+      return { output, alive: session.alive };
+    });
+    session.writeChain = run.catch(() => void 0);
+    return run;
+  }
+  /** Kill a single session (idempotent). Kills the whole process GROUP so a detached grandchild dies too. */
+  kill(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session === void 0) return;
+    clearTimeout(session.ttlTimer);
+    session.alive = false;
+    this.sessions.delete(sessionId);
+    try {
+      process.kill(-session.pty.pid, "SIGKILL");
+    } catch {
+      try {
+        session.pty.kill();
+      } catch {
+      }
+    }
+  }
+  /** Reap every session — used by the process-exit reaper; also callable on `/clear`. */
+  killAll() {
+    for (const id of [...this.sessions.keys()]) this.kill(id);
+  }
+  /** Live session count — for observability / tests. */
+  activeSessionCount() {
+    return this.sessions.size;
+  }
+};
+
+export { PtyInteractiveBackend, YIELD_MAX_MS, YIELD_MIN_MS, clampYield };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pty-interactive-backend.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `PtyInteractiveBackend` — the LOCAL implementation of `@theokit/sdk`'s\n * `InteractiveBackend`, backed by `node-pty`. This is the terminal-surface\n * backend: it allocates a real pseudo-terminal so REPLs, `git rebase -i`, and\n * prompting commands can be driven to completion. Ported from the AgentBuilder\n * Codex clone (M11) into the ecosystem (M14) so any terminal agent injects it.\n *\n * `node-pty` is an OPTIONAL dependency of this package — the ONLY place in the\n * theokit ecosystem that touches it. Core / sdk-tools / cluster / desktop never\n * do. When the native module is unavailable (or a spawn fails), every method\n * throws the SDK's typed {@link InteractiveUnavailableError} so the caller falls\n * back to non-interactive exec.\n *\n * Safety (mirrors M11): graceful typed degradation; per-session write\n * serialization (concurrent writes never steal each other's output); idle TTL\n * reaper; process-GROUP kill so detached grandchildren die; a process-exit\n * reaper; tail-capped output (the live prompt, not the stale banner).\n */\nimport { randomUUID } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\n\nimport {\n  InteractiveBackend,\n  InteractiveUnavailableError,\n  NoSuchSessionError,\n  type StartInteractiveOptions,\n  type StartInteractiveResult,\n  type WriteStdinOptions,\n  type WriteStdinResult,\n} from \"@theokit/sdk/interactive\";\n\nconst nodeRequire = createRequire(import.meta.url);\n\nexport const YIELD_MIN_MS = 250;\nexport const YIELD_MAX_MS = 30_000;\nconst DEFAULT_YIELD_MS = 500;\nconst DEFAULT_TTL_MS = 300_000; // 5 min idle → reap\nconst DEFAULT_MAX_BYTES = 100_000;\n\n/** The minimal `node-pty` surface driven here (kept structural so the import stays lazy). */\ninterface PtyProcess {\n  readonly pid: number;\n  write(data: string): void;\n  kill(signal?: string): void;\n  onData(cb: (data: string) => void): void;\n  onExit(cb: (e: { exitCode: number }) => void): void;\n}\ninterface PtyModule {\n  spawn(file: string, args: string[], opts: Record<string, unknown>): PtyProcess;\n}\n\ninterface PtySession {\n  id: string;\n  pty: PtyProcess;\n  pending: string;\n  alive: boolean;\n  ttlTimer: ReturnType<typeof setTimeout>;\n  writeChain: Promise<unknown>;\n}\n\n/** Bound the yield window to [{@link YIELD_MIN_MS}, {@link YIELD_MAX_MS}]. */\nexport function clampYield(ms: number | undefined): number {\n  const v = ms ?? DEFAULT_YIELD_MS;\n  return Math.max(YIELD_MIN_MS, Math.min(YIELD_MAX_MS, v));\n}\n\n/** Keep the TAIL of output — the newest bytes carry the live prompt. */\nfunction capTail(buf: string, max: number): string {\n  return buf.length > max ? `…(truncated)\\n${buf.slice(-max)}` : buf;\n}\n\nexport class PtyInteractiveBackend extends InteractiveBackend {\n  private readonly sessions = new Map<string, PtySession>();\n  private ptyModule: PtyModule | null | undefined;\n  private exitReaperArmed = false;\n\n  /** Lazy, cached node-pty load — a failed native build must degrade, not crash at import time. */\n  private loadPty(): PtyModule | null {\n    if (this.ptyModule !== undefined) return this.ptyModule;\n    try {\n      this.ptyModule = nodeRequire(\"node-pty\") as PtyModule;\n    } catch {\n      this.ptyModule = null;\n    }\n    return this.ptyModule;\n  }\n\n  /** Whether the interactive (PTY) path is usable in this environment. */\n  available(): boolean {\n    return this.loadPty() !== null;\n  }\n\n  /** Reap orphaned PTYs when the host process exits. ONLY the `exit` event — installing SIGINT/SIGTERM\n   *  handlers would remove Node's default terminate-on-signal behavior. Armed once, lazily. */\n  private armExitReaper(): void {\n    if (this.exitReaperArmed) return;\n    this.exitReaperArmed = true;\n    process.on(\"exit\", () => this.killAll());\n  }\n\n  private async collect(session: PtySession, yieldMs: number, maxBytes: number): Promise<string> {\n    await new Promise((r) => setTimeout(r, clampYield(yieldMs)));\n    const out = session.pending;\n    session.pending = \"\";\n    return capTail(out, maxBytes);\n  }\n\n  private armTtl(session: PtySession, ttlMs: number): void {\n    clearTimeout(session.ttlTimer);\n    session.ttlTimer = setTimeout(() => this.kill(session.id), ttlMs);\n  }\n\n  async startInteractive(\n    command: string,\n    opts?: StartInteractiveOptions,\n  ): Promise<StartInteractiveResult> {\n    const pty = this.loadPty();\n    if (pty === null) {\n      throw new InteractiveUnavailableError(\n        \"interactive shell unavailable: node-pty native module failed to load; use non-interactive exec\",\n      );\n    }\n    this.armExitReaper();\n    const shell = process.env.SHELL ?? \"/bin/bash\";\n    const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;\n    const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;\n    // Validate cwd at the boundary: node-pty does NOT throw on a non-existent cwd (it spawns a broken\n    // session), so fail-fast to the typed fallback the caller expects.\n    const cwd = opts?.cwd ?? process.cwd();\n    if (!existsSync(cwd)) {\n      throw new InteractiveUnavailableError(`interactive shell unavailable: cwd does not exist: ${cwd}`);\n    }\n    let proc: PtyProcess;\n    try {\n      proc = pty.spawn(shell, [\"-c\", command], {\n        name: \"xterm-color\",\n        cols: opts?.cols ?? 80,\n        rows: opts?.rows ?? 24,\n        cwd,\n        env: process.env,\n      });\n    } catch (err) {\n      throw new InteractiveUnavailableError(\n        `interactive shell unavailable: failed to spawn a PTY (${err instanceof Error ? err.message : String(err)})`,\n      );\n    }\n    const id = `pty-${randomUUID()}`;\n    const session: PtySession = {\n      id,\n      pty: proc,\n      pending: \"\",\n      alive: true,\n      ttlTimer: setTimeout(() => this.kill(id), ttlMs),\n      writeChain: Promise.resolve(),\n    };\n    proc.onData((data) => {\n      session.pending = capTail(session.pending + data, maxBytes);\n    });\n    proc.onExit(() => {\n      session.alive = false;\n      clearTimeout(session.ttlTimer);\n      this.sessions.delete(id);\n    });\n    this.sessions.set(id, session);\n    const output = await this.collect(session, opts?.yieldMs ?? DEFAULT_YIELD_MS, maxBytes);\n    return { sessionId: id, output };\n  }\n\n  async writeStdin(\n    sessionId: string,\n    chars: string,\n    opts?: WriteStdinOptions,\n  ): Promise<WriteStdinResult> {\n    const session = this.sessions.get(sessionId);\n    if (session === undefined || !session.alive) throw new NoSuchSessionError(sessionId);\n    // Serialize per session: chain onto the previous write so two concurrent calls run strictly in\n    // order and each reads only its own output window (no stolen output).\n    const run = session.writeChain.then(async () => {\n      if (!session.alive) throw new NoSuchSessionError(sessionId);\n      this.armTtl(session, opts?.ttlMs ?? DEFAULT_TTL_MS);\n      if (chars.length > 0) session.pty.write(chars);\n      const output = await this.collect(\n        session,\n        opts?.yieldMs ?? DEFAULT_YIELD_MS,\n        opts?.maxBytes ?? DEFAULT_MAX_BYTES,\n      );\n      return { output, alive: session.alive };\n    });\n    session.writeChain = run.catch(() => undefined);\n    return run;\n  }\n\n  /** Kill a single session (idempotent). Kills the whole process GROUP so a detached grandchild dies too. */\n  kill(sessionId: string): void {\n    const session = this.sessions.get(sessionId);\n    if (session === undefined) return;\n    clearTimeout(session.ttlTimer);\n    session.alive = false;\n    this.sessions.delete(sessionId);\n    try {\n      process.kill(-session.pty.pid, \"SIGKILL\");\n    } catch {\n      try {\n        session.pty.kill();\n      } catch {\n        // already dead — nothing to do\n      }\n    }\n  }\n\n  /** Reap every session — used by the process-exit reaper; also callable on `/clear`. */\n  killAll(): void {\n    for (const id of [...this.sessions.keys()]) this.kill(id);\n  }\n\n  /** Live session count — for observability / tests. */\n  activeSessionCount(): number {\n    return this.sessions.size;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@theokit/sdk-pty",
+  "version": "0.1.0",
+  "description": "Local interactive-shell backend for @theokit/sdk — a node-pty implementation of InteractiveBackend. Opt-in, terminal-surface only; node-pty is optional so install never fails on a native build.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@theokit/sdk": ">=4.4.1"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@theokit/sdk": "workspace:*",
+    "node-pty": "^1.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}