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

package/dist/tool-failure-C8zB73HV.js

@@ -0,0 +1,98 @@
+import { m as isStringValue, n as isJsonObject } from "./src-X9phtB2j.js";
+import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-CPQo7iTI.js";
+import { t as ReviewInputError } from "./input-error-OLgB_h31.js";
+//#region src/review-api/public-tools.ts
+function publicDescription(text) {
+	return text.replace(/\breview_(\w+)/g, "session_$1").replace(/\breviewId\b/g, "sessionId").replace(/\bReview\b/g, "Whiteboard").replace("The result carries review,", "The result carries session,");
+}
+/** Rewrite schema prose without changing property names, enum values or examples. */
+function translateSchemaDescriptions(value) {
+	if (Array.isArray(value)) {
+		value.forEach(translateSchemaDescriptions);
+		return;
+	}
+	if (!isJsonObject(value)) return;
+	for (const [key, item] of Object.entries(value)) if (key === "description" && isStringValue(item)) value[key] = publicDescription(item);
+	else if (![
+		"examples",
+		"default",
+		"const",
+		"enum"
+	].includes(key)) translateSchemaDescriptions(item);
+}
+/** Public vocabulary belongs to the agent boundary, not stored documents. */
+function publicTool(tool) {
+	const inputSchema = structuredClone(tool.inputSchema);
+	if (isJsonObject(inputSchema)) translateSchemaDescriptions(inputSchema);
+	inputSchema.properties = Object.fromEntries(Object.entries(inputSchema.properties ?? {}).map(([key, value]) => [key === "reviewId" ? "sessionId" : key, value]));
+	if (inputSchema.required) inputSchema.required = inputSchema.required.map((key) => key === "reviewId" ? "sessionId" : key);
+	return {
+		...tool,
+		name: tool.name.replace(/^review_/, "session_"),
+		description: publicDescription(tool.description),
+		inputSchema
+	};
+}
+/** Translate known response envelopes only; authored content is opaque. */
+function publicResult(value) {
+	if (Array.isArray(value)) return value.map(publicResult);
+	if (!isJsonObject(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+		return [key === "reviewId" ? "sessionId" : key === "review" ? "session" : key === "reviews" ? "sessions" : key, key === "review" || key === "reviews" ? publicResult(item) : item];
+	}));
+}
+async function callPublicTool(client, tool, input, signal) {
+	if ("reviewId" in input) throw new Error("Use sessionId with session tools.");
+	const { sessionId, ...rest } = input;
+	const fields = { ...rest };
+	if (sessionId !== void 0) fields.reviewId = sessionId;
+	const result = await callAuthoringTool(client, tool, fields, signal);
+	return result instanceof ToolText ? result : publicResult(result);
+}
+//#endregion
+//#region src/review-api/recovery.ts
+const RECOVERY = "Whiteboard is not running, so its tools and guidance are unavailable. Start Whiteboard Desktop (or `whiteboard server start` for headless use). If Whiteboard's tools still do not appear, reconnect the Whiteboard MCP server or start a new agent session.";
+//#endregion
+//#region src/review-api/tool-failure.ts
+/**
+* Sort a failed agent tool call into the CLI's closed error vocabulary, so
+* telemetry can tell an agent's bad input from a broken host. `connect`
+* covers reaching the host and reading its catalog; `call` is the tool itself.
+*/
+function toolFailure(error, phase) {
+	const status = error instanceof ReviewApiError || error instanceof ReviewInputError ? error.status : void 0;
+	if (status === 400) return {
+		errorName: "usage_error",
+		errorCategory: "user_input"
+	};
+	if (status === 401) return {
+		errorName: "desktop_connection_error",
+		errorCategory: "dependency"
+	};
+	if (status === 404) return {
+		errorName: "review_not_found",
+		errorCategory: "local_state"
+	};
+	if (status === 409) return {
+		errorName: "review_state_error",
+		errorCategory: "local_state"
+	};
+	if (status !== void 0) return {
+		errorName: "unexpected_error",
+		errorCategory: "internal"
+	};
+	if (phase === "connect") return {
+		errorName: "desktop_connection_error",
+		errorCategory: "dependency"
+	};
+	if (error instanceof Error && (error instanceof TypeError || error.name === "AbortError" || error.cause !== void 0)) return {
+		errorName: "network_error",
+		errorCategory: "transport"
+	};
+	return {
+		errorName: "unexpected_error",
+		errorCategory: "internal"
+	};
+}
+//#endregion
+export { publicTool as i, RECOVERY as n, callPublicTool as r, toolFailure as t };

