@termwright/mcp 0.2.0 → 0.3.0

package/dist/docs-85fGFORb.d.ts

@@ -0,0 +1,13 @@
+/** One file of the emitted package, keyed by its path inside the directory. */
+interface SkillFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** Renders the committed tool inventories from the same registry the server exposes. */
+declare function renderMcpToolSurfaceMarkdown(): string;
+/** Builds the agent-skill package in memory. */
+declare function buildAgentSkill(): readonly SkillFile[];
+/** Writes the package into `directory`, creating it if needed. Returns the paths written. */
+declare function writeAgentSkill(directory: string): Promise<readonly string[]>;
+
+export { type SkillFile as S, buildAgentSkill as b, renderMcpToolSurfaceMarkdown as r, writeAgentSkill as w };

package/dist/docs.d.ts

@@ -0,0 +1 @@
+export { r as renderMcpToolSurfaceMarkdown } from './docs-85fGFORb.js';

package/dist/docs.js

@@ -0,0 +1,7 @@
+import {
+  renderMcpToolSurfaceMarkdown
+} from "./chunk-ROMJP5D3.js";
+export {
+  renderMcpToolSurfaceMarkdown
+};
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { TermwrightErrorCode, TerminalHarness, AppLogEvent, ExitStatus, EnvMode, LaunchOptions, AppLogSource, Locator } from '@termwright/driver';
+import { TermwrightErrorCode, TerminalHarness, SemanticLocatorRef, AppLogEvent, ExitStatus, EnvMode, LaunchOptions, AppLogSource, AnyLocator } from '@termwright/driver';
 import { z } from 'zod';
+export { S as SkillFile, b as buildAgentSkill, w as writeAgentSkill } from './docs-85fGFORb.js';
 import { SemanticSnapshot, Rect, SemanticState, SemanticNode, SemanticRole } from '@termwright/protocol';
 export { Rect, SEMANTIC_ROLES, SemanticNode, SemanticRole, SemanticSnapshot, SemanticState } from '@termwright/protocol';
 import { Server } from 'node:http';
@@ -151,16 +152,6 @@ declare function buildAgentContext(): AgentContext;
 /** The one-screen cheat sheet printed by `termwright-mcp usage`. */
 declare function buildUsage(): string;
 
