@nathwn12/janua 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-11-01
+
+### Added
+
+- `pty_read` takes `match`, a regular expression it waits for, and returns `matched`: the read returns
+  once the text from the cursor matches, or reports `matched: false` when `waitMs` runs out or the
+  session exits, so a non-zero `waitMs` is what makes it useful.
+- `pty_list` is paged with `limit`/`offset` and returns `{sessions, total, nextOffset}`, so a session
+  list longer than one page is still walkable and a lost session id is recoverable.
+- Every tool declares MCP `annotations` (read-only, mutating, destructive) and an `outputSchema`, so a
+  client can validate a result and judge a call before making it.
+
+### Changed
+
+- Windows: `pty_spawn` resolves a bare `command` through `PATH` x `PATHEXT` and runs a `.cmd`/`.bat`
+  shim (`npm`, `npx`, `pnpm`, `yarn`, `tsc`) through `cmd /c`, because `CreateProcess` consults
+  neither.
+- `pty_read` waits for visible text instead of returning an escape-only chunk: the cursor and title
+  sequences ConPTY emits ahead of any output no longer end a read early.
+- Migrated to MCP TypeScript SDK v2 (`@modelcontextprotocol/server` 2.4.0).
+
 ## [0.1.0] - 2026-10-31
 
 ### Added

package/README.md

@@ -46,11 +46,11 @@ On Windows, if your client cannot launch `npx` directly, wrap it in the command
 
 | 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_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`. On Windows a bare name is resolved through `PATH` x `PATHEXT` and a batch shim runs through `cmd /c` (see Windows notes). |
 | `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_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; `match` (a regex of at most 200 characters) makes the read wait until the text from `cursor` matches it. Returns `{data, cursor, exited, exitCode, dropped, matched}`. |
 | `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`. |
+| `pty_list` | Sessions newest last, one page at a time: `limit` (1-200, default 50) and `offset` (default 0). Returns `{sessions, total, nextOffset}`, where `total` counts every session known and `nextOffset` is null on the last page. Each session carries `sessionId`, `pid`, `title`, `command`, `exited`, `exitCode`, `bytes` and `createdAt`. |
 
 ### Reading without duplicates
 
@@ -61,12 +61,21 @@ for a cursor that has since been discarded, the reply starts at the oldest retai
 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.
+the session exits, or at the deadline. A ConPTY opens with escape-only chunks (mode set, focus
+reporting), so a stripped read that finds nothing visible keeps waiting from the same cursor for the
+text behind it; `stripAnsi: false` returns those first bytes as they arrive.
+
+`match` turns that same wait into a wait for a prompt: the read returns once the text from `cursor`
+matches the pattern, or the session exits, or `waitMs` runs out, and reports `matched: false` on
+timeout while still returning whatever arrived — so give it a non-zero `waitMs`.
 
 ### 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`.
+Every tool also declares its success shape as an output schema, so a client validates
+`structuredContent`; a failure carries its typed code in the text content only, because a payload
+that contradicted the declared shape would be rejected by a validating client.
 
 ## Limits and defaults
 
@@ -79,6 +88,20 @@ Tool failures come back as an `isError` result carrying a typed code, never as a
 
 ## Windows notes
 
+- **Command names are resolved the way a shell resolves them.** `CreateProcess` does not consult
+  `PATHEXT`, so a bare `npm`, `npx`, `pnpm`, `yarn` or `tsc` - all of them `.cmd` batch shims -
+  used to fail with "Cannot create process, error code: 2". A bare name is now looked up against
+  `PATH` x `PATHEXT` (`.COM;.EXE;.BAT;.CMD` by default) and the first match wins. An `.exe`/`.com`
+  runs directly by its absolute path; a `.cmd`/`.bat` runs through `cmd /d /s /c`, because batch
+  files cannot be executed by `CreateProcess` at all. Nothing is run through a shell on POSIX, and
+  a name that contains a path separator is never resolved through `PATH`.
+- **Arguments are quoted for that `cmd /c` line.** An argument holding a space, a tab, a quote or a
+  cmd metacharacter is wrapped in `"`, and an embedded `"` is doubled, so
+  `['hello world', 'say "hi" now']` arrives as two arguments with their spaces and quotes intact.
+  Two cmd behaviours cannot be escaped from outside: `%NAME%` inside an argument is expanded by
+  cmd, and `^` is consumed even inside quotes - an argument containing `^` through a batch shim is
+  refused with `invalid_args` rather than silently mangled. Drive either through a `cmd.exe`
+  session instead.
 - 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.

