@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/review-api/activity.ts

@@ -0,0 +1,340 @@
+import { randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+import { z } from "zod";
+
+import { ReviewInputError } from "./document.js";
+
+const focusSchema = z.strictObject({
+  description: z.string().trim().min(1).max(160),
+  targetId: z.string().min(1).optional(),
+});
+
+/** Which page an agent last wrote on, so the app knows where its courier is. */
+export type ActivitySurface = "document" | "lenses";
+
+// One schema per action, so each agent tool states exactly what it needs.
+export const activityBeginSchema = z.strictObject({
+  focus: focusSchema.nullable().optional(),
+});
+
+export const activityUpdateSchema = z.strictObject({
+  activityId: z.string().min(1),
+  focus: focusSchema.nullable().optional(),
+});
+
+export const activityEndSchema = z.strictObject({
+  activityId: z.string().min(1),
+});
+
+export const activitySchema = z.discriminatedUnion("action", [
+  activityBeginSchema.extend({ action: z.literal("begin") }),
+  activityUpdateSchema.extend({ action: z.literal("update") }),
+  activityEndSchema.extend({ action: z.literal("end") }),
+]);
+
+export type ActivityFocus = z.infer<typeof focusSchema>;
+
+/** One agent working on a review. */
+export interface ActivityPresence {
+  activityId: string;
+  /** The agent's color: the lowest slot free when it began, kept until it ends. */
+  slot: number;
+  focus?: ActivityFocus;
+  /** Where it last wrote; absent until its first attributed write. */
+  surface?: ActivitySurface;
+}
+
+export interface ActivitySnapshot {
+  /** Live presences. */
+  workingCount: number;
+  /** The latest expiry among live presences. */
+  expiresAt: number | null;
+  /** Each live presence, in the order they began. */
+  activities?: ActivityPresence[];
+}
+
+// A presence lasts until end, or three minutes without an attributed write or
+// an update, so a crashed agent stops showing within that long.
+export const ACTIVITY_TTL_MS = 180_000;
+
+export class ReviewActivity {
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly listeners = new Set<(reviewId: string) => void>();
+  private readonly working = new Set<string>();
+  private readonly workingListeners = new Set<() => void>();
+
+  constructor(
+    private readonly db: DatabaseSync,
+    private readonly assertReview?: (reviewId: string) => void,
+  ) {
+    // Presences replace the per-scope leases; both last minutes, so the old
+    // table is dropped rather than migrated.
+    db.exec(`CREATE TABLE IF NOT EXISTS authoring_presences(
+      activity_id TEXT PRIMARY KEY, review_id TEXT NOT NULL, slot INTEGER NOT NULL,
+      started_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, focus TEXT, surface TEXT);
+      DROP TABLE IF EXISTS authoring_sessions;`);
+
+    for (const row of db
+      .prepare(
+        "SELECT DISTINCT review_id FROM authoring_presences WHERE expires_at>?",
+      )
+      .all(Date.now())) {
+      this.working.add(String(row.review_id));
+      this.scheduleExpiry(String(row.review_id));
+    }
+  }
+  subscribe(listener: (reviewId: string) => void) {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Fires only when a review starts or stops being authored, never on
+   * renewals or focus changes. */
+  subscribeWorking(listener: () => void) {
+    this.workingListeners.add(listener);
+
+    return () => {
+      this.workingListeners.delete(listener);
+    };
+  }
+  isWorking(reviewId: string) {
+    return this.working.has(reviewId);
+  }
+  private changed(reviewId: string) {
+    const working =
+      this.db
+        .prepare(
+          "SELECT 1 FROM authoring_presences WHERE review_id=? AND expires_at>? LIMIT 1",
+        )
+        .get(reviewId, Date.now()) !== undefined;
+
+    if (working !== this.working.has(reviewId)) {
+      if (working) this.working.add(reviewId);
+      else this.working.delete(reviewId);
+
+      for (const notify of this.workingListeners) notify();
+    }
+
+    for (const notify of this.listeners) notify(reviewId);
+  }
+  private live(reviewId: string) {
+    return this.db
+      .prepare(
+        "SELECT activity_id,slot,expires_at,focus,surface FROM authoring_presences WHERE review_id=? AND expires_at>? ORDER BY rowid",
+      )
+      .all(reviewId, Date.now());
+  }
+
+  read(reviewId: string): ActivitySnapshot {
+    const live = this.live(reviewId);
+
+    const snapshot: ActivitySnapshot = {
+      workingCount: live.length,
+      expiresAt: live.length
+        ? Math.max(...live.map((row) => Number(row.expires_at)))
+        : null,
+    };
+
+    if (live.length)
+      snapshot.activities = live.map((row) => {
+        const presence: ActivityPresence = {
+          activityId: String(row.activity_id),
+          slot: Number(row.slot),
+        };
+
+        if (row.focus)
+          presence.focus = focusSchema.parse(JSON.parse(String(row.focus)));
+
+        if (row.surface === "document" || row.surface === "lenses")
+          presence.surface = row.surface;
+
+        return presence;
+      });
+
+    return snapshot;
+  }
+
+  /** Inside the caller's write transaction: the presence a write belongs to,
+   * renewed and moved to the write's surface. The named one if it is live;
+   * otherwise, with none named, the review's only presence. A write is never
+   * refused for this. Call `extended` once the transaction commits. */
+  attribute(
+    reviewId: string,
+    surface: ActivitySurface,
+    activityId?: string,
+  ): string | undefined {
+    const live = this.live(reviewId);
+
+    const owner =
+      activityId === undefined
+        ? live.length === 1
+          ? String(live[0]!.activity_id)
+          : undefined
+        : live.some((row) => row.activity_id === activityId)
+          ? activityId
+          : undefined;
+
+    if (owner === undefined) return undefined;
+    this.db
+      .prepare(
+        "UPDATE authoring_presences SET expires_at=?,surface=? WHERE activity_id=?",
+      )
+      .run(Date.now() + ACTIVITY_TTL_MS, surface, owner);
+
+    return owner;
+  }
+
+  /** Move the expiry timer after a committed `attribute`. */
+  extended(reviewId: string) {
+    this.scheduleExpiry(reviewId);
+    this.changed(reviewId);
+  }
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Activity boundary: activitySchema.parse below validates incoming JSON.
+  update(reviewId: string, value: unknown) {
+    const input = activitySchema.parse(value);
+    const now = Date.now();
+
+    let activityId: string;
+
+    this.db.exec("BEGIN IMMEDIATE");
+
+    try {
+      this.assertReview?.(reviewId);
+
+      if (input.action === "begin") {
+        activityId = randomUUID();
+
+        const taken = new Set(
+          this.live(reviewId).map((row) => Number(row.slot)),
+        );
+
+        let slot = 0;
+
+        while (taken.has(slot)) slot += 1;
+        this.db
+          .prepare(
+            "INSERT INTO authoring_presences(activity_id,review_id,slot,started_at,expires_at,focus) VALUES(?,?,?,?,?,?)",
+          )
+          .run(
+            activityId,
+            reviewId,
+            slot,
+            now,
+            now + ACTIVITY_TTL_MS,
+            input.focus ? JSON.stringify(input.focus) : null,
+          );
+      } else {
+        activityId = input.activityId;
+
+        if (input.action === "end") {
+          // Ending twice, or ending an expired presence, is harmless.
+          this.db
+            .prepare(
+              "DELETE FROM authoring_presences WHERE activity_id=? AND review_id=?",
+            )
+            .run(activityId, reviewId);
+        } else {
+          const renewed = this.db
+            .prepare(
+              `UPDATE authoring_presences SET expires_at=?${input.focus === undefined ? "" : ",focus=?"}
+              WHERE activity_id=? AND review_id=? AND expires_at>?`,
+            )
+            .run(
+              ...[
+                now + ACTIVITY_TTL_MS,
+                ...(input.focus === undefined
+                  ? []
+                  : [
+                      input.focus === null ? null : JSON.stringify(input.focus),
+                    ]),
+                activityId,
+                reviewId,
+                now,
+              ],
+            );
+
+          if (renewed.changes === 0)
+            throw new ReviewInputError(
+              "This activity ended or expired. Begin a new one.",
+              409,
+            );
+        }
+      }
+
+      this.db.exec("COMMIT");
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+
+    this.scheduleExpiry(reviewId);
+
+    this.changed(reviewId);
+
+    const result: ActivitySnapshot & { activityId?: string } =
+      this.read(reviewId);
+
+    if (input.action === "begin") result.activityId = activityId;
+
+    return result;
+  }
+
+  /** One timer per review, for its soonest-expiring presence. */
+  private scheduleExpiry(reviewId: string) {
+    clearTimeout(this.timers.get(reviewId));
+    this.timers.delete(reviewId);
+
+    const next = this.db
+      .prepare(
+        "SELECT MIN(expires_at) AS expires_at FROM authoring_presences WHERE review_id=? AND expires_at>?",
+      )
+      .get(reviewId, Date.now());
+
+    if (next?.expires_at === null || next?.expires_at === undefined) return;
+
+    const timer = setTimeout(
+      () => {
+        this.scheduleExpiry(reviewId);
+        this.changed(reviewId);
+      },
+      Math.max(1, Number(next.expires_at) - Date.now()),
+    );
+
+    timer.unref?.();
+    this.timers.set(reviewId, timer);
+  }
+
+  /** Called when another database connection commits session changes. */
+  refresh() {
+    const ids = new Set(this.timers.keys());
+
+    for (const row of this.db
+      .prepare(
+        "SELECT DISTINCT review_id FROM authoring_presences WHERE expires_at>?",
+      )
+      .all(Date.now()))
+      ids.add(String(row.review_id));
+
+    for (const id of ids) {
+      this.scheduleExpiry(id);
+      this.changed(id);
+    }
+  }
+
+  /** The store deletes the session atomically with its review before notifying. */
+  deleted(reviewId: string) {
+    clearTimeout(this.timers.get(reviewId));
+    this.timers.delete(reviewId);
+    this.changed(reviewId);
+  }
+  close() {
+    this.listeners.clear();
+    this.workingListeners.clear();
+
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+  }
+}

package/src/review-api/agent-cli.ts

@@ -0,0 +1,219 @@
+import type { Readable, Writable } from "node:stream";
+
+import { traceMachineEnabled } from "@dev.fast/trace-core";
+import {
+  REVIEW_INSTANCE_ENV,
+  selectReviewInstance,
+} from "@review/desktop-discovery.js";
+import { devReviewHome } from "@review/review-home-paths.js";
+import {
+  type ReviewToolCall,
+  reviewSessionAgent,
+} from "@review/review-telemetry.js";
+
+import {
+  type AuthoringTool,
+  connectReviewInstance,
+  toolResultText,
+} from "./agent-client.js";
+import { type ReviewApiClient, ReviewApiError } from "./client.js";
+import { callPublicTool, publicTool } from "./public-tools.js";
+import { RECOVERY } from "./recovery.js";
+import { REVIEW_AGENT_HEADER, REVIEW_VIA_HEADER } from "./request-origin.js";
+import { toolFailure } from "./tool-failure.js";
+
+interface AgentCliInput {
+  argv: string[];
+  env?: NodeJS.ProcessEnv;
+  stdin?: Readable;
+  stdout: Writable;
+  stderr: Writable;
+  /** Awaited on the api path: the process exits right after the call. */
+  onToolCall?: (call: ReviewToolCall) => Promise<void> | void;
+  /** Receives the failure so the parent CLI can classify its terminal event. */
+  onFailure?: (error: Error) => void;
+  /** Receives the release of each Desktop reached, for telemetry. */
+  onDesktop?: (appVersion: string | undefined) => void;
+}
+
+export const reviewAgentCliHelp =
+  "whiteboard api tools  (one line per tool)\nwhiteboard api tools <tool-name>  (its description and input schema)\nwhiteboard api <tool-name> '<json>'\nwhiteboard api <tool-name> -  (read JSON from stdin)\nwhiteboard mcp  (stdio MCP adapter; Whiteboard Desktop or whiteboard server start must be running)\nSelect headless state with DEV_REVIEW_SERVER_DIR or whiteboard --state-dir <path> api/mcp.\n";
+
+export async function runReviewAgentCli(input: AgentCliInput): Promise<number> {
+  const env = input.env ?? process.env;
+
+  try {
+    const [mode, ...rest] = input.argv;
+
+    // --json requests raw data for session_get; other tools already return JSON.
+    const [name, json, ...extra] = rest.filter(
+      (argument) => argument !== "--json",
+    );
+
+    if (
+      rest.includes("--help") ||
+      rest.includes("-h") ||
+      (mode === "api" && !name)
+    ) {
+      input.stdout.write(reviewAgentCliHelp);
+
+      return 0;
+    }
+
+    if (extra.length || (mode === "mcp" && name))
+      throw new Error("Unexpected arguments. Use whiteboard api --help.");
+
+    const headers = {
+      [REVIEW_VIA_HEADER]: mode === "mcp" ? "mcp" : "api",
+      [REVIEW_AGENT_HEADER]: reviewSessionAgent(env),
+    };
+
+    if (mode === "mcp") {
+      const { serveReviewMcp } = await import("./mcp.js");
+      await serveReviewMcp(
+        async (key, agentKind) => {
+          const connected = await connectReviewInstance(
+            key ? { ...env, [REVIEW_INSTANCE_ENV]: key } : env,
+            agentKind
+              ? { ...headers, [REVIEW_AGENT_HEADER]: agentKind }
+              : headers,
+          );
+
+          input.onDesktop?.(connected.instance?.appVersion);
+
+          return connected;
+        },
+        input.stdin ?? process.stdin,
+        input.stdout,
+        input.stderr,
+        await traceMachineEnabled({ env: input.env }),
+        env.DEV_REVIEW_SERVER_DIR?.trim()
+          ? undefined
+          : async (problem) => {
+              const selection = await selectReviewInstance({ env });
+
+              return {
+                key: selection.key,
+                selectedBy: selection.source,
+                desktopAvailable: false,
+                running: selection.instances
+                  .filter((instance) => instance.healthy)
+                  .map((instance) => instance.key),
+                home: devReviewHome(env),
+                problem,
+              };
+            },
+        input.onToolCall,
+        reviewSessionAgent(env),
+      );
+
+      return 0;
+    }
+
+    let client: ReviewApiClient;
+    let tools: AuthoringTool[];
+
+    try {
+      const connected = await connectReviewInstance(input.env, headers);
+
+      input.onDesktop?.(connected.instance?.appVersion);
+      client = connected.client;
+      tools = (await client.read<AuthoringTool[]>("/authoring")).map(
+        publicTool,
+      );
+    } catch (error) {
+      if (
+        name === "session_get_instructions" &&
+        !(error instanceof ReviewApiError)
+      ) {
+        input.stderr.write(RECOVERY + "\n");
+
+        return 1;
+      }
+
+      throw error;
+    }
+
+    if (name === "tools") {
+      // The whole catalog is too long to read; a name prints one schema.
+      if (json) {
+        const tool = tools.find((tool) => tool.name === json);
+
+        if (!tool)
+          throw new Error(
+            `Unknown review tool: ${json}. Use whiteboard api tools.`,
+          );
+        input.stdout.write(JSON.stringify(tool, null, 2) + "\n");
+
+        return 0;
+      }
+
+      for (const tool of tools)
+        input.stdout.write(
+          `${tool.name}: ${tool.description.split(/(?<=\.)\s/)[0]}\n`,
+        );
+
+      return 0;
+    }
+
+    const tool = tools.find((tool) => tool.name === name);
+
+    if (!tool)
+      throw new Error(
+        `Unknown review tool: ${name}. Use whiteboard api tools.`,
+      );
+    let source = json ?? "{}";
+
+    if (source === "-") {
+      if (!input.stdin) throw new Error("No input stream supplied.");
+      source = "";
+      input.stdin.setEncoding("utf8");
+
+      for await (const chunk of input.stdin) source += chunk;
+    }
+
+    const args = parseJsonText(source);
+
+    if (!isJsonObject(args))
+      throw new Error("Tool input must be a JSON object.");
+
+    if (name === "session_get" && rest.includes("--json")) args.format = "json";
+    const startedAt = Date.now();
+    let result: Awaited<ReturnType<typeof callPublicTool>>;
+
+    try {
+      result = await callPublicTool(client, tool, args);
+    } catch (error) {
+      await input.onToolCall?.({
+        tool: tool.name,
+        via: "api",
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        ...toolFailure(error, "call"),
+      });
+
+      throw error;
+    }
+
+    await input.onToolCall?.({
+      tool: tool.name,
+      via: "api",
+      ok: true,
+      durationMs: Date.now() - startedAt,
+    });
+
+    const text = toolResultText(tool, result);
+    input.stdout.write(text.endsWith("\n") ? text : text + "\n");
+
+    return 0;
+  } catch (error) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+
+    input.onFailure?.(failure);
+    input.stderr.write(failure.message + "\n");
+
+    return 1;
+  }
+}
+
+import { isJsonObject, parseJsonText } from "@dev.fast/json";