@dev.fast/whiteboard 0.3.4 → 0.3.5-preview.20261021.131

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

@@ -17,7 +17,10 @@ import { ReviewInputError } from "./document.js";
 
 /** A saved Ask conversation: its history entry, and how to reopen it. */
 export const askRecordSchema = askHistoryEntrySchema.extend({
-  reviewId: z.string(),
+  /** The board the conversation started on, and the block if any. */
+  anchor: z.object({ board: z.string(), block: z.string().optional() }),
+  /** Absent for a shared board. */
+  projectId: z.string().optional(),
   /** The ACP session the agent keeps the transcript under. */
   sessionId: z.string(),
   /** The review version asked about; its pins recreate the checkout. */
@@ -34,7 +37,9 @@ export type AskRecord = z.infer<typeof askRecordSchema>;
 const rowSchema = z
   .object({
     id: z.string(),
-    review_id: z.string(),
+    anchor_board: z.string(),
+    anchor_block: z.string().nullable(),
+    project_id: z.string().nullable(),
     agent: z.string(),
     session_id: z.string(),
     version: z.number(),
@@ -51,7 +56,11 @@ const rowSchema = z
   .transform((row) =>
     askRecordSchema.parse({
       id: row.id,
-      reviewId: row.review_id,
+      anchor:
+        row.anchor_block === null
+          ? { board: row.anchor_board }
+          : { board: row.anchor_board, block: row.anchor_block },
+      projectId: row.project_id ?? undefined,
       agent: row.agent,
       sessionId: row.session_id,
       version: row.version,
@@ -68,17 +77,33 @@ const rowSchema = z
     }),
   );
 
-/** Saved Ask conversations, per review. Shared reviews are not in
- * `reviews`, so there is no foreign key; deleting a review deletes its rows. */
+/** A thread's project is always its anchor board's. */
+const THREAD_PROJECT_SQL =
+  "(SELECT project_id FROM reviews WHERE reviews.id=ask_conversations.anchor_board)";
+
+/** Every column of a thread, with its project. */
+const THREAD_COLUMNS = `ask_conversations.*, ${THREAD_PROJECT_SQL} AS project_id`;
+
+/** Saved Ask conversations by project, each anchored on the board it started
+ * on. No foreign key on the anchor: shared reviews are not in `reviews`.
+ * So deleting a board removes its threads by hand (removeReview). */
 export class AskHistory {
+  private readonly listeners = new Set<() => void>();
+
   private externalWriteGuard?: (reviewId: string) => void;
   setExternalWriteGuard(guard: (reviewId: string) => void) {
     this.externalWriteGuard = guard;
   }
-  constructor(private readonly db: DatabaseSync) {
+  constructor(
+    private readonly db: DatabaseSync,
+    /** The store's rule for writing about a board: one in Trash is
+     * read-only. */
+    private readonly writable: (reviewId: string) => void = () => {},
+  ) {
     db.exec(`CREATE TABLE IF NOT EXISTS ask_conversations(
       id TEXT PRIMARY KEY,
-      review_id TEXT NOT NULL,
+      anchor_board TEXT NOT NULL,
+      anchor_block TEXT,
       agent TEXT NOT NULL,
       session_id TEXT NOT NULL,
       version INTEGER NOT NULL,
@@ -91,25 +116,12 @@ export class AskHistory {
       entries TEXT,
       bypass INTEGER NOT NULL DEFAULT 0,
       permissions TEXT,
-      UNIQUE(agent, session_id));
-    CREATE INDEX IF NOT EXISTS ask_conversations_review ON ask_conversations(review_id, updated_at);`);
-
-    // Conversations saved before bypassing permissions, or before auto mode,
-    // lack its column.
-    const columns = new Set(
-      db
-        .prepare("PRAGMA table_info(ask_conversations)")
-        .all()
-        .map((column) => String(column.name)),
-    );
+      viewed_at TEXT,
+      UNIQUE(agent, session_id));`);
 
-    if (!columns.has("bypass"))
-      db.exec(
-        "ALTER TABLE ask_conversations ADD COLUMN bypass INTEGER NOT NULL DEFAULT 0",
-      );
-
-    if (!columns.has("permissions"))
-      db.exec("ALTER TABLE ask_conversations ADD COLUMN permissions TEXT");
+    db.exec(
+      "CREATE INDEX IF NOT EXISTS ask_conversations_review ON ask_conversations(anchor_board, updated_at)",
+    );
 
     // What each agent offered last, so a new question can pick a model and
     // effort, and a command, before its agent starts.
@@ -122,34 +134,46 @@ export class AskHistory {
     );
   }
 
-  private assertWritable(reviewId: string) {
-    if (reviewId.startsWith("shared-")) this.externalWriteGuard?.(reviewId);
+  /** Calls back when a conversation is saved, renamed, used or deleted. */
+  subscribe(listener: () => void) {
+    this.listeners.add(listener);
 
-    const row = this.db
-      .prepare("SELECT deleted_at FROM review_attention WHERE review_id=?")
-      .get(reviewId);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
 
-    if (row?.deleted_at)
-      throw new ReviewInputError(
-        `This whiteboard was moved to Trash on ${new Date(String(row.deleted_at)).toLocaleDateString("en-US", { month: "short", day: "numeric" })}. Restore it with session_lifecycle({"sessionId":"${reviewId}","state":"active"}) to continue.`,
-        409,
-      );
+  private changed() {
+    for (const listener of this.listeners) listener();
+  }
+
+  private assertWritable(reviewId: string) {
+    if (reviewId.startsWith("shared-")) this.externalWriteGuard?.(reviewId);
+    else this.writable(reviewId);
   }
+
   private assertThreadWritable(id: string) {
     const record = this.get(id);
 
-    if (record) this.assertWritable(record.reviewId);
+    if (record) this.assertWritable(record.anchor.board);
   }
   save(record: AskRecord) {
-    this.assertWritable(record.reviewId);
+    this.assertWritable(record.anchor.board);
     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,permissions)
-        VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+        // Its columns, not the row: when it was last seen, and what the
+        // panel showed, stay.
+        `INSERT INTO ask_conversations(id,anchor_board,anchor_block,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass,permissions)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+        ON CONFLICT(id) DO UPDATE SET anchor_board=excluded.anchor_board, anchor_block=excluded.anchor_block,
+          agent=excluded.agent, session_id=excluded.session_id, version=excluded.version, head=excluded.head,
+          cwd=excluded.cwd, selection=excluded.selection, title=excluded.title, created_at=excluded.created_at,
+          updated_at=excluded.updated_at, bypass=excluded.bypass, permissions=excluded.permissions`,
       )
       .run(
         record.id,
-        record.reviewId,
+        record.anchor.board,
+        record.anchor.block ?? null,
         record.agent,
         record.sessionId,
         record.version,
@@ -162,6 +186,7 @@ export class AskHistory {
         record.permissions === "bypass" ? 1 : 0,
         record.permissions ?? null,
       );
+    this.changed();
   }
 
   /** What the agent may do without asking when the conversation reopens. */
@@ -189,6 +214,7 @@ export class AskHistory {
     this.db
       .prepare("UPDATE ask_conversations SET entries=? WHERE id=?")
       .run(JSON.stringify(entries), id);
+    this.changed();
   }
 
   /** The agent's name for the conversation, which the list shows. */
@@ -197,6 +223,7 @@ export class AskHistory {
     this.db
       .prepare("UPDATE ask_conversations SET title=? WHERE id=?")
       .run(title.slice(0, 200), id);
+    this.changed();
   }
 
   saveOffer(agent: AskAgentId, offer: AskOffer) {
@@ -245,50 +272,90 @@ export class AskHistory {
     this.db
       .prepare("UPDATE ask_conversations SET updated_at=? WHERE id=?")
       .run(at, id);
+    this.changed();
+  }
+
+  /** Conversations in a board's project, or started on the board when it
+   * has none. Newest first. */
+  list(board: string, projectId?: string) {
+    // The project's boards by their index on project_id, then their
+    // threads by ask_conversations_review.
+    return this.entries(
+      "anchor_board=? OR anchor_board IN (SELECT id FROM reviews WHERE project_id=?)",
+      board,
+      projectId ?? null,
+    );
   }
 
-  /** Newest first. */
-  list(reviewId: string): AskHistoryEntry[] {
+  /** Every project's conversations, newest first. */
+  listAll() {
+    return this.entries("1");
+  }
+
+  private entries(
+    where: string,
+    ...params: (string | null)[]
+  ): (AskHistoryEntry & { projectId?: string; viewedAt?: string })[] {
+    // A transcript can be long: SQLite finds its first question, and the
+    // rest of it is left unread.
     return this.db
       .prepare(
-        "SELECT * FROM ask_conversations WHERE review_id=? ORDER BY updated_at DESC",
+        `SELECT id, anchor_board, anchor_block, ${THREAD_PROJECT_SQL} AS project_id, agent, session_id, version, head, cwd, selection, title,
+          created_at, updated_at, NULL AS entries, bypass, permissions, viewed_at,
+          (SELECT json_extract(value,'$.text') FROM json_each(entries)
+            WHERE json_extract(value,'$.kind')='user' LIMIT 1) AS question
+        FROM ask_conversations WHERE ${where} ORDER BY updated_at DESC`,
       )
-      .all(reviewId)
+      .all(...params)
       .map((row) => {
         const {
-          reviewId: _reviewId,
+          anchor,
           sessionId: _sessionId,
           version: _version,
           cwd: _cwd,
-          entries,
+          entries: _entries,
           permissions: _permissions,
           ...entry
         } = rowSchema.parse(row);
 
-        const question = entries?.find((entry) => entry.kind === "user")?.text;
+        const question = z.string().nullable().parse(row.question) ?? "";
 
-        if (question?.trim()) entry.question = question;
+        if (question.trim()) entry.question = question;
 
-        return entry;
+        const viewedAt = z.string().nullable().parse(row.viewed_at);
+
+        return { ...entry, anchor, ...(viewedAt !== null && { viewedAt }) };
       });
   }
 
   get(id: string): AskRecord | undefined {
     const row = this.db
-      .prepare("SELECT * FROM ask_conversations WHERE id=?")
+      .prepare(`SELECT ${THREAD_COLUMNS} FROM ask_conversations WHERE id=?`)
       .get(id);
 
     return row ? rowSchema.parse(row) : undefined;
   }
 
+  /** The reviewer saw the thread, on screen with the app focused. Only
+   * when it was seen changes: not its order, nor when it was used. */
+  markViewed(id: string, at = new Date().toISOString()) {
+    this.db
+      .prepare("UPDATE ask_conversations SET viewed_at=? WHERE id=?")
+      .run(at, id);
+    this.changed();
+  }
+
+  /** Forgets the threads that started on a board gone for good. */
   removeReview(reviewId: string) {
     this.db
-      .prepare("DELETE FROM ask_conversations WHERE review_id=?")
+      .prepare("DELETE FROM ask_conversations WHERE anchor_board=?")
       .run(reviewId);
+    this.changed();
   }
 
   delete(id: string) {
     this.assertThreadWritable(id);
     this.db.prepare("DELETE FROM ask_conversations WHERE id=?").run(id);
+    this.changed();
   }
 }

package/src/review-api/authoring-tools.ts

@@ -1,3 +1,4 @@
+import { type JsonValue, isJsonObject } from "@dev.fast/json";
 import { z } from "zod";
 
 import {
@@ -15,10 +16,7 @@ import { commandSchema } from "./store.js";
 /** The host publishes its input schemas, except where agents write less than
  * the host accepts (publishedEditSchema, publishedLensEditSchema) or name a
  * checkout by path (pathTargetSchema); adapters validate nothing. */
-export function authoringTools(
-  scratchpadAvailable = false,
-  traceEnabled = false,
-) {
+export function authoringTools(traceEnabled = false) {
   const id = z.string().min(1);
   const review = { reviewId: id };
 
@@ -31,19 +29,21 @@ export function authoringTools(
       ...trace.shape,
       kind: z.enum(["image", "trace"]),
     })
+    .omit({ repositoryId: true })
+    .extend({ repositoryPath: id })
     .partial()
-    .required({ id: true, repositoryId: true, kind: true });
+    .required({ id: true, repositoryPath: true, kind: true });
 
   const descriptions = {
     create:
-      'Create a review of saved working files, immutable commits or a GitHub PR. Revisions are resolved on acceptance. A worktree target reviews the saved files in its checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base: the branch to compare against, by default the default branch of the repository. The diff starts at the merge base of base and HEAD, which follows rebases. Omitted commits base means source at head with no diff; supply the parent to review introduced changes. For a branch stacked on another, pass the branch below it as base; Desktop links reviews into a stack through their bases. For a GitHub PR, pullRequestUrl alone is enough: target and title become optional, and the host fetches the PR into a registered checkout of its repository and pins the current PR head and GitHub diff base, titled from the PR. When the existing review for that PR is in Trash, creation reports its ID; restore it with review_lifecycle state:"active" before continuing. When an active review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting. kind:"scratchpad" names the one scratchpad, which the host creates itself. The result carries review, the review as review_list shows it: its target with resolved commits, origin (its PR), repositoryName and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop.',
+      'Create a whiteboard. target names its repository by the checkout\'s path, and what it shows: {kind:"project"} for a plan in that repository\'s project with no change; {kind:"worktree", base?} for the saved files in the checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base, by default the repository\'s default branch, from the merge base of base and HEAD, which follows rebases; {kind:"commits", head, base?} for immutable commits (omitted base means source at head with no diff; supply the parent to review introduced changes); {kind:"pullRequest", pullRequest} for a GitHub PR by URL or number, fetched into that checkout and pinned at the PR head and GitHub diff base. For a branch stacked on another, pass the branch below it as base. Group plan implementations or a PR stack under one project-target overview with parentId, and order its children with dependsOn; Git bases do not set these relationships. Revisions are resolved on acceptance. With a PR and no title the PR\'s title is used. When the existing review for that PR is in Trash, creation reports its ID; restore it with review_lifecycle state:"active" before continuing. When an active review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting:false. The result carries review, as review_list shows it, with its target and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop. parentId and dependsOn set its place among the project\'s reviews, as review_set_parent and review_set_dependencies do; projectId files it in another project, by project.id from review_list.',
     set_target:
-      "Move the review to a new target, such as the commits after a rebase or amend, preserving the document and component IDs. Revisions are resolved on acceptance. Returns warnings for retained source ranges in files the new commits changed, to verify, and resources that no longer match; fix them with review_edit. Earlier versions keep their source. Omitted pullRequestUrl keeps the PR within the same repository; changing repositories clears it. Supply a URL to replace it or null to detach.",
+      "Move the review to a new target (the same targets review_create takes), such as the commits after a rebase or amend, or commits or a PR for a board that had none. The document and component IDs are kept. Revisions are resolved on acceptance. Returns warnings for retained source ranges in files the new commits changed, to verify, and resources that no longer match; fix them with review_edit. Earlier versions keep their source. A PR target names the PR; other targets keep it within the same repository and clear it across repositories.",
     edit: [
-      "Edit one document component. content is one component, named by its type; each type's fields are in the Components section of session_get_instructions (authoring or scratchpad).",
-      "Anchors are head/path#L10-L20 or base/path#L7, or diff/path#L84-R90 for a range across sides, with repository-relative paths and 1-based inclusive lines. pins {repositoryId, head, base?} say which commits anchors quote: a step, frame, attachment or operation without pins uses its block's, and a block without them the review's.",
-      "insert adds content: parentId nests it, afterId places it, and omitted placement appends (on the scratchpad, it lands at the top). update patches a component's own fields; null removes an optional one. A section's children and a diagram's units change through their own IDs; a call stack's frames change by replacing the call stack. move and remove take a targetId; removing a flow_node removes its edges.",
-      "The host assigns short durable IDs. The result names the edited component and, for an insert or replace, its first-level children, and quotes the first and last line of each anchor the edit added or changed (the first 20; unquotedAnchors counts the rest): check they are the lines you meant. Accepted edits save at once.",
+      "Edit one document component. content is one component, named by its type; each type's fields are in the Components section of session_get_instructions.",
+      "Anchors are head/path#L10-L20 or base/path#L7, or diff/path#L84-R90 for a range across sides, with repository-relative paths and 1-based inclusive lines. pins {head, base?} say which commits of the whiteboard's repository anchors quote: a step, frame, attachment or operation without pins uses its block's, and a block without them the review's.",
+      "insert adds content: parentId nests it, afterId places it, and omitted placement appends. update patches a component's own fields; null removes an optional one. A section's children and a diagram's units change through their own IDs; a call stack's frames change by replacing the call stack. move and remove take a targetId; removing a flow_node removes its edges.",
+      "The host assigns short durable IDs. The result names the edited component and, for an insert or replace, its first-level children, and quotes the first and last line of each anchor the edit added or changed (the first 20; unquotedAnchors counts the rest): check they are the lines you meant. Accepted edits save at once. An edit to a block the user is editing is refused with an error: edit another block, or retry later.",
       "While a reader may be watching, write small and often: one paragraph per edit. Insert a new diagram whole. Change one already drawn a unit at a time (a flow_node, flow_edge or step, with parentId naming the diagram), and link each added flow_node to a node already drawn.",
     ].join("\n"),
     lens_edit:
@@ -56,7 +56,11 @@ export function authoringTools(
     lifecycle:
       "Move a review between active and trash. Trash retains the review for 30 days before automatic deletion. Moving it back to active restores it; moving it to trash again does not restart that period.",
     delete:
-      "Permanently delete a review and its history. The review must be in Trash. This cannot be undone.",
+      "Permanently delete a review and its history. The review must be in Trash. This cannot be undone. Its children move up to top level, and dependencies on it are dropped.",
+    set_parent:
+      "Nest the review under another review of the same project, or make it top-level with parentId:null. Nesting is one level deep: the parent must be top-level, and a review with children can't become a child. The sidebar shows children under their parent. Saves no review version. Returns the review's relations: parentId, children in sibling order, and dependsOn.",
+    set_dependencies:
+      "Replace the list of reviews this one builds on: any reviews of the same project. Siblings list after what they depend on, directly or through other reviews; a PR stack is a chain. A list that would close a cycle is refused, naming the cycle. Saves no review version. Returns the review's relations.",
   };
 
   const tool = (
@@ -70,7 +74,7 @@ export function authoringTools(
     name: `review_${name === "restore" ? "restore_version" : name}`,
     description,
     inputSchema: {
-      ...z.toJSONSchema(schema, { io: "input" }),
+      ...withoutRepositoryIds(z.toJSONSchema(schema, { io: "input" })),
       type: "object" as const,
     },
     method,
@@ -92,9 +96,6 @@ export function authoringTools(
       'Read Whiteboard\'s guidance before creating or editing a review. The default topic gives the authoring workflow; "file-lenses" covers Diff-view file lenses.' +
         (traceEnabled
           ? ' Call review_get_instructions({topic:"trace-archaeology"}) for why code exists, what an agent was thinking, or whether an agent solved this before.'
-          : "") +
-        (scratchpadAvailable
-          ? ' When the user asks in conversation to be shown how code works or wants a diagram, without asking for a review, draw it on the scratchpad rather than answering only in chat: call review_get_instructions({topic:"scratchpad"}) first. A request for a review or to use Whiteboard means authoring a review with the default topic.'
           : ""),
       instructionsQuerySchema.partial(),
       "GET",
@@ -124,10 +125,12 @@ export function authoringTools(
     ...commandSchema.shape.operation.options.map((operation) => {
       const type = operation.shape.type.value;
 
-      // Agents name a checkout by its path; /commands registers it.
+      // Hidden from agents: they name checkouts by path inside the target
+      // and give PRs as a target.
       const {
         type: _type,
         repositoryId: _repositoryId,
+        pullRequestUrl: _pullRequestUrl,
         ...fields
       }: Record<string, z.ZodType> = operation.shape;
 
@@ -137,12 +140,7 @@ export function authoringTools(
         z.strictObject({
           ...fields,
           ...(type === "create" && {
-            target: pathTargetSchema.optional(),
-            repositoryPath: id
-              .optional()
-              .describe(
-                "Only with pullRequestUrl and no target: the local checkout to fetch the PR into. Default: the existing review's, else the first registered checkout with a remote for the PR's repository.",
-              ),
+            target: pathTargetSchema,
             open: z.boolean().optional(),
           }),
           ...(type === "set_target" && { target: pathTargetSchema }),
@@ -196,13 +194,6 @@ export function authoringTools(
       "POST",
       "/workspace-cleanup",
     ),
-    tool(
-      "register_repository",
-      "Register a local Git or jj repository and return its id, for pins on scratchpad blocks. session_create and session_set_target take the checkout's path instead.",
-      z.strictObject({ path: id }),
-      "POST",
-      "/repositories",
-    ),
     tool(
       "upload",
       'Retain an image or trace for use in a review. kind:"image" takes base64; kind:"trace" takes trace. Reusing an upload ID requires identical content; rejected uploads are not saved.',
@@ -212,3 +203,27 @@ export function authoringTools(
     ),
   ];
 }
+
+/** Drops repositoryId from pins: the host fills in the board's own. */
+function withoutRepositoryIds<T>(schema: T): T {
+  // SAFETY: a JSON round trip of a JSON Schema, dropping one property.
+  return JSON.parse(JSON.stringify(schema), (_key, value: JsonValue) => {
+    if (
+      !isJsonObject(value) ||
+      !isJsonObject(value.properties) ||
+      !("repositoryId" in value.properties) ||
+      !("head" in value.properties)
+    )
+      return value;
+
+    const { repositoryId: _repositoryId, ...properties } = value.properties;
+
+    return {
+      ...value,
+      properties,
+      ...(Array.isArray(value.required) && {
+        required: value.required.filter((name) => name !== "repositoryId"),
+      }),
+    };
+  }) as T;
+}

package/src/review-api/azure-devops-provider.ts

@@ -1,6 +1,7 @@
 import { errorMessage } from "@dev.fast/trace-core";
 import { z } from "zod";
 
+import { azureRepositoryOf, slugOf } from "./azure-remote.js";
 import { ReviewInputError } from "./document.js";
 import type { PullRequestProvider } from "./provider.js";
 import { firstLine } from "./pull-request.js";
@@ -12,13 +13,6 @@ const PULL_REQUEST_URLS = [
   /^https:\/\/([A-Za-z0-9-]+)\.visualstudio\.com\/(?:DefaultCollection\/)?([^/]+)\/_git\/([^/]+)\/pullrequest\/([1-9]\d*)$/,
 ];
 
-const REMOTE_URLS = [
-  /^https:\/\/(?:[^@]+@)?dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+?)(?:\.git)?\/?$/,
-  /^https:\/\/([^.]+)\.visualstudio\.com\/(?:DefaultCollection\/)?([^/]+)\/_git\/([^/]+?)(?:\.git)?\/?$/,
-  /^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/,
-  /^[^@]+@vs-ssh\.visualstudio\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/,
-];
-
 const metadataSchema = z.object({
   title: z.string(),
   sourceRefName: z.string().min(1),
@@ -31,17 +25,6 @@ const metadataSchema = z.object({
   }),
 });
 
-/** org/project/repository, decoded; undefined for malformed escapes. */
-function slugOf(patterns: RegExp[], url: string) {
-  const match = patterns.map((pattern) => pattern.exec(url)).find(Boolean);
-
-  try {
-    return match && match.slice(1, 4).map(decodeURIComponent).join("/");
-  } catch {
-    return undefined;
-  }
-}
-
 function azFailure(url: string, failure: string) {
   const unreadable = (hint: string) =>
     new ReviewInputError(
@@ -162,8 +145,7 @@ export const azureDevOpsProvider: PullRequestProvider = {
 
   matchesRemote(remoteUrl, address) {
     return (
-      slugOf(REMOTE_URLS, remoteUrl.trim())?.toLowerCase() ===
-      address.slug.toLowerCase()
+      azureRepositoryOf(remoteUrl)?.toLowerCase() === address.slug.toLowerCase()
     );
   },
 };

package/src/review-api/azure-remote.ts

@@ -0,0 +1,21 @@
+const REMOTE_URLS = [
+  /^https:\/\/(?:[^@]+@)?dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+?)(?:\.git)?\/?$/,
+  /^https:\/\/([^.]+)\.visualstudio\.com\/(?:DefaultCollection\/)?([^/]+)\/_git\/([^/]+?)(?:\.git)?\/?$/,
+  /^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/,
+  /^[^@]+@vs-ssh\.visualstudio\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/,
+];
+
+/** org/project/repository, decoded; undefined for malformed escapes. */
+export function slugOf(patterns: RegExp[], url: string) {
+  const match = patterns.map((pattern) => pattern.exec(url)).find(Boolean);
+
+  try {
+    return match && match.slice(1, 4).map(decodeURIComponent).join("/");
+  } catch {
+    return undefined;
+  }
+}
+
+export function azureRepositoryOf(remoteUrl: string) {
+  return slugOf(REMOTE_URLS, remoteUrl.trim());
+}

package/src/review-api/blocks/definition.ts

@@ -13,7 +13,7 @@ export const identity = { id: text.optional() };
  * them reads its document's. */
 export const elementPins = sourcePinsSchema
   .optional()
-  .describe("Pins for the anchors here; needed on the scratchpad.");
+  .describe("Pins for the anchors here.");
 
 /**
  * One block kind: the strict schema the store parses with, and the rules a

package/src/review-api/blocks/markdown.ts

@@ -6,12 +6,12 @@ export const markdown = {
   type: "markdown",
   schema: defineBlock("markdown", {
     markdown: text.describe(
-      "Safe Markdown. Repository file links must use [label](review-source:head/path#L10-L24) or review-source:base/path#L10-L24, with a repository-relative path and verified line numbers. Relative paths, absolute filesystem paths, and file/editor URLs are rejected. External links use https://, http://, or mailto:; document anchors use #heading.",
+      "Safe Markdown. Repository file links must use [label](whiteboard:source/head/path#L10-L24) or whiteboard:source/base/path#L10-L24, or whiteboard:source/<commit>/path#L10-L24 at any commit of the board's repository, with a repository-relative path and verified line numbers. Link another board as [label](whiteboard:board/<sessionId>) or one of its blocks as whiteboard:board/<sessionId>#<blockId>; both must exist. Relative paths, absolute filesystem paths, and file/editor URLs are rejected. External links use https://, http://, or mailto:; document anchors use #heading.",
     ),
     pins: sourcePinsSchema
       .optional()
       .describe(
-        "Repository and commits this block's review-source links resolve against, instead of the document's pins.",
+        "Repository and commits this block's whiteboard:source/ links resolve against, instead of the document's pins.",
       ),
   }),
 } as const;