@termwright/mcp 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ snapshot, click a button by its ref, wait on a condition, and ask what changed.
 It is deliberately thin. Every tool validates its arguments with zod, calls the
 public `@termwright/driver` API, and renders the result. There is no locator
 engine, no wait loop and no matching heuristic here — a behaviour that differed
-between this server and the test preset would be a bug in this package.
+between this server and the Native Host would be a bug in this package.
 
 ## Install
 
@@ -47,28 +47,68 @@ process.on('SIGINT', () => void running.close());
 // terminal.snapshot -> the compact format, plus refs / cursor / modes / scroll
 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
+dialog "Permission" ref=semantic:n7@42 bounds=(8,20,40,9) modal
+  button "Approve" ref=semantic:n8@42 bounds=(14,23,11,1) focused
+  button "Reject" ref=semantic:n9@42 bounds=(14,36,10,1)
 visible text:
 …
 
-// terminal.click        { "terminal": "t1", "ref": "n8@42" }
-// terminal.wait_for     { "terminal": "t1", "wait": "text", "text": "Approved" }
+// terminal.click        { "terminal": "t1", "ref": "semantic:n9@42" }
+// terminal.wait_for     { "terminal": "t1", "wait": "text", "text": "Rejected" }
+// terminal.wait_for     { "terminal": "t1", "wait": "focused", "testId": "reject" }
 // terminal.capture_since{ "terminal": "t1", "cursor": 42 }  -> changed rows + subtrees
 // terminal.close        { "terminal": "t1" }
 ```
 
+The text wait proves the PTY output. When the next operation requires a semantic
+result, wait for that explicit state (`focused`, `checked`, `selected`, …)
+before capturing. The condition must represent a change from the baseline; an
+already-satisfied condition proves no new commit. Screen-only output and the
+prefix of a future semantic frame are intentionally indistinguishable until the
+probe publishes a causal signal.
+
 Streamable HTTP, for hosts that connect over a socket:
 
 ```sh
