@nathwn12/janua 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-31
+
+### Added
+
+- `janua`: a stdio MCP server exposing persistent interactive terminals. Five tools: `pty_spawn`,
+  `pty_write`, `pty_read`, `pty_kill`, `pty_list`. A PTY outlives a single command, so a program can
+  be talked to across several tool calls: prompts, REPLs, and dev servers that need a restart rather
+  than a relaunch.
+- Per-session output ring buffer with monotonic byte cursors: a read continues where the last one
+  stopped, and a cursor older than the 1 MiB window reports the bytes it lost in `dropped`.
+- `pty_read` blocks with `waitMs` instead of being polled, and strips ANSI escape sequences by
+  default, including ConPTY window titles that contain Windows paths.
+- Typed tool failures instead of exceptions across the MCP boundary: `invalid_args`,
+  `session_not_found`, `spawn_failed`, `pty_write_failed`, `too_many_sessions`.
+- Guards: `cwd` must exist, `command` must not be empty, a 5-10 word `description` is required per
+  session, and 16 concurrent sessions is the default cap.
+- Every session is killed on server exit, `SIGINT` and `SIGTERM`, and on stdin close.
+- Windows: taskkill-based tree termination, dead-pid guard before kill, and disposal of node-pty's
+  console worker after a child exits so the server (and its tests) can shut down cleanly.
+- `test/` covers spawn/read/list/kill, writing to a stdin-reading child, typed `session_not_found`,
+  cursor/`maxBytes` continuity, and an end-to-end MCP handshake over stdio.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nathan <137482711+nathwn12@users.noreply.github.com>
+
+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/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# janua
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A terminal you can talk to. `janua` is an MCP server that gives an agent persistent interactive
+terminals (PTYs): start a program, write to it, read what it answers, kill it when you are done.
+
+A command runner answers once and is gone. Half the programs an agent needs are not like that: a dev
+server you have to restart, an installer that stops on a prompt, a REPL where the second command
+depends on the first. `janua` keeps the process alive on the other end of a real pseudo-terminal, so
+the program behaves the way it does in a terminal you are sitting at - prompts appear, progress bars
+update, and typing works.
+
+## Install
+
+```powershell
+npx @nathwn12/janua
+```
+
+That is the whole install: no build step, no native compile (the PTY ships prebuilt binaries). Point
+your MCP client at it:
+
+```json
+{
+  "mcpServers": {
+    "janua": {
+      "command": "npx",
+      "args": ["-y", "@nathwn12/janua"]
+    }
+  }
+}
+```
+
+On Windows, if your client cannot launch `npx` directly, wrap it in the command shell:
+
+```json
+{
+  "mcpServers": {
+    "janua": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@nathwn12/janua"]
+    }
+  }
+}
+```
+
+## The five tools
+
+| Tool | What it does |
+| --- | --- |
+| `pty_spawn` | Start `command` with `args` in a new PTY. Takes an optional `cwd`, `env`, `cols`/`rows` (defaults 80x24), `title`, and a required 5-10 word `description`. Returns `{sessionId, pid, title}`. No shell string: command and args are passed as given, there is no `shell: true`. |
+| `pty_write` | Send `data` to a session. `newline` (default true) appends a carriage return, which is what a prompt is waiting for. Returns `{ok}`. |
+| `pty_read` | Read output from `cursor` onward, up to `maxBytes` (default 8000). `waitMs` waits up to 10 s for new output; `stripAnsi` (default true) removes colour and cursor-control sequences. Returns `{data, cursor, exited, exitCode, dropped}`. |
+| `pty_kill` | Terminate the program. Idempotent. `signal` defaults to `SIGTERM` and is honoured on POSIX; Windows terminates the process tree. Returns `{ok}`. |
+| `pty_list` | Every session with `sessionId`, `pid`, `title`, `command`, `exited`, `exitCode`, `bytes` and `createdAt`. |
+
+### Reading without duplicates
+
+`cursor` is a byte offset into the session's whole output stream, not an index into a window. Pass
+the cursor a read returns and the next read continues exactly where the last one stopped. Omit it to
+start at the oldest byte still buffered. The buffer keeps the last 1 MiB per session; if a read asks
+for a cursor that has since been discarded, the reply starts at the oldest retained byte and reports
+how many bytes were lost in `dropped`.
+
+`waitMs` makes a read block instead of polling: it returns as soon as new output arrives, or when
+the session exits, or at the deadline.
+
+### Errors
+
+Tool failures come back as an `isError` result carrying a typed code, never as a thrown exception:
+`invalid_args`, `session_not_found`, `spawn_failed`, `pty_write_failed`, `too_many_sessions`.
+
+## Limits and defaults
+
+- 16 concurrent sessions (`JANUA_MAX_SESSIONS` overrides it). Exited sessions are purged first when
+  the cap is reached; if none can be purged the spawn fails with `too_many_sessions`.
+- 1 MiB of retained output per session (`JANUA_MAX_BUFFER_BYTES` overrides it).
+- `cwd` must exist and be a directory, and `command` must not be empty: both are refused with
+  `invalid_args` before anything is spawned.
+- Every session is killed when the server exits, and on `SIGINT`/`SIGTERM`.
+
+## Windows notes
+
+- Terminals come from ConPTY, so programs see a real console: `cmd.exe`, PowerShell, `node`, Python
+  and anything that uses colour or prompts all work. A first read right after spawn usually contains
+  a screen-initialisation sequence; it is stripped by default.
+- There are no POSIX signals. `signal` is accepted and ignored; `pty_kill` terminates the process
+  tree instead.
+- A child that prints a window title sequence (`ESC ] 0 ; ... BEL`) will show it in the raw stream
+  when `stripAnsi: false`. With stripping on it is removed, including titles containing Windows paths.
+- `pty_write` appends `\r`, not `\n`, because that is what a console line discipline expects.
+- In ConPTY the exit event and the last chunk of output can arrive up to about a second after the
+  program dies. `pty_read` with `waitMs` covers that: `exited: true` and the `exitCode` are reported
+  on whichever read observes them.
+
+PTY engine: @lydell/node-pty (MIT)
+
+## Going deeper
+
+`docs/GUIDE.md` has three worked examples: restarting a dev server, answering an interactive prompt,
+and driving a REPL.

