@termwright/mcp 0.2.0

package/dist/chunk-PGY4ZDLD.js

@@ -0,0 +1,1843 @@
+// src/errors.ts
+import { TermwrightError } from "@termwright/driver";
+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 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}`);
+  return parts.join("\n");
+}
+
+// src/model.ts
+var SEMANTIC_ROLES = [
+  "application",
+  "region",
+  "dialog",
+  "alert",
+  "status",
+  "list",
+  "listitem",
+  "menu",
+  "menuitem",
+  "button",
+  "checkbox",
+  "radio",
+  "tab",
+  "textbox",
+  "heading",
+  "text",
+  "progressbar",
+  "separator",
+  "scrollbar",
+  "table",
+  "row",
+  "cell",
+  "generic"
+];
+var FILTERABLE_STATES = [
+  "disabled",
+  "focused",
+  "selected",
+  "checked",
+  "expanded",
+  "modal",
+  "busy",
+  "hidden",
+  "readonly"
+];
+var SIGNALS = ["INT", "TERM", "KILL", "HUP"];
+
+// src/sessions.ts
+import { mkdir, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { launchTerminal } from "@termwright/driver";
+
+// 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 (`DEFAULT_LIMITS.maxSessions`). */
+  maxSessions: 16,
+  /** Concurrent terminals inside one MCP session. */
+  maxTerminals: 16,
+  /** Snapshots retained per terminal for `capture_since` cursors. */
+  maxHistory: 16,
+  /** Argument ceiling for a launch command line. */
+  maxCommandParts: 64
+});
+var SAFE_ENV_KEYS = ["PATH", "HOME", "LANG", "LC_ALL", "SHELL", "TMPDIR", "USER", "TERM"];
+function childEnv(request) {
+  const env = {};
+  if (request.inheritEnv === true) {
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== void 0) env[key] = value;
+    }
+  } else {
+    for (const key of SAFE_ENV_KEYS) {
+      const value = process.env[key];
+      if (value !== void 0) env[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(request.env ?? {})) env[key] = value;
+  return env;
+}
+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],
+      env: childEnv(request),
+      ...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) }
+    };
+    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: []
+    };
+    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; 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,
+      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;
+      })
+    );
+  }
+};
+var SessionRegistry = class {
+  #sessions = /* @__PURE__ */ new Map();
+  #maxSessions;
+  #storageDir;
+  constructor(options = {}) {
+    this.#maxSessions = options.maxSessions ?? MCP_LIMITS.maxSessions;
+    this.#storageDir = options.storageDir;
+  }
+  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 store; 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 store = new TerminalStore({
+      sessionKey: key,
+      ...this.#storageDir === void 0 ? {} : { storageDir: this.#storageDir }
+    });
+    const session = { key, store, attachment: attach(store) };
+    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 session.store.closeAll();
+  }
+  /** Closes every session. */
+  async closeAll() {
+    const keys = [...this.#sessions.keys()];
+    await Promise.all(keys.map(async (key) => this.delete(key)));
+  }
+};
+
+// 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 locatorForRef(harness, ref) {
+  const parsed = parseRef(ref);
+  if (parsed === null) {
+    throw usageError(`ref ${JSON.stringify(ref)} is not of the form n8@42`);
+  }
+  const tree = harness.semanticTree();
+  if (tree === null) {
+    throw new McpError(
+      "unsupported-action",
+      `ref ${ref} cannot be used: this session has no semantic tree`,
+      "target by text or by grid coordinates instead"
+    );
+  }
+  if (tree.revision !== parsed.revision) {
+    throw new McpError(
+      "stale-snapshot",
+      `ref ${ref} was minted at semantic revision ${parsed.revision}; the live revision is ${tree.revision}`,
+      "call terminal.snapshot or terminal.capture_since and use the fresh refs"
+    );
+  }
+  const node = tree.nodes.find((candidate) => candidate.id === parsed.nodeId);
+  if (node === void 0) {
+    throw new McpError(
+      "stale-snapshot",
+      `ref ${ref} no longer exists at semantic revision ${tree.revision}`,
+      "call terminal.snapshot and use the fresh refs"
+    );
+  }
+  if (node.testId !== void 0) return harness.getByTestId(node.testId);
+  return harness.getByRole(node.role, definedOnly({ name: node.name, exact: true }));
+}
+function buildLocator(harness, input) {
+  let locator;
+  if (input.ref !== void 0) {
+    locator = locatorForRef(harness, 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 z2 } from "zod";
+
+// src/schemas.ts
+import { z } from "zod";
+var terminalId = z.string().min(1).describe('terminal handle returned by terminal.launch, e.g. "t1"');
+var timeoutMs = z.number().int().positive().max(6e5).describe("timeout in milliseconds; defaults to the driver timeout class for the action");
+var stateFilter = z.object({
+  disabled: z.boolean().optional(),
+  focused: z.boolean().optional(),
+  selected: z.boolean().optional(),
+  checked: z.union([z.boolean(), z.literal("mixed")]).optional(),
+  expanded: z.boolean().optional(),
+  modal: z.boolean().optional(),
+  busy: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  readonly: z.boolean().optional()
+}).describe("only nodes asserting these state flags match");
+var cellPosition = z.object({
+  row: z.number().int().min(0),
+  column: z.number().int().min(0)
+});
+var targetShape = {
+  ref: z.string().optional().describe('ref from a previous snapshot, e.g. "n8@42"; only valid at that semantic revision'),
+  selector: z.string().optional().describe('CSS dialect: "dialog button#approve:focused" (role, #testId, .class, :state)'),
+  role: z.enum(SEMANTIC_ROLES).optional().describe("semantic role; requires a semantic tree"),
+  name: z.string().optional().describe('accessible name; "/pattern/flags" is read as a regular expression'),
+  testId: z.string().optional().describe("author-supplied test id"),
+  label: z.string().optional().describe("label text (labelledBy, else name)"),
+  text: z.string().optional().describe("visible text; matches the grid when there is no semantic tree"),
+  exact: z.boolean().optional().describe("exact rather than substring text matching"),
+  state: stateFilter.optional(),
+  nth: z.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 = z.object(targetShape);
+var refEntrySchema = z.object({
+  ref: z.string(),
+  role: z.string(),
+  name: z.string(),
+  depth: z.number().int().min(0),
+  bounds: z.object({
+    row: z.number().int(),
+    column: z.number().int(),
+    width: z.number().int(),
+    height: z.number().int()
+  }).optional(),
+  flags: z.array(z.string()),
+  testId: z.string().optional(),
+  value: z.string().optional()
+});
+var semanticTreeState = z.enum(["available", "unavailable"]);
+var cursorSchema = z.object({
+  row: z.number().int(),
+  column: z.number().int(),
+  visible: z.boolean(),
+  shape: z.enum(["block", "underline", "bar"]).optional()
+});
+var modesSchema = z.object({
+  mouseTracking: z.enum(["none", "x10", "vt200", "drag", "any"]),
+  mouseEncoding: z.enum(["default", "sgr", "urxvt", "utf8"]),
+  bracketedPaste: z.boolean(),
+  applicationCursorKeys: z.boolean(),
+  applicationKeypad: z.boolean(),
+  focusReporting: z.boolean(),
+  synchronizedOutput: z.boolean()
+});
+var exitSchema = z.object({
+  code: z.number().int().nullable(),
+  signal: z.string().nullable()
+});
+var signalSchema = z.enum(SIGNALS);
+var buttonSchema = z.enum(["left", "middle", "right"]);
+var roleEnum = z.enum(SEMANTIC_ROLES);
+var STATE_NAMES = FILTERABLE_STATES;
+
+// src/tools.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
+  };
+}
+var semanticFields = {
+  terminal: z2.string(),
+  revision: z2.number().int().describe("screen revision; pass it to terminal.capture_since as cursor"),
+  semanticRevision: z2.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;
+  if (entry.harness.semanticTree() !== null) return;
+  try {
+    await entry.harness.waitForStable({ timeout: SEMANTIC_SETTLE_MS });
+  } catch {
+  }
+}
+var SEMANTIC_SETTLE_MS = 2e3;
+function capture(context, entry) {
+  const record = context.store.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);
+}
+var receiptFields = {
+  ok: z2.literal(true),
+  terminal: z2.string(),
+  revision: z2.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 inherits only a safe environment subset unless inheritEnv is set; values passed in env are never echoed back.",
+  inputSchema: {
+    command: z2.array(z2.string()).min(1).describe('argv, e.g. ["node", "app.js"] \u2014 no shell is involved'),
+    cwd: z2.string().optional(),
+    env: z2.record(z2.string(), z2.string()).optional().describe("extra environment for the child"),
+    inheritEnv: z2.boolean().optional().describe("pass the whole server environment to the child (default false)"),
+    columns: z2.number().int().min(1).max(1e3).optional().describe("default 100"),
+    rows: z2.number().int().min(1).max(1e3).optional().describe("default 30"),
+    scrollbackLines: z2.number().int().min(0).max(1e5).optional(),
+    semanticNegotiationMs: z2.number().int().min(0).max(6e4).optional(),
+    timeouts: z2.object({
+      action: z2.number().int().positive().optional(),
+      text: z2.number().int().positive().optional(),
+      idle: z2.number().int().positive().optional(),
+      ready: z2.number().int().positive().optional(),
+      exit: z2.number().int().positive().optional()
+    }).optional()
+  },
+  outputSchema: {
+    ...semanticFields,
+    sessionId: z2.string(),
+    columns: z2.number().int(),
+    rows: z2.number().int(),
+    adapter: z2.object({ name: z2.string(), version: z2.string() }).optional(),
+    capabilities: z2.array(z2.string()),
+    platform: z2.string(),
+    compact: z2.string()
+  },
+  annotations: { openWorldHint: true },
+  handler: async (context, args) => {
+    const entry = await context.store.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: z2.number().int(),
+    rows: z2.number().int(),
+    adapter: z2.object({ name: z2.string(), version: z2.string() }).optional(),
+    capabilities: z2.array(z2.string()),
+    platform: z2.string()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.store.get(args.terminal);
+    await settleSemantics(entry);
+    const caps = entry.harness.capabilities();
+    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}`,
+      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
+      }
+    };
+  }
+});
+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: z2.enum(["compact", "full"]).optional().describe('default "compact"'),
+    maxNodes: z2.number().int().min(1).max(5e3).optional(),
+    maxRows: z2.number().int().min(1).max(1e4).optional(),
+    includeText: z2.boolean().optional().describe("include the visible grid text (default true)")
+  },
+  outputSchema: {
+    ...semanticFields,
+    cursorValue: z2.number().int().describe("alias of revision, to pass to terminal.capture_since"),
+    columns: z2.number().int(),
+    rows: z2.number().int(),
+    buffer: z2.enum(["normal", "alternate"]),
+    cursor: cursorSchema,
+    modes: modesSchema,
+    scroll: z2.object({
+      offset: z2.number().int(),
+      length: z2.number().int(),
+      retainedFloor: z2.number().int()
+    }),
+    refs: z2.array(refEntrySchema),
+    compact: z2.string(),
+    dumpPath: z2.string().optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.store.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.store.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
+        )}
+`
+      );
+    }
+    return {
+      text: dumpPath === void 0 ? compact : `${compact}
+full dump: ${dumpPath}`,
+      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 }
+      }
+    };
+  }
+});
+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: z2.number().int().min(0).describe("revision returned by an earlier snapshot"),
+    maxRows: z2.number().int().min(1).max(1e4).optional(),
+    maxSubtrees: z2.number().int().min(1).max(1e3).optional()
+  },
+  outputSchema: {
+    ...semanticFields,
+    since: z2.number().int(),
+    changedRows: z2.array(z2.object({ row: z2.number().int(), text: z2.string() })),
+    changedSubtrees: z2.array(
+      z2.object({
+        change: z2.enum(["added", "removed", "updated"]),
+        ref: z2.string(),
+        role: z2.string(),
+        name: z2.string(),
+        compact: z2.string()
+      })
+    ),
+    compact: z2.string()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.store.get(args.terminal);
+    await settleSemantics(entry);
+    const before = context.store.baseline(entry, args.cursor);
+    const after = context.store.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 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}`);
+    }
+    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 })),
+        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: z2.number().int().min(1).max(100).optional().describe("default 20")
+  },
+  outputSchema: {
+    terminal: z2.string(),
+    revision: z2.number().int(),
+    count: z2.number().int(),
+    matches: z2.array(
+      z2.object({
+        ref: z2.string(),
+        revision: z2.number().int(),
+        semantic: z2.boolean(),
+        role: z2.string().optional(),
+        name: z2.string().optional(),
+        bounds: refEntrySchema.shape.bounds
+      })
+    )
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.store.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.`,
+    inputSchema: {
+      terminal: terminalId,
+      ...targetShape,
+      button: buttonSchema.optional(),
+      position: z2.object({ rowOffset: z2.number().int(), columnOffset: z2.number().int() }).optional().describe("offset inside the target rectangle"),
+      timeout: timeoutMs.optional()
+    },
+    outputSchema: { ...receiptFields, ref: z2.string() },
+    handler: async (context, args) => {
+      const entry = context.store.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: z2.string().min(1).describe('space-separated chords, e.g. "Control+A Home"'),
+    ...targetShape,
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: { ...receiptFields, ref: z2.string().optional() },
+  handler: async (context, args) => {
+    const entry = context.store.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: z2.string(),
+    ...targetShapeWithoutText,
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: { ...receiptFields, ref: z2.string().optional() },
+  handler: async (context, args) => {
+    const entry = context.store.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: z2.string() },
+  outputSchema: receiptFields,
+  handler: async (context, args) => {
+    const entry = context.store.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: z2.string(),
+    encoding: z2.enum(["utf8", "base64"]).optional().describe('default "utf8"')
+  },
+  outputSchema: { ...receiptFields, bytes: z2.number().int() },
+  handler: async (context, args) => {
+    const entry = context.store.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.store.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: z2.number().int(),
+    deltaX: z2.number().int().optional()
+  },
+  outputSchema: receiptFields,
+  handler: async (context, args) => {
+    const entry = context.store.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: z2.number().int().min(1).max(1e3),
+    rows: z2.number().int().min(1).max(1e3)
+  },
+  outputSchema: { ...receiptFields, columns: z2.number().int(), rows: z2.number().int() },
+  handler: async (context, args) => {
+    const entry = context.store.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.store.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: z2.number().int().optional().describe("lines to move the viewport; negative scrolls up"),
+    from: z2.number().int().min(0).optional(),
+    to: z2.number().int().min(0).optional(),
+    search: z2.string().optional().describe('literal text, or "/pattern/flags"'),
+    limit: z2.number().int().min(1).max(1e3).optional().describe("max search hits (default 50)")
+  },
+  outputSchema: {
+    terminal: z2.string(),
+    length: z2.number().int(),
+    retainedFloor: z2.number().int(),
+    position: z2.number().int(),
+    text: z2.string().optional(),
+    matches: z2.array(z2.object({ line: z2.number().int(), match: z2.string() })).optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.store.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.store.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: z2.boolean().optional() },
+  outputSchema: { terminal: z2.string(), text: z2.string() },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.store.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: z2.enum(["text", "title", "visible", "hidden", "attached", "stable", "idle", "render", "exit"]),
+    text: z2.string().optional().describe('for wait="text"; "/pattern/flags" is a regular expression'),
+    title: z2.string().optional().describe('for wait="title"'),
+    ...targetShapeWithoutText,
+    frames: z2.number().int().min(1).optional().describe('for wait="stable"'),
+    after: z2.number().int().min(0).optional().describe('for wait="render": the revision to beat'),
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: {
+    ...receiptFields,
+    wait: z2.string(),
+    exit: exitSchema.optional()
+  },
+  handler: async (context, args) => {
+    const entry = context.store.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: z2.literal(true), terminal: z2.string(), exit: exitSchema.nullable() },
+  annotations: { idempotentHint: true },
+  handler: async (context, args) => {
+    const entry = await context.store.close(args.terminal);
+    return {
+      text: `closed ${entry.id}`,
+      data: { ok: true, terminal: entry.id, exit: entry.exit }
+    };
+  }
+});
+var 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
+]);
+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 z3 } from "zod";
+var ERROR_KINDS = [
+  "timeout",
+  "stale-snapshot",
+  "ambiguous-locator",
+  "unsupported-action",
+  "history-truncated",
+  "protocol-violation",
+  "capacity",
+  "process-exited",
+  "session-closed",
+  "usage",
+  "no-session",
+  "internal"
+];
+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 z3.toJSONSchema(z3.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",
+    "  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/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(text, data) {
+  return { content: [{ type: "text", text }], structuredContent: data };
+}
+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(store) {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} }, instructions: INSTRUCTIONS }
+  );
+  const context = { store };
+  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 {
+          const outcome = await tool.handler(context, args);
+          return successResult(outcome.text, outcome.data);
+        } catch (error) {
+          return errorResult(error);
+        }
+      }
+    );
+  }
+  return server;
+}
+async function connect(store, transport) {
+  const server = createTermwrightMcpServer(store);
+  await connectTransport(server, transport);
+  return {
+    server,
+    store,
+    close: async () => {
+      await store.closeAll();
+      await server.close();
+    }
+  };
+}
+async function serveStdio(options = {}) {
+  const store = new TerminalStore({
+    sessionKey: "stdio",
+    ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir }
+  });
+  return connect(store, new StdioServerTransport());
+}
+async function serveInMemory(options = {}) {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const store = new TerminalStore({
+    sessionKey: options.sessionKey ?? "in-memory",
+    ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir }
+  });
+  const running = await connect(store, serverTransport);
+  return { ...running, clientTransport };
+}
+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 registry = new SessionRegistry({
+    ...options.maxSessions === void 0 ? {} : { maxSessions: options.maxSessions },
+    ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir }
+  });
+  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;
+          }
+          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, (store) => {
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => newKey
+          });
+          const server = createTermwrightMcpServer(store);
+          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 () => {
+      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;
+  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 "--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;
+      default:
+        throw usageError(
+          `unknown argument ${JSON.stringify(arg)}`,
+          "run `termwright-mcp usage` for the one-screen cheat sheet"
+        );
+    }
+  }
+  return { command, json, http, port, host };
+}
+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 "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,
+  MCP_LIMITS,
+  TerminalStore,
+  SessionRegistry,
+  formatRef,
+  parseRef,
+  formatBounds,
+  stateFlags,
+  formatNodeLine,
+  walkSnapshot,
+  refEntries,
+  toRefEntry,
+  formatCompactSnapshot,
+  diffRows,
+  diffSemantic,
+  textOrRegExp,
+  buildLocator,
+  TOOLS,
+  toolByName,
+  SERVER_NAME,
+  SERVER_VERSION,
+  AGENT_CONTEXT_VERSION,
+  buildAgentContext,
+  buildUsage,
+  createTermwrightMcpServer,
+  serveStdio,
+  serveInMemory,
+  serveHttp,
+  runCli,
+  main
+};
+//# sourceMappingURL=chunk-PGY4ZDLD.js.map