@dev.fast/whiteboard 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,188 @@
+import {
+  ReviewInstanceUnavailableError,
+  healthyReviewInstance,
+  reviewInstanceUnavailable,
+  selectReviewInstance,
+} from "@review/desktop-discovery.js";
+import {
+  readReviewServerDiscovery,
+  reviewServerIsHealthy,
+  reviewServerStateDir,
+  serverNotReady,
+} from "@review/server-discovery.js";
+
+import { ReviewApiClient, ReviewApiError } from "./client.js";
+import { ReviewInputError } from "./input-error.js";
+
+export interface AuthoringTool {
+  name: string;
+  description: string;
+  inputSchema: Tool["inputSchema"];
+  method: "GET" | "POST";
+  path: string;
+  commandType?: string;
+}
+
+const TEXT_TOOLS = new Set([
+  "review_get",
+  "review_get_instructions",
+  "session_get",
+  "session_get_instructions",
+]);
+
+export interface ConnectedReview {
+  client: ReviewApiClient;
+  /** The Desktop reached; absent for a headless server. */
+  instance?: { key: string; appVersion?: string };
+}
+
+export async function connectReviewApi(
+  env = process.env,
+  headers: Record<string, string> = {},
+) {
+  return (await connectReviewInstance(env, headers)).client;
+}
+
+export async function connectReviewInstance(
+  env = process.env,
+  headers: Record<string, string> = {},
+): Promise<ConnectedReview> {
+  const request: ConstructorParameters<typeof ReviewApiClient>[1] = (
+    url,
+    init,
+  ) => {
+    const merged = new Headers(init?.headers);
+
+    for (const [key, value] of Object.entries(headers)) merged.set(key, value);
+
+    return fetch(url, { ...init, headers: merged });
+  };
+
+  if (env.DEV_REVIEW_SERVER_DIR?.trim()) {
+    const stateDir = reviewServerStateDir(env);
+    const server = await readReviewServerDiscovery(stateDir);
+
+    if (!server || !(await reviewServerIsHealthy(server)))
+      throw serverNotReady(stateDir);
+
+    return {
+      client: new ReviewApiClient(
+        { serverUrl: server.url, token: server.token },
+        request,
+      ),
+    };
+  }
+
+  const selection = await selectReviewInstance({ env });
+  const discovery = healthyReviewInstance(selection);
+
+  if (!discovery) {
+    const unavailable = reviewInstanceUnavailable(selection);
+    const message = `${unavailable.message} For headless authoring, select a running server with --state-dir or DEV_REVIEW_SERVER_DIR.`;
+
+    if (unavailable instanceof ReviewInstanceUnavailableError)
+      throw new ReviewInstanceUnavailableError(message);
+
+    throw unavailable;
+  }
+
+  return {
+    client: new ReviewApiClient(
+      { serverUrl: discovery.url, token: discovery.token },
+      request,
+    ),
+    instance: { key: selection.key, appVersion: discovery.appVersion },
+  };
+}
+
+/** Only translate the tool envelope. The host owns validation and persistence. */
+export async function callAuthoringTool(
+  client: ReviewApiClient,
+  tool: AuthoringTool,
+  input: NonNullable<CallToolRequest["params"]["arguments"]>,
+  signal?: AbortSignal,
+) {
+  if (tool.commandType) {
+    try {
+      return await client.post<JsonValue>(
+        tool.path,
+        { operation: { ...input, type: tool.commandType } },
+        signal,
+      );
+    } catch (error) {
+      // A host reply (any status) is definite: a failed command rolls back.
+      if (error instanceof ReviewApiError || signal?.aborted) throw error;
+
+      throw new Error(
+        `Whiteboard may or may not have applied ${tool.name} (${error instanceof Error ? error.message : String(error)}). Check with review_get before retrying.`,
+        { cause: error },
+      );
+    }
+  }
+
+  const fields = { ...input };
+
+  const route = tool.path.replace(/:reviewId\b/g, () => {
+    const value = fields.reviewId;
+
+    if (!isStringValue(value) || !value)
+      throw new ReviewInputError("reviewId is required.");
+    delete fields.reviewId;
+
+    return encodeURIComponent(value);
+  });
+
+  if (tool.method === "POST")
+    return client.post<JsonValue>(route, fields, signal);
+  const query = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(fields)) {
+    // Hosts often send null for an unused optional field; the route reads absence.
+    if (value === null || value === undefined) continue;
+
+    // Arrays travel as repeated keys, as in paths=a&paths=b.
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (!isStringValue(item) && !isNumberValue(item) && !isBooleanValue(item))
+        throw new ReviewInputError(
+          `${key} must be a string, number, boolean or list of them.`,
+        );
+
+      query.append(key, String(item));
+    }
+  }
+
+  const response = await client.response(
+    route + (query.size ? `?${query}` : ""),
+    { signal },
+  );
+
+  return response.headers.get("content-type")?.startsWith("text/plain")
+    ? new ToolText(await response.text())
+    : parseJsonText(await response.text());
+}
+
+/** A plain-text reply, shown to the agent as-is instead of as a JSON string. */
+export class ToolText {
+  constructor(readonly text: string) {}
+}
+
+/** The text an agent sees for a tool result. */
+export function toolResultText(
+  tool: Pick<AuthoringTool, "name">,
+  result: JsonValue | ToolText,
+) {
+  if (result instanceof ToolText) return result.text;
+
+  return TEXT_TOOLS.has(tool.name) && isStringValue(result)
+    ? result
+    : JSON.stringify(result);
+}
+
+import {
+  isBooleanValue,
+  isNumberValue,
+  isStringValue,
+  type JsonValue,
+  parseJsonText,
+} from "@dev.fast/json";
+import type { CallToolRequest, Tool } from "@modelcontextprotocol/sdk/types.js";

