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

package/src/server/review-gateway-transport.ts

@@ -0,0 +1,204 @@
+import { Readable } from "node:stream";
+import { setTimeout as delay } from "node:timers/promises";
+
+import {
+  REVIEW_CLIENT_HEADER,
+  REVIEW_CLIENT_REMOTE,
+} from "@dev.fast/review-protocol";
+import { type Dispatcher, request } from "undici";
+import { z } from "zod";
+
+import { StreamLimitError } from "./bounded-stream.js";
+import type { GatewayHosts, GatewayRemote } from "./review-gateway-hosts.js";
+
+export const FIRST_RETRY_MS = 500;
+
+export const MAX_RETRY_MS = 30_000;
+
+export const FIRST_BYTE_TIMEOUT_MS = 10_000;
+
+const NO_ANSWER = `it did not answer within ${FIRST_BYTE_TIMEOUT_MS / 1_000} seconds`;
+
+export const jitter = (ms: number) => ms * (0.75 + Math.random() * 0.5);
+
+const STEADY_MS = 10_000;
+
+const MAX_LINE_CHARS = 64 * 1024 * 1024;
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  delay(ms, undefined, { signal }).catch(() => undefined);
+
+export async function reconnect(
+  signal: AbortSignal,
+  attempt: () => Promise<void>,
+) {
+  let wait = FIRST_RETRY_MS;
+
+  while (!signal.aborted) {
+    const started = Date.now();
+    await attempt();
+
+    if (signal.aborted) return;
+
+    if (Date.now() - started >= STEADY_MS) wait = FIRST_RETRY_MS;
+    await sleep(jitter(wait), signal);
+    wait = Math.min(wait * 2, MAX_RETRY_MS);
+  }
+}
+
+export async function readLines(
+  body: AsyncIterable<Uint8Array>,
+  line: (text: string) => void,
+) {
+  const decoder = new TextDecoder();
+  let pending = "";
+
+  for await (const chunk of body) {
+    pending += decoder.decode(chunk, { stream: true });
+    let end: number;
+
+    while ((end = pending.indexOf("\n")) !== -1) {
+      line(pending.slice(0, end));
+      pending = pending.slice(end + 1);
+    }
+
+    if (pending.length > MAX_LINE_CHARS) throw new Error("A line is too long.");
+  }
+}
+
+export function keepOpen(input: {
+  hosts: GatewayHosts;
+  remote: GatewayRemote;
+  path: string;
+  signal: AbortSignal;
+  read(body: AsyncIterable<Uint8Array>): Promise<void>;
+}) {
+  const { remote, signal } = input;
+
+  void reconnect(signal, async () => {
+    let timedOut = false;
+
+    try {
+      const response = await send(remote, {
+        method: "GET",
+        path: input.path,
+        headers: remoteHeaders(remote),
+        signal,
+      });
+
+      if (response.statusCode === 200) await input.read(response.body);
+      else await response.body.dump();
+    } catch (error) {
+      timedOut = errorCode(error) === "UND_ERR_HEADERS_TIMEOUT";
+    }
+
+    if (signal.aborted) return;
+
+    if (timedOut) input.hosts.failed(remote, NO_ANSWER);
+    else input.hosts.recheck(remote);
+  });
+}
+
+export const remoteHeaders = (remote: GatewayRemote) => ({
+  "x-review-token": remote.endpoint?.token ?? "",
+  [REVIEW_CLIENT_HEADER]: REVIEW_CLIENT_REMOTE,
+});
+
+export async function send(
+  remote: GatewayRemote,
+  input: {
+    method: Dispatcher.HttpMethod;
+    path: string;
+    headers?: Record<string, string>;
+    body?: Buffer | Readable;
+    signal?: AbortSignal;
+    headersTimeout?: number;
+  },
+  retry = true,
+): Promise<Dispatcher.ResponseData> {
+  if (!remote.endpoint) throw new Error(`${remote.alias} has no endpoint.`);
+  let response: Dispatcher.ResponseData;
+
+  try {
+    response = await request(new URL(input.path, remote.endpoint.url), {
+      dispatcher: remote.dispatcher,
+      method: input.method,
+      headers: input.headers,
+      body: input.body,
+      signal: input.signal,
+      headersTimeout: input.headersTimeout ?? FIRST_BYTE_TIMEOUT_MS,
+      bodyTimeout: 0,
+    });
+  } catch (error) {
+    if (
+      retry &&
+      !input.signal?.aborted &&
+      !(input.body instanceof Readable) &&
+      errorCode(error) === "UND_ERR_SOCKET" &&
+      (input.body === undefined || reusedSocket(error))
+    )
+      return send(remote, input, false);
+
+    throw error;
+  }
+
+  if (response.statusCode === 401) remote.unauthorized?.();
+
+  return response;
+}
+
+export async function readBody(
+  body: Dispatcher.ResponseData["body"],
+  limit: number,
+) {
+  const parts: Buffer[] = [];
+  let size = 0;
+
+  for await (const part of body) {
+    // SAFETY: undici's body yields Buffers.
+    const chunk = part as Buffer;
+    size += chunk.byteLength;
+
+    if (size > limit) {
+      body.destroy();
+      throw new StreamLimitError();
+    }
+
+    parts.push(chunk);
+  }
+
+  return Buffer.concat(parts, size);
+}
+
+const codedError = z.object({ code: z.string() });
+
+const socketError = z.object({ socket: z.object({ bytesRead: z.number() }) });
+
+// undici has no reusedSocket; a socket that already read bytes served an earlier response.
+const reusedSocket = (cause: unknown) =>
+  (socketError.safeParse(cause).data?.socket.bytesRead ?? 0) > 0;
+
+const ERROR_WORDS = new Map([
+  ["ECONNREFUSED", "it refused the connection"],
+  ["ECONNRESET", "it closed the connection"],
+  ["UND_ERR_SOCKET", "it closed the connection"],
+  ["EPIPE", "it closed the connection"],
+  ["ETIMEDOUT", "it did not answer"],
+  ["UND_ERR_HEADERS_TIMEOUT", NO_ANSWER],
+]);
+
+export function errorCode(cause: unknown): string {
+  if (!(cause instanceof Error)) return String(cause);
+
+  return (
+    codedError.safeParse(cause).data?.code ??
+    codedError.safeParse(cause.cause).data?.code ??
+    cause.message
+  );
+}
+
+export function errorText(cause: unknown): string {
+  const code = errorCode(cause);
+
+  return ERROR_WORDS.get(code) ?? `it failed (${code})`;
+}

