@vintasoftware/pr-review-canvas 0.1.0

package/src/canvas/zip.ts

@@ -0,0 +1,123 @@
+// The shared canvas format: a zip holding manifest.json and review.json at the root, and nothing
+// else. Everything that reads a zip goes through readCanvasZip, so a file from a teammate, from a
+// pull request attachment, and from the CLI is checked the same way.
+import { unzipSync, zipSync } from 'fflate'
+import { type CanvasManifest, CanvasManifestSchema } from '../contract/canvas-manifest.js'
+import { type ReviewArtifact, ReviewArtifactSchema } from '../contract/review-artifact.js'
+
+export const MANIFEST_ENTRY = 'manifest.json'
+export const REVIEW_ENTRY = 'review.json'
+export const CANVAS_ZIP_MAX_BYTES = 20 * 1024 * 1024
+/** `PK\x03\x04`, the first bytes of every zip. */
+export const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04] as const
+
+export interface CanvasZipContents {
+  manifest: CanvasManifest
+  artifact: ReviewArtifact
+}
+
+/** A zip that cannot be read as a canvas. `issues` names the problems, never the file's content. */
+export class CanvasZipError extends Error {
+  readonly code: 'CANVAS_INVALID' | 'CANVAS_TOO_LARGE'
+  readonly issues: string[]
+
+  constructor(code: 'CANVAS_INVALID' | 'CANVAS_TOO_LARGE', message: string, issues: string[] = []) {
+    super(message)
+    this.name = 'CanvasZipError'
+    this.code = code
+    this.issues = issues
+  }
+}
+
+export function hasZipMagic(bytes: Uint8Array): boolean {
+  return ZIP_MAGIC.every((byte, i) => bytes[i] === byte)
+}
+
+export function buildCanvasZip(manifest: CanvasManifest, artifact: ReviewArtifact): Uint8Array<ArrayBuffer> {
+  const encoder = new TextEncoder()
+  // Copied into a plain buffer, so the bytes can be handed straight to a Blob or a Response.
+  return Uint8Array.from(
+    zipSync(
+      {
+        [MANIFEST_ENTRY]: encoder.encode(`${JSON.stringify(manifest, null, 2)}\n`),
+        [REVIEW_ENTRY]: encoder.encode(`${JSON.stringify(artifact, null, 2)}\n`),
+      },
+      { level: 6, mtime: new Date(manifest.generatedAt) }
+    )
+  )
+}
+
+function decode(entry: Uint8Array | undefined, name: string, issues: string[]): unknown {
+  if (entry === undefined) {
+    issues.push(`${name} is missing from the zip`)
+    return null
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(entry)) as unknown
+  } catch {
+    issues.push(`${name} is not valid JSON`)
+    return null
+  }
+}
+
+/**
+ * The two entries of the zip, both schema-checked. Names with a directory part are ignored rather
+ * than written anywhere, so a zip carrying `../../etc/passwd` reads as a zip missing its entries.
+ */
+export function readCanvasZip(bytes: Uint8Array): CanvasZipContents {
+  if (bytes.length > CANVAS_ZIP_MAX_BYTES) {
+    throw new CanvasZipError('CANVAS_TOO_LARGE', `the canvas zip is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`)
+  }
+  if (!hasZipMagic(bytes)) {
+    throw new CanvasZipError('CANVAS_INVALID', 'this file is not a zip', [
+      'the file does not start with the zip signature',
+    ])
+  }
+  let entries: Record<string, Uint8Array>
+  // Only the first copy of each of the two root entries is inflated, and the two together may
+  // not claim more than the cap, so a small archive cannot inflate into gigabytes.
+  const taken = new Set<string>()
+  let claimed = 0
+  try {
+    entries = unzipSync(bytes, {
+      filter: file => {
+        if (file.name !== MANIFEST_ENTRY && file.name !== REVIEW_ENTRY) {
+          return false
+        }
+        if (taken.has(file.name) || claimed + file.originalSize > CANVAS_ZIP_MAX_BYTES) {
+          return false
+        }
+        taken.add(file.name)
+        claimed += file.originalSize
+        return true
+      },
+    })
+  } catch (err) {
+    throw new CanvasZipError('CANVAS_INVALID', 'the zip could not be read', [
+      err instanceof Error ? err.message : String(err),
+    ])
+  }
+  const issues: string[] = []
+  const rawManifest = decode(entries[MANIFEST_ENTRY], MANIFEST_ENTRY, issues)
+  const rawArtifact = decode(entries[REVIEW_ENTRY], REVIEW_ENTRY, issues)
+  if (issues.length > 0) {
+    throw new CanvasZipError('CANVAS_INVALID', 'the zip is not a review canvas', issues)
+  }
+  const manifest = CanvasManifestSchema.safeParse(rawManifest)
+  const artifact = ReviewArtifactSchema.safeParse(rawArtifact)
+  if (!manifest.success) {
+    issues.push(...manifest.error.issues.map(i => `${MANIFEST_ENTRY}: ${i.path.join('.')} ${i.message}`))
+  }
+  if (!artifact.success) {
+    issues.push(...artifact.error.issues.map(i => `${REVIEW_ENTRY}: ${i.path.join('.')} ${i.message}`))
+  }
+  if (!(manifest.success && artifact.success)) {
+    throw new CanvasZipError('CANVAS_INVALID', 'the zip is not a review canvas', issues)
+  }
+  if (artifact.data.pr.headSha !== manifest.data.headSha) {
+    throw new CanvasZipError('CANVAS_INVALID', 'the zip is not a review canvas', [
+      `${REVIEW_ENTRY} is for ${artifact.data.pr.headSha.slice(0, 7)} while ${MANIFEST_ENTRY} says ${manifest.data.headSha.slice(0, 7)}`,
+    ])
+  }
+  return { manifest: manifest.data, artifact: artifact.data }
+}

