@aloud/runner 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Run Aloud usability studies in a real browser on your own machine, so a study can reach localhost and anything else behind your network.",
   "license": "ISC",
   "repository": {
@@ -21,14 +21,17 @@
   "files": ["dist/cli.js", "src", "README.md"],
   "engines": { "node": ">=20" },
   "scripts": {
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --external:playwright --external:sharp --outfile=dist/cli.js",
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --external:playwright --external:sharp --external:@modelcontextprotocol/sdk --external:zod --outfile=dist/cli.js",
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "playwright": "^1.62.1",
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.3",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@aloud/mcp": "*",
     "@aloud/core": "*",
     "@aloud/engine": "*",
     "@aloud/eval": "*",

package/src/cli.ts

@@ -25,6 +25,7 @@ import { RunnerClient } from "./protocol/client";
 import { installChromium, preflight } from "./preflight";
 import { TerminalReporter } from "./ui/output";
 import { runLoop } from "./loop";
+import { startStdioServer } from "@aloud/mcp";
 
 /** Where a runner reaches the hosted control plane. Overridable for self-hosting and for tests. */
 const DEFAULT_SERVER = process.env.ALOUD_SERVER?.replace(/\/+$/, "") || "https://usealoud.com";
@@ -43,6 +44,9 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
       return status();
     case "allow":
       return allow(rest);
+    case "mcp":
+      await startStdioServer();
+      return 0;
     case "help":
     case "--help":
     case "-h":
@@ -67,6 +71,7 @@ function printHelp(): void {
       "  aloud start [--once] [--quiet]  Wait for studies and run them here",
       "  aloud status                    What is set up, and whether it is running",
       "  aloud allow <host>              Let studies open this host from this machine",
+      "  aloud mcp                       Connect an MCP host to the Aloud web workspace",
       "  aloud logout                    Forget the token on this machine",
       "",
       `Server: ${DEFAULT_SERVER}  (override with ALOUD_SERVER)`,

package/src/discovery.ts

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { chromium, type BrowserContext } from "playwright";
+import {
+  VIEWPORT_PRESETS,
+  evaluateTargetUrl,
+  hostPermitted,
+  intersectHosts,
+  type DeviceContext,
+  type DiscoveryLink,
+  type DiscoveryPage,
+  type ProductDiscoveryEvidence,
+  type StudySetupJob,
+} from "@aloud/core";
+import type { LocalPolicy } from "./config/policy";
+
+const MAX_PAGES = 6;
+const MAX_LINKS_PER_PAGE = 200;
+const PAGE_TIMEOUT_MS = 15_000;
+
+/**
+ * Reads a small, public-facing corpus without clicking controls, submitting forms, or carrying a
+ * signed-in browser profile. The server can narrow this job, but only the on-disk policy can grant
+ * this machine access to a host.
+ */
+export async function discoverProduct(
+  job: StudySetupJob,
+  local: LocalPolicy,
+): Promise<ProductDiscoveryEvidence> {
+  const effectiveHosts = intersectHosts(job.allowedHosts, local.allowedHosts);
+  if (effectiveHosts.length === 0) {
+    throw new Error(
+      `Product discovery wants ${job.allowedHosts.join(", ")}, but this machine allows ` +
+        `${local.allowedHosts.join(", ") || "nothing"}.`,
+    );
+  }
+  await assertTarget(job.url, effectiveHosts, local);
+
+  const browser = await chromium.launch({
+    args: ["--disable-dev-shm-usage"],
+    handleSIGINT: false,
+    handleSIGTERM: false,
+    handleSIGHUP: false,
+  });
+  const viewport = VIEWPORT_PRESETS[job.device as DeviceContext];
+  const context = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height },
+    deviceScaleFactor: viewport.deviceScaleFactor,
+    isMobile: viewport.isMobile,
+    hasTouch: viewport.isMobile,
+    serviceWorkers: "block",
+  });
+
+  try {
+    await guardRequests(context, effectiveHosts, local);
+    const start = canonicalUrl(job.url);
+    const origin = new URL(start).origin;
+    const queued = [start];
+    const seen = new Set<string>();
+    const pages: DiscoveryPage[] = [];
+
+    while (queued.length > 0 && pages.length < MAX_PAGES) {
+      const url = queued.shift()!;
+      if (seen.has(url)) continue;
+      seen.add(url);
+      try {
+        await assertTarget(url, effectiveHosts, local);
+        const page = await context.newPage();
+        try {
+          page.setDefaultTimeout(PAGE_TIMEOUT_MS);
+          await page.goto(url, { waitUntil: "domcontentloaded", timeout: PAGE_TIMEOUT_MS });
+          try {
+            await page.waitForLoadState("networkidle", { timeout: 1_500 });
+          } catch {
+            // Some products poll forever. The DOM is still useful after DOMContentLoaded.
+          }
+          await assertTarget(page.url(), effectiveHosts, local);
+          const captured = await extractPage(page);
+          pages.push(captured);
+
+          const candidates = prioritiseDiscoveryLinks(captured.links, origin)
+            .map((link) => canonicalUrl(link.href))
+            .filter((href) => !seen.has(href) && !queued.includes(href));
+          queued.push(...candidates.slice(0, MAX_PAGES - pages.length));
+        } finally {
+          await page.close();
+        }
+      } catch (error) {
+        if (pages.length === 0) throw error;
+        // A stale marketing link should not erase the useful pages already captured.
+      }
+    }
+
+    if (pages.length === 0) throw new Error("Product discovery could not read the starting page.");
+    const capturedAt = new Date().toISOString();
+    const sourceFingerprint = createHash("sha256")
+      .update(JSON.stringify(pages.map(({ url, title, headings, visibleText }) => ({ url, title, headings, visibleText }))))
+      .digest("hex");
+    return { pages, sourceFingerprint, capturedAt };
+  } finally {
+    await context.close();
+    await browser.close();
+  }
+}
+
+async function assertTarget(url: string, allowedDomains: string[], local: LocalPolicy): Promise<void> {
+  const verdict = await evaluateTargetUrl(url, {
+    allowedDomains,
+    allowPrivateNetwork: local.allowPrivateNetwork,
+  });
+  if (!verdict.allowed) throw new Error(`Refusing product discovery: ${verdict.reason}`);
+}
+
+async function guardRequests(
+  context: BrowserContext,
+  allowedDomains: string[],
+  local: LocalPolicy,
+): Promise<void> {
+  await context.route("**/*", async (route) => {
+    const request = route.request();
+    let url: URL;
+    try {
+      url = new URL(request.url());
+    } catch {
+      await route.abort("blockedbyclient");
+      return;
+    }
+    if (url.protocol === "data:" || url.protocol === "blob:") {
+      await route.continue();
+      return;
+    }
+    if (
+      (url.protocol !== "http:" && url.protocol !== "https:") ||
+      !hostPermitted(url.hostname, allowedDomains)
+    ) {
+      await route.abort("blockedbyclient");
+      return;
+    }
+    if (request.resourceType() === "document") {
+      const verdict = await evaluateTargetUrl(url.toString(), {
+        allowedDomains,
+        allowPrivateNetwork: local.allowPrivateNetwork,
+      });
+      if (!verdict.allowed) {
+        await route.abort("blockedbyclient");
+        return;
+      }
+    }
+    await route.continue();
+  });
+}
+
+async function extractPage(page: import("playwright").Page): Promise<DiscoveryPage> {
+  // Pass source text rather than a closure here. TypeScript runners may decorate nested
+  // functions with module-local helpers that do not exist inside the browser realm.
+  const extracted = await page.evaluate(`(() => {
+    const isVisible = (element) => {
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+    };
+    const headings = [];
+    for (const element of document.querySelectorAll("h1,h2,h3")) {
+      if (!isVisible(element)) continue;
+      const text = (element.innerText || "").replace(/\\s+/g, " ").trim();
+      if (text) headings.push(text);
+    }
+    const links = [];
+    for (const element of document.querySelectorAll("a[href]")) {
+      if (!isVisible(element)) continue;
+      const href = element.href;
+      if (!href.startsWith("http://") && !href.startsWith("https://")) continue;
+      links.push({ href, text: (element.innerText || "").replace(/\\s+/g, " ").trim() });
+    }
+    return {
+      title: document.title || "",
+      headings,
+      visibleText: (document.body?.innerText || "").replace(/\\s+/g, " ").trim(),
+      links,
+    };
+  })()`) as {
+    title: string;
+    headings: string[];
+    visibleText: string;
+    links: DiscoveryLink[];
+  };
+  return {
+    url: canonicalUrl(page.url()),
+    title: extracted.title.slice(0, 300),
+    headings: [...new Set(extracted.headings)].slice(0, 80).map((heading) => heading.slice(0, 300)),
+    visibleText: extracted.visibleText.slice(0, 30_000),
+    links: extracted.links.slice(0, MAX_LINKS_PER_PAGE).map((link) => ({
+      href: link.href,
+      text: link.text.slice(0, 240),
+    })),
+  };
+}
+
+/** Stable and exported so corpus selection can be unit-tested without launching Chromium. */
+export function prioritiseDiscoveryLinks(links: DiscoveryLink[], origin: string): DiscoveryLink[] {
+  const scores = [
+    [/\b(pricing|plans?)\b/i, 100],
+    [/\b(features?|product)\b/i, 95],
+    [/\b(use[- ]?cases?|solutions?)\b/i, 90],
+    [/\b(customers?|stories|case[- ]?studies)\b/i, 80],
+    [/\b(docs?|guides?|help)\b/i, 70],
+    [/\b(about|why)\b/i, 60],
+  ] as const;
+  const destructive = /\b(log[- ]?out|sign[- ]?out|delete|remove|unsubscribe)\b/i;
+  const unique = new Map<string, { link: DiscoveryLink; score: number; index: number }>();
+  links.forEach((link, index) => {
+    try {
+      const url = new URL(link.href);
+      if (url.origin !== origin || destructive.test(`${link.text} ${url.pathname}`)) return;
+      const key = canonicalUrl(url.toString());
+      const haystack = `${link.text} ${url.pathname.replace(/[-_/]+/g, " ")}`;
+      const score = scores.find(([pattern]) => pattern.test(haystack))?.[1] ?? 0;
+      if (!unique.has(key)) unique.set(key, { link: { ...link, href: key }, score, index });
+    } catch {
+      // Invalid page links are not evidence and do not stop discovery.
+    }
+  });
+  return [...unique.values()]
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .map(({ link }) => link);
+}
+
+function canonicalUrl(raw: string): string {
+  const url = new URL(raw);
+  url.hash = "";
+  return url.toString();
+}