-termwright-mcp --http --port 7333    # endpoint: http://127.0.0.1:7333/mcp
+termwright-mcp --http --port 7333 --show-auth-token
+# Explicit opt-in prints the endpoint and its fresh per-launch bearer token.
+```
+
+Every MCP-bearing HTTP request, including initialize and `DELETE`, must send
+`Authorization: Bearer <token>`; an allowlisted CORS preflight is the only
+bearer-free request and cannot reach MCP routing. Library callers receive the
+token as `handle.authToken`; the SDK transport accepts it through
+`requestInit.headers`:
+
+```ts
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { serveHttp } from '@termwright/mcp';
+
+const handle = await serveHttp();
+const transport = new StreamableHTTPClientTransport(
+  new URL(`http://127.0.0.1:${handle.port}/mcp`),
+  { requestInit: { headers: { authorization: `Bearer ${handle.authToken}` } } },
+);
 ```
 
 Sessions are keyed by `Mcp-Session-Id` in this package's own `SessionRegistry`,
-not inside transport objects: each session owns its terminals, `DELETE` disposes
+not inside transport objects. A session id is routing metadata, never a
+credential: authentication happens before session lookup, refresh, initialize
+or request-body buffering. Each session owns its terminals, `DELETE` disposes
 them, and the ceiling (16 sessions, 16 terminals each) is enforced before a
 transport exists.
 
+The listener binds to loopback by default. A non-loopback `host` is refused
+unless `allowNonLoopback: true` is set (CLI: `--allow-non-loopback`). That opt-in
+does not add TLS: put a remotely reachable listener behind a private,
+authenticated TLS boundary because the bearer otherwise crosses the network in
+cleartext. Browser requests carrying `Origin` are rejected by default; an
+embedding may allow exact HTTP(S) origins with `allowedOrigins`. A bounded
+per-peer rate limiter protects authenticated work and accepted preflights
+without letting invalid credentials or preflight traffic consume a legitimate
+client's bucket; configure its window/request/client ceilings with `rateLimit`
+when the deployment has a known proxy or concurrency envelope.
+
 Streamable HTTP gives no disconnect signal, so a session also expires after
 `idleTtlMs` without a request (10 minutes by default, `0` to disable). Every
 request naming a session refreshes it; expiry runs the full teardown — terminals
@@ -77,19 +117,57 @@ stderr. stdio has no TTL: there, EOF on the pipe is the signal.
 
 ## Tools
 
-`terminal.launch`, `capabilities`, `snapshot`, `capture_since`, `query`,
-`click`, `double_click`, `press`, `type`, `paste`, `write_raw`, `drag`, `wheel`,
-`resize`, `signal`, `scrollback`, `select_cells`, `copy_selection`, `wait_for`,
-`close` — the surface CONTRACTS.md §MCP defines — plus `trace.open`,
-`trace.overview`, `trace.frame_at` and `trace.diff` for recorded sessions. Every
-one carries an `inputSchema` and an `outputSchema` and returns
-`structuredContent`.
-
-Targeting, in precedence order: `ref`, `selector` (the CSS dialect
-`dialog button#approve:focused`), `testId`, `role` (+ `name`), `label`, `text`.
-Any name or text may be written as `/pattern/flags` to match as a regular
-expression. Locators are strict: more than one match fails with
-`ambiguous-locator` unless you pass `nth`.
+<!-- BEGIN GENERATED MCP TOOL SURFACE -->
+<!-- Generated from packages/mcp/src/registry.ts; do not edit this block by hand. -->
+### Live terminal tools
+
+| Tool | Purpose |
+| --- | --- |
+| `terminal.launch` | 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. |
+| `terminal.capabilities` | 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. |
+| `terminal.snapshot` | 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. |
+| `terminal.capture_since` | Incremental view: the screen rows that differ and the semantic subtrees that were added, removed or updated in the latest committed semantic tree since the given cursor. A screen change alone does not imply a future semantic commit; wait for an explicit semantic state when the caller requires one. The cursor must be a revision this server handed out earlier (snapshot or capture_since); older cursors fail with history-truncated. |
+| `terminal.query` | 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. |
+| `terminal.checkpoint` | Returns the atomic session/contract/screen/semantic identity used by revision-safe actions and waits. |
+| `terminal.actionability` | Runs the same ActionPlanner used by execution, but sends no input. Reports every authoritative requirement and the chosen strategy or typed rejection. |
+| `terminal.click` | Sends a real click mouse report through the pseudo-terminal. Fails closed with input-mode-disabled when the required tracking mode or encoding is disabled or unobservable. |
+| `terminal.double_click` | Sends a real double-click mouse report through the pseudo-terminal. Fails closed with input-mode-disabled when the required tracking mode or encoding is disabled or unobservable. |
+| `terminal.hover` | Sends a real motion mouse report through the pseudo-terminal. Fails closed with input-mode-disabled when the required tracking mode or encoding is disabled or unobservable. |
+| `terminal.press` | 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 must already be focused. |
+| `terminal.type` | Types text as individual keystrokes (not a paste). With a target, the node must already be focused; use terminal.fill for focus + replacement. |
+| `terminal.fill` | Ensures the semantic control receives focus through the real input path, selects its current value, and types the replacement. |
+| `terminal.check` | Uses the central action planner and real terminal input to check a checkbox or radio, then verifies semantic state. |
+| `terminal.uncheck` | Uses the central action planner and real terminal input to uncheck a checkbox or radio, then verifies semantic state. |
+| `terminal.paste` | Pastes text, wrapped in bracketed-paste markers when the program enabled that mode. Use it for multi-line input instead of terminal.type. |
+| `terminal.write_raw` | Writes bytes to the pseudo-terminal verbatim — no newline, no key encoding. The escape hatch for sequences the key encoder does not model. |
+| `terminal.drag` | Drags with real mouse reports: either from one target to another (toTarget), or between two cell positions inside the source target (from/to). |
+| `terminal.wheel` | Sends wheel reports over a target. Positive deltaY scrolls down. |
+| `terminal.resize` | Resizes the pseudo-terminal; the child sees a real SIGWINCH. |
+| `terminal.signal` | Sends INT, TERM, KILL or HUP to the child. Destructive by design: terminal.close cleans up without signalling. |
+| `terminal.scrollback` | Emulator-side history: read a line range, search it, or move the viewport. The child sees nothing — no input is sent. |
+| `terminal.select_cells` | Selects a rectangle in the emulator (like a mouse selection). No input is sent. |
+| `terminal.copy_selection` | Returns the text of the current selection and optionally clears it. |
+| `terminal.wait_for` | Revision-driven waits — never a sleep. "text"/"title" wait for content, locator states use the driver's canonical Conditions, "quiet" explicitly waits for heuristic silence, "render" for a render after a given revision, "exit" for the child to exit. |
+| `terminal.close` | 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. |
+
+### Trace tools
+
+| Tool | Purpose |
+| --- | --- |
+| `trace.open` | 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. |
+| `trace.overview` | 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. |
+| `trace.frame_at` | Rebuilds the screen at a moment — named by timeMs, stepIndex or marker — 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. |
+| `trace.diff` | 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. |
+
+### Targeting
+
+Targeting precedence is `ref`, `selector`, `testId`, `role` (+`name`), `label`, `text`, `screenText`.
+
+`semanticTree: unavailable` means the program ships no integration — target physical output with `screenText`, never semantic `text` or `role`.
+
+Names and text accept `/pattern/flags`. Locators are strict: more than one match returns
+`ambiguous-locator` unless `nth` is explicit.
+<!-- END GENERATED MCP TOOL SURFACE -->
 
 ## Replaying a recorded failure
 