package/src/server/review-gateway.ts

@@ -0,0 +1,433 @@
+import { Readable } from "node:stream";
+import type { ReadableStream as WebReadableStream } from "node:stream/web";
+
+import {
+  REVIEW_CLIENT_HEADER,
+  REVIEW_HOST_HEADER,
+  type ReviewGatewayHost,
+  type ReviewGatewayHostState,
+  parseJsonText,
+} from "@dev.fast/review-protocol";
+import { Hono } from "hono";
+import type { Dispatcher } from "undici";
+import { z } from "zod";
+
+import { StreamLimitError, readBoundedStream } from "./bounded-stream.js";
+import type { ReviewDesktopVerbRelay } from "./global-verb-relay.js";
+import { DEFAULT_MAX_REQUEST_BYTES } from "./http-json.js";
+import {
+  type GatewayRemote,
+  createGatewayHosts,
+} from "./review-gateway-hosts.js";
+import { type ListSource, listedBy } from "./review-gateway-list.js";
+import { UUID, openGatewayMemory } from "./review-gateway-memory.js";
+import { createGatewayPushes } from "./review-gateway-pushes.js";
+import {
+  type Located,
+  createGatewayStreams,
+  downDetail,
+} from "./review-gateway-streams.js";
+import {
+  FIRST_BYTE_TIMEOUT_MS,
+  errorCode,
+  errorText,
+  remoteHeaders,
+  send,
+} from "./review-gateway-transport.js";
+import { serverJson } from "./review-server-core.js";
+
+const LOCAL_ROUTES = new Set([
+  "repositories",
+  "resources",
+  "workspace-cleanup",
+  "authoring",
+  "capabilities",
+  "status",
+  "instructions",
+  "sharing",
+  "commands",
+]);
+
+interface RemoteRoute {
+  method: string;
+  path: string;
+  /** May wait on preparing a checkout or launching an agent. */
+  slow?: true;
+}
+
+const REMOTE_ROUTES: readonly RemoteRoute[] = [
+  { method: "GET", path: "" },
+  { method: "GET", path: "progress" },
+  { method: "POST", path: "progress" },
+  { method: "GET", path: "commits" },
+  { method: "GET", path: "diff" },
+  { method: "GET", path: "structural-diff" },
+  { method: "GET", path: "stack" },
+  { method: "GET", path: "tree" },
+  { method: "GET", path: "file" },
+  { method: "GET", path: "resources/:name" },
+  { method: "GET", path: "maps/:name" },
+  { method: "POST", path: "navigator" },
+  { method: "POST", path: "copy-context" },
+  { method: "GET", path: "language-context", slow: true },
+  { method: "GET", path: "ask/agents" },
+  { method: "GET", path: "ask/agents/:agent/offer", slow: true },
+  { method: "GET", path: "ask/mentions", slow: true },
+  { method: "GET", path: "ask/threads" },
+  { method: "POST", path: "ask/watch" },
+  { method: "GET", path: "ask/:thread" },
+  { method: "POST", path: "ask", slow: true },
+  {
+    method: "POST",
+    path: "ask/:thread/:action{open|choice|permissions}",
+    slow: true,
+  },
+  {
+    method: "POST",
+    path: "ask/:thread/:action{prompt|permission|files|retry|cancel|close}",
+  },
+  { method: "DELETE", path: "ask/:thread" },
+];
+
+const SLOW_ROUTE_TIMEOUT_MS = 120_000;
+
+const LIST_WAIT_MS = 2_000;
+
+const HOP_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "transfer-encoding",
+  "content-length",
+  "te",
+  "trailer",
+  "upgrade",
+]);
+
+const DROPPED_REQUEST_HEADERS = new Set([
+  ...HOP_HEADERS,
+  "host",
+  "origin",
+  "accept-encoding",
+  "cookie",
+  "authorization",
+  "x-review-token",
+  REVIEW_CLIENT_HEADER,
+  REVIEW_HOST_HEADER,
+]);
+
+const commandTarget = z.object({
+  operation: z.object({ reviewId: z.string().optional() }).optional(),
+});
+
+export function createReviewGateway(input: {
+  local(request: Request): Response | Promise<Response>;
+  isLocal(reviewId: string): boolean;
+  version: string;
+  home: string;
+  relay: ReviewDesktopVerbRelay;
+  heartbeatMs?: number;
+  slowRouteMs?: number;
+  restarted?(alias: string): void;
+  log?(message: string): void;
+}) {
+  const log = input.log ?? (() => {});
+  const memory = openGatewayMemory(input.home, log);
+  let changing = false;
+  let closed = false;
+
+  const hosts = createGatewayHosts({
+    version: input.version,
+    log,
+    machine: (serverId, alias) => memory.rename(serverId, alias),
+    ...(input.heartbeatMs !== undefined && { heartbeatMs: input.heartbeatMs }),
+    restarted: (alias) => input.restarted?.(alias),
+    changed() {
+      if (changing) return;
+      changing = true;
+      queueMicrotask(() => {
+        changing = false;
+
+        if (closed) return;
+        const online = new Set(hosts.online());
+
+        for (const [abort, remote] of streaming)
+          if (!online.has(remote)) abort.abort();
+        streams.changed();
+        pushes.changed();
+      });
+    },
+  });
+
+  const streaming = new Map<AbortController, GatewayRemote>();
+  const waiting = new Set<() => void>();
+
+  const lists = (): ListSource => ({
+    states: hosts.states(),
+    serving: (serverId) => hosts.serving(serverId) !== undefined,
+    serverIdOf: memory.serverIdOf,
+    list: memory.list,
+  });
+
+  function locate(reviewId: string): Located {
+    if (!UUID.test(reviewId) || input.isLocal(reviewId)) return "local";
+    const listed = listedBy(reviewId, lists());
+
+    if (!listed) return undefined;
+    const remote = hosts.serving(listed.serverId);
+
+    return remote ? { remote } : { down: listed.state };
+  }
+
+  // A review just created on a host may not be on its list yet.
+  function ownerOf(reviewId: string): Located | Promise<Located> {
+    const located = locate(reviewId);
+
+    if (located !== undefined || !hosts.online().length) return located;
+    const found = Promise.withResolvers<Located>();
+
+    const settle = (owner: Located) => {
+      clearTimeout(timer);
+      waiting.delete(check);
+      found.resolve(owner);
+    };
+
+    const check = () => {
+      const owner = locate(reviewId);
+
+      if (owner !== undefined) settle(owner);
+    };
+
+    const timer = setTimeout(() => settle(undefined), LIST_WAIT_MS);
+    waiting.add(check);
+
+    return found.promise;
+  }
+
+  function answer(
+    alias: string,
+    status: number,
+    body: { ok: boolean; error?: string },
+  ) {
+    const response = serverJson(status, body);
+    response.headers.set(REVIEW_HOST_HEADER, alias);
+
+    return response;
+  }
+
+  function unavailable(down: ReviewGatewayHostState) {
+    return answer(down.alias, 503, { ok: false, error: downDetail(down) });
+  }
+
+  async function forward(
+    remote: GatewayRemote,
+    request: Request,
+    options: { route?: RemoteRoute; body?: Buffer },
+  ): Promise<Response> {
+    const url = new URL(request.url);
+    const { route } = options;
+
+    // The local token never leaves this machine, in a header or the query.
+    if (url.searchParams.has("token")) url.searchParams.delete("token");
+
+    const headers: Record<string, string> = remoteHeaders(remote);
+
+    request.headers.forEach((value, key) => {
+      if (!DROPPED_REQUEST_HEADERS.has(key)) headers[key] = value;
+    });
+
+    const limit = route?.slow
+      ? (input.slowRouteMs ?? SLOW_ROUTE_TIMEOUT_MS)
+      : FIRST_BYTE_TIMEOUT_MS;
+
+    const abort = new AbortController();
+
+    // SAFETY: Node's Request body is its own web stream; the DOM type only
+    // names the same object.
+    const stream = request.body as WebReadableStream | null;
+    let response: Dispatcher.ResponseData;
+
+    try {
+      response = await send(remote, {
+        method: request.method,
+        path: `${url.pathname}${url.search}`,
+        headers,
+        body: options.body ?? (stream ? Readable.fromWeb(stream) : undefined),
+        signal: AbortSignal.any([request.signal, abort.signal]),
+        headersTimeout: limit,
+      });
+    } catch (error) {
+      const timedOut = errorCode(error) === "UND_ERR_HEADERS_TIMEOUT";
+
+      const reason = timedOut
+        ? `it did not answer within ${limit / 1_000} seconds`
+        : errorText(error);
+
+      if (!route?.slow && !request.signal.aborted) hosts.failed(remote, reason);
+
+      return answer(remote.alias, timedOut ? 504 : 502, {
+        ok: false,
+        error: `Could not reach ${remote.alias}: ${reason}.`,
+      });
+    }
+
+    const { statusCode: status } = response;
+    const out = new Headers();
+
+    for (const [key, value] of Object.entries(response.headers))
+      if (
+        value !== undefined &&
+        !HOP_HEADERS.has(key) &&
+        !key.startsWith("access-control-")
+      )
+        out.set(key, Array.isArray(value) ? value.join(", ") : value);
+
+    out.set(REVIEW_HOST_HEADER, remote.alias);
+
+    if (request.method === "HEAD" || status === 204 || status === 304) {
+      await response.body.dump();
+
+      return new Response(null, { status, headers: out });
+    }
+
+    streaming.set(abort, remote);
+    response.body.on("close", () => streaming.delete(abort));
+
+    // SAFETY: Node's Response takes its own web stream; the DOM type only
+    // names the same object.
+    const piped = Readable.toWeb(response.body) as ReadableStream<Uint8Array>;
+
+    return new Response(piped, { status, headers: out });
+  }
+
+  async function command(request: Request): Promise<Response> {
+    if (!request.body) return input.local(request);
+    let body: Buffer;
+
+    try {
+      body = await readBoundedStream(request.body, DEFAULT_MAX_REQUEST_BYTES);
+    } catch (error) {
+      if (!(error instanceof StreamLimitError)) throw error;
+
+      return serverJson(413, {
+        ok: false,
+        error: "Request body exceeds 1 MiB.",
+      });
+    }
+
+    let reviewId: string | undefined;
+
+    try {
+      reviewId = commandTarget.safeParse(parseJsonText(body.toString())).data
+        ?.operation?.reviewId;
+    } catch {}
+
+    const owner = reviewId === undefined ? undefined : await ownerOf(reviewId);
+
+    if (owner === undefined || owner === "local")
+      return input.local(
+        new Request(request.url, {
+          method: request.method,
+          headers: request.headers,
+          body: new Uint8Array(body),
+          signal: request.signal,
+        }),
+      );
+
+    if ("down" in owner) return unavailable(owner.down);
+
+    return forward(owner.remote, request, { body });
+  }
+
+  async function review(
+    request: Request,
+    reviewId: string,
+    route?: RemoteRoute | "telemetry",
+  ): Promise<Response> {
+    if (!reviewId || LOCAL_ROUTES.has(reviewId)) return input.local(request);
+    const owner = await ownerOf(reviewId);
+
+    if (owner === undefined || owner === "local") return input.local(request);
+
+    const alias = "remote" in owner ? owner.remote.alias : owner.down.alias;
+
+    if (route === "telemetry") {
+      await request.body?.cancel();
+
+      return answer(alias, 200, { ok: true });
+    }
+
+    if (!route)
+      return answer(alias, 404, {
+        ok: false,
+        error: "This route is not available for a review on another machine.",
+      });
+
+    if ("down" in owner) return unavailable(owner.down);
+
+    return forward(owner.remote, request, { route });
+  }
+
+  const app = new Hono({ strict: false }).basePath("/reviews-api");
+
+  app.post("/commands", (context) => command(context.req.raw));
+  app.get("/", (context) => streams.list(context.req.raw));
+  app.get("/watch", (context) => streams.watch(context.req.raw));
+  app.all("/:id/telemetry/*", (context) =>
+    review(context.req.raw, context.req.param("id"), "telemetry"),
+  );
+
+  for (const route of REMOTE_ROUTES)
+    app.on(route.method, `/:id${route.path && `/${route.path}`}`, (context) =>
+      review(context.req.raw, context.req.param("id") ?? "", route),
+    );
+
+  for (const path of ["/:id", "/:id/*"])
+    app.all(path, (context) =>
+      review(context.req.raw, context.req.param("id") ?? ""),
+    );
+
+  app.all("*", (context) => input.local(context.req.raw));
+
+  const streams = createGatewayStreams({
+    hosts,
+    memory,
+    local: input.local,
+    lists,
+    locate,
+    listed() {
+      for (const check of waiting) check();
+    },
+  });
+
+  async function claim(remote: GatewayRemote, reviewId: string) {
+    if ((await ownerOf(reviewId)) === undefined)
+      return `${reviewId} is not on ${remote.alias}'s list.`;
+  }
+
+  const pushes = createGatewayPushes({
+    hosts,
+    relay: input.relay,
+    claim,
+    log,
+  });
+
+  const stopWatchingWindows = input.relay.onAttachedChange(() => {
+    if (!closed) pushes.changed();
+  });
+
+  return {
+    fetch: (request: Request) => app.fetch(request),
+    setHosts: (list: ReviewGatewayHost[]) => hosts.set(list),
+    hosts: () => hosts.states(),
+    async close() {
+      closed = true;
+      stopWatchingWindows();
+      streams.close();
+      pushes.close();
+      hosts.close();
+      await memory.flush();
+    },
+  };
+}
+
+export type ReviewGateway = ReturnType<typeof createReviewGateway>;

package/src/server/review-server-core.ts

@@ -4,7 +4,12 @@ import type {
   ReviewServerHealthWithToken,
 } from "@dev.fast/review-protocol";
 import { traceMachineEnabled } from "@dev.fast/trace-core";
-import { detectAskAgents, launchAskAgent } from "@review/ask/agents.js";
+import {
+  type AskAgentLauncher,
+  askAgentTakesMcp,
+  detectAskAgents,
+  launchAskAgent,
+} from "@review/ask/agents.js";
 import { AskThreads, type AskTools } from "@review/ask/threads.js";
 import {
   readBuildCommit,
@@ -94,6 +99,12 @@ export function createReviewServerApp(input: {
 
     return serverJson(accepted ? 200 : 404, { ok: accepted });
   });
+  answerErrorsAsJson(app);
+
+  return app;
+}
+
+export function answerErrorsAsJson(app: Hono<ReviewHonoEnv>) {
   app.notFound(() => serverJson(404, { ok: false, error: "Not found." }));
   app.onError((error) => {
     const serverError = error instanceof ReviewServerError ? error : undefined;
@@ -107,8 +118,6 @@ export function createReviewServerApp(input: {
         : { ok: false, error: message },
     );
   });
-
-  return app;
 }
 
 export interface WhiteboardCoreInput {
@@ -124,7 +133,13 @@ export interface WhiteboardCoreInput {
   scratchpad: () => boolean;
   status: () => JsonObject;
   hooks?: ReviewApiHooks;
-  ask?: { tools: AskTools };
+  ask?: {
+    tools: AskTools;
+    /** Tests only: an in-process agent. */
+    launch?: AskAgentLauncher;
+    /** Where agents are found, and the environment they run in. */
+    env?: Promise<NodeJS.ProcessEnv>;
+  };
 }
 
 export function createWhiteboardCore(input: WhiteboardCoreInput) {
@@ -139,8 +154,20 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
 
   const callbacks = relayReviewCallbacks(input.relay, input.softwareMapEnabled);
 
+  const { ask } = input;
+
+  const launch = ask?.launch ?? launchAskAgent;
+
   const askThreads =
-    input.ask && new AskThreads(launchAskAgent, input.ask.tools);
+    ask &&
+    new AskThreads(
+      async (agent, cwd, options) =>
+        launch(agent, cwd, { ...options, env: await ask.env }),
+      {
+        takesMcp: async (agent) => askAgentTakesMcp(agent, await ask.env),
+        ...ask.tools,
+      },
+    );
 
   const closeDeletedThreads = () =>
     askThreads?.closeDeletedReviews((id) =>
@@ -167,7 +194,10 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
     () => traceMachineEnabled(),
     input.status,
     input.hooks,
-    askThreads && { threads: askThreads, agents: () => detectAskAgents() },
+    askThreads && {
+      threads: askThreads,
+      agents: async () => detectAskAgents(await ask?.env),
+    },
   );
 
   // A shared store mounts the publisher with the rest of sharing.