package/bin/janua.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// janua: a terminal you can talk to, over MCP stdio.
+//
+// stdout belongs to the JSON-RPC frames and nothing else; diagnostics go to
+// stderr. Every session is killed on transport close, SIGINT, SIGTERM and
+// normal exit, so no PTY outlives the server.
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from '../lib/server.js';
+
+const { server, manager } = createServer();
+
+let closing = false;
+function shutdown(code = 0) {
+  if (closing) return;
+  closing = true;
+  manager.killAll();
+  process.exit(code);
+}
+
+process.on('exit', () => manager.killAll());
+process.on('SIGINT', () => shutdown(0));
+process.on('SIGTERM', () => shutdown(0));
+// The client closing stdin is the normal end of a stdio MCP session: without
+// this the PTY handles would keep the process alive after the transport dies.
+process.stdin.on('end', () => shutdown(0));
+process.stdin.on('close', () => shutdown(0));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/docs/GUIDE.md

@@ -0,0 +1,134 @@
+# janua guide
+
+Three worked examples of the thing a command runner cannot do: keep a program alive and talk to it.
+Tool calls are shown as the arguments you pass and the result you get back; long outputs are
+abbreviated.
+
+---
+
+## 1. Restarting a dev server
+
+The first spawn starts the server. Later calls do not start a second one: they write `Ctrl+C` into
+the same session and start the command again inside the same shell, so the port is reused and the
+environment is identical.
+
+```jsonc
+// pty_spawn - a shell, so the session survives the server dying
+{
+  "command": "cmd.exe",
+  "args": ["/d", "/k"],
+  "cwd": "C:\\work\\site",
+  "title": "site-dev",
+  "description": "shell for the site dev server"
+}
+// -> {"sessionId":"6f1c...","pid":9032,"title":"site-dev"}
+```
+
+```jsonc
+// pty_write - start it
+{"sessionId":"6f1c...","data":"npm run dev"}
+// -> {"ok":true}
+
+// pty_read - wait for the first request log
+{"sessionId":"6f1c...","cursor":0,"waitMs":10000}
+// -> {"data":"\r\n> site@1.0.0 dev\r\n> vite\r\n\r\n  VITE v6.0.0  ready in 214 ms\r\n  ->  Local: http://localhost:5173/\r\n",
+//     "cursor":118,"exited":false,"exitCode":null}
+```
+
+Restart on the same session - `\u0003` is Ctrl+C, then the same command line:
+
+```jsonc
+{"sessionId":"6f1c...","data":"\u0003","newline":false}
+{"sessionId":"6f1c...","data":"npm run dev"}
+
+// pty_read from the last cursor shows only what happened since
+{"sessionId":"6f1c...","cursor":118,"waitMs":10000}
+// -> {"data":"^C\r\n> site@1.0.0 dev\r\n> vite\r\n\r\n  VITE v6.0.0  ready in 187 ms\r\n",
+//     "cursor":231,"exited":false,"exitCode":null}
+```
+
+Kill it when the work is done. `cmd.exe /k` keeps the shell, so killing the session ends the shell
+and the tree under it:
+
+```jsonc
+{"sessionId":"6f1c...","signal":"SIGTERM"}
+// -> {"ok":true}
+```
+
+**Why a shell here.** A session running `npm` directly dies when the server exits and cannot be
+restarted in place. A shell session outlives its child, which is what a restart is.
+
+---
+
+## 2. Answering an interactive prompt
+
+An installer asks a question and exits if nobody answers. `pty_read` shows the question; `pty_write`
+answers it. The newline default appends the carriage return the prompt is waiting for.
+
+```jsonc
+{"command":"npx","args":["-y","create-something@latest","my-app"],"cwd":"C:\\work","description":"scaffold a new project"}
+// -> {"sessionId":"b2a8...","pid":7744,"title":"npx"}
+
+{"sessionId":"b2a8...","cursor":0,"waitMs":5000}
+// -> {"data":"Need to install the following packages:\ncreate-something@1.4.0\nOk to proceed? (y) ",
+//     "cursor":84,"exited":false,"exitCode":null}
+
+{"sessionId":"b2a8...","data":"y"}          // -> {"ok":true}
+{"sessionId":"b2a8...","data":"","newline":true}  // bare Enter, when a default is offered
+{"sessionId":"b2a8...","cursor":84,"waitMs":10000}
+// -> {"data":"\r\n✔ Project created in C:\\work\\my-app\r\n","cursor":137,"exited":false,"exitCode":null}
+```
+
+**Reading the menu.** Options separated by `(y/n)` or `[1] [2]` are answered by one keystroke, but
+the program only sees it once Enter arrives - which is why `newline` defaults to true. For a
+keystroke that must arrive alone (arrow keys, a TUI), pass `"newline": false`.
+
+**If the answer was wrong,** the session is still alive: answer again rather than spawning another.
+Use `pty_kill` only when the program is stuck in a state no input can leave.
+
+---
+
+## 3. Driving a REPL
+
+A REPL keeps state between commands, which is exactly what a one-shot `node -e` cannot do. Keep the
+cursor moving so each read shows only the new result.
+
+```jsonc
+{"command":"node","args":["--interactive"],"cwd":"C:\\work\\scratch","title":"node-repl","description":"scratch REPL for quick checks"}
+// -> {"sessionId":"c91d...","pid":3312,"title":"node-repl"}
+
+{"sessionId":"c91d...","cursor":0,"waitMs":5000}
+// -> {"data":"> ","cursor":2,"exited":false,"exitCode":null}
+
+{"sessionId":"c91d...","data":"const xs = [1,2,3].map(n => n * 7)"}
+{"sessionId":"c91d...","cursor":2,"waitMs":5000}
+// -> {"data":"const xs = [1,2,3].map(n => n * 7)\r\nundefined\r\n> ","cursor":52,...}
+
+{"sessionId":"c91d...","data":"xs"}
+{"sessionId":"c91d...","cursor":52,"waitMs":5000}
+// -> {"data":"xs\r\n[ 7, 14, 21 ]\r\n> ","cursor":76,...}
+```
+
+Note that `xs` still exists in the second command: that is the point of a session. A multi-line
+construct (a `function`, an object literal, an `if` block) is entered one line at a time; the REPL
+prints `... ` until it is complete.
+
+End it with Ctrl+D (end of input) or kill the session:
+
+```jsonc
+{"sessionId":"c91d...","data":"\u0004","newline":false}
+{"sessionId":"c91d...","cursor":76,"waitMs":5000}
+// -> {"data":"","cursor":76,"exited":true,"exitCode":0}
+```
+
+---
+
+## Rules of thumb
+
+- One session per long-lived thing. Spawn once, talk many times, kill once.
+- Always pass the `cursor` a read returned. Reading from 0 again re-delivers everything still
+  buffered, which is useful for a full dump and wasteful for a diff.
+- `waitMs` beats sleeping between reads: it returns the moment output arrives.
+- Keep `description` meaningful (5-10 words). It is what makes a list of sessions readable later.
+- Kill what you started. A session lives until it exits or the server does.
+- 16 sessions is the default cap; `too_many_sessions` means kill one first.