package/src/review-api/anchor-quotes.ts

@@ -0,0 +1,88 @@
+import {
+  type LensSource,
+  formatAnchor,
+  selectionKey,
+} from "@review/lens-selection.js";
+
+import { type Pins, anchorPins, selectionReferences } from "./document.js";
+import type { Snapshot } from "./store.js";
+
+export interface AnchorQuote {
+  anchor: string;
+  first: string;
+  last?: string;
+}
+
+const QUOTE_LIMIT = 20;
+
+// A blank line quoted as "" reads like a failed quote.
+const clip = (line: string) =>
+  line.trim() === ""
+    ? "(blank line)"
+    : line.length > 120
+      ? `${line.slice(0, 119)}…`
+      : line;
+
+/**
+ * The first and last line of each anchor an edit added or changed, so its
+ * author can see a range is the one meant without reading the file again.
+ * A range that can't be read was already rejected, so it is skipped here.
+ * `unquoted` counts the anchors past the limit, so a short list isn't
+ * mistaken for a complete one.
+ */
+export async function anchorQuotes(
+  before: Snapshot | undefined,
+  after: Snapshot,
+  read: (pins: Pins, side: "base" | "head", file: string) => Promise<string>,
+): Promise<{ quotes: AnchorQuote[]; unquoted: number }> {
+  const key = (id: string, source: LensSource) =>
+    `${id}\0${selectionKey(source)}`;
+
+  const known = new Set(
+    before
+      ? selectionReferences(before.document, { tolerant: true }).map(
+          ({ id, source }) => key(id, source),
+        )
+      : [],
+  );
+
+  const added = selectionReferences(after.document, { tolerant: true }).filter(
+    ({ id, source }) => !known.has(key(id, source)),
+  );
+
+  const quotes = await Promise.all(
+    added
+      .slice(0, QUOTE_LIMIT)
+      .map(async ({ source }): Promise<AnchorQuote | undefined> => {
+        try {
+          const pins = anchorPins(source, after.pins);
+
+          const line = async (endpoint: LensSource["start"]) =>
+            (await read(pins, endpoint.side, source.file)).split("\n")[
+              endpoint.line - 1
+            ] ?? "";
+
+          const first = clip(await line(source.start));
+
+          const single =
+            source.start.side === source.end.side &&
+            source.start.line === source.end.line;
+
+          return single
+            ? { anchor: formatAnchor(source), first }
+            : {
+                anchor: formatAnchor(source),
+                first,
+                last: clip(await line(source.end)),
+              };
+        } catch {
+          return undefined;
+        }
+      }),
+  );
+
+  return {
+    quotes: quotes.filter((quote) => quote !== undefined),
+    unquoted: Math.max(0, added.length - QUOTE_LIMIT),
+  };
+}

