@bugmole/cli 0.4.0

package/src/registry-worker/jobs/index.ts

@@ -0,0 +1,29 @@
+// Cron entry point. wrangler.jsonc schedules:
+//   "* * * * *"   → frequent work: cloud-run dispatch, notification outbox
+//   "17 3 * * *"  → daily work: retention, monthly billing close, subscription sync
+import type { Env } from "../core.js";
+
+export type Job = (env: Env, ctx: ExecutionContext, now: Date) => Promise<void>;
+
+export const MINUTE_CRON = "* * * * *";
+export const DAILY_CRON = "17 3 * * *";
+
+const minuteJobs: Array<[string, Job]> = [];
+const dailyJobs: Array<[string, Job]> = [];
+
+export function registerJob(schedule: "minute" | "daily", name: string, job: Job): void {
+  (schedule === "minute" ? minuteJobs : dailyJobs).push([name, job]);
+}
+
+export async function runScheduledJobs(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+  const now = new Date(controller.scheduledTime);
+  const jobs = controller.cron === DAILY_CRON ? dailyJobs : minuteJobs;
+  // One failing job must not starve the others.
+  for (const [name, job] of jobs) {
+    try {
+      await job(env, ctx, now);
+    } catch (error) {
+      console.error(`[registry] scheduled job ${name} failed`, error);
+    }
+  }
+}

package/src/registry-worker/jobs/retention.ts

@@ -0,0 +1,68 @@
+// Deletes run history older than each workspace's plan allows, including the
+// evidence Bugmole stores for it. Runs in small batches every day.
+import type { Env } from "../core.js";
+import { getEntitlements } from "../billing/entitlements.js";
+import { recordAudit } from "../org/audit.js";
+import { registerJob } from "./index.js";
+
+const TERMINAL = "('success', 'partial', 'error', 'cancelled')";
+const MAX_RUNS_PER_TICK = 500;
+/** No plan keeps less history than this, so younger runs are never examined. */
+const MIN_HISTORY_DAYS = 7;
+
+export function historyCutoff(historyDays: number | null, now: Date): string | null {
+  return historyDays === null ? null : new Date(now.getTime() - historyDays * 86_400_000).toISOString();
+}
+
+async function deletePrefix(bucket: R2Bucket, prefix: string): Promise<number> {
+  let cursor: string | undefined;
+  let deleted = 0;
+  do {
+    const page = await bucket.list({ prefix, cursor, limit: 1000 });
+    const keys = page.objects.map((object) => object.key);
+    if (keys.length) {
+      await bucket.delete(keys);
+      deleted += keys.length;
+    }
+    cursor = page.truncated ? page.cursor : undefined;
+  } while (cursor);
+  return deleted;
+}
+
+export async function enforceRetention(env: Env, now = new Date()): Promise<{ runs: number; objects: number }> {
+  const oldest = new Date(now.getTime() - MIN_HISTORY_DAYS * 86_400_000).toISOString();
+  const workspaces = await env.DB.prepare(`
+    SELECT DISTINCT workspace_id AS workspaceId FROM runs
+    WHERE workspace_id IS NOT NULL AND status IN ${TERMINAL} AND COALESCE(completed_at, requested_at) < ?
+  `).bind(oldest).all<{ workspaceId: string }>();
+  let runs = 0;
+  let objects = 0;
+  for (const { workspaceId } of workspaces.results) {
+    if (runs >= MAX_RUNS_PER_TICK) break;
+    const { historyDays } = await getEntitlements(env, workspaceId);
+    const cutoff = historyCutoff(historyDays, now);
+    if (!cutoff) continue;
+    const expired = await env.DB.prepare(`
+      SELECT id, project_id AS projectId FROM runs
+      WHERE workspace_id = ? AND status IN ${TERMINAL} AND COALESCE(completed_at, requested_at) < ?
+      ORDER BY requested_at LIMIT ?
+    `).bind(workspaceId, cutoff, MAX_RUNS_PER_TICK - runs).all<{ id: string; projectId: string }>();
+    if (!expired.results.length) continue;
+    for (const run of expired.results) {
+      if (env.ARTIFACTS) objects += await deletePrefix(env.ARTIFACTS, `projects/${run.projectId}/runs/${run.id}/`);
+      await env.DB.batch([
+        env.DB.prepare("DELETE FROM run_events WHERE run_id = ?").bind(run.id),
+        env.DB.prepare("DELETE FROM runs WHERE id = ?").bind(run.id),
+      ]);
+    }
+    runs += expired.results.length;
+    await recordAudit(env, { type: "system", id: "retention" }, {
+      workspaceId, action: "runs.expired", data: { count: expired.results.length, historyDays, cutoff },
+    });
+  }
+  return { runs, objects };
+}
+
+registerJob("daily", "retention", async (env, _ctx, now) => {
+  await enforceRetention(env, now);
+});