package/lib/ansi.js

@@ -0,0 +1,15 @@
+// ANSI escape stripping.
+//
+// Two passes, because a Windows ConPTY emits both kinds and the naive
+// ansi-regex pattern cuts an OSC title short at the first backslash (a path
+// like C:\Users\...), leaving the rest of the title in the output:
+//   1. OSC: ESC ] ... BEL | ESC \ | 0x9C  (window titles, hyperlinks)
+//   2. every other escape: CSI, and single-character two-byte sequences.
+// Stripping happens per read, so a sequence split across two reads is left in
+// place until the rest of it arrives.
+const OSC_PATTERN = /(?:\u001B\]|\u009D)[\s\S]*?(?:\u0007|\u001B\\|\u009C)/g;
+const ESCAPE_PATTERN = /\u001B(?:\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+
+export function stripAnsi(text) {
+  return text.replace(OSC_PATTERN, '').replace(ESCAPE_PATTERN, '');
+}

package/lib/errors.js

@@ -0,0 +1,57 @@
+// Typed errors and their MCP tool-result shapes.
+//
+// Nothing in this package throws across the MCP boundary. A handler either
+// returns a success payload or one of these typed failures, and the server
+// wrapper turns every throw into one as well.
+
+export const ERROR_CODES = Object.freeze({
+  INVALID_ARGS: 'invalid_args',
+  SESSION_NOT_FOUND: 'session_not_found',
+  SPAWN_FAILED: 'spawn_failed',
+  PTY_WRITE_FAILED: 'pty_write_failed',
+  TOO_MANY_SESSIONS: 'too_many_sessions',
+  // Anything unexpected. Never used for a condition the codes above cover.
+  INTERNAL: 'internal_error',
+});
+
+export class JanuaError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'JanuaError';
+    this.code = code;
+  }
+}
+
+export function invalidArgs(message) {
+  return new JanuaError(ERROR_CODES.INVALID_ARGS, message);
+}
+
+export function sessionNotFound(sessionId) {
+  return new JanuaError(ERROR_CODES.SESSION_NOT_FOUND, `no session with id "${sessionId}"`);
+}
+
+export function describeCause(err) {
+  if (err && typeof err.message === 'string' && err.message) return err.message;
+  return String(err);
+}
+
+/** Success result: the payload as JSON text for the model, and structured for clients. */
+export function toolSuccess(payload) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload) }],
+    structuredContent: payload,
+  };
+}
+
+/** Failure result: a typed code, a readable message, and isError so clients surface it. */
+export function toolFailure(err) {
+  const code = err instanceof JanuaError ? err.code : ERROR_CODES.INTERNAL;
+  const message = err instanceof JanuaError
+    ? err.message
+    : `unexpected failure: ${describeCause(err)}`;
+  return {
+    isError: true,
+    content: [{ type: 'text', text: `${code}: ${message}` }],
+    structuredContent: { error: { code, message } },
+  };
+}

