@termwright/mcp 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,826 @@
+import { TermwrightErrorCode, TerminalHarness, AppLogEvent, ExitStatus, EnvMode, LaunchOptions, AppLogSource, Locator } from '@termwright/driver';
+import { z } from 'zod';
+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';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { TraceReader } from '@termwright/trace';
+import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { ScreenFrame } from '@termwright/screenshot';
+
+/**
+ * Crash reports, projected for agents.
+ *
+ * When a program dies on its own — a signal, or a non-zero exit nobody asked
+ * for — the driver keeps what the session knew at that moment: the exit status,
+ * the tail of the screen (where a stack trace lands), the last semantic
+ * revision, the inputs just before the end, and the diagnostics log. This module
+ * bounds that for a tool result and renders it the way an agent reads it.
+ *
+ * **The screen tail is unredacted.** It is whatever the terminal displayed,
+ * secrets included, so it is treated like a screenshot: bounded, never logged,
+ * and flagged as sensitive wherever an agent is told about it.
+ */
+
+/** The crash projection carried in `structuredContent`. */
+declare const crashSchema: z.ZodObject<{
+    exit: z.ZodObject<{
+        code: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    timeMs: z.ZodNumber;
+    screenTail: z.ZodArray<z.ZodString>;
+    screenTailTruncated: z.ZodBoolean;
+    lastSemanticRevision: z.ZodNullable<z.ZodNumber>;
+    recentInputs: z.ZodArray<z.ZodObject<{
+        timeMs: z.ZodNumber;
+        kind: z.ZodEnum<{
+            key: "key";
+            mouse: "mouse";
+            paste: "paste";
+            raw: "raw";
+        }>;
+        bytes: z.ZodNumber;
+        preview: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodString;
+        timeMs: z.ZodNumber;
+        revision: z.ZodOptional<z.ZodNumber>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            mouse: "mouse";
+            focus: "focus";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The structured shape of {@link crashSchema}. */
+type CrashProjection = z.output<typeof crashSchema>;
+
+/**
+ * Kinds an agent can branch on: every driver code, plus the three failures that
+ * never reach the driver.
+ *
+ * Derived from `TermwrightErrorCode` rather than restated, so a code added
+ * upstream is publishable here the moment it lands instead of failing the
+ * assignment in {@link toErrorPayload}.
+ */
+type ErrorKind = TermwrightErrorCode | 'usage' | 'no-session' | 'internal';
+/** CLI exit codes (CONTRACTS.md §MCP). */
+declare const EXIT_CODES: Readonly<{
+    ok: 0;
+    assertion: 1;
+    usage: 2;
+    noSession: 3;
+    ipc: 4;
+    internal: 5;
+}>;
+/** Exit code for a failure of the given kind. */
+declare function exitCodeFor(kind: ErrorKind): number;
+/**
+ * A failure raised by the MCP layer itself (argument validation, unknown
+ * terminal handle, capacity). Structurally identical to `TermwrightError`
+ * (`kind` + `suggestion`) but with a wider kind domain; it never crosses a
+ * package boundary, so it does not need to be a `TermwrightError` subclass.
+ */
+declare class McpError extends Error {
+    readonly kind: ErrorKind;
+    readonly suggestion: string | undefined;
+    constructor(kind: ErrorKind, message: string, suggestion?: string);
+}
+/** Bad or contradictory tool arguments — exit code 2. */
+declare function usageError(message: string, suggestion?: string): McpError;
+/** Unknown or already-closed terminal handle — exit code 3. */
+declare function noSessionError(message: string, suggestion?: string): McpError;
+/** The agent-facing projection of a failure. */
+interface ErrorPayload {
+    readonly kind: ErrorKind;
+    readonly message: string;
+    readonly suggestion?: string;
+    readonly semanticTree?: boolean;
+    readonly candidates?: readonly string[];
+    readonly screenExcerpt?: string;
+    /**
+     * What the session knew when the program died, when the failure happened
+     * around a crash. Its `screenTail` is unredacted — see `crash.ts`.
+     */
+    readonly crash?: CrashProjection;
+}
+/**
+ * Projects any thrown value into an {@link ErrorPayload}. Driver diagnostics
+ * (candidates, screen excerpt, suggestion) are carried over — bounded — because
+ * they are what lets an agent fix its own next call. Stack traces are dropped.
+ */
+declare function toErrorPayload(error: unknown): ErrorPayload;
+/** Renders an {@link ErrorPayload} the way a tool result's text content shows it. */
+declare function renderErrorPayload(payload: ErrorPayload): string;
+
+/** JSON Schema for one tool's input or output. */
+type JsonSchema = Record<string, unknown>;
+/** One tool, as `agent-context` describes it. */
+interface AgentContextTool {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema: JsonSchema;
+    readonly annotations: Readonly<Record<string, unknown>>;
+}
+/** The whole document. */
+interface AgentContext {
+    readonly v: number;
+    readonly server: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly tools: readonly AgentContextTool[];
+    readonly enums: {
+        readonly roles: readonly string[];
+        readonly states: readonly string[];
+        readonly signals: readonly string[];
+        readonly errorKinds: readonly ErrorKind[];
+    };
+    readonly exitCodes: Readonly<Record<string, number>>;
+    readonly limits: Readonly<Record<string, number>>;
+    readonly conventions: readonly string[];
+}
+/** Builds the versioned document from the live tool definitions. */
+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;
+    readonly err: (text: string) => void;
+}
+/**
+ * Runs the CLI and resolves with the process exit code. Serving blocks until
+ * the transport closes, so `serve` only resolves on shutdown.
+ */
+declare function runCli(argv: readonly string[], io?: CliIo): Promise<number>;
+/** Entry point for the `termwright-mcp` bin. */
+declare function main(): Promise<void>;
+
+/**
+ * The protocol- and driver-shaped types this package projects into MCP results.
+ *
+ * Roles, states and snapshot types come straight from `@termwright/protocol`
+ * (CONTRACTS.md §Dependency rules allows `mcp` to import its constants and
+ * types), so there is exactly one source of truth for the closed sets an agent
+ * sees in the tool schemas. Screen- and session-shaped types come from the
+ * driver, which owns them.
+ */
+
+/** 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']`. */
+declare const SIGNALS: readonly ["INT", "TERM", "KILL", "HUP"];
+
+/** A screen row whose text differs from the baseline. */
+interface RowChange {
+    readonly row: number;
+    readonly text: string;
+}
+/** A changed semantic subtree, identified by the ref of its root. */
+interface SubtreeChange {
+    readonly change: 'added' | 'removed' | 'updated';
+    readonly ref: string;
+    readonly role: string;
+    readonly name: string;
+    /** The subtree in compact ref format, one node per line, indented. */
+    readonly compact: string;
+}
+/** Rows present in `after` but different (or absent) in `before`. */
+declare function diffRows(before: readonly string[], after: readonly string[]): readonly RowChange[];
+/**
+ * Changed subtrees between two semantic snapshots, matched by node id.
+ *
+ * Only *minimal roots* are reported: when a node and its parent both changed,
+ * the parent's subtree already contains the child, so the child is folded in.
+ * Removals are reported with the ref they had in the baseline.
+ */
+declare function diffSemantic(before: SemanticSnapshot | null, after: SemanticSnapshot | null): readonly SubtreeChange[];
+
+/**
+ * The compact snapshot format from CONTRACTS.md §MCP. It is normative, so this
+ * module is deliberately small and covered by a golden test:
+ *
+ * ```
+ * Terminal t1 100x30 revision 42
+ * semanticTree: available
+ * dialog "Permission" ref=n7@42 bounds=(8,20,40,9) modal
+ *   button "Approve" ref=n8@42 bounds=(14,23,11,1) focused
+ * visible text:
+ * <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
+ * 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 role: string;
+    readonly name: string;
+    readonly depth: number;
+    readonly bounds?: Rect;
+    readonly flags: readonly string[];
+    readonly testId?: string;
+    readonly value?: 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. */
+declare function parseRef(ref: string): {
+    readonly nodeId: string;
+    readonly revision: number;
+} | null;
+/** Renders a rect as `(row,column,width,height)`. */
+declare function formatBounds(bounds: Rect): string;
+/**
+ * The trailing flag list of a node line: every asserted state, in the closed
+ * order of the protocol's state set. Booleans render as bare names (`modal`),
+ * everything else as `name=value` (`checked=mixed`, `level=2`).
+ */
+declare function stateFlags(state: SemanticState | undefined): readonly string[];
+/** Renders one node line (without indentation). */
+declare function formatNodeLine(entry: RefEntry): string;
+/** Depth-first walk of a snapshot in document order, roots first. */
+declare function walkSnapshot(snapshot: SemanticSnapshot): readonly {
+    node: SemanticNode;
+    depth: number;
+}[];
+/** Turns a snapshot into ref entries in document order. */
+declare function refEntries(snapshot: SemanticSnapshot): readonly RefEntry[];
+/** Projects a single node into a {@link RefEntry}. */
+declare function toRefEntry(node: SemanticNode, revision: number, depth?: number): RefEntry;
+/** Options for {@link formatCompactSnapshot}. */
+interface CompactSnapshotOptions {
+    /** Terminal handle, e.g. `t1`. */
+    readonly terminal: string;
+    readonly columns: number;
+    readonly rows: number;
+    /** Screen revision — the cursor `terminal.capture_since` takes. */
+    readonly revision: number;
+    readonly semantic: SemanticSnapshot | null;
+    /** Visible grid text, one entry per row. */
+    readonly text: readonly string[];
+    /** Cap on listed nodes; the remainder is summarised on one line. */
+    readonly maxNodes?: number;
+    /** Cap on rendered rows; the remainder is summarised on one line. */
+    readonly maxRows?: number;
+    /** Omit the `visible text:` block (the `full` variant writes it to disk). */
+    readonly includeText?: boolean;
+}
+/** Renders the normative compact snapshot. */
+declare function formatCompactSnapshot(options: CompactSnapshotOptions): string;
+
+/**
+ * The application's own log, on the session timeline.
+ *
+ * A terminal shows what a program *drew*; its log says what the program
+ * *decided*. That gap is where "the screen looks right but nothing happened"
+ * lives, so an agent that can read both stops guessing.
+ *
+ * The driver publishes `app-log` events — a followed file yields a raw line, an
+ * instrumented adapter yields a structured record — and this module buffers
+ * them per terminal so `terminal.capture_since` can hand back everything since
+ * a cursor.
+ */
+
+/** One buffered log entry, as an agent reads it. */
+declare const logEntrySchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    timeMs: z.ZodNumber;
+    source: z.ZodEnum<{
+        file: "file";
+        adapter: "adapter";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        fatal: "fatal";
+    }>>;
+    message: z.ZodString;
+    logger: z.ZodOptional<z.ZodString>;
+    attrs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    revision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The structured shape of {@link logEntrySchema}. */
+type LogEntry = z.output<typeof logEntrySchema>;
+/** What a read since a cursor found. */
+interface LogWindow {
+    readonly entries: readonly LogEntry[];
+    /**
+     * Entries that existed between the cursor and the oldest one still buffered,
+     * plus any trimmed to fit the response ceiling.
+     *
+     * Computed **at read time** from sequence numbers rather than accumulated in
+     * a counter as entries are dropped. A counter that is only published with the
+     * next event silently loses the final window — exactly when a program has
+     * gone quiet because it died, which is when the number matters most.
+     */
+    readonly omitted: number;
+    /** Pass as the next cursor; equals the newest sequence number seen. */
+    readonly cursor: number;
+}
+/** A bounded, per-terminal ring of log entries. */
+declare class LogBuffer {
+    #private;
+    constructor(capacity?: number);
+    /** Sequence number of the newest entry; 0 when nothing has arrived. */
+    get sequence(): number;
+    /** Entries currently retained. */
+    get size(): number;
+    /** Records one driver event. */
+    append(event: AppLogEvent): void;
+    /**
+     * Everything after `cursor`, newest-biased and bounded.
+     *
+     * A cursor older than the buffer is not an error: the entries in between are
+     * counted in {@link LogWindow.omitted} so an agent knows its view has a hole,
+     * rather than quietly seeing a shorter list.
+     */
+    since(cursor: number, limit?: number): LogWindow;
+}
+
+/**
+ * The same properties, but optional ones may also be explicitly `undefined` —
+ * the shape zod produces for `.optional()` fields.
+ */
+type Loose<T> = {
+    [K in keyof T]?: T[K] | undefined;
+};
+
+/** Ceilings for the replay side of the server. */
+declare const TRACE_LIMITS: Readonly<{
+    /** Archives kept open per MCP session; the least recently used is evicted. */
+    maxOpen: 8;
+    /** Refusal threshold for an archive, in bytes. */
+    maxArchiveBytes: number;
+    /** Rows of reconstructed screen text a single frame may return. */
+    maxFrameRows: 200;
+}>;
+/** One archive this session has open. */
+interface OpenTrace {
+    /** Agent-facing handle, `tr1`, `tr2`, … */
+    readonly id: string;
+    readonly path: string;
+    readonly reader: TraceReader;
+    /** Bumped on every use, so eviction drops the coldest archive. */
+    lastUsedAt: number;
+}
+/** Options for {@link TraceStore}. */
+interface TraceStoreOptions {
+    readonly maxOpen?: number;
+    readonly maxArchiveBytes?: number;
+    /** Injectable clock, for tests. */
+    readonly now?: () => number;
+}
+/** The `.twtrace` archives one MCP session has open. */
+declare class TraceStore {
+    #private;
+    constructor(options?: TraceStoreOptions);
+    /** Handles of every archive still open. */
+    list(): readonly OpenTrace[];
+    /**
+     * Opens an archive and registers it under a fresh `tr<n>` handle.
+     *
+     * At the ceiling the least recently used archive is closed rather than the
+     * call being refused: an agent can always re-open a path, but it cannot
+     * recover from a server that has wedged itself on old readers. The evicted
+     * handle is reported so the caller knows why it stopped working.
+     */
+    open(path: string): Promise<{
+        readonly trace: OpenTrace;
+        readonly evicted: string | null;
+    }>;
+    /** Looks up a handle and marks it as used. */
+    get(id: string): OpenTrace;
+    /** Closes every open archive. Best-effort, so shutdown always completes. */
+    closeAll(): Promise<void>;
+}
+
+/**
+ * Ceilings for the MCP layer. The session counts come from
+ * `DEFAULT_LIMITS` in `@termwright/protocol`; the rest are this package's own
+ * (how much capture history a terminal keeps, how long a command line may be).
+ */
+declare const MCP_LIMITS: Readonly<{
+    /** Concurrent MCP sessions. */
+    maxSessions: number;
+    /** Concurrent terminals inside one MCP session. */
+    maxTerminals: number;
+    /** Snapshots retained per terminal for `capture_since` cursors. */
+    maxHistory: 16;
+    /** Argument ceiling for a launch command line. */
+    maxCommandParts: 64;
+}>;
+/** A snapshot the server handed out, kept so a later cursor can diff against it. */
+interface RevisionRecord {
+    /** Screen revision; this is the `cursor` value agents pass back. */
+    readonly revision: number;
+    readonly semanticRevision: number | null;
+    readonly rows: readonly string[];
+    readonly semantic: SemanticSnapshot | null;
+    /** Log sequence at capture time, so a later diff knows where to resume. */
+    readonly logSeq: number;
+    readonly capturedAt: number;
+}
+/** One terminal owned by one MCP session. */
+interface TerminalEntry {
+    /** Agent-facing handle, `t1`, `t2`, … */
+    readonly id: string;
+    readonly harness: TerminalHarness;
+    /** Directory for `variant: "full"` dumps; created lazily. */
+    readonly directory: string;
+    readonly command: readonly string[];
+    exit: ExitStatus | null;
+    closed: boolean;
+    history: RevisionRecord[];
+    /** The application's own log, buffered for `terminal.capture_since`. */
+    readonly logs: LogBuffer;
+}
+/** Options for {@link TerminalStore}. */
+interface TerminalStoreOptions {
+    /** Stable key of the owning MCP session (`stdio`, or an `Mcp-Session-Id`). */
+    readonly sessionKey: string;
+    /** Root for on-disk snapshot dumps. Defaults to `<tmp>/termwright-mcp`. */
+    readonly storageDir?: string;
+    readonly maxTerminals?: number;
+    /** Injectable clock, for tests. */
+    readonly now?: () => number;
+}
+/**
+ * Arguments accepted by {@link TerminalStore.launch}. Optional fields admit an
+ * explicit `undefined` because they arrive from zod-parsed tool arguments.
+ */
+interface LaunchRequest {
+    readonly command: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    readonly envMode?: EnvMode | undefined;
+    readonly columns?: number | undefined;
+    readonly rows?: number | undefined;
+    readonly scrollbackLines?: number | undefined;
+    readonly semanticNegotiationMs?: number | undefined;
+    readonly timeouts?: Loose<NonNullable<LaunchOptions['timeouts']>> | undefined;
+    /** Log files to follow for the lifetime of the session. */
+    readonly logs?: readonly Loose<AppLogSource>[] | undefined;
+}
+/** The terminals of a single MCP session, plus their capture history. */
+declare class TerminalStore {
+    #private;
+    readonly sessionKey: string;
+    constructor(options: TerminalStoreOptions);
+    /** Handles of every terminal still open in this session. */
+    list(): readonly TerminalEntry[];
+    /** Launches a child and registers it under a fresh `t<n>` handle. */
+    launch(request: LaunchRequest): Promise<TerminalEntry>;
+    /** Looks up a handle without throwing; for callers that tolerate absence. */
+    find(id: string): TerminalEntry | undefined;
+    /** Looks up a handle; unknown or closed handles are a `no-session` failure. */
+    get(id: string): TerminalEntry;
+    /**
+     * Captures the current screen and semantic tree, and remembers it so a later
+     * `capture_since` can diff against this revision.
+     */
+    record(entry: TerminalEntry): RevisionRecord;
+    /** The recorded baseline for a cursor, or a `history-truncated` failure. */
+    baseline(entry: TerminalEntry, cursor: number): RevisionRecord;
+    /** Writes a full dump next to the session and returns its path. */
+    writeDump(entry: TerminalEntry, name: string, contents: string): Promise<string>;
+    /** Closes one terminal and forgets it. Idempotent. */
+    close(id: string): Promise<TerminalEntry>;
+    /** Closes every terminal; failures are swallowed so shutdown always completes. */
+    closeAll(): Promise<void>;
+}
+/**
+ * Everything one MCP session owns: the terminals it launched and the trace
+ * archives it opened. Both are disposed together when the session goes away.
+ */
+interface SessionStores {
+    readonly terminals: TerminalStore;
+    readonly traces: TraceStore;
+}
+/** Builds the stores for a session key. */
+declare function createSessionStores(options: {
+    readonly sessionKey: string;
+    readonly storageDir?: string | undefined;
+}): SessionStores;
+/** Closes both stores of a session. */
+declare function closeSessionStores(stores: SessionStores): Promise<void>;
+/** A registered MCP session: its key, its stores, and its disposer. */
+interface RegisteredSession<T> {
+    readonly key: string;
+    readonly stores: SessionStores;
+    readonly attachment: T;
+    /** Clock reading of the last request that named this session. */
+    lastSeenAt: number;
+}
+/** Options for {@link SessionRegistry}. */
+interface SessionRegistryOptions<T> {
+    readonly maxSessions?: number;
+    readonly storageDir?: string;
+    /**
+     * Milliseconds a session may sit idle before it is torn down. `0` disables
+     * expiry, which is what stdio wants: there, EOF on the pipe is the signal.
+     */
+    readonly idleTtlMs?: number;
+    /** Injectable clock, for tests. */
+    readonly now?: () => number;
+    /** Released alongside the stores — the transport, for a socket-backed session. */
+    readonly disposeAttachment?: (attachment: T) => Promise<void> | void;
+    /** Called after an idle session was torn down, for the server log. */
+    readonly onExpired?: (key: string) => void;
+}
+/**
+ * Sessions keyed by `Mcp-Session-Id` (or `stdio` for the stdio transport).
+ * The registry — not the transport — owns the lifetime and the ceiling.
+ */
+declare class SessionRegistry<T> {
+    #private;
+    constructor(options?: SessionRegistryOptions<T>);
+    /** The configured idle ceiling; `0` when expiry is disabled. */
+    get idleTtlMs(): number;
+    /**
+     * Marks a session as used. Called for **every** request that names one, so a
+     * session stays alive exactly as long as someone is talking to it.
+     */
+    touch(key: string): void;
+    /**
+     * Tears down every session idle past the TTL and returns their keys.
+     *
+     * Streamable HTTP has no disconnect signal: a client that crashes or walks
+     * away leaves its session, its terminals and their children running, and its
+     * slot taken. Repeated agent failures would then add up to an accidental
+     * denial of service against the operator's own machine, so idleness is the
+     * only honest liveness signal available here.
+     */
+    sweepIdle(): Promise<readonly string[]>;
+    /**
+     * Runs {@link sweepIdle} on a timer until the returned function is called.
+     * The timer is unref'd, so it never keeps a process alive on its own.
+     */
+    startIdleSweeper(intervalMs?: number): () => void;
+    /** Stops the sweeper started by {@link startIdleSweeper}. Idempotent. */
+    stopIdleSweeper(): void;
+    get size(): number;
+    /** True when another session would exceed the ceiling. */
+    get atCapacity(): boolean;
+    /** Creates a session and its stores; throws `capacity` at the ceiling. */
+    create(key: string, attach: (stores: SessionStores) => T): RegisteredSession<T>;
+    get(key: string): RegisteredSession<T> | undefined;
+    /** Removes a session and closes everything it owned. */
+    delete(key: string): Promise<void>;
+    /** Closes every session and stops the sweeper. */
+    closeAll(): Promise<void>;
+}
+
+/** Registers every tool from {@link TOOLS} on a fresh `McpServer`. */
+declare function createTermwrightMcpServer(stores: SessionStores): McpServer;
+/** A running server plus the handle needed to shut it down. */
+interface RunningServer {
+    readonly server: McpServer;
+    readonly stores: SessionStores;
+    close(): Promise<void>;
+}
+/** Options shared by the transports. */
+interface ServeOptions {
+    /** Root for `variant: "full"` snapshot dumps. */
+    readonly storageDir?: string;
+    readonly maxSessions?: number;
+}
+/** Serves the tools over stdio — the transport an MCP host spawns. */
+declare function serveStdio(options?: ServeOptions): Promise<RunningServer>;
+/**
+ * An in-process client/server pair over `InMemoryTransport`. Used by this
+ * package's tests, and by anything embedding the tools without a socket.
+ */
+declare function serveInMemory(options?: ServeOptions & {
+    readonly sessionKey?: string;
+}): Promise<RunningServer & {
+    readonly clientTransport: Transport;
+}>;
+/** A listening Streamable HTTP server. */
+interface HttpServerHandle {
+    readonly http: Server;
+    readonly registry: SessionRegistry<{
+        transport: StreamableHTTPServerTransport;
+        server: McpServer;
+    }>;
+    readonly port: number;
+    close(): Promise<void>;
+}
+/** Options for {@link serveHttp}. */
+interface HttpServeOptions extends ServeOptions {
+    readonly port?: number;
+    readonly host?: string;
+    /** Path the MCP endpoint listens on. Defaults to `/mcp`. */
+    readonly path?: string;
+    /**
+     * Milliseconds a session may sit idle before it is torn down. Defaults to
+     * {@link DEFAULT_IDLE_TTL_MS}; `0` disables expiry.
+     */
+    readonly idleTtlMs?: number;
+    /** Injectable clock, for tests. */
+    readonly now?: () => number;
+    /** Where an expiry is reported. Defaults to stderr. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Serves the tools over Streamable HTTP with multi-session support.
+ *
+ * Sessions live in {@link SessionRegistry}: `initialize` mints a session id and
+ * registers a store together with its transport, every later request is routed
+ * by its `Mcp-Session-Id` header, and `DELETE` (or transport close) disposes the
+ * session's terminals. The ceiling is enforced here, before a transport exists.
+ */
+declare function serveHttp(options?: HttpServeOptions): Promise<HttpServerHandle>;
+
+/** Ceilings for images leaving the server. */
+declare const SCREENSHOT_LIMITS: Readonly<{
+    /**
+     * Refusal threshold for one PNG, in bytes.
+     *
+     * An MCP result travels inside a JSON-RPC message, and base64 inflates it by
+     * a third: a screenshot larger than this is more likely to blow a context
+     * window than to answer a question, so it fails with a suggestion instead.
+     */
+    maxPngBytes: number;
+    /** Pixel density multiplier ceiling. */
+    maxScale: 3;
+}>;
+/** An image ready to be attached to a tool result. */
+interface ScreenshotImage {
+    /** Base64 PNG, as `ImageContent.data` requires. */
+    readonly data: string;
+    readonly mimeType: 'image/png';
+    readonly width: number;
+    readonly height: number;
+    /** False when a character had no embedded outline; see `fallbackCharacters`. */
+    readonly selfContained: boolean;
+    readonly fallbackCharacters: readonly string[];
+}
+/** How a caller asks for an image. */
+interface ScreenshotRequest {
+    readonly scale?: number | undefined;
+    /** Light background instead of the default dark one. */
+    readonly theme?: 'dark' | 'light' | undefined;
+}
+/**
+ * Renders `frame` to a PNG.
+ *
+ * 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
+ * next thing to try.
+ */
+declare function renderScreenshot(frame: ScreenFrame, request?: ScreenshotRequest): ScreenshotImage;
+
+/**
+ * The small kit every tool definition is built from: what a handler is given,
+ * what it returns, and the `defineTool` helper that keeps input schema, output
+ * schema and handler types in step.
+ *
+ * It lives apart from the tool files so that `tools.ts` (live terminals) and
+ * `trace-tools.ts` (recorded sessions) can share it without importing each
+ * other.
+ */
+
+/** What a tool handler is given besides its arguments: the session's stores. */
+interface ToolContext {
+    readonly terminals: TerminalStore;
+    readonly traces: TraceStore;
+}
+/** A handler's result: the text block an agent reads, plus the structured data. */
+interface ToolOutcome<T> {
+    readonly text: string;
+    readonly data: T;
+    /**
+     * Images attached to the result as `ImageContent`, when the caller asked for
+     * one. Text and structured data are never replaced by an image — an agent
+     * that cannot see pictures loses nothing.
+     */
+    readonly images?: readonly ScreenshotImage[];
+}
+/** A registered tool, in the form both the server and `agent-context` consume. */
+interface ToolDefinition {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, z.ZodType>;
+    readonly outputSchema: Record<string, z.ZodType>;
+    readonly annotations: ToolAnnotations;
+    /**
+     * Args are typed `never` in the erased form so that any concrete handler is
+     * assignable; the server passes the values zod already validated.
+     */
+    readonly handler: (context: ToolContext, args: never) => Promise<ToolOutcome<Record<string, unknown>>>;
+}
+declare function defineTool<I extends Record<string, z.ZodType>, O extends Record<string, z.ZodType>>(definition: {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: I;
+    readonly outputSchema: O;
+    readonly annotations?: ToolAnnotations;
+    readonly handler: (context: ToolContext, args: z.output<z.ZodObject<I>>) => Promise<ToolOutcome<z.output<z.ZodObject<O>>>>;
+}): ToolDefinition;
+
+/**
+ * The tool registry: everything the server exposes, in one ordered list.
+ *
+ * Live-terminal tools come first (CONTRACTS.md §MCP), replay tools after. The
+ * server, `agent-context` and the `skill` package all read this list, so a tool
+ * is registered, documented and distributed by being added here once.
+ */
+
+/** Every tool this server exposes. */
+declare const TOOLS: readonly ToolDefinition[];
+/** Convenience lookup used by the server and by tests. */
+declare function toolByName(name: string): ToolDefinition | undefined;
+
+/** The live-terminal tools, in the order CONTRACTS.md §MCP lists them. */
+declare const TERMINAL_TOOLS: readonly ToolDefinition[];
+
+/** The replay tools, in the order an investigation uses them. */
+declare const TRACE_TOOLS: readonly ToolDefinition[];
+
+/**
+ * Turning a tool's target arguments into a driver `Locator`.
+ *
+ * This module owns *no* matching logic: it picks the driver locator factory the
+ * arguments describe and hands everything else — strictness, waiting, staleness,
+ * candidate diagnostics — to `@termwright/driver`.
+ */
+
+/**
+ * The target arguments every acting tool accepts. Exactly one selector wins.
+ *
+ * Optional fields admit an explicit `undefined` because they arrive straight
+ * 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`. */
+    readonly ref?: string | undefined;
+    /** The Textual-style CSS dialect, 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). */
+    readonly text?: string | undefined;
+    /** Label text (`labelledBy`, else name). */
+    readonly label?: string | undefined;
+    readonly exact?: boolean | undefined;
+    readonly state?: Readonly<Loose<SemanticState>> | undefined;
+    /** Zero-based pick among multiple matches; strict mode applies when omitted. */
+    readonly nth?: number | undefined;
+}
+/**
+ * Reads `/pattern/flags` as a RegExp and anything else as a literal string —
+ * the same convention the YAML snapshot format uses for names.
+ */
+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.
+ *
+ * Every branch hands straight to a driver factory; nothing here matches, waits
+ * or decides staleness.
+ */
+declare function buildLocator(harness: TerminalHarness, input: TargetInput): Locator;
+
+/** 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";
+/** 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 };