@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/src/acpx/acpx.ts

@@ -4,7 +4,10 @@
  * `src/testing/fake-runner.ts` or spawn `src/testing/fake-acpx.mjs` through this adapter.
  */
 import { type ChildProcess, execFile, type SpawnOptions, spawn } from 'node:child_process'
+import { accessSync, constants } from 'node:fs'
+import path from 'node:path'
 import { promisify } from 'node:util'
+import { z } from 'zod'
 import {
   type AgentErrorCode,
   type AgentEvent,
@@ -13,6 +16,7 @@ import {
   mapAcpxMessage,
   scrubForLog,
 } from './events.js'
+import type { ModelUpgrades } from './models.js'
 import { createNdjsonSplitter, NdjsonError } from './ndjson.js'
 
 const execFileAsync = promisify(execFile)
@@ -23,6 +27,8 @@ export const ACPX_BIN = 'acpx'
 export const KILL_GRACE_MS = 3000
 /** A cancel that has not answered by then is given up on, and the child is killed instead. */
 export const CANCEL_TIMEOUT_SEC = 30
+/** `sessions show` reads a local record, so it answers fast or not at all. */
+export const SHOW_TIMEOUT_SEC = 20
 /** The runner's deadline sits this far past acpx's, so acpx reports its own timeout first. */
 export const DEADLINE_SLACK_MS = 15_000
 
@@ -68,6 +74,10 @@ export interface AgentRunner {
   acpxVersion(): Promise<string | null>
   /** Whether one agent's own CLI is installed and logged in. */
   availability(agent: string): Promise<{ installed: boolean; authenticated: boolean; reason?: string }>
+  /** Which models the agent's catalog says were replaced, and by what. Empty when it says nothing. */
+  modelUpgrades(agent: string): Promise<ModelUpgrades>
+  /** The model the named session last ran, or null when acpx does not say. */
+  sessionModel(options: { agent: string; session: string; cwd: string }): Promise<string | null>
 }
 
 /**
@@ -115,6 +125,10 @@ export function buildEnsureArgs(agent: string, session: string, cwd: string, tim
   return [...commonAcpxArgs(cwd, timeoutSec), agent, 'sessions', 'ensure', '-s', session]
 }
 
+export function buildShowArgs(agent: string, session: string, cwd: string): string[] {
+  return [...commonAcpxArgs(cwd, SHOW_TIMEOUT_SEC), agent, 'sessions', 'show', session]
+}
+
 export function buildExecArgs(agent: string, cwd: string, timeoutSec: number, prompt: string): string[] {
   return [...commonAcpxArgs(cwd, timeoutSec), agent, 'exec', prompt]
 }
@@ -125,16 +139,62 @@ const AUTH_CHECKS: Readonly<Record<string, { bin: string; args: string[] }>> = {
   codex: { bin: 'codex', args: ['login', 'status'] },
 }
 
+/** The part of `codex debug models` read here: each model and the one that replaced it. */
+const CodexCatalogSchema = z.object({
+  models: z.array(z.object({ slug: z.string(), upgrade: z.object({ model: z.string() }).nullish() })),
+})
+
+/** The part of `sessions show` read here: the model the session last ran. */
+const SessionRecordSchema = z.object({ acpx: z.object({ current_model_id: z.string().min(1) }) })
+
+/** The path `name` runs from on this PATH, or null when it is not there. */
+export function findOnPath(name: string, env: NodeJS.ProcessEnv): string | null {
+  for (const dir of (env['PATH'] ?? '').split(path.delimiter)) {
+    if (dir === '') {
+      continue
+    }
+    const candidate = path.join(dir, name)
+    try {
+      accessSync(candidate, constants.X_OK)
+      return candidate
+    } catch {
+      // Not in this directory.
+    }
+  }
+  return null
+}
+
+/**
+ * The environment acpx runs under. Without `CLAUDE_CODE_EXECUTABLE`, the Claude adapter runs the
+ * Claude Code build bundled with it, which can be months behind the installed one and so resolves
+ * `opus` to an older model. A value the user set already is kept.
+ */
+export function acpxEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  if (env['CLAUDE_CODE_EXECUTABLE'] !== undefined) {
+    return env
+  }
+  const claude = findOnPath('claude', env)
+  return claude === null ? env : { ...env, CLAUDE_CODE_EXECUTABLE: claude }
+}
+
 /** Only the one call shape the runner makes, so a test double is a plain function. */
 export type SpawnImpl = (file: string, args: string[], options: SpawnOptions) => ChildProcess
 export type ExecFileImpl = (
   file: string,
   args: string[],
-  options: { cwd?: string; timeout?: number; maxBuffer?: number; killSignal?: NodeJS.Signals }
+  options: {
+    cwd?: string
+    timeout?: number
+    maxBuffer?: number
+    killSignal?: NodeJS.Signals
+    env?: NodeJS.ProcessEnv
+  }
 ) => Promise<{ stdout: string; stderr: string }>
 
 export interface CreateAgentRunnerOptions {
   bin?: string
+  /** The environment acpx gets, before `acpxEnv` fills it in. Defaults to this process's. */
+  env?: NodeJS.ProcessEnv
   spawnImpl?: SpawnImpl
   execFileImpl?: ExecFileImpl
   /** How far the runner's own deadline sits past acpx's. Tests shorten it. */
@@ -189,6 +249,7 @@ function createEventQueue(): {
 
 export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRunner {
   const bin = opts.bin ?? ACPX_BIN
+  const env = acpxEnv(opts.env ?? process.env)
   const slackMs = opts.deadlineSlackMs ?? DEADLINE_SLACK_MS
   const cancelGraceMs = opts.cancelGraceMs ?? CANCEL_TIMEOUT_SEC * 1000
   const spawnImpl = opts.spawnImpl ?? spawn
@@ -201,9 +262,7 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
     args: string[],
     options: { cwd?: string; timeoutSec?: number; killSignal?: NodeJS.Signals } = {}
   ): Promise<{ ok: boolean; stdout: string; stderr: string; error?: unknown }> => {
-    const call: { cwd?: string; timeout?: number; maxBuffer?: number; killSignal?: NodeJS.Signals } = {
-      maxBuffer: 4 * 1024 * 1024,
-    }
+    const call: Parameters<ExecFileImpl>[2] = { maxBuffer: 4 * 1024 * 1024, env }
     if (options.cwd !== undefined) {
       call.cwd = options.cwd
     }
@@ -226,6 +285,7 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
     run(options) {
       return startRun(
         bin,
+        env,
         spawnImpl,
         options,
         // The cancel call gets its own timeout, and SIGKILL when it elapses: a cancel that hangs
@@ -307,6 +367,34 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
         reason: `\`${check.bin} ${check.args.join(' ')}\` failed; log in and try again`,
       }
     },
+
+    async modelUpgrades(agent) {
+      if (agent !== 'codex') {
+        return new Map()
+      }
+      // Codex keeps the catalog it last fetched on disk, so this answers in milliseconds.
+      const result = await execQuiet('codex', ['debug', 'models'], { timeoutSec: 20 })
+      // A failed call, output that is not JSON, and an unknown shape all mean no known upgrades.
+      try {
+        const catalog = CodexCatalogSchema.parse(JSON.parse(result.stdout))
+        return new Map(catalog.models.flatMap(m => (m.upgrade ? [[m.slug, m.upgrade.model] as const] : [])))
+      } catch {
+        return new Map()
+      }
+    },
+
+    async sessionModel(options) {
+      const result = await execQuiet(bin, buildShowArgs(options.agent, options.session, options.cwd), {
+        cwd: options.cwd,
+        timeoutSec: SHOW_TIMEOUT_SEC,
+      })
+      // A missing session prints an error line instead, which fails the schema like any other.
+      try {
+        return SessionRecordSchema.parse(JSON.parse(result.stdout)).acpx.current_model_id
+      } catch {
+        return null
+      }
+    },
   }
 }
 
@@ -367,6 +455,7 @@ export function readExecStream(stdout: string): {
 /** Spawns one prompt turn and turns its output into events. */
 function startRun(
   bin: string,
+  env: NodeJS.ProcessEnv,
   spawnImpl: SpawnImpl,
   options: AgentRunOptions,
   cancelCall: (args: string[]) => Promise<unknown>,
@@ -385,7 +474,11 @@ function startRun(
 
   let child: ChildProcess
   try {
-    child = spawnImpl(bin, buildPromptArgs(options), { cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'] })
+    child = spawnImpl(bin, buildPromptArgs(options), {
+      cwd: options.cwd,
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
   } catch {
     queue.push({ type: 'error', code: 'AGENT_MISSING', message: `${bin} could not be started` })
     queue.end()

package/src/acpx/models.ts

@@ -0,0 +1,43 @@
+/**
+ * A saved model id names a family, not a frozen version: every turn runs the newest model of it.
+ *
+ * Claude has family aliases (`opus`, `sonnet[1m]`, ...) that the Claude CLI resolves to its newest
+ * model, so a versioned id is rewritten to its alias. GPT has no aliases, and a family's next model can
+ * carry a new name (`gpt-5.6-terra` became `gpt-6-sol`), so the Codex catalog's own `upgrade` links
+ * are followed instead. `pin:<id>` opts out: the id after it is sent as written.
+ */
+
+export const PIN_PREFIX = 'pin:'
+
+/**
+ * `claude-opus-4-8`, `claude-sonnet-5[1m]`, `claude-haiku-4-5-20251001`. Bedrock and Vertex ids
+ * (`us.anthropic.claude-...`, `claude-...@date`) do not match, so they run as written too.
+ */
+const CLAUDE_VERSIONED = /^claude-(opus|sonnet|haiku|fable)-\d[\w.-]*?(\[[^\]]+\])?$/i
+
+/** A trailing `[...]` is a setting on the model (`[1m]`, `[high]`), kept across the upgrade. */
+const SUFFIX = /^([^[]+)(\[[^\]]+\])?$/
+
+/** Old model slug to the slug that replaced it, as the agent's catalog reports it. */
+export type ModelUpgrades = ReadonlyMap<string, string>
+
+export function latestModel(agent: string, model: string, upgrades: ModelUpgrades): string {
+  if (model.startsWith(PIN_PREFIX)) {
+    return model.slice(PIN_PREFIX.length).trim()
+  }
+  if (agent === 'claude') {
+    const versioned = CLAUDE_VERSIONED.exec(model)
+    return versioned === null ? model : `${versioned[1]?.toLowerCase()}${versioned[2] ?? ''}`
+  }
+  const parts = SUFFIX.exec(model)
+  if (parts?.[1] === undefined) {
+    return model
+  }
+  let slug = parts[1]
+  const seen = new Set([slug])
+  for (let next = upgrades.get(slug); next !== undefined && !seen.has(next); next = upgrades.get(slug)) {
+    seen.add(next)
+    slug = next
+  }
+  return `${slug}${parts[2] ?? ''}`
+}

package/src/chat/chat-manager.ts

@@ -2,6 +2,7 @@
 // and keep the transcript. The lock is what makes `CHAT_BUSY` a real answer rather than two
 // agents writing into one thread.
 import type { AgentRunner } from '../acpx/acpx.js'
+import { latestModel } from '../acpx/models.js'
 import type { ChatContext, ChatEvent, ChatThreadsResponse, ChatTurn } from '../contract/chat.js'
 import type { FileEntry, Repo, ReviewArtifact } from '../contract/review-artifact.js'
 import type { Settings, SettingsOverrides } from '../contract/settings.js'
@@ -75,6 +76,29 @@ interface RunningTurn {
   stopped: boolean
 }
 
+/**
+ * The `--model` of one turn: the newest model of the saved family. With no saved model the agent's
+ * own default applies, unless the session is on a model that has since been replaced: a thread
+ * started months ago, or a default set to an old id.
+ */
+async function modelForTurn(
+  runner: AgentRunner,
+  settings: Settings,
+  session: string,
+  cwd: string
+): Promise<string | undefined> {
+  const upgrades = await runner.modelUpgrades(settings.agent)
+  if (settings.model !== null) {
+    return latestModel(settings.agent, settings.model, upgrades)
+  }
+  const current = await runner.sessionModel({ agent: settings.agent, session, cwd })
+  if (current === null) {
+    return undefined
+  }
+  const latest = latestModel(settings.agent, current, upgrades)
+  return latest === current ? undefined : latest
+}
+
 export function createChatManager(deps: ChatManagerDeps): ChatManager {
   const running = new Map<ReviewKey, RunningTurn>()
 
@@ -232,6 +256,8 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       context: input.context,
     })
 
+    const model = await modelForTurn(deps.runner, settings, thread.name, deps.repoRoot)
+
     // A stop that arrived while the turn was setting up means no agent is started at all. The
     // transcript is written before the events, so a reader who leaves now still finds it there.
     if (slot.stopped) {
@@ -255,7 +281,7 @@ export function createChatManager(deps: ChatManagerDeps): ChatManager {
       prompt,
       cwd: deps.repoRoot,
       timeoutSec: settings.chatTimeoutSec,
-      model: settings.model ?? undefined,
+      model,
       maxTurns: settings.maxTurns ?? undefined,
       // The runner scrubs the line before it gets here; this only writes it down.
       onRawLine: line => {

package/src/cli.ts

@@ -1,6 +1,9 @@
+import { execFile } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
 import path from 'node:path'
+import { createInterface } from 'node:readline/promises'
 import { parseArgs } from 'node:util'
-import { createAgentRunner } from './acpx/acpx.js'
+import { ACPX_BIN, createAgentRunner, findOnPath } from './acpx/acpx.js'
 import {
   type CliIo,
   EXIT,
@@ -23,8 +26,10 @@ import { loadProjectConfig } from './project-config.js'
 import { checkSkill } from './review/doctor.js'
 import { type AppContext, createAppContext, readPackageVersion } from './server/context.js'
 import { startServer } from './server/node-server.js'
+import { PACKAGE_ROOT } from './paths.js'
 import { readJson } from './store/atomic-json.js'
 import { ensureDataDir } from './store/data-dir.js'
+import { type CommandResult, runUpgrade } from './upgrade.js'
 
 const SUBCOMMANDS = [
   'serve',
@@ -35,6 +40,7 @@ const SUBCOMMANDS = [
   'import',
   'install-skill',
   'doctor',
+  'upgrade',
 ] as const
 
 const USAGE = `usage: pr-review <command> [flags]
@@ -55,6 +61,9 @@ const USAGE = `usage: pr-review <command> [flags]
                    (both flags: the named commit is exported and the number stamps the zip)
   import <zip> [--pr <n>] [--force] [--repo <dir>] [--data-dir <dir>]
   doctor [--all-checks] [--repo <dir>] [--data-dir <dir>]
+  upgrade [--yes] [--only package,acpx,skill] [--repo <dir>]
+                   (updates pr-review and acpx with npm, and refreshes the project's skill copies;
+                    lists the changes and asks first unless --yes)
 
 Every command prints one JSON line on success and { "error": { code, message, hint } } on failure.
 Exit codes: 0 ok, 1 error, 2 usage, 4 gh/glab missing or not logged in, 5 invalid model output.
@@ -155,6 +164,52 @@ async function installSkillCommand(argv: string[]): Promise<number> {
   return runInstallSkill({ repoRoot, cwd }, rest, io)
 }
 
+function runCommand(file: string, args: string[]): Promise<CommandResult> {
+  return new Promise(resolve => {
+    execFile(file, args, { encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) =>
+      resolve({ ok: err === null, stdout, stderr })
+    )
+  })
+}
+
+async function confirmOnTerminal(question: string): Promise<boolean | null> {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) return null
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  try {
+    return /^y(es)?$/i.test((await rl.question(question)).trim())
+  } finally {
+    rl.close()
+  }
+}
+
+async function upgradeCommand(argv: string[]): Promise<number> {
+  const { repo, rest } = splitCommonFlags(argv)
+  const cwd = process.cwd()
+  let repoRoot: string | null
+  try {
+    repoRoot = await resolveRepoRoot(createGit(repo === undefined ? cwd : path.resolve(cwd, repo)))
+  } catch {
+    repoRoot = null
+  }
+  const pkg = JSON.parse(await readFile(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')) as { name: string }
+  return runUpgrade(
+    {
+      packageName: pkg.name,
+      version: readPackageVersion(),
+      packageRoot: PACKAGE_ROOT,
+      repoRoot,
+      acpxVersion: () => createAgentRunner().acpxVersion(),
+      acpxPath: findOnPath(ACPX_BIN, process.env),
+      run: runCommand,
+      runInstalled: args =>
+        runCommand(process.execPath, [path.join(PACKAGE_ROOT, 'bin', 'pr-review.mjs'), ...args]),
+      confirm: confirmOnTerminal,
+    },
+    rest,
+    io
+  )
+}
+
 export async function main(argv: string[]): Promise<number> {
   // `pnpm review -- --port 3011` forwards the `--` itself; drop it so parseArgs sees the flags.
   const [command, ...rest] = argv.filter(a => a !== '--')
@@ -174,6 +229,8 @@ export async function main(argv: string[]): Promise<number> {
         return await installSkillCommand(rest)
       case 'doctor':
         return await doctorCommand(rest)
+      case 'upgrade':
+        return await upgradeCommand(rest)
       default: {
         const { repo, dataDir, rest: own } = splitCommonFlags(rest)
         const ctx = await buildContext(repo, dataDir)

package/src/commands.ts

@@ -213,7 +213,11 @@ async function validateFile(
   }
   const artifact = ReviewArtifactSchema.safeParse(parsed.raw)
   const input = artifact.success ? artifactToModelOutput(artifact.data satisfies ReviewArtifact) : parsed.raw
-  const result = validateModelOutput(input, await validationInput(ctx, context, input))
+  // A stored canvas may predate the rules about what a generation must hide; only its correctness is checked.
+  const result = validateModelOutput(input, {
+    ...(await validationInput(ctx, context, input)),
+    storedArtifact: artifact.success,
+  })
   return { ok: result.ok, errors: result.errors }
 }
 

package/src/contract/api.ts

@@ -2,7 +2,7 @@ import type { z } from 'zod'
 import type { CanvasManifest } from './canvas-manifest.js'
 import type { CommentsPayload, IssueComment, ReviewComment } from './comments.js'
 import type { SharedCanvasInfoSchema } from './discovery.js'
-import type { FileEntry, Pr, ReviewArtifact } from './review-artifact.js'
+import type { FileEntry, FoldLevel, Pr, ReviewArtifact } from './review-artifact.js'
 import type { LocalKey, ReviewKey } from './review-key.js'
 import type { PrState } from './state.js'
 
@@ -123,6 +123,12 @@ export interface PrBundle {
   stale?: StaleInfo
   /** Set on a ready bundle whose canvas was generated for another commit with an identical diff. */
   carriedOver?: CarriedOverInfo
+  /**
+   * The canvas the reviewed marks on this page were made on, when they followed a line of descent
+   * onto this one; absent when none did. Not necessarily this canvas's own basis: the reviewer may
+   * have marked nothing on the canvases in between.
+   */
+  marksCarriedFrom?: string
   sharedCanvas?: SharedCanvasInfo
   skillCommand: string
   /** Set on a local review: work that has no pull request, so the forge side of the page is off. */
@@ -162,12 +168,20 @@ export interface ReviewSummary {
 export interface ReviewBodyResponse {
   headSha: string
   body: string
+  /** How many pending comments would go out with the review. */
+  pending: number
   /** The titles of the layers that still need a look; approve is refused while this is not empty. */
   unreviewed: string[]
 }
 
 export interface PostReviewResponse {
   review: ReviewSummary
+  comments: ReviewComment[]
+  warnings: string[]
+  /** How many pending comments went out with the review. */
+  submitted: number
+  /** The state after the pending review was cleared, so the page drops its drafts in one step. */
+  state: PrState
 }
 
 export interface PatchesResponse {
@@ -219,3 +233,14 @@ export interface ChatStatus {
 export interface HomeData {
   recentPrs: Array<{ number: number; title: string; updatedAt: string }>
 }
+
+/** The JSON the review page carries in its bootstrap script; the app reads it before any request. */
+export interface ReviewBootstrap {
+  prNumber: ReviewKey
+  owner: string
+  repo: string
+  version: string
+  host: PublicHost
+  /** The reading level the canvas opens at, from the settings file. */
+  foldLevel: FoldLevel
+}

package/src/contract/canvas-manifest.ts

@@ -23,6 +23,11 @@ export const CanvasIndexSchema = z.object({
       generatedAt: z.string(),
       source: z.enum(['local', 'import']),
       importedAt: z.string().optional(),
+      /**
+       * The canvas this one was generated from. Kept here as well as on the artifact so the line
+       * of descent can be walked from the index alone, without opening every canvas on the way.
+       */
+      basisCanvasSha: z.string().optional(),
       /** A snapshot of uncommitted work: it sits on no branch, so no pull request can claim it. */
       worktree: z.boolean().optional(),
     })

package/src/contract/generation-context.ts

@@ -2,7 +2,14 @@ import { z } from 'zod'
 import { DefaultLayerSchema, GenerationModeSchema, HighRiskRuleSchema } from '../project-config.js'
 import { DEFAULT_TEST_PATTERNS } from '../review/test-paths.js'
 import { type LocalKey, LocalKeySchema } from './review-key.js'
-import { FileEntrySchema, LIMITS, PrSchema, RepoSchema, type TextCaps } from './review-artifact.js'
+import {
+  FileEntrySchema,
+  LIMITS,
+  POINT_KINDS,
+  PrSchema,
+  RepoSchema,
+  type TextCaps,
+} from './review-artifact.js'
 
 /**
  * What `prepare` was asked to describe: a pull request, two refs, or one of the two reviews of
@@ -46,6 +53,48 @@ const capsShape = {
   diagram: z.number().int().positive(),
 } satisfies Record<keyof TextCaps, z.ZodNumber>
 
+/** Which files the head changes relative to the basis canvas's diff, by path. */
+export const FileDeltaSchema = z.object({
+  unchanged: z.array(z.string()),
+  changed: z.array(z.string()),
+  added: z.array(z.string()),
+  removed: z.array(z.string()),
+})
+export type FileDelta = z.infer<typeof FileDeltaSchema>
+
+export const BasisSplitLayerSchema = z.object({
+  key: z.string().min(1),
+  title: z.string(),
+  /** `carried` when the head touches none of the layer's files. */
+  status: z.enum(['carried', 're-judged']),
+  carriedFiles: z.array(z.string()),
+  reJudgedFiles: z.array(z.string()),
+})
+export type BasisSplitLayer = z.infer<typeof BasisSplitLayerSchema>
+
+export const BasisSplitPointSchema = z.object({
+  kind: z.enum(POINT_KINDS),
+  path: z.string().min(1),
+  title: z.string(),
+  status: z.enum(['carried', 're-judged']),
+})
+export type BasisSplitPoint = z.infer<typeof BasisSplitPointSchema>
+
+/**
+ * The basis canvas of an incremental run, already divided into what the head leaves untouched and
+ * what has to be decided anew. `prepare` computes it, so the generator reads two lists instead of
+ * comparing diffs itself, and `publish` records `canvasSha` on the canvas it stores.
+ */
+export const BasisSplitSchema = z.object({
+  canvasSha: z.string().regex(/^[0-9a-f]{40}$/),
+  /** Absolute path of the basis canvas's `review.json`, in the canvas store. */
+  reviewJsonPath: z.string().min(1),
+  files: FileDeltaSchema,
+  layers: z.array(BasisSplitLayerSchema),
+  points: z.array(BasisSplitPointSchema),
+})
+export type BasisSplit = z.infer<typeof BasisSplitSchema>
+
 /**
  * `context.json`: everything the agent and `publish` need about one prepared canvas. Written by
  * `prepare` next to `prompt.md`; `publish` validates `model.json` against the hunk index and the
@@ -87,6 +136,8 @@ export const GenerationContextSchema = z.object({
   smallPr: z.boolean(),
   /** More than 400 files or 50 000 changed lines: the prompt inlines nothing and tightens the caps. */
   largePr: z.boolean(),
+  /** Absent when this canvas is generated from a blank page: no basis, `--force`, or turned off. */
+  basis: BasisSplitSchema.optional(),
   preparedAt: z.string(),
 })
 export type GenerationContext = z.infer<typeof GenerationContextSchema>

package/src/contract/keys.ts

@@ -9,6 +9,7 @@ export {
   parseHunkId,
   parseLineId,
   pointAnchorId,
+  reviewedId,
   sanitizeKey,
   uniqueKey,
 } from '../../static/js/keys.js'

package/src/contract/pending.ts

@@ -0,0 +1,49 @@
+// A review the reviewer is still writing: comments kept on this machine until the review is
+// submitted, the way a pending review works on the forge's own page.
+import { z } from 'zod'
+import { SideSchema } from './review-artifact.js'
+import { COMMENT_BODY_MAX } from './comments.js'
+
+/**
+ * One comment waiting in the pending review. It names a line the way a posted inline comment
+ * does, so submitting it needs nothing the page has to look up again.
+ */
+export const PendingCommentSchema = z.object({
+  /** Local id, unique inside one target's state. Never a forge id: nothing was posted yet. */
+  id: z.string().min(1),
+  path: z.string().min(1),
+  line: z.number().int().positive(),
+  side: SideSchema,
+  /** The first line of a multi-line comment, absent when it covers one line. */
+  startLine: z.number().int().positive().optional(),
+  body: z.string().min(1).max(COMMENT_BODY_MAX),
+  /** Set when the comment came from an attention point, so the point can be marked posted. */
+  pointFingerprint: z.string().min(1).optional(),
+  /** The commit the reviewer was reading when they wrote it. */
+  headSha: z.string(),
+  createdAt: z.string(),
+  /** Creation time until the reviewer edits the draft. */
+  updatedAt: z.string(),
+})
+export type PendingComment = z.infer<typeof PendingCommentSchema>
+
+/** What the page sends to `POST /api/prs/:n/pending`. */
+export const AddPendingInputSchema = z.object({
+  path: z.string().min(1),
+  line: z.number().int().positive(),
+  side: SideSchema,
+  startLine: z.number().int().positive().optional(),
+  body: z.string().min(1).max(COMMENT_BODY_MAX),
+  pointFingerprint: z.string().min(1).optional(),
+  headSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
+})
+export type AddPendingInput = z.infer<typeof AddPendingInputSchema>
+
+/** What the page sends to `PATCH /api/prs/:n/pending/:id`. */
+export const EditPendingInputSchema = z.object({
+  body: z.string().min(1).max(COMMENT_BODY_MAX),
+})
+export type EditPendingInput = z.infer<typeof EditPendingInputSchema>