package/lib/ring.js

@@ -0,0 +1,82 @@
+// Per-session output ring buffer.
+//
+// Offsets ("cursors") are monotonic byte offsets into the session's whole
+// output stream, not indexes into the retained window: offset 0 is the first
+// byte the child ever wrote, and it stays comparable forever. When the cap is
+// exceeded the oldest bytes are dropped and the window's base offset advances,
+// so a caller holding an old cursor is told exactly how many bytes it missed.
+
+export class OutputRing {
+  #chunks = [];
+  #cap;
+
+  constructor(capBytes) {
+    this.#cap = capBytes;
+    this.base = 0; // absolute offset of the first retained byte
+    this.total = 0; // absolute offset one past the last byte written
+  }
+
+  get cap() {
+    return this.#cap;
+  }
+
+  /** Bytes currently retained (<= cap). */
+  get available() {
+    return this.total - this.base;
+  }
+
+  append(text) {
+    if (!text) return;
+    const chunk = Buffer.from(text, 'utf8');
+    this.#chunks.push(chunk);
+    this.total += chunk.length;
+
+    let over = this.total - this.base - this.#cap;
+    while (over > 0 && this.#chunks.length > 0) {
+      const head = this.#chunks[0];
+      if (head.length <= over) {
+        this.#chunks.shift();
+        this.base += head.length;
+        over -= head.length;
+        continue;
+      }
+      this.#chunks[0] = head.subarray(over);
+      this.base += over;
+      over = 0;
+    }
+  }
+
+  /**
+   * Read up to `maxBytes` starting at absolute offset `cursor`.
+   * Returns the bytes clamped into the retained window, the absolute offset
+   * they end at, and how many bytes between the requested cursor and the
+   * retained window were dropped before the caller could read them.
+   */
+  read(cursor, maxBytes) {
+    const wanted = Number.isFinite(cursor) ? Math.max(0, Math.floor(cursor)) : this.base;
+    const clamped = Math.min(wanted, this.total);
+    const from = Math.max(clamped, this.base);
+    const dropped = from - clamped;
+    const end = Math.min(this.total, from + Math.max(0, Math.floor(maxBytes)));
+    return { data: this.#slice(from, end), dropped, end };
+  }
+
+  #slice(start, end) {
+    if (end <= start) return Buffer.alloc(0);
+    const out = Buffer.allocUnsafe(end - start);
+    let offset = this.base;
+    let written = 0;
+    for (const chunk of this.#chunks) {
+      const chunkStart = offset;
+      const chunkEnd = offset + chunk.length;
+      offset = chunkEnd;
+      if (chunkEnd <= start) continue;
+      if (chunkStart >= end) break;
+      const from = Math.max(start, chunkStart) - chunkStart;
+      const to = Math.min(end, chunkEnd) - chunkStart;
+      chunk.copy(out, written, from, to);
+      written += to - from;
+    }
+    return out.subarray(0, written);
+  }
+}