package/bin/janua.js

@@ -5,7 +5,7 @@
 // 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 { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { createServer } from '../lib/server.js';
 
 const { server, manager } = createServer();

package/docs/GUIDE.md

@@ -58,6 +58,12 @@ and the tree under it:
 **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.
 
+**Running `npm` without a shell.** `pty_spawn` with `"command": "npm"` works too, for a one-shot
+command rather than a server you restart: on Windows a bare name is resolved through `PATH` x
+`PATHEXT`, and the `npm.cmd` batch shim it finds is started through `cmd /d /s /c`. The arguments
+are quoted for that line, so `{"command":"npm","args":["run","build","--","--outDir","my dir"]}`
+arrives as five arguments with the space intact.
+
 ---
 
 ## 2. Answering an interactive prompt
@@ -69,6 +75,9 @@ answers it. The newline default appends the carriage return the prompt is waitin
 {"command":"npx","args":["-y","create-something@latest","my-app"],"cwd":"C:\\work","description":"scaffold a new project"}
 // -> {"sessionId":"b2a8...","pid":7744,"title":"npx"}
 
+// On Windows npx is a .cmd shim: janua resolves it through PATH x PATHEXT and runs it through
+// cmd /d /s /c, so the spawn above works without wrapping it in a shell yourself.
+
 {"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}

package/lib/errors.js

@@ -43,7 +43,13 @@ export function toolSuccess(payload) {
   };
 }
 
-/** Failure result: a typed code, a readable message, and isError so clients surface it. */
+/** Failure result: a typed code, a readable message, and isError so clients surface it.
+ *
+ * Deliberately no structuredContent: a tool that declares an outputSchema has
+ * its structuredContent validated against it even when isError is set, so an
+ * {error} envelope there would turn a typed tool failure into a thrown
+ * protocol error. The code stays in the text payload, which is never validated.
+ */
 export function toolFailure(err) {
   const code = err instanceof JanuaError ? err.code : ERROR_CODES.INTERNAL;
   const message = err instanceof JanuaError
@@ -52,6 +58,5 @@ export function toolFailure(err) {
   return {
     isError: true,
     content: [{ type: 'text', text: `${code}: ${message}` }],
-    structuredContent: { error: { code, message } },
   };
 }

package/lib/server.js

@@ -5,7 +5,7 @@
 // and never escapes into the JSON-RPC transport.
 
 import { createRequire } from 'node:module';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { SessionManager } from './sessions.js';
 import { toolFailure, toolSuccess } from './errors.js';
@@ -30,6 +30,47 @@ function wrap(handler) {
   };
 }
 