package/src/chat/chat-manager.ts

@@ -0,0 +1,389 @@
+// One turn at a time per pull request: build the prompt, run the agent, stream what it says,
+// 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 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'
+import type { ChatThread } from '../contract/state.js'
+import type { SettingsStore } from '../store/settings-store.js'
+import type { StateStore } from '../store/state-store.js'
+import { type ContextSources, renderChatContext } from './context.js'
+import { renderSeed, type SeedPaths } from './seed.js'
+import { NEW_THREAD_TITLE, nextThreadIndex, type TranscriptStore, threadName, threadTitle } from './threads.js'
+
+export class ChatBusyError extends Error {
+  constructor() {
+    super('a chat turn is already running for this pull request')
+    this.name = 'ChatBusyError'
+  }
+}
+
+export interface ChatManagerDeps {
+  runner: AgentRunner
+  settings: SettingsStore
+  state: StateStore
+  transcripts: TranscriptStore
+  repo: Repo
+  repoRoot: string
+  /** `serve --agent/--model`, which win over the settings file. */
+  overrides: SettingsOverrides
+  loadSeedTemplate: () => Promise<string>
+  now: () => Date
+}
+
+/** Everything about the pull request one turn needs, resolved by the route. */
+export interface ChatTarget {
+  prNumber: number
+  headSha: string
+  artifact: ReviewArtifact
+  files: FileEntry[]
+  patches: Record<string, string>
+  /** `<canvas>/derived`, which holds head/, base/ and patches/. */
+  derivedDir: string
+  readLines: ContextSources['readLines']
+}
+
+export interface ChatSendInput {
+  message: string
+  context: ChatContext
+  thread?: string | undefined
+}
+
+export interface ChatManager {
+  effectiveSettings(): Promise<Settings>
+  threads(prNumber: number): Promise<ChatThreadsResponse>
+  createThread(prNumber: number): Promise<ChatThread>
+  selectThread(prNumber: number, name: string): Promise<ChatThread | null>
+  send(target: ChatTarget, input: ChatSendInput): AsyncIterable<ChatEvent>
+  /** True when a turn was running and has been asked to stop. */
+  cancel(prNumber: number): Promise<boolean>
+  busy(prNumber: number): boolean
+}
+
+/** The slot a turn holds while it runs. The handle is filled in once the agent has started. */
+interface RunningTurn {
+  run: { cancel: () => Promise<void> } | null
+  /** True once a stop arrived, which can be before the agent has started. */
+  stopped: boolean
+}
+
+export function createChatManager(deps: ChatManagerDeps): ChatManager {
+  const running = new Map<number, RunningTurn>()
+
+  const effectiveSettings = async (): Promise<Settings> => {
+    const saved = await deps.settings.read()
+    return {
+      ...saved,
+      ...(deps.overrides.agent === undefined ? {} : { agent: deps.overrides.agent }),
+      ...(deps.overrides.model === undefined ? {} : { model: deps.overrides.model }),
+    }
+  }
+
+  const newThread = async (prNumber: number, agent: string): Promise<ChatThread> => {
+    const at = deps.now().toISOString()
+    let created: ChatThread | null = null
+    await deps.state.update(prNumber, state => {
+      const thread: ChatThread = {
+        name: threadName(deps.repo, prNumber, agent, nextThreadIndex(state.chat.threads)),
+        agent,
+        rev: 0,
+        title: NEW_THREAD_TITLE,
+        createdAt: at,
+        seededHeadSha: '',
+      }
+      created = thread
+      return { ...state, chat: { threads: [...state.chat.threads, thread], activeThread: thread.name } }
+    })
+    if (created === null) {
+      throw new Error('the thread was not created')
+    }
+    return created
+  }
+
+  /** The thread a message goes to: the one asked for, the active one, or a fresh one. */
+  const resolveThread = async (prNumber: number, agent: string, wanted?: string): Promise<ChatThread> => {
+    const state = await deps.state.read(prNumber)
+    const byName = wanted === undefined ? undefined : state.chat.threads.find(t => t.name === wanted)
+    const active =
+      byName ??
+      (state.chat.activeThread === undefined
+        ? undefined
+        : state.chat.threads.find(t => t.name === state.chat.activeThread))
+    // Changing the agent starts a new thread: the old session belongs to the old agent.
+    if (active === undefined || active.agent !== agent) {
+      return newThread(prNumber, agent)
+    }
+    if (state.chat.activeThread !== active.name) {
+      await deps.state.update(prNumber, current => ({
+        ...current,
+        chat: { ...current.chat, activeThread: active.name },
+      }))
+    }
+    return active
+  }
+
+  /**
+   * Writes the answer down. A turn the agent never took leaves the thread as it was, so the next
+   * try creates the session again and sends the seed again.
+   */
+  const saveTurn = async (
+    prNumber: number,
+    thread: ChatThread,
+    userText: string,
+    assistant: ChatTurn,
+    seededHeadSha: string,
+    reached: boolean
+  ): Promise<void> => {
+    await deps.transcripts.append(prNumber, thread.name, assistant)
+    if (!reached) {
+      return
+    }
+    await deps.state.update(prNumber, state => ({
+      ...state,
+      chat: {
+        ...state.chat,
+        threads: state.chat.threads.map(t =>
+          t.name === thread.name
+            ? {
+                ...t,
+                rev: t.rev + 1,
+                seededHeadSha,
+                // The first turn of a thread gives it its title.
+                title: t.rev === 0 ? threadTitle(userText) : t.title,
+              }
+            : t
+        ),
+      },
+    }))
+  }
+
+  /**
+   * Clears the mark that says this thread has been seeded. The agent lost the acpx session behind
+   * it, so the next turn creates the session again and sends the seed with it. The revision keeps
+   * counting the turns the thread has taken, which is what its title is keyed on.
+   */
+  const forgetSession = async (prNumber: number, name: string): Promise<void> => {
+    await deps.state.update(prNumber, state => ({
+      ...state,
+      chat: {
+        ...state.chat,
+        threads: state.chat.threads.map(t => (t.name === name ? { ...t, seededHeadSha: '' } : t)),
+      },
+    }))
+  }
+
+  async function* send(target: ChatTarget, input: ChatSendInput): AsyncIterable<ChatEvent> {
+    if (running.has(target.prNumber)) {
+      throw new ChatBusyError()
+    }
+    // The slot is taken before the first await, so a second request that arrives while this one
+    // is still reading the settings sees a busy chat rather than starting a second agent.
+    const slot: RunningTurn = { run: null, stopped: false }
+    running.set(target.prNumber, slot)
+    try {
+      yield* runTurn(target, input, slot)
+    } finally {
+      running.delete(target.prNumber)
+    }
+  }
+
+  async function* runTurn(target: ChatTarget, input: ChatSendInput, slot: RunningTurn): AsyncIterable<ChatEvent> {
+    const settings = await effectiveSettings()
+    const thread = await resolveThread(target.prNumber, settings.agent, input.thread)
+    const seeded = thread.seededHeadSha !== target.headSha
+    const at = deps.now().toISOString()
+    const contextBlock = await renderChatContext(input.context, {
+      artifact: target.artifact,
+      files: target.files,
+      patches: target.patches,
+      readLines: target.readLines,
+    })
+    const seed = seeded
+      ? `${renderSeed(await deps.loadSeedTemplate(), target.artifact, seedPaths(deps, target))}\n\n`
+      : ''
+    const prompt = `${seed}${contextBlock}\n\n## Question\n\n${input.message}\n`
+
+    // A thread that has never been seeded has no acpx session behind it either.
+    if (thread.seededHeadSha === '') {
+      await deps.runner.ensureSession({
+        agent: settings.agent,
+        session: thread.name,
+        cwd: deps.repoRoot,
+        timeoutSec: settings.chatTimeoutSec,
+      })
+    }
+
+    await deps.transcripts.append(target.prNumber, thread.name, {
+      role: 'user',
+      text: input.message,
+      at,
+      context: input.context,
+    })
+
+    // 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) {
+      await saveTurn(
+        target.prNumber,
+        thread,
+        input.message,
+        { role: 'assistant', text: '', at: deps.now().toISOString(), incomplete: 'cancelled' },
+        target.headSha,
+        // The seed never went anywhere, so the thread stays where it was.
+        false
+      )
+      yield { event: 'turn', thread: thread.name, agent: settings.agent, seeded }
+      yield { event: 'cancelled' }
+      return
+    }
+
+    const run = deps.runner.run({
+      agent: settings.agent,
+      session: thread.name,
+      prompt,
+      cwd: deps.repoRoot,
+      timeoutSec: settings.chatTimeoutSec,
+      model: settings.model ?? undefined,
+      maxTurns: settings.maxTurns ?? undefined,
+      // The runner scrubs the line before it gets here; this only writes it down.
+      onRawLine: line => {
+        void deps.transcripts.appendEvent(target.prNumber, thread.name, line).catch(() => undefined)
+      },
+    })
+    slot.run = run
+    // A stop between the spawn above and the loop below reaches the agent through its handle.
+    if (slot.stopped) {
+      void run.cancel().catch(() => undefined)
+    }
+
+    let answer = ''
+    let incomplete: string | undefined
+    let ended = false
+    try {
+      yield { event: 'turn', thread: thread.name, agent: settings.agent, seeded }
+      for await (const event of run.events) {
+        switch (event.type) {
+          case 'chunk':
+            answer += event.text
+            yield { event: 'chunk', text: event.text }
+            break
+          case 'thought':
+            yield { event: 'thought', text: event.text }
+            break
+          case 'tool':
+            yield { event: 'tool', id: event.id, title: event.title, status: event.status }
+            break
+          case 'done':
+            if (event.stopReason === 'cancelled') {
+              incomplete = 'cancelled'
+              yield { event: 'cancelled' }
+            } else if (event.stopReason === 'end_turn') {
+              yield { event: 'done', stopReason: event.stopReason }
+            } else {
+              incomplete = event.stopReason
+              yield {
+                event: 'error',
+                code: 'AGENT_INCOMPLETE',
+                message: `the agent stopped early (${event.stopReason})`,
+              }
+            }
+            break
+          case 'error':
+            incomplete = event.code
+            yield { event: 'error', code: event.code, message: event.message, ...hintFor(event.code) }
+            break
+          default:
+            break
+        }
+      }
+      ended = true
+    } finally {
+      // A reader that went away leaves the agent running, so the turn is stopped with it, and
+      // what it had said by then is a partial answer rather than the whole one.
+      if (!ended) {
+        incomplete ??= 'cancelled'
+        await run.cancel().catch(() => undefined)
+      }
+      await saveTurn(
+        target.prNumber,
+        thread,
+        input.message,
+        {
+          role: 'assistant',
+          text: answer,
+          at: deps.now().toISOString(),
+          ...(incomplete === undefined ? {} : { incomplete }),
+        },
+        target.headSha,
+        // An error before the agent said anything means the turn never reached it.
+        answer !== '' || incomplete === undefined || incomplete === 'cancelled'
+      )
+      if (incomplete === 'AGENT_NO_SESSION') {
+        await forgetSession(target.prNumber, thread.name)
+      }
+    }
+  }
+
+  return {
+    effectiveSettings,
+    async threads(prNumber) {
+      const [state, settings] = await Promise.all([deps.state.read(prNumber), effectiveSettings()])
+      return {
+        threads: state.chat.threads.map(t => ({
+          name: t.name,
+          agent: t.agent,
+          title: t.title,
+          createdAt: t.createdAt,
+        })),
+        activeThread: state.chat.activeThread ?? null,
+        agent: settings.agent,
+      }
+    },
+    async createThread(prNumber) {
+      const settings = await effectiveSettings()
+      return newThread(prNumber, settings.agent)
+    },
+    async selectThread(prNumber, name) {
+      const state = await deps.state.read(prNumber)
+      const thread = state.chat.threads.find(t => t.name === name)
+      if (thread === undefined) {
+        return null
+      }
+      await deps.state.update(prNumber, current => ({ ...current, chat: { ...current.chat, activeThread: name } }))
+      return thread
+    },
+    send,
+    async cancel(prNumber) {
+      const slot = running.get(prNumber)
+      if (slot === undefined) {
+        return false
+      }
+      // A turn whose agent has not started yet is stopped by the flag: `runTurn` reads it the
+      // moment it has a handle, so the stop is never lost to the setup it arrived during.
+      slot.stopped = true
+      await slot.run?.cancel()
+      return true
+    },
+    busy: prNumber => running.has(prNumber),
+  }
+}
+
+function seedPaths(deps: ChatManagerDeps, target: ChatTarget): SeedPaths {
+  return {
+    headDir: `${target.derivedDir}/head`,
+    baseDir: `${target.derivedDir}/base`,
+    patchDir: `${target.derivedDir}/patches`,
+    repoRoot: deps.repoRoot,
+  }
+}
+
+function hintFor(code: string): { hint?: string } {
+  if (code === 'AGENT_AUTH_REQUIRED') {
+    return { hint: 'log the agent in from a terminal, then try again' }
+  }
+  if (code === 'AGENT_MISSING') {
+    return { hint: 'install acpx and the agent CLI, then reload' }
+  }
+  return {}
+}