package/lib/server.js

@@ -0,0 +1,133 @@
+// MCP server surface: exactly five tools.
+//
+// pty_spawn / pty_write / pty_read / pty_kill / pty_list.
+// Every handler funnels through wrap(), so a throw becomes a typed tool error
+// and never escapes into the JSON-RPC transport.
+
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { SessionManager } from './sessions.js';
+import { toolFailure, toolSuccess } from './errors.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+const INSTRUCTIONS = [
+  'janua gives you persistent interactive terminals. Use pty_spawn for programs you need to talk to over time',
+  '(dev servers, REPLs, anything that prompts), not for one-shot commands. Keep the returned sessionId, read with',
+  'pty_read using the cursor it returns so output is never duplicated, write with pty_write, and pty_kill when done.',
+].join(' ');
+
+/** Wrap a handler so success is a payload and every throw is a typed tool error. */
+function wrap(handler) {
+  return async (args) => {
+    try {
+      return toolSuccess(await handler(args));
+    } catch (err) {
+      return toolFailure(err);
+    }
+  };
+}
+
+export function createServer(options = {}) {
+  const manager = options.manager ?? new SessionManager();
+  const server = new McpServer(
+    { name: 'janua', version },
+    { instructions: INSTRUCTIONS },
+  );
+
+  server.registerTool(
+    'pty_spawn',
+    {
+      title: 'Spawn interactive terminal',
+      description:
+        'Start a program in a persistent pseudo-terminal and return {sessionId, pid, title}. '
+        + 'The program keeps running until pty_kill or its own exit; nothing is run through a shell, '
+        + 'so command and args are passed exactly as given. Use this for anything you need to talk to '
+        + '(dev servers, REPLs, installers that prompt), not for commands whose output you want once.',
+      inputSchema: {
+        command: z.string().describe('Executable to run: a name resolved on PATH, or an absolute path. No shell string.'),
+        args: z.array(z.string()).optional().describe('Arguments for command, one array entry each.'),
+        cwd: z.string().optional().describe('Working directory for the program. Must exist. Defaults to the server process cwd.'),
+        env: z.record(z.string(), z.string()).optional().describe('Extra environment variables, merged over the server environment.'),
+        cols: z.number().int().min(1).max(1000).optional().describe('Terminal columns (default 80).'),
+        rows: z.number().int().min(1).max(1000).optional().describe('Terminal rows (default 24).'),
+        title: z.string().optional().describe('Short label for this session, shown by pty_list. Defaults to the command name.'),
+        description: z.string().describe('5-10 words saying what this session is for, so a later read makes sense on its own.'),
+      },
+    },
+    wrap(async (args) => manager.spawn(args)),
+  );
+
+  server.registerTool(
+    'pty_write',
+    {
+      title: 'Write to terminal',
+      description:
+        'Send keystrokes to a running session. newline (default true) appends a carriage return, which is what '
+        + 'a shell or prompt is waiting for. Output produced in response is not returned here: read it with pty_read.',
+      inputSchema: {
+        sessionId: z.string().describe('Session id returned by pty_spawn.'),
+        data: z.string().describe('Text to send. Escape sequences such as \\u0003 (Ctrl+C) are sent literally.'),
+        newline: z.boolean().optional().describe('Append a carriage return after data (default true).'),
+      },
+    },
+    wrap(async ({ sessionId, data, newline }) => manager.write(sessionId, data, newline ?? true)),
+  );
+
+  server.registerTool(
+    'pty_read',
+    {
+      title: 'Read terminal output',
+      description:
+        'Read output from a session, starting at cursor, and return {data, cursor, exited, exitCode, dropped}. '
+        + 'Pass the cursor from the previous read to get only new output; omit it to read from the oldest byte '
+        + 'still buffered. dropped > 0 means the ring buffer discarded that many bytes before this read. '
+        + 'waitMs waits for the session to produce new output (or exit) before returning.',
+      inputSchema: {
+        sessionId: z.string().describe('Session id returned by pty_spawn.'),
+        cursor: z.number().int().min(0).optional().describe('Byte offset from the previous read. Omit to read from the start of the buffer.'),
+        maxBytes: z.number().int().min(1).max(1048576).optional().describe('Maximum bytes to return (default 8000).'),
+        waitMs: z.number().int().min(0).max(10000).optional().describe('Wait up to this many milliseconds for new output (default 0).'),
+        stripAnsi: z.boolean().optional().describe('Remove ANSI escape sequences from data (default true). The cursor still counts raw bytes.'),
+      },
+    },
+    wrap(async ({ sessionId, cursor, maxBytes, waitMs, stripAnsi }) =>
+      manager.read(sessionId, {
+        cursor,
+        maxBytes: maxBytes ?? 8000,
+        waitMs: waitMs ?? 0,
+        stripAnsi: stripAnsi ?? true,
+      })),
+  );
+
+  server.registerTool(
+    'pty_kill',
+    {
+      title: 'Kill terminal',
+      description:
+        'Terminate a session\'s program. Idempotent: killing an already-exited session returns ok. '
+        + 'The session stays listed with its exit code so its last output can still be read.',
+      inputSchema: {
+        sessionId: z.string().describe('Session id returned by pty_spawn.'),
+        signal: z.string().optional().describe('POSIX signal name (default SIGTERM). Ignored on Windows, where the process tree is terminated.'),
+      },
+    },
+    wrap(async ({ sessionId, signal }) => manager.kill(sessionId, signal ?? 'SIGTERM')),
+  );
+
+  server.registerTool(
+    'pty_list',
+    {
+      title: 'List terminals',
+      description:
+        'List every session this server knows about, newest last: sessionId, pid, title, command, exited, '
+        + 'exitCode, bytes emitted, and createdAt. Use it to recover a session id you lost.',
+      inputSchema: {},
+    },
+    wrap(async () => ({ sessions: manager.list() })),
+  );
+
+  return { server, manager };
+}