+// Hints say what a tool does to the world, so a client can decide what to
+// auto-approve: none of these reach the network, only pty_kill destroys state,
+// and only pty_read can be repeated for the same answer.
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const MUTATING = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
+
+// Output schemas mirror the payloads exactly, so structuredContent is declared
+// rather than merely sent and clients can rely on the fields. v2 wants a schema
+// object here, not a raw shape: a bare { field: z.string() } record is the
+// deprecated form and is only auto-wrapped for inputSchema.
+const SPAWN_OUTPUT = z.object({
+  sessionId: z.string().describe('Session id to pass to the other tools.'),
+  pid: z.number().describe('Process id of the program in the terminal.'),
+  title: z.string().describe('Label shown by pty_list.'),
+});
+const OK_OUTPUT = z.object({ ok: z.boolean().describe('True when the call did what it says.') });
+const READ_OUTPUT = z.object({
+  data: z.string().describe('Output from cursor onward.'),
+  cursor: z.number().describe('Byte offset to pass to the next read.'),
+  exited: z.boolean().describe('Whether the program has exited.'),
+  exitCode: z.number().nullable().describe('Exit code once exited, otherwise null.'),
+  dropped: z.number().describe('Bytes the buffer discarded before this read.'),
+  matched: z.boolean().describe('True when match was given and the text matched, or when no match was given.'),
+});
+const SESSION_SHAPE = {
+  sessionId: z.string(),
+  pid: z.number(),
+  title: z.string(),
+  command: z.string(),
+  exited: z.boolean(),
+  exitCode: z.number().nullable(),
+  bytes: z.number(),
+  createdAt: z.string(),
+};
+const LIST_OUTPUT = z.object({
+  sessions: z.array(z.object(SESSION_SHAPE)).describe('This page, newest last.'),
+  total: z.number().describe('Sessions known in total, not just this page.'),
+  nextOffset: z.number().nullable().describe('Offset of the next page, or null on the last one.'),
+});
+
 export function createServer(options = {}) {
   const manager = options.manager ?? new SessionManager();
   const server = new McpServer(
@@ -44,9 +85,11 @@ export function createServer(options = {}) {
       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 '
+        + 'so command and args are passed exactly as given. On Windows a bare name is resolved through '
+        + 'PATH and PATHEXT, and a .cmd/.bat shim (npm, npx, pnpm, yarn, tsc) runs through cmd /c with its '
+        + 'arguments quoted. Use this for anything you need to talk to '
         + '(dev servers, REPLs, installers that prompt), not for commands whose output you want once.',
-      inputSchema: {
+      inputSchema: z.object({
         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.'),
@@ -55,7 +98,9 @@ export function createServer(options = {}) {
         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.'),
-      },
+      }),
+      outputSchema: SPAWN_OUTPUT,
+      annotations: MUTATING,
     },
     wrap(async (args) => manager.spawn(args)),
   );
@@ -67,11 +112,13 @@ export function createServer(options = {}) {
       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: {
+      inputSchema: z.object({
         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).'),
-      },
+      }),
+      outputSchema: OK_OUTPUT,
+      annotations: MUTATING,
     },
     wrap(async ({ sessionId, data, newline }) => manager.write(sessionId, data, newline ?? true)),
   );
@@ -81,24 +128,32 @@ export function createServer(options = {}) {
     {
       title: 'Read terminal output',
       description:
-        'Read output from a session, starting at cursor, and return {data, cursor, exited, exitCode, dropped}. '
+        'Read output from a session, starting at cursor, and return {data, cursor, exited, exitCode, dropped, matched}. '
         + '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: {
+        + 'waitMs waits for the session to produce output (or exit) before returning; with stripAnsi '
+        + 'a chunk holding only escape sequences does not count, so the read keeps waiting for visible text. '
+        + 'match is a regular expression that makes the read wait until the text from cursor matches it, or the '
+        + 'session exits, or waitMs runs out, then reports matched: false on timeout — so a non-zero waitMs is what '
+        + 'makes match useful.',
+      inputSchema: z.object({
         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.'),
-      },
+        match: z.string().optional().describe('Regular expression (at most 200 characters) the text from cursor must match before the read returns; with stripAnsi false it matches the raw text.'),
+      }),
+      outputSchema: READ_OUTPUT,
+      annotations: READ_ONLY,
     },
-    wrap(async ({ sessionId, cursor, maxBytes, waitMs, stripAnsi }) =>
+    wrap(async ({ sessionId, cursor, maxBytes, waitMs, stripAnsi, match }) =>
       manager.read(sessionId, {
         cursor,
         maxBytes: maxBytes ?? 8000,
         waitMs: waitMs ?? 0,
         stripAnsi: stripAnsi ?? true,
+        match,
       })),
   );
 