@@ -102,8 +180,8 @@ same vocabulary as a live session.
 // trace.frame_at  { "traceId": "tr1", "stepIndex": 1 }
 Terminal tr1 40x6 revision 2
 semanticTree: available
-dialog "Permission" ref=n1@2 modal
-  button "Approve" ref=n2@2 disabled
+dialog "Permission" ref=semantic:n1@2 modal
+  button "Approve" ref=semantic:n2@2 disabled
 visible text:
 …
 // trace.diff      { "traceId": "tr1", "fromMs": 0, "toMs": 3000 }  -> changed rows + subtrees
@@ -139,8 +217,8 @@ window; lower `screenshotScale` or resize the terminal.
 
 ## Refs and revisions
 
-A ref is `n8@42`: node id at semantic revision 42 (grid matches get
-`grid:1,2,9,1@7`). Refs go straight to `harness.locatorForRef()`, so they resolve
+A ref is `semantic:n8@42`: node id at semantic revision 42 (screen matches get
+`screen:1,2,9,1@7`). Refs go straight to `harness.locatorForRef()`, so they resolve
 by node *identity* — two buttons with the same name stay distinct. A producer
 which promises stable identity can resolve that node again in later revisions.
 Frame-local identities and grid refs remain revision-bound; take a fresh
@@ -148,11 +226,14 @@ snapshot when either becomes stale.
 
 `terminal.snapshot` also returns a screen `revision`; pass it back as the
 `cursor` of `terminal.capture_since` to get only the rows and semantic subtrees
-that changed. Cursors the server never handed out fail with `history-truncated`
-(the last 16 captures per terminal are retained).
+that changed in the latest committed tree. A changed screen does not promise a
+future semantic commit; wait for an explicit semantic condition when one is
+required. Cursors the server never handed out fail with `history-truncated` (the
+last 16 captures per terminal are retained).
 
 Programs without a framework probe or custom semantic producer report
-`semanticTree: unavailable`. There are no invented roles: target them by text.
+`semanticTree: unavailable`. There are no invented roles: target physical
+output with `screenText`.
 
 ## Application logs
 
@@ -216,7 +297,7 @@ are the one thing never recorded: the driver keeps their size only.
 Failures come back as tool results with `isError` set. The text content reads
 
 ```
-error stale-snapshot: ref n8@42 no longer exists at semantic revision 43
+error stale-snapshot: ref semantic:n8@42 no longer exists at semantic revision 43
 suggestion: re-resolve the locator; the node identity is no longer present
 semanticTree: true
 ```

package/dist/bin.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   main
-} from "./chunk-IPNUAUAN.js";
+} from "./chunk-R2N52YYH.js";
+import "./chunk-ROMJP5D3.js";
 
 // src/bin.ts
 process.stdout.on("error", (error) => {

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n/** The `termwright-mcp` executable. All logic lives in `cli.ts`. */\nimport { main } from './cli.js';\n\n// `termwright-mcp agent-context | head` closes the pipe early; that is a normal\n// end of output for a CLI, not a crash.\nprocess.stdout.on('error', (error: NodeJS.ErrnoException) => {\n  if (error.code === 'EPIPE') process.exit(0);\n  throw error;\n});\n\nawait main();\n"],"mappings":";;;;;;AAMA,QAAQ,OAAO,GAAG,SAAS,CAAC,UAAiC;AAC3D,MAAI,MAAM,SAAS,QAAS,SAAQ,KAAK,CAAC;AAC1C,QAAM;AACR,CAAC;AAED,MAAM,KAAK;","names":[]}
+{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n/** The `termwright-mcp` executable. All logic lives in `cli.ts`. */\nimport { main } from './cli.js';\n\n// `termwright-mcp agent-context | head` closes the pipe early; that is a normal\n// end of output for a CLI, not a crash.\nprocess.stdout.on('error', (error: NodeJS.ErrnoException) => {\n  if (error.code === 'EPIPE') process.exit(0);\n  throw error;\n});\n\nawait main();\n"],"mappings":";;;;;;;AAMA,QAAQ,OAAO,GAAG,SAAS,CAAC,UAAiC;AAC3D,MAAI,MAAM,SAAS,QAAS,SAAQ,KAAK,CAAC;AAC1C,QAAM;AACR,CAAC;AAED,MAAM,KAAK;","names":[]}