package/lib/sessions.js

@@ -0,0 +1,310 @@
+// Session registry: one PTY per session id, with a bounded output ring.
+//
+// Deliberate properties:
+//   - a session outlives its child: after exit it stays listed and readable so
+//     the exit code and the tail of its output can still be collected;
+//   - the cap counts every known session, but exited sessions are purged first,
+//     so a long-lived server is not wedged by history;
+//   - nothing here throws a raw node-pty error across the boundary: spawn and
+//     write failures become typed JanuaError codes.
+
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { spawn as spawnPty } from '@lydell/node-pty';
+import { OutputRing } from './ring.js';
+import { stripAnsi } from './ansi.js';
+import {
+  ERROR_CODES,
+  JanuaError,
+  describeCause,
+  invalidArgs,
+  sessionNotFound,
+} from './errors.js';
+
+export const DEFAULT_COLS = 80;
+export const DEFAULT_ROWS = 24;
+export const DEFAULT_MAX_SESSIONS = 16;
+export const DEFAULT_MAX_BUFFER_BYTES = 1024 * 1024;
+
+function envInt(name, fallback) {
+  const raw = Number.parseInt(process.env[name] ?? '', 10);
+  return Number.isInteger(raw) && raw > 0 ? raw : fallback;
+}
+
+function assertDescription(description) {
+  const words = typeof description === 'string'
+    ? description.trim().split(/\s+/).filter(Boolean)
+    : [];
+  if (words.length < 5 || words.length > 10) {
+    throw invalidArgs(
+      `description must be 5-10 words saying what the session is for, got ${words.length}`,
+    );
+  }
+  return description.trim();
+}
+
+function resolveCwd(cwd) {
+  if (cwd === undefined || cwd === null || cwd === '') return process.cwd();
+  if (typeof cwd !== 'string') throw invalidArgs('cwd must be a string');
+  let stats;
+  try {
+    stats = statSync(cwd);
+  } catch {
+    throw invalidArgs(`cwd does not exist: ${cwd}`);
+  }
+  if (!stats.isDirectory()) throw invalidArgs(`cwd is not a directory: ${cwd}`);
+  return cwd;
+}
+
+// node-pty keeps a worker thread draining the ConPTY console socket after the
+// child exits, which pins the Node event loop open. Disposing it (a private
+// field, guarded) is what lets a short-lived process or a test runner exit
+// once its sessions are gone. Failure here is not fatal: the session is already
+// finished, so it is swallowed.
+function releasePtyInternals(term) {
+  const worker = term?._agent?._conoutSocketWorker;
+  if (worker && typeof worker.dispose === 'function') {
+    try {
+      worker.dispose();
+    } catch {
+      // already gone
+    }
+  }
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function terminate(term, signal) {
+  // node-pty throws "Signals not supported on windows." when a signal argument
+  // is passed, so Windows is always killed the only way it supports.
+  if (process.platform === 'win32') {
+    // Killing a child that already died makes node-pty fork its console-list
+    // helper, which fails to attach and prints noise on stderr while holding a
+    // 5 s timer. The native exit callback still arrives on its own, so a dead
+    // pid is left alone.
+    if (!isProcessAlive(term.pid)) return;
+    // taskkill /T ends the whole tree in one step; node-pty's own Windows kill
+    // enumerates console processes through that helper and, from a process with
+    // piped stdio (every MCP server), waits out its 5 s timeout first. The PTY
+    // exit event still fires from the native callback, so node-pty's kill stays
+    // as a fallback for anything taskkill refuses.
+    const result = spawnSync('taskkill', ['/pid', String(term.pid), '/T', '/F'], { encoding: 'utf8' });
+    if (result.status === 0) return;
+    // A pid that is already gone still looks alive to process.kill(pid, 0)
+    // while ConPTY holds its handle. That is the one failure that must not fall
+    // through: node-pty's own kill would fork its helper and print an
+    // AttachConsole error for a child whose exit event is already on its way.
+    const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.toLowerCase();
+    if (output.includes('not found') || output.includes('not running')) return;
+    term.kill();
+    return;
+  }
+  term.kill(signal ?? 'SIGTERM');
+}
+
+function waitForChange(session, ms) {
+  return new Promise((resolve) => {
+    const done = () => {
+      session.waiters.delete(done);
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(done, Math.max(0, ms));
+    session.waiters.add(done);
+  });
+}
+
+export class SessionManager {
+  #sessions = new Map();
+  #maxSessions;
+  #maxBufferBytes;
+
+  constructor(options = {}) {
+    this.#maxSessions = options.maxSessions ?? envInt('JANUA_MAX_SESSIONS', DEFAULT_MAX_SESSIONS);
+    this.#maxBufferBytes = options.maxBufferBytes
+      ?? envInt('JANUA_MAX_BUFFER_BYTES', DEFAULT_MAX_BUFFER_BYTES);
+  }
+
+  get maxSessions() {
+    return this.#maxSessions;
+  }
+
+  get maxBufferBytes() {
+    return this.#maxBufferBytes;
+  }
+
+  spawn(input = {}) {
+    const command = typeof input.command === 'string' ? input.command.trim() : '';
+    if (!command) throw invalidArgs('command must be a non-empty string');
+    if (input.args !== undefined && !Array.isArray(input.args)) {
+      throw invalidArgs('args must be an array of strings');
+    }
+    const args = (input.args ?? []).map((arg) => String(arg));
+    const description = assertDescription(input.description);
+    const cwd = resolveCwd(input.cwd);
+    const cols = input.cols ?? DEFAULT_COLS;
+    const rows = input.rows ?? DEFAULT_ROWS;
+
+    this.#purgeExited();
+    if (this.#sessions.size >= this.#maxSessions) {
+      throw new JanuaError(
+        ERROR_CODES.TOO_MANY_SESSIONS,
+        `session limit reached (${this.#maxSessions}); kill a session with pty_kill before spawning another`,
+      );
+    }
+
+    const title = (typeof input.title === 'string' && input.title.trim()) || basename(command) || command;
+    const env = { ...process.env, ...(input.env ?? {}) };
+    const sessionId = randomUUID();
+
+    let term;
+    try {
+      term = spawnPty(command, args, { cols, rows, cwd, env });
+    } catch (err) {
+      throw new JanuaError(
+        ERROR_CODES.SPAWN_FAILED,
+        `could not start ${command}: ${describeCause(err)}`,
+      );
+    }
+
+    const session = {
+      sessionId,
+      term,
+      pid: term.pid,
+      title,
+      command,
+      args,
+      description,
+      cwd,
+      cols,
+      rows,
+      createdAt: new Date().toISOString(),
+      exited: false,
+      exitCode: null,
+      ring: new OutputRing(this.#maxBufferBytes),
+      waiters: new Set(),
+    };
+
+    term.onData((chunk) => {
+      session.ring.append(chunk);
+      this.#notify(session);
+    });
+    term.onExit(({ exitCode }) => {
+      session.exited = true;
+      session.exitCode = typeof exitCode === 'number' ? exitCode : null;
+      releasePtyInternals(term);
+      this.#notify(session);
+    });
+
+    this.#sessions.set(sessionId, session);
+    return { sessionId, pid: session.pid, title };
+  }
+
+  write(sessionId, data, newline = true) {
+    const session = this.#get(sessionId);
+    if (typeof data !== 'string') throw invalidArgs('data must be a string');
+    if (session.exited) {
+      throw new JanuaError(
+        ERROR_CODES.PTY_WRITE_FAILED,
+        `session ${sessionId} has exited (exit code ${session.exitCode}); nothing is listening`,
+      );
+    }
+    try {
+      session.term.write(newline ? `${data}\r` : data);
+    } catch (err) {
+      throw new JanuaError(
+        ERROR_CODES.PTY_WRITE_FAILED,
+        `write to session ${sessionId} failed: ${describeCause(err)}`,
+      );
+    }
+    return { ok: true };
+  }
+
+  async read(sessionId, options = {}) {
+    const session = this.#get(sessionId);
+    const maxBytes = options.maxBytes ?? 8000;
+    const waitMs = Math.min(Math.max(0, options.waitMs ?? 0), 10000);
+    const requested = Number.isInteger(options.cursor) ? options.cursor : session.ring.base;
+    if (requested < 0) throw invalidArgs('cursor must be a non-negative byte offset');
+
+    const deadline = Date.now() + waitMs;
+    while (session.ring.total <= requested && !session.exited && Date.now() < deadline) {
+      await waitForChange(session, deadline - Date.now());
+    }
+
+    const slice = session.ring.read(requested, maxBytes);
+    const text = slice.data.toString('utf8');
+    return {
+      data: options.stripAnsi === false ? text : stripAnsi(text),
+      cursor: slice.end,
+      exited: session.exited,
+      exitCode: session.exitCode,
+      dropped: slice.dropped,
+    };
+  }
+
+  kill(sessionId, signal = 'SIGTERM') {
+    const session = this.#get(sessionId);
+    if (session.exited) return { ok: true };
+    try {
+      terminate(session.term, signal);
+    } catch (err) {
+      throw new JanuaError(
+        ERROR_CODES.INTERNAL,
+        `kill of session ${sessionId} failed: ${describeCause(err)}`,
+      );
+    }
+    return { ok: true };
+  }
+
+  list() {
+    return [...this.#sessions.values()].map((session) => ({
+      sessionId: session.sessionId,
+      pid: session.pid,
+      title: session.title,
+      command: session.command,
+      exited: session.exited,
+      exitCode: session.exitCode,
+      bytes: session.ring.total,
+      createdAt: session.createdAt,
+    }));
+  }
+
+  killAll() {
+    for (const session of this.#sessions.values()) {
+      if (session.exited) continue;
+      try {
+        terminate(session.term);
+      } catch {
+        // shutting down: a session that refuses to die must not block the rest
+      }
+    }
+  }
+
+  #get(sessionId) {
+    const session = this.#sessions.get(sessionId);
+    if (!session) throw sessionNotFound(sessionId);
+    return session;
+  }
+
+  #notify(session) {
+    for (const waiter of [...session.waiters]) waiter();
+  }
+
+  #purgeExited() {
+    if (this.#sessions.size < this.#maxSessions) return;
+    for (const [id, session] of this.#sessions) {
+      if (session.exited) this.#sessions.delete(id);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@nathwn12/janua",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A stdio MCP server that gives an agent persistent interactive terminals: spawn a program in a real PTY, talk to it, read what it answers.",
+  "license": "MIT",
+  "author": "nathwn12",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nathwn12/oc-collections.git",
+    "directory": "packages/janua"
+  },
+  "engines": {
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
+  },
+  "type": "module",
+  "bin": {
+    "janua": "bin/janua.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "check": "node --check bin/janua.js && node --check lib/ansi.js && node --check lib/errors.js && node --check lib/ring.js && node --check lib/server.js && node --check lib/sessions.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "docs/GUIDE.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "mcp",
+    "pty",
+    "terminal",
+    "interactive",
+    "stdio",
+    "agent"
+  ],
+  "dependencies": {
+    "@lydell/node-pty": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  }
+}