@@ -109,10 +164,12 @@ export function createServer(options = {}) {
       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: {
+      inputSchema: z.object({
         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.'),
-      },
+      }),
+      outputSchema: OK_OUTPUT,
+      annotations: DESTRUCTIVE,
     },
     wrap(async ({ sessionId, signal }) => manager.kill(sessionId, signal ?? 'SIGTERM')),
   );
@@ -122,11 +179,17 @@ export function createServer(options = {}) {
     {
       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: {},
+        'List sessions this server knows about, newest last, one page at a time: sessionId, pid, title, command, '
+        + 'exited, exitCode, bytes emitted, and createdAt. Returns {sessions, total, nextOffset}: total counts every '
+        + 'session known, and nextOffset is null on the last page. Use it to recover a session id you lost.',
+      inputSchema: z.object({
+        limit: z.number().int().min(1).max(200).optional().describe('Sessions to return (default 50, max 200).'),
+        offset: z.number().int().min(0).optional().describe('Sessions to skip from the oldest (default 0).'),
+      }),
+      outputSchema: LIST_OUTPUT,
+      annotations: READ_ONLY,
     },
-    wrap(async () => ({ sessions: manager.list() })),
+    wrap(async ({ limit, offset }) => manager.list({ limit, offset })),
   );
 
   return { server, manager };

package/lib/sessions.js