package/dist/tutorial-trace-DrBvkaeL.js

@@ -0,0 +1,43 @@
+import { r as TUTORIAL_TRACE_SESSION_ID } from "./review-agent-traces-DNJFYzc8.js";
+//#region ../trace-core/src/tutorial-trace.ts
+function loadTutorialTrace() {
+	return {
+		parserVersion: "1",
+		descriptor: {
+			sessionId: TUTORIAL_TRACE_SESSION_ID,
+			harness: "codex",
+			available: true,
+			source: null,
+			subagents: [],
+			commits: []
+		},
+		traceName: null,
+		cacheStatus: "current",
+		subagents: [],
+		trace: {
+			harness: "codex",
+			title: "Shared agent chat server — illustrative tutorial session",
+			startedAt: null,
+			endedAt: null,
+			activeMs: null,
+			userTurns: 1,
+			toolCalls: 0,
+			events: [
+				{
+					kind: "user",
+					text: "Right now, each Review window manages its own agent chats, so opening the same thread in another window can show stale messages or start a duplicate session. I think we want to have one shared server / source of truth for all agent chats. Can you move session ownership and message history into the server, and have each window subscribe to updates? Closing a window should not end the conversation. Keep the existing chat UI, and make sure reconnecting shows the messages that arrived while the window was closed."
+				},
+				{
+					kind: "assistant",
+					markdown: "I'll make the server own each thread's agent session and message history. Windows will read that history and subscribe to new messages, so opening a thread in two windows attaches both to the same conversation."
+				},
+				{
+					kind: "assistant",
+					markdown: "Closing a window will detach its subscription without stopping the agent session. On reconnect, the window will catch up from the server's stored history before displaying live updates. I'll also check that simultaneous requests to open the same thread cannot create duplicate sessions."
+				}
+			]
+		}
+	};
+}
+//#endregion
+export { loadTutorialTrace };

package/instructions/authoring.md