package/src/index.ts

@@ -22,3 +22,4 @@ export * from "./run/execute";
 export * from "./ui/output";
 export * from "./preflight";
 export * from "./loop";
+export * from "./discovery";

package/src/loop.ts

@@ -1,9 +1,10 @@
-import { systemClock, type JobLease, type StudyRun } from "@aloud/core";
+import { systemClock, type JobLease, type StudyRun, type StudySetupJob } from "@aloud/core";
 import { OfflineError, RunnerClient, LeaseLostError, ServerError } from "./protocol/client";
 import { BlobSpool } from "./protocol/blob-spool";
 import { executeLease, type ExecuteResult, type RunReporter } from "./run/execute";
 import type { StageRouting } from "./model/proxy-adapter";
 import type { LocalPolicy } from "./config/policy";
+import { discoverProduct } from "./discovery";
 
 /**
  * Claim, run, repeat.
@@ -21,8 +22,10 @@ const FAST_WINDOW_MS = 30_000;
 const IDLE_AFTER_MS = 5 * 60_000;
 
 interface ClaimResponse {
+  kind?: "study_run" | "product_discovery";
   lease?: JobLease;
   run?: StudyRun;
+  setupJob?: StudySetupJob;
   productId?: string;
   routing?: Partial<Record<string, StageRouting>>;
 }
@@ -75,6 +78,36 @@ export async function runLoop(deps: LoopDeps): Promise<ExecuteResult[]> {
       throw error;
     }
 
+    if (claim?.kind === "product_discovery" && claim.setupJob) {
+      lastActivityAt = now();
+      deps.ui.note(`Learning what ${new URL(claim.setupJob.url).hostname} does from its public pages.`);
+      try {
+        const evidence = await discoverProduct(claim.setupJob, deps.local);
+        await deps.client.request("api/runner/discovery", {
+          method: "POST",
+          body: { setupJobId: claim.setupJob.id, evidence },
+          ...(deps.signal ? { signal: deps.signal } : {}),
+        });
+        deps.ui.note(`Product context captured from ${evidence.pages.length} page${evidence.pages.length === 1 ? "" : "s"}.`);
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : "Product discovery failed.";
+        deps.ui.failed(reason);
+        try {
+          await deps.client.request("api/runner/discovery", {
+            method: "POST",
+            body: { setupJobId: claim.setupJob.id, failureReason: reason },
+            ...(deps.signal ? { signal: deps.signal } : {}),
+          });
+        } catch {
+          // The control plane will expire the job; the original browser error is the useful one.
+        }
+      }
+      lastActivityAt = now();
+      if (deps.once) break;
+      deps.ui.waiting?.(deps.webUrl);
+      continue;
+    }
+
     if (claim?.lease && !claim.run) {
       // The server offered work without saying what it is. Better to say so than to invent a run
       // row and write a report whose methodology section is fiction.

package/src/model/proxy-adapter.ts

@@ -1,6 +1,6 @@
 import { ModelError, type AdapterRequest, type AdapterResponse, type ModelAdapter } from "@aloud/engine";
 import type { ProviderName, PromptStage } from "@aloud/core";
-import { LeaseLostError, ServerError, type RunnerClient } from "../protocol/client";
+import { LeaseLostError, ServerError, type ModelProxyRequest, type RunnerClient } from "../protocol/client";
 import type { BlobSpool } from "../protocol/blob-spool";
 
 /**
@@ -89,24 +89,35 @@ export class ProxyModelAdapter implements ModelAdapter {
   }
 
   private async post(request: AdapterRequest, images: unknown[]): Promise<ModelProxyResponse> {
-    const { body } = await this.deps.client.request<ModelProxyResponse>("api/runner/model", {
+    const body: ModelProxyRequest = {
+      leaseId: this.deps.leaseId,
+      stage: this.deps.stage,
+      // Sent so the server can reject a mismatch loudly rather than silently billing for
+      // something the runner did not ask for. The server's own table is the authority.
+      modelId: this.modelId,
+      // BILLING_PLAN 1.6: the proxy writes the usage row and can derive the workspace and the run
+      // from the lease, but not the participant or the moment. Only this side knows them, so only
+      // this side can send them, and the server checks the session against the lease before it
+      // believes any of it.
+      //
+      // Read off the request rather than off `this.deps`, because one adapter serves every session
+      // in a run at once: a field on the adapter would name whichever session called last.
+      sessionId: request.sessionId ?? null,
+      momentId: request.momentId ?? null,
+      system: request.system,
+      prompt: request.prompt,
+      responseShape: request.responseShape,
+      maxOutputTokens: request.maxOutputTokens,
+      temperature: request.temperature,
+      images,
+    };
+
+    const response = await this.deps.client.request<ModelProxyResponse>("api/runner/model", {
       method: "POST",
-      body: {
-        leaseId: this.deps.leaseId,
-        stage: this.deps.stage,
-        // Sent so the server can reject a mismatch loudly rather than silently billing for
-        // something the runner did not ask for. The server's own table is the authority.
-        modelId: this.modelId,
-        system: request.system,
-        prompt: request.prompt,
-        responseShape: request.responseShape,
-        maxOutputTokens: request.maxOutputTokens,
-        temperature: request.temperature,
-        images,
-      },
+      body,
       ...(request.signal ? { signal: request.signal } : {}),
     });
-    return body ?? {};
+    return response.body ?? {};
   }
 
   /** A hash if the server already has the bytes, the bytes if it does not. */