package/src/chat/context.ts

@@ -0,0 +1,160 @@
+// The block that goes above the reader's message: what they pointed at, in the agent's terms.
+// Every value is checked against the canvas first, so a made-up path never reaches a file read.
+import type { ChatContext } from '../contract/chat.js'
+import { chatContextLabel } from '../contract/chat.js'
+import type { FileEntry, Hunk, Layer, ReviewArtifact } from '../contract/review-artifact.js'
+
+/** A file's patch goes into the message up to this many lines; past it the agent reads the file. */
+export const INLINE_PATCH_MAX_LINES = 400
+/** A line range the reader can select and the agent can read in one block. */
+export const LINE_RANGE_MAX = 400
+
+export class ChatContextError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ChatContextError'
+  }
+}
+
+export interface ContextSources {
+  artifact: ReviewArtifact
+  files: readonly FileEntry[]
+  patches: Record<string, string>
+  /** Lines of a materialized file, or null when this head has none. */
+  readLines: (side: 'head' | 'base', path: string, from: number, to: number) => Promise<string[] | null>
+}
+
+function layerById(artifact: ReviewArtifact, id: string): Layer {
+  const layer = artifact.layers.find(l => l.id === id)
+  if (layer === undefined) {
+    throw new ChatContextError(`this canvas has no layer ${id}`)
+  }
+  return layer
+}
+
+function fileByPath(sources: ContextSources, path: string): FileEntry {
+  const entry = sources.files.find(f => f.path === path)
+  if (entry === undefined) {
+    throw new ChatContextError(`${path} is not a file of this pull request`)
+  }
+  return entry
+}
+
+/** The hunk a line sits in, on the side the reader selected. */
+export function enclosingHunk(entry: FileEntry, side: 'new' | 'old', line: number): Hunk | undefined {
+  return entry.hunks.find(h => {
+    const start = side === 'new' ? h.newStart : h.oldStart
+    // A hunk that adds lines shows none on the old side, and the other way round.
+    const count = side === 'new' ? h.newLines : h.oldLines
+    return count > 0 && line >= start && line < start + count
+  })
+}
+
+function fence(body: string, lang = ''): string {
+  return `\`\`\`${lang}\n${body}\n\`\`\``
+}
+
+function patchOf(sources: ContextSources, entry: FileEntry): string | null {
+  const patch = sources.patches[entry.key]
+  if (patch === undefined || patch === '') {
+    return null
+  }
+  return patch.split('\n').length > INLINE_PATCH_MAX_LINES ? null : patch
+}
+
+/**
+ * The context block for one message. The label is the same text the chip on screen shows, so the
+ * reader and the agent are talking about the same thing.
+ */
+export async function renderChatContext(context: ChatContext, sources: ContextSources): Promise<string> {
+  const label = chatContextLabel(
+    context,
+    id => sources.artifact.layers.find(l => l.id === id)?.title,
+    fp => sources.artifact.points.find(p => p.fingerprint === fp)?.title
+  )
+  switch (context.kind) {
+    case 'pr':
+      return '## Context: the whole pull request\n\nThe reader is asking about the pull request as a whole.'
+    case 'layer': {
+      const layer = layerById(sources.artifact, context.layerId)
+      const files = layer.files.map(f => `- \`${f.path}\` (${f.hunks.join(', ')})`).join('\n')
+      return [`## Context: ${label}`, '', layer.rationale, '', files === '' ? '_no files_' : files].join('\n')
+    }
+    case 'file': {
+      const entry = fileByPath(sources, context.path)
+      const patch = patchOf(sources, entry)
+      const body =
+        patch === null
+          ? `The patch is too long to inline. Read the file at the materialized head path for \`${entry.path}\`.`
+          : fence(patch, 'diff')
+      return [
+        `## Context: \`${entry.path}\``,
+        '',
+        `${entry.status}, +${entry.additions} −${entry.deletions}`,
+        '',
+        body,
+      ].join('\n')
+    }
+    case 'lines':
+      return renderLines(context, sources, label)
+    case 'point':
+      return renderPoint(context, sources)
+  }
+}
+
+/**
+ * An attention point: what it says, plus the lines it sits on. The agent needs the text to know
+ * what the reader is reacting to; the lines alone leave it guessing. One context, one heading.
+ */
+async function renderPoint(context: Extract<ChatContext, { kind: 'point' }>, sources: ContextSources): Promise<string> {
+  const point = sources.artifact.points.find(p => p.fingerprint === context.fingerprint)
+  if (point === undefined) {
+    throw new ChatContextError('this canvas has no such attention point')
+  }
+  const at: Extract<ChatContext, { kind: 'lines' }> = {
+    kind: 'lines',
+    path: point.path,
+    side: point.side === 'old' ? 'old' : 'new',
+    start: point.line,
+    end: point.endLine ?? point.line,
+  }
+  return [
+    `## Context: attention point — ${point.title}`,
+    '',
+    `${point.kind} · ${point.level}`,
+    '',
+    point.body,
+    '',
+    `It sits on ${chatContextLabel(at)}:`,
+    '',
+    await linesBody(at, sources),
+  ].join('\n')
+}
+
+async function renderLines(
+  context: Extract<ChatContext, { kind: 'lines' }>,
+  sources: ContextSources,
+  label: string
+): Promise<string> {
+  return `## Context: ${label}\n\n${await linesBody(context, sources)}`
+}
+
+/** The quoted lines and the hunk around them, with no heading of their own. */
+async function linesBody(context: Extract<ChatContext, { kind: 'lines' }>, sources: ContextSources): Promise<string> {
+  if (context.end < context.start) {
+    throw new ChatContextError('the last line of a selection comes after the first')
+  }
+  if (context.end - context.start + 1 > LINE_RANGE_MAX) {
+    throw new ChatContextError(`select at most ${LINE_RANGE_MAX} lines`)
+  }
+  const entry = fileByPath(sources, context.path)
+  const side = context.side === 'new' ? 'head' : 'base'
+  const lines = await sources.readLines(side, entry.path, context.start, context.end)
+  const hunk = enclosingHunk(entry, context.side, context.start)
+  const numbered =
+    lines === null || lines.length === 0
+      ? '_these lines are not available locally_'
+      : fence(lines.map((text, i) => `${context.start + i}: ${text}`).join('\n'))
+  const hunkBlock = hunk === undefined ? '' : `\n\nThe hunk around them is \`${hunk.id}\` (\`${hunk.header}\`).`
+  return `${numbered}${hunkBlock}`
+}