@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/src/server/desktop-server.ts

@@ -12,19 +12,22 @@ import {
   type JsonValue,
   REVIEW_DESKTOP_DISCOVERY_VERSION,
   type ReviewCliInstallApplyResponse,
+  ReviewConnectRequestSchema,
   type ReviewDesktopDiscovery,
-  type ReviewTutorialOpenResponse,
+  type ReviewGatewayHost,
   isJsonObject,
   isObjectValue,
   parseReviewCliInstallApplyRequest,
   reviewDiffrSummarizerInputSchema,
 } from "@dev.fast/review-protocol";
 import { shellQuote, writePrivateJsonAtomic } from "@dev.fast/trace-core";
-import type { AskTools } from "@review/ask/threads.js";
+import { connectAgent, detectConnectAgents } from "@review/agent-connect";
+import { type AskTools, cliAskTools } from "@review/ask/threads.js";
 import {
   applyCliInstall,
   declineCliInstall,
   finishCliInstallUpdate,
+  pathShimPath,
   removeCliInstall,
   removeLegacyReviewSkills,
   resetCliInstall,
@@ -52,6 +55,7 @@ import {
   type ReviewTelemetryContext,
 } from "@review/review-telemetry";
 import type { SharedReviewStore } from "@review/sharing/import.js";
+import { Hono } from "hono";
 import { z } from "zod";
 
 import { aliasInstallationToAccount } from "./account-alias";
@@ -67,18 +71,25 @@ import {
   GlobalReviewDesktopVerbRelay,
   type ReviewDesktopVerbRelay,
 } from "./global-verb-relay";
-import { createNodeRequestListener, readBoundedRequestJson } from "./hono-http";
+import {
+  type ReviewHonoEnv,
+  createNodeRequestListener,
+  readBoundedRequestJson,
+} from "./hono-http";
 import { ReviewServerError } from "./http-json";
 import { createJsonReviewReporting } from "./json-review-reporting";
+import { removeLegacyTutorial } from "./legacy-tutorial-cleanup";
+import { createReviewGateway } from "./review-gateway";
 import { reviewLifecycleTelemetry } from "./review-lifecycle-telemetry";
 import { ReviewOpenWatchdog } from "./review-open-watchdog";
-import { createWhiteboardCore, serverJson } from "./review-server-core";
+import {
+  answerErrorsAsJson,
+  createWhiteboardCore,
+  serverJson,
+} from "./review-server-core";
 import { invalidateStructuralComparisons } from "./structural-comparisons.js";
-import { createTutorialService } from "./tutorial-service";
 import { captureSanitizedUiTelemetry } from "./ui-telemetry";
 
-const TUTORIAL_LIFECYCLE_LOCK_KEY = "tutorial-lifecycle";
-
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -100,6 +111,8 @@ export interface GlobalReviewServerInput {
   relay?: ReviewDesktopVerbRelay;
   /** Electron's Review crash dump directory; `/crash-reports` reads only inside it. */
   crashDumpsDir?: string;
+  onRemoteHostRestarted?(alias: string): void;
+  log?(message: string): void;
 }
 
 export interface GlobalReviewServer {
@@ -107,6 +120,7 @@ export interface GlobalReviewServer {
   readonly url: string;
   listen(): Promise<void>;
   close(reason?: "app-exit"): Promise<void>;
+  setRemoteHosts(hosts: ReviewGatewayHost[]): void;
 }
 
 export function createGlobalReviewServer(
@@ -135,45 +149,13 @@ export function createGlobalReviewServer(
   const relay =
     input.relay ?? new GlobalReviewDesktopVerbRelay({ maxClients: 1 });
 
-  // This Desktop's own CLI, pinned to this instance so another running
-  // Whiteboard never answers it.
-  const askCliEnv = () => [
-    { name: REVIEW_INSTANCE_ENV, value: identity.key },
-    ...(process.versions.electron
-      ? [{ name: "ELECTRON_RUN_AS_NODE", value: "1" }]
-      : []),
-    ...(process.env.DEV_REVIEW_HOME
-      ? [{ name: "DEV_REVIEW_HOME", value: process.env.DEV_REVIEW_HOME }]
-      : []),
-  ];
-
-  // Ask sessions get its MCP server, `whiteboard mcp`; an agent whose model
-  // would not get it uses `whiteboard api` from its shell instead.
-  const askTools: AskTools = {
-    mcpServers: () =>
-      discovery.cliPath
-        ? [
-            {
-              name: "whiteboard",
-              command: process.execPath,
-              args: [discovery.cliPath, "mcp"],
-              env: askCliEnv(),
-            },
-          ]
-        : [],
-    cli: () =>
-      discovery.cliPath &&
-      [
-        ...askCliEnv().map(({ name, value }) => `${name}=${shellQuote(value)}`),
-        shellQuote(process.execPath),
-        shellQuote(discovery.cliPath),
-      ].join(" "),
-  };
+  const askTools = cliAskTools(() => discovery.cliPath, {
+    name: REVIEW_INSTANCE_ENV,
+    value: identity.key,
+  });
 
   const reviewStore = input.reviewStore;
 
-  const reviewLocks = new Map<string, Promise<void>>();
-
   // A reload or a second window starts the workbench again, but the launch
   // this server belongs to became ready once.
   let appReadyReported = false;
@@ -187,12 +169,6 @@ export function createGlobalReviewServer(
       ),
   });
 
-  const tutorial = createTutorialService({
-    packageRoot: input.packageRoot,
-    store: reviewStore,
-    data: input.reviewData,
-  });
-
   let closing = false;
   const cliPath = path.join(input.packageRoot, "dist", "cli.js");
 
@@ -258,14 +234,31 @@ export function createGlobalReviewServer(
 
   const { app } = core;
 
-  app.route(
+  const localApi = new Hono<ReviewHonoEnv>();
+  answerErrorsAsJson(localApi);
+
+  localApi.route(
     "/reviews-api",
     createJsonReviewReporting(input.reviewStore, telemetry, {
       shared: input.sharedReviews,
     }),
   );
 
-  app.route("/reviews-api", core.api);
+  localApi.route("/reviews-api", core.api);
+
+  const gateway = createReviewGateway({
+    local: (request) => localApi.fetch(request),
+    isLocal: (reviewId) => reviewStore.has(reviewId),
+    version: readReviewPackageVersion(import.meta.url),
+    home: devReviewHome(),
+    relay,
+    restarted: (alias) => input.onRemoteHostRestarted?.(alias),
+    log: input.log,
+  });
+
+  app.all("/reviews-api", (context) => gateway.fetch(context.req.raw));
+  app.all("/reviews-api/*", (context) => gateway.fetch(context.req.raw));
+  app.get("/remote-hosts", () => serverJson(200, gateway.hosts()));
   app.get("/preferences/scratchpad", () =>
     serverJson(200, { enabled: scratchpadEnabled }),
   );
@@ -372,32 +365,6 @@ export function createGlobalReviewServer(
 
     return serverJson(result.status, result.body);
   });
-  app.get("/tutorial/status", async () =>
-    serverJson(200, await tutorial.status()),
-  );
-  app.post("/tutorial/prepare", async () => {
-    const prepared = await withReviewLock(
-      TUTORIAL_LIFECYCLE_LOCK_KEY,
-      prepareTutorialLocked,
-    );
-
-    return serverJson(200, {
-      ok: true,
-      reviewUuid: prepared.reviewId,
-    });
-  });
-  app.post("/tutorial/open", async () => {
-    return serverJson(
-      200,
-      await withReviewLock(TUTORIAL_LIFECYCLE_LOCK_KEY, openTutorialLocked),
-    );
-  });
-  app.delete("/tutorial", async () => {
-    await withReviewLock(TUTORIAL_LIFECYCLE_LOCK_KEY, deleteTutorialLocked);
-
-    return serverJson(200, { ok: true });
-  });
-
   app.get("/diffr-config", async () =>
     serverJson(200, await readDiffrConfig()),
   );
@@ -517,50 +484,27 @@ export function createGlobalReviewServer(
 
     return serverJson(200, { ok: true });
   });
+  // The harnesses first run connects for the user, instead of asking them
+  // to paste a prompt into each one.
+  app.get("/install/agents", async () =>
+    serverJson(200, { agents: await detectConnectAgents() }),
+  );
+  app.post("/install/connect", async (context) => {
+    const request = ReviewConnectRequestSchema.safeParse(
+      await readBoundedRequestJson(context.req.raw),
+    );
 
-  const httpServer = createServer(createNodeRequestListener(app));
-
-  async function prepareTutorialLocked() {
-    return tutorial.prepare();
-  }
-
-  async function openTutorialLocked(): Promise<ReviewTutorialOpenResponse> {
-    const snapshot = await prepareTutorialLocked();
-
-    return {
-      kind: "api",
-      reviewUuid: snapshot.reviewId,
-      title: snapshot.title,
-    };
-  }
-
-  async function deleteTutorialLocked(): Promise<void> {
-    await tutorial.cleanup();
-  }
-
-  async function withReviewLock<T>(
-    reviewUuid: string,
-    operation: () => Promise<T>,
-  ): Promise<T> {
-    const previous = reviewLocks.get(reviewUuid) ?? Promise.resolve();
-    let release: () => void = () => {};
-
-    const current = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-
-    const chain = previous.then(() => current);
-    reviewLocks.set(reviewUuid, chain);
-    await previous;
+    if (!request.success) throw new ReviewServerError("Invalid agent.", 400);
 
-    try {
-      return await operation();
-    } finally {
-      release();
+    return serverJson(
+      200,
+      await connectAgent(request.data.target, {
+        hasShim: existsSync(pathShimPath()),
+      }),
+    );
+  });
 
-      if (reviewLocks.get(reviewUuid) === chain) reviewLocks.delete(reviewUuid);
-    }
-  }
+  const httpServer = createServer(createNodeRequestListener(app));
 
   return {
     discovery,
@@ -569,6 +513,10 @@ export function createGlobalReviewServer(
     },
     listen: async () => {
       await migrateDiffrConfig();
+      await removeLegacyTutorial({
+        store: reviewStore,
+        data: input.reviewData,
+      });
       scratchpadEnabled = await readScratchpadEnabled();
       boundPort = await listen(httpServer, input.port);
       discovery.url = urlForBoundPort();
@@ -587,8 +535,10 @@ export function createGlobalReviewServer(
       openWatchdog.dispose();
 
       await closeHttpServer(httpServer);
+      await gateway.close();
       await telemetry.shutdown(1_500);
     },
+    setRemoteHosts: (hosts) => gateway.setHosts(hosts),
   };
 }
 

package/src/server/global-verb-relay.ts

@@ -35,6 +35,7 @@ export interface ReviewDesktopVerbRelay {
   dispatch(value: JsonValue): Promise<ReviewVerbResponse>;
   acceptResult(value: JsonValue): boolean;
   close(): void;
+  onAttachedChange(listener: () => void): () => void;
 }
 
 /**
@@ -51,6 +52,7 @@ export class GlobalReviewDesktopVerbRelay implements ReviewDesktopVerbRelay {
   private readonly pending = new Map<string, PendingVerb>();
   private readonly timeoutMs: number;
   private readonly maxClients: number;
+  private readonly attachedListeners = new Set<() => void>();
 
   constructor(options: { timeoutMs?: number; maxClients?: number } = {}) {
     this.timeoutMs = options.timeoutMs ?? DEFAULT_VERB_TIMEOUT_MS;
@@ -73,9 +75,21 @@ export class GlobalReviewDesktopVerbRelay implements ReviewDesktopVerbRelay {
     this.clients.set(writer, detach);
     writer.signal.addEventListener("abort", detach, { once: true });
 
+    if (this.clients.size === 1) this.notifyAttached();
+
     return true;
   }
 
+  onAttachedChange(listener: () => void): () => void {
+    this.attachedListeners.add(listener);
+
+    return () => this.attachedListeners.delete(listener);
+  }
+
+  private notifyAttached(): void {
+    for (const listener of [...this.attachedListeners]) listener();
+  }
+
   dispatch(value: JsonValue): Promise<ReviewVerbResponse> {
     const request: ReviewVerbRequest = parseReviewVerbRequest(value);
 
@@ -170,6 +184,8 @@ export class GlobalReviewDesktopVerbRelay implements ReviewDesktopVerbRelay {
     for (const [id, verb] of [...this.pending]) {
       if (verb.waiting.get(id) === writer) this.stopWaiting(verb, id);
     }
+
+    if (this.clients.size === 0) this.notifyAttached();
   }
 
   /** Drops one client's id; with nobody left to answer, the verb fails. */

package/src/server/headless-host.ts

@@ -1,17 +1,32 @@
+import { spawn } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
 import { once } from "node:events";
+import { existsSync } from "node:fs";
 import { mkdir, realpath, rm } from "node:fs/promises";
 import { createServer } from "node:http";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 
 import { isObjectValue } from "@dev.fast/json";
 import { withFileLock, writePrivateJsonAtomic } from "@dev.fast/trace-core";
+import type { AskAgentLauncher } from "@review/ask/agents.js";
+import { cliAskTools } from "@review/ask/threads.js";
+import { desktopUsesHome } from "@review/desktop-discovery.js";
+import { findReviewPackageRoot } from "@review/package-paths.js";
 import { openReviewProfile } from "@review/review-api/profile.js";
 import {
+  DESKTOP_TAKEOVER_SIGNAL,
   type ReviewServerDiscovery,
+  desktopOwnsHome,
   headlessServerLockPath,
+  readReviewServerDiscovery,
   reviewServerDiscoveryPath,
 } from "@review/server-discovery.js";
 
+import {
+  headlessServerOwner,
+  stopBackgroundServer,
+} from "./background-server.js";
 import { migrateDiffrConfig } from "./diffr-config.js";
 import { GlobalReviewDesktopVerbRelay } from "./global-verb-relay.js";
 import { createNodeRequestListener } from "./hono-http.js";
@@ -26,12 +41,16 @@ interface HeadlessServerInput {
   stateDir: string;
   port?: number;
   softwareMapEnabled?: boolean;
+  startedBy?: ReviewServerDiscovery["startedBy"];
   signal: AbortSignal;
   /** The CLI's instance, already on the `headless` surface. */
   telemetry?: Pick<ReviewTelemetryCapture, "captureUiEvent">;
   onReady(discovery: ReviewServerDiscovery): void;
+  launchAskAgent?: AskAgentLauncher;
 }
 
+export class HeadlessServerBusyError extends Error {}
+
 /** One foreground headless endpoint per profile; Desktop shares its database. */
 export async function runHeadlessServer(input: HeadlessServerInput) {
   await mkdir(input.stateDir, { recursive: true, mode: 0o700 });
@@ -45,7 +64,7 @@ export async function runHeadlessServer(input: HeadlessServerInput) {
   ).finally(() => stopErrorTelemetry?.());
 
   if (!outcome.acquired)
-    throw new Error(
+    throw new HeadlessServerBusyError(
       `A Whiteboard server already owns ${stateDir}. Stop it first, or choose another --state-dir.`,
     );
 }
@@ -70,15 +89,104 @@ export function withHeadlessServerLock<T>(
   );
 }
 
+/**
+ * Desktop owns its home: it stops any server there, then starts under that
+ * server's lock, so none can start until Desktop has published its discovery.
+ */
+export async function takeOverServerHome<T>(
+  home: string,
+  start: () => Promise<T>,
+): Promise<T> {
+  const stateDir = await realpath(home);
+  const deadline = Date.now() + 30_000;
+
+  while (true) {
+    const outcome = await withHeadlessServerLock(stateDir, start);
+
+    if (outcome.acquired) return outcome.result;
+
+    const owner = await headlessServerOwner(stateDir);
+
+    const discovery = await readReviewServerDiscovery(stateDir).catch(
+      () => null,
+    );
+
+    if (owner !== undefined && discovery?.serverPid === owner)
+      await stopBackgroundServer(discovery, DESKTOP_TAKEOVER_SIGNAL);
+    else if (Date.now() > deadline)
+      throw new Error(
+        `Process ${owner} holds the Whiteboard server's lock in ${stateDir} without serving it.`,
+      );
+    else await delay(100);
+  }
+}
+
+const LOGIN_PATH_TIMEOUT_MS = 4_000;
+
+/** Started over ssh, this server has sshd's PATH; agents are on the login
+ * shell's. */
+async function agentEnv(): Promise<NodeJS.ProcessEnv> {
+  const login = process.env.SHELL && (await loginPath(process.env.SHELL));
+
+  return {
+    ...process.env,
+    PATH: [login, process.env.PATH, path.dirname(process.execPath)]
+      .filter(Boolean)
+      .join(path.delimiter),
+  };
+}
+
+function loginPath(shell: string) {
+  return new Promise<string | undefined>((resolve) => {
+    const child = spawn(
+      shell,
+      ["-lic", 'printf "\\nWHITEBOARD-PATH=%s\\n" "$PATH"'],
+      { detached: true, stdio: ["ignore", "pipe", "ignore"] },
+    );
+
+    let output = "";
+
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => (output += chunk));
+
+    const timer = setTimeout(() => {
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {}
+
+      resolve(undefined);
+    }, LOGIN_PATH_TIMEOUT_MS);
+
+    child.once("error", () => {
+      clearTimeout(timer);
+      resolve(undefined);
+    });
+    child.once("close", () => {
+      clearTimeout(timer);
+
+      const found = output
+        .replaceAll("\r", "")
+        .split("\n")
+        .findLast((line) => line.startsWith("WHITEBOARD-PATH="))
+        ?.slice("WHITEBOARD-PATH=".length);
+
+      resolve(found?.startsWith("/") ? found : undefined);
+    });
+  });
+}
+
 async function serve(input: HeadlessServerInput) {
   if (input.signal.aborted) return;
 
+  if (await desktopUsesHome(input.stateDir))
+    throw new HeadlessServerBusyError(desktopOwnsHome(input.stateDir));
+
   await migrateDiffrConfig(input.signal);
 
   if (input.telemetry) await drainServerCrashReport(input.telemetry);
 
   const local = await openReviewProfile(input.stateDir, {
-    manageWorkspaces: false,
+    manageWorkspaces: true,
   });
 
   const discovery: ReviewServerDiscovery = {
@@ -87,11 +195,18 @@ async function serve(input: HeadlessServerInput) {
     url: "http://127.0.0.1:0",
     serverPid: process.pid,
     token: randomBytes(32).toString("base64url"),
+    startedBy: input.startedBy ?? "user",
   };
 
   const relay = new GlobalReviewDesktopVerbRelay();
 
-  const { app, api } = createWhiteboardCore({
+  const cliPath = path.join(
+    findReviewPackageRoot(import.meta.url),
+    "dist",
+    "cli.js",
+  );
+
+  const { app, api, close } = createWhiteboardCore({
     profile: local,
     relay,
     token: discovery.token,
@@ -100,6 +215,14 @@ async function serve(input: HeadlessServerInput) {
     // The scratchpad is the laptop's alone, even with a Desktop attached.
     scratchpad: () => false,
     status: () => ({ key: "headless", home: input.stateDir }),
+    ask: {
+      tools: cliAskTools(() => (existsSync(cliPath) ? cliPath : undefined), {
+        name: "DEV_REVIEW_SERVER_DIR",
+        value: input.stateDir,
+      }),
+      launch: input.launchAskAgent,
+      env: agentEnv(),
+    },
   });
 
   app.route("/reviews-api", api);
@@ -129,6 +252,8 @@ async function serve(input: HeadlessServerInput) {
         input.signal.addEventListener("abort", () => resolve(), { once: true });
     });
   } finally {
+    close();
+
     // Watch streams may live forever. Drain ordinary requests, then bound shutdown.
     const forceClose = setTimeout(() => server.closeAllConnections(), 5_000);
     forceClose.unref();

package/src/server/hono-http.ts

@@ -1,7 +1,11 @@
 import crypto from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
-import { type JsonValue, parseJsonText } from "@dev.fast/review-protocol";
+import {
+  type JsonValue,
+  REVIEW_HOST_HEADER,
+  parseJsonText,
+} from "@dev.fast/review-protocol";
 import { type HttpBindings, getRequestListener } from "@hono/node-server";
 import { REVIEW_APP_SESSION_ID_HEADER } from "@review/ui-telemetry-events";
 import type { Hono } from "hono";
@@ -76,6 +80,7 @@ export function applyCorsHeaders(
     "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS",
   );
   response.headers.set("access-control-allow-private-network", "true");
+  response.headers.set("access-control-expose-headers", REVIEW_HOST_HEADER);
 
   return response;
 }

package/src/server/legacy-tutorial-cleanup.ts

@@ -0,0 +1,38 @@
+import { rm } from "node:fs/promises";
+import path from "node:path";
+
+import type { LocalReviewData } from "@review/review-api/local-data";
+import type { ReviewStore } from "@review/review-api/store";
+import { devReviewHome } from "@review/review-home-paths";
+
+/**
+ * Earlier versions shipped a three-minute tutorial: a managed review over a
+ * sample checkout under ~/.dev/tutorial. Whiteboard no longer has one, so
+ * remove what an earlier version left behind. Best effort: a failure leaves
+ * it for the next start.
+ */
+export async function removeLegacyTutorial(input: {
+  store: ReviewStore;
+  data: LocalReviewData;
+  root?: string;
+}): Promise<void> {
+  const tutorialRoot = input.root ?? path.join(devReviewHome(), "tutorial");
+
+  try {
+    for (const reviewId of input.store.legacyTutorialIds())
+      await input.store.execute({ operation: { type: "delete", reviewId } });
+
+    for (const repository of input.store.repositories()) {
+      const relative = path.relative(tutorialRoot, repository.path);
+
+      if (relative && !relative.startsWith("..") && !path.isAbsolute(relative))
+        await input.data.forgetRepository(repository.id);
+    }
+
+    // Windows cannot delete a checkout while its Git reader or watchers
+    // hold it open, and handles can outlive their close briefly.
+    await rm(tutorialRoot, { recursive: true, force: true, maxRetries: 10 });
+  } catch (error) {
+    console.warn("[Whiteboard] Removing the old tutorial failed:", error);
+  }
+}