package/src/protocol/client.ts

@@ -1,4 +1,5 @@
 import { scrubToken } from "../config/credentials";
+import { RUNNER_VERSION, RUNNER_VERSION_HEADER } from "../version";
 
 /**
  * The runner's only route to the server.
@@ -50,6 +51,36 @@ export interface RunnerClientOptions {
 
 export const DEFAULT_OFFLINE_HORIZON_MS = 60_000;
 
+/**
+ * The body of a call to `api/runner/model`, which is the one request that spends money.
+ *
+ * Written down as a type because both halves of it are checked server-side and neither is believed:
+ * `stage` and `modelId` are validated against the server's own routing table, and `sessionId` is
+ * validated against the lease's run (SPEC 20.1). A runner cannot widen what it may spend on, or
+ * whose ledger the spend lands in, by editing this object.
+ */
+export interface ModelProxyRequest {
+  leaseId: string;
+  stage: string;
+  modelId: string;
+  /**
+   * BILLING_PLAN 1.6: which participant this call is for, and which moment it is paying for.
+   *
+   * The proxy knows the lease and therefore the run, but has no way to know either of these. Before
+   * they were sent, every study run through a local runner was invisible to per-session cost
+   * analysis, and cost per moment could not be measured at all. Null for stages outside the
+   * participant loop, such as synthesis.
+   */
+  sessionId: string | null;
+  momentId: string | null;
+  system: string | null;
+  prompt: string;
+  responseShape: string;
+  maxOutputTokens: number;
+  temperature: number;
+  images: unknown[];
+}
+
 export interface RequestOptions {
   method?: "GET" | "POST" | "PUT";
   body?: unknown;
@@ -100,6 +131,9 @@ export class RunnerClient {
           headers: {
             authorization: `Bearer ${this.options.token}`,
             accept: "application/json",
+            // Cheap on every request rather than negotiated once: a runner that upgrades mid-poll
+            // should be recognised on its next word, not after a reconnect.
+            [RUNNER_VERSION_HEADER]: RUNNER_VERSION,
             ...(options.raw
               ? { "content-type": options.raw.contentType }
               : options.body !== undefined

package/src/version.ts

@@ -0,0 +1,16 @@
+/**
+ * What this runner is, when it introduces itself.
+ *
+ * Sent as a header on every request, and recorded by the server on each claim, so the server can
+ * refuse to queue work a machine is too old to understand. The alternative, which is what happened
+ * before this existed, is a job nothing claims and a page that waits and then gives up without ever
+ * saying the word "upgrade".
+ *
+ * Written out rather than read from package.json at runtime. The bundle that ships to npm has no
+ * package.json beside it to read, and importing one into the source trips the composite build's
+ * rootDir. `version.test.ts` asserts this matches, so the drift this invites cannot survive CI.
+ */
+export const RUNNER_VERSION = "0.2.1";
+
+/** The header the server reads it from. */
+export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";