letagents 0.12.18 → 0.12.20

package/shared/local-room-knowledge.mjs

@@ -0,0 +1,53 @@
+import { assertKnowledgeReplay, RoomKnowledgeError } from './room-knowledge.mjs';
+
+export function initializeRoomKnowledge(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS local_room_knowledge (
+    room_id TEXT NOT NULL, id TEXT NOT NULL, type TEXT NOT NULL, version INTEGER NOT NULL,
+    value TEXT NOT NULL, PRIMARY KEY(room_id, id));
+    CREATE TABLE IF NOT EXISTS local_room_knowledge_revisions (
+    room_id TEXT NOT NULL, id TEXT NOT NULL, version INTEGER NOT NULL, value TEXT NOT NULL,
+    PRIMARY KEY(room_id, id, version));
+    CREATE TABLE IF NOT EXISTS local_room_knowledge_outbox (room_id TEXT NOT NULL, id TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY(room_id, id));`);
+}
+export function listLocalKnowledge(db, roomId, type) {
+  initializeRoomKnowledge(db);
+  const rows = db.prepare('SELECT value FROM local_room_knowledge WHERE room_id = ? AND type = ? ORDER BY json_extract(value, \'$.archived\') ASC, (json_extract(value, \'$.response\') IS NULL) DESC, json_extract(value, \'$.updated_at\') DESC LIMIT 201').all(roomId, type);
+  return { records: rows.slice(0, 200).map(row => JSON.parse(row.value)), truncated: rows.length > 200 };
+}
+export function getLocalKnowledge(db, roomId, id) {
+  initializeRoomKnowledge(db);
+  const row = db.prepare('SELECT value FROM local_room_knowledge WHERE room_id = ? AND id = ?').get(roomId, id);
+  return row ? JSON.parse(row.value) : null;
+}
+export function localKnowledgeHistory(db, roomId, id) {
+  initializeRoomKnowledge(db);
+  return db.prepare('SELECT value FROM local_room_knowledge_revisions WHERE room_id = ? AND id = ? ORDER BY version DESC LIMIT 100').all(roomId, id).map(row => JSON.parse(row.value));
+}
+export function saveLocalKnowledge(db, record, expectedVersion) {
+  initializeRoomKnowledge(db);
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const existing = getLocalKnowledge(db, record.room_id, record.id);
+    if (record.source_message_id) assertLocalKnowledgeSource(db, record);
+    if (expectedVersion === undefined && existing) {
+      const row = db.prepare('SELECT value FROM local_room_knowledge_revisions WHERE room_id = ? AND id = ? AND version = 1').get(record.room_id, record.id);
+      if (!row) throw new RoomKnowledgeError('The original version is unavailable. Please refresh.', 409);
+      const initial = JSON.parse(row.value);
+      assertKnowledgeReplay(initial, record);
+      db.exec('COMMIT');
+      return existing;
+    }
+    if (expectedVersion !== undefined && existing?.version !== expectedVersion) throw new RoomKnowledgeError('This changed since you opened it. Refresh to see the latest version.', 409);
+    db.prepare('INSERT INTO local_room_knowledge VALUES (?, ?, ?, ?, ?) ON CONFLICT(room_id, id) DO UPDATE SET version = excluded.version, value = excluded.value').run(record.room_id, record.id, record.type, record.version, JSON.stringify(record));
+    db.prepare('INSERT INTO local_room_knowledge_revisions VALUES (?, ?, ?, ?)').run(record.room_id, record.id, record.version, JSON.stringify(record));
+    if (record.type === 'attention' && record.response) db.prepare('INSERT OR IGNORE INTO local_room_knowledge_outbox VALUES (?, ?, ?)').run(record.room_id, record.id, JSON.stringify(record));
+    db.exec('COMMIT');
+    return record;
+  } catch (error) { db.exec('ROLLBACK'); throw error; }
+}
+
+function assertLocalKnowledgeSource(db, record) {
+  const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'local_chat_messages'").get();
+  const row = table && db.prepare("SELECT number FROM local_chat_messages WHERE room_id = ? AND number = ? AND NOT (COALESCE(agent_prompt_kind, '') = 'auto' AND TRIM(text) = '')").get(record.room_id, Number(record.source_message_id.slice(4)));
+  if (!row) throw new RoomKnowledgeError('The source message does not exist or is not visible in this local room.');
+}

package/shared/mcp-workspace-capture-worker.mjs

@@ -0,0 +1,41 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { mkdir, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { captureWorkspaceTree, captureWorkspacePair } from './workspace-turn-capture.mjs';
+import { encodeWorkspaceReview, REVIEW_PAGE_SIZE } from './workspace-review.mjs';
+
+// Git inspection and archive encoding never occupy the MCP transport's thread.
+// A process runs at most one capture worker; only small metadata crosses IPC.
+try {
+  const { capture, directory, text } = workerData;
+  const identity = `mcp-workspace:${capture.capture_id}`;
+  if (workerData.operation === 'begin') {
+    parentPort.postMessage({ baseline: await captureWorkspaceTree(capture.workspace, identity) });
+  } else {
+    const pair = await captureWorkspacePair(capture.workspace, capture.base_revision, capture.baseline, `${identity}:${capture.preparation_id}`);
+    pair.contribution.summary = text;
+    const { review, ...preview } = pair;
+    const summary = { version: 3, recorded_state: 'completed', evidence_incomplete: true, elapsed_ms: null,
+      operation_counts: { unresolved: 0, succeeded: 0, failed: 0, denied_before_start: 0,
+        cancelled_before_start: 0, interrupted_after_start: 0, lost_after_start: 0 }, ...preview };
+    let encoded = null;
+    let warning = capture.baseline ? null : 'The starting snapshot is unavailable; no exact change attribution is available.';
+    try { encoded = encodeWorkspaceReview(review); }
+    catch (error) {
+      if (!(error instanceof RangeError)) throw error;
+      warning = 'This capture exceeds the full-review size limit. Only its bounded preview is available.';
+    }
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (encoded) {
+      await writeFile(join(directory, 'review.tmp'), encoded.data, { mode: 0o600 });
+      await rename(join(directory, 'review.tmp'), join(directory, 'review'));
+    }
+    const prepared = { summary, text, warning,
+      archive: encoded ? { digest: encoded.digest, length: encoded.data.length, total: Math.ceil(encoded.data.length / REVIEW_PAGE_SIZE) } : null };
+    await writeFile(join(directory, 'prepared.tmp'), JSON.stringify(prepared), { mode: 0o600 });
+    await rename(join(directory, 'prepared.tmp'), join(directory, 'prepared.json'));
+    parentPort.postMessage({ prepared: true });
+  }
+} catch {
+  parentPort.postMessage({ error: 'Workspace capture could not finish. Retry with the same capture_id.' });
+}

package/shared/room-agent-work.d.mts

@@ -1,7 +1,10 @@
+import type { WorkspaceChangeSummary } from "./workspace-change-summary.mjs";
 export const ROOM_WORK_STATES: readonly ["active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown"];
 export const ROOM_WORK_OPERATION_OUTCOMES: readonly ["unresolved", "succeeded", "failed", "denied_before_start", "cancelled_before_start", "interrupted_after_start", "lost_after_start"];
 export type RoomAgentWorkSummary = {
-  version: 1;
+  version: 1 | 2 | 3;
+  contribution?: { changes: WorkspaceChangeSummary; summary: string | null };
+  workspace?: WorkspaceChangeSummary;
   recorded_state: typeof ROOM_WORK_STATES[number];
   evidence_incomplete: boolean;
   elapsed_ms: number | null;

package/shared/room-agent-work.mjs

@@ -1,6 +1,7 @@
-// Room-public, host-reported evidence; never execution or approval authority.
-// No free-form strings, native handles, paths, command text, or output belong
-// in this version. Both the publisher and server use this strict boundary.
+import { parseWorkspaceChangeSummary } from './workspace-change-summary.mjs';
+// v1 is numeric execution evidence. v2 additionally carries a bounded,
+// deliberately room-visible workspace review snapshot. v3 separates changes
+// during one turn from the cumulative workspace, with an optional public summary.
 export const ROOM_WORK_STATES = [
   "active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown",
 ];
@@ -21,8 +22,22 @@ export function isClearedRoomAgentWorkSummary(value) {
 
 /** Return a canonical allowlisted copy, or reject without echoing private input. */
 export function parseRoomAgentWorkSummary(value) {
-  if (!exactKeys(value, ["version", "recorded_state", "evidence_incomplete", "elapsed_ms", "operation_counts"])
-    || value.version !== 1 || !ROOM_WORK_STATES.includes(value.recorded_state)
+  const workspace = [2, 3].includes(value?.version) ? parseWorkspaceChangeSummary(value.workspace) : null;
+  const keys = ["version", "recorded_state", "evidence_incomplete", "elapsed_ms", "operation_counts"];
+  if ([2, 3].includes(value?.version)) keys.push("workspace");
+  let contribution = null;
+  if (value?.version === 3) {
+    keys.push("contribution");
+    const candidate = value.contribution;
+    if (!exactKeys(candidate, ["changes", "summary"]) || !(candidate.summary === null
+      || typeof candidate.summary === "string" && candidate.summary.length <= 400)) return null;
+    const changes = parseWorkspaceChangeSummary(candidate.changes);
+    if (!changes) return null;
+    contribution = { changes, summary: candidate.summary };
+    if (new TextEncoder().encode(JSON.stringify(value)).length > 500 * 1024) return null;
+  }
+  if (!exactKeys(value, keys)
+    || ![1, 2, 3].includes(value.version) || (value.version >= 2 && !workspace) || !ROOM_WORK_STATES.includes(value.recorded_state)
     || typeof value.evidence_incomplete !== "boolean"
     || (value.elapsed_ms !== null && (!Number.isSafeInteger(value.elapsed_ms) || Number(value.elapsed_ms) < 0))
     || !exactKeys(value.operation_counts, ROOM_WORK_OPERATION_OUTCOMES)) return null;
@@ -37,7 +52,9 @@ export function parseRoomAgentWorkSummary(value) {
   // A bounded evidence snapshot, not an unbounded lifetime counter.
   if (total > 10_000) return null;
   return {
-    version: 1, recorded_state: value.recorded_state,
+    version: value.version, recorded_state: value.recorded_state,
+    ...(workspace ? { workspace } : {}),
+    ...(contribution ? { contribution } : {}),
     evidence_incomplete: value.evidence_incomplete, elapsed_ms: value.elapsed_ms,
     operation_counts: counts,
   };

package/shared/room-knowledge.d.mts

@@ -0,0 +1,25 @@
+export type KnowledgeType = 'memory' | 'attention';
+export type MemoryCategory = 'goal' | 'decision' | 'constraint' | 'term' | 'reference';
+export type AttentionCategory = 'question' | 'decision' | 'approval' | 'review';
+export interface KnowledgeActor { id: string; label: string; kind: 'human' | 'agent' }
+export interface KnowledgeInput {
+  category: MemoryCategory | AttentionCategory; title: string; body: string;
+  recommendation?: string; unblocks?: string; source_url?: string; source_message_id?: string;
+}
+export interface KnowledgeRecord extends Required<KnowledgeInput> {
+  id: string; room_id: string; type: KnowledgeType; version: number;
+  author: KnowledgeActor; updated_by: KnowledgeActor; created_at: string; updated_at: string; archived: boolean;
+  response: { body: string; actor: KnowledgeActor; at: string } | null;
+}
+export interface KnowledgePage { records: KnowledgeRecord[]; truncated: boolean }
+export interface KnowledgeRevisionInput extends Partial<KnowledgeInput> { expected_version: number; response?: string; archived?: boolean }
+export const MEMORY_CATEGORIES: MemoryCategory[];
+export const ATTENTION_CATEGORIES: AttentionCategory[];
+export class RoomKnowledgeError extends Error { status: number; constructor(message: string, status?: number) }
+export function parseKnowledgeInput(type: KnowledgeType, value: unknown): Required<KnowledgeInput>;
+export function knowledgeId(value: unknown): string;
+export function createKnowledgeRecord(room_id: string, type: KnowledgeType, input: KnowledgeInput & { client_id: string }, author: KnowledgeActor, now?: string): KnowledgeRecord;
+export function reviseKnowledgeRecord(record: KnowledgeRecord, input: KnowledgeRevisionInput, actor: KnowledgeActor, now?: string): KnowledgeRecord;
+export function assertKnowledgeReplay(existing: KnowledgeRecord, candidate: KnowledgeRecord): void;
+
+export function formatAttentionResponse(record: KnowledgeRecord): string;

package/shared/room-knowledge.mjs

@@ -0,0 +1,74 @@
+export const MEMORY_CATEGORIES = ['goal', 'decision', 'constraint', 'term', 'reference'];
+export const ATTENTION_CATEGORIES = ['question', 'decision', 'approval', 'review'];
+
+export class RoomKnowledgeError extends Error {
+  constructor(message, status = 400) { super(message); this.status = status; }
+}
+
+function text(value, name, max, required = false) {
+  if (value == null && !required) return '';
+  if (typeof value !== 'string' || value.length > max || (required && !value.trim())) {
+    throw new RoomKnowledgeError(`${name} must be ${required ? 'nonempty text' : 'text'} of at most ${max} characters.`);
+  }
+  return value.trim();
+}
+
+export function parseKnowledgeInput(type, value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new RoomKnowledgeError('A record is required.');
+  const categories = type === 'memory' ? MEMORY_CATEGORIES : type === 'attention' ? ATTENTION_CATEGORIES : [];
+  if (!categories.includes(value.category)) throw new RoomKnowledgeError('Choose a valid category.');
+  const source_url = text(value.source_url, 'Source URL', 2048);
+  if (source_url) {
+    let url;
+    try { url = new URL(source_url); } catch { throw new RoomKnowledgeError('Source URL must be an HTTP or HTTPS link.'); }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new RoomKnowledgeError('Source URL must be an HTTP or HTTPS link without credentials.');
+  }
+  const source_message_id = text(value.source_message_id, 'Source message', 40);
+  if (source_message_id && (!/^msg_[1-9]\d{0,9}$/.test(source_message_id) || Number(source_message_id.slice(4)) > 2147483647)) throw new RoomKnowledgeError('Invalid source message.');
+  return {
+    category: value.category,
+    title: text(value.title, 'Title', 160, true),
+    body: text(value.body, 'Context', 8000, true),
+    recommendation: type === 'attention' ? text(value.recommendation, 'Recommendation', 2000) : '',
+    unblocks: type === 'attention' ? text(value.unblocks, 'What this unblocks', 1000) : '',
+    source_url,
+    source_message_id,
+  };
+}
+
+export function knowledgeId(value) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9_-]{8,80}$/.test(value)) throw new RoomKnowledgeError('Use a stable client ID of 8–80 letters, numbers, underscores or hyphens.');
+  return value;
+}
+
+export function createKnowledgeRecord(room_id, type, input, author, now = new Date().toISOString()) {
+  return { ...parseKnowledgeInput(type, input), id: knowledgeId(input.client_id), room_id, type,
+    version: 1, author, updated_by: author, created_at: now, updated_at: now,
+    archived: false, response: null };
+}
+
+export function reviseKnowledgeRecord(record, input, actor, now = new Date().toISOString()) {
+  if (input.expected_version !== record.version) throw new RoomKnowledgeError('This changed since you opened it. Refresh to see the latest version.', 409);
+  if (actor.kind !== 'human') throw new RoomKnowledgeError('Only a human can revise shared memory or answer a request.', 403);
+  if (record.type === 'attention') {
+    if (record.response) throw new RoomKnowledgeError('This request has already been answered.', 409);
+    return { ...record, version: record.version + 1, updated_at: now, updated_by: actor,
+      response: { body: text(input.response, 'Response', 8000, true), actor, at: now } };
+  }
+  if (input.archived !== undefined && typeof input.archived !== 'boolean') throw new RoomKnowledgeError('Archived must be true or false.');
+  const content = input.archived !== undefined ? {} : parseKnowledgeInput('memory', input);
+  return { ...record, ...content, archived: input.archived ?? record.archived,
+    version: record.version + 1, updated_at: now, updated_by: actor };
+}
+
+export function assertKnowledgeReplay(existing, candidate) {
+  const keys = ['type', 'category', 'title', 'body', 'recommendation', 'unblocks', 'source_url', 'source_message_id'];
+  if (existing.author.id !== candidate.author.id || existing.author.kind !== candidate.author.kind || keys.some(key => existing[key] !== candidate[key])) {
+    throw new RoomKnowledgeError('This client ID was already used for different content. Use a new ID for a new record.', 409);
+  }
+}
+
+export function formatAttentionResponse(record) {
+  const handle = record.author.kind === 'agent' ? record.author.id.trim().replace(/[A-Z]/g, c => c.toLowerCase()).replace(/[^a-z0-9_.:/-]+/g, '') : '';
+  return `${handle ? `@agent:${handle}\n\n` : ''}Human response (${record.id}):\n\n${record.response.body}`;
+}

package/shared/workspace-change-capture.d.mts

@@ -0,0 +1,2 @@
+import type { WorkspaceChangeSummary } from './workspace-change-summary.mjs';
+export function captureWorkspaceChanges(workspace: string, startingRevision: string | null, settledTree?: string, fullReview?: boolean): Promise<WorkspaceChangeSummary>;

package/shared/workspace-change-capture.mjs

@@ -0,0 +1,147 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { open, readlink, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { WORKSPACE_FILE_LIMIT, WORKSPACE_PATCH_LIMIT, parseWorkspaceChangeSummary } from './workspace-change-summary.mjs';
+const execute = promisify(execFile);
+async function git(cwd, args, limit = 4 * 1024 * 1024) {
+    const result = await execute('git', ['--no-optional-locks', ...args], {
+        cwd, encoding: 'utf8', timeout: 5_000, maxBuffer: limit,
+        env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))), GIT_TERMINAL_PROMPT: '0' },
+    });
+    return result.stdout;
+}
+/** Reads the actual provider workspace; never stages, commits, or changes its index. */
+export async function captureWorkspaceChanges(workspace, startingRevision, settledTree, fullReview = false) {
+    const patchLimit = fullReview ? 128 * 1024 * 1024 : WORKSPACE_PATCH_LIMIT;
+    const fileLimit = fullReview ? 10_000 : WORKSPACE_FILE_LIMIT;
+    const empty = (state) => ({
+        captured_at: new Date().toISOString(), branch: null, base_revision: null, state,
+        files: [], additions: 0, deletions: 0, hidden_files: 0, patch: '', patch_truncated: false,
+    });
+    try {
+        if ((await git(workspace, ['rev-parse', '--is-inside-work-tree'])).trim() !== 'true')
+            return empty('not_git');
+    }
+    catch (error) {
+        return empty(/not a git repository/i.test(String(error.stderr ?? '')) ? 'not_git' : 'unavailable');
+    }
+    try {
+        if (startingRevision !== null && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(startingRevision))
+            return empty('unavailable');
+        const branch = await git(workspace, ['symbolic-ref', '--quiet', '--short', 'HEAD']).then(value => value.trim(), () => null);
+        if (settledTree && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(settledTree))
+            return empty('unavailable');
+        const base = await git(workspace, ['rev-parse', '--verify', `${startingRevision ?? 'HEAD'}^{tree}`])
+            .then(value => value.trim(), error => { if (startingRevision)
+            throw error; return null; });
+        const diffArgs = ['--no-ext-diff', '--no-textconv', '--no-color', '-M'];
+        const [names, stats, untracked] = await Promise.all([
+            base ? git(workspace, ['diff', ...diffArgs, '--name-status', '-z', base, ...(settledTree ? [settledTree] : []), '--']) : Promise.resolve(''),
+            base ? git(workspace, ['diff', ...diffArgs, '--numstat', '-z', base, ...(settledTree ? [settledTree] : []), '--']) : Promise.resolve(''),
+            settledTree ? Promise.resolve('') : git(workspace, ['ls-files', '--others', '--exclude-standard', ...(base ? [] : ['--cached']), '-z']),
+        ]);
+        const files = new Map();
+        const nameParts = names.split('\0');
+        for (let i = 0; i < nameParts.length - 1;) {
+            const code = nameParts[i++];
+            const first = nameParts[i++];
+            const renamed = code.startsWith('R') || code.startsWith('C');
+            const path = renamed ? nameParts[i++] : first;
+            const status = { A: 'added', M: 'modified', D: 'deleted', R: 'renamed', C: 'copied', T: 'typechange' }[code[0]] ?? 'unknown';
+            files.set(path, { path, previous_path: renamed ? first : null, status, additions: 0, deletions: 0, binary: false });
+        }
+        const statParts = stats.split('\0');
+        for (let i = 0; i < statParts.length; i++) {
+            const match = /^([^\t]+)\t([^\t]+)\t([\s\S]*)$/.exec(statParts[i]);
+            if (!match)
+                continue;
+            let path = match[3];
+            if (!path) {
+                path = statParts[i + 2];
+                i += 2;
+            }
+            const file = files.get(path);
+            if (!file)
+                continue;
+            file.binary = match[1] === '-' || match[2] === '-';
+            file.additions = file.binary ? 0 : Number(match[1]);
+            file.deletions = file.binary ? 0 : Number(match[2]);
+        }
+        let patch = '';
+        let truncated = false;
+        if (base) {
+            try {
+                patch = await git(workspace, ['diff', ...diffArgs, '--unified=3', base, ...(settledTree ? [settledTree] : []), '--'], patchLimit);
+            }
+            catch (error) {
+                const failure = error;
+                if (failure.code !== 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
+                    throw error;
+                patch = String(failure.stdout ?? '').slice(0, patchLimit);
+                truncated = true;
+            }
+        }
+        const newPaths = [...new Set(untracked.split('\0').filter(Boolean))];
+        let inspectedFiles = 0;
+        for (const path of newPaths) {
+            if (files.has(path))
+                continue;
+            const file = { path, previous_path: null, status: base ? 'untracked' : 'added', additions: 0, deletions: 0, binary: false };
+            files.set(path, file);
+            if (++inspectedFiles > fileLimit) {
+                truncated = true;
+                continue;
+            }
+            // Do not follow symlinks into files outside the workspace.
+            const absolute = join(workspace, path);
+            const metadata = await lstat(absolute);
+            let bytes;
+            if (metadata.isSymbolicLink())
+                bytes = Buffer.from(await readlink(absolute));
+            else if (metadata.isFile() && metadata.size <= 1024 * 1024) {
+                const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const buffer = Buffer.alloc(1024 * 1024 + 1);
+                    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                    bytes = buffer.subarray(0, bytesRead);
+                    if (bytesRead > 1024 * 1024) {
+                        truncated = true;
+                        continue;
+                    }
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            else {
+                truncated = true;
+                continue;
+            }
+            file.binary = bytes.includes(0);
+            if (file.binary)
+                continue;
+            const text = bytes.toString('utf8');
+            const lines = text ? text.replace(/\n$/, '').split('\n') : [];
+            file.additions = lines.length;
+            if (patch.length < patchLimit) {
+                const label = JSON.stringify(`b/${path}`);
+                const addition = `diff --git ${JSON.stringify(`a/${path}`)} ${label}\nnew file mode ${metadata.isSymbolicLink() ? '120000' : '100644'}\n--- /dev/null\n+++ ${label}\n@@ -0,0 +1,${lines.length} @@\n${lines.map(line => `+${line}\n`).join('')}`;
+                patch += addition;
+            }
+            else
+                truncated = true;
+        }
+        const all = [...files.values()];
+        const result = parseWorkspaceChangeSummary({ ...empty('ready'), branch, base_revision: startingRevision ?? base,
+            files: all.slice(0, fileLimit), additions: all.reduce((n, file) => n + file.additions, 0),
+            deletions: all.reduce((n, file) => n + file.deletions, 0), hidden_files: Math.max(0, all.length - fileLimit),
+            patch: patch.slice(0, patchLimit), patch_truncated: truncated || patch.length > patchLimit,
+        }, fullReview);
+        return result ?? empty('unavailable');
+    }
+    catch {
+        return empty('unavailable');
+    }
+}

package/shared/workspace-change-summary.d.mts

@@ -0,0 +1,24 @@
+export const WORKSPACE_PATCH_LIMIT: number;
+export const WORKSPACE_FILE_LIMIT: number;
+export type WorkspaceChangedFile = {
+  path: string;
+  previous_path: string | null;
+  status: 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'untracked' | 'unknown';
+  additions: number;
+  deletions: number;
+  binary: boolean;
+};
+export type WorkspaceChangeSummary = {
+  captured_at: string;
+  branch: string | null;
+  /** Immutable workspace starting revision; includes committed work since creation. */
+  base_revision: string | null;
+  state: 'ready' | 'unavailable' | 'not_git';
+  files: WorkspaceChangedFile[];
+  additions: number;
+  deletions: number;
+  hidden_files: number;
+  patch: string;
+  patch_truncated: boolean;
+};
+export function parseWorkspaceChangeSummary(value: unknown, fullReview?: boolean): WorkspaceChangeSummary | null;

package/shared/workspace-change-summary.mjs

@@ -0,0 +1,44 @@
+// Bounded room-visible source changes. Absolute host paths and arbitrary metadata
+// are excluded; patch text is intentional review content, never execution input.
+export const WORKSPACE_PATCH_LIMIT = 128 * 1024;
+export const WORKSPACE_FILE_LIMIT = 200;
+const states = ['added', 'modified', 'deleted', 'renamed', 'copied', 'typechange', 'untracked', 'unknown'];
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const count = value => Number.isSafeInteger(value) && value >= 0;
+const path = value => typeof value === 'string' && value.length > 0 && value.length <= 2048
+  && !value.startsWith('/') && !/^[A-Za-z]:/.test(value) && !value.split(/[\\/]/).includes('..')
+  && !/[\x00-\x1f\x7f]/.test(value);
+
+export function parseWorkspaceChangeSummary(value, fullReview = false) {
+  if (!exact(value, ['captured_at', 'branch', 'base_revision', 'state', 'files', 'additions', 'deletions', 'hidden_files', 'patch', 'patch_truncated'])
+    || typeof value.captured_at !== 'string' || !Number.isFinite(Date.parse(value.captured_at))
+    || !(value.branch === null || typeof value.branch === 'string' && value.branch.length <= 256 && !/[\x00-\x1f\x7f]/.test(value.branch))
+    || !(value.base_revision === null || typeof value.base_revision === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value.base_revision))
+    || !['ready', 'unavailable', 'not_git'].includes(value.state)
+    || !Array.isArray(value.files) || value.files.length > (fullReview ? 10_000 : WORKSPACE_FILE_LIMIT)
+    || !count(value.additions) || !count(value.deletions) || !count(value.hidden_files)
+    || typeof value.patch !== 'string' || value.patch.length > (fullReview ? 128 * 1024 * 1024 : WORKSPACE_PATCH_LIMIT)
+    || typeof value.patch_truncated !== 'boolean') return null;
+  // Full reviews are byte-bounded by their encoded envelope. Re-serializing each
+  // patch here creates several full-size copies while decoding a large review.
+  if (!fullReview && new TextEncoder().encode(JSON.stringify(value)).length > 480 * 1024) return null;
+  const files = [];
+  const paths = new Set();
+  for (const file of value.files) {
+    if (!exact(file, ['path', 'previous_path', 'status', 'additions', 'deletions', 'binary'])
+      || !path(file.path) || paths.has(file.path)
+      || !(file.previous_path === null || path(file.previous_path)) || !states.includes(file.status)
+      || !count(file.additions) || !count(file.deletions) || typeof file.binary !== 'boolean') return null;
+    paths.add(file.path);
+    files.push({ path: file.path, previous_path: file.previous_path, status: file.status,
+      additions: file.additions, deletions: file.deletions, binary: file.binary });
+  }
+  if (value.state !== 'ready' && (files.length || value.additions || value.deletions || value.hidden_files || value.patch || value.patch_truncated)) return null;
+  if (files.reduce((n, file) => n + file.additions, 0) > value.additions
+    || files.reduce((n, file) => n + file.deletions, 0) > value.deletions) return null;
+  return { captured_at: new Date(value.captured_at).toISOString(), branch: value.branch,
+    base_revision: value.base_revision, state: value.state, files, additions: value.additions,
+    deletions: value.deletions, hidden_files: value.hidden_files, patch: value.patch,
+    patch_truncated: value.patch_truncated };
+}

package/shared/workspace-diff.d.mts

@@ -0,0 +1,9 @@
+import type { WorkspaceChangedFile } from './workspace-change-summary.mjs';
+export type WorkspaceDiffLine = { text: string; kind: 'context' | 'added' | 'deleted' | 'hunk' | 'metadata'; before: number | null; after: number | null };
+export type WorkspaceDiffPageLine = WorkspaceDiffLine & { textLength: number; textOffset: number; nextTextOffset: number | null };
+export type WorkspaceDiffPage = { lines: WorkspaceDiffPageLine[]; nextOffset: number | null; included: boolean };
+export type WorkspaceDiffPageOptions = { offset?: number; textOffset?: number; singleLine?: boolean };
+export type WorkspaceDiffIndex = { patch: string; files: Map<string, { end: number; checkpoints: { position: number; before: number; after: number }[] }> };
+export function createWorkspaceDiffIndex(patch: string, files: WorkspaceChangedFile[]): WorkspaceDiffIndex;
+export function readWorkspaceDiffPage(index: WorkspaceDiffIndex, path: string, options?: WorkspaceDiffPageOptions): WorkspaceDiffPage;
+export function workspaceFilePatches(patch: string, files: WorkspaceChangedFile[], window?: { offset: number; limit: number }): Map<string, WorkspaceDiffLine[]>;

package/shared/workspace-diff.mjs

@@ -0,0 +1,105 @@
+function unquotePath(path) {
+  if (!path.startsWith('"') || !path.endsWith('"')) return path;
+  const bytes = [];
+  const source = path.slice(1, -1);
+  const encoder = new TextEncoder();
+  for (let i = 0; i < source.length;) {
+    const octal = source[i] === '\\' ? /^\\([0-7]{1,3})/.exec(source.slice(i)) : null;
+    if (octal) { bytes.push(parseInt(octal[1], 8)); i += octal[0].length; continue; }
+    if (source[i] === '\\' && i + 1 < source.length) {
+      const char = source[++i];
+      bytes.push(...encoder.encode(({ t: '\t', n: '\n', r: '\r', b: '\b', f: '\f', v: '\v' })[char] ?? char));
+      i++; continue;
+    }
+    const char = String.fromCodePoint(source.codePointAt(i));
+    bytes.push(...encoder.encode(char)); i += char.length;
+  }
+  return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+// File boundaries and sparse line checkpoints are retained only by an open review.
+export function createWorkspaceDiffIndex(patch, files) {
+  const byPath = new Map(files.map(file => [file.path, file]));
+  const byHeader = new Map(files.flatMap(file => [
+    [`diff --git a/${file.previous_path ?? file.path} b/${file.path}`, file],
+    [`diff --git ${JSON.stringify(`a/${file.previous_path ?? file.path}`)} ${JSON.stringify(`b/${file.path}`)}`, file],
+  ]));
+  const result = { patch, files: new Map() };
+  const boundary = /^diff --git /gm;
+  let current = boundary.exec(patch);
+  while (current) {
+    const next = boundary.exec(patch), end = next?.index ?? patch.length;
+    const headers = [];
+    let position = current.index;
+    while (position < end) {
+      const newline = patch.indexOf('\n', position);
+      const stop = newline < 0 || newline >= end ? end : newline;
+      const line = patch.slice(position, stop);
+      if (line.startsWith('@@ ')) break;
+      headers.push(line); position = stop + 1;
+    }
+    const target = headers.find(line => line.startsWith('+++ '));
+    const source = headers.find(line => line.startsWith('--- '));
+    const path = target && target !== '+++ /dev/null' ? unquotePath(target.slice(4)).replace(/^b\//, '')
+      : source ? unquotePath(source.slice(4)).replace(/^a\//, '') : null;
+    const renamed = headers.find(line => line.startsWith('rename to '));
+    const file = byPath.get(path) ?? (renamed ? byPath.get(unquotePath(renamed.slice(10))) : undefined) ?? byHeader.get(headers[0]);
+    if (file) result.files.set(file.path, { end, checkpoints: [{ position, before: 0, after: 0 }] });
+    current = next;
+  }
+  return result;
+}
+
+function readLines(index, path, offset, limit, textOffset, characterLimit, budget) {
+  const file = index.files.get(path);
+  if (!file) return { lines: [], nextOffset: null, included: false };
+  const checkpointIndex = Math.min(Math.floor(offset / 500), file.checkpoints.length - 1);
+  let { position, before, after } = file.checkpoints[checkpointIndex];
+  let row = checkpointIndex * 500;
+  const lines = [];
+  while (position < file.end) {
+    const newline = index.patch.indexOf('\n', position);
+    const stop = newline < 0 || newline >= file.end ? file.end : newline;
+    const start = position;
+    position = stop + 1;
+    // Only hunk headers need a regular expression; never slice a giant code line.
+    const first = index.patch[start];
+    const hunk = first === '@' ? /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(index.patch.slice(start, Math.min(stop, start + 256))) : null;
+    let kind, oldLine = null, newLine = null, contentStart = start;
+    if (hunk) { before = Number(hunk[1]); after = Number(hunk[2]); kind = 'hunk'; }
+    else if (first === '+') { kind = 'added'; contentStart++; newLine = after++; }
+    else if (first === '-') { kind = 'deleted'; contentStart++; oldLine = before++; }
+    else if (first === ' ') { kind = 'context'; contentStart++; oldLine = before++; newLine = after++; }
+    else if (stop > start) kind = 'metadata';
+    else continue;
+    if (row >= offset) {
+      const textLength = stop - contentStart;
+      let from = Math.min(textOffset, textLength), to = Math.min(textLength, from + characterLimit, from + budget);
+      // Keep UTF-16 surrogate pairs intact at display-chunk boundaries.
+      if (from && /[\uDC00-\uDFFF]/.test(index.patch[contentStart + from]) && /[\uD800-\uDBFF]/.test(index.patch[contentStart + from - 1])) from--;
+      if (to < textLength && /[\uD800-\uDBFF]/.test(index.patch[contentStart + to - 1])) to--;
+      const text = index.patch.slice(contentStart + from, contentStart + to);
+      lines.push({ text, kind, before: oldLine, after: newLine, textLength, textOffset: from, nextTextOffset: to < textLength ? to : null });
+      budget -= text.length;
+    }
+    row++;
+    if (row % 500 === 0 && !file.checkpoints[row / 500]) file.checkpoints[row / 500] = { position, before, after };
+    if (lines.length >= limit || budget <= 0) break;
+  }
+  return { lines, nextOffset: position < file.end ? row : null, included: true };
+}
+
+export function readWorkspaceDiffPage(index, path, options = {}) {
+  const { offset = 0, textOffset = 0, singleLine = false } = options;
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > index.patch.length
+    || !Number.isSafeInteger(textOffset) || textOffset < 0 || textOffset > index.patch.length) throw new Error('Invalid diff page.');
+  return readLines(index, path, offset, singleLine ? 1 : 500, textOffset, 4096, 128 * 1024);
+}
+
+// Existing callers can still inspect a small preview without a review session.
+export function workspaceFilePatches(patch, files, window) {
+  const index = createWorkspaceDiffIndex(patch, files);
+  return new Map([...index.files.keys()].map(path => [path,
+    readLines(index, path, window?.offset ?? 0, window?.limit ?? Infinity, 0, Infinity, Infinity).lines
+      .map(({ text, kind, before, after }) => ({ text, kind, before, after }))]));
+}