package/src/review-api/ask-history.ts

@@ -0,0 +1,242 @@
+import type { DatabaseSync } from "node:sqlite";
+
+import {
+  type AskAgentId,
+  type AskEntry,
+  type AskHistoryEntry,
+  type AskOffer,
+  askEntrySchema,
+  askHistoryEntrySchema,
+  askOfferSchema,
+} from "@review/ask/thread-state.js";
+import { z } from "zod";
+
+/** A saved Ask conversation: its history entry, and how to reopen it. */
+export const askRecordSchema = askHistoryEntrySchema.extend({
+  reviewId: z.string(),
+  /** The ACP session the agent keeps the transcript under. */
+  sessionId: z.string(),
+  /** The review version asked about; its pins recreate the checkout. */
+  version: z.number().int(),
+  cwd: z.string(),
+  /** What the panel showed last; absent until a turn ends or it closes. */
+  entries: z.array(askEntrySchema).optional(),
+  /** The agent edits and runs commands without asking. */
+  bypass: z.boolean().optional(),
+});
+
+export type AskRecord = z.infer<typeof askRecordSchema>;
+
+const rowSchema = z
+  .object({
+    id: z.string(),
+    review_id: z.string(),
+    agent: z.string(),
+    session_id: z.string(),
+    version: z.number(),
+    head: z.string(),
+    cwd: z.string(),
+    selection: z.string(),
+    title: z.string(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    entries: z.string().nullable(),
+    bypass: z.number(),
+  })
+  .transform((row) =>
+    askRecordSchema.parse({
+      id: row.id,
+      reviewId: row.review_id,
+      agent: row.agent,
+      sessionId: row.session_id,
+      version: row.version,
+      head: row.head,
+      cwd: row.cwd,
+      selection: JSON.parse(row.selection),
+      title: row.title,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      entries: row.entries === null ? undefined : JSON.parse(row.entries),
+      bypass: row.bypass === 1,
+    }),
+  );
+
+/** Saved Ask conversations, per review. Shared reviews are not in
+ * `reviews`, so there is no foreign key; deleting a review deletes its rows. */
+export class AskHistory {
+  constructor(private readonly db: DatabaseSync) {
+    db.exec(`CREATE TABLE IF NOT EXISTS ask_conversations(
+      id TEXT PRIMARY KEY,
+      review_id TEXT NOT NULL,
+      agent TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      head TEXT NOT NULL,
+      cwd TEXT NOT NULL,
+      selection TEXT NOT NULL,
+      title TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      entries TEXT,
+      bypass INTEGER NOT NULL DEFAULT 0,
+      UNIQUE(agent, session_id));
+    CREATE INDEX IF NOT EXISTS ask_conversations_review ON ask_conversations(review_id, updated_at);`);
+
+    // Conversations saved before bypassing permissions lack the column.
+    if (
+      !db
+        .prepare("PRAGMA table_info(ask_conversations)")
+        .all()
+        .some((column) => String(column.name) === "bypass")
+    )
+      db.exec(
+        "ALTER TABLE ask_conversations ADD COLUMN bypass INTEGER NOT NULL DEFAULT 0",
+      );
+
+    // What each agent offered last, so a new question can pick a model and
+    // effort, and a command, before its agent starts.
+    db.exec(
+      "CREATE TABLE IF NOT EXISTS ask_agent_offers(agent TEXT PRIMARY KEY, offer TEXT NOT NULL)",
+    );
+    // And with each model it ran, since the efforts on offer depend on it.
+    db.exec(
+      "CREATE TABLE IF NOT EXISTS ask_agent_model_offers(agent TEXT NOT NULL, model TEXT NOT NULL, offer TEXT NOT NULL, PRIMARY KEY(agent, model))",
+    );
+  }
+
+  save(record: AskRecord) {
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO ask_conversations(id,review_id,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`,
+      )
+      .run(
+        record.id,
+        record.reviewId,
+        record.agent,
+        record.sessionId,
+        record.version,
+        record.head,
+        record.cwd,
+        JSON.stringify(record.selection),
+        record.title,
+        record.createdAt,
+        record.updatedAt,
+        record.bypass ? 1 : 0,
+      );
+  }
+
+  /** Whether reopening the conversation bypasses permissions. */
+  setBypass(id: string, bypass: boolean) {
+    this.db
+      .prepare("UPDATE ask_conversations SET bypass=? WHERE id=?")
+      .run(bypass ? 1 : 0, id);
+  }
+
+  /** Points a conversation at a new session, when its agent could not
+   * reopen the one it had. */
+  updateSession(id: string, sessionId: string) {
+    this.db
+      .prepare("UPDATE ask_conversations SET session_id=? WHERE id=?")
+      .run(sessionId, id);
+  }
+
+  /** Keeps what the panel shows, so a reopen need not wait on the agent. */
+  saveEntries(id: string, entries: AskEntry[]) {
+    this.db
+      .prepare("UPDATE ask_conversations SET entries=? WHERE id=?")
+      .run(JSON.stringify(entries), id);
+  }
+
+  /** The agent's name for the conversation, which the list shows. */
+  rename(id: string, title: string) {
+    this.db
+      .prepare("UPDATE ask_conversations SET title=? WHERE id=?")
+      .run(title.slice(0, 200), id);
+  }
+
+  saveOffer(agent: AskAgentId, offer: AskOffer) {
+    this.db
+      .prepare(
+        "INSERT OR REPLACE INTO ask_agent_offers(agent, offer) VALUES(?, ?)",
+      )
+      .run(agent, JSON.stringify(offer));
+    this.saveModelOffer(agent, offer);
+  }
+
+  /** Keeps what the agent offers with the offer's model, without making
+   * it what the agent offered last. */
+  saveModelOffer(agent: AskAgentId, offer: AskOffer) {
+    const model = offer.choices.model?.current;
+
+    if (!model) return;
+    this.db
+      .prepare(
+        "INSERT OR REPLACE INTO ask_agent_model_offers(agent, model, offer) VALUES(?, ?, ?)",
+      )
+      .run(agent, model, JSON.stringify(offer));
+  }
+
+  /** What the agent offered last, or last with the model given. */
+  offer(agent: AskAgentId, model?: string): AskOffer | undefined {
+    const row = z
+      .object({ offer: z.string() })
+      .safeParse(
+        model === undefined
+          ? this.db
+              .prepare("SELECT offer FROM ask_agent_offers WHERE agent=?")
+              .get(agent)
+          : this.db
+              .prepare(
+                "SELECT offer FROM ask_agent_model_offers WHERE agent=? AND model=?",
+              )
+              .get(agent, model),
+      ).data;
+
+    return row && askOfferSchema.safeParse(JSON.parse(row.offer)).data;
+  }
+
+  touch(id: string, at = new Date().toISOString()) {
+    this.db
+      .prepare("UPDATE ask_conversations SET updated_at=? WHERE id=?")
+      .run(at, id);
+  }
+
+  /** Newest first. */
+  list(reviewId: string): AskHistoryEntry[] {
+    return this.db
+      .prepare(
+        "SELECT * FROM ask_conversations WHERE review_id=? ORDER BY updated_at DESC",
+      )
+      .all(reviewId)
+      .map((row) => {
+        const {
+          reviewId: _reviewId,
+          sessionId: _sessionId,
+          version: _version,
+          cwd: _cwd,
+          entries,
+          bypass: _bypass,
+          ...entry
+        } = rowSchema.parse(row);
+
+        const question = entries?.find((entry) => entry.kind === "user")?.text;
+
+        if (question?.trim()) entry.question = question;
+
+        return entry;
+      });
+  }
+
+  get(id: string): AskRecord | undefined {
+    const row = this.db
+      .prepare("SELECT * FROM ask_conversations WHERE id=?")
+      .get(id);
+
+    return row ? rowSchema.parse(row) : undefined;
+  }
+
+  delete(id: string) {
+    this.db.prepare("DELETE FROM ask_conversations WHERE id=?").run(id);
+  }
+}