@termwright/mcp 0.2.0 → 0.3.0

package/dist/chunk-R2N52YYH.js

@@ -0,0 +1,629 @@
+import {
+  CrashContextError,
+  EXIT_CODES,
+  SERVER_NAME,
+  SERVER_VERSION,
+  SessionRegistry,
+  TOOLS,
+  buildAgentContext,
+  buildAgentSkill,
+  buildUsage,
+  closeSessionStores,
+  createSessionStores,
+  describeCrash,
+  exitCodeFor,
+  renderErrorPayload,
+  toErrorPayload,
+  usageError,
+  writeAgentSkill
+} from "./chunk-ROMJP5D3.js";
+
+// src/server.ts
+import { createServer } from "http";
+import { randomBytes, randomUUID } from "crypto";
+
+// src/http-security.ts
+import { timingSafeEqual } from "crypto";
+import { isIP } from "net";
+var DEFAULT_HTTP_RATE_LIMIT = Object.freeze({
+  windowMs: 6e4,
+  maxRequests: 120,
+  maxClients: 1024
+});
+var BoundedRateLimiter = class {
+  #windowMs;
+  #maxRequests;
+  #maxClients;
+  #buckets = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.#windowMs = positiveInteger(
+      options.windowMs ?? DEFAULT_HTTP_RATE_LIMIT.windowMs,
+      "rateLimit.windowMs"
+    );
+    this.#maxRequests = positiveInteger(
+      options.maxRequests ?? DEFAULT_HTTP_RATE_LIMIT.maxRequests,
+      "rateLimit.maxRequests"
+    );
+    this.#maxClients = positiveInteger(
+      options.maxClients ?? DEFAULT_HTTP_RATE_LIMIT.maxClients,
+      "rateLimit.maxClients"
+    );
+  }
+  /** Visible for deterministic tests and operational diagnostics. */
+  get size() {
+    return this.#buckets.size;
+  }
+  admit(identity, now) {
+    if (!Number.isFinite(now)) throw new TypeError("rate-limit clock must return a finite number");
+    let bucket = this.#buckets.get(identity);
+    if (bucket !== void 0 && now - bucket.startedAt >= this.#windowMs) {
+      this.#buckets.delete(identity);
+      bucket = void 0;
+    }
+    if (bucket === void 0) {
+      if (this.#buckets.size >= this.#maxClients) this.#purgeExpired(now);
+      if (this.#buckets.size >= this.#maxClients) {
+        return { allowed: false, retryAfterSeconds: this.#retryForOldest(now) };
+      }
+      this.#buckets.set(identity, { startedAt: now, requests: 1 });
+      return { allowed: true, retryAfterSeconds: 0 };
+    }
+    if (bucket.requests >= this.#maxRequests) {
+      return {
+        allowed: false,
+        retryAfterSeconds: secondsUntil(bucket.startedAt + this.#windowMs, now)
+      };
+    }
+    bucket.requests += 1;
+    return { allowed: true, retryAfterSeconds: 0 };
+  }
+  #purgeExpired(now) {
+    for (const [identity, bucket] of this.#buckets) {
+      if (now - bucket.startedAt >= this.#windowMs) this.#buckets.delete(identity);
+    }
+  }
+  #retryForOldest(now) {
+    let oldestExpiry = Number.POSITIVE_INFINITY;
+    for (const bucket of this.#buckets.values()) {
+      oldestExpiry = Math.min(oldestExpiry, bucket.startedAt + this.#windowMs);
+    }
+    return Number.isFinite(oldestExpiry) ? secondsUntil(oldestExpiry, now) : 1;
+  }
+};
+function normalizeAllowedOrigins(origins = []) {
+  const normalized = /* @__PURE__ */ new Set();
+  for (const candidate of origins) {
+    let url;
+    try {
+      url = new URL(candidate);
+    } catch {
+      throw new TypeError(`allowed origin is not a URL: ${JSON.stringify(candidate)}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+      throw new TypeError(
+        `allowed origin must be an HTTP(S) origin without path, query or credentials: ${JSON.stringify(candidate)}`
+      );
+    }
+    normalized.add(url.origin);
+  }
+  return normalized;
+}
+function isLoopbackHost(host) {
+  const lower = host.toLowerCase().replace(/^\[|\]$/gu, "");
+  if (lower === "localhost" || lower === "::1") return true;
+  if (isIP(lower) === 4) return lower.split(".")[0] === "127";
+  return /^::ffff:127(?:\.\d{1,3}){3}$/u.test(lower);
+}
+function admitHttpRequest(request, response, options) {
+  const identity = request.socket.remoteAddress ?? "<unknown-peer>";
+  const origin = request.headers.origin;
+  if (origin !== void 0 && (Array.isArray(origin) || !options.allowedOrigins.has(origin))) {
+    sendSecurityError(response, 403, "origin is not allowed");
+    return false;
+  }
+  if (typeof origin === "string") {
+    response.setHeader("access-control-allow-origin", origin);
+    response.setHeader("access-control-expose-headers", "Mcp-Session-Id");
+    response.setHeader("vary", "Origin");
+    if (request.method === "OPTIONS") {
+      if (!admitRate(identity, response, options.preflightRateLimiter, options.now)) return false;
+      return admitPreflight(request, response);
+    }
+  }
+  if (!bearerMatches(request.headers.authorization, options.token)) {
+    sendSecurityError(response, 401, "missing or invalid bearer token", {
+      "www-authenticate": 'Bearer realm="termwright-mcp"'
+    });
+    return false;
+  }
+  if (!admitRate(identity, response, options.authenticatedRateLimiter, options.now)) return false;
+  return true;
+}
+function admitRate(identity, response, limiter, now) {
+  const rate = limiter.admit(identity, now());
+  if (rate.allowed) return true;
+  sendSecurityError(response, 429, "rate limit exceeded", {
+    "retry-after": String(rate.retryAfterSeconds)
+  });
+  return false;
+}
+var CORS_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "DELETE"]);
+var CORS_HEADERS = /* @__PURE__ */ new Set([
+  "accept",
+  "authorization",
+  "content-type",
+  "last-event-id",
+  "mcp-protocol-version",
+  "mcp-session-id"
+]);
+function admitPreflight(request, response) {
+  const method = request.headers["access-control-request-method"];
+  const requestedHeaders = (request.headers["access-control-request-headers"] ?? "").split(",").map((header) => header.trim().toLowerCase()).filter((header) => header !== "");
+  if (typeof method !== "string" || !CORS_METHODS.has(method.toUpperCase()) || requestedHeaders.some((header) => !CORS_HEADERS.has(header))) {
+    sendSecurityError(response, 403, "CORS preflight is not allowed");
+    return false;
+  }
+  response.writeHead(204, {
+    "access-control-allow-methods": [...CORS_METHODS].join(", "),
+    "access-control-allow-headers": [...CORS_HEADERS].join(", "),
+    "access-control-max-age": "600"
+  });
+  response.end();
+  return false;
+}
+function bearerMatches(header, expected) {
+  if (header === void 0 || !header.startsWith("Bearer ")) return false;
+  const provided = header.slice("Bearer ".length);
+  const left = Buffer.from(provided, "utf8");
+  const right = Buffer.from(expected, "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function sendSecurityError(response, status, error, headers = {}) {
+  const text = JSON.stringify({ error });
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    connection: "close",
+    "content-type": "application/json",
+    ...headers
+  });
+  response.end(text);
+}
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0)
+    throw new TypeError(`${name} must be a positive safe integer`);
+  return value;
+}
+function secondsUntil(deadline, now) {
+  return Math.max(1, Math.ceil((deadline - now) / 1e3));
+}
+
+// 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 semantic:n8@42 are only valid at semantic revision 42 \u2014 re-snapshot after the screen changes. Programs without a termwright adapter report semanticTree: unavailable; target them by text instead of by role.";
+function successResult(outcome) {
+  return {
+    content: [
+      { type: "text", text: outcome.text },
+      ...(outcome.images ?? []).map((image) => ({
+        type: "image",
+        data: image.data,
+        mimeType: image.mimeType
+      }))
+    ],
+    structuredContent: outcome.data
+  };
+}
+function withCrashContext(context, args, error) {
+  if (error instanceof CrashContextError) return error;
+  const id = args?.terminal;
+  if (typeof id !== "string") return error;
+  const report = context.terminals.find(id)?.harness.crashReport();
+  return report === void 0 || report === null ? error : new CrashContextError(error, describeCrash(report));
+}
+var ERROR_META_KEY = "io.termwright/error";
+function errorResult(error) {
+  const payload = toErrorPayload(error);
+  return {
+    isError: true,
+    content: [{ type: "text", text: renderErrorPayload(payload) }],
+    _meta: { [ERROR_META_KEY]: payload }
+  };
+}
+function createTermwrightMcpServer(stores) {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} }, instructions: INSTRUCTIONS }
+  );
+  const context = { terminals: stores.terminals, traces: stores.traces };
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations
+      },
+      async (args) => {
+        try {
+          return successResult(await tool.handler(context, args));
+        } catch (error) {
+          return errorResult(withCrashContext(context, args, error));
+        }
+      }
+    );
+  }
+  return server;
+}
+async function connect(stores, transport) {
+  const server = createTermwrightMcpServer(stores);
+  try {
+    await connectTransport(server, transport);
+  } catch (error) {
+    const cleanup = await Promise.allSettled([closeSessionStores(stores), server.close()]);
+    const failures = cleanup.flatMap(
+      (result) => result.status === "rejected" ? [result.reason] : []
+    );
+    if (failures.length > 0)
+      throw new AggregateError([error, ...failures], "MCP transport startup and rollback failed");
+    throw error;
+  }
+  return {
+    server,
+    stores,
+    close: async () => {
+      const results = await Promise.allSettled([closeSessionStores(stores), server.close()]);
+      const failures = results.flatMap(
+        (result) => result.status === "rejected" ? [result.reason] : []
+      );
+      if (failures.length > 0)
+        throw new AggregateError(failures, "MCP transport failed to close cleanly");
+    }
+  };
+}
+async function serveStdio(options = {}) {
+  const stores = createSessionStores({ sessionKey: "stdio", storageDir: options.storageDir });
+  return connect(stores, new StdioServerTransport());
+}
+async function serveInMemory(options = {}) {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const stores = createSessionStores({
+    sessionKey: options.sessionKey ?? "in-memory",
+    storageDir: options.storageDir
+  });
+  const running = await connect(stores, serverTransport);
+  return { ...running, clientTransport };
+}
+var DEFAULT_IDLE_TTL_MS = 10 * 6e4;
+function sendJson(response, status, body) {
+  const text = JSON.stringify(body);
+  response.writeHead(status, { "content-type": "application/json" });
+  response.end(text);
+}
+async function readBody(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.from(chunk);
+    size += buffer.byteLength;
+    if (size > 4 * 1024 * 1024) throw new Error("request body too large");
+    chunks.push(buffer);
+  }
+  if (chunks.length === 0) return void 0;
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+async function serveHttp(options = {}) {
+  const path = options.path ?? "/mcp";
+  const host = options.host ?? "127.0.0.1";
+  if (!isLoopbackHost(host) && options.allowNonLoopback !== true) {
+    throw usageError(
+      `refusing non-loopback MCP HTTP bind ${JSON.stringify(host)} without allowNonLoopback`,
+      "keep the default loopback bind, or explicitly acknowledge the remote trust boundary"
+    );
+  }
+  const authToken = randomBytes(32).toString("base64url");
+  const allowedOrigins = normalizeAllowedOrigins(options.allowedOrigins);
+  const authenticatedRateLimiter = new BoundedRateLimiter(options.rateLimit);
+  const preflightRateLimiter = new BoundedRateLimiter(options.rateLimit);
+  const now = options.now ?? Date.now;
+  const log = options.log ?? ((message) => void process.stderr.write(`${message}
+`));
+  const registry = new SessionRegistry({
+    ...options.maxSessions === void 0 ? {} : { maxSessions: options.maxSessions },
+    ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir },
+    ...options.now === void 0 ? {} : { now: options.now },
+    idleTtlMs: options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS,
+    disposeAttachment: async (attachment) => {
+      await attachment.transport.close();
+    },
+    onExpired: (key) => {
+      log(`termwright: session ${key} expired after idling; terminals and traces released`);
+    },
+    onBackgroundError: (error) => {
+      log(
+        `termwright: idle session cleanup failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  });
+  const http = createServer((request, response) => {
+    void (async () => {
+      try {
+        if (!admitHttpRequest(request, response, {
+          token: authToken,
+          allowedOrigins,
+          authenticatedRateLimiter,
+          preflightRateLimiter,
+          now
+        }))
+          return;
+        const url = new URL(request.url ?? "/", "http://localhost");
+        if (url.pathname !== path) {
+          sendJson(response, 404, { error: "not found" });
+          return;
+        }
+        const sessionId = request.headers["mcp-session-id"];
+        const key = Array.isArray(sessionId) ? sessionId[0] : sessionId;
+        if (request.method === "DELETE") {
+          if (key !== void 0) await registry.delete(key);
+          response.writeHead(204).end();
+          return;
+        }
+        const body = request.method === "POST" ? await readBody(request) : void 0;
+        if (key !== void 0) {
+          const session2 = registry.get(key);
+          if (session2 === void 0) {
+            sendJson(response, 404, { error: "unknown session", kind: "no-session" });
+            return;
+          }
+          registry.touch(key);
+          await session2.attachment.transport.handleRequest(request, response, body);
+          return;
+        }
+        if (request.method !== "POST" || !isInitializeRequest(body)) {
+          sendJson(response, 400, { error: "missing Mcp-Session-Id", kind: "usage" });
+          return;
+        }
+        const newKey = randomUUID();
+        const session = registry.create(newKey, (stores) => {
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => newKey
+          });
+          const server = createTermwrightMcpServer(stores);
+          transport.onclose = () => {
+            void registry.delete(newKey).catch((error) => {
+              log(
+                `termwright: session ${newKey} transport cleanup failed: ${error instanceof Error ? error.message : String(error)}`
+              );
+            });
+          };
+          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();
+      }
+    })();
+  });
+  try {
+    await new Promise((resolve, reject) => {
+      const onError = (error) => {
+        http.off("listening", onListening);
+        reject(error);
+      };
+      const onListening = () => {
+        http.off("error", onError);
+        resolve();
+      };
+      http.once("error", onError);
+      http.once("listening", onListening);
+      http.listen(options.port ?? 0, host);
+    });
+  } catch (error) {
+    await registry.closeAll().catch((cleanup) => {
+      throw new AggregateError([error, cleanup], "MCP HTTP bind and rollback both failed");
+    });
+    throw error;
+  }
+  registry.startIdleSweeper();
+  const address = http.address();
+  const port = typeof address === "object" && address !== null ? address.port : options.port ?? 0;
+  return {
+    http,
+    registry,
+    port,
+    authToken,
+    close: async () => {
+      registry.stopIdleSweeper();
+      const results = await Promise.allSettled([
+        registry.closeAll(),
+        new Promise((resolve, reject) => {
+          http.close((error) => error === void 0 ? resolve() : reject(error));
+        })
+      ]);
+      const failures = results.flatMap(
+        (result) => result.status === "rejected" ? [result.reason] : []
+      );
+      if (failures.length > 0)
+        throw new AggregateError(failures, "MCP HTTP server failed to close cleanly");
+    }
+  };
+}
+
+// src/cli.ts
+var defaultIo = {
+  out: (text) => process.stdout.write(`${text}
+`),
+  err: (text) => process.stderr.write(`${text}
+`)
+};
+function parseArgs(argv) {
+  let command = "serve";
+  let json = false;
+  let http = false;
+  let port;
+  let host;
+  let allowNonLoopback = false;
+  let showAuthToken = false;
+  let out;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--http":
+        http = true;
+        break;
+      case "--port": {
+        const value = Number(argv[index + 1]);
+        if (!Number.isInteger(value) || value < 0 || value > 65535) {
+          throw usageError("--port needs an integer between 0 and 65535");
+        }
+        port = value;
+        index += 1;
+        break;
+      }
+      case "--host":
+        host = argv[index + 1];
+        if (host === void 0) throw usageError("--host needs a value");
+        index += 1;
+        break;
+      case "--allow-non-loopback":
+        allowNonLoopback = true;
+        break;
+      case "--show-auth-token":
+        showAuthToken = true;
+        break;
+      case "--out":
+        out = argv[index + 1];
+        if (out === void 0) throw usageError("--out needs a directory");
+        index += 1;
+        break;
+      case "--help":
+      case "-h":
+        command = "help";
+        break;
+      case "--version":
+      case "-v":
+        command = "version";
+        break;
+      case "serve":
+      case "stdio":
+        command = "serve";
+        break;
+      case "agent-context":
+        command = "agent-context";
+        break;
+      case "usage":
+        command = "usage";
+        break;
+      case "skill":
+        command = "skill";
+        break;
+      default:
+        throw usageError(
+          `unknown argument ${JSON.stringify(arg)}`,
+          "run `termwright-mcp usage` for the one-screen cheat sheet"
+        );
+    }
+  }
+  return { command, json, http, port, host, allowNonLoopback, showAuthToken, out };
+}
+function httpStartupMessages(args, handle) {
+  return [
+    `${SERVER_NAME} MCP listening on http://${args.host ?? "127.0.0.1"}:${handle.port}/mcp`,
+    args.showAuthToken ? `${SERVER_NAME} MCP bearer token: ${handle.authToken}` : `${SERVER_NAME} MCP bearer token hidden; restart with --show-auth-token to disclose it explicitly`
+  ];
+}
+async function runCli(argv, io = defaultIo) {
+  let json = argv.includes("--json");
+  try {
+    const args = parseArgs(argv);
+    json = args.json;
+    switch (args.command) {
+      case "version":
+        io.out(
+          json ? JSON.stringify({ name: SERVER_NAME, version: SERVER_VERSION }) : SERVER_VERSION
+        );
+        return EXIT_CODES.ok;
+      case "help":
+      case "usage":
+        io.out(json ? JSON.stringify(buildAgentContext()) : buildUsage());
+        return EXIT_CODES.ok;
+      case "agent-context":
+        io.out(JSON.stringify(buildAgentContext(), null, json ? 0 : 2));
+        return EXIT_CODES.ok;
+      case "skill": {
+        if (args.out === void 0) {
+          const files = buildAgentSkill();
+          io.out(
+            json ? JSON.stringify(Object.fromEntries(files.map((file) => [file.path, file.contents]))) : files.map((file) => `=== ${file.path}
+${file.contents}`).join("\n")
+          );
+          return EXIT_CODES.ok;
+        }
+        const written = await writeAgentSkill(args.out);
+        io.out(json ? JSON.stringify({ written }) : written.join("\n"));
+        return EXIT_CODES.ok;
+      }
+      case "serve": {
+        if (args.http) {
+          const handle = await serveHttp({
+            ...args.port === void 0 ? {} : { port: args.port },
+            ...args.host === void 0 ? {} : { host: args.host },
+            ...args.allowNonLoopback ? { allowNonLoopback: true } : {}
+          });
+          for (const line of httpStartupMessages(args, handle)) io.err(line);
+          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 {
+  createTermwrightMcpServer,
+  serveStdio,
+  serveInMemory,
+  serveHttp,
+  runCli,
+  main
+};
+//# sourceMappingURL=chunk-R2N52YYH.js.map