@termwright/mcp 0.2.0

package/dist/chunk-QDIAASH7.js

@@ -0,0 +1,2982 @@
+// src/errors.ts
+import { TermwrightError } from "@termwright/driver";
+
+// src/crash.ts
+import { z } from "zod";
+var CRASH_LIMITS = Object.freeze({
+  /** Screen-tail lines kept, newest end of the buffer. */
+  maxScreenTailLines: 40,
+  /** Characters kept per screen-tail line. */
+  maxLineChars: 500,
+  /** Recent inputs kept, newest last. */
+  maxInputs: 10,
+  /** Diagnostics entries kept, newest last. */
+  maxDiagnostics: 10
+});
+var crashSchema = z.object({
+  exit: z.object({ code: z.number().int().nullable(), signal: z.string().nullable() }),
+  timeMs: z.number(),
+  screenTail: z.array(z.string()).describe("what the terminal showed at the end, verbatim and unredacted \u2014 treat as sensitive"),
+  screenTailTruncated: z.boolean(),
+  lastSemanticRevision: z.number().int().nullable(),
+  recentInputs: z.array(
+    z.object({
+      timeMs: z.number(),
+      kind: z.enum(["key", "mouse", "paste", "raw"]),
+      bytes: z.number().int(),
+      preview: z.string().optional().describe("omitted for pastes, which routinely carry secrets")
+    })
+  ),
+  diagnostics: z.array(
+    z.object({
+      // A free string on purpose — do not "fix" this into an enum. Tolerant
+      // reader, strict producer: the driver owns the closed code set and pins
+      // it with its own tests, while this consumer must survive a code it has
+      // never heard of. A closed enum here would let one unrecognised code
+      // fail the whole crash report, at the moment it is needed most.
+      code: z.string(),
+      detail: z.string(),
+      timeMs: z.number(),
+      revision: z.number().int().optional(),
+      mode: z.enum(["mouse", "focus"]).optional().describe('for "mode-unverifiable": which mode the platform hides')
+    })
+  )
+});
+function boundLines(lines) {
+  const kept = lines.slice(-CRASH_LIMITS.maxScreenTailLines);
+  return {
+    lines: kept.map((line) => line.length > CRASH_LIMITS.maxLineChars ? `${line.slice(0, CRASH_LIMITS.maxLineChars)}\u2026` : line),
+    truncated: kept.length < lines.length
+  };
+}
+function describeCrash(report) {
+  const tail = boundLines(report.screenTail);
+  return {
+    exit: { code: report.exit.code, signal: report.exit.signal },
+    timeMs: report.timeMs,
+    screenTail: tail.lines,
+    screenTailTruncated: tail.truncated,
+    lastSemanticRevision: report.lastSemanticTree?.revision ?? null,
+    recentInputs: report.recentInputs.slice(-CRASH_LIMITS.maxInputs).map((input) => ({
+      timeMs: input.timeMs,
+      kind: input.kind,
+      bytes: input.bytes,
+      ...input.preview === void 0 ? {} : { preview: input.preview }
+    })),
+    diagnostics: report.diagnosticsTail.slice(-CRASH_LIMITS.maxDiagnostics).map((entry) => ({
+      code: entry.code,
+      detail: entry.detail,
+      timeMs: entry.timeMs,
+      ...entry.revision === void 0 ? {} : { revision: entry.revision },
+      ...entry.mode === void 0 ? {} : { mode: entry.mode }
+    }))
+  };
+}
+function renderCrash(crash) {
+  const lines = [
+    `crash: the program exited on its own \u2014 code=${String(crash.exit.code)} signal=${String(crash.exit.signal)} at ${crash.timeMs}ms`
+  ];
+  if (crash.recentInputs.length > 0) {
+    const inputs = crash.recentInputs.map(
+      (input) => input.preview === void 0 ? `${input.kind}(${input.bytes}B)` : `${input.kind} ${JSON.stringify(input.preview)}`
+    );
+    lines.push(`last input: ${inputs.join(" ")}`);
+  }
+  for (const entry of crash.diagnostics) {
+    const mode = entry.mode === void 0 ? "" : ` (${entry.mode})`;
+    lines.push(`diagnostic ${entry.code}${mode}: ${entry.detail}`);
+  }
+  if (crash.screenTail.length > 0) {
+    lines.push(crash.screenTailTruncated ? "screen tail (truncated):" : "screen tail:");
+    lines.push(...crash.screenTail);
+  }
+  return lines.join("\n");
+}
+var CrashContextError = class extends Error {
+  cause;
+  crash;
+  constructor(cause, crash) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = "CrashContextError";
+    this.cause = cause;
+    this.crash = crash;
+  }
+};
+
+// src/errors.ts
+var MCP_ERROR_KINDS = ["usage", "no-session", "internal"];
+var EXIT_CODES = Object.freeze({
+  ok: 0,
+  assertion: 1,
+  usage: 2,
+  noSession: 3,
+  ipc: 4,
+  internal: 5
+});
+function exitCodeFor(kind) {
+  switch (kind) {
+    case "usage":
+      return EXIT_CODES.usage;
+    case "no-session":
+    case "session-closed":
+      return EXIT_CODES.noSession;
+    case "protocol-violation":
+      return EXIT_CODES.ipc;
+    case "internal":
+      return EXIT_CODES.internal;
+    default:
+      return EXIT_CODES.assertion;
+  }
+}
+var McpError = class extends Error {
+  kind;
+  suggestion;
+  constructor(kind, message, suggestion) {
+    super(message);
+    this.name = "McpError";
+    this.kind = kind;
+    this.suggestion = suggestion;
+  }
+};
+function usageError(message, suggestion) {
+  return new McpError("usage", message, suggestion);
+}
+function noSessionError(message, suggestion) {
+  return new McpError("no-session", message, suggestion);
+}
+var MAX_CANDIDATES = 10;
+var MAX_EXCERPT_CHARS = 2e3;
+function toErrorPayload(error) {
+  if (error instanceof CrashContextError) {
+    return { ...toErrorPayload(error.cause), crash: error.crash };
+  }
+  if (error instanceof TermwrightError) {
+    const diagnostics = error.diagnostics;
+    const candidates = diagnostics.candidates?.slice(0, MAX_CANDIDATES).map((candidate) => {
+      const role = candidate.role ?? "generic";
+      const name = candidate.name === void 0 ? "" : ` ${JSON.stringify(candidate.name)}`;
+      return `${role}${name} ref=${candidate.ref}`;
+    });
+    return {
+      kind: error.code,
+      message: error.message,
+      ...diagnostics.suggestion === void 0 ? {} : { suggestion: diagnostics.suggestion },
+      semanticTree: diagnostics.semanticTree,
+      ...candidates === void 0 || candidates.length === 0 ? {} : { candidates },
+      ...diagnostics.screenExcerpt === void 0 ? {} : { screenExcerpt: diagnostics.screenExcerpt.slice(0, MAX_EXCERPT_CHARS) }
+    };
+  }
+  if (error instanceof McpError) {
+    return {
+      kind: error.kind,
+      message: error.message,
+      ...error.suggestion === void 0 ? {} : { suggestion: error.suggestion }
+    };
+  }
+  return { kind: "internal", message: error instanceof Error ? error.message : String(error) };
+}
+function renderErrorPayload(payload) {
+  const parts = [`error ${payload.kind}: ${payload.message}`];
+  if (payload.suggestion !== void 0) parts.push(`suggestion: ${payload.suggestion}`);
+  if (payload.semanticTree !== void 0) parts.push(`semanticTree: ${payload.semanticTree}`);
+  if (payload.candidates !== void 0) {
+    parts.push(`candidates:
+${payload.candidates.map((candidate) => `  - ${candidate}`).join("\n")}`);
+  }
+  if (payload.screenExcerpt !== void 0) parts.push(`screen:
+${payload.screenExcerpt}`);
+  if (payload.crash !== void 0) parts.push(renderCrash(payload.crash));
+  return parts.join("\n");
+}
+
+// src/model.ts
+import { SEMANTIC_ROLES } from "@termwright/protocol";
+var FILTERABLE_STATES = [
+  "disabled",
+  "focused",
+  "selected",
+  "checked",
+  "expanded",
+  "modal",
+  "busy",
+  "hidden",
+  "readonly"
+];
+var SIGNALS = ["INT", "TERM", "KILL", "HUP"];
+
+// src/traces.ts
+import { stat } from "fs/promises";
+import { openTrace, TraceError } from "@termwright/trace";
+var TRACE_LIMITS = Object.freeze({
+  /** Archives kept open per MCP session; the least recently used is evicted. */
+  maxOpen: 8,
+  /** Refusal threshold for an archive, in bytes. */
+  maxArchiveBytes: 128 * 1024 * 1024,
+  /** Rows of reconstructed screen text a single frame may return. */
+  maxFrameRows: 200
+});
+function rethrowTraceError(error, path) {
+  if (error instanceof TraceError) {
+    throw new McpError(
+      error.code,
+      `${path}: ${error.message}`,
+      error.diagnostics.suggestion ?? "check that the path points at a .twtrace directory or zip"
+    );
+  }
+  if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    throw usageError(`no trace at ${path}`, "pass the path of a .twtrace directory or zip");
+  }
+  throw error;
+}
+var TraceStore = class {
+  #open = /* @__PURE__ */ new Map();
+  #maxOpen;
+  #maxArchiveBytes;
+  #now;
+  #counter = 0;
+  constructor(options = {}) {
+    this.#maxOpen = options.maxOpen ?? TRACE_LIMITS.maxOpen;
+    this.#maxArchiveBytes = options.maxArchiveBytes ?? TRACE_LIMITS.maxArchiveBytes;
+    this.#now = options.now ?? Date.now;
+  }
+  /** Handles of every archive still open. */
+  list() {
+    return [...this.#open.values()];
+  }
+  /**
+   * Opens an archive and registers it under a fresh `tr<n>` handle.
+   *
+   * At the ceiling the least recently used archive is closed rather than the
+   * call being refused: an agent can always re-open a path, but it cannot
+   * recover from a server that has wedged itself on old readers. The evicted
+   * handle is reported so the caller knows why it stopped working.
+   */
+  async open(path) {
+    let size;
+    try {
+      const stats = await stat(path);
+      size = stats.isDirectory() ? 0 : stats.size;
+    } catch (error) {
+      rethrowTraceError(error, path);
+    }
+    if (size > this.#maxArchiveBytes) {
+      throw new McpError(
+        "capacity",
+        `${path} is ${size} bytes; the ceiling is ${this.#maxArchiveBytes}`,
+        "open the archive with @termwright/trace directly, or re-record with tighter limits"
+      );
+    }
+    let reader;
+    try {
+      reader = await openTrace(path);
+    } catch (error) {
+      rethrowTraceError(error, path);
+    }
+    const evicted = await this.#evictIfFull();
+    this.#counter += 1;
+    const trace = {
+      id: `tr${this.#counter}`,
+      path,
+      reader,
+      lastUsedAt: this.#now()
+    };
+    this.#open.set(trace.id, trace);
+    return { trace, evicted };
+  }
+  /** Looks up a handle and marks it as used. */
+  get(id) {
+    const trace = this.#open.get(id);
+    if (trace === void 0) {
+      const known = [...this.#open.keys()];
+      throw noSessionError(
+        `unknown trace ${JSON.stringify(id)}`,
+        known.length === 0 ? "open one with trace.open" : `open traces: ${known.join(", ")} (an evicted handle has to be re-opened by path)`
+      );
+    }
+    trace.lastUsedAt = this.#now();
+    return trace;
+  }
+  async #evictIfFull() {
+    if (this.#open.size < this.#maxOpen) return null;
+    const coldest = [...this.#open.values()].reduce(
+      (oldest, candidate) => candidate.lastUsedAt < oldest.lastUsedAt ? candidate : oldest
+    );
+    this.#open.delete(coldest.id);
+    await coldest.reader.close();
+    return coldest.id;
+  }
+  /** Closes every open archive. Best-effort, so shutdown always completes. */
+  async closeAll() {
+    const traces = [...this.#open.values()];
+    this.#open.clear();
+    await Promise.all(
+      traces.map(async (trace) => {
+        try {
+          await trace.reader.close();
+        } catch {
+        }
+      })
+    );
+  }
+};
+
+// src/sessions.ts
+import { mkdir, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { launchTerminal } from "@termwright/driver";
+import { DEFAULT_LIMITS } from "@termwright/protocol";
+
+// src/logs.ts
+import { z as z2 } from "zod";
+var LOG_LIMITS = Object.freeze({
+  /** Entries retained per terminal; the oldest are evicted first. */
+  bufferSize: 1e3,
+  /** Entries returned by one call, newest kept. */
+  maxPerResponse: 100,
+  /** Characters kept per line or message. */
+  maxTextChars: 2e3
+});
+var logEntrySchema = z2.object({
+  seq: z2.number().int().describe("per-session counter assigned on arrival; the cursor for logs"),
+  timeMs: z2.number().describe("session clock; for a followed file, when the driver read the line"),
+  source: z2.enum(["file", "adapter"]),
+  label: z2.string().optional().describe("which log source, when the session follows more than one"),
+  level: z2.enum(["trace", "debug", "info", "warn", "error", "fatal"]).optional(),
+  message: z2.string().describe("the raw line, or the record\u2019s formatted message"),
+  logger: z2.string().optional(),
+  attrs: z2.record(z2.string(), z2.unknown()).optional(),
+  revision: z2.number().int().optional().describe("semantic revision current when the record was produced")
+});
+function clamp(text) {
+  return text.length > LOG_LIMITS.maxTextChars ? `${text.slice(0, LOG_LIMITS.maxTextChars)}\u2026` : text;
+}
+function toEntry(event, seq) {
+  const record = event.record;
+  return {
+    seq,
+    timeMs: event.timeMs,
+    source: event.source,
+    ...event.label === void 0 ? {} : { label: event.label },
+    ...record === void 0 ? { message: clamp(event.line ?? "") } : {
+      level: record.level,
+      message: clamp(record.message),
+      ...record.logger === void 0 ? {} : { logger: record.logger },
+      ...record.attrs === void 0 ? {} : { attrs: { ...record.attrs } },
+      ...record.revision === void 0 ? {} : { revision: record.revision }
+    }
+  };
+}
+var LogBuffer = class {
+  #entries = [];
+  #capacity;
+  #counter = 0;
+  constructor(capacity = LOG_LIMITS.bufferSize) {
+    this.#capacity = capacity;
+  }
+  /** Sequence number of the newest entry; 0 when nothing has arrived. */
+  get sequence() {
+    return this.#counter;
+  }
+  /** Entries currently retained. */
+  get size() {
+    return this.#entries.length;
+  }
+  /** Records one driver event. */
+  append(event) {
+    this.#counter += 1;
+    this.#entries.push(toEntry(event, this.#counter));
+    if (this.#entries.length > this.#capacity) this.#entries.splice(0, this.#entries.length - this.#capacity);
+  }
+  /**
+   * Everything after `cursor`, newest-biased and bounded.
+   *
+   * A cursor older than the buffer is not an error: the entries in between are
+   * counted in {@link LogWindow.omitted} so an agent knows its view has a hole,
+   * rather than quietly seeing a shorter list.
+   */
+  since(cursor, limit = LOG_LIMITS.maxPerResponse) {
+    const newer = this.#entries.filter((entry) => entry.seq > cursor);
+    const oldestKept = this.#entries[0]?.seq ?? this.#counter + 1;
+    const evicted = Math.max(0, Math.min(oldestKept - 1, this.#counter) - cursor);
+    const trimmed = newer.length > limit ? newer.slice(-limit) : newer;
+    return {
+      entries: trimmed,
+      omitted: evicted + (newer.length - trimmed.length),
+      cursor: this.#counter
+    };
+  }
+};
+function renderLogs(window) {
+  if (window.entries.length === 0 && window.omitted === 0) return "logs: none";
+  const header = window.omitted === 0 ? `logs: ${window.entries.length}` : `logs: ${window.entries.length} (${window.omitted} omitted \u2014 raise the limit or read more often)`;
+  return [
+    header,
+    ...window.entries.map((entry) => {
+      const level = entry.level === void 0 ? "" : ` ${entry.level.toUpperCase()}`;
+      const label = entry.label === void 0 ? "" : ` [${entry.label}]`;
+      const logger = entry.logger === void 0 ? "" : ` ${entry.logger}:`;
+      return `  ${entry.timeMs}ms${level}${label}${logger} ${entry.message}`;
+    })
+  ].join("\n");
+}
+
+// src/objects.ts
+function definedOnly(value) {
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== void 0) out[key] = item;
+  }
+  return out;
+}
+
+// src/sessions.ts
+var MCP_LIMITS = Object.freeze({
+  /** Concurrent MCP sessions. */
+  maxSessions: DEFAULT_LIMITS.maxSessions,
+  /** Concurrent terminals inside one MCP session. */
+  maxTerminals: DEFAULT_LIMITS.maxSessions,
+  /** Snapshots retained per terminal for `capture_since` cursors. */
+  maxHistory: 16,
+  /** Argument ceiling for a launch command line. */
+  maxCommandParts: 64
+});
+var TerminalStore = class {
+  sessionKey;
+  #directory;
+  #maxTerminals;
+  #now;
+  #terminals = /* @__PURE__ */ new Map();
+  #counter = 0;
+  constructor(options) {
+    this.sessionKey = options.sessionKey;
+    this.#directory = join(options.storageDir ?? join(tmpdir(), "termwright-mcp"), options.sessionKey);
+    this.#maxTerminals = options.maxTerminals ?? MCP_LIMITS.maxTerminals;
+    this.#now = options.now ?? Date.now;
+  }
+  /** Handles of every terminal still open in this session. */
+  list() {
+    return [...this.#terminals.values()];
+  }
+  /** Launches a child and registers it under a fresh `t<n>` handle. */
+  async launch(request) {
+    if (request.command.length === 0) throw usageError("command must have at least one element");
+    if (request.command.length > MCP_LIMITS.maxCommandParts) {
+      throw usageError(`command may have at most ${MCP_LIMITS.maxCommandParts} elements`);
+    }
+    if (this.#terminals.size >= this.#maxTerminals) {
+      throw new McpError(
+        "capacity",
+        `this session already owns ${this.#maxTerminals} terminals`,
+        "close a terminal with terminal.close before launching another"
+      );
+    }
+    const options = {
+      command: [...request.command],
+      // Environment policy belongs to the driver: 'replace' (its default) keeps
+      // the operator's secrets out of the child, 'inherit' is opt-in.
+      ...request.env === void 0 ? {} : { env: request.env },
+      ...request.envMode === void 0 ? {} : { envMode: request.envMode },
+      ...request.cwd === void 0 ? {} : { cwd: request.cwd },
+      ...request.columns === void 0 ? {} : { columns: request.columns },
+      ...request.rows === void 0 ? {} : { rows: request.rows },
+      ...request.scrollbackLines === void 0 ? {} : { scrollbackLines: request.scrollbackLines },
+      ...request.semanticNegotiationMs === void 0 ? {} : { semanticNegotiationMs: request.semanticNegotiationMs },
+      ...request.timeouts === void 0 ? {} : { timeouts: definedOnly(request.timeouts) },
+      ...request.logs === void 0 ? {} : {
+        logs: request.logs.flatMap((source) => source.path === void 0 ? [] : [{
+          path: source.path,
+          ...source.label === void 0 ? {} : { label: source.label }
+        }])
+      }
+    };
+    const harness = await launchTerminal(options);
+    this.#counter += 1;
+    const id = `t${this.#counter}`;
+    const entry = {
+      id,
+      harness,
+      directory: join(this.#directory, id),
+      command: [...request.command],
+      exit: null,
+      closed: false,
+      history: [],
+      logs: new LogBuffer()
+    };
+    harness.events.on("app-log", (event) => {
+      entry.logs.append(event);
+    });
+    void harness.exit.then(
+      (status) => {
+        entry.exit = status;
+      },
+      () => {
+        entry.exit = { code: null, signal: null };
+      }
+    );
+    this.#terminals.set(id, entry);
+    return entry;
+  }
+  /** Looks up a handle without throwing; for callers that tolerate absence. */
+  find(id) {
+    return this.#terminals.get(id);
+  }
+  /** Looks up a handle; unknown or closed handles are a `no-session` failure. */
+  get(id) {
+    const entry = this.#terminals.get(id);
+    if (entry === void 0) {
+      const known = [...this.#terminals.keys()];
+      throw noSessionError(
+        `unknown terminal ${JSON.stringify(id)}`,
+        known.length === 0 ? "launch one with terminal.launch" : `open terminals: ${known.join(", ")}`
+      );
+    }
+    return entry;
+  }
+  /**
+   * Captures the current screen and semantic tree, and remembers it so a later
+   * `capture_since` can diff against this revision.
+   */
+  record(entry) {
+    const screen = entry.harness.screen();
+    const semantic = entry.harness.semanticTree();
+    const record = {
+      revision: screen.revision,
+      semanticRevision: semantic?.revision ?? null,
+      rows: screen.text().split("\n"),
+      semantic,
+      logSeq: entry.logs.sequence,
+      capturedAt: this.#now()
+    };
+    entry.history = [...entry.history.filter((item) => item.revision !== record.revision), record].slice(
+      -MCP_LIMITS.maxHistory
+    );
+    return record;
+  }
+  /** The recorded baseline for a cursor, or a `history-truncated` failure. */
+  baseline(entry, cursor) {
+    const found = entry.history.find((item) => item.revision === cursor);
+    if (found !== void 0) return found;
+    const known = entry.history.map((item) => item.revision);
+    throw new McpError(
+      "history-truncated",
+      `no capture retained for cursor ${cursor}`,
+      known.length === 0 ? "take a terminal.snapshot first; its revision is the cursor" : `retained cursors: ${known.join(", ")}`
+    );
+  }
+  /** Writes a full dump next to the session and returns its path. */
+  async writeDump(entry, name, contents) {
+    await mkdir(entry.directory, { recursive: true });
+    const path = join(entry.directory, name);
+    await writeFile(path, contents, "utf8");
+    return path;
+  }
+  /** Closes one terminal and forgets it. Idempotent. */
+  async close(id) {
+    const entry = this.get(id);
+    await entry.harness.close();
+    entry.closed = true;
+    this.#terminals.delete(id);
+    return entry;
+  }
+  /** Closes every terminal; failures are swallowed so shutdown always completes. */
+  async closeAll() {
+    const entries = [...this.#terminals.values()];
+    this.#terminals.clear();
+    await Promise.all(
+      entries.map(async (entry) => {
+        try {
+          await entry.harness.close();
+        } catch {
+        }
+        entry.closed = true;
+      })
+    );
+  }
+};
+function createSessionStores(options) {
+  return {
+    terminals: new TerminalStore({
+      sessionKey: options.sessionKey,
+      ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir }
+    }),
+    traces: new TraceStore()
+  };
+}
+async function closeSessionStores(stores) {
+  await Promise.all([stores.terminals.closeAll(), stores.traces.closeAll()]);
+}
+var SessionRegistry = class {
+  #sessions = /* @__PURE__ */ new Map();
+  #maxSessions;
+  #storageDir;
+  #idleTtlMs;
+  #now;
+  #disposeAttachment;
+  #onExpired;
+  #sweeper;
+  constructor(options = {}) {
+    this.#maxSessions = options.maxSessions ?? MCP_LIMITS.maxSessions;
+    this.#storageDir = options.storageDir;
+    this.#idleTtlMs = options.idleTtlMs ?? 0;
+    this.#now = options.now ?? Date.now;
+    this.#disposeAttachment = options.disposeAttachment;
+    this.#onExpired = options.onExpired;
+  }
+  /** The configured idle ceiling; `0` when expiry is disabled. */
+  get idleTtlMs() {
+    return this.#idleTtlMs;
+  }
+  /**
+   * Marks a session as used. Called for **every** request that names one, so a
+   * session stays alive exactly as long as someone is talking to it.
+   */
+  touch(key) {
+    const session = this.#sessions.get(key);
+    if (session !== void 0) session.lastSeenAt = this.#now();
+  }
+  /**
+   * Tears down every session idle past the TTL and returns their keys.
+   *
+   * Streamable HTTP has no disconnect signal: a client that crashes or walks
+   * away leaves its session, its terminals and their children running, and its
+   * slot taken. Repeated agent failures would then add up to an accidental
+   * denial of service against the operator's own machine, so idleness is the
+   * only honest liveness signal available here.
+   */
+  async sweepIdle() {
+    if (this.#idleTtlMs <= 0) return [];
+    const deadline = this.#now() - this.#idleTtlMs;
+    const expired = [...this.#sessions.values()].filter((session) => session.lastSeenAt <= deadline).map((session) => session.key);
+    for (const key of expired) {
+      await this.delete(key);
+      this.#onExpired?.(key);
+    }
+    return expired;
+  }
+  /**
+   * Runs {@link sweepIdle} on a timer until the returned function is called.
+   * The timer is unref'd, so it never keeps a process alive on its own.
+   */
+  startIdleSweeper(intervalMs = Math.min(Math.max(this.#idleTtlMs / 4, 1e3), 6e4)) {
+    if (this.#idleTtlMs <= 0) return () => void 0;
+    this.#sweeper = setInterval(() => {
+      void this.sweepIdle();
+    }, intervalMs);
+    this.#sweeper.unref?.();
+    return () => this.stopIdleSweeper();
+  }
+  /** Stops the sweeper started by {@link startIdleSweeper}. Idempotent. */
+  stopIdleSweeper() {
+    if (this.#sweeper === void 0) return;
+    clearInterval(this.#sweeper);
+    this.#sweeper = void 0;
+  }
+  get size() {
+    return this.#sessions.size;
+  }
+  /** True when another session would exceed the ceiling. */
+  get atCapacity() {
+    return this.#sessions.size >= this.#maxSessions;
+  }
+  /** Creates a session and its stores; throws `capacity` at the ceiling. */
+  create(key, attach) {
+    if (this.#sessions.has(key)) throw usageError(`session ${key} already exists`);
+    if (this.atCapacity) {
+      throw new McpError(
+        "capacity",
+        `server already serves ${this.#maxSessions} MCP sessions`,
+        "close an existing session (DELETE with its Mcp-Session-Id) and retry"
+      );
+    }
+    const stores = createSessionStores({ sessionKey: key, storageDir: this.#storageDir });
+    const session = {
+      key,
+      stores,
+      attachment: attach(stores),
+      lastSeenAt: this.#now()
+    };
+    this.#sessions.set(key, session);
+    return session;
+  }
+  get(key) {
+    return this.#sessions.get(key);
+  }
+  /** Removes a session and closes everything it owned. */
+  async delete(key) {
+    const session = this.#sessions.get(key);
+    if (session === void 0) return;
+    this.#sessions.delete(key);
+    await closeSessionStores(session.stores);
+    try {
+      await this.#disposeAttachment?.(session.attachment);
+    } catch {
+    }
+  }
+  /** Closes every session and stops the sweeper. */
+  async closeAll() {
+    this.stopIdleSweeper();
+    const keys = [...this.#sessions.keys()];
+    await Promise.all(keys.map(async (key) => this.delete(key)));
+  }
+};
+
+// src/tool-kit.ts
+function defineTool(definition) {
+  return {
+    name: definition.name,
+    title: definition.title,
+    description: definition.description,
+    inputSchema: definition.inputSchema,
+    outputSchema: definition.outputSchema,
+    annotations: definition.annotations ?? {},
+    handler: definition.handler
+  };
+}
+
+// src/screenshots.ts
+import { LIGHT_THEME, renderPng } from "@termwright/screenshot";
+var SCREENSHOT_LIMITS = Object.freeze({
+  /**
+   * Refusal threshold for one PNG, in bytes.
+   *
+   * An MCP result travels inside a JSON-RPC message, and base64 inflates it by
+   * a third: a screenshot larger than this is more likely to blow a context
+   * window than to answer a question, so it fails with a suggestion instead.
+   */
+  maxPngBytes: 3 * 1024 * 1024,
+  /** Pixel density multiplier ceiling. */
+  maxScale: 3
+});
+function renderScreenshot(frame2, request = {}) {
+  const scale = request.scale ?? 1;
+  if (!Number.isFinite(scale) || scale <= 0 || scale > SCREENSHOT_LIMITS.maxScale) {
+    throw new McpError(
+      "usage",
+      `screenshotScale must be between 0 and ${SCREENSHOT_LIMITS.maxScale}, got ${scale}`,
+      "omit it for 1, or pass 2 for a retina-sharp image"
+    );
+  }
+  let rendered;
+  try {
+    rendered = renderPng(frame2, {
+      scale,
+      ...request.theme === "light" ? { theme: LIGHT_THEME } : {}
+    });
+  } catch (error) {
+    throw new McpError(
+      "unsupported-action",
+      `the screenshot renderer failed: ${error instanceof Error ? error.message : String(error)}`,
+      "omit screenshot \u2014 the tool still returns the screen as text and the compact tree"
+    );
+  }
+  if (rendered.png.byteLength > SCREENSHOT_LIMITS.maxPngBytes) {
+    throw new McpError(
+      "capacity",
+      `the PNG is ${rendered.png.byteLength} bytes; the ceiling is ${SCREENSHOT_LIMITS.maxPngBytes}`,
+      "lower screenshotScale, or resize the terminal before taking the screenshot"
+    );
+  }
+  return {
+    data: Buffer.from(rendered.png).toString("base64"),
+    mimeType: "image/png",
+    width: rendered.width,
+    height: rendered.height,
+    selfContained: rendered.selfContained,
+    fallbackCharacters: [...rendered.fallbackCharacters]
+  };
+}
+
+// src/format.ts
+function formatRef(nodeId, revision) {
+  return `${nodeId}@${revision}`;
+}
+function parseRef(ref) {
+  const at = ref.lastIndexOf("@");
+  if (at <= 0) return null;
+  const nodeId = ref.slice(0, at);
+  const revision = Number(ref.slice(at + 1));
+  if (!Number.isInteger(revision) || revision < 0) return null;
+  return { nodeId, revision };
+}
+function formatBounds(bounds) {
+  return `(${bounds.row},${bounds.column},${bounds.width},${bounds.height})`;
+}
+function stateFlags(state) {
+  if (state === void 0) return [];
+  const flags = [];
+  for (const [key, value] of Object.entries(state)) {
+    if (value === void 0) continue;
+    if (value === true) flags.push(key);
+    else if (value === false) continue;
+    else flags.push(`${key}=${String(value)}`);
+  }
+  return flags;
+}
+function formatNodeLine(entry) {
+  const parts = [`${entry.role} ${JSON.stringify(entry.name)}`, `ref=${entry.ref}`];
+  if (entry.bounds !== void 0) parts.push(`bounds=${formatBounds(entry.bounds)}`);
+  return [...parts, ...entry.flags].join(" ");
+}
+function walkSnapshot(snapshot2) {
+  const children = /* @__PURE__ */ new Map();
+  const byId = /* @__PURE__ */ new Map();
+  for (const node of snapshot2.nodes) {
+    byId.set(node.id, node);
+    const parent = node.parentId;
+    if (parent === void 0) continue;
+    const bucket = children.get(parent);
+    if (bucket === void 0) children.set(parent, [node]);
+    else bucket.push(node);
+  }
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (node, depth) => {
+    if (seen.has(node.id)) return;
+    seen.add(node.id);
+    out.push({ node, depth });
+    for (const child of children.get(node.id) ?? []) visit(child, depth + 1);
+  };
+  for (const rootId of snapshot2.rootIds) {
+    const root = byId.get(rootId);
+    if (root !== void 0) visit(root, 0);
+  }
+  for (const node of snapshot2.nodes) visit(node, 0);
+  return out;
+}
+function refEntries(snapshot2) {
+  return walkSnapshot(snapshot2).map(({ node, depth }) => toRefEntry(node, snapshot2.revision, depth));
+}
+function toRefEntry(node, revision, depth = 0) {
+  return {
+    ref: formatRef(node.id, revision),
+    role: node.role,
+    name: node.name,
+    depth,
+    ...node.bounds === void 0 ? {} : { bounds: node.bounds },
+    flags: stateFlags(node.state),
+    ...node.testId === void 0 ? {} : { testId: node.testId },
+    ...node.value === void 0 ? {} : { value: node.value }
+  };
+}
+var DEFAULT_MAX_NODES = 500;
+function formatCompactSnapshot(options) {
+  const lines = [
+    `Terminal ${options.terminal} ${options.columns}x${options.rows} revision ${options.revision}`,
+    `semanticTree: ${options.semantic === null ? "unavailable" : "available"}`
+  ];
+  if (options.semantic !== null) {
+    const entries = refEntries(options.semantic);
+    const limit = options.maxNodes ?? DEFAULT_MAX_NODES;
+    for (const entry of entries.slice(0, limit)) {
+      lines.push(`${"  ".repeat(entry.depth)}${formatNodeLine(entry)}`);
+    }
+    if (entries.length > limit) {
+      lines.push(`... ${entries.length - limit} more nodes (raise maxNodes or use variant="full")`);
+    }
+  }
+  if (options.includeText !== false) {
+    lines.push("visible text:");
+    const maxRows = options.maxRows ?? options.text.length;
+    lines.push(...options.text.slice(0, maxRows));
+    if (options.text.length > maxRows) lines.push(`... ${options.text.length - maxRows} more rows`);
+  }
+  return lines.join("\n");
+}
+
+// src/diff.ts
+function diffRows(before, after) {
+  const changes = [];
+  for (let row = 0; row < after.length; row += 1) {
+    const next = after[row] ?? "";
+    if (before[row] !== next) changes.push({ row, text: next });
+  }
+  for (let row = after.length; row < before.length; row += 1) {
+    changes.push({ row, text: "" });
+  }
+  return changes;
+}
+function nodeChanged(before, after) {
+  return before.role !== after.role || before.name !== after.name || before.value !== after.value || before.testId !== after.testId || before.description !== after.description || before.parentId !== after.parentId || JSON.stringify(before.bounds ?? null) !== JSON.stringify(after.bounds ?? null) || JSON.stringify(before.state ?? null) !== JSON.stringify(after.state ?? null);
+}
+function indexById(snapshot2) {
+  const index = /* @__PURE__ */ new Map();
+  for (const node of snapshot2?.nodes ?? []) index.set(node.id, node);
+  return index;
+}
+function renderSubtree(snapshot2, rootId, walked) {
+  const rootIndex = walked.findIndex(({ node }) => node.id === rootId);
+  const rootEntry = walked[rootIndex];
+  if (rootEntry === void 0) throw new Error(`node ${rootId} vanished mid-diff`);
+  const lines = [];
+  let root;
+  for (let i = rootIndex; i < walked.length; i += 1) {
+    const current = walked[i];
+    if (current === void 0) break;
+    if (i > rootIndex && current.depth <= rootEntry.depth) break;
+    const entry = toRefEntry(current.node, snapshot2.revision, current.depth - rootEntry.depth);
+    root ??= entry;
+    lines.push(`${"  ".repeat(entry.depth)}${formatNodeLine(entry)}`);
+  }
+  return { root: root ?? toRefEntry(rootEntry.node, snapshot2.revision), compact: lines.join("\n") };
+}
+function diffSemantic(before, after) {
+  if (after === null) {
+    if (before === null) return [];
+    return before.nodes.map((node) => ({
+      change: "removed",
+      ref: formatRef(node.id, before.revision),
+      role: node.role,
+      name: node.name,
+      compact: formatNodeLine(toRefEntry(node, before.revision))
+    }));
+  }
+  const beforeIndex = indexById(before);
+  const afterIndex = indexById(after);
+  const walked = walkSnapshot(after);
+  const changedIds = /* @__PURE__ */ new Set();
+  for (const node of after.nodes) {
+    const previous = beforeIndex.get(node.id);
+    if (previous === void 0 || nodeChanged(previous, node)) changedIds.add(node.id);
+  }
+  const changes = [];
+  for (const { node } of walked) {
+    if (!changedIds.has(node.id)) continue;
+    const parentId = node.parentId;
+    if (parentId !== void 0 && changedIds.has(parentId) && afterIndex.has(parentId)) continue;
+    const rendered = renderSubtree(after, node.id, walked);
+    changes.push({
+      change: beforeIndex.has(node.id) ? "updated" : "added",
+      ref: rendered.root.ref,
+      role: node.role,
+      name: node.name,
+      compact: rendered.compact
+    });
+  }
+  for (const node of before?.nodes ?? []) {
+    if (afterIndex.has(node.id)) continue;
+    const parentId = node.parentId;
+    if (parentId !== void 0 && !afterIndex.has(parentId)) continue;
+    changes.push({
+      change: "removed",
+      ref: formatRef(node.id, before?.revision ?? 0),
+      role: node.role,
+      name: node.name,
+      compact: formatNodeLine(toRefEntry(node, before?.revision ?? 0))
+    });
+  }
+  return changes;
+}
+
+// src/targets.ts
+var REGEX_LITERAL = /^\/(.*)\/([gimsuy]*)$/su;
+function textOrRegExp(value) {
+  const match = REGEX_LITERAL.exec(value);
+  if (match === null) return value;
+  try {
+    return new RegExp(match[1] ?? "", match[2] ?? "");
+  } catch (error) {
+    throw usageError(
+      `invalid regular expression ${JSON.stringify(value)}: ${error instanceof Error ? error.message : String(error)}`,
+      "quote a literal string, or fix the /pattern/flags form"
+    );
+  }
+}
+function hasTarget(input) {
+  return input.ref !== void 0 || input.selector !== void 0 || input.role !== void 0 || input.testId !== void 0 || input.text !== void 0 || input.label !== void 0;
+}
+function buildLocator(harness, input) {
+  let locator;
+  if (input.ref !== void 0) {
+    locator = harness.locatorForRef(input.ref);
+  } else if (input.selector !== void 0) {
+    locator = harness.locator(input.selector);
+  } else if (input.testId !== void 0) {
+    locator = harness.getByTestId(input.testId);
+  } else if (input.role !== void 0) {
+    locator = harness.getByRole(
+      input.role,
+      definedOnly({
+        name: input.name === void 0 ? void 0 : textOrRegExp(input.name),
+        exact: input.exact,
+        state: input.state === void 0 ? void 0 : definedOnly(input.state)
+      })
+    );
+  } else if (input.label !== void 0) {
+    locator = harness.getByLabel(textOrRegExp(input.label), definedOnly({ exact: input.exact }));
+  } else if (input.text !== void 0) {
+    locator = harness.getByText(textOrRegExp(input.text), definedOnly({ exact: input.exact }));
+  } else {
+    throw usageError(
+      "no target given",
+      "pass one of ref, selector, testId, role (+name), label or text"
+    );
+  }
+  return input.nth === void 0 ? locator : locator.nth(input.nth);
+}
+
+// src/tools.ts
+import { z as z5 } from "zod";
+
+// src/screenshot-schema.ts
+import { z as z3 } from "zod";
+var screenshotSchema = z3.object({
+  width: z3.number().int(),
+  height: z3.number().int(),
+  mimeType: z3.literal("image/png"),
+  selfContained: z3.boolean().describe("false when a character had no embedded outline and fell back to a font"),
+  fallbackCharacters: z3.array(z3.string())
+});
+function describeImage(image) {
+  return {
+    width: image.width,
+    height: image.height,
+    mimeType: image.mimeType,
+    selfContained: image.selfContained,
+    fallbackCharacters: [...image.fallbackCharacters]
+  };
+}
+
+// src/schemas.ts
+import { z as z4 } from "zod";
+var terminalId = z4.string().min(1).describe('terminal handle returned by terminal.launch, e.g. "t1"');
+var timeoutMs = z4.number().int().positive().max(6e5).describe("timeout in milliseconds; defaults to the driver timeout class for the action");
+var stateFilter = z4.object({
+  disabled: z4.boolean().optional(),
+  focused: z4.boolean().optional(),
+  selected: z4.boolean().optional(),
+  checked: z4.union([z4.boolean(), z4.literal("mixed")]).optional(),
+  expanded: z4.boolean().optional(),
+  modal: z4.boolean().optional(),
+  busy: z4.boolean().optional(),
+  hidden: z4.boolean().optional(),
+  readonly: z4.boolean().optional()
+}).describe("only nodes asserting these state flags match");
+var cellPosition = z4.object({
+  row: z4.number().int().min(0),
+  column: z4.number().int().min(0)
+});
+var targetShape = {
+  ref: z4.string().optional().describe(
+    'ref from a previous snapshot: "n8@42" (semantic node) or "grid:1,2,9,1@7" (grid match); valid only at the revision it was minted at'
+  ),
+  selector: z4.string().optional().describe('CSS dialect: "dialog button#approve:focused" (role, #testId, .class, :state)'),
+  role: z4.enum(SEMANTIC_ROLES).optional().describe("semantic role; requires a semantic tree"),
+  name: z4.string().optional().describe('accessible name; "/pattern/flags" is read as a regular expression'),
+  testId: z4.string().optional().describe("author-supplied test id"),
+  label: z4.string().optional().describe("label text (labelledBy, else name)"),
+  text: z4.string().optional().describe("visible text; matches the grid when there is no semantic tree"),
+  exact: z4.boolean().optional().describe("exact rather than substring text matching"),
+  state: stateFilter.optional(),
+  nth: z4.number().int().min(0).optional().describe("zero-based pick among matches; omit for strict mode (>1 match fails)")
+};
+var targetShapeWithoutText = (({ text: _text, ...rest }) => rest)(targetShape);
+var targetObject = z4.object(targetShape);
+var refEntrySchema = z4.object({
+  ref: z4.string(),
+  role: z4.string(),
+  name: z4.string(),
+  depth: z4.number().int().min(0),
+  bounds: z4.object({
+    row: z4.number().int(),
+    column: z4.number().int(),
+    width: z4.number().int(),
+    height: z4.number().int()
+  }).optional(),
+  flags: z4.array(z4.string()),
+  testId: z4.string().optional(),
+  value: z4.string().optional()
+});
+var semanticTreeState = z4.enum(["available", "unavailable"]);
+var cursorSchema = z4.object({
+  row: z4.number().int(),
+  column: z4.number().int(),
+  visible: z4.boolean(),
+  shape: z4.enum(["block", "underline", "bar"]).optional()
+});
+var modesSchema = z4.object({
+  /**
+   * `'unknown'` means the platform hides the mode from the emulator (ConPTY on
+   * Windows), not that the program disabled mouse reporting. Pointer actions
+   * still work there: input goes out as SGR, which every program that enables
+   * mouse reporting understands.
+   */
+  mouseTracking: z4.enum(["none", "x10", "vt200", "drag", "any", "unknown"]),
+  mouseEncoding: z4.enum(["default", "sgr", "urxvt", "utf8", "unknown"]),
+  bracketedPaste: z4.boolean(),
+  applicationCursorKeys: z4.boolean(),
+  applicationKeypad: z4.boolean(),
+  /**
+   * `'unknown'` has the same meaning as for the mouse fields: the platform
+   * hides the mode, so the emulator cannot say whether the program asked for
+   * focus events. It is not `'off'`.
+   */
+  focusReporting: z4.enum(["on", "off", "unknown"]),
+  synchronizedOutput: z4.boolean()
+});
+var exitSchema = z4.object({
+  code: z4.number().int().nullable(),
+  signal: z4.string().nullable()
+});
+var signalSchema = z4.enum(SIGNALS);
+var buttonSchema = z4.enum(["left", "middle", "right"]);
+var roleEnum = z4.enum(SEMANTIC_ROLES);
+var STATE_NAMES = FILTERABLE_STATES;
+
+// src/tools.ts
+var semanticFields = {
+  terminal: z5.string(),
+  revision: z5.number().int().describe("screen revision; pass it to terminal.capture_since as cursor"),
+  semanticRevision: z5.number().int().nullable(),
+  semanticTree: semanticTreeState
+};
+function treeState(available) {
+  return available ? "available" : "unavailable";
+}
+function optionalTimeout(timeout) {
+  return timeout === void 0 ? {} : { timeout };
+}
+async function settleSemantics(entry) {
+  if (!entry.harness.capabilities().semanticTree) return;
+  const budget = entry.harness.semanticTree() === null ? FIRST_TREE_SETTLE_MS : PAIRING_SETTLE_MS;
+  try {
+    await entry.harness.waitForStable({ timeout: budget });
+  } catch {
+  }
+}
+var FIRST_TREE_SETTLE_MS = 2e3;
+var PAIRING_SETTLE_MS = 250;
+function capture(context, entry) {
+  const record = context.terminals.record(entry);
+  return {
+    rows: record.rows,
+    refs: record.semantic === null ? [] : refEntries(record.semantic),
+    revision: record.revision,
+    semanticRevision: record.semanticRevision
+  };
+}
+function compactFor(entry, rows, options = {}) {
+  const screen = entry.harness.screen();
+  return formatCompactSnapshot({
+    terminal: entry.id,
+    columns: screen.columns,
+    rows: screen.rows,
+    revision: screen.revision,
+    semantic: entry.harness.semanticTree(),
+    text: rows,
+    ...options
+  });
+}
+function locatorFor(entry, args) {
+  return buildLocator(entry.harness, args);
+}
+function crashOf(entry) {
+  const report = entry.harness.crashReport();
+  return report === null ? void 0 : describeCrash(report);
+}
+var receiptFields = {
+  ok: z5.literal(true),
+  terminal: z5.string(),
+  revision: z5.number().int()
+};
+function receipt(entry) {
+  return { ok: true, terminal: entry.id, revision: entry.harness.screen().revision };
+}
+var launch = defineTool({
+  name: "terminal.launch",
+  title: "Launch a terminal",
+  description: 'Starts a program in a real pseudo-terminal and returns a terminal handle plus the first snapshot. The child gets a minimal environment unless envMode is "inherit"; values passed in env are never echoed back.',
+  inputSchema: {
+    command: z5.array(z5.string()).min(1).describe('argv, e.g. ["node", "app.js"] \u2014 no shell is involved'),
+    cwd: z5.string().optional(),
+    env: z5.record(z5.string(), z5.string()).optional().describe("extra environment for the child"),
+    envMode: z5.enum(["replace", "inherit"]).optional().describe(
+      'default "replace": the child gets PATH, HOME, LANG, LC_ALL, SHELL, TMPDIR, USER, TERM plus env. "inherit" hands it the whole server environment'
+    ),
+    columns: z5.number().int().min(1).max(1e3).optional().describe("default 100"),
+    rows: z5.number().int().min(1).max(1e3).optional().describe("default 30"),
+    scrollbackLines: z5.number().int().min(0).max(1e5).optional(),
+    semanticNegotiationMs: z5.number().int().min(0).max(6e4).optional(),
+    logs: z5.array(
+      z5.object({
+        path: z5.string().min(1).describe("log file to follow for the life of the session"),
+        label: z5.string().optional().describe("short name shown on each entry")
+      })
+    ).max(8).optional().describe(
+      "application log files to follow. An existing file is followed from its end, so a session never replays a previous run; a missing one is waited for"
+    ),
+    timeouts: z5.object({
+      action: z5.number().int().positive().optional(),
+      text: z5.number().int().positive().optional(),
+      idle: z5.number().int().positive().optional(),
+      ready: z5.number().int().positive().optional(),
+      exit: z5.number().int().positive().optional()
+    }).optional()
+  },
+  outputSchema: {
+    ...semanticFields,
+    sessionId: z5.string(),
+    columns: z5.number().int(),
+    rows: z5.number().int(),
+    adapter: z5.object({ name: z5.string(), version: z5.string() }).optional(),
+    capabilities: z5.array(z5.string()),
+    platform: z5.string(),
+    compact: z5.string()
+  },
+  annotations: { openWorldHint: true },
+  handler: async (context, args) => {
+    const entry = await context.terminals.launch(args);
+    await settleSemantics(entry);
+    const capabilities2 = entry.harness.capabilities();
+    const screen = entry.harness.screen();
+    const state = capture(context, entry);
+    const compact = compactFor(entry, state.rows);
+    return {
+      text: compact,
+      data: {
+        terminal: entry.id,
+        sessionId: entry.harness.sessionId,
+        revision: state.revision,
+        semanticRevision: state.semanticRevision,
+        semanticTree: treeState(capabilities2.semanticTree),
+        columns: screen.columns,
+        rows: screen.rows,
+        ...capabilities2.adapter === void 0 ? {} : { adapter: capabilities2.adapter },
+        capabilities: [...capabilities2.capabilities],
+        platform: capabilities2.platform,
+        compact
+      }
+    };
+  }
+});
+var capabilities = defineTool({
+  name: "terminal.capabilities",
+  title: "Session capabilities",
+  description: "What this session supports: whether a semantic tree is published, which adapter publishes it, and the terminal geometry. Call it before relying on role-based targeting.",
+  inputSchema: { terminal: terminalId },
+  outputSchema: {
+    ...semanticFields,
+    columns: z5.number().int(),
+    rows: z5.number().int(),
+    adapter: z5.object({ name: z5.string(), version: z5.string() }).optional(),
+    capabilities: z5.array(z5.string()),
+    platform: z5.string(),
+    crash: crashSchema.optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await settleSemantics(entry);
+    const caps = entry.harness.capabilities();
+    const crash = crashOf(entry);
+    const screen = entry.harness.screen();
+    const semantic = entry.harness.semanticTree();
+    return {
+      text: `Terminal ${entry.id} ${screen.columns}x${screen.rows} revision ${screen.revision}
+semanticTree: ${caps.semanticTree ? "available" : "unavailable"}
+adapter: ${caps.adapter === void 0 ? "none" : `${caps.adapter.name} ${caps.adapter.version}`}
+capabilities: ${caps.capabilities.join(", ") || "none"}
+platform: ${caps.platform}` + (crash === void 0 ? "" : `
+${renderCrash(crash)}`),
+      data: {
+        terminal: entry.id,
+        revision: screen.revision,
+        semanticRevision: semantic?.revision ?? null,
+        semanticTree: treeState(caps.semanticTree),
+        columns: screen.columns,
+        rows: screen.rows,
+        ...caps.adapter === void 0 ? {} : { adapter: caps.adapter },
+        capabilities: [...caps.capabilities],
+        platform: caps.platform,
+        ...crash === void 0 ? {} : { crash }
+      }
+    };
+  }
+});
+var snapshot = defineTool({
+  name: "terminal.snapshot",
+  title: "Snapshot the terminal",
+  description: 'One typed view of the terminal: compact semantic refs, visible text, cursor, terminal modes and scroll position. variant "full" writes the complete dump (text, ANSI, HTML, semantic tree) to disk and returns only refs plus the file path. The returned revision is the cursor for terminal.capture_since.',
+  inputSchema: {
+    terminal: terminalId,
+    variant: z5.enum(["compact", "full"]).optional().describe('default "compact"'),
+    maxNodes: z5.number().int().min(1).max(5e3).optional(),
+    maxRows: z5.number().int().min(1).max(1e4).optional(),
+    includeText: z5.boolean().optional().describe("include the visible grid text (default true)"),
+    screenshot: z5.boolean().optional().describe("also attach a PNG of the screen, rendered without a browser"),
+    screenshotScale: z5.number().min(0.1).max(3).optional().describe("pixel density of the PNG; default 1, 2 is retina-sharp"),
+    screenshotTheme: z5.enum(["dark", "light"]).optional().describe("PNG background; default dark")
+  },
+  outputSchema: {
+    ...semanticFields,
+    cursorValue: z5.number().int().describe("alias of revision, to pass to terminal.capture_since"),
+    columns: z5.number().int(),
+    rows: z5.number().int(),
+    buffer: z5.enum(["normal", "alternate"]),
+    cursor: cursorSchema,
+    modes: modesSchema,
+    scroll: z5.object({
+      offset: z5.number().int(),
+      length: z5.number().int(),
+      retainedFloor: z5.number().int()
+    }),
+    refs: z5.array(refEntrySchema),
+    compact: z5.string(),
+    dumpPath: z5.string().optional(),
+    screenshot: screenshotSchema.optional(),
+    crash: crashSchema.optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await settleSemantics(entry);
+    const state = capture(context, entry);
+    const screen = entry.harness.screen();
+    const semantic = entry.harness.semanticTree();
+    const full = args.variant === "full";
+    const compact = compactFor(entry, state.rows, {
+      ...args.maxNodes === void 0 ? {} : { maxNodes: args.maxNodes },
+      ...args.maxRows === void 0 ? {} : { maxRows: args.maxRows },
+      includeText: full ? false : args.includeText !== false
+    });
+    let dumpPath;
+    if (full) {
+      dumpPath = await context.terminals.writeDump(
+        entry,
+        `snapshot-${screen.revision}.json`,
+        `${JSON.stringify(
+          {
+            terminal: entry.id,
+            revision: screen.revision,
+            columns: screen.columns,
+            rows: screen.rows,
+            text: screen.text(),
+            ansi: screen.ansi(),
+            html: screen.html(),
+            semantic
+          },
+          null,
+          2
+        )}
+`
+      );
+    }
+    const crash = crashOf(entry);
+    const image = args.screenshot === true ? renderScreenshot(screen, {
+      scale: args.screenshotScale,
+      theme: args.screenshotTheme
+    }) : void 0;
+    const trailer = [
+      ...dumpPath === void 0 ? [] : [`full dump: ${dumpPath}`],
+      ...crash === void 0 ? [] : [renderCrash(crash)]
+    ];
+    return {
+      text: trailer.length === 0 ? compact : `${compact}
+${trailer.join("\n")}`,
+      ...image === void 0 ? {} : { images: [image] },
+      data: {
+        terminal: entry.id,
+        revision: screen.revision,
+        cursorValue: screen.revision,
+        semanticRevision: state.semanticRevision,
+        semanticTree: treeState(semantic !== null),
+        columns: screen.columns,
+        rows: screen.rows,
+        buffer: screen.buffer,
+        cursor: screen.cursor,
+        modes: screen.modes,
+        scroll: {
+          offset: entry.harness.scrollback.position(),
+          length: entry.harness.scrollback.length,
+          retainedFloor: entry.harness.scrollback.retainedFloor
+        },
+        refs: state.refs.map((entry2) => ({ ...entry2, flags: [...entry2.flags] })),
+        compact,
+        ...dumpPath === void 0 ? {} : { dumpPath },
+        ...image === void 0 ? {} : { screenshot: describeImage(image) },
+        ...crash === void 0 ? {} : { crash }
+      }
+    };
+  }
+});
+var captureSince = defineTool({
+  name: "terminal.capture_since",
+  title: "What changed since a revision",
+  description: "Incremental view: the screen rows that differ and the semantic subtrees that were added, removed or updated since the given cursor. The cursor must be a revision this server handed out earlier (snapshot or capture_since); older cursors fail with history-truncated.",
+  inputSchema: {
+    terminal: terminalId,
+    cursor: z5.number().int().min(0).describe("revision returned by an earlier snapshot"),
+    maxRows: z5.number().int().min(1).max(1e4).optional(),
+    maxSubtrees: z5.number().int().min(1).max(1e3).optional(),
+    maxLogs: z5.number().int().min(0).max(500).optional().describe(`application log entries to return; default ${LOG_LIMITS.maxPerResponse}, 0 to skip`)
+  },
+  outputSchema: {
+    ...semanticFields,
+    since: z5.number().int(),
+    changedRows: z5.array(z5.object({ row: z5.number().int(), text: z5.string() })),
+    changedSubtrees: z5.array(
+      z5.object({
+        change: z5.enum(["added", "removed", "updated"]),
+        ref: z5.string(),
+        role: z5.string(),
+        name: z5.string(),
+        compact: z5.string()
+      })
+    ),
+    logs: z5.array(logEntrySchema),
+    logsOmitted: z5.number().int().describe("entries dropped between the cursor and the oldest one still buffered"),
+    logCursor: z5.number().int().describe("newest log sequence seen; advances with every capture"),
+    compact: z5.string()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await settleSemantics(entry);
+    const before = context.terminals.baseline(entry, args.cursor);
+    const after = context.terminals.record(entry);
+    const rowLimit = args.maxRows ?? 200;
+    const subtreeLimit = args.maxSubtrees ?? 100;
+    const changedRows = diffRows(before.rows, after.rows).slice(0, rowLimit);
+    const changedSubtrees = diffSemantic(before.semantic, after.semantic).slice(0, subtreeLimit);
+    const logs = entry.logs.since(before.logSeq, args.maxLogs ?? LOG_LIMITS.maxPerResponse);
+    const lines = [
+      `Terminal ${entry.id} revision ${after.revision} (since ${args.cursor})`,
+      `semanticTree: ${after.semantic === null ? "unavailable" : "available"}`
+    ];
+    lines.push(`changed rows: ${changedRows.length}`);
+    for (const row of changedRows) lines.push(`  ${row.row}: ${row.text}`);
+    lines.push(`changed nodes: ${changedSubtrees.length}`);
+    for (const subtree of changedSubtrees) {
+      const marker = subtree.change === "added" ? "+" : subtree.change === "removed" ? "-" : "~";
+      for (const line of subtree.compact.split("\n")) lines.push(`  ${marker} ${line}`);
+    }
+    lines.push(renderLogs(logs));
+    return {
+      text: lines.join("\n"),
+      data: {
+        terminal: entry.id,
+        revision: after.revision,
+        semanticRevision: after.semanticRevision,
+        semanticTree: treeState(after.semantic !== null),
+        since: args.cursor,
+        changedRows: changedRows.map((row) => ({ ...row })),
+        changedSubtrees: changedSubtrees.map((subtree) => ({ ...subtree })),
+        logs: logs.entries.map((log) => ({ ...log })),
+        logsOmitted: logs.omitted,
+        logCursor: logs.cursor,
+        compact: lines.join("\n")
+      }
+    };
+  }
+});
+var query = defineTool({
+  name: "terminal.query",
+  title: "Find matching nodes",
+  description: "Resolves a target to refs without acting on it. Use it to check how many nodes a locator matches before clicking, or to turn a role/name into a ref.",
+  inputSchema: {
+    terminal: terminalId,
+    ...targetShape,
+    timeout: timeoutMs.optional(),
+    limit: z5.number().int().min(1).max(100).optional().describe("default 20")
+  },
+  outputSchema: {
+    terminal: z5.string(),
+    revision: z5.number().int(),
+    count: z5.number().int(),
+    matches: z5.array(
+      z5.object({
+        ref: z5.string(),
+        revision: z5.number().int(),
+        semantic: z5.boolean(),
+        role: z5.string().optional(),
+        name: z5.string().optional(),
+        bounds: refEntrySchema.shape.bounds
+      })
+    )
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await settleSemantics(entry);
+    const locator = locatorFor(entry, args);
+    const limit = args.limit ?? 20;
+    const count = await locator.count();
+    const matches = [];
+    for (let index = 0; index < Math.min(count, limit); index += 1) {
+      const target = await locator.nth(index).resolve(optionalTimeout(args.timeout));
+      matches.push({
+        ref: target.ref,
+        revision: target.revision,
+        semantic: target.semantic,
+        ...target.role === void 0 ? {} : { role: target.role },
+        ...target.name === void 0 ? {} : { name: target.name },
+        ...target.rect === null ? {} : { bounds: target.rect }
+      });
+    }
+    const text = matches.length === 0 ? `no matches (count ${count})` : matches.map(
+      (match) => `${match.role ?? "generic"} ${JSON.stringify(match.name ?? "")} ref=${match.ref}`
+    ).join("\n");
+    return {
+      text,
+      data: { terminal: entry.id, revision: entry.harness.screen().revision, count, matches }
+    };
+  }
+});
+function pointerTool(name) {
+  const double = name === "terminal.double_click";
+  return defineTool({
+    name,
+    title: double ? "Double-click a target" : "Click a target",
+    description: `Sends a real ${double ? "double " : ""}mouse report through the pseudo-terminal. Fails with unsupported-action when the program never enabled mouse tracking. Where the platform hides the mode (modes.mouseTracking "unknown", e.g. Windows ConPTY) the click is sent anyway, encoded as SGR.`,
+    inputSchema: {
+      terminal: terminalId,
+      ...targetShape,
+      button: buttonSchema.optional(),
+      position: z5.object({ rowOffset: z5.number().int(), columnOffset: z5.number().int() }).optional().describe("offset inside the target rectangle"),
+      timeout: timeoutMs.optional()
+    },
+    outputSchema: { ...receiptFields, ref: z5.string() },
+    handler: async (context, args) => {
+      const entry = context.terminals.get(args.terminal);
+      const locator = locatorFor(entry, args);
+      const target = await locator.resolve(optionalTimeout(args.timeout));
+      const options = {
+        ...optionalTimeout(args.timeout),
+        ...args.button === void 0 ? {} : { button: args.button },
+        ...args.position === void 0 ? {} : { position: args.position }
+      };
+      if (double) await locator.doubleClick(options);
+      else await locator.click(options);
+      return {
+        text: `${double ? "double-clicked" : "clicked"} ref=${target.ref}`,
+        data: { ...receipt(entry), ref: target.ref }
+      };
+    }
+  });
+}
+var press = defineTool({
+  name: "terminal.press",
+  title: "Press keys",
+  description: 'Sends key chords as real bytes, honouring the modes the program enabled (application cursor keys, keypad). Examples: "Enter", "Escape", "Control+K Control+U". With a target, the node is focused first.',
+  inputSchema: {
+    terminal: terminalId,
+    keys: z5.string().min(1).describe('space-separated chords, e.g. "Control+A Home"'),
+    ...targetShape,
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: { ...receiptFields, ref: z5.string().optional() },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    if (hasTarget(args)) {
+      const locator = locatorFor(entry, args);
+      const target = await locator.resolve(optionalTimeout(args.timeout));
+      await locator.press(args.keys, optionalTimeout(args.timeout));
+      return { text: `pressed ${args.keys} on ref=${target.ref}`, data: { ...receipt(entry), ref: target.ref } };
+    }
+    await entry.harness.press(args.keys);
+    return { text: `pressed ${args.keys}`, data: receipt(entry) };
+  }
+});
+var type = defineTool({
+  name: "terminal.type",
+  title: "Type text",
+  description: "Types text as individual keystrokes (not a paste). With a target, the node is focused first.",
+  inputSchema: {
+    terminal: terminalId,
+    text: z5.string(),
+    ...targetShapeWithoutText,
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: { ...receiptFields, ref: z5.string().optional() },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    if (hasTarget(args)) {
+      const locator = locatorFor(entry, args);
+      const target = await locator.resolve(optionalTimeout(args.timeout));
+      await locator.type(args.text, optionalTimeout(args.timeout));
+      return { text: `typed into ref=${target.ref}`, data: { ...receipt(entry), ref: target.ref } };
+    }
+    await entry.harness.type(args.text);
+    return { text: `typed ${args.text.length} characters`, data: receipt(entry) };
+  }
+});
+var paste = defineTool({
+  name: "terminal.paste",
+  title: "Paste text",
+  description: "Pastes text, wrapped in bracketed-paste markers when the program enabled that mode. Use it for multi-line input instead of terminal.type.",
+  inputSchema: { terminal: terminalId, text: z5.string() },
+  outputSchema: receiptFields,
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await entry.harness.paste(args.text);
+    return { text: `pasted ${args.text.length} characters`, data: receipt(entry) };
+  }
+});
+var writeRaw = defineTool({
+  name: "terminal.write_raw",
+  title: "Write raw bytes",
+  description: "Writes bytes to the pseudo-terminal verbatim \u2014 no newline, no key encoding. The escape hatch for sequences the key encoder does not model.",
+  inputSchema: {
+    terminal: terminalId,
+    data: z5.string(),
+    encoding: z5.enum(["utf8", "base64"]).optional().describe('default "utf8"')
+  },
+  outputSchema: { ...receiptFields, bytes: z5.number().int() },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const bytes = args.encoding === "base64" ? new Uint8Array(Buffer.from(args.data, "base64")) : args.data;
+    await entry.harness.write(bytes);
+    const length = typeof bytes === "string" ? Buffer.byteLength(bytes) : bytes.byteLength;
+    return { text: `wrote ${length} bytes`, data: { ...receipt(entry), bytes: length } };
+  }
+});
+var drag = defineTool({
+  name: "terminal.drag",
+  title: "Drag",
+  description: "Drags with real mouse reports: either from one target to another (toTarget), or between two cell positions inside the source target (from/to).",
+  inputSchema: {
+    terminal: terminalId,
+    ...targetShape,
+    toTarget: targetObject.optional().describe("drop target; omit when using from/to"),
+    from: cellPosition.optional(),
+    to: cellPosition.optional(),
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: receiptFields,
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const source = locatorFor(entry, args);
+    if (args.toTarget !== void 0) {
+      await source.dragTo(locatorFor(entry, args.toTarget), optionalTimeout(args.timeout));
+      return { text: "dragged to target", data: receipt(entry) };
+    }
+    if (args.from === void 0 || args.to === void 0) {
+      throw usageError("drag needs either toTarget, or both from and to");
+    }
+    await source.drag({ from: args.from, to: args.to });
+    return {
+      text: `dragged (${args.from.row},${args.from.column}) -> (${args.to.row},${args.to.column})`,
+      data: receipt(entry)
+    };
+  }
+});
+var wheel = defineTool({
+  name: "terminal.wheel",
+  title: "Scroll with the wheel",
+  description: "Sends wheel reports over a target. Positive deltaY scrolls down.",
+  inputSchema: {
+    terminal: terminalId,
+    ...targetShape,
+    deltaY: z5.number().int(),
+    deltaX: z5.number().int().optional()
+  },
+  outputSchema: receiptFields,
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await locatorFor(entry, args).wheel({
+      deltaY: args.deltaY,
+      ...args.deltaX === void 0 ? {} : { deltaX: args.deltaX }
+    });
+    return { text: `wheel deltaY=${args.deltaY}`, data: receipt(entry) };
+  }
+});
+var resize = defineTool({
+  name: "terminal.resize",
+  title: "Resize the terminal",
+  description: "Resizes the pseudo-terminal; the child sees a real SIGWINCH.",
+  inputSchema: {
+    terminal: terminalId,
+    columns: z5.number().int().min(1).max(1e3),
+    rows: z5.number().int().min(1).max(1e3)
+  },
+  outputSchema: { ...receiptFields, columns: z5.number().int(), rows: z5.number().int() },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await entry.harness.resize({ columns: args.columns, rows: args.rows });
+    return {
+      text: `resized to ${args.columns}x${args.rows}`,
+      data: { ...receipt(entry), columns: args.columns, rows: args.rows }
+    };
+  }
+});
+var signal = defineTool({
+  name: "terminal.signal",
+  title: "Send a signal",
+  description: "Sends INT, TERM, KILL or HUP to the child. Destructive by design: terminal.close cleans up without signalling.",
+  inputSchema: { terminal: terminalId, signal: signalSchema },
+  outputSchema: receiptFields,
+  annotations: { destructiveHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    await entry.harness.signal(args.signal);
+    return { text: `sent SIG${args.signal}`, data: receipt(entry) };
+  }
+});
+var scrollback = defineTool({
+  name: "terminal.scrollback",
+  title: "Read or move the scrollback",
+  description: "Emulator-side history: read a line range, search it, or move the viewport. The child sees nothing \u2014 no input is sent.",
+  inputSchema: {
+    terminal: terminalId,
+    move: z5.number().int().optional().describe("lines to move the viewport; negative scrolls up"),
+    from: z5.number().int().min(0).optional(),
+    to: z5.number().int().min(0).optional(),
+    search: z5.string().optional().describe('literal text, or "/pattern/flags"'),
+    limit: z5.number().int().min(1).max(1e3).optional().describe("max search hits (default 50)")
+  },
+  outputSchema: {
+    terminal: z5.string(),
+    length: z5.number().int(),
+    retainedFloor: z5.number().int(),
+    position: z5.number().int(),
+    text: z5.string().optional(),
+    matches: z5.array(z5.object({ line: z5.number().int(), match: z5.string() })).optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const api = entry.harness.scrollback;
+    if (args.move !== void 0) api.move({ lines: args.move });
+    const wantsText = args.from !== void 0 || args.to !== void 0 || args.search === void 0;
+    const text = wantsText ? api.text({
+      ...args.from === void 0 ? {} : { from: args.from },
+      ...args.to === void 0 ? {} : { to: args.to }
+    }) : void 0;
+    const matches = args.search === void 0 ? void 0 : api.search(textOrRegExp(args.search)).slice(0, args.limit ?? 50);
+    const lines = [
+      `scrollback length ${api.length} floor ${api.retainedFloor} position ${api.position()}`
+    ];
+    if (matches !== void 0) {
+      lines.push(...matches.map((match) => `  ${match.line}: ${match.match}`));
+    }
+    if (text !== void 0) lines.push(text);
+    return {
+      text: lines.join("\n"),
+      data: {
+        terminal: entry.id,
+        length: api.length,
+        retainedFloor: api.retainedFloor,
+        position: api.position(),
+        ...text === void 0 ? {} : { text },
+        ...matches === void 0 ? {} : { matches: matches.map((match) => ({ ...match })) }
+      }
+    };
+  }
+});
+var selectCells = defineTool({
+  name: "terminal.select_cells",
+  title: "Select a cell range",
+  description: "Selects a rectangle in the emulator (like a mouse selection). No input is sent.",
+  inputSchema: { terminal: terminalId, start: cellPosition, end: cellPosition },
+  outputSchema: receiptFields,
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    entry.harness.selection.selectCells({ start: args.start, end: args.end });
+    return {
+      text: `selected (${args.start.row},${args.start.column})-(${args.end.row},${args.end.column})`,
+      data: receipt(entry)
+    };
+  }
+});
+var copySelection = defineTool({
+  name: "terminal.copy_selection",
+  title: "Copy the selection",
+  description: "Returns the text of the current selection and optionally clears it.",
+  inputSchema: { terminal: terminalId, clear: z5.boolean().optional() },
+  outputSchema: { terminal: z5.string(), text: z5.string() },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const text = entry.harness.selection.copy();
+    if (args.clear === true) entry.harness.selection.clear();
+    return { text, data: { terminal: entry.id, text } };
+  }
+});
+var waitFor = defineTool({
+  name: "terminal.wait_for",
+  title: "Wait for a condition",
+  description: 'Revision-driven waits \u2014 never a sleep. "text"/"title" wait for content, "visible"/"hidden"/"attached" wait on a target, "stable" waits for renders to settle, "idle" for output to stop, "render" for a render after a given revision, "exit" for the child to exit.',
+  inputSchema: {
+    terminal: terminalId,
+    wait: z5.enum(["text", "title", "visible", "hidden", "attached", "stable", "idle", "render", "exit"]),
+    text: z5.string().optional().describe('for wait="text"; "/pattern/flags" is a regular expression'),
+    title: z5.string().optional().describe('for wait="title"'),
+    ...targetShapeWithoutText,
+    frames: z5.number().int().min(1).optional().describe('for wait="stable"'),
+    after: z5.number().int().min(0).optional().describe('for wait="render": the revision to beat'),
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: {
+    ...receiptFields,
+    wait: z5.string(),
+    exit: exitSchema.optional()
+  },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const timeout = optionalTimeout(args.timeout);
+    switch (args.wait) {
+      case "text": {
+        if (args.text === void 0) throw usageError('wait="text" needs text');
+        await entry.harness.waitForText(textOrRegExp(args.text), timeout);
+        break;
+      }
+      case "title": {
+        if (args.title === void 0) throw usageError('wait="title" needs title');
+        await entry.harness.waitForTitle(textOrRegExp(args.title), timeout);
+        break;
+      }
+      case "visible":
+      case "hidden":
+      case "attached": {
+        await locatorFor(entry, args).waitFor({ state: args.wait, ...timeout });
+        break;
+      }
+      case "stable": {
+        await entry.harness.waitForStable({
+          ...args.frames === void 0 ? {} : { frames: args.frames },
+          ...timeout
+        });
+        break;
+      }
+      case "idle": {
+        await entry.harness.waitForIdle(timeout);
+        break;
+      }
+      case "render": {
+        if (args.after === void 0) throw usageError('wait="render" needs after');
+        await entry.harness.waitForRender({ after: args.after, ...timeout });
+        break;
+      }
+      case "exit": {
+        const status = await entry.harness.waitForExit(timeout);
+        return {
+          text: `exited code=${String(status.code)} signal=${String(status.signal)}`,
+          data: { ...receipt(entry), wait: args.wait, exit: status }
+        };
+      }
+    }
+    return { text: `wait ${args.wait} satisfied`, data: { ...receipt(entry), wait: args.wait } };
+  }
+});
+var close = defineTool({
+  name: "terminal.close",
+  title: "Close a terminal",
+  description: "Bounded physical cleanup: hangs up the pseudo-terminal and forgets the handle. Send signals explicitly with terminal.signal if the child must be killed first.",
+  inputSchema: { terminal: terminalId },
+  outputSchema: { ok: z5.literal(true), terminal: z5.string(), exit: exitSchema.nullable() },
+  annotations: { idempotentHint: true },
+  handler: async (context, args) => {
+    const entry = await context.terminals.close(args.terminal);
+    return {
+      text: `closed ${entry.id}`,
+      data: { ok: true, terminal: entry.id, exit: entry.exit }
+    };
+  }
+});
+var TERMINAL_TOOLS = Object.freeze([
+  launch,
+  capabilities,
+  snapshot,
+  captureSince,
+  query,
+  pointerTool("terminal.click"),
+  pointerTool("terminal.double_click"),
+  press,
+  type,
+  paste,
+  writeRaw,
+  drag,
+  wheel,
+  resize,
+  signal,
+  scrollback,
+  selectCells,
+  copySelection,
+  waitFor,
+  close
+]);
+
+// src/trace-tools.ts
+import { z as z6 } from "zod";
+import { frameFromAnsi } from "@termwright/trace";
+var traceId = z6.string().min(1).describe('trace handle returned by trace.open, e.g. "tr1"');
+var screenshotShape = {
+  screenshot: z6.boolean().optional().describe("also attach a PNG of the reconstructed frame, rendered without a browser"),
+  screenshotScale: z6.number().min(0.1).max(3).optional().describe("pixel density of the PNG; default 1, 2 is retina-sharp"),
+  screenshotTheme: z6.enum(["dark", "light"]).optional().describe("PNG background; default dark")
+};
+var metaSchema = z6.object({
+  sessionId: z6.string(),
+  command: z6.array(z6.string()),
+  columns: z6.number().int(),
+  rows: z6.number().int(),
+  startedAt: z6.string(),
+  platform: z6.string(),
+  semanticTree: z6.boolean(),
+  durationMs: z6.number().optional(),
+  truncated: z6.boolean().optional(),
+  exit: z6.object({ code: z6.number().int().nullable(), signal: z6.string().nullable() }).optional()
+});
+function crashOfMeta(meta) {
+  const crash = meta.crash;
+  if (crash === void 0) return void 0;
+  const parsed = crashSchema.safeParse({
+    exit: crash.exit,
+    timeMs: crash.castOffset,
+    screenTail: crash.screenTail,
+    screenTailTruncated: false,
+    lastSemanticRevision: crash.lastSemanticRevision ?? null,
+    recentInputs: crash.recentInputs ?? [],
+    diagnostics: crash.diagnosticsTail ?? []
+  });
+  return parsed.success ? parsed.data : void 0;
+}
+function projectMeta(meta) {
+  return {
+    sessionId: meta.sessionId,
+    command: [...meta.command],
+    columns: meta.columns,
+    rows: meta.rows,
+    startedAt: meta.startedAt,
+    platform: meta.platform,
+    semanticTree: meta.semanticTree,
+    ...meta.durationMs === void 0 ? {} : { durationMs: meta.durationMs },
+    ...meta.truncated === void 0 ? {} : { truncated: meta.truncated },
+    ...meta.exit === void 0 ? {} : { exit: { code: meta.exit.code, signal: meta.exit.signal } }
+  };
+}
+var stepSchema = z6.object({
+  index: z6.number().int(),
+  stepId: z6.string(),
+  title: z6.string(),
+  parentStepId: z6.string().optional(),
+  status: z6.enum(["passed", "failed", "skipped"]).nullable(),
+  error: z6.string().optional(),
+  castOffset: z6.number(),
+  castEndOffset: z6.number().nullable()
+});
+function projectStep(step, index) {
+  return {
+    index,
+    stepId: step.stepId,
+    title: step.title,
+    ...step.parentStepId === void 0 ? {} : { parentStepId: step.parentStepId },
+    status: step.status,
+    ...step.error === void 0 ? {} : { error: step.error },
+    castOffset: step.castOffset,
+    castEndOffset: step.castEndOffset
+  };
+}
+async function markersOf(reader) {
+  const markers = [];
+  for await (const event of reader.castEvents()) {
+    if (event.code === "m") markers.push({ timeMs: event.timeMs, label: event.data });
+  }
+  return markers;
+}
+function fromTraceLog(entry, index) {
+  return {
+    seq: entry.seq ?? index + 1,
+    timeMs: entry.castOffset,
+    source: entry.source,
+    ...entry.label === void 0 ? {} : { label: entry.label },
+    ...entry.level === void 0 ? {} : { level: entry.level },
+    message: entry.message,
+    ...entry.attrs === void 0 ? {} : { attrs: { ...entry.attrs } }
+  };
+}
+async function logsBetween(reader, fromMs, toMs, limit) {
+  if (limit <= 0) return { entries: [], omitted: 0 };
+  const window = [];
+  let index = 0;
+  let seen = 0;
+  for await (const entry of reader.logs()) {
+    if (entry.castOffset > fromMs && entry.castOffset <= toMs) {
+      seen += 1;
+      window.push(fromTraceLog(entry, index));
+      if (window.length > limit) window.shift();
+    }
+    index += 1;
+  }
+  return { entries: window, omitted: seen - window.length };
+}
+async function frameAt(trace, timeMs, logWindow = 20) {
+  const state = await trace.reader.stateAt(timeMs, { logWindow });
+  const grid = await frameFromAnsi(state.castPrefix, {
+    columns: state.columns,
+    rows: state.rows,
+    timeMs: state.timeMs,
+    semanticRevision: state.nearestSemanticRevision
+  });
+  return {
+    grid,
+    timeMs: state.timeMs,
+    columns: state.columns,
+    rows: state.rows,
+    lines: grid.text().split("\n"),
+    semantic: state.nearestSemantic?.snapshot ?? null,
+    semanticRevision: state.nearestSemanticRevision,
+    step: state.step,
+    logs: state.logs.map((entry, index) => fromTraceLog(entry, index))
+  };
+}
+async function resolveTime(trace, args) {
+  const given = [args.timeMs, args.stepIndex, args.marker].filter((value) => value !== void 0);
+  if (given.length !== 1) {
+    throw usageError(
+      "give exactly one of timeMs, stepIndex or marker",
+      "trace.overview lists step indexes and marker labels"
+    );
+  }
+  if (args.timeMs !== void 0) return args.timeMs;
+  if (args.stepIndex !== void 0) {
+    const steps = await trace.reader.steps();
+    const step = steps[args.stepIndex];
+    if (step === void 0) {
+      throw usageError(
+        `no step ${args.stepIndex}; the trace has ${steps.length}`,
+        "call trace.overview for the step list"
+      );
+    }
+    return step.castOffset;
+  }
+  const label = args.marker ?? "";
+  const markers = await markersOf(trace.reader);
+  const marker = markers.find((candidate) => candidate.label === label);
+  if (marker === void 0) {
+    throw usageError(
+      `no marker ${JSON.stringify(label)}`,
+      markers.length === 0 ? "this recording has no markers; use stepIndex or timeMs" : `markers: ${markers.map((candidate) => JSON.stringify(candidate.label)).join(", ")}`
+    );
+  }
+  return marker.timeMs;
+}
+function renderFrame(trace, frame2, maxRows) {
+  return formatCompactSnapshot({
+    terminal: trace.id,
+    columns: frame2.columns,
+    rows: frame2.rows,
+    revision: frame2.semanticRevision ?? 0,
+    semantic: frame2.semantic,
+    text: frame2.lines,
+    maxRows: maxRows ?? TRACE_LIMITS.maxFrameRows
+  });
+}
+var open = defineTool({
+  name: "trace.open",
+  title: "Open a trace archive",
+  description: "Validates a .twtrace directory or zip and returns a handle plus its metadata: the recorded command, viewport, duration, exit status and whether the session published a semantic tree. Start every replay investigation here.",
+  inputSchema: {
+    path: z6.string().min(1).describe("path to a .twtrace directory or zip")
+  },
+  outputSchema: {
+    traceId: z6.string(),
+    path: z6.string(),
+    meta: metaSchema,
+    steps: z6.number().int(),
+    evicted: z6.string().nullable().describe("handle closed to make room, if the open-trace ceiling was reached")
+  },
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  handler: async (context, args) => {
+    const { trace, evicted } = await context.traces.open(args.path);
+    const meta = trace.reader.meta;
+    const steps = await trace.reader.steps();
+    const exit = meta.exit;
+    return {
+      text: [
+        `Trace ${trace.id} ${meta.command.join(" ")} ${meta.columns}x${meta.rows}`,
+        `recorded: ${meta.startedAt} on ${meta.platform}`,
+        `semanticTree: ${meta.semanticTree ? "available" : "unavailable"}`,
+        `steps: ${steps.length}`,
+        exit === void 0 ? "exit: not recorded" : `exit: code=${String(exit.code)} signal=${String(exit.signal)}`,
+        ...meta.truncated === true ? ["warning: recording was truncated at a size limit"] : [],
+        ...evicted === null ? [] : [`note: closed ${evicted} to stay within the open-trace ceiling`]
+      ].join("\n"),
+      data: {
+        traceId: trace.id,
+        path: trace.path,
+        meta: projectMeta(meta),
+        steps: steps.length,
+        evicted
+      }
+    };
+  }
+});
+var overview = defineTool({
+  name: "trace.overview",
+  title: "Summarise a trace",
+  description: "The shape of a recording: every step with its status and timing, the cast markers, the exit status, and which step failed. Use it to pick the moment worth reconstructing before calling trace.frame_at.",
+  inputSchema: { traceId },
+  outputSchema: {
+    traceId: z6.string(),
+    durationMs: z6.number().nullable(),
+    semanticTree: semanticTreeState,
+    exit: z6.object({ code: z6.number().int().nullable(), signal: z6.string().nullable() }).nullable(),
+    truncated: z6.boolean(),
+    steps: z6.array(stepSchema),
+    failedSteps: z6.array(stepSchema),
+    markers: z6.array(z6.object({ timeMs: z6.number(), label: z6.string() })),
+    crash: crashSchema.optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const trace = context.traces.get(args.traceId);
+    const meta = trace.reader.meta;
+    const steps = (await trace.reader.steps()).map(projectStep);
+    const failedSteps = steps.filter((step) => step.status === "failed");
+    const markers = [...await markersOf(trace.reader)];
+    const lines = [
+      `Trace ${trace.id} ${meta.command.join(" ")} ${meta.columns}x${meta.rows}`,
+      `semanticTree: ${meta.semanticTree ? "available" : "unavailable"}`,
+      `duration: ${meta.durationMs === void 0 ? "unknown" : `${meta.durationMs} ms`}`,
+      `exit: ${meta.exit === void 0 ? "not recorded" : `code=${String(meta.exit.code)} signal=${String(meta.exit.signal)}`}`,
+      `steps: ${steps.length}${failedSteps.length === 0 ? "" : ` (${failedSteps.length} failed)`}`
+    ];
+    for (const step of steps) {
+      const status = step.status ?? "unfinished";
+      const window = `${step.castOffset}..${step.castEndOffset === null ? "?" : step.castEndOffset}ms`;
+      lines.push(
+        `  [${step.index}] ${status} ${JSON.stringify(step.title)} ${window}` + (step.error === void 0 ? "" : `
+      ${step.error}`)
+      );
+    }
+    if (markers.length > 0) {
+      lines.push(`markers: ${markers.map((marker) => `${marker.timeMs}ms ${marker.label}`).join(", ")}`);
+    }
+    const crash = crashOfMeta(meta);
+    if (crash !== void 0) lines.push(renderCrash(crash));
+    return {
+      text: lines.join("\n"),
+      data: {
+        traceId: trace.id,
+        durationMs: meta.durationMs ?? null,
+        semanticTree: meta.semanticTree ? "available" : "unavailable",
+        exit: meta.exit === void 0 ? null : { code: meta.exit.code, signal: meta.exit.signal },
+        truncated: meta.truncated === true,
+        steps,
+        failedSteps,
+        markers,
+        ...crash === void 0 ? {} : { crash }
+      }
+    };
+  }
+});
+var frame = defineTool({
+  name: "trace.frame_at",
+  title: "Reconstruct one moment",
+  description: "Rebuilds the screen at a moment \u2014 named by timeMs, stepIndex or marker \u2014 by replaying the recording into a headless emulator, and pairs it with the semantic tree of the nearest revision at or before that moment. Reads exactly like a live terminal.snapshot.",
+  inputSchema: {
+    traceId,
+    timeMs: z6.number().min(0).optional().describe("cast-timeline offset in milliseconds"),
+    stepIndex: z6.number().int().min(0).optional().describe("step index from trace.overview"),
+    marker: z6.string().optional().describe("cast marker label from trace.overview"),
+    maxRows: z6.number().int().min(1).max(1e4).optional(),
+    maxLogs: z6.number().int().min(0).max(500).optional().describe("preceding application log entries to include; default 20, 0 to skip"),
+    ...screenshotShape
+  },
+  outputSchema: {
+    traceId: z6.string(),
+    timeMs: z6.number(),
+    columns: z6.number().int(),
+    rows: z6.number().int(),
+    semanticRevision: z6.number().int().nullable(),
+    semanticTree: semanticTreeState,
+    step: stepSchema.partial().nullable(),
+    refs: z6.array(refEntrySchema),
+    logs: z6.array(logEntrySchema),
+    compact: z6.string(),
+    screenshot: screenshotSchema.optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const trace = context.traces.get(args.traceId);
+    const at = await resolveTime(trace, args);
+    const reconstructed = await frameAt(trace, at, args.maxLogs ?? 20);
+    const compact = renderFrame(trace, reconstructed, args.maxRows);
+    const logs = reconstructed.logs.length === 0 ? "" : `
+${renderLogs({ entries: reconstructed.logs, omitted: 0, cursor: 0 })}`;
+    const step = reconstructed.step;
+    const image = args.screenshot === true ? renderScreenshot(reconstructed.grid, {
+      scale: args.screenshotScale,
+      theme: args.screenshotTheme
+    }) : void 0;
+    return {
+      text: `${compact}${logs}`,
+      ...image === void 0 ? {} : { images: [image] },
+      data: {
+        traceId: trace.id,
+        timeMs: reconstructed.timeMs,
+        columns: reconstructed.columns,
+        rows: reconstructed.rows,
+        semanticRevision: reconstructed.semanticRevision,
+        semanticTree: reconstructed.semantic === null ? "unavailable" : "available",
+        step: step === null ? null : projectStep(step, 0),
+        refs: reconstructed.semantic === null ? [] : refEntries(reconstructed.semantic).map((entry) => ({ ...entry, flags: [...entry.flags] })),
+        logs: reconstructed.logs.map((entry) => ({ ...entry })),
+        compact,
+        ...image === void 0 ? {} : { screenshot: describeImage(image) }
+      }
+    };
+  }
+});
+var diff = defineTool({
+  name: "trace.diff",
+  title: "What changed between two moments",
+  description: "Reconstructs two moments of a recording and reports what moved: changed screen rows and changed semantic subtrees, in the same shape as terminal.capture_since on a live session.",
+  inputSchema: {
+    traceId,
+    fromMs: z6.number().min(0),
+    toMs: z6.number().min(0),
+    maxRows: z6.number().int().min(1).max(1e4).optional(),
+    maxSubtrees: z6.number().int().min(1).max(1e3).optional(),
+    maxLogs: z6.number().int().min(0).max(500).optional().describe(`application log entries between the two moments; default ${LOG_LIMITS.maxPerResponse}, 0 to skip`)
+  },
+  outputSchema: {
+    traceId: z6.string(),
+    fromMs: z6.number(),
+    toMs: z6.number(),
+    semanticTree: semanticTreeState,
+    changedRows: z6.array(z6.object({ row: z6.number().int(), text: z6.string() })),
+    changedSubtrees: z6.array(
+      z6.object({
+        change: z6.enum(["added", "removed", "updated"]),
+        ref: z6.string(),
+        role: z6.string(),
+        name: z6.string(),
+        compact: z6.string()
+      })
+    ),
+    logs: z6.array(logEntrySchema),
+    logsOmitted: z6.number().int(),
+    compact: z6.string()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    if (args.toMs < args.fromMs) {
+      throw usageError("toMs must not precede fromMs", "swap the two, or read trace.overview for the timeline");
+    }
+    const trace = context.traces.get(args.traceId);
+    const before = await frameAt(trace, args.fromMs, 0);
+    const after = await frameAt(trace, args.toMs, 0);
+    const logs = await logsBetween(
+      trace.reader,
+      before.timeMs,
+      after.timeMs,
+      args.maxLogs ?? LOG_LIMITS.maxPerResponse
+    );
+    const changedRows = diffRows(before.lines, after.lines).slice(
+      0,
+      args.maxRows ?? TRACE_LIMITS.maxFrameRows
+    );
+    const changedSubtrees = diffSemantic(before.semantic, after.semantic).slice(
+      0,
+      args.maxSubtrees ?? 100
+    );
+    const lines = [
+      `Trace ${trace.id} ${before.timeMs}ms -> ${after.timeMs}ms`,
+      `semanticTree: ${after.semantic === null ? "unavailable" : "available"}`,
+      `changed rows: ${changedRows.length}`,
+      ...changedRows.map((row) => `  ${row.row}: ${row.text}`),
+      `changed nodes: ${changedSubtrees.length}`
+    ];
+    for (const subtree of changedSubtrees) {
+      const marker = subtree.change === "added" ? "+" : subtree.change === "removed" ? "-" : "~";
+      for (const line of subtree.compact.split("\n")) lines.push(`  ${marker} ${line}`);
+    }
+    lines.push(renderLogs({ entries: logs.entries, omitted: logs.omitted, cursor: 0 }));
+    return {
+      text: lines.join("\n"),
+      data: {
+        traceId: trace.id,
+        fromMs: before.timeMs,
+        toMs: after.timeMs,
+        semanticTree: after.semantic === null ? "unavailable" : "available",
+        changedRows: changedRows.map((row) => ({ ...row })),
+        changedSubtrees: changedSubtrees.map((subtree) => ({ ...subtree })),
+        logs: logs.entries.map((entry) => ({ ...entry })),
+        logsOmitted: logs.omitted,
+        compact: lines.join("\n")
+      }
+    };
+  }
+});
+var TRACE_TOOLS = Object.freeze([open, overview, frame, diff]);
+
+// src/registry.ts
+var TOOLS = Object.freeze([...TERMINAL_TOOLS, ...TRACE_TOOLS]);
+function toolByName(name) {
+  return TOOLS.find((tool) => tool.name === name);
+}
+
+// src/version.ts
+var SERVER_NAME = "termwright";
+var SERVER_VERSION = "0.1.0";
+var AGENT_CONTEXT_VERSION = 1;
+
+// src/agent-context.ts
+import { z as z7 } from "zod";
+var DRIVER_ERROR_KINDS = [
+  "timeout",
+  "stale-snapshot",
+  "ambiguous-locator",
+  "unsupported-action",
+  "history-truncated",
+  "protocol-violation",
+  "capacity",
+  "process-exited",
+  "session-closed"
+];
+var ERROR_KINDS = [...DRIVER_ERROR_KINDS, ...MCP_ERROR_KINDS];
+var CONVENTIONS = [
+  'A ref looks like n8@42: node id at semantic revision 42. It is valid only while 42 is the live semantic revision; reusing it later fails with kind "stale-snapshot" \u2014 take a fresh snapshot.',
+  "terminal.snapshot returns a screen revision; pass it to terminal.capture_since as cursor to get only the rows and semantic subtrees that changed.",
+  'Any name or text argument may be written as "/pattern/flags" to match as a regular expression.',
+  "Targeting precedence is ref, selector, testId, role (+name), label, text.",
+  'Locators are strict: more than one match fails with kind "ambiguous-locator" unless nth is given.',
+  'semanticTree "unavailable" means the program ships no adapter \u2014 target by text, never by role.',
+  "Errors are returned as tool results with isError set; structuredContent.error.kind is the value to branch on, and structuredContent.error.suggestion says what to try next."
+];
+function toJsonSchema(shape) {
+  return z7.toJSONSchema(z7.object(shape), { io: "input" });
+}
+function buildAgentContext() {
+  return {
+    v: AGENT_CONTEXT_VERSION,
+    server: { name: SERVER_NAME, version: SERVER_VERSION },
+    tools: TOOLS.map((tool) => ({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: toJsonSchema(tool.inputSchema),
+      outputSchema: toJsonSchema(tool.outputSchema),
+      annotations: { ...tool.annotations }
+    })),
+    enums: {
+      roles: [...SEMANTIC_ROLES],
+      states: [...STATE_NAMES],
+      signals: [...SIGNALS],
+      errorKinds: ERROR_KINDS
+    },
+    exitCodes: { ...EXIT_CODES },
+    limits: { ...MCP_LIMITS },
+    conventions: [...CONVENTIONS]
+  };
+}
+function buildUsage() {
+  return [
+    `${SERVER_NAME} MCP server ${SERVER_VERSION} \u2014 drive terminal programs over MCP`,
+    "",
+    "serve",
+    "  termwright-mcp                     serve over stdio (what an MCP host spawns)",
+    "  termwright-mcp --http --port 7333  serve Streamable HTTP on /mcp, multi-session",
+    "  termwright-mcp agent-context       versioned JSON: tools, params, enums, exit codes",
+    "  termwright-mcp usage               this page",
+    "  termwright-mcp skill --out DIR     emit an agent-skill package (SKILL.md + reference)",
+    "  global: --json (machine-readable errors with a kind), --version, --help",
+    "",
+    "typical loop",
+    '  terminal.launch {command:["node","app.js"]}   -> terminal "t1" + first snapshot',
+    '  terminal.snapshot {terminal:"t1"}             -> refs n8@42 + visible text + revision',
+    '  terminal.click {terminal:"t1", ref:"n8@42"}   -> real mouse report through the PTY',
+    '  terminal.wait_for {terminal:"t1", wait:"text", text:"Approved"}',
+    '  terminal.capture_since {terminal:"t1", cursor:42} -> only what changed',
+    '  terminal.close {terminal:"t1"}',
+    "",
+    "targeting  ref | selector | testId | role(+name) | label | text   (+ exact, state, nth)",
+    `roles      ${SEMANTIC_ROLES.join(" ")}`,
+    `states     ${STATE_NAMES.join(" ")}`,
+    "",
+    "exit codes 0 ok / 1 assertion / 2 usage / 3 no-session / 4 ipc / 5 internal",
+    "error kinds " + ERROR_KINDS.join(" ")
+  ].join("\n");
+}
+
+// src/agent-skill.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
+var SKILL_DESCRIPTION = "Drive terminal programs (TUIs, CLIs, REPLs) over MCP: launch one in a real pseudo-terminal, read a compact accessibility-style snapshot, click and type, wait on conditions, and poll only what changed. Use when asked to test, inspect, automate or debug a terminal application.";
+function renderParameters(schema) {
+  const properties = schema["properties"];
+  if (typeof properties !== "object" || properties === null) return "  (no parameters)";
+  const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+  return Object.entries(properties).map(([name, definition]) => {
+    const type2 = typeof definition["type"] === "string" ? definition["type"] : Array.isArray(definition["enum"]) ? definition["enum"].map((value) => JSON.stringify(value)).join("|") : "value";
+    const description = typeof definition["description"] === "string" ? ` \u2014 ${definition["description"]}` : "";
+    return `- \`${name}\`${required.has(name) ? "" : "?"}: ${type2}${description}`;
+  }).join("\n");
+}
+function renderSkillMarkdown() {
+  return [
+    "---",
+    `name: ${SERVER_NAME}`,
+    `description: ${SKILL_DESCRIPTION}`,
+    "---",
+    "",
+    `# Driving terminal programs with ${SERVER_NAME}`,
+    "",
+    "The MCP server exposes one terminal per handle (`t1`, `t2`, \u2026). Every action goes through a",
+    "real pseudo-terminal: a click is a mouse report, a keystroke is real bytes. There is no",
+    "back-channel into the application.",
+    "",
+    "## The loop",
+    "",
+    '1. `terminal.launch { command: ["node", "app.js"] }` \u2014 returns the handle and the first snapshot.',
+    "2. `terminal.snapshot { terminal }` \u2014 compact refs, visible text, cursor, modes, scroll position.",
+    "3. Act: `terminal.click`, `terminal.press`, `terminal.type`, `terminal.paste`, `terminal.drag`, \u2026",
+    '4. `terminal.wait_for { wait: "text" | "visible" | "stable" | "idle" | "exit", \u2026 }` \u2014 never sleep.',
+    "5. `terminal.capture_since { cursor }` \u2014 only the rows and semantic subtrees that changed.",
+    "6. `terminal.close { terminal }`.",
+    "",
+    "## Reading a snapshot",
+    "",
+    "```",
+    "Terminal t1 100x30 revision 42",
+    "semanticTree: available",
+    'dialog "Permission" ref=n7@42 bounds=(8,20,40,9) modal',
+    '  button "Approve" ref=n8@42 bounds=(14,23,11,1) focused',
+    "visible text:",
+    "\u2026",
+    "```",
+    "",
+    "The header `revision` is the **screen** revision \u2014 that is the `cursor` for",
+    "`terminal.capture_since`. A ref's number is the **semantic** revision: `n8@42` is valid only",
+    "while 42 is live, and reusing it after the screen moved on fails with `stale-snapshot`. The fix",
+    "is always to snapshot again, never to retry the same ref.",
+    "",
+    "`semanticTree: unavailable` means the program ships no adapter. Target those by `text`; there",
+    "are no invented roles.",
+    "",
+    "## Targeting",
+    "",
+    "Precedence: `ref`, `selector`, `testId`, `role` (+`name`), `label`, `text`. Any name or text may",
+    "be written `/pattern/flags` to match as a regular expression. Locators are strict \u2014 more than one",
+    "match fails with `ambiguous-locator` and lists the candidates; pass `nth` to disambiguate, or use",
+    "`terminal.query` first to see what matches.",
+    "",
+    "## Investigating a recorded failure",
+    "",
+    "A failing test run leaves a `.twtrace` archive. Replay it with the same vocabulary:",
+    "",
+    "1. `trace.open { path }` \u2014 validates the archive, returns a handle and what was recorded.",
+    "2. `trace.overview { traceId }` \u2014 steps with status and timing, markers, exit, which step failed.",
+    "3. `trace.frame_at { traceId, stepIndex | timeMs | marker }` \u2014 the screen at that moment, rebuilt,",
+    "   with the semantic tree of the nearest revision. Reads exactly like a live snapshot.",
+    "4. `trace.diff { traceId, fromMs, toMs }` \u2014 what moved between two moments.",
+    "",
+    "Start at the failed step from `trace.overview`, reconstruct it, then diff against a moment before",
+    "it to see what changed. Handles are per session and the coldest is evicted at the ceiling \u2014 if one",
+    "stops resolving, call `trace.open` again.",
+    "",
+    "## The application\u2019s own log",
+    "",
+    "A terminal shows what a program *drew*; its log says what it *decided*. When the screen looks",
+    "right and nothing happened, the answer is usually an `error` or `warn` line, not another pixel.",
+    "",
+    'Pass `logs: [{ path: "app.log", label: "app" }]` to `terminal.launch` and every',
+    "`terminal.capture_since` returns the entries since your cursor, with `logsOmitted` when the",
+    "buffer overflowed and `logCursor` to resume from. An existing file is followed from its end, so",
+    "you never see the previous run.",
+    "",
+    "Two things worth knowing. A followed file is polled, so a line written just now may arrive on the",
+    "next call \u2014 re-asking with the same cursor is lossless, never a reason to widen the window. And a",
+    "log is application output like any other: it can contain tokens and personal data, so treat it",
+    "with the same care as a crash screen tail.",
+    "",
+    "In a replay the same view is there: `trace.frame_at` carries the entries leading up to that",
+    'moment and `trace.diff` the ones between two \u2014 so the question "what was it saying when the',
+    'screen looked like this" is answered the same way live and after the fact.',
+    "",
+    "## Reading terminal modes",
+    "",
+    "A snapshot reports `modes`. Both mouse fields can read `unknown`, which means the platform hides",
+    "the mode from the emulator \u2014 Windows ConPTY does \u2014 not that the program turned mouse reporting",
+    "off. Clicks still go through there, encoded as SGR. So `unknown` is never a reason to fall back",
+    "to keyboard-only interaction; a real `none` is.",
+    "",
+    "## Screenshots",
+    "",
+    "`terminal.snapshot` and `trace.frame_at` take `screenshot: true` (plus `screenshotScale` and",
+    "`screenshotTheme`) and attach a PNG. The text and the compact tree come back in the same result,",
+    "so ask for a picture only when pixels answer something the text cannot \u2014 alignment, colour, a",
+    "glyph that looks wrong. Check `structuredContent.screenshot.selfContained`: when false, some",
+    "character fell back to a font that may not exist where the image is viewed.",
+    "",
+    "## When the program dies",
+    "",
+    "A program that exits on its own \u2014 a signal, or a non-zero code nobody asked for \u2014 leaves a crash",
+    "report. It rides along with whatever call failed next, and `terminal.capabilities` /",
+    "`terminal.snapshot` show it instead of reporting a merely closed session. Read the exit status and",
+    "the screen tail before retrying: a locator that never resolved because the program is gone looks",
+    "like a timeout, and waiting longer will not bring it back. `trace.overview` shows the same section",
+    "for a recording that carries one.",
+    "",
+    "**The screen tail is unredacted.** It is whatever the terminal displayed at the end \u2014 a stack",
+    "trace, a config dump, an echoed password, whatever was there. Treat it like a screenshot of the",
+    "user's machine: use it to diagnose, but do not paste it into issues, commit messages, chat",
+    "transcripts or anywhere else it outlives the investigation. The one thing never recorded is the",
+    "content of a paste \u2014 those carry secrets routinely, so only their size is kept.",
+    "",
+    "## When a call fails",
+    "",
+    "Failures come back with `isError` and a text block starting `error <kind>: <message>` plus a",
+    "`suggestion`. Branch on the kind: `stale-snapshot` (re-snapshot), `ambiguous-locator` (narrow the",
+    "target), `timeout` (the condition never held \u2014 read the screen excerpt), `unsupported-action` (the",
+    "program never enabled mouse tracking, or has no semantic tree), `no-session` (bad handle),",
+    '`history-truncated` (cursor too old). The same payload is in `_meta["io.termwright/error"]`.',
+    "",
+    "See `reference.md` for every tool and parameter, and `agent-context.json` for the machine-readable",
+    "surface (enums, defaults, exit codes).",
+    "",
+    "## Command line",
+    "",
+    "```",
+    buildUsage().split("\n").slice(2).join("\n").trim(),
+    "```",
+    ""
+  ].join("\n");
+}
+function renderReferenceMarkdown() {
+  const context = buildAgentContext();
+  const sections = context.tools.map(
+    (tool) => [
+      `## ${tool.name}`,
+      "",
+      tool.description,
+      "",
+      "**Input**",
+      renderParameters(tool.inputSchema),
+      "",
+      "**Output**",
+      renderParameters(tool.outputSchema),
+      ""
+    ].join("\n")
+  );
+  return [
+    `# ${SERVER_NAME} tool reference (${SERVER_VERSION})`,
+    "",
+    `Generated from the zod schemas of ${TOOLS.length} tools; do not edit by hand.`,
+    "",
+    ...sections,
+    "## Exit codes",
+    "",
+    Object.entries(context.exitCodes).map(([name, code]) => `- ${String(code)} \u2014 ${name}`).join("\n"),
+    "",
+    "## Error kinds",
+    "",
+    context.enums.errorKinds.map((kind) => `- \`${kind}\``).join("\n"),
+    ""
+  ].join("\n");
+}
+function buildAgentSkill() {
+  return [
+    { path: "SKILL.md", contents: renderSkillMarkdown() },
+    { path: "reference.md", contents: renderReferenceMarkdown() },
+    { path: "agent-context.json", contents: `${JSON.stringify(buildAgentContext(), null, 2)}
+` }
+  ];
+}
+async function writeAgentSkill(directory) {
+  await mkdir2(directory, { recursive: true });
+  const written = [];
+  for (const file of buildAgentSkill()) {
+    const path = join2(directory, file.path);
+    await writeFile2(path, file.contents, "utf8");
+    written.push(path);
+  }
+  return written;
+}
+
+// src/server.ts
+import { createServer } from "http";
+import { randomUUID } from "crypto";
+
+// src/sdk-facade.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+async function connectTransport(server, transport) {
+  await server.connect(transport);
+}
+
+// src/server.ts
+var INSTRUCTIONS = "Drive terminal programs the way a person would. terminal.launch starts a program and returns a handle; terminal.snapshot gives compact refs plus visible text; act with terminal.click / press / type; wait with terminal.wait_for; poll cheaply with terminal.capture_since using the revision a snapshot returned. Refs like n8@42 are only valid at semantic revision 42 \u2014 re-snapshot after the screen changes. Programs without a termwright adapter report semanticTree: unavailable; target them by text instead of by role.";
+function successResult(outcome) {
+  return {
+    content: [
+      { type: "text", text: outcome.text },
+      ...(outcome.images ?? []).map((image) => ({
+        type: "image",
+        data: image.data,
+        mimeType: image.mimeType
+      }))
+    ],
+    structuredContent: outcome.data
+  };
+}
+function withCrashContext(context, args, error) {
+  if (error instanceof CrashContextError) return error;
+  const id = args?.terminal;
+  if (typeof id !== "string") return error;
+  const report = context.terminals.find(id)?.harness.crashReport();
+  return report === void 0 || report === null ? error : new CrashContextError(error, describeCrash(report));
+}
+var ERROR_META_KEY = "io.termwright/error";
+function errorResult(error) {
+  const payload = toErrorPayload(error);
+  return {
+    isError: true,
+    content: [{ type: "text", text: renderErrorPayload(payload) }],
+    _meta: { [ERROR_META_KEY]: payload }
+  };
+}
+function createTermwrightMcpServer(stores) {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} }, instructions: INSTRUCTIONS }
+  );
+  const context = { terminals: stores.terminals, traces: stores.traces };
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations
+      },
+      async (args) => {
+        try {
+          return successResult(await tool.handler(context, args));
+        } catch (error) {
+          return errorResult(withCrashContext(context, args, error));
+        }
+      }
+    );
+  }
+  return server;
+}
+async function connect(stores, transport) {
+  const server = createTermwrightMcpServer(stores);
+  await connectTransport(server, transport);
+  return {
+    server,
+    stores,
+    close: async () => {
+      await closeSessionStores(stores);
+      await server.close();
+    }
+  };
+}
+async function serveStdio(options = {}) {
+  const stores = createSessionStores({ sessionKey: "stdio", storageDir: options.storageDir });
+  return connect(stores, new StdioServerTransport());
+}
+async function serveInMemory(options = {}) {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const stores = createSessionStores({
+    sessionKey: options.sessionKey ?? "in-memory",
+    storageDir: options.storageDir
+  });
+  const running = await connect(stores, serverTransport);
+  return { ...running, clientTransport };
+}
+var DEFAULT_IDLE_TTL_MS = 10 * 6e4;
+function sendJson(response, status, body) {
+  const text = JSON.stringify(body);
+  response.writeHead(status, { "content-type": "application/json" });
+  response.end(text);
+}
+async function readBody(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.from(chunk);
+    size += buffer.byteLength;
+    if (size > 4 * 1024 * 1024) throw new Error("request body too large");
+    chunks.push(buffer);
+  }
+  if (chunks.length === 0) return void 0;
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+async function serveHttp(options = {}) {
+  const path = options.path ?? "/mcp";
+  const log = options.log ?? ((message) => void process.stderr.write(`${message}
+`));
+  const registry = new SessionRegistry({
+    ...options.maxSessions === void 0 ? {} : { maxSessions: options.maxSessions },
+    ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir },
+    ...options.now === void 0 ? {} : { now: options.now },
+    idleTtlMs: options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS,
+    disposeAttachment: async (attachment) => {
+      await attachment.transport.close();
+    },
+    onExpired: (key) => {
+      log(`termwright: session ${key} expired after idling; terminals and traces released`);
+    }
+  });
+  registry.startIdleSweeper();
+  const http = createServer((request, response) => {
+    void (async () => {
+      try {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        if (url.pathname !== path) {
+          sendJson(response, 404, { error: "not found" });
+          return;
+        }
+        const sessionId = request.headers["mcp-session-id"];
+        const key = Array.isArray(sessionId) ? sessionId[0] : sessionId;
+        if (request.method === "DELETE") {
+          if (key !== void 0) await registry.delete(key);
+          response.writeHead(204).end();
+          return;
+        }
+        const body = request.method === "POST" ? await readBody(request) : void 0;
+        if (key !== void 0) {
+          const session2 = registry.get(key);
+          if (session2 === void 0) {
+            sendJson(response, 404, { error: "unknown session", kind: "no-session" });
+            return;
+          }
+          registry.touch(key);
+          await session2.attachment.transport.handleRequest(request, response, body);
+          return;
+        }
+        if (request.method !== "POST" || !isInitializeRequest(body)) {
+          sendJson(response, 400, { error: "missing Mcp-Session-Id", kind: "usage" });
+          return;
+        }
+        const newKey = randomUUID();
+        const session = registry.create(newKey, (stores) => {
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => newKey
+          });
+          const server = createTermwrightMcpServer(stores);
+          transport.onclose = () => {
+            void registry.delete(newKey);
+          };
+          return { transport, server };
+        });
+        await connectTransport(session.attachment.server, session.attachment.transport);
+        await session.attachment.transport.handleRequest(request, response, body);
+      } catch (error) {
+        const payload = toErrorPayload(error);
+        if (!response.headersSent) sendJson(response, 500, { error: payload.message, kind: payload.kind });
+        else response.end();
+      }
+    })();
+  });
+  await new Promise((resolve) => {
+    http.listen(options.port ?? 0, options.host ?? "127.0.0.1", resolve);
+  });
+  const address = http.address();
+  const port = typeof address === "object" && address !== null ? address.port : options.port ?? 0;
+  return {
+    http,
+    registry,
+    port,
+    close: async () => {
+      registry.stopIdleSweeper();
+      await registry.closeAll();
+      await new Promise((resolve) => {
+        http.close(() => {
+          resolve();
+        });
+      });
+    }
+  };
+}
+
+// src/cli.ts
+var defaultIo = {
+  out: (text) => process.stdout.write(`${text}
+`),
+  err: (text) => process.stderr.write(`${text}
+`)
+};
+function parseArgs(argv) {
+  let command = "serve";
+  let json = false;
+  let http = false;
+  let port;
+  let host;
+  let out;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--http":
+        http = true;
+        break;
+      case "--port": {
+        const value = Number(argv[index + 1]);
+        if (!Number.isInteger(value) || value < 0 || value > 65535) {
+          throw usageError("--port needs an integer between 0 and 65535");
+        }
+        port = value;
+        index += 1;
+        break;
+      }
+      case "--host":
+        host = argv[index + 1];
+        if (host === void 0) throw usageError("--host needs a value");
+        index += 1;
+        break;
+      case "--out":
+        out = argv[index + 1];
+        if (out === void 0) throw usageError("--out needs a directory");
+        index += 1;
+        break;
+      case "--help":
+      case "-h":
+        command = "help";
+        break;
+      case "--version":
+      case "-v":
+        command = "version";
+        break;
+      case "serve":
+      case "stdio":
+        command = "serve";
+        break;
+      case "agent-context":
+        command = "agent-context";
+        break;
+      case "usage":
+        command = "usage";
+        break;
+      case "skill":
+        command = "skill";
+        break;
+      default:
+        throw usageError(
+          `unknown argument ${JSON.stringify(arg)}`,
+          "run `termwright-mcp usage` for the one-screen cheat sheet"
+        );
+    }
+  }
+  return { command, json, http, port, host, out };
+}
+async function runCli(argv, io = defaultIo) {
+  let json = argv.includes("--json");
+  try {
+    const args = parseArgs(argv);
+    json = args.json;
+    switch (args.command) {
+      case "version":
+        io.out(json ? JSON.stringify({ name: SERVER_NAME, version: SERVER_VERSION }) : SERVER_VERSION);
+        return EXIT_CODES.ok;
+      case "help":
+      case "usage":
+        io.out(json ? JSON.stringify(buildAgentContext()) : buildUsage());
+        return EXIT_CODES.ok;
+      case "agent-context":
+        io.out(JSON.stringify(buildAgentContext(), null, json ? 0 : 2));
+        return EXIT_CODES.ok;
+      case "skill": {
+        if (args.out === void 0) {
+          const files = buildAgentSkill();
+          io.out(
+            json ? JSON.stringify(Object.fromEntries(files.map((file) => [file.path, file.contents]))) : files.map((file) => `=== ${file.path}
+${file.contents}`).join("\n")
+          );
+          return EXIT_CODES.ok;
+        }
+        const written = await writeAgentSkill(args.out);
+        io.out(json ? JSON.stringify({ written }) : written.join("\n"));
+        return EXIT_CODES.ok;
+      }
+      case "serve": {
+        if (args.http) {
+          const handle = await serveHttp({
+            ...args.port === void 0 ? {} : { port: args.port },
+            ...args.host === void 0 ? {} : { host: args.host }
+          });
+          io.err(`${SERVER_NAME} MCP listening on http://${args.host ?? "127.0.0.1"}:${handle.port}/mcp`);
+          await new Promise((resolve) => {
+            handle.http.on("close", resolve);
+          });
+          return EXIT_CODES.ok;
+        }
+        const running = await serveStdio();
+        await new Promise((resolve) => {
+          const shutdown = () => {
+            void running.close().then(resolve, resolve);
+          };
+          process.once("SIGINT", shutdown);
+          process.once("SIGTERM", shutdown);
+          running.server.server.onclose = shutdown;
+        });
+        return EXIT_CODES.ok;
+      }
+    }
+  } catch (error) {
+    const payload = toErrorPayload(error);
+    io.err(json ? JSON.stringify(payload) : `${payload.kind}: ${payload.message}`);
+    if (!json && payload.suggestion !== void 0) io.err(`suggestion: ${payload.suggestion}`);
+    return exitCodeFor(payload.kind);
+  }
+}
+async function main() {
+  process.exitCode = await runCli(process.argv.slice(2));
+}
+
+export {
+  EXIT_CODES,
+  exitCodeFor,
+  McpError,
+  usageError,
+  noSessionError,
+  toErrorPayload,
+  renderErrorPayload,
+  SEMANTIC_ROLES,
+  FILTERABLE_STATES,
+  SIGNALS,
+  TRACE_LIMITS,
+  TraceStore,
+  MCP_LIMITS,
+  TerminalStore,
+  createSessionStores,
+  closeSessionStores,
+  SessionRegistry,
+  defineTool,
+  SCREENSHOT_LIMITS,
+  renderScreenshot,
+  formatRef,
+  parseRef,
+  formatBounds,
+  stateFlags,
+  formatNodeLine,
+  walkSnapshot,
+  refEntries,
+  toRefEntry,
+  formatCompactSnapshot,
+  diffRows,
+  diffSemantic,
+  textOrRegExp,
+  buildLocator,
+  TERMINAL_TOOLS,
+  TRACE_TOOLS,
+  TOOLS,
+  toolByName,
+  SERVER_NAME,
+  SERVER_VERSION,
+  AGENT_CONTEXT_VERSION,
+  buildAgentContext,
+  buildUsage,
+  buildAgentSkill,
+  writeAgentSkill,
+  createTermwrightMcpServer,
+  serveStdio,
+  serveInMemory,
+  serveHttp,
+  runCli,
+  main
+};
+//# sourceMappingURL=chunk-QDIAASH7.js.map