-/** One file of the emitted package, keyed by its path inside the directory. */
-interface SkillFile {
-    readonly path: string;
-    readonly contents: string;
-}
-/** Builds the agent-skill package in memory. */
-declare function buildAgentSkill(): readonly SkillFile[];
-/** Writes the package into `directory`, creating it if needed. Returns the paths written. */
-declare function writeAgentSkill(directory: string): Promise<readonly string[]>;
-
 /** Where the CLI writes. Injectable so tests never touch the real streams. */
 interface CliIo {
     readonly out: (text: string) => void;
@@ -186,8 +177,6 @@ declare function main(): Promise<void>;
 
 /** The driver's view of the visible grid. */
 type ScreenSnapshot = ReturnType<TerminalHarness['screen']>;
-/** Session capabilities as reported after the semantic handshake window. */
-type SessionCapabilities = ReturnType<TerminalHarness['capabilities']>;
 /** State flags an agent may filter on; the value type follows {@link SemanticState}. */
 declare const FILTERABLE_STATES: readonly ["disabled", "focused", "selected", "checked", "expanded", "modal", "busy", "hidden", "readonly"];
 /** Signals `terminal.signal` accepts, mirroring `TerminalHarness['signal']`. */
@@ -225,20 +214,20 @@ declare function diffSemantic(before: SemanticSnapshot | null, after: SemanticSn
  * ```
  * 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
  * visible text:
  * <grid text>
  * ```
  *
  * `bounds` is `(row,column,width,height)` — the field order of the protocol's
- * `Rect`. Refs are `<nodeId>@<semanticRevision>`, byte-identical to the refs the
+ * `Rect`. Refs are `semantic:<nodeId>@<semanticRevision>`, byte-identical to the refs the
  * driver puts on `ResolvedTarget`, so a ref can be quoted back to any tool.
  */
 
 /** One line of the ref list, plus the structured fields behind it. */
 interface RefEntry {
-    readonly ref: string;
+    readonly ref: SemanticLocatorRef;
     readonly role: string;
     readonly name: string;
     readonly depth: number;
@@ -246,10 +235,12 @@ interface RefEntry {
     readonly flags: readonly string[];
     readonly testId?: string;
     readonly value?: string;
+    readonly applicationScroll?: string;
+    readonly paintedRegion?: string;
 }
-/** Formats `n8@42` for a node observed at `revision`. */
-declare function formatRef(nodeId: string, revision: number): string;
-/** Splits `n8@42` back into its parts; returns `null` for anything else. */
+/** Formats an explicitly semantic ref for a node observed at `revision`. */
+declare function formatRef(nodeId: string, revision: number): SemanticLocatorRef;
+/** Splits a semantic ref back into its parts; screen refs are rejected. */
 declare function parseRef(ref: string): {
     readonly nodeId: string;
     readonly revision: number;
@@ -294,6 +285,13 @@ interface CompactSnapshotOptions {
 /** Renders the normative compact snapshot. */
 declare function formatCompactSnapshot(options: CompactSnapshotOptions): string;
 
+/** Bounded fixed-window admission policy, keyed by the TCP peer address. */
+interface HttpRateLimitOptions {
+    readonly windowMs?: number;
+    readonly maxRequests?: number;
+    readonly maxClients?: number;
+}
+
 /**
  * The application's own log, on the session timeline.
  *
@@ -357,6 +355,8 @@ declare class LogBuffer {
     get size(): number;
     /** Records one driver event. */
     append(event: AppLogEvent): void;
+    /** Advances the cursor for source events that were explicitly reported lost. */
+    omit(count: number): void;
     /**
      * Everything after `cursor`, newest-biased and bounded.
      *
@@ -459,6 +459,8 @@ interface TerminalEntry {
     readonly directory: string;
     readonly command: readonly string[];
     exit: ExitStatus | null;
+    /** Backend/lifecycle failure is not a fabricated process exit. */
+    exitFailure?: unknown;
     closed: boolean;
     history: RevisionRecord[];
     /** The application's own log, buffered for `terminal.capture_since`. */
@@ -540,6 +542,8 @@ interface RegisteredSession<T> {
     readonly attachment: T;
     /** Clock reading of the last request that named this session. */
     lastSeenAt: number;
+    /** One shared cleanup transaction; retained on failure so callers observe it. */
+    closing?: Promise<void>;
 }
 /** Options for {@link SessionRegistry}. */
 interface SessionRegistryOptions<T> {
@@ -556,6 +560,8 @@ interface SessionRegistryOptions<T> {
     readonly disposeAttachment?: (attachment: T) => Promise<void> | void;
     /** Called after an idle session was torn down, for the server log. */
     readonly onExpired?: (key: string) => void;
+    /** Receives managed sweeper failures; never an unhandled rejection. */
+    readonly onBackgroundError?: (error: unknown) => void;
 }
 /**
  * Sessions keyed by `Mcp-Session-Id` (or `stdio` for the stdio transport).
@@ -633,12 +639,26 @@ interface HttpServerHandle {
         server: McpServer;
     }>;
     readonly port: number;
+    /** Per-launch bearer required by every HTTP request. Never put it in a URL. */
+    readonly authToken: string;
     close(): Promise<void>;
 }
 /** Options for {@link serveHttp}. */
 interface HttpServeOptions extends ServeOptions {
     readonly port?: number;
     readonly host?: string;
+    /**
+     * Explicit acknowledgement that a non-loopback bind exposes process launch,
+     * terminal input and filesystem-backed trace tools to the network.
+     */
+    readonly allowNonLoopback?: boolean;
+    /**
+     * Browser origins allowed to call the endpoint. Non-browser MCP clients omit
+     * `Origin`; any presented origin is rejected unless it appears here exactly.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /** Per-peer request ceiling. The limiter's identity map is bounded too. */
+    readonly rateLimit?: HttpRateLimitOptions;
     /** Path the MCP endpoint listens on. Defaults to `/mcp`. */
     readonly path?: string;
     /**
@@ -696,7 +716,7 @@ interface ScreenshotRequest {
  *
  * Failures are typed rather than thrown as raw errors: a scale out of range is
  * `usage`, an image over the ceiling is `capacity`, and a renderer that cannot
- * run at all (no font, no rasteriser) is `unsupported-action` — each with the
+ * run at all (no font, no rasteriser) is `capability-unavailable` — each with the
  * next thing to try.
  */
 declare function renderScreenshot(frame: ScreenFrame, request?: ScreenshotRequest): ScreenshotImage;
@@ -785,16 +805,18 @@ declare const TRACE_TOOLS: readonly ToolDefinition[];
  * from zod-parsed arguments, where an absent key is present-and-undefined.
  */
 interface TargetInput {
-    /** A ref from a previous snapshot: `n8@42`, or `grid:1,2,9,1@7`. */
+    /** A domain-tagged ref: `semantic:n8@42`, or `screen:1,2,9,1@7`. */
     readonly ref?: string | undefined;
-    /** The Textual-style CSS dialect, e.g. `dialog button#approve:focused`. */
+    /** Termwright Semantic Selector Language, e.g. `dialog button#approve:focused`. */
     readonly selector?: string | undefined;
     readonly role?: SemanticRole | undefined;
     /** Accessible name; `/…/flags` is read as a regular expression. */
     readonly name?: string | undefined;
     readonly testId?: string | undefined;
-    /** Visible text (grid matching when there is no semantic tree). */
+    /** Text carried by a semantic node. Requires a semantic tree. */
     readonly text?: string | undefined;
+    /** Text rendered in the physical terminal grid. */
+    readonly screenText?: string | undefined;
     /** Label text (`labelledBy`, else name). */
     readonly label?: string | undefined;
     readonly exact?: boolean | undefined;
@@ -809,18 +831,18 @@ interface TargetInput {
 declare function textOrRegExp(value: string): string | RegExp;
 /**
  * Builds the locator described by `input`. Precedence is `ref`, `selector`,
- * `testId`, `role`, `label`, `text` — the order from most to least specific.
+ * `testId`, `role`, `label`, `text`, `screenText` — the order from most to least specific.
  *
  * Every branch hands straight to a driver factory; nothing here matches, waits
  * or decides staleness.
  */
-declare function buildLocator(harness: TerminalHarness, input: TargetInput): Locator;
+declare function buildLocator(harness: TerminalHarness, input: TargetInput): AnyLocator;
 
 /** Identity reported over MCP and by `--version`. Kept in step with package.json. */
 declare const SERVER_NAME = "termwright";
 /** Package version. */
-declare const SERVER_VERSION = "0.1.0";
+declare const SERVER_VERSION = "0.3.0";
 /** Version of the `agent-context` document shape (independent of the package). */
 declare const AGENT_CONTEXT_VERSION = 1;
 
-export { AGENT_CONTEXT_VERSION, type AgentContext, type AgentContextTool, type CliIo, type CompactSnapshotOptions, EXIT_CODES, type ErrorKind, type ErrorPayload, FILTERABLE_STATES, type HttpServeOptions, type HttpServerHandle, type JsonSchema, type LaunchRequest, MCP_LIMITS, McpError, type OpenTrace, type RefEntry, type RegisteredSession, type RevisionRecord, type RowChange, type RunningServer, SCREENSHOT_LIMITS, SERVER_NAME, SERVER_VERSION, SIGNALS, type ScreenSnapshot, type ScreenshotImage, type ScreenshotRequest, type ServeOptions, type SessionCapabilities, SessionRegistry, type SessionStores, type SkillFile, type SubtreeChange, TERMINAL_TOOLS, TOOLS, TRACE_LIMITS, TRACE_TOOLS, type TargetInput, type TerminalEntry, TerminalStore, type TerminalStoreOptions, type ToolContext, type ToolDefinition, type ToolOutcome, TraceStore, type TraceStoreOptions, buildAgentContext, buildAgentSkill, buildLocator, buildUsage, closeSessionStores, createSessionStores, createTermwrightMcpServer, defineTool, diffRows, diffSemantic, exitCodeFor, formatBounds, formatCompactSnapshot, formatNodeLine, formatRef, main, noSessionError, parseRef, refEntries, renderErrorPayload, renderScreenshot, runCli, serveHttp, serveInMemory, serveStdio, stateFlags, textOrRegExp, toErrorPayload, toRefEntry, toolByName, usageError, walkSnapshot, writeAgentSkill };
+export { AGENT_CONTEXT_VERSION, type AgentContext, type AgentContextTool, type CliIo, type CompactSnapshotOptions, EXIT_CODES, type ErrorKind, type ErrorPayload, FILTERABLE_STATES, type HttpRateLimitOptions, type HttpServeOptions, type HttpServerHandle, type JsonSchema, type LaunchRequest, MCP_LIMITS, McpError, type OpenTrace, type RefEntry, type RegisteredSession, type RevisionRecord, type RowChange, type RunningServer, SCREENSHOT_LIMITS, SERVER_NAME, SERVER_VERSION, SIGNALS, type ScreenSnapshot, type ScreenshotImage, type ScreenshotRequest, type ServeOptions, SessionRegistry, type SessionStores, type SubtreeChange, TERMINAL_TOOLS, TOOLS, TRACE_LIMITS, TRACE_TOOLS, type TargetInput, type TerminalEntry, TerminalStore, type TerminalStoreOptions, type ToolContext, type ToolDefinition, type ToolOutcome, TraceStore, type TraceStoreOptions, buildAgentContext, buildLocator, buildUsage, closeSessionStores, createSessionStores, createTermwrightMcpServer, defineTool, diffRows, diffSemantic, exitCodeFor, formatBounds, formatCompactSnapshot, formatNodeLine, formatRef, main, noSessionError, parseRef, refEntries, renderErrorPayload, renderScreenshot, runCli, serveHttp, serveInMemory, serveStdio, stateFlags, textOrRegExp, toErrorPayload, toRefEntry, toolByName, usageError, walkSnapshot };

package/dist/index.js

@@ -1,3 +1,11 @@
+import {
+  createTermwrightMcpServer,
+  main,
+  runCli,
+  serveHttp,
+  serveInMemory,
+  serveStdio
+} from "./chunk-R2N52YYH.js";
 import {
   AGENT_CONTEXT_VERSION,
   EXIT_CODES,
@@ -22,7 +30,6 @@ import {
   buildUsage,
   closeSessionStores,
   createSessionStores,
-  createTermwrightMcpServer,
   defineTool,
   diffRows,
   diffSemantic,
@@ -31,16 +38,11 @@ import {
   formatCompactSnapshot,
   formatNodeLine,
   formatRef,
-  main,
   noSessionError,
   parseRef,
   refEntries,
   renderErrorPayload,
   renderScreenshot,
-  runCli,
-  serveHttp,
-  serveInMemory,
-  serveStdio,
   stateFlags,
   textOrRegExp,
   toErrorPayload,
@@ -49,7 +51,7 @@ import {
   usageError,
   walkSnapshot,
   writeAgentSkill
-} from "./chunk-IPNUAUAN.js";
+} from "./chunk-ROMJP5D3.js";
 export {
   AGENT_CONTEXT_VERSION,
   EXIT_CODES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termwright/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "thin MCP server over the public driver API",
   "license": "MIT",
   "repository": {
@@ -10,7 +10,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": "^22.0.0 || ^24.0.0"
   },
   "exports": {
     ".": {
@@ -27,14 +27,17 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.0.0",
-    "@termwright/driver": "0.2.0",
-    "@termwright/protocol": "0.2.0",
-    "@termwright/screenshot": "0.2.0",
-    "@termwright/trace": "0.2.0"
+    "@termwright/driver": "0.3.0",
+    "@termwright/protocol": "0.3.0",
+    "@termwright/screenshot": "0.3.0",
+    "@termwright/trace": "0.3.0"
+  },
+  "devDependencies": {
+    "@termwright/resource-broker": "0.3.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/bin.ts --format esm --dts --sourcemap",
+    "build": "tsup src/index.ts src/bin.ts src/docs.ts --format esm --dts --sourcemap --clean",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "pnpm --dir ../.. test -- -- --run packages/mcp"
   }
 }