@aloud/runner 0.2.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "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": {

package/src/cli.ts

@@ -8,6 +8,13 @@
  */
 import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
+import { startApproval, waitForApproval, type ApprovalStart } from "./protocol/approval";
+import {
+  clearMcpCredentials,
+  mcpCredentialsPath,
+  readMcpCredentials,
+  writeMcpCredentials,
+} from "./config/mcp-credentials";
 import { mkdir } from "node:fs/promises";
 import { accessSync, constants, existsSync, openSync, readFileSync, unlinkSync } from "node:fs";
 import { hostname } from "node:os";
@@ -51,7 +58,11 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
     case "setup":
       return setup();
     case "mcp":
-      await startStdioServer();
+      // `aloud mcp` is the server an MCP host launches; `aloud mcp connect` is how it gets a
+      // credential in the first place. Same word, because from the outside they are one feature.
+      if (rest[0] === "connect") return connectMcp(rest.slice(1));
+      if (rest[0] === "disconnect") return disconnectMcp();
+      await startStdioServer((await mcpOptions()) ?? undefined);
       return 0;
     case "help":
     case "--help":
@@ -74,11 +85,12 @@ function printHelp(): void {
       "aloud - run usability studies on this machine",
       "",
       "  aloud setup                     What to do next, for a person or an agent",
-      "  aloud login [--token <token>]   Connect this machine to your workspace",
+      "  aloud login [--token <token>]   Connect this machine, approving it in your browser",
       "  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 mcp                       Serve MCP to an editor, using the saved credential",
+      "  aloud mcp connect               Connect an editor, approving it in your browser",
       "  aloud logout                    Forget the token on this machine",
       "",
       `Server: ${DEFAULT_SERVER}  (override with ALOUD_SERVER)`,
@@ -96,6 +108,7 @@ function policyOf(credentials: Credentials, argv: readonly string[]): LocalPolic
   return policyFrom({
     allowedHosts: credentials.allowedHosts,
     allowPrivateNetwork: credentials.allowPrivateNetwork,
+    syntheticEmailTemplate: process.env.UTA_SYNTHETIC_EMAIL_TEMPLATE ?? null,
     ...(concurrency !== null ? { maxConcurrentSessions: concurrency } : {}),
   });
 }
@@ -104,44 +117,63 @@ function policyOf(credentials: Credentials, argv: readonly string[]): LocalPolic
 
 async function login(argv: readonly string[]): Promise<number> {
   const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
-  let token = stringOption(argv, "--token");
-
-  if (!token) {
-    // An agent runs commands in a shell with nothing attached to stdin, so the prompt below would
-    // read end-of-file and the token would come back empty. That used to surface as "that does not
-    // look like a runner token", which blames the wrong thing and tells nobody what to do. This is
-    // the single step of setup that a person has to perform, so it is worth saying so precisely.
-    if (!process.stdin.isTTY) {
-      process.stderr.write(
-        [
-          "",
-          "There is no terminal attached here, so there is nowhere to paste a token.",
-          "",
-          "If you are an agent: stop and hand this back. The person runs `aloud login` in their",
-          "own terminal and pastes the token at the prompt. Do not ask them to paste it to you.",
-          "",
-          "To connect without a terminal, set both of these instead and skip login entirely:",
-          `  export ALOUD_SERVER=${server}`,
-          "  export ALOUD_RUNNER_TOKEN=utar_...",
-          "",
-          `A token comes from ${server}/app/settings/runners and is shown once.`,
-          "",
-        ].join("\n"),
-      );
-      return 1;
-    }
+  const token = stringOption(argv, "--token");
 
-    process.stdout.write(`\nOpen ${server}/app/settings/runners and create a runner.\n`);
-    process.stdout.write("It shows you a token once. Paste it here.\n\n");
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    try {
-      token = (await rl.question("Token: ")).trim();
-    } finally {
-      rl.close();
-    }
+  // A token on the command line is for CI, where there is nobody to click anything. Everything else
+  // goes through an approval, including a terminal: it is fewer steps even when someone is watching.
+  if (token) return connectWith(server, token);
+
+  let started: ApprovalStart;
+  try {
+    started = await startApproval({ server, kind: "runner", name: hostname() });
+  } catch (error) {
+    process.stderr.write(`\n${(error as Error).message}\n\n`);
+    return 1;
   }
 
-  if (!token?.startsWith("utar_")) {
+  process.stdout.write("\nTo connect this machine, open this page and approve it:\n\n");
+  process.stdout.write(`  ${started.approveUrl}\n\n`);
+  process.stdout.write("Then type this code on that page:\n\n");
+  process.stdout.write(`  ${started.userCode}\n\n`);
+  // Said explicitly because the thing running this is often not a person, and the old flow trained
+  // agents to go looking for a token to paste. There is nothing to paste any more.
+  process.stdout.write("Waiting for approval. Nothing here needs a terminal, and there is no token\n");
+  process.stdout.write("to paste: if you are an agent, give the person the link and the code above.\n\n");
+
+  // Opening a browser is a courtesy for whoever is sitting here. It is never attempted when nobody
+  // is, and a failure is ignored, because the printed URL is the thing that actually matters.
+  if (process.stdout.isTTY) openInBrowser(started.approveUrl);
+
+  const outcome = await waitForApproval(started, {
+    server,
+    onWaiting: (seconds) => process.stdout.write(`  still waiting (${seconds}s)\n`),
+  }).catch((error: Error) => {
+    process.stderr.write(`\n${error.message}\n`);
+    return null;
+  });
+
+  if (!outcome) return 1;
+  if (outcome.status === "denied") {
+    process.stderr.write("\nThat request was refused. Nothing was connected.\n\n");
+    return 1;
+  }
+  if (outcome.status === "expired") {
+    process.stderr.write("\nThat request expired before anyone approved it. Run `aloud login` again.\n\n");
+    return 1;
+  }
+
+  return connectWith(server, outcome.secret);
+}
+
+/**
+ * Writes the credential and says what this machine may now do.
+ *
+ * Shared by both paths on purpose: a token that arrived through an approval and one passed on the
+ * command line have to end up in exactly the same state on disk, or the two ways of connecting
+ * diverge in ways nobody notices until one of them breaks.
+ */
+async function connectWith(server: string, token: string): Promise<number> {
+  if (!token.startsWith("utar_")) {
     process.stderr.write("That does not look like a runner token. They start with utar_.\n");
     return 1;
   }
@@ -184,6 +216,93 @@ async function login(argv: readonly string[]): Promise<number> {
   return 0;
 }
 
+/** Best effort, and deliberately silent about failing. The URL was already printed. */
+function openInBrowser(url: string): void {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // No browser here. That is what the printed link is for.
+  }
+}
+
+/**
+ * Connects an MCP host, through the same approval as a machine.
+ *
+ * The difference from a runner is only what the approval mints. Everything a person experiences,
+ * and everything an agent has to do, is identical: a link, a code, and a wait. Nobody edits a
+ * config file to hold a token, which was the last place a credential still had to be carried by
+ * hand after `aloud login` stopped needing one.
+ */
+async function connectMcp(argv: readonly string[]): Promise<number> {
+  const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
+
+  let started: ApprovalStart;
+  try {
+    started = await startApproval({ server, kind: "mcp", name: hostname() });
+  } catch (error) {
+    process.stderr.write(`\n${(error as Error).message}\n\n`);
+    return 1;
+  }
+
+  process.stdout.write("\nTo connect this editor to your workspace, open this page and approve it:\n\n");
+  process.stdout.write(`  ${started.approveUrl}\n\n`);
+  process.stdout.write("Then type this code on that page:\n\n");
+  process.stdout.write(`  ${started.userCode}\n\n`);
+  process.stdout.write("Waiting for approval. There is no token to paste anywhere.\n\n");
+  if (process.stdout.isTTY) openInBrowser(started.approveUrl);
+
+  const outcome = await waitForApproval(started, {
+    server,
+    onWaiting: (seconds) => process.stdout.write(`  still waiting (${seconds}s)\n`),
+  }).catch((error: Error) => {
+    process.stderr.write(`\n${error.message}\n`);
+    return null;
+  });
+
+  if (!outcome) return 1;
+  if (outcome.status === "denied") {
+    process.stderr.write("\nThat request was refused. Nothing was connected.\n\n");
+    return 1;
+  }
+  if (outcome.status === "expired") {
+    process.stderr.write("\nThat request expired. Run `aloud mcp connect` again.\n\n");
+    return 1;
+  }
+
+  await writeMcpCredentials({ server, token: outcome.secret });
+
+  process.stdout.write(`\nConnected. The credential is in ${mcpCredentialsPath()}, not in any config file.\n`);
+  process.stdout.write("Point your MCP host at `aloud mcp` and it will find it.\n\n");
+  return 0;
+}
+
+async function disconnectMcp(): Promise<number> {
+  const removed = await clearMcpCredentials();
+  process.stdout.write(
+    removed
+      ? `Forgot the MCP credential at ${mcpCredentialsPath()}.\nRevoke it in the web app too, if you want it dead everywhere.\n`
+      : "There was no MCP credential here to forget.\n",
+  );
+  return 0;
+}
+
+/**
+ * The credential `aloud mcp` runs with, if there is one.
+ *
+ * The environment wins, so CI and self-hosting keep working exactly as they did. A missing file is
+ * not an error here: `startStdioServer` falls back to the environment and produces the message that
+ * explains what to set.
+ */
+async function mcpOptions(): Promise<{ server: string; token: string } | null> {
+  const credentials = await readMcpCredentials().catch(() => null);
+  if (!credentials) return null;
+  if (process.env.ALOUD_MCP_TOKEN?.trim()) return null;
+  return { server: credentials.server, token: credentials.token };
+}
+
 async function logout(): Promise<number> {
   const removed = await clearCredentials();
   process.stdout.write(removed ? `Forgot the token at ${credentialsPath()}.\n` : "There was nothing to forget.\n");
@@ -257,8 +376,8 @@ async function setup(): Promise<number> {
   if (signedIn.state === "none" || signedIn.state === "revoked") {
     steps.push([
       "aloud login",
-      "Needs a terminal. If you are an agent, hand this step to the person: they run it",
-      "themselves and paste the token at the prompt. Do not ask them to paste it to you.",
+      "Prints a link and a short code, then waits. Give both to the person; they approve in",
+      "their browser. Nothing to paste, and no terminal needed. It finishes on its own.",
     ]);
   }
   if (!running) {
@@ -300,8 +419,8 @@ async function setup(): Promise<number> {
   }
   out("  - The package is `@aloud/runner`, exactly. If that name does not resolve, stop and say so.");
   out("    Do not install a similarly named package, and do not hand the token to anything else.");
-  out("  - The token is a credential. It belongs in this terminal, never in your transcript,");
-  out("    a file, an .env, or a commit. Get one at https://usealoud.com/app/settings/runners");
+  out("  - There is nothing secret for you to handle. `aloud login` prints a link and a code,");
+  out("    and the credential goes straight to this machine. Never ask anyone for a token.");
   out("  - `aloud start` does not exit. Run it in a background shell and do not block on it.");
   out();
   if (!credentials) {
@@ -350,14 +469,12 @@ async function interactiveSetup(state: {
     if (state.signedIn.state !== "ok") {
       out("");
       if (state.signedIn.state === "revoked") {
-        out(`The token saved here was revoked, so this machine needs a new one.`);
+        out("The credential saved here was revoked, so this machine needs connecting again.");
       }
-      out(`Create a token at ${server}/app/settings/runners`);
-      out("It is shown once. Copy it, then paste it below.");
-      out("");
-      const token = (await rl.question("Token: ")).trim();
       rl.close();
-      const code = await login(["--token", token, "--server", server]);
+      // Straight into the approval. There is no token to ask anybody for any more, so there is
+      // nothing to prompt for either.
+      const code = await login(["--server", server]);
       if (code !== 0) return code;
     } else {
       rl.close();

package/src/config/mcp-credentials.ts

@@ -0,0 +1,83 @@
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * The MCP grant, at ~/.aloud/mcp.json, mode 0600.
+ *
+ * Kept in its own file rather than beside the runner token, because they are different credentials
+ * with different lifetimes: a machine can be revoked without cutting off an editor, and an editor
+ * can be disconnected without stopping studies. Same rules as `credentials.ts` otherwise, including
+ * the refusal to read a file other users can see.
+ *
+ * This exists so nobody has to paste a token into an MCP host's config file. `aloud mcp connect`
+ * puts it here, and `aloud mcp` reads it.
+ */
+export interface McpCredentials {
+  server: string;
+  token: string;
+}
+
+export class McpCredentialsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "McpCredentialsError";
+  }
+}
+
+export function mcpCredentialsPath(home = homedir()): string {
+  return join(home, ".aloud", "mcp.json");
+}
+
+export async function readMcpCredentials(path = mcpCredentialsPath()): Promise<McpCredentials | null> {
+  let raw: string;
+  try {
+    const info = await stat(path);
+    // eslint-disable-next-line no-bitwise
+    if ((info.mode & 0o077) !== 0) {
+      throw new McpCredentialsError(
+        `${path} can be read by other users on this machine. Fix it with:\n  chmod 600 ${path}`,
+      );
+    }
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof McpCredentialsError) throw error;
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+
+  let parsed: Partial<McpCredentials>;
+  try {
+    parsed = JSON.parse(raw) as Partial<McpCredentials>;
+  } catch {
+    throw new McpCredentialsError(`${path} is not valid JSON. Delete it and run \`aloud mcp connect\` again.`);
+  }
+  if (!parsed.token || !parsed.server) {
+    throw new McpCredentialsError(`${path} is missing fields. Delete it and run \`aloud mcp connect\` again.`);
+  }
+
+  return { server: parsed.server.replace(/\/+$/, ""), token: parsed.token };
+}
+
+/** `mode` on writeFile only applies at creation, so the chmod is the part that actually holds. */
+export async function writeMcpCredentials(
+  credentials: McpCredentials,
+  path = mcpCredentialsPath(),
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+export async function clearMcpCredentials(path = mcpCredentialsPath()): Promise<boolean> {
+  try {
+    await writeFile(path, "", { mode: 0o600, flag: constants.O_WRONLY | constants.O_TRUNC });
+    const { unlink } = await import("node:fs/promises");
+    await unlink(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/config/policy.ts

@@ -25,6 +25,8 @@ export interface LocalPolicy {
   allowPrivateNetwork: boolean;
   /** The server does not know how much memory this machine has. This is a local decision. */
   maxConcurrentSessions: number;
+  /** Runner-local QA inbox/catch-all; never supplied by the control plane. */
+  syntheticEmailTemplate: string | null;
 }
 
 export const DEFAULT_MAX_CONCURRENT_SESSIONS = 3;
@@ -33,6 +35,7 @@ export function policyFrom(input: {
   allowedHosts?: readonly string[];
   allowPrivateNetwork?: boolean;
   maxConcurrentSessions?: number;
+  syntheticEmailTemplate?: string | null;
 }): LocalPolicy {
   return {
     allowedHosts: normaliseHosts(input.allowedHosts ?? []),
@@ -40,6 +43,7 @@ export function policyFrom(input: {
     // Clamped rather than trusted: three browsers is already a lot on a laptop, and a typo of 300
     // should not take the machine down.
     maxConcurrentSessions: clamp(input.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS, 1, 8),
+    syntheticEmailTemplate: input.syntheticEmailTemplate?.trim() || null,
   };
 }
 

package/src/model/proxy-adapter.ts

@@ -107,6 +107,7 @@ export class ProxyModelAdapter implements ModelAdapter {
       system: request.system,
       prompt: request.prompt,
       responseShape: request.responseShape,
+      responseSchema: request.responseSchema,
       maxOutputTokens: request.maxOutputTokens,
       temperature: request.temperature,
       images,

package/src/protocol/approval.ts

@@ -0,0 +1,99 @@
+/**
+ * Getting a credential onto this machine without anybody carrying one.
+ *
+ * The client asks the server to open an approval, prints a URL and a short code, and waits. A person
+ * opens that URL in a browser they are already signed in to, types the code this printed, and
+ * approves. The next poll returns the credential and writes it to disk.
+ *
+ * The reason this exists rather than a prompt: a prompt needs a terminal, and the thing driving
+ * setup is increasingly an agent that does not have one. Waiting on a click needs nothing but time,
+ * so the same command works for a person and for an agent, and neither of them ever sees a token.
+ */
+export interface ApprovalStart {
+  id: string;
+  userCode: string;
+  deviceCode: string;
+  approveUrl: string;
+  expiresAt: string;
+  pollMs: number;
+}
+
+export type ApprovalOutcome =
+  | { status: "approved"; secret: string; kind: "runner" | "mcp" }
+  | { status: "denied" }
+  | { status: "expired" };
+
+export class ApprovalFailed extends Error {}
+
+export async function startApproval(input: {
+  server: string;
+  kind: "runner" | "mcp";
+  name?: string | null;
+  fetchImpl?: typeof fetch;
+}): Promise<ApprovalStart> {
+  const response = await (input.fetchImpl ?? fetch)(new URL("api/approvals", input.server + "/"), {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    redirect: "error",
+    body: JSON.stringify({ kind: input.kind, name: input.name ?? null }),
+  });
+  if (!response.ok) {
+    throw new ApprovalFailed(`${input.server} would not start an approval (${response.status}).`);
+  }
+  return (await response.json()) as ApprovalStart;
+}
+
+/**
+ * Polls until somebody answers, or the request expires.
+ *
+ * `204` means keep waiting, matching the run loop's claim endpoint. The interval comes from the
+ * server rather than being chosen here, because every poll is an invocation on the other end and
+ * the server is the side that knows what it can afford.
+ */
+export async function waitForApproval(
+  start: ApprovalStart,
+  deps: {
+    server: string;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    onWaiting?: (secondsElapsed: number) => void;
+    signal?: AbortSignal;
+  },
+): Promise<ApprovalOutcome> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now ?? (() => Date.now());
+
+  const startedAt = now();
+  const deadline = Date.parse(start.expiresAt);
+  let announced = 0;
+
+  for (;;) {
+    if (deps.signal?.aborted) throw new ApprovalFailed("Stopped waiting.");
+    if (now() >= deadline) return { status: "expired" };
+
+    const response = await fetchImpl(new URL("api/approvals/collect", deps.server + "/"), {
+      method: "POST",
+      headers: { authorization: `Bearer ${start.deviceCode}`, accept: "application/json" },
+      redirect: "error",
+    }).catch(() => null);
+
+    // A dropped poll is not an answer. Keep waiting rather than failing someone's setup because a
+    // wifi card slept: the deadline is what ends this, not one bad request.
+    if (response && response.status !== 204) {
+      if (!response.ok) {
+        throw new ApprovalFailed(`${deps.server} refused the approval check (${response.status}).`);
+      }
+      const body = (await response.json()) as ApprovalOutcome;
+      if (body.status !== "expired" || now() >= deadline) return body;
+    }
+
+    const elapsed = Math.round((now() - startedAt) / 1000);
+    if (elapsed - announced >= 15) {
+      announced = elapsed;
+      deps.onWaiting?.(elapsed);
+    }
+    await sleep(start.pollMs);
+  }
+}

package/src/protocol/client.ts

@@ -76,6 +76,7 @@ export interface ModelProxyRequest {
   system: string | null;
   prompt: string;
   responseShape: string;
+  responseSchema: Record<string, unknown>;
   maxOutputTokens: number;
   temperature: number;
   images: unknown[];

package/src/run/execute.ts

@@ -155,6 +155,7 @@ export async function executeLease(deps: ExecuteDeps): Promise<ExecuteResult> {
       run: { ...deps.run, snapshot },
       snapshot,
       productId: deps.productId,
+      syntheticEmailTemplate: deps.local.syntheticEmailTemplate,
     },
     {
       gateway,
@@ -253,6 +254,9 @@ export async function executeLease(deps: ExecuteDeps): Promise<ExecuteResult> {
   if (outcome && !leaseLost) {
     // Same order as the server's own persistence: findings before the report, because the report
     // holds ordered identifiers that have to resolve to something.
+    // Sessions are checkpointed before synthesis, then posted again here because integrity runs
+    // during synthesis and enriches them with the evidence exclusions the replay must disclose.
+    await postPart(deps.client, deps.lease.id, "sessions", outcome.sessions);
     await postPart(deps.client, deps.lease.id, "judgments", outcome.judgments);
     await postPart(deps.client, deps.lease.id, "issues", outcome.issues);
     await postPart(deps.client, deps.lease.id, "findings", outcome.findings);

package/src/version.ts

@@ -10,7 +10,7 @@
  * 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.5";
+export const RUNNER_VERSION = "0.3.0";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";