package/src/registry-worker/mcp/mcp.test.ts

@@ -0,0 +1,355 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync, sign, type KeyObject } from "node:crypto";
+import test from "node:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+import type { AppDriver, DriverContext, DriverResult } from "../../runtime/driver.js";
+import { parseMaestroStyleFlow } from "../../runtime/flow-language.js";
+import { planDocument } from "./tools.js";
+import type { Env } from "../core.js";
+import { call, createTestEnv, seedProject } from "../testing/harness.js";
+import { resetMcpKeyCache } from "./token.js";
+
+const ISSUER = "https://id.test";
+const RESOURCE = "https://registry.test/mcp";
+const KID = "key-1";
+
+const keys = generateKeyPairSync("rsa", { modulusLength: 2048 });
+const otherKeys = generateKeyPairSync("rsa", { modulusLength: 2048 });
+
+function b64url(value: string | Buffer): string {
+  return Buffer.from(value).toString("base64url");
+}
+
+function jwt(claims: Record<string, unknown>, options: { key?: KeyObject; kid?: string; typ?: string; alg?: string } = {}): string {
+  const header = b64url(JSON.stringify({ alg: options.alg ?? "RS256", kid: options.kid ?? KID, typ: options.typ ?? "at+jwt" }));
+  const body = b64url(JSON.stringify(claims));
+  const signature = sign("sha256", Buffer.from(`${header}.${body}`), options.key ?? keys.privateKey);
+  return `${header}.${body}.${b64url(signature)}`;
+}
+
+function accessToken(sub: string, overrides: Record<string, unknown> = {}, options: Parameters<typeof jwt>[1] = {}): string {
+  const now = Math.floor(Date.now() / 1000);
+  return jwt({
+    iss: ISSUER,
+    aud: RESOURCE,
+    sub,
+    client_id: "mcp_0123",
+    scope: "openid email offline_access bugmole:mcp",
+    email: `${sub}@acme.test`,
+    email_verified: true,
+    iat: now,
+    exp: now + 3600,
+    ...overrides,
+  }, options);
+}
+
+function mcpEnv(overrides: Partial<Env> = {}) {
+  resetMcpKeyCache();
+  let jwksCalls = 0;
+  const aegisFetch = (async (input: RequestInfo | URL) => {
+    const url = new URL(String(input));
+    if (url.toString() !== `${ISSUER}/jwks`) return new Response("not found", { status: 404 });
+    jwksCalls += 1;
+    return Response.json({ keys: [{ ...keys.publicKey.export({ format: "jwk" }), kid: KID, alg: "RS256", use: "sig" }] });
+  }) as typeof fetch;
+  const setup = createTestEnv({
+    FEATURE_MCP: "on",
+    AEGIS_ISSUER: ISSUER,
+    AEGIS_FETCH: aegisFetch,
+    REGISTRY_PUBLIC_URL: "https://registry.test",
+    DASHBOARD_URL: "https://dash.test",
+    ...overrides,
+  } as Partial<Env>);
+  return { ...setup, jwksCalls: () => jwksCalls };
+}
+
+let nextId = 1;
+async function rpc(env: Env, token: string, method: string, params?: unknown) {
+  const res = await call(env, "POST", "/mcp", {
+    token,
+    body: { jsonrpc: "2.0", id: nextId++, method, ...(params === undefined ? {} : { params }) },
+    headers: { accept: "application/json, text/event-stream" },
+  });
+  return res;
+}
+
+async function tool(env: Env, token: string, name: string, args: Record<string, unknown> = {}) {
+  const res = await rpc(env, token, "tools/call", { name, arguments: args });
+  assert.equal(res.status, 200, JSON.stringify(res.json));
+  const result = res.json.result;
+  return { ...result, data: result.isError ? null : JSON.parse(result.content[0].text), message: result.content[0].text as string };
+}
+
+test("the MCP endpoint is off unless enabled", async () => {
+  const { env } = mcpEnv({ FEATURE_MCP: undefined } as Partial<Env>);
+  assert.equal((await call(env, "POST", "/mcp", { body: {} })).status, 404);
+  assert.equal((await call(env, "GET", "/.well-known/oauth-protected-resource/mcp")).status, 404);
+});
+
+test("assistants discover Aegis from the resource metadata", async () => {
+  const { env } = mcpEnv();
+  for (const path of ["/.well-known/oauth-protected-resource/mcp", "/.well-known/oauth-protected-resource"]) {
+    const res = await call(env, "GET", path);
+    assert.equal(res.status, 200);
+    assert.equal(res.json.resource, RESOURCE);
+    assert.deepEqual(res.json.authorization_servers, [ISSUER]);
+    assert.ok(res.json.scopes_supported.includes("bugmole:mcp"));
+    assert.equal(res.headers.get("access-control-allow-origin"), "*");
+  }
+  const anonymous = await call(env, "POST", "/mcp", { body: { jsonrpc: "2.0", id: 1, method: "initialize" } });
+  assert.equal(anonymous.status, 401);
+  const challenge = anonymous.headers.get("www-authenticate") ?? "";
+  assert.match(challenge, /^Bearer /);
+  assert.match(challenge, /resource_metadata="https:\/\/registry\.test\/\.well-known\/oauth-protected-resource\/mcp"/);
+  assert.match(challenge, /scope="bugmole:mcp"/);
+  assert.equal((await call(env, "OPTIONS", "/mcp")).status, 204);
+});
+
+test("only current Aegis access tokens for this endpoint are accepted", async () => {
+  const { env, db, jwksCalls } = mcpEnv();
+  const now = Math.floor(Date.now() / 1000);
+  const rejected: Array<[string, string]> = [
+    ["another audience", accessToken("user_a", { aud: "https://other.test/mcp" })],
+    ["another issuer", accessToken("user_a", { iss: "https://evil.test" })],
+    ["expired", accessToken("user_a", { exp: now - 600 })],
+    ["not yet valid", accessToken("user_a", { nbf: now + 600 })],
+    ["no MCP scope", accessToken("user_a", { scope: "openid email" })],
+    ["no subject", accessToken("user_a", { sub: "" })],
+    ["an ID token", accessToken("user_a", {}, { typ: "JWT" })],
+    ["signed by someone else", accessToken("user_a", {}, { key: otherKeys.privateKey })],
+    ["unknown key", accessToken("user_a", {}, { kid: "key-9" })],
+    ["HS256", accessToken("user_a", {}, { alg: "HS256" })],
+    ["garbage", "not.a.jwt"],
+  ];
+  for (const [label, token] of rejected) {
+    const res = await rpc(env, token, "ping");
+    assert.equal(res.status, 401, label);
+    assert.match(res.headers.get("www-authenticate") ?? "", /error="invalid_token"/, label);
+  }
+  // The key set is cached; an unknown key id refetches it at most once a minute.
+  assert.ok(jwksCalls() <= 2, `fetched keys ${jwksCalls()} times`);
+
+  const ok = await rpc(env, accessToken("user_a", { aud: [RESOURCE, "https://other.test"] }), "ping");
+  assert.equal(ok.status, 200);
+  assert.deepEqual(ok.json, { jsonrpc: "2.0", id: ok.json.id, result: {} });
+
+  // Someone their organization removed is refused.
+  db.db.prepare("INSERT INTO aegis_users (id, deprovisioned_at) VALUES (?, CURRENT_TIMESTAMP)").run("user_gone");
+  assert.equal((await rpc(env, accessToken("user_gone"), "ping")).status, 401);
+});
+
+test("initialize, tools/list, notifications and errors follow the protocol", async () => {
+  const { env } = mcpEnv();
+  const token = accessToken("user_a");
+  const init = await rpc(env, token, "initialize", { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1" } });
+  assert.equal(init.json.result.protocolVersion, "2025-03-26");
+  assert.equal(init.json.result.serverInfo.name, "bugmole");
+  assert.ok(init.json.result.capabilities.tools);
+  assert.match(init.json.result.instructions, /explore[\s\S]*plan[\s\S]*run[\s\S]*report/);
+  const unknownVersion = await rpc(env, token, "initialize", { protocolVersion: "1999-01-01" });
+  assert.equal(unknownVersion.json.result.protocolVersion, "2025-06-18");
+
+  const listed = await rpc(env, token, "tools/list");
+  const names = listed.json.result.tools.map((item: { name: string }) => item.name);
+  assert.deepEqual(names, [
+    "list_projects", "list_test_plans", "get_test_plan", "save_test_plan", "run_tests",
+    "get_run", "list_runs", "explore_app", "get_exploration", "list_journeys",
+  ]);
+  for (const item of listed.json.result.tools) {
+    assert.equal(item.inputSchema.type, "object", item.name);
+    assert.equal(typeof item.annotations.readOnlyHint, "boolean", item.name);
+    assert.equal(item.run, undefined);
+  }
+
+  const notification = await call(env, "POST", "/mcp", { token, body: { jsonrpc: "2.0", method: "notifications/initialized" } });
+  assert.equal(notification.status, 202);
+  const missing = await rpc(env, token, "sampling/createMessage");
+  assert.equal(missing.json.error.code, -32601);
+  const parse = await call(env, "POST", "/mcp", { token, body: "{nope", headers: { "content-type": "application/json" } });
+  assert.equal(parse.json.error.code, -32700);
+  const batch = await call(env, "POST", "/mcp", { token, body: [{ jsonrpc: "2.0", id: 1, method: "ping" }, { jsonrpc: "2.0", method: "notifications/x" }] });
+  assert.equal(batch.json.length, 1);
+  assert.equal((await call(env, "GET", "/mcp", { token })).status, 405);
+  const unknownTool = await tool(env, token, "delete_everything");
+  assert.equal(unknownTool.isError, true);
+  const missingArg = await tool(env, token, "list_test_plans", {});
+  assert.equal(missingArg.isError, true);
+  assert.match(missingArg.message, /projectId is required/);
+});
+
+const FLOW = `url: https://shop.example.com/cart
+---
+- launchApp
+- tapOn: "Checkout"
+- inputText: "{{secret.SHOP_PASSWORD}}"
+- assertVisible: "Order placed"
+`;
+
+test("an assistant explores, writes a plan, runs it and reads the result as the signed-in person", async () => {
+  const { env, artifacts } = mcpEnv();
+  const { owner, projectId } = await seedProject(env, { storageProvider: "bugmole" });
+  const environment = await call(env, "POST", `/api/projects/${projectId}/environments`, {
+    as: owner,
+    body: { id: "staging", name: "Staging", baseUrl: "https://staging.shop.test" },
+  });
+  assert.ok([200, 201].includes(environment.status), JSON.stringify(environment.json));
+  const token = accessToken(owner);
+
+  const projects = await tool(env, token, "list_projects");
+  const project = projects.data.projects.find((item: { id: string }) => item.id === projectId);
+  assert.equal(project.storage, "Bugmole");
+  assert.equal(project.runsGoTo, "your workers");
+  assert.ok(project.environments.some((item: { baseUrl: string }) => item.baseUrl === "https://staging.shop.test"));
+
+  // Explore
+  const explore = await tool(env, token, "explore_app", { projectId, url: "https://staging.shop.test", goal: "guest checkout" });
+  assert.equal(explore.isError, undefined, explore.message);
+  assert.equal(explore.data.status, "queued");
+  const exploration = await tool(env, token, "get_exploration", { projectId, taskId: explore.data.taskId });
+  assert.equal(exploration.data.status, "queued");
+  assert.match(exploration.data.title, /Explore staging\.shop\.test: guest checkout/);
+  assert.equal((await tool(env, token, "explore_app", { projectId, url: "javascript:alert(1)" })).isError, true);
+  assert.deepEqual((await tool(env, token, "list_journeys", { projectId })).data, { journeys: [] });
+
+  // Plan
+  const invalid = await tool(env, token, "save_test_plan", { projectId, planId: "checkout", name: "Guest checkout", flow: "- launchApp" });
+  assert.equal(invalid.isError, true);
+  assert.match(invalid.message, /isn't valid/);
+  const badId = await tool(env, token, "save_test_plan", { projectId, planId: "../x", name: "x", flow: FLOW });
+  assert.equal(badId.isError, true);
+  const saved = await tool(env, token, "save_test_plan", { projectId, planId: "checkout-guest", name: "Guest checkout", flow: FLOW, actor: "guest" });
+  assert.equal(saved.isError, undefined, saved.message);
+  assert.equal(saved.data.steps, 4);
+  const storedFlow = artifacts.objects.get(`projects/${projectId}/spec/flows/checkout-guest.yaml`);
+  assert.equal(new TextDecoder().decode(storedFlow!.body), FLOW);
+  const planText = new TextDecoder().decode(artifacts.objects.get(`projects/${projectId}/plans/checkout-guest.flow.yaml`)!.body);
+  const plan = YAML.parse(planText);
+  assert.equal(plan.suites[0].journeys[0].flow, "flows/checkout-guest.yaml");
+  assert.equal(plan.suites[0].journeys[0].driver, "playwright");
+  assert.equal(plan.suites[0].journeys[0].id, "checkout-guest");
+  assert.equal(plan.suites[0].journeys[0].actor, "guest");
+  assert.equal(plan.suites[0].journeys[0].steps.length, 4);
+  assert.doesNotMatch(planText, /SHOP_PASSWORD/, "typed text stays out of the plan's step labels");
+
+  const plans = await tool(env, token, "list_test_plans", { projectId });
+  assert.deepEqual(plans.data.plans.map((item: { planId: string }) => item.planId), ["checkout-guest"]);
+  const read = await tool(env, token, "get_test_plan", { projectId, planId: "checkout-guest" });
+  assert.equal(read.data.flow, FLOW);
+  assert.equal(read.data.name, "Guest checkout");
+
+  // Run
+  const started = await tool(env, token, "run_tests", { projectId, planId: "checkout-guest", environmentId: "staging", browsers: ["chromium", "firefox"] });
+  assert.equal(started.isError, undefined, started.message);
+  assert.equal(started.data.where, "your workers");
+  assert.match(started.data.link, /^https:\/\/dash\.test\/runs\?project=shop&run=run_/);
+  const run = await tool(env, token, "get_run", { runId: started.data.runId });
+  assert.equal(run.data.status, "queued");
+  assert.equal(run.data.environmentBaseUrl, "https://staging.shop.test");
+  assert.ok(run.data.recentEvents.some((event: { type: string }) => event.type === "queued"));
+  const runs = await tool(env, token, "list_runs", { projectId, planId: "checkout-guest" });
+  assert.equal(runs.data.runs.length, 1);
+  const missingPlan = await tool(env, token, "run_tests", { projectId, planId: "nope" });
+  assert.equal(missingPlan.isError, true);
+
+  // A worker reports a failure; the assistant sees the step and Bugmole's diagnosis.
+  await call(env, "POST", `/api/runs/${started.data.runId}/claim`, { as: owner, body: { workerId: "w1" } });
+  const finished = await call(env, "POST", `/api/runs/${started.data.runId}`, {
+    as: owner,
+    body: {
+      status: "partial",
+      workerId: "w1",
+      stepsExecuted: 4,
+      stepsPassed: 3,
+      stepsFailed: 1,
+      targetResults: [{
+        targetId: "chromium", browser: "chromium", status: "failed", stepsPassed: 3, stepsFailed: 1, artifactKeys: [],
+        steps: [{ index: 3, status: "failed", label: "See “Order placed”", message: "Not visible after 10s" }],
+        analysis: { title: "The confirmation text changed", category: "test", source: "ai", fixSummary: "Assert “Thanks for your order”" },
+      }],
+    },
+  });
+  assert.ok([200, 201].includes(finished.status), JSON.stringify(finished.json));
+  const report = await tool(env, token, "get_run", { runId: started.data.runId });
+  assert.equal(report.data.status, "partial");
+  assert.deepEqual(report.data.targets[0].failedStep, { number: 4, label: "See “Order placed”", message: "Not visible after 10s" });
+  assert.deepEqual(report.data.targets[0].diagnosis, { title: "The confirmation text changed", cause: "test", fix: "Assert “Thanks for your order”" });
+});
+
+test("assistants can only reach what the person can", async () => {
+  const { env } = mcpEnv();
+  const { owner, projectId } = await seedProject(env, { storageProvider: "bugmole" });
+  await call(env, "POST", `/api/projects/${projectId}/plans`, {
+    as: owner,
+    body: { planId: "checkout", journeyId: "checkout", objectKey: `projects/${projectId}/plans/checkout.flow.yaml` },
+  });
+  const stranger = accessToken("user_stranger");
+  assert.deepEqual((await tool(env, stranger, "list_projects")).data, { projects: [] });
+  for (const [name, args] of [
+    ["list_test_plans", { projectId }],
+    ["get_test_plan", { projectId, planId: "checkout" }],
+    ["save_test_plan", { projectId, planId: "x", name: "x", flow: FLOW }],
+    ["run_tests", { projectId, planId: "checkout" }],
+    ["list_runs", { projectId }],
+    ["explore_app", { projectId, url: "https://shop.test" }],
+    ["list_journeys", { projectId }],
+  ] as const) {
+    const result = await tool(env, stranger, name, args);
+    assert.equal(result.isError, true, name);
+  }
+  const ownRun = await tool(env, accessToken(owner), "run_tests", { projectId, planId: "checkout" });
+  assert.equal((await tool(env, stranger, "get_run", { runId: ownRun.data.runId })).isError, true);
+});
+
+test("projects that keep files in their own storage get a clear answer", async () => {
+  const { env } = mcpEnv();
+  const { owner, projectId } = await seedProject(env, { storageProvider: "r2" });
+  const saved = await tool(env, accessToken(owner), "save_test_plan", { projectId, planId: "x", name: "x", flow: FLOW });
+  assert.equal(saved.isError, true);
+  assert.match(saved.message, /its own storage/);
+});
+
+test("a plan saved through MCP is one the runner can execute", async () => {
+  const { execute } = await import("../../runtime/executor.js");
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bugmole-mcp-plan-"));
+  try {
+    const specDir = path.join(dir, "spec");
+    fs.mkdirSync(path.join(specDir, "plans"), { recursive: true });
+    fs.mkdirSync(path.join(specDir, "flows"), { recursive: true });
+    const steps = parseMaestroStyleFlow(FLOW).steps;
+    fs.writeFileSync(path.join(specDir, "flows", "checkout-guest.yaml"), FLOW);
+    fs.writeFileSync(
+      path.join(specDir, "plans", "checkout-guest.flow.yaml"),
+      YAML.stringify(planDocument({ planId: "checkout-guest", name: "Guest checkout", journeyId: "checkout-guest", actor: "guest", steps })),
+    );
+    const contexts: DriverContext[] = [];
+    const driver = {
+      id: "playwright",
+      async run(context: DriverContext): Promise<DriverResult> {
+        contexts.push(context);
+        return { status: "passed", message: "ok", artifacts: [], steps: steps.map((_step, index) => ({ sequenceNumber: index, status: "passed" as const })) };
+      },
+    } as unknown as AppDriver;
+    let driverId = "";
+    const result = await execute(
+      { project: { id: "shop" }, runtime: { spec_dir: specDir, artifacts_dir: path.join(dir, "artifacts") } },
+      {
+        planId: "checkout-guest",
+        journeyId: "checkout-guest",
+        baseUrl: "https://staging.shop.test",
+        driverFactory: (_cfg: unknown, id: string) => {
+          driverId = id;
+          return driver;
+        },
+      },
+    );
+    assert.equal(result.status, "success", result.error ?? "");
+    assert.equal(driverId, "playwright");
+    assert.equal(fs.readFileSync(contexts[0].flowPath ?? "", "utf8"), FLOW);
+    assert.equal(result.stepsPassed, 4);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/registry-worker/mcp/routes.ts

@@ -0,0 +1,215 @@
+// Hosted MCP endpoint (Streamable HTTP, JSON responses) for ChatGPT, Claude
+// and other assistants. People sign in through Aegis; see docs/mcp-hosted.md.
+import { bearer, response, type Env } from "../core.js";
+import { flagMode } from "../flags.js";
+import { registryDispatch } from "../hooks.js";
+import { isDeprovisioned } from "../sso/membership.js";
+import { registerPublicRoutes } from "../routes/index.js";
+import { aegisIssuer, MCP_SCOPE, verifyMcpToken, type McpIdentity, type McpTokenEnv } from "./token.js";
+import { callTool, FLOW_REFERENCE, toolList, type RegistryCall } from "./tools.js";
+
+export const MCP_PATH = "/mcp";
+export const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const MAX_BODY_BYTES = 512 * 1024;
+
+type McpEnv = Env & McpTokenEnv & { AEGIS_ISSUER?: string };
+
+const INSTRUCTIONS = `Bugmole tests web apps the way a person uses them. Work in this order:
+
+1. explore: list_projects to pick a project and environment. For an app or area you don't know yet, explore_app, then get_exploration until it's done, then list_journeys.
+2. plan: write a flow for one journey (what a person does and should see), then save_test_plan. Read existing plans with list_test_plans / get_test_plan first and change them rather than duplicating.
+3. run: run_tests, then get_run until the status is success, partial, error or cancelled. Runs take a minute or two.
+4. report: summarise for the person: what passed, what failed at which step, Bugmole's diagnosis (test, app or environment) and the run link. If the test is at fault, fix the flow, save it and run again; if the app is at fault, say so and don't change the test to hide it.
+
+Never put real passwords in a flow; use {{secret.NAME}}.
+
+${FLOW_REFERENCE}`;
+
+export function mcpEnabled(env: Env): boolean {
+  return flagMode(env, "mcp") === "on";
+}
+
+function publicUrl(env: Env, request: Request): string {
+  return (env.REGISTRY_PUBLIC_URL || new URL(request.url).origin).replace(/\/+$/, "");
+}
+
+export function mcpResource(env: Env, request: Request): string {
+  return `${publicUrl(env, request)}${MCP_PATH}`;
+}
+
+function metadataUrl(env: Env, request: Request): string {
+  return `${publicUrl(env, request)}/.well-known/oauth-protected-resource${MCP_PATH}`;
+}
+
+const cors = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
+  "access-control-allow-headers": "authorization, content-type, mcp-protocol-version, mcp-session-id, last-event-id",
+  "access-control-expose-headers": "www-authenticate, mcp-session-id",
+  "access-control-max-age": "86400",
+};
+
+function withCors(res: Response): Response {
+  const headers = new Headers(res.headers);
+  for (const [name, value] of Object.entries(cors)) headers.set(name, value);
+  return new Response(res.body, { status: res.status, headers });
+}
+
+function unauthorized(env: Env, request: Request, error?: "invalid_token" | "insufficient_scope"): Response {
+  const parts = [`resource_metadata="${metadataUrl(env, request)}"`, `scope="${MCP_SCOPE}"`];
+  if (error) parts.unshift(`error="${error}"`);
+  return withCors(new Response(JSON.stringify({ error: error ?? "unauthorized", error_description: "Sign in to Bugmole to use these tools" }), {
+    status: 401,
+    headers: { "content-type": "application/json", "www-authenticate": `Bearer ${parts.join(", ")}` },
+  }));
+}
+
+function protectedResourceMetadata(env: McpEnv, request: Request): Response {
+  return withCors(Response.json({
+    resource: mcpResource(env, request),
+    authorization_servers: [aegisIssuer(env)],
+    scopes_supported: [MCP_SCOPE, "openid", "email", "offline_access"],
+    bearer_methods_supported: ["header"],
+    resource_name: "Bugmole",
+    resource_documentation: "https://bugmole.com/docs/ai-assistants",
+  }, { headers: { "cache-control": "public, max-age=300" } }));
+}
+
+type JsonRpcRequest = { jsonrpc?: string; id?: string | number | null; method?: string; params?: any };
+
+function rpcResult(id: JsonRpcRequest["id"], result: unknown) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+
+function rpcError(id: JsonRpcRequest["id"], code: number, message: string) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+
+/** Calls the registry's own routes in-process as the signed-in person, like the dashboard does. */
+export function registryCaller(env: Env, identity: McpIdentity, ctx: ExecutionContext, origin: string): RegistryCall {
+  return async (method, path, body, init = {}) => {
+    const dispatch = registryDispatch.fetch;
+    if (!dispatch) throw new Error("registry dispatch is not bound");
+    const headers = new Headers({
+      "x-aegis-id": identity.aegisId,
+      "x-aegis-secret": env.AEGIS_CLIENT_SECRET,
+      "x-bugmole-via": "mcp",
+    });
+    if (identity.email && identity.emailVerified) {
+      headers.set("x-aegis-email", identity.email);
+      headers.set("x-aegis-email-verified", "true");
+    }
+    if (identity.orgId) headers.set("x-aegis-org", identity.orgId);
+    let payload: string | undefined;
+    if (body !== undefined) {
+      payload = typeof body === "string" ? body : JSON.stringify(body);
+      headers.set("content-type", init.contentType ?? "application/json");
+      headers.set("content-length", String(new TextEncoder().encode(payload).byteLength));
+    }
+    const res = await dispatch(new Request(`${origin}${path}`, { method, headers, body: payload }), env, ctx);
+    const text = await res.text();
+    let json: any = null;
+    if (!init.raw) {
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+        json = null;
+      }
+    } else if (!res.ok) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+    return { status: res.status, json, text };
+  };
+}
+
+async function handleRpc(message: JsonRpcRequest, env: McpEnv, identity: McpIdentity, ctx: ExecutionContext, request: Request) {
+  const isNotification = message.id === undefined;
+  if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    return isNotification ? null : rpcError(message.id, -32600, "Invalid request");
+  }
+  switch (message.method) {
+    case "initialize": {
+      const requested = message.params?.protocolVersion;
+      const protocolVersion = PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0];
+      return rpcResult(message.id, {
+        protocolVersion,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "bugmole", title: "Bugmole", version: "1.0.0" },
+        instructions: INSTRUCTIONS,
+      });
+    }
+    case "ping":
+      return isNotification ? null : rpcResult(message.id, {});
+    case "tools/list":
+      return rpcResult(message.id, { tools: toolList() });
+    case "tools/call": {
+      const name = message.params?.name;
+      if (typeof name !== "string") return rpcError(message.id, -32602, "Tool name is required");
+      const origin = new URL(request.url).origin;
+      const result = await callTool(name, message.params?.arguments, {
+        call: registryCaller(env, identity, ctx, origin),
+        dashboardUrl: (env.DASHBOARD_URL || "https://app.bugmole.com").replace(/\/+$/, ""),
+      });
+      return rpcResult(message.id, result);
+    }
+    case "resources/list":
+      return rpcResult(message.id, { resources: [] });
+    case "prompts/list":
+      return rpcResult(message.id, { prompts: [] });
+    default:
+      if (message.method.startsWith("notifications/")) return null;
+      return isNotification ? null : rpcError(message.id, -32601, `Method not found: ${message.method}`);
+  }
+}
+
+async function handleMcp(request: Request, env: McpEnv, ctx: ExecutionContext): Promise<Response> {
+  if (request.method === "OPTIONS") return withCors(new Response(null, { status: 204 }));
+  const token = bearer(request);
+  if (!token) return unauthorized(env, request);
+  const identity = await verifyMcpToken(env, token, mcpResource(env, request));
+  if (!identity) return unauthorized(env, request, "invalid_token");
+  if (await isDeprovisioned(env, identity.aegisId)) return unauthorized(env, request, "invalid_token");
+  // No server-initiated stream and no sessions: every request stands alone.
+  if (request.method !== "POST") {
+    return withCors(new Response(null, { status: 405, headers: { allow: "POST, OPTIONS" } }));
+  }
+  const declared = Number(request.headers.get("content-length") ?? "0");
+  if (declared > MAX_BODY_BYTES) return withCors(response(rpcError(null, -32600, "Request too large"), 413));
+  const raw = await request.text();
+  if (raw.length > MAX_BODY_BYTES) return withCors(response(rpcError(null, -32600, "Request too large"), 413));
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return withCors(response(rpcError(null, -32700, "Parse error"), 400));
+  }
+  const batch = Array.isArray(parsed);
+  const messages = (batch ? parsed : [parsed]) as JsonRpcRequest[];
+  if (messages.length === 0 || messages.length > 20) return withCors(response(rpcError(null, -32600, "Invalid request"), 400));
+  const replies = [];
+  for (const message of messages) {
+    const reply = message && typeof message === "object"
+      ? await handleRpc(message, env, identity, ctx, request)
+      : rpcError(null, -32600, "Invalid request");
+    if (reply) replies.push(reply);
+  }
+  if (replies.length === 0) return withCors(new Response(null, { status: 202 }));
+  return withCors(response(batch ? replies : replies[0]));
+}
+
+registerPublicRoutes(async ({ request, env, url, ctx }) => {
+  const isMetadata = url.pathname === "/.well-known/oauth-protected-resource"
+    || url.pathname === `/.well-known/oauth-protected-resource${MCP_PATH}`;
+  const isEndpoint = url.pathname === MCP_PATH || url.pathname === `${MCP_PATH}/`;
+  if (!isMetadata && !isEndpoint) return null;
+  if (!mcpEnabled(env)) return response({ error: "Not found" }, 404);
+  if (isMetadata) {
+    if (request.method === "OPTIONS") return withCors(new Response(null, { status: 204 }));
+    return request.method === "GET" ? protectedResourceMetadata(env, request) : withCors(response({ error: "Method not allowed" }, 405));
+  }
+  return handleMcp(request, env, ctx);
+});