@@ -0,0 +1,36 @@
+you are writing an interactive rfc-style whiteboard, for consumption by a staff engineer.
+
+**flow**
+follow these first five steps in order, with no tool calls beyond what they need: loading the tools they use (`session_create`, `session_activity_begin`, `session_edit`, `session_get`, and later `session_activity_update` and `session_activity_end`) and, for a PR, reading its description (`gh pr view`).
+- create the whiteboard, pinned to the commits/pr the user describes, naming the checkout by its `repositoryPath`. if they name none, use a `worktree` target with no `base`: it reviews the checkout, uncommitted work included, against the default branch. for uncommitted work only, pass `base: "HEAD"`. untracked files are left out: run `git add -N <file>` on new files you want reviewed
+- trigger a subagent with this exact instruction: "Call `session_get_instructions({topic:\"file-lenses\"})` and follow it for whiteboard <sessionId>, whose change is `<base>..<head>` in `<repositoryPath>`."
+- call `session_activity_begin` and pass its `activityId` on every `session_edit`
+- read the diff with git (or jj) in `repositoryPath`, at the commits `session_create` returned: `git diff <base> <head>`, or for a worktree target `git diff <base>` plus `git status` for untracked files. if it shows no changes, the target is wrong: fix it with `session_set_target` before writing
+- immediately after reading the diff (and the PR description) - put down a first pass at the what/why section.
+
+- whiteboard structure - each of these should be written as a top-level `section`, in this order:
+    - what/why: succinct description of what the change is, + why the change was made (if this context is available to you.)
+    - requirements: as given by the user, in their own words, if this context is available to you. otherwise, omit. write these as short bullet points
+    - design: how the solution works at the level of components, data and control flow, not functions.
+        - pick one diagram that best shows the shape of the change:
+            - `sequence` if participants interact over time (who calls whom, async handoffs)
+            - `flow_diagram` if the interesting part is branches, retries or state transitions
+            - `database_lens` if the interesting part is a schema change to the data stores, and/or who reads/writes it
+        - if the change is mostly a new/changed contract, show the key types / interfaces as `code_peek`(s)
+        plus the main decisions and tradeoffs, and alternatives considered if you have evidence for them (trace, PR discussion). skip for small changes whose design is self-evident.
+    - implementation: how the code delivers the design, at the level of functions and files. walk the changed code in the order a reader should follow it, starting with the entry point.
+        - `call_stack_diff` for the old vs. new path through user flows. always root the flows in the user/agent entry point (eg a button click, CLI command, etc.), including unchanged nodes along the way.
+        - `code_peek` for the few spots that carry the mechanism or an invariant; link everything else inline
+
+- before finishing, read the whole whiteboard back with `session_get({sessionId, full: true})` (without `full`, prose is cut short) and fix any contradictions/unverified claims.
+
+**updating existing whiteboard**
+- move the whiteboard to the new commits with `session_set_target`
+- read the existing whiteboard (if you haven't already,) read the diff since last whiteboard, make any necessary updates to the whiteboard.
+
+**guidelines**
+- IMPORTANT: Write incrementally. The user sees you write on the canvas in real-time. Show them visual progress every few seconds.
+- use `session_activity_update` to provide regular status updates on your area of focus.
+- keep whiteboards short and sweet when possible (esp. for small changes.) feel free to omit sections.
+- when something (a phrase in the prose, diagram node, etc.) describes actual code in the codebase, always default to attaching/hyperlink code.
+- Link repository code as `[label](review-source:head/src/file.ts#L10-L24)`; use `base` for old code. Use repository-relative paths and verified line numbers.

package/instructions/file-lenses.md

@@ -0,0 +1,13 @@
+you are grouping a code whiteboard's changed files into file lenses for the Diff view.
+
+**input:** a whiteboard id, and its change as `<base>..<head>` in a repository path.
+
+**flow**
+- call `session_activity_begin` before writing, pass its `activityId` on every `session_lens_edit`, and call `session_activity_end` when done.
+- call `session_lens_get`: before any lens exists, its `uncategorized` lists every changed file
+- categorize all the changes into buckets - leaving nothing in uncategorized changes by the end
+    - first, categorize away non-implementation code:  tests, docs, generated files and lockfiles, config and build, fixtures and snapshots, pure renames and moves, formatting-only changes, imports — all might be reasonable.
+    - then, when left with only implementation code, split it by the part of the design each file serves (e.g. the data model, an API, a UI surface), in the order a reader should take them. keep each lens small enough to read in one sitting, and don't split a file across lenses unless it holds two unrelated changes.
+
+**guidelines**
+- to see a file's changes, run `git diff <base> <head> -- <path>` in the repository. otherwise, rely on the file listing.

package/instructions/scratchpad.md

@@ -0,0 +1,23 @@
+# Scratchpad
+
+The scratchpad is one document in Whiteboard that is not a session for any change. It has no target, base, head or lifecycle. You draw on it the way you would sketch an explanation on a whiteboard: a short paragraph, a sequence or flow diagram, a call tree, a code peek, and the smallest view that makes the point. The user reads it in the app and copies blocks back to you.
+
+Its id is fixed: `scratchpad`. While it is turned on in Whiteboard Settings it always exists; never create, rename, delete, dismiss or share it.
+
+## When to draw here
+
+- The user asks to be shown how something works, wants a picture of a flow, a call path, a data shape or a layout, or is thinking out loud with you before there is a concrete plan.
+- The explanation spans more than one file or more than one repository, or would be an ASCII diagram in chat.
+
+Answer in chat when one sentence or one code line does it. Do not use the scratchpad to review a change; author a session instead (`session_get_instructions({})`).
+
+## How
+
+1. `session_capabilities({})`. Draw only when `desktopAvailable` and `scratchpadEnabled` are true. Otherwise answer in chat; if the pad is off, say once that it can be turned on in Whiteboard Settings.
+2. Every source reference needs pins. For each repository you will quote, `session_register_repository({path})` for its `repositoryId`, and `git rev-parse HEAD` (or the commit the user is looking at) for a commit id. Put `pins: {repositoryId, head}` on each block that quotes code (`code_peek`, `sequence`, `flow_diagram`, `call_stack_diff`, `database_lens` and `markdown` with `review-source:` links); a step, frame, attachment or operation that quotes other commits than its block takes its own `pins`. Add `base` only when an anchor reads the base side. A reference without pins is rejected, since the scratchpad has none to lend.
+3. Read what you cite at those commits, for example `git show <head>:<path>` in the repository, so line numbers match the pins.
+4. Call `session_activity_begin` and pass the `activityId` it returns on each `session_edit` as you append blocks. Omitted placement puts the block at the top of the pad, and the response's `targetId` names it. A thought that spans several blocks reads top-down only if you insert it bottom-up (last block first) or give each following block `afterId` of the block you just inserted. Draw a diagram whole in one insert; fix one you drew earlier by patching its nodes, edges or steps by ID, and `replace` a block only when the whole picture was wrong. Each block's fields are in the Components section below; read `session_get_instructions({topic:"authoring"})` for choosing components. End the activity when finished.
+5. After your first insert in a session, `session_open({sessionId: "scratchpad"})` once so the pad is showing. Do not call it again for later edits; they appear live.
+6. In chat, say in one line what you drew. Do not repeat the diagram there.
+
+Keep it a log, not a document: the newest thought sits at the top, above older ones. Do not build sections, outlines or status markers unless the user asks for structure. When the user asks to clear the pad, `replace` or `remove` its blocks; history keeps what was there.

package/instructions/trace-archaeology.md

@@ -0,0 +1,113 @@
+# Trace archaeology
+
+Agent-written commits record `Agent-Session: <id>` trailers. Use the `whiteboard trace` CLI to resolve and pull those sessions. Use FFF to find candidate events. Use `whiteboard trace show` for exact evidence.
+
+The `whiteboard trace` commands also work without Whiteboard installed or running.
+
+## Configuration
+
+Before hosted setup, explain: full transcripts go to the chosen origin. Writers can upload and check their own status; only admins can read transcripts.
+
+- Enable only user-authorized repositories and origins. Existing authorization is sufficient unless later revoked, including by `whiteboard trace deny`.
+- Check `whiteboard trace status`; `--agent-session <id>` narrows uploads. If authorized, run `whiteboard trace store create` when needed, then `whiteboard trace allow .`. Check status again.
+- Without authorization, leave capture off and continue read-only investigation. Trace lookup does not require publication.
+
+FFF setup is human-owned. If FFF is unavailable, report the setup gap. Do not replace or reconfigure it.
+
+Local commit trailers and blame resolution work without trace storage access.
+Read commands use the machine's selected trace store. When both an S3/R2
+bucket and the hosted store are configured, add `--storage s3|hosted` to
+read the other one; it changes nothing about capture or consent.
+
+## Explain code provenance
+
+When asked why code exists, who wrote it, or what decisions produced it:
+
+1. Identify the commits behind the target lines:
+
+   ```sh
+   whiteboard trace blame <file> -L <start,end> --json
+   ```
+
+   This command identifies the last commit that touched each line. Add `--history` only when the current provenance does not explain the decision:
+
+   ```sh
+   whiteboard trace blame <file> -L <start,end> --history --json
+   ```
+
+2. Pull each relevant session into the local corpus:
+
+   ```sh
+   whiteboard trace pull --agent-session <session-id> --json
+   ```
+
+   Read the absolute normalized file paths from the response's `paths` array. Do not derive them from the corpus layout.
+
+3. Use FFF to search the normalized files returned in `paths`.
+
+   Treat each result only as a candidate locator. Each trace file has this shape:
+
+   ```text
+   <owner>/<repo>/<session>/main.jsonl
+   <owner>/<repo>/<session>/<subagent>.jsonl
+   ```
+
+   Ignore physical line 1 because it is trace metadata. For a match on line `<L>`, use event index `<L> - 2`. Use the record's `index` when the excerpt shows it.
+
+4. Inspect each relevant event:
+
+   ```sh
+   whiteboard trace show <session-id> --trace <trace> --event <event> --json
+   ```
+
+   Pass the trace name from the result, including `main`. Search results are not final evidence.
+
+5. Check the current code before you explain the result. The trace can describe a decision that the author later reversed.
+
+This flow is complete when you inspected the relevant events and checked every historical claim against the current code.
+
+## Research a topic
+
+When asked if an agent has previously solved a problem or handled a topic:
+
+1. Pull the current repository traces:
+
+   ```sh
+   whiteboard trace pull --json
+   ```
+
+   Add `--main-only` only when subagent work is not relevant.
+   Read the absolute normalized file paths from the response's `paths` array.
+
+2. Use FFF to search the normalized files returned in `paths`. Read the session and trace from the result path. Ignore physical line 1. For a match on line `<L>`, use event index `<L> - 2`.
+
+3. Inspect the relevant events:
+
+   ```sh
+   whiteboard trace show <session-id> --trace <trace> --event <event> --json
+   ```
+
+When the investigation starts from one commit, list its sessions first:
+
+```sh
+whiteboard trace list --commit <rev> --json
+whiteboard trace pull --commit <rev> --json
+```
+
+When no commit anchors the investigation, page through every published session of the hosted store with `--cursor`. This command needs the hosted store; on a machine that selects s3, pass `--storage hosted`.
+
+```sh
+whiteboard trace sessions --json
+```
+
+Use `whiteboard trace show <session-id>` when the full session timeline helps explain the result.
+
+This flow is complete when you inspected the source events and checked the result against current code.
+
+## Evidence Rules
+
+- Treat traces as historical evidence, not current specifications.
+- Prefer `--json` when you parse command output.
+- Cite session, trace, and event locators for event evidence.
+- Cite commit IDs and source lines for current code evidence.
+- Report missing or uncertain provenance. Never invent an explanation.

package/onboarding.md

@@ -0,0 +1,8 @@
+# Whiteboard workflow
+
+1. Install Whiteboard Desktop; it installs the `whiteboard` CLI.
+2. Open Whiteboard Desktop. It hosts the JSON review server for this workflow.
+3. Run `whiteboard connect <agent>` and paste its prompt into the agent; the
+   agent adds the Whiteboard MCP server, which serves the authoring instructions.
+4. Ask the agent for a review. It authors the review through the Whiteboard MCP
+   tools or `whiteboard api`.

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@dev.fast/whiteboard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1-preview.20261005.98",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devdotfast/whiteboard.git",
+    "directory": "packages/review"
+  },
+  "bin": {
+    "review": "./dist/cli.js",
+    "whiteboard": "./dist/cli.js"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "onboarding.md",
+    "dist",
+    "instructions",
+    "tutorial",
+    "!tutorial/.bundle",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*test-utils*",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./sharing": {
+      "types": "./dist/sharing/index.d.ts",
+      "import": "./dist/sharing/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "0.84.0",
+    "@agentclientprotocol/codex-acp": "2.0.0",
+    "@agentclientprotocol/sdk": "1.5.1",
+    "@hono/node-server": "2.0.12",
+    "@img/sharp-wasm32": "0.35.4",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "commander": "14.0.3",
+    "fuzzysort": "4.0.2",
+    "hono": "4.13.7",
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-gfm": "3.1.0",
+    "mdast-util-math": "3.0.0",
+    "micromark-extension-gfm": "3.0.0",
+    "pi-acp": "0.0.34",
+    "pino": "10.3.1",
+    "semver": "7.8.5",
+    "sharp": "0.35.4",
+    "smol-toml": "1.8.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@dev.fast/diffr": "0.1.10",
+    "@dev.fast/local-vcs": "^0.1.0",
+    "@types/node": "24.12.2",
+    "@types/semver": "7.7.1",
+    "micromark-extension-math": "3.1.0",
+    "pino-pretty": "13.1.3",
+    "tsdown": "0.22.14",
+    "tsx": "4.21.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11",
+    "@dev.fast/json": "0.0.0",
+    "@dev.fast/review-protocol": "0.0.0",
+    "@dev.fast/review-share-protocol": "0.1.2",
+    "@dev.fast/trace-core": "0.0.0",
+    "@dev.fast/trace-protocol": "0.5.0"
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "intent": {
+    "version": 1,
+    "repo": "devdotfast/review",
+    "docs": "packages/review/instructions/authoring.md"
+  },
+  "gitHead": "2c6b8b5b8fe7c3435cf223f6a12a87e507ccf6f1",
+  "scripts": {
+    "prebuild": "pnpm run build:workspace-deps",
+    "ensure:diffr": "diffr-fetch --into bin",
+    "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",
+    "build:tutorial-assets": "tsx scripts/build-tutorial-assets.ts",
+    "ensure:tutorial-assets": "tsx scripts/ensure-tutorial-assets.ts",
+    "check:tutorial": "tsx scripts/check-tutorial.ts",
+    "build:workspace-deps": "pnpm --filter @dev.fast/json --filter @dev.fast/local-vcs --filter @dev.fast/review-protocol --filter @dev.fast/review-share-protocol --filter @dev.fast/trace-protocol --filter @dev.fast/trace-core build",
+    "pretypecheck": "pnpm run ensure:tutorial-assets",
+    "pretest": "pnpm run ensure:tutorial-assets",
+    "pretest:node": "pnpm run ensure:tutorial-assets",
+    "start": "tsx src/cli.ts",
+    "review": "tsx src/cli.ts",
+    "test": "vitest run --config vitest.config.ts",
+    "test:node": "vitest run --config vitest.config.ts --project shared-module-graph",
+    "test:telemetry-privacy": "vitest run --config vitest.config.ts src/ui-telemetry-events.test.ts src/error-telemetry.test.ts",
+    "typecheck": "pnpm -w exec tsc --noEmit -p packages/review",
+    "test:integration:diffr": "pnpm run build:workspace-deps && pnpm run ensure:diffr --required && vitest run --config vitest.integration.config.ts",
+    "whiteboard": "tsx src/cli.ts"
+  }
 }

package/src/agent-selection.ts

@@ -0,0 +1,100 @@
+import {
+  ReviewApiSelectionSourceSchema,
+  ReviewSelectedDiffSchema,
+} from "@dev.fast/review-protocol";
+import { z } from "zod";
+
+/** The most block text an anchor keeps; a selection in a longer block is
+ * not anchored. */
+export const ASK_ANCHOR_TEXT_LIMIT = 20_000;
+
+/** A semantic selection, independent of comment/thread creation. */
+export const AgentSelectionSchema = z.strictObject({
+  target: z.discriminatedUnion("kind", [
+    z.strictObject({
+      kind: z.literal("text"),
+      quote: z.string(),
+      /** Where the quote is: characters `start` to `end` of the text of the
+       * review block `blockId`, which was `text` then. The block keeps its
+       * id across versions; comparing its text then and now finds the quote
+       * again, or tells that it changed. */
+      anchor: z
+        .strictObject({
+          blockId: z.string().min(1).max(200),
+          start: z.number().int().nonnegative(),
+          end: z.number().int().positive(),
+          text: z.string().max(ASK_ANCHOR_TEXT_LIMIT),
+        })
+        .refine((anchor) => anchor.start < anchor.end, "an empty anchor")
+        .optional(),
+    }),
+    z.strictObject({
+      kind: z.literal("code"),
+      path: z.string(),
+      side: z.enum(["base", "head"]),
+      startLine: z.number().int().positive(),
+      endLine: z.number().int().positive(),
+    }),
+  ]),
+  title: z.string().max(500),
+  detail: z.string().max(24000).optional(),
+  revision: z.string().max(200).optional(),
+  selectedDiff: ReviewSelectedDiffSchema.optional(),
+  apiSource: ReviewApiSelectionSourceSchema.optional(),
+});
+
+export type AgentSelection = z.infer<typeof AgentSelectionSchema>;
+
+export function selectionMarkdown(
+  selection: AgentSelection,
+  sourceExcerpt = "",
+  diffPaths?: { base: string; head: string },
+): string {
+  const target = selection.target;
+
+  if (selection.selectedDiff)
+    return selectedDiffMarkdown(selection.selectedDiff, diffPaths);
+
+  if (target.kind === "text")
+    return target.quote
+      .split(/\r?\n/)
+      .map((line) => `> ${line}`)
+      .join("\n");
+
+  return [`## ${selection.title}`, selection.detail ?? "", sourceExcerpt]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function selectedDiffMarkdown(
+  diff: z.infer<typeof ReviewSelectedDiffSchema>,
+  paths?: { base: string; head: string },
+): string {
+  const oldCount = diff.rows.filter((row) => row.kind !== "added").length;
+  const newCount = diff.rows.filter((row) => row.kind !== "deleted").length;
+
+  const lines = diff.rows.map(
+    (row) =>
+      `${row.kind === "added" ? "+" : row.kind === "deleted" ? "-" : " "}${row.text}`,
+  );
+
+  // Keep Markdown source containing backtick fences inside this diff fence.
+  const fence = "`".repeat(
+    Math.max(
+      3,
+      ...lines.flatMap((line) =>
+        [...line.matchAll(/`+/g)].map((match) => match[0].length + 1),
+      ),
+    ),
+  );
+
+  return [
+    `Base: ${paths?.base ?? "a/"}`,
+    `Head: ${paths?.head ?? "b/"}`,
+    `Range: -${diff.oldStart},${oldCount} +${diff.newStart},${newCount}`,
+    "",
+    `${fence}diff`,
+    ...lines,
+    fence,
+  ].join("\n");
+}

package/src/agent-session-ref.ts

@@ -0,0 +1,80 @@
+export type ReviewAgentHarness = "claude-code" | "codex" | "opencode" | "pi";
+
+export interface SessionRef {
+  harness: ReviewAgentHarness;
+  sessionId: string;
+}
+
+export type EnvironmentValues = Readonly<Record<string, string | undefined>>;
+
+export const AUTHORING_AGENT_SESSION_ENV = "DEV_FAST_AGENT_SESSION";
+
+export function authoringSessionKey(ref: SessionRef): string {
+  return `${ref.harness}:${ref.sessionId}`;
+}
+
+export function parseAuthoringSessionKey(
+  value: string | null | undefined,
+): SessionRef | undefined {
+  const separator = value?.indexOf(":") ?? -1;
+
+  if (!value || separator < 1 || separator === value.length - 1) {
+    return undefined;
+  }
+
+  const harness = value.slice(0, separator);
+  const sessionId = value.slice(separator + 1);
+
+  return isReviewAgentHarness(harness) ? { harness, sessionId } : undefined;
+}
+
+export function resolveAuthoringSessionRef(
+  env: EnvironmentValues,
+): SessionRef | undefined {
+  const hosted = readEnvValue(env[AUTHORING_AGENT_SESSION_ENV]);
+
+  if (hosted) {
+    const ref = parseAuthoringSessionKey(hosted);
+
+    if (!ref) {
+      throw new Error(
+        `${AUTHORING_AGENT_SESSION_ENV} has an invalid authoring session reference.`,
+      );
+    }
+
+    return ref;
+  }
+
+  const codexThreadId = readEnvValue(env.CODEX_THREAD_ID);
+
+  if (codexThreadId) return { harness: "codex", sessionId: codexThreadId };
+
+  const claudeSessionId =
+    readEnvValue(env.CLAUDE_CODE_SESSION_ID) ??
+    readEnvValue(env.CLAUDE_SESSION_ID);
+
+  if (claudeSessionId) {
+    return { harness: "claude-code", sessionId: claudeSessionId };
+  }
+
+  const piSessionId = readEnvValue(env.PI_SESSION_ID);
+
+  if (piSessionId) return { harness: "pi", sessionId: piSessionId };
+
+  return undefined;
+}
+
+function isReviewAgentHarness(value: string): value is ReviewAgentHarness {
+  return (
+    value === "claude-code" ||
+    value === "codex" ||
+    value === "opencode" ||
+    value === "pi"
+  );
+}
+
+function readEnvValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+
+  return trimmed ? trimmed : undefined;
+}