@gleapai/kai-bridge 0.9.1 → 0.10.0

package/runner/tools/verify-mcp.mjs

@@ -1,442 +0,0 @@
-#!/usr/bin/env node
-// Minimal stdio MCP server for the `kai-verifier` persona (Kai Code
-// "Verify"). Two tools, zero dependencies; speaks newline-delimited
-// JSON-RPC 2.0 per the MCP stdio transport (same skeleton as todo-mcp.mjs
-// / ask-user-mcp.mjs).
-//
-//   report_verification — the verdict channel. The verifier drives the
-//     running preview with the Playwright MCP, records a video +
-//     screenshots, and must hand the host a STRUCTURED result — pass/fail
-//     checks, what stayed untested, and the local path of every artifact
-//     the browser tools wrote. Prose in the final message can't be
-//     uploaded or rendered as an evidence card. The runner's mapper
-//     (lib/acp/mapper.mjs) sniffs calls to this tool into the
-//     `verify_report` contract event; the host (kai-bridge daemon) uploads
-//     the artifacts and replaces the paths with URLs. The tool itself is a
-//     signalling no-op — the INPUT is the product. Not turn-ending: the
-//     persona wraps up normally after reporting.
-//
-//   http_request — the ONLY HTTP path for API changes (no curl). Performs
-//     the call in-process against the preview / external origins the host
-//     allows, appends one JSON line per call to
-//     `<evidence dir>/requests.jsonl` (the transcript IS the evidence — the
-//     host uploads it as a `requests` artifact) and refuses writes when the
-//     run is read-only. The host derives an auth header from the app's own
-//     sign-in and hands it over by env — the model never sees the value.
-//
-// Env (all set by the host; every one optional):
-//   KAI_VERIFY_READ_ONLY=1        non-GET/HEAD/OPTIONS refused, recorded as `refused: "read_only"`
-//   KAI_VERIFY_ORIGINS            allowed origins, `;`/`,`/space separated (`http://localhost:*` = any port)
-//   KAI_VERIFY_AUTH_HEADER        `Header-Name: value` (bare value = Authorization); sent to LOCAL origins only, masked everywhere
-//   KAI_VERIFY_EVIDENCE_DIR       where `requests.jsonl` is appended (no dir → nothing written)
-
-import { appendFileSync, mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
-
-const CHECK_STATUS = ["passed", "failed"];
-export const BLOCKED_CODES = ["needs_login", "preview_unreachable", "not_verifiable", "other"];
-export const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
-export const RESPONSE_BODY_CAP = 8 * 1024;
-export const REQUEST_TIMEOUT_MS = 30_000;
-export const REQUESTS_FILE = "requests.jsonl";
-const MASKED = "[masked]";
-const MASKED_REQUEST_HEADERS = new Set(["authorization", "cookie", "proxy-authorization", "x-api-key"]);
-const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
-
-const REPORT_TOOL = {
-  name: "report_verification",
-  description:
-    "File the verification report for this run. Call it EXACTLY ONCE, as " +
-    "the last thing you do: list every check you performed with its " +
-    "result, everything you could not test, and the path of EVERY " +
-    "artifact (video, screenshots, traces) the browser tools returned. " +
-    "A `passed` report needs at least one check. " +
-    "Status `blocked` = you could not verify (preview unreachable, a login " +
-    "wall, nothing to exercise from the app, …) — explain why in `reason`, " +
-    "classify it in `blockedCode` and still list the partial evidence you " +
-    "have. Never include cookies, tokens, response bodies or other secret " +
-    "values anywhere in the report.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      status: {
-        type: "string",
-        enum: ["passed", "failed", "blocked"],
-        description:
-          "Overall verdict: passed = every check passed (at least one check); failed = at least " +
-          "one check failed; blocked = verification could not be carried out.",
-      },
-      scope: {
-        type: "string",
-        description: "One line: what was tested (feature / flow / pages / endpoints).",
-      },
-      reason: {
-        type: "string",
-        description: "For failed/blocked: the explanation in one or two sentences.",
-      },
-      blockedCode: {
-        type: "string",
-        enum: BLOCKED_CODES,
-        description:
-          "For blocked only: `needs_login` = a sign-in wall stopped you, or an API answered 401/403 without credentials (set " +
-          "`loginPath`; do NOT ask the user for credentials — the host " +
-          "arranges the sign-in and re-runs you); `preview_unreachable` = " +
-          "the preview never answered / the page never loaded; `not_verifiable` = " +
-          "the change has nothing a tester can exercise from the running app (build tooling, " +
-          "comments, types only) — never fabricate a check instead; `other` = anything else (explain in `reason`).",
-      },
-      loginPath: {
-        type: "string",
-        description:
-          "With blockedCode needs_login: the URL path of the login wall or the endpoint that refused you " +
-          "(e.g. `/login`, `/api/v1/me`) — never the full URL with tokens, never credentials.",
-      },
-      checks: {
-        type: "array",
-        items: {
-          type: "object",
-          properties: {
-            label: { type: "string", description: "What was checked, in plain words." },
-            status: { type: "string", enum: CHECK_STATUS },
-          },
-          required: ["label", "status"],
-        },
-        description: "Every check performed, in order. Only checks you actually performed.",
-      },
-      untested: {
-        type: "array",
-        items: { type: "string" },
-        description: "What was NOT verified and why (honest gaps — a 404 on a guessed API path belongs here, not in checks).",
-      },
-      artifacts: {
-        type: "array",
-        items: {
-          type: "object",
-          properties: {
-            label: { type: "string", description: "Short caption shown under the artifact." },
-            path: { type: "string", description: "Local file path exactly as the browser tool returned it." },
-            kind: { type: "string", enum: ["screenshot", "video", "trace"] },
-          },
-          required: ["label", "path", "kind"],
-        },
-        description: "Every recording, screenshot and trace produced in this run (the HTTP transcript is collected by the host — do not list it).",
-      },
-    },
-    required: ["status", "checks", "artifacts"],
-  },
-};
-
-const HTTP_TOOL = {
-  name: "http_request",
-  description:
-    "Perform ONE HTTP request against the running preview (or an external origin the task lists) and record it " +
-    "in the verification transcript. This is the only way to call an API in a verification run — never use curl. " +
-    "The host adds the app's own authentication automatically when it has one; never guess or paste tokens. " +
-    "In a read-only run (shared database) anything but GET/HEAD/OPTIONS is refused and recorded as skipped — " +
-    "put such endpoints in `untested`. A 401/403 without credentials is a `needs_login` block, never a failed check; " +
-    "a 404 on a path you guessed is `untested`. Resolve real paths from the OpenAPI spec first.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      method: { type: "string", description: "HTTP method (GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE). Default GET." },
-      url: { type: "string", description: "Absolute URL on an allowed origin, or a path (`/api/v1/tickets`) resolved against the first allowed origin." },
-      headers: { type: "object", additionalProperties: { type: "string" }, description: "Extra request headers (Accept, Content-Type, …). Authentication is added by the host." },
-      body: { description: "Request body: a string is sent as-is; an object is sent as JSON." },
-      check: { type: "string", description: "What this request verifies, in plain words (shown next to the row in the transcript)." },
-    },
-    required: ["url"],
-  },
-};
-
-export const TOOLS = [REPORT_TOOL, HTTP_TOOL];
-
-/** `KAI_VERIFY_ORIGINS` → normalised origins (`http://localhost:*` kept as a wildcard). */
-export function parseOrigins(raw) {
-  const out = [];
-  for (const part of String(raw || "").split(/[;,\s]+/)) {
-    const text = part.trim();
-    if (!text) continue;
-    const wildcard = /^(https?):\/\/([^/:]+):\*$/i.exec(text);
-    if (wildcard) {
-      out.push(`${wildcard[1].toLowerCase()}://${wildcard[2].toLowerCase()}:*`);
-      continue;
-    }
-    try {
-      out.push(new URL(text).origin.toLowerCase());
-    } catch {
-      /* junk entry */
-    }
-  }
-  return [...new Set(out)];
-}
-
-/** Is `url`'s origin one of the allowed ones (wildcard ports included)? */
-export function isAllowedOrigin(url, allowed) {
-  let u;
-  try {
-    u = new URL(url);
-  } catch {
-    return false;
-  }
-  if (u.protocol !== "http:" && u.protocol !== "https:") return false;
-  const origin = u.origin.toLowerCase();
-  for (const a of allowed || []) {
-    if (a === origin) return true;
-    if (a.endsWith(":*") && origin.startsWith(a.slice(0, -1))) return true;
-    if (a.endsWith(":*")) {
-      const [proto, host] = a.slice(0, -2).split("://");
-      if (u.protocol === `${proto}:` && u.hostname.toLowerCase() === host) return true;
-    }
-  }
-  return false;
-}
-
-/** Absolute URL for the request: paths resolve against the first allowed origin. */
-export function resolveRequestUrl(raw, allowed) {
-  const text = String(raw || "").trim();
-  if (!text) return null;
-  if (/^https?:\/\//i.test(text)) return text;
-  const base = (allowed || []).find((o) => !o.endsWith(":*"));
-  if (!base) return null;
-  try {
-    return new URL(text.startsWith("/") ? text : `/${text}`, base).toString();
-  } catch {
-    return null;
-  }
-}
-
-/** `Authorization: Bearer x` → { name, value }; a bare value is an Authorization header. Null when empty. */
-export function parseAuthHeader(raw) {
-  const text = String(raw || "").trim();
-  if (!text) return null;
-  const m = /^([A-Za-z0-9-]+):\s*(.+)$/.exec(text);
-  if (m) return { name: m[1], value: m[2].trim() };
-  return { name: "Authorization", value: text };
-}
-
-/** The host-derived auth header only ever goes to the preview itself, never to an external origin. */
-export function isLocalOrigin(url) {
-  try {
-    return LOCAL_HOSTS.has(new URL(url).hostname.toLowerCase());
-  } catch {
-    return false;
-  }
-}
-
-/** Request headers as recorded: credentials masked, names lower-cased. */
-export function maskHeaders(headers) {
-  const out = {};
-  for (const [k, v] of Object.entries(headers || {})) {
-    const key = String(k).toLowerCase();
-    out[key] = MASKED_REQUEST_HEADERS.has(key) ? MASKED : String(v);
-  }
-  return out;
-}
-
-/** Response body capped at 8 KB for the transcript. */
-export function capBody(text) {
-  const body = String(text ?? "");
-  if (body.length <= RESPONSE_BODY_CAP) return { body, truncated: false };
-  return { body: body.slice(0, RESPONSE_BODY_CAP), truncated: true };
-}
-
-/**
- * Pure: decide what to do with an `http_request` call. Returns
- * `{ refused: "origin" | "read_only" | "invalid", url, method, headers }`
- * or `{ url, method, headers, body }` ready for fetch. `headers` already
- * carries the host auth header when it applies.
- */
-export function planRequest(args, { readOnly = false, allowed = [], auth = null } = {}) {
-  const method = String(args?.method || "GET").trim().toUpperCase() || "GET";
-  const url = resolveRequestUrl(args?.url, allowed);
-  const userHeaders = {};
-  for (const [k, v] of Object.entries(args?.headers && typeof args.headers === "object" ? args.headers : {})) {
-    if (typeof v === "string" || typeof v === "number") userHeaders[String(k)] = String(v);
-  }
-  if (!url) return { refused: "invalid", method, url: String(args?.url || ""), headers: userHeaders, reason: "not a valid URL (absolute http(s) URL or a path on the preview)" };
-  if (!isAllowedOrigin(url, allowed)) return { refused: "origin", method, url, headers: userHeaders, reason: `origin not allowed for this run (allowed: ${allowed.join(", ") || "none"})` };
-  if (readOnly && !READ_METHODS.has(method)) return { refused: "read_only", method, url, headers: userHeaders, reason: "this is a read-only run — writes are skipped; list the endpoint under untested" };
-  const headers = { ...userHeaders };
-  let body = args?.body;
-  if (body !== undefined && body !== null && !READ_METHODS.has(method)) {
-    if (typeof body !== "string") {
-      body = JSON.stringify(body);
-      if (!Object.keys(headers).some((h) => h.toLowerCase() === "content-type")) headers["Content-Type"] = "application/json";
-    }
-  } else {
-    body = undefined;
-  }
-  if (auth && isLocalOrigin(url)) {
-    // The host's header wins: a guessed Authorization from the model would
-    // only ever hide the real sign-in state.
-    for (const k of Object.keys(headers)) if (k.toLowerCase() === auth.name.toLowerCase()) delete headers[k];
-    headers[auth.name] = auth.value;
-  }
-  return { method, url, headers, body };
-}
-
-/** One transcript row (`requests.jsonl` line). Credentials are masked, never the row's URL query (the model chose it). */
-export function buildRequestRow({ plan, check, status = null, ms = null, responseHeaders = null, responseBody = null, truncated = false, error = null, now = new Date() }) {
-  const row = {
-    t: now.toISOString(),
-    method: plan.method,
-    url: plan.url,
-    status,
-    ms,
-    requestHeaders: maskHeaders(plan.headers),
-    requestBody: plan.body === undefined ? null : capBody(plan.body).body,
-    responseHeaders,
-    responseBody,
-    truncated: !!truncated,
-    check: typeof check === "string" && check.trim() ? check.trim().slice(0, 300) : null,
-  };
-  if (plan.refused) row.refused = plan.refused;
-  if (error) row.error = String(error).slice(0, 300);
-  return row;
-}
-
-function appendRow(dir, row) {
-  if (!dir) return;
-  try {
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, REQUESTS_FILE), `${JSON.stringify(row)}\n`);
-  } catch {
-    /* the transcript is best-effort; the tool result still reaches the model */
-  }
-}
-
-/** What the model sees for a refused call — plain words, an action to take. */
-function describeRefusal(plan) {
-  if (plan.refused === "read_only") return `Skipped: ${plan.method} ${plan.url} — ${plan.reason}. Recorded as skipped in the transcript.`;
-  if (plan.refused === "origin") return `Refused: ${plan.method} ${plan.url} — ${plan.reason}.`;
-  return `Refused: ${plan.url || "(empty)"} — ${plan.reason}.`;
-}
-
-/**
- * Perform the call (injectable fetch for tests). Returns the tool result
- * text + the transcript row; the auth header value never appears in either.
- */
-export async function performHttpRequest(args, { readOnly, allowed, auth, evidenceDir, fetchImpl = fetch, now = () => new Date(), timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
-  const plan = planRequest(args, { readOnly, allowed, auth });
-  if (plan.refused) {
-    const row = buildRequestRow({ plan, check: args?.check, now: now() });
-    appendRow(evidenceDir, row);
-    return { text: describeRefusal(plan), row, isError: plan.refused !== "read_only" };
-  }
-  const startedAt = Date.now();
-  try {
-    const res = await fetchImpl(plan.url, {
-      method: plan.method,
-      headers: plan.headers,
-      body: plan.body,
-      redirect: "manual",
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    const ms = Date.now() - startedAt;
-    const responseHeaders = {};
-    for (const [k, v] of res.headers?.entries?.() ?? []) responseHeaders[k.toLowerCase()] = v;
-    const raw = plan.method === "HEAD" ? "" : await res.text().catch(() => "");
-    const { body, truncated } = capBody(raw);
-    const row = buildRequestRow({ plan, check: args?.check, status: res.status, ms, responseHeaders, responseBody: body, truncated, now: now() });
-    appendRow(evidenceDir, row);
-    const headLine = `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""} (${ms} ms) ${plan.method} ${plan.url}`;
-    const shown = ["content-type", "content-length", "location"].filter((h) => responseHeaders[h]).map((h) => `${h}: ${responseHeaders[h]}`);
-    const text = [headLine, ...shown, "", body || "(empty body)", truncated ? `\n[response truncated to ${RESPONSE_BODY_CAP} bytes in the transcript]` : ""].join("\n").trimEnd();
-    return { text, row, isError: false };
-  } catch (err) {
-    const ms = Date.now() - startedAt;
-    const message = err?.name === "TimeoutError" ? `timed out after ${Math.round(timeoutMs / 1000)}s` : err?.cause?.code || err?.message || String(err);
-    const row = buildRequestRow({ plan, check: args?.check, ms, error: message, now: now() });
-    appendRow(evidenceDir, row);
-    return { text: `Request failed: ${plan.method} ${plan.url} — ${message}. If the preview never answers, report blocked (preview_unreachable).`, row, isError: true };
-  }
-}
-
-/** Env → the request policy for this run. */
-export function policyFromEnv(env = process.env) {
-  return {
-    readOnly: env.KAI_VERIFY_READ_ONLY === "1" || env.KAI_VERIFY_READ_ONLY === "true",
-    allowed: parseOrigins(env.KAI_VERIFY_ORIGINS),
-    auth: parseAuthHeader(env.KAI_VERIFY_AUTH_HEADER),
-    evidenceDir: env.KAI_VERIFY_EVIDENCE_DIR || null,
-  };
-}
-
-function send(message) {
-  process.stdout.write(`${JSON.stringify(message)}\n`);
-}
-
-function reply(id, result) {
-  send({ jsonrpc: "2.0", id, result });
-}
-
-function replyError(id, code, message) {
-  send({ jsonrpc: "2.0", id, error: { code, message } });
-}
-
-function serve() {
-  const policy = policyFromEnv();
-  const rl = createInterface({ input: process.stdin, terminal: false });
-  rl.on("line", (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) return;
-    let msg;
-    try {
-      msg = JSON.parse(trimmed);
-    } catch {
-      return;
-    }
-    const { id, method } = msg ?? {};
-    if (typeof method !== "string") return;
-
-    if (method === "initialize") {
-      reply(id, {
-        protocolVersion: msg.params?.protocolVersion ?? "2025-06-18",
-        capabilities: { tools: {} },
-        serverInfo: { name: "kai-verify", version: "1.1.0" },
-      });
-      return;
-    }
-    if (method === "notifications/initialized" || id == null) {
-      return; // notifications need no response
-    }
-    if (method === "tools/list") {
-      reply(id, { tools: TOOLS });
-      return;
-    }
-    if (method === "tools/call") {
-      const name = msg.params?.name;
-      const args = msg.params?.arguments ?? {};
-      if (name === REPORT_TOOL.name) {
-        // Loose validation: the host normalises the report; a malformed call
-        // must not stall the turn with an error the model then retries.
-        const checks = Array.isArray(args.checks) ? args.checks.length : 0;
-        const artifacts = Array.isArray(args.artifacts) ? args.artifacts.length : 0;
-        reply(id, {
-          content: [
-            {
-              type: "text",
-              text: `Verification report received (${args.status ?? "unknown"}, ${checks} check${checks === 1 ? "" : "s"}, ${artifacts} artifact${artifacts === 1 ? "" : "s"}). You are done — end your turn with a one-paragraph summary.`,
-            },
-          ],
-        });
-        return;
-      }
-      if (name === HTTP_TOOL.name) {
-        void performHttpRequest(args, policy).then(
-          ({ text, isError }) => reply(id, { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) }),
-          (err) => reply(id, { content: [{ type: "text", text: `Request failed: ${err?.message || err}` }], isError: true }),
-        );
-        return;
-      }
-      replyError(id, -32602, `unknown tool: ${name}`);
-      return;
-    }
-    replyError(id, -32601, `unknown method: ${method}`);
-  });
-}
-
-// Runs as a server when spawned directly; importable for its pure helpers.
-if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) serve();