@@ -11,7 +11,7 @@
 import { randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { statSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, extname, join } from 'node:path';
 import { spawn as spawnPty } from '@lydell/node-pty';
 import { OutputRing } from './ring.js';
 import { stripAnsi } from './ansi.js';
@@ -27,12 +27,124 @@ export const DEFAULT_COLS = 80;
 export const DEFAULT_ROWS = 24;
 export const DEFAULT_MAX_SESSIONS = 16;
 export const DEFAULT_MAX_BUFFER_BYTES = 1024 * 1024;
+export const DEFAULT_LIST_LIMIT = 50;
+export const MAX_LIST_LIMIT = 200;
+
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+const BATCH_EXTENSIONS = new Set(['.cmd', '.bat']);
 
 function envInt(name, fallback) {
   const raw = Number.parseInt(process.env[name] ?? '', 10);
   return Number.isInteger(raw) && raw > 0 ? raw : fallback;
 }
 
+// Windows environment names are case-insensitive, so an override must replace
+// the existing key whatever its case: otherwise the child would see two PATHs
+// and the one it reads is not necessarily the one resolution searched.
+function mergeEnv(extra) {
+  const env = { ...process.env };
+  for (const [key, value] of Object.entries(extra ?? {})) {
+    if (process.platform === 'win32') {
+      const upper = key.toUpperCase();
+      for (const existing of Object.keys(env)) {
+        if (existing !== key && existing.toUpperCase() === upper) delete env[existing];
+      }
+    }
+    env[key] = value;
+  }
+  return env;
+}
+
+function envValue(env, name) {
+  if (env[name] !== undefined) return env[name];
+  const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name);
+  return key === undefined ? undefined : env[key];
+}
+
+// The first file on PATH that answers to `command`, in PATHEXT order, the way
+// cmd.exe finds it. A name that already carries a PATHEXT extension is looked
+// up as-is; anything else gets each extension appended in turn.
+function findOnPath(command, env) {
+  const pathValue = envValue(env, 'PATH');
+  if (!pathValue) return null;
+  const extensions = (envValue(env, 'PATHEXT') || DEFAULT_PATHEXT)
+    .split(';')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const lower = command.toLowerCase();
+  const suffixes = extensions.some((entry) => lower.endsWith(entry.toLowerCase()))
+    ? ['']
+    : extensions;
+  for (const entry of pathValue.split(';')) {
+    const directory = entry.trim().replace(/^"(.*)"$/, '$1');
+    if (!directory) continue;
+    for (const suffix of suffixes) {
+      const candidate = join(directory, `${command}${suffix}`);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        // not here, try the next extension or directory
+      }
+    }
+  }
+  return null;
+}
+
+// One argument as cmd.exe reads it on a /c line: quoted when it holds anything
+// the line would otherwise split or interpret, with an embedded `"` doubled.
+function quoteForCmd(value) {
+  const text = String(value);
+  if (text === '') return '""';
+  if (!/[\s"&|<>^()]/.test(text)) return text;
+  return `"${text.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Turn a tool's command and args into what node-pty is handed.
+ *
+ * POSIX passes through untouched. On Windows a bare name is resolved against
+ * PATH x PATHEXT, because CreateProcess does not consult PATHEXT: `npm`,
+ * `npx`, `pnpm`, `yarn` and `tsc` are .cmd batch shims, and CreateProcess
+ * fails on them with error code 2. A batch shim runs through `cmd /d /s /c`
+ * with the whole line passed as node-pty's pre-escaped CommandLine string, so
+ * node-pty does not re-escape the quotes with backslashes that cmd does not
+ * understand. An .exe/.com resolves to its absolute path and runs directly.
+ *
+ * `^` is refused on the batch path: cmd consumes it even inside quotes, so an
+ * argument carrying one cannot be passed through a shim intact.
+ */
+export function resolveSpawn(command, args, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const direct = { file: command, args, viaShell: false, resolved: null };
+  if (platform !== 'win32') return direct;
+  if (/[\\/]/.test(command)) return direct;
+
+  const resolved = findOnPath(command, env);
+  if (!resolved) return direct;
+  const extension = extname(resolved).toLowerCase();
+  if (!BATCH_EXTENSIONS.has(extension)) {
+    return { file: resolved, args, viaShell: false, resolved };
+  }
+
+  if (args.some((arg) => arg.includes('^'))) {
+    throw invalidArgs(
+      `${command} is a batch shim and an argument contains "^", which cmd consumes even inside quotes; `
+      + 'run it through a cmd.exe session instead',
+    );
+  }
+  const comspec = envValue(env, 'COMSPEC') || 'cmd.exe';
+  const line = [quoteForCmd(resolved), ...args.map(quoteForCmd)].join(' ');
+  return {
+    // The outer pair is the one cmd /s strips; what is left is the quoted
+    // command and its quoted arguments, exactly as a shell would have built it.
+    file: comspec,
+    args: `/d /s /c "${line}"`,
+    viaShell: true,
+    resolved,
+  };
+}
+
 function assertDescription(description) {
   const words = typeof description === 'string'
     ? description.trim().split(/\s+/).filter(Boolean)
@@ -112,6 +224,27 @@ function terminate(term, signal) {
   term.kill(signal ?? 'SIGTERM');
 }
 
+export const MAX_MATCH_PATTERN = 200;
+
+// A match pattern is a regular expression source, compiled once per read so a
+// bad one is a typed invalid_args naming the problem, never a SyntaxError
+// escaping across the tool boundary.
+function compileMatch(match) {
+  if (match === undefined || match === null) return null;
+  if (typeof match !== 'string') {
+    throw invalidArgs('match must be a string holding a regular expression');
+  }
+  if (match === '') throw invalidArgs('match must not be empty');
+  if (match.length > MAX_MATCH_PATTERN) {
+    throw invalidArgs(`match must be at most ${MAX_MATCH_PATTERN} characters, got ${match.length}`);
+  }
+  try {
+    return new RegExp(match);
+  } catch (err) {
+    throw invalidArgs(`match is not a valid regular expression: ${describeCause(err)}`);
+  }
+}
+
 function waitForChange(session, ms) {
   return new Promise((resolve) => {
     const done = () => {
@@ -164,16 +297,20 @@ export class SessionManager {
     }
 
     const title = (typeof input.title === 'string' && input.title.trim()) || basename(command) || command;
-    const env = { ...process.env, ...(input.env ?? {}) };
+    const env = mergeEnv(input.env);
+    const plan = resolveSpawn(command, args, { env });
     const sessionId = randomUUID();
 
     let term;
     try {
-      term = spawnPty(command, args, { cols, rows, cwd, env });
+      term = spawnPty(plan.file, plan.args, { cols, rows, cwd, env });
     } catch (err) {
+      // The searched-for name is always in the message, and the resolved path
+      // too when PATH turned the name into something else.
+      const target = plan.resolved ? `${command} (resolved to ${plan.resolved})` : command;
       throw new JanuaError(
         ERROR_CODES.SPAWN_FAILED,
-        `could not start ${command}: ${describeCause(err)}`,
+        `could not start ${target}: ${describeCause(err)}`,
       );
     }
 
@@ -237,20 +374,51 @@ export class SessionManager {
     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 pattern = compileMatch(options.match);
+    const raw = options.stripAnsi === false;
     const deadline = Date.now() + waitMs;
-    while (session.ring.total <= requested && !session.exited && Date.now() < deadline) {
+    for (;;) {
+      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');
+      const data = raw ? text : stripAnsi(text);
+      const matched = pattern === null ? true : pattern.test(data);
+      const atDeadline = Date.now() >= deadline;
+      const result = {
+        data,
+        cursor: slice.end,
+        exited: session.exited,
+        exitCode: session.exitCode,
+        dropped: slice.dropped,
+        matched,
+      };
+
+      if (pattern !== null) {
+        // A pattern turns the read into a wait for the prompt itself, on the
+        // same wait path: it returns when the text from the caller's cursor
+        // matches, the child exits, the deadline passes, or the window is full
+        // and the pattern is not in it — the caller then reads on from the
+        // returned cursor, so a pattern past the window is not silently lost.
+        const windowFull = slice.end < session.ring.total;
+        if (matched || result.exited || atDeadline || windowFull) return result;
+        await waitForChange(session, deadline - Date.now());
+        continue;
+      }
+
+      // A ConPTY opens with escape-only chunks (mode set, focus reporting), so
+      // the bytes arrive while the visible text has not. Returning "" there
+      // reads as a silent terminal, so a stripped read keeps waiting from the
+      // same absolute cursor until something visible lands, the child exits, or
+      // the deadline passes. A raw read still returns the first bytes, escapes
+      // and all, and a slice that carried no bytes has nothing to wait for.
+      if (raw || data !== '' || slice.end === requested || result.exited || atDeadline) {
+        return result;
+      }
       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') {
@@ -267,8 +435,19 @@ export class SessionManager {
     return { ok: true };
   }
 
-  list() {
-    return [...this.#sessions.values()].map((session) => ({
+  // Newest last, one page at a time. total counts every session known, so a
+  // client can tell a full page from the end of the list; nextOffset is null on
+  // the last page.
+  list(options = {}) {
+    const limit = options.limit ?? DEFAULT_LIST_LIMIT;
+    const offset = options.offset ?? 0;
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT) {
+      throw invalidArgs(`limit must be an integer between 1 and ${MAX_LIST_LIMIT}`);
+    }
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw invalidArgs('offset must be an integer >= 0');
+    }
+    const all = [...this.#sessions.values()].map((session) => ({
       sessionId: session.sessionId,
       pid: session.pid,
       title: session.title,
@@ -278,6 +457,9 @@ export class SessionManager {
       bytes: session.ring.total,
       createdAt: session.createdAt,
     }));
+    const sessions = all.slice(offset, offset + limit);
+    const nextOffset = offset + sessions.length < all.length ? offset + sessions.length : null;
+    return { sessions, total: all.length, nextOffset };
   }
 
   killAll() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathwn12/janua",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",
@@ -38,7 +38,13 @@
   ],
   "dependencies": {
     "@lydell/node-pty": "^1.1.0",
-    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@modelcontextprotocol/server": "^2.4.0",
     "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }