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

package/src/review-api/http.ts

@@ -1,9 +1,10 @@
-import { createHash } from "node:crypto";
-
 import { type JsonObject, isJsonObject } from "@dev.fast/json";
 import {
   REVIEW_CLIENT_HEADER,
   REVIEW_CLIENT_REMOTE,
+  type ReviewRemoteLanguageEnvironment,
+  type ReviewRemoteNavigatorAnswer,
+  type ReviewStreamLine,
   type ReviewStructuralDiffEvent,
 } from "@dev.fast/review-protocol";
 import { errorMessage } from "@dev.fast/trace-core";
@@ -12,7 +13,11 @@ import {
   AgentSelectionSchema,
   selectionMarkdown,
 } from "@review/agent-selection.js";
-import { type AskAgentStatus, askAgents } from "@review/ask/agents.js";
+import {
+  type AskAgentStatus,
+  askAgents,
+  defaultAskPermissions,
+} from "@review/ask/agents.js";
 import { checkoutFiles, mentionableFiles } from "@review/ask/checkout-files.js";
 import { parseFileRef, resolveFileRefs } from "@review/ask/file-refs.js";
 import {
@@ -20,9 +25,11 @@ import {
   type AskThreadState,
   askAgentIds,
   askChoiceKinds,
+  askPermissionsSchema,
   askPicksSchema,
   askQuestionSchema,
 } from "@review/ask/thread-state.js";
+import type { AskThreadHooks } from "@review/ask/thread.js";
 import type { AskThreads } from "@review/ask/threads.js";
 import { watchAskThreads } from "@review/ask/watch.js";
 import { fuzzyRank } from "@review/fuzzy-match.js";
@@ -41,6 +48,7 @@ import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 
 import { anchorQuotes } from "./anchor-quotes.js";
+import type { AskRecord } from "./ask-history.js";
 import { authoringTools } from "./authoring-tools.js";
 import { documentText } from "./document-text.js";
 import { ReviewInputError } from "./document.js";
@@ -50,6 +58,7 @@ import {
   scratchpadAvailable,
 } from "./instructions.js";
 import type { LocalReviewData } from "./local-data.js";
+import { registerOnboardingRoutes } from "./onboarding.js";
 import {
   inspectQuerySchema,
   queryAnchor,
@@ -86,10 +95,10 @@ const askStartSchema = z.strictObject({
   question: askQuestionSchema,
   selection: AgentSelectionSchema,
   picks: askPicksSchema.optional(),
-  bypass: z.boolean().optional(),
+  permissions: askPermissionsSchema.optional(),
 });
 
-const askPermitSchema = z.strictObject({ bypass: z.boolean() });
+const askPermitSchema = z.strictObject({ permissions: askPermissionsSchema });
 
 /** The threads one watch follows: those of a review's open Asks. A body,
  * not the query, so there can be as many as are open. */
@@ -155,10 +164,6 @@ export interface ReviewApiHooks {
   sharing?: SharingHostEvents;
 }
 
-/** A gateway forwarding from another machine; it gets no local paths. */
-const remoteCaller = (context: Context) =>
-  context.req.header(REVIEW_CLIENT_HEADER) === REVIEW_CLIENT_REMOTE;
-
 /** Both hosts mount this behind their token authentication. */
 export function createReviewApi(
   store: ReviewStore,
@@ -509,121 +514,123 @@ export function createReviewApi(
         );
       },
     );
-  app.get("/watch", async (context) => {
-    const query = context.req.query("subscriptions");
+  app.get("/watch", (context) => {
+    let input: unknown;
+
+    try {
+      input = JSON.parse(context.req.query("subscriptions") ?? "");
+    } catch {
+      throw new ReviewInputError("Invalid subscriptions.");
+    }
+
+    const subscriptions = z
+      .array(
+        z.strictObject({
+          reviewId: z.string().min(1).nullable(),
+          mode: coverageModeSchema,
+        }),
+      )
+      .parse(input);
+
+    const modes = new Set(
+      subscriptions.flatMap((item) =>
+        item.reviewId === null ? [item.mode] : [],
+      ),
+    );
 
-    if (query !== undefined) {
-      let input: unknown;
+    const reviewIds = new Set(
+      subscriptions.flatMap((item) => item.reviewId ?? []),
+    );
+
+    const dirtyModes = new Set(modes);
+    const dirtyReviews = new Set(reviewIds);
+    const sentLists = new Map<string, string>();
 
+    const readReviewLine = (reviewId: string): ReviewStreamLine<Snapshot> => {
       try {
-        input = JSON.parse(query);
-      } catch {
-        throw new ReviewInputError("Invalid subscriptions.");
+        return {
+          kind: "review",
+          reviewId,
+          value: {
+            ...readReview(reviewId),
+            activity: store.activity.read(reviewId),
+            coverageRevision: data?.coverageRevision ?? 0,
+          },
+        };
+      } catch (error) {
+        return {
+          kind: "review",
+          reviewId,
+          error:
+            error instanceof ReviewInputError
+              ? error.message
+              : "Could not read review.",
+        };
       }
+    };
 
-      const subscriptions = z
-        .array(
-          z.strictObject({
-            reviewId: z.string().min(1).nullable(),
-            mode: coverageModeSchema,
-          }),
-        )
-        .parse(input);
+    const lines = () => {
+      const pending: string[] = [];
 
-      // Only entries whose review (or the catalog) changed are re-read and re-sent.
-      const dirty = new Set(subscriptions.keys());
+      for (const mode of dirtyModes) {
+        const line = JSON.stringify({
+          kind: "list",
+          mode,
+          reviews: catalog(mode),
+        } satisfies ReviewStreamLine);
 
-      const mark = (id: string | null) => {
-        let marked = false;
+        if (sentLists.get(mode) !== line) pending.push(line);
+        sentLists.set(mode, line);
+      }
 
-        subscriptions.forEach((item, index) => {
-          if (item.reviewId === id) {
-            dirty.add(index);
-            marked = true;
-          }
-        });
+      for (const reviewId of dirtyReviews)
+        pending.push(JSON.stringify(readReviewLine(reviewId)));
 
-        return marked;
-      };
+      dirtyModes.clear();
+      dirtyReviews.clear();
 
-      return watch(
-        () =>
-          subscriptions.map(({ reviewId, mode }, index) => {
-            if (!dirty.delete(index)) return null;
-
-            try {
-              return {
-                value:
-                  reviewId === null
-                    ? catalog(mode)
-                    : {
-                        ...readReview(reviewId),
-                        activity: store.activity.read(reviewId),
-                        coverageRevision: data?.coverageRevision ?? 0,
-                      },
-              };
-            } catch (error) {
-              return {
-                error:
-                  error instanceof ReviewInputError
-                    ? error.message
-                    : "Could not read review.",
-              };
-            }
-          }),
-        (notify) => {
-          const stopRefresh = store.watchWorktrees();
-
-          const stops = [
-            stopRefresh,
-            data?.subscribeCoverage(() => {
-              subscriptions.forEach((item, index) => {
-                if (item.reviewId !== null) dirty.add(index);
-              });
-
-              // Coverage never changes the catalog; don't send an all-null line.
-              if (dirty.size > 0) notify();
-            }) ?? (() => {}),
-            store.subscribe((result) => {
-              if (mark(result.reviewId)) notify();
-            }),
-            store.activity.subscribe((id) => {
-              if (mark(id)) notify();
-            }),
-            store.activity.subscribeWorking(() => {
-              if (mark(null)) notify();
-            }),
-            shared?.subscribe(() => {
-              if (mark(null)) notify();
-            }) ?? (() => {}),
-            store.subscribeCatalog(() => {
-              if (mark(null)) notify();
-            }),
-          ];
+      return pending;
+    };
 
-          return () => stops.forEach((stop) => stop());
-        },
-        // A missing review is an {error} entry here, never a 404.
-        () => {},
-      );
-    }
+    const markReview = (reviewId: string) => {
+      if (!reviewIds.has(reviewId)) return false;
+      dirtyReviews.add(reviewId);
 
-    await ensureScratchpad();
+      return true;
+    };
 
-    return watch(
-      () => catalog(coverageModeSchema.parse(context.req.query("mode"))),
-      (notify) => {
-        const local = store.subscribeCatalog(notify);
-        const activity = store.activity.subscribeWorking(notify);
-        const imported = shared?.subscribe(notify);
-
-        return () => {
-          local();
-          activity();
-          imported?.();
-        };
-      },
-    );
+    const markLists = () => {
+      modes.forEach((mode) => dirtyModes.add(mode));
+
+      return modes.size > 0;
+    };
+
+    return watch(lines, (notify) => {
+      const stops = [
+        store.watchWorktrees(),
+        data?.subscribeCoverage(() => {
+          reviewIds.forEach((id) => dirtyReviews.add(id));
+          notify();
+        }) ?? (() => {}),
+        store.subscribe((result) => {
+          if (markReview(result.reviewId)) notify();
+        }),
+        store.activity.subscribe((id) => {
+          if (markReview(id)) notify();
+        }),
+        store.activity.subscribeWorking(() => {
+          if (markLists()) notify();
+        }),
+        shared?.subscribe(() => {
+          if (markLists()) notify();
+        }) ?? (() => {}),
+        store.subscribeCatalog(() => {
+          if (markLists()) notify();
+        }),
+      ];
+
+      return () => stops.forEach((stop) => stop());
+    });
   });
 
   /** Show a review in Desktop and start preparing its pinned checkouts. */
@@ -684,41 +691,6 @@ export function createReviewApi(
 
     return context.json({ ok: true, ...(await openReview(readReview(id))) });
   });
-  app.get("/:id/watch", (context) => {
-    const id = context.req.param("id");
-
-    // Activity changes every renewal; reload the document only when it changed.
-    let document: Snapshot | undefined;
-
-    return watch(
-      () => ({
-        ...(document ??= readReview(id)),
-        activity: isShared(id)
-          ? { workingCount: 0, expiresAt: null }
-          : store.activity.read(id),
-      }),
-      (notify) => {
-        const stopRefresh = store.watchWorktrees();
-
-        const stopDocument = store.subscribe((result) => {
-          if (result.reviewId === id) {
-            document = undefined;
-            notify();
-          }
-        });
-
-        const stopActivity = store.activity.subscribe((changed) => {
-          if (changed === id) notify();
-        });
-
-        return () => {
-          stopRefresh();
-          stopDocument();
-          stopActivity();
-        };
-      },
-    );
-  });
 
   if (data) {
     const traceQuery = readQuerySchemas.maps.extend({
@@ -768,12 +740,6 @@ export function createReviewApi(
       return context.json(result);
     });
     app.post("/:id/navigator", reviewAccess("edit"), async (context) => {
-      if (remoteCaller(context))
-        throw new ReviewInputError(
-          "Source windows are not available for a review on another machine.",
-          409,
-        );
-
       const input = readQuerySchemas.file
         .extend({
           side: z.enum(["base", "head"]).default("head"),
@@ -782,16 +748,24 @@ export function createReviewApi(
         })
         .parse(context.req.query());
 
-      return context.json(
-        await data.navigatorWorkspace(
-          readReview(context.req.param("id"), input.version),
-          {
-            ...input,
-            empty: input.empty === "true",
-            anchor: queryAnchor(input),
-          },
-        ),
+      const answer = await data.navigatorWorkspace(
+        readReview(context.req.param("id"), input.version),
+        {
+          ...input,
+          empty: input.empty === "true",
+          anchor: queryAnchor(input),
+        },
       );
+
+      if (context.req.header(REVIEW_CLIENT_HEADER) !== REVIEW_CLIENT_REMOTE)
+        return context.json(answer);
+
+      return context.json({
+        ...(input.empty === "true"
+          ? { workspacePath: answer.workspacePath, emptySide: true }
+          : answer),
+        serverId: store.serverId(),
+      } satisfies ReviewRemoteNavigatorAnswer);
     });
     app.get("/:id/tree", async (context) => {
       const input = readQuerySchemas.tree.parse(context.req.query());
@@ -884,21 +858,17 @@ export function createReviewApi(
         queryAnchor(input),
       );
 
-      return context.json(
-        remoteCaller(context)
-          ? {
-              // A live checkout's identity names its path; keep only its equality.
-              identity: createHash("sha256")
-                .update(environment.identity)
-                .digest("hex"),
-              // An acquisition error can quote local paths.
-              ...(environment.issue && {
-                issue:
-                  "The checkout for language features is not available on the remote machine.",
-              }),
-            }
-          : environment,
-      );
+      if (context.req.header(REVIEW_CLIENT_HEADER) !== REVIEW_CLIENT_REMOTE)
+        return context.json(environment);
+
+      // The laptop opens a remote root on this server, so it needs the server id.
+      const { rootPath, ...rest } = environment;
+
+      return context.json({
+        ...rest,
+        remoteRootPath: rootPath ?? null,
+        serverId: store.serverId(),
+      } satisfies ReviewRemoteLanguageEnvironment);
     });
     app.post("/:id/environment", reviewAccess("active"), async (context) => {
       const input = z
@@ -972,7 +942,6 @@ export function createReviewApi(
       }
 
       const local =
-        !remoteCaller(context) &&
         !input.commit &&
         !anchor &&
         input.side === "head" &&
@@ -1013,7 +982,7 @@ export function createReviewApi(
           } catch (error) {
             send({
               type: "error",
-              message: error instanceof Error ? error.message : String(error),
+              message: errorMessage(error),
             });
           } finally {
             if (!abort.signal.aborted) controller.close();
@@ -1131,7 +1100,9 @@ export function createReviewApi(
     );
 
     return [
-      `Selected ${target.kind === "text" ? "text" : "code"} from Whiteboard: ${snapshot.title}`,
+      target.kind === "review"
+        ? `Whiteboard: ${snapshot.title}`
+        : `Selected ${target.kind === "text" ? "text" : "code"} from Whiteboard: ${snapshot.title}`,
       `Session ID: ${snapshot.reviewId}`,
       `Version: ${snapshot.version}`,
       ...(selection.apiSource?.commit
@@ -1171,20 +1142,80 @@ export function createReviewApi(
       return thread;
     };
 
+    /** Where a thread in a review saves itself: its Ask history, recorded
+     * once the agent has a session to reopen. */
+    const historyHooks = (
+      record: Omit<AskRecord, "sessionId">,
+    ): AskThreadHooks => ({
+      onSession: (sessionId) =>
+        store.askHistory.get(record.id)
+          ? store.askHistory.updateSession(record.id, sessionId)
+          : store.askHistory.save({ ...record, sessionId }),
+      onTurn: () => store.askHistory.touch(record.id),
+      onSave: (entries) => store.askHistory.saveEntries(record.id, entries),
+      onPermissions: (permissions) =>
+        store.askHistory.setPermissions(record.id, permissions),
+      onOffer: (offer) => store.askHistory.saveOffer(record.agent, offer),
+      onTitle: (title) => store.askHistory.rename(record.id, title),
+    });
+
+    /** Threads started for a review before its canvas opened, for it to
+     * show once it does. */
+    const handedOff = new Map<string, string[]>();
+
+    const handOff = (reviewId: string, threadId: string) =>
+      handedOff.set(reviewId, [...(handedOff.get(reviewId) ?? []), threadId]);
+
+    // The conversations started for this review since its canvas last asked,
+    // to open in its Ask panel.
+    app.post("/:id/ask/handoff", (context) => {
+      const reviewId = context.req.param("id");
+      const ids = handedOff.get(reviewId) ?? [];
+
+      handedOff.delete(reviewId);
+
+      return context.json({
+        threads: ids.flatMap((id) => {
+          const record = store.askHistory.get(id);
+
+          if (record)
+            return [{ id, agent: record.agent, selection: record.selection }];
+
+          // Its agent has no session to save yet, but the thread is live.
+          const live = ask.threads.get(id);
+
+          if (live?.reviewId !== reviewId) return [];
+          const state = live.read();
+
+          return [
+            {
+              id,
+              agent: state.agent,
+              selection: {
+                target: { kind: "review" as const },
+                title: state.selection.title,
+              },
+            },
+          ];
+        }),
+      });
+    });
+
     /** What an agent reads before a session's first question: the review,
      * the checkout, and the selection. */
     const askContext = async (
+      threadId: string,
       agent: AskAgentId,
       snapshot: Snapshot,
       checkout: { head: string; live: boolean },
       selection: AgentSelection,
       version: number | undefined,
     ) => {
-      const reach = await ask.threads.reach(agent);
+      const reach = await ask.threads.reach(agent, threadId);
       const { reviewId } = snapshot;
 
       return [
-        `A reviewer is reading "${snapshot.title}" in Whiteboard and has a question about a selection.`,
+        `A reviewer is reading "${snapshot.title}" in Whiteboard and has a question about ${selection.target.kind === "review" ? "it" : "a selection"}.`,
         checkout.live
           ? "Your working directory is the repository the review describes."
           : `Your working directory is a checkout of the review's head commit, ${checkout.head}. Answer from this code, not from other branches.`,
@@ -1204,6 +1235,13 @@ export function createReviewApi(
       ].join("\n");
     };
 
+    registerOnboardingRoutes(app, store, ask, {
+      register: (root) => data.register(root),
+      historyHooks,
+      handOff,
+      open: openCreated,
+    });
+
     // The agents answering in any review, which quitting the app would stop.
     app.get("/ask/working", (context) =>
       context.json({ agents: ask.threads.working() }),
@@ -1291,7 +1329,11 @@ export function createReviewApi(
       const id = crypto.randomUUID();
       const createdAt = new Date().toISOString();
 
+      const permissions =
+        input.permissions ?? defaultAskPermissions(input.agent);
+
       const initialContext = await askContext(
+        id,
         input.agent,
         snapshot,
         checkout,
@@ -1307,30 +1349,21 @@ export function createReviewApi(
         agent: input.agent,
         // Saved once the agent has a session to reopen; a later one
         // replaces a session the agent could not reopen.
-        onSession: (sessionId) =>
-          store.askHistory.get(id)
-            ? store.askHistory.updateSession(id, sessionId)
-            : store.askHistory.save({
-                id,
-                reviewId,
-                agent: input.agent,
-                sessionId,
-                version: snapshot.version,
-                head: checkout.head,
-                cwd: checkout.rootPath,
-                selection: input.selection,
-                title: input.question.text.slice(0, 200),
-                createdAt,
-                updatedAt: createdAt,
-                bypass: input.bypass,
-              }),
-        onTurn: () => store.askHistory.touch(id),
-        onSave: (entries) => store.askHistory.saveEntries(id, entries),
+        ...historyHooks({
+          id,
+          reviewId,
+          agent: input.agent,
+          version: snapshot.version,
+          head: checkout.head,
+          cwd: checkout.rootPath,
+          selection: input.selection,
+          title: input.question.text.slice(0, 200),
+          createdAt,
+          updatedAt: createdAt,
+          permissions,
+        }),
         picks: input.picks,
-        bypass: input.bypass,
-        onBypass: (bypass) => store.askHistory.setBypass(id, bypass),
-        onOffer: (offer) => store.askHistory.saveOffer(input.agent, offer),
-        onTitle: (title) => store.askHistory.rename(id, title),
+        permissions,
         cwd: checkout.rootPath,
         head: checkout.head,
         selection: {
@@ -1391,7 +1424,7 @@ export function createReviewApi(
         agentName: askAgents[record.agent].name,
         status: "idle",
         readOnly: true,
-        bypass: false,
+        permissions: record.permissions ?? "read-only",
         head: record.head,
         cwd: record.cwd,
         title: record.title,
@@ -1428,6 +1461,7 @@ export function createReviewApi(
         const target = record.selection.target;
 
         const initialContext = await askContext(
+          record.id,
           record.agent,
           snapshot,
           checkout,
@@ -1449,15 +1483,9 @@ export function createReviewApi(
           resume: { sessionId: record.sessionId, entries: record.entries },
           // For a new session, should the agent no longer have this one.
           context: initialContext,
-          onSession: (sessionId) =>
-            store.askHistory.updateSession(record.id, sessionId),
-          onTurn: () => store.askHistory.touch(record.id),
-          onSave: (entries) => store.askHistory.saveEntries(record.id, entries),
+          ...historyHooks(record),
           picks,
-          bypass: record.bypass,
-          onBypass: (bypass) => store.askHistory.setBypass(record.id, bypass),
-          onOffer: (offer) => store.askHistory.saveOffer(record.agent, offer),
-          onTitle: (title) => store.askHistory.rename(record.id, title),
+          permissions: record.permissions,
         });
 
         return context.json({ threadId: record.id });
@@ -1575,7 +1603,7 @@ export function createReviewApi(
       },
     );
 
-    // Bypasses permissions from the next answer, or stops.
+    // Changes what the agent may do from the next answer.
     app.post(
       "/:id/ask/:threadId/permissions",
       reviewAccess("edit"),
@@ -1585,7 +1613,7 @@ export function createReviewApi(
           context.req.param("threadId"),
         );
 
-        const { bypass } = askPermitSchema.parse(
+        const { permissions } = askPermitSchema.parse(
           await readBoundedRequestJson(context.req.raw),
         );
 
@@ -1596,7 +1624,7 @@ export function createReviewApi(
           );
 
         try {
-          await thread.permit(bypass);
+          await thread.permit(permissions);
         } catch (error) {
           throw new ReviewInputError(errorMessage(error), 409);
         }
@@ -1670,7 +1698,13 @@ export function createReviewApi(
     const snapshot = readReview(id, query.version);
 
     if (isShared(id) || !snapshot.pins) return context.json({ layers: [] });
-    const layers = await resolveReviewStackLayers(snapshot, store.list());
+
+    const layers = await resolveReviewStackLayers(snapshot, store.list(), {
+      repositoryPath: store
+        .repositories()
+        .find((repository) => repository.id === snapshot.pins!.repositoryId)
+        ?.path,
+    });
 
     return context.json({ layers });
   });
@@ -1962,35 +1996,23 @@ async function locateRepositories(
   };
 }
 
-/** Send committed state, coalescing updates when the reader falls behind. */
-function watch<T>(
-  read: () => T,
+function watch(
+  lines: () => string[],
   subscribe: (notify: () => void) => () => void,
-  probe: () => void = read,
 ) {
-  probe(); // Return a normal 404 before opening the response.
   let stop = () => {};
 
-  let dirty = true;
   const encoder = new TextEncoder();
 
   const send = (controller: ReadableStreamDefaultController<Uint8Array>) => {
-    if (
-      !dirty ||
-      controller.desiredSize === null ||
-      controller.desiredSize <= 0
-    )
-      return;
+    if (controller.desiredSize === null || controller.desiredSize <= 0) return;
 
     try {
-      const line = JSON.stringify(read()) + "\n";
+      const pending = lines();
 
-      // enqueue can pull synchronously; clear first so it doesn't resend.
-      dirty = false;
-      controller.enqueue(encoder.encode(line));
+      if (pending.length)
+        controller.enqueue(encoder.encode(pending.join("\n") + "\n"));
     } catch (error) {
-      // A review can be deleted while this stream is open. Do not throw into
-      // the already-committed writer; close this reader and unsubscribe it.
       stop();
       controller.error(error);
     }
@@ -1998,9 +2020,15 @@ function watch<T>(
 
   const body = new ReadableStream<Uint8Array>({
     start(controller) {
+      let scheduled = false;
+
       stop = subscribe(() => {
-        dirty = true;
-        send(controller);
+        if (scheduled) return;
+        scheduled = true;
+        queueMicrotask(() => {
+          scheduled = false;
+          send(controller);
+        });
       });
       send(controller);
     },