@openchambery/web 1.18.2-beta.6 → 1.18.2-beta.8

package/server/lib/session-turn-pages/DOCUMENTATION.md

@@ -11,6 +11,8 @@ Exposed as:
 
 - `GET /api/openchamber/sessions/:sessionID/messages`
 - `GET /api/openchamber/sessions/:sessionID/messages/reconcile`
+- `GET /api/openchamber/sessions/:sessionID/changes` (L2 file list / L3 single-file patch)
+- `GET /api/session/:sessionID/message/:messageID` (exact message with L1 summary projection; registered before the generic OpenCode proxy)
 
 ## Why this exists
 
@@ -69,9 +71,22 @@ Success `200`:
 - `complete`: `upstreamComplete && selected.length === accumulated.length`. True when upstream history is exhausted **and** `selectTurnRecords` did not trim any older scanned rows (nothing left for the client). When the scan window held more than N turns and older rows were trimmed, `complete` stays `false` with a `cursor` so the client can fetch the trimmed history.
 - `partsProjection`: `"slim-v1"` on every turn-page response (first packet and prepend). Names the projection applied to `records`; see below. Reconcile responses omit this field and keep full parts.
 
-### Turn-page parts projection
+### Turn-page payload projection
+
+Every turn-page response summarizes `tool`, `reasoning`, and `file` parts plus message `summary.diffs` so it does not have to carry the bodies of a long tool-heavy turn, inline attachment data URLs, or full file patches. Projection runs **after** `selectTurnRecords`, so `turnCount`, `complete`, and cursor encoding are all derived from unprojected records and cannot shift.
+
+### Changes Host contract (L1 / L2 / L3)
+
+| Layer | Surface | Payload |
+|---|---|---|
+| **L1** | Turn pages, reconcile response pages, message/session SSE fan-out, exact `GET /api/session/:sessionID/message/:messageID` | Any `info.summary.diffs` **array** is projected to `summary.diffCount: number` + `summary.hasDiffs: boolean` and **`summary.diffs` is removed**. Other lightweight summary fields are preserved. `diffCount` is the original array length; `hasDiffs === diffCount > 0`. L1 never retains a file array. |
+| **L2** | `GET /api/openchamber/sessions/:sessionID/changes?messageID=` (no `file`) | Host reads official `session.message` locally, returns only `{ files: [{ file, status?, additions, deletions }] }`. Never returns patch/before/after/from/to or the full message envelope. |
+| **L3** | Same route with `file=` | Host calls official `session.diff({ sessionID, messageID, directory })`, returns `{ diff: SnapshotFileDiff }` for the exact `file` string match (includes that file's patch). No match → HTTP 404 `{ error: 'change file not found', code: 'change_not_found' }`. |
+
+Exact message GET keeps the official `{ info, parts }` response shape and only applies L1 summary projection so materialize/recovery never relays a raw multi-megabyte `summary.diffs` array through the generic proxy. Abort/45s timeout semantics match the turn-page routes. Global `/api` auth still applies.
+
+Changes query guards: `sessionID` / `messageID` length `1..512`; optional `file` length `1..4096` and rejects control characters / NUL. Failures: invalid params → 400, abort → 499, upstream/malformed → 502. Logs carry only safe flags and ids — never paths, patch bodies, or tokens.
 
-Every turn-page response summarizes `tool`, `reasoning`, and `file` parts so it does not have to carry the bodies of a long tool-heavy turn or inline attachment data URLs. Projection runs **after** `selectTurnRecords`, so `turnCount`, `complete`, and cursor encoding are all derived from unprojected records and cannot shift.
 
 | Kept | Dropped |
 |---|---|
@@ -85,6 +100,7 @@ Rules:
 - Slim tool input keeps only short locator and task-identity fields (path, pattern, query, command, `subagent_type`, `description`, skill `name` / `id`). Slim metadata keeps `sessionId`, skill `name`, plus edit `additions`/`deletions`. Projection still drops result bodies, task prompts, patches, and large write payloads.
 - Assistant `text` stays intact. User rows are no longer wholesale pass-through: their `file` parts are projected; other user parts stay as-is.
 - `file` projection keeps already-present size/width/height (top-level or `metadata`). `byteSize` is derived from a data URL when present. PNG/GIF/JPEG/WebP headers may fill missing `width`/`height`. Unknown dimensions omit those fields.
+- Message `info.summary.diffs` is L1-projected to `diffCount` / `hasDiffs` (file array removed). Reconcile preserves full parts and applies this same L1 summary projection to response-page byte budgeting and serialization; raw upstream scan budgets retain raw bytes. Clients that need file rows or patches use the Changes L2/L3 API.
 - A slim `file` part is a reference, not renderable content. Clients must hydrate the full message (`session.message` by `messageID`) before painting or editing the attachment. Do not treat slim file metadata as a complete part.
 - Records that gain nothing from projection keep their original object reference, so identity-based change detection downstream still works.
 - Projection applies to every turn-page response, including first packet, prepend, and explicit cursors (`before` present). Reconcile routes return full parts, unchanged.
@@ -242,10 +258,11 @@ When the per-page budget fills before the gap is complete, the host returns `con
 
 ## Files
 
-- `service.js` — `isUserAuthoredTurnBoundary`, `selectTurnRecords`, `encodeHostCursor`, `decodeHostCursor`, `createSessionTurnPageService({ fetchPage, maxScanPages?, maxScanMessages? })`
+- `service.js` — `isUserAuthoredTurnBoundary`, `selectTurnRecords`, `encodeHostCursor`, `decodeHostCursor`, `projectMessageDiffSummaries` (L1), `projectSlimParts`, `createSessionTurnPageService({ fetchPage, maxScanPages?, maxScanMessages? })`
 - `reconcile.service.js` — `encodeReconcileContinuation`, `decodeReconcileContinuation`, `createSessionReconcileService({ fetchPage, runtimeKey?, page/total budgets?, continuationSecret?, clock?, continuationTtlMs? })`
-- `routes.js` — Express registration for both turn-page and reconcile; optional injected `sessionTurnPageService` / `sessionReconcileService` for tests; default wires SDK `session.messages` via `buildOpenCodeUrl` + `getOpenCodeAuthHeaders`
-- `service.test.js` / `routes.test.js` / `reconcile.service.test.js` / `reconcile.routes.test.js` — unit contracts
+- `changes.service.js` — `createSessionChangesService({ fetchMessage, fetchDiff })` for L2/L3; injectable for unit tests
+- `routes.js` — Express registration for turn-page, reconcile, Changes, and exact message GET; optional injected `sessionTurnPageService` / `sessionReconcileService` / `sessionChangesService` / `fetchExactMessage` for tests; default wires SDK `session.messages` / `session.message` / `session.diff` via `buildOpenCodeUrl` + `getOpenCodeAuthHeaders`
+- `service.test.js` / `routes.test.js` / `reconcile.service.test.js` / `reconcile.routes.test.js` / `changes.service.test.js` — unit contracts
 
 ## Registration
 
@@ -257,14 +274,17 @@ registerSessionTurnPageRoutes(app, {
 });
 ```
 
-Reconcile is registered on the more-specific path **before** the generic messages path inside `registerSessionTurnPageRoutes`.
+Inside `registerSessionTurnPageRoutes`, registration order is: reconcile → turn-page messages → exact `GET /api/session/:sessionID/message/:messageID` → Changes. All of these register before the generic OpenCode proxy in `feature-routes-runtime.js`. Electron reuses this same Host composition in-process.
 
 ## Error HTTP map
 
 | Condition | Status |
 |---|---|
 | Invalid turns / scanLimit / sessionID / cursor | 400 |
+| Invalid messageID / file (Changes / exact message) | 400 |
 | Invalid anchor / continuation / reconcile params | 400 |
+| Change file not found (`change_not_found`) | 404 |
+| Exact message not found | 404 |
 | max_scan_pages / max_scan_messages | 413 |
 | Client abort | 499 |
 | Server exception (reconcile) | 500 (stack logged; safe client body) |

package/server/lib/session-turn-pages/changes.service.js

@@ -0,0 +1,156 @@
+/**
+ * OpenChamber-owned session Changes API (L2 file list / L3 single-file patch).
+ *
+ * L2 (no `file`): read official `session.message`, project summary.diffs to
+ *   `{ files: [{ file, status?, additions, deletions }] }` — never patch bodies
+ *   or the full message envelope.
+ * L3 (with `file`): call official `session.diff({ sessionID, messageID })`,
+ *   return `{ diff: SnapshotFileDiff }` for the exact file string match.
+ *
+ * Dependency-injected for unit tests (`fetchMessage`, `fetchDiff`).
+ */
+
+/**
+ * Project a raw summary.diffs entry to L2 file-list scalars.
+ * @param {unknown} entry
+ * @returns {{ file: string, status?: string, additions: number, deletions: number } | null}
+ */
+export const projectChangeFileEntry = (entry) => {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return null;
+  }
+  const file = typeof entry.file === 'string' ? entry.file : null;
+  if (!file || file.length === 0) {
+    return null;
+  }
+
+  /** Built from allowlist only — patch/before/after/from/to never copied. */
+  const out = { file };
+  if (typeof entry.status === 'string') {
+    out.status = entry.status;
+  }
+  out.additions = typeof entry.additions === 'number' && Number.isFinite(entry.additions)
+    ? entry.additions
+    : 0;
+  out.deletions = typeof entry.deletions === 'number' && Number.isFinite(entry.deletions)
+    ? entry.deletions
+    : 0;
+  return out;
+};
+
+/**
+ * Extract L2 file list from a session.message response shape.
+ * Accepts `{ info, parts }`, `{ data: { info, parts } }`, or bare info.
+ * @param {unknown} messagePayload
+ * @returns {{ files: Array<{ file: string, status?: string, additions: number, deletions: number }> }}
+ */
+export const projectChangeFileList = (messagePayload) => {
+  const record = messagePayload && typeof messagePayload === 'object' && !Array.isArray(messagePayload)
+    ? messagePayload
+    : null;
+  const info = record?.info && typeof record.info === 'object' && !Array.isArray(record.info)
+    ? record.info
+    : (record?.summary ? record : null);
+  const summary = info?.summary && typeof info.summary === 'object' && !Array.isArray(info.summary)
+    ? info.summary
+    : null;
+  const diffs = Array.isArray(summary?.diffs) ? summary.diffs : [];
+
+  const files = [];
+  for (const entry of diffs) {
+    const projected = projectChangeFileEntry(entry);
+    if (projected) files.push(projected);
+  }
+  return { files };
+};
+
+/**
+ * Find exact file match in a session.diff array.
+ * @param {unknown} diffs
+ * @param {string} file
+ * @returns {unknown | null}
+ */
+export const findChangeFileDiff = (diffs, file) => {
+  if (!Array.isArray(diffs) || typeof file !== 'string') {
+    return null;
+  }
+  for (const entry of diffs) {
+    if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.file === file) {
+      return entry;
+    }
+  }
+  return null;
+};
+
+/**
+ * @param {{
+ *   fetchMessage: (args: { sessionID: string, messageID: string, directory?: string, signal?: AbortSignal }) => Promise<unknown>,
+ *   fetchDiff: (args: { sessionID: string, messageID: string, directory?: string, signal?: AbortSignal }) => Promise<unknown>,
+ *   logger?: { warn?: Function },
+ * }} deps
+ */
+export const createSessionChangesService = (deps) => {
+  const {
+    fetchMessage,
+    fetchDiff,
+    logger = console,
+  } = deps;
+
+  if (typeof fetchMessage !== 'function' || typeof fetchDiff !== 'function') {
+    throw new Error('createSessionChangesService requires fetchMessage and fetchDiff');
+  }
+
+  /**
+   * @param {{
+   *   sessionID: string,
+   *   messageID: string,
+   *   directory?: string,
+   *   file?: string,
+   *   signal?: AbortSignal,
+   * }} input
+   */
+  const loadChanges = async (input) => {
+    const sessionID = typeof input?.sessionID === 'string' ? input.sessionID : '';
+    const messageID = typeof input?.messageID === 'string' ? input.messageID : '';
+    const directory = typeof input?.directory === 'string' && input.directory.length > 0
+      ? input.directory
+      : undefined;
+    const file = typeof input?.file === 'string' && input.file.length > 0
+      ? input.file
+      : undefined;
+    const signal = input?.signal;
+
+    if (!sessionID || !messageID) {
+      return { ok: false, error: 'invalid_params' };
+    }
+
+    try {
+      if (!file) {
+        const payload = await fetchMessage({ sessionID, messageID, directory, signal });
+        return { ok: true, body: projectChangeFileList(payload) };
+      }
+
+      const diffs = await fetchDiff({ sessionID, messageID, directory, signal });
+      if (!Array.isArray(diffs)) {
+        logger?.warn?.('[session-changes] session.diff malformed payload');
+        return { ok: false, error: 'upstream' };
+      }
+      const match = findChangeFileDiff(diffs, file);
+      if (!match) {
+        return { ok: false, error: 'change_not_found' };
+      }
+      return { ok: true, body: { diff: match } };
+    } catch (error) {
+      if (error?.name === 'AbortError' || error?.code === 'aborted') {
+        return { ok: false, error: 'aborted' };
+      }
+      if (typeof error?.code === 'string' && error.code.length > 0) {
+        return { ok: false, error: error.code };
+      }
+      logger?.warn?.('[session-changes] upstream failure');
+      return { ok: false, error: 'upstream' };
+    }
+  };
+
+  return { loadChanges };
+};

package/server/lib/session-turn-pages/changes.service.test.js

@@ -0,0 +1,188 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createSessionChangesService,
+  findChangeFileDiff,
+  projectChangeFileEntry,
+  projectChangeFileList,
+} from './changes.service.js';
+
+describe('projectChangeFileEntry', () => {
+  it('keeps file/status/additions/deletions and drops patch bodies', () => {
+    expect(projectChangeFileEntry({
+      file: 'src/a.ts',
+      status: 'modified',
+      additions: 3,
+      deletions: 1,
+      patch: '@@',
+      before: 'old',
+      after: 'new',
+      from: 'f',
+      to: 't',
+    })).toEqual({
+      file: 'src/a.ts',
+      status: 'modified',
+      additions: 3,
+      deletions: 1,
+    });
+  });
+
+  it('returns null when file is missing', () => {
+    expect(projectChangeFileEntry({ additions: 1 })).toBeNull();
+  });
+});
+
+describe('projectChangeFileList', () => {
+  it('projects summary.diffs from a message envelope and never returns the message', () => {
+    const list = projectChangeFileList({
+      info: {
+        id: 'msg_1',
+        summary: {
+          diffs: [
+            { file: 'a.ts', status: 'added', additions: 2, deletions: 0, patch: 'big' },
+            { file: 'b.ts', additions: 1, deletions: 1, before: 'x' },
+            { additions: 9 },
+          ],
+        },
+      },
+      parts: [{ type: 'text', text: 'secret' }],
+    });
+
+    expect(list).toEqual({
+      files: [
+        { file: 'a.ts', status: 'added', additions: 2, deletions: 0 },
+        { file: 'b.ts', additions: 1, deletions: 1 },
+      ],
+    });
+    expect(list.info).toBeUndefined();
+    expect(list.parts).toBeUndefined();
+    expect(JSON.stringify(list)).not.toContain('patch');
+    expect(JSON.stringify(list)).not.toContain('secret');
+  });
+
+  it('returns empty files when summary.diffs is absent', () => {
+    expect(projectChangeFileList({ info: { id: 'msg_1' }, parts: [] })).toEqual({ files: [] });
+  });
+});
+
+describe('findChangeFileDiff', () => {
+  it('matches exact file string only', () => {
+    const diffs = [
+      { file: 'src/a.ts', patch: 'a' },
+      { file: 'src/b.ts', patch: 'b' },
+    ];
+    expect(findChangeFileDiff(diffs, 'src/b.ts')).toEqual({ file: 'src/b.ts', patch: 'b' });
+    expect(findChangeFileDiff(diffs, 'src/missing.ts')).toBeNull();
+    expect(findChangeFileDiff(diffs, 'src/A.ts')).toBeNull();
+  });
+});
+
+describe('createSessionChangesService', () => {
+  it('L2 path calls fetchMessage and returns projected files', async () => {
+    const fetchMessage = vi.fn(async () => ({
+      info: {
+        summary: {
+          diffs: [{
+            file: 'hot.ts',
+            status: 'modified',
+            additions: 4,
+            deletions: 2,
+            patch: 'HUGE',
+          }],
+        },
+      },
+      parts: [],
+    }));
+    const fetchDiff = vi.fn();
+    const service = createSessionChangesService({ fetchMessage, fetchDiff });
+
+    const result = await service.loadChanges({
+      sessionID: 'ses_1',
+      messageID: 'msg_1',
+      directory: '/repo',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.body).toEqual({
+      files: [{
+        file: 'hot.ts',
+        status: 'modified',
+        additions: 4,
+        deletions: 2,
+      }],
+    });
+    expect(fetchMessage).toHaveBeenCalledOnce();
+    expect(fetchDiff).not.toHaveBeenCalled();
+  });
+
+  it('L3 path calls fetchDiff and returns the matched SnapshotFileDiff', async () => {
+    const fetchMessage = vi.fn();
+    const fetchDiff = vi.fn(async () => ([
+      { file: 'a.ts', patch: 'a-patch', additions: 1, deletions: 0 },
+      { file: 'b.ts', patch: 'b-patch', additions: 2, deletions: 1, status: 'modified' },
+    ]));
+    const service = createSessionChangesService({ fetchMessage, fetchDiff });
+
+    const result = await service.loadChanges({
+      sessionID: 'ses_1',
+      messageID: 'msg_1',
+      file: 'b.ts',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.body).toEqual({
+      diff: {
+        file: 'b.ts',
+        patch: 'b-patch',
+        additions: 2,
+        deletions: 1,
+        status: 'modified',
+      },
+    });
+    expect(fetchDiff).toHaveBeenCalledOnce();
+    expect(fetchMessage).not.toHaveBeenCalled();
+  });
+
+  it('returns change_not_found when file is absent from session.diff', async () => {
+    const service = createSessionChangesService({
+      fetchMessage: vi.fn(),
+      fetchDiff: vi.fn(async () => [{ file: 'other.ts', patch: 'x' }]),
+    });
+    const result = await service.loadChanges({
+      sessionID: 'ses_1',
+      messageID: 'msg_1',
+      file: 'missing.ts',
+    });
+    expect(result).toEqual({ ok: false, error: 'change_not_found' });
+  });
+
+  it('maps abort errors to aborted', async () => {
+    const service = createSessionChangesService({
+      fetchMessage: vi.fn(async () => {
+        const error = new Error('aborted');
+        error.name = 'AbortError';
+        throw error;
+      }),
+      fetchDiff: vi.fn(),
+    });
+    const result = await service.loadChanges({
+      sessionID: 'ses_1',
+      messageID: 'msg_1',
+    });
+    expect(result).toEqual({ ok: false, error: 'aborted' });
+  });
+
+  it('maps malformed/upstream failures to upstream', async () => {
+    const service = createSessionChangesService({
+      fetchMessage: vi.fn(),
+      fetchDiff: vi.fn(async () => ({ not: 'array' })),
+      logger: { warn: vi.fn() },
+    });
+    const result = await service.loadChanges({
+      sessionID: 'ses_1',
+      messageID: 'msg_1',
+      file: 'a.ts',
+    });
+    expect(result).toEqual({ ok: false, error: 'upstream' });
+  });
+});

package/server/lib/session-turn-pages/reconcile.routes.test.js

@@ -209,6 +209,54 @@ describe('registerSessionTurnPageRoutes — reconcile', () => {
     });
   });
 
+  it('summarizes message diff snapshots while preserving full reconcile parts', async () => {
+    const patch = 'diff-body-'.repeat(20_000);
+    const reconcile = vi.fn(async () => successPage({
+      records: [{
+        info: {
+          id: 'msg_u2',
+          role: 'user',
+          summary: {
+            diffs: [{
+              file: 'src/large.ts',
+              status: 'modified',
+              additions: 5,
+              deletions: 1,
+              patch,
+            }],
+          },
+        },
+        parts: [{ id: 'prt_1', type: 'text', text: 'full recovery text' }],
+      }],
+    }));
+    const { app, route } = registry();
+    registerSessionTurnPageRoutes(app, {
+      sessionTurnPageService: { loadPage: vi.fn() },
+      sessionReconcileService: { reconcile },
+    });
+    const res = response();
+
+    await route('GET', RECONCILE_ROUTE)({
+      params: { sessionID: 'ses_42' },
+      query: { anchor: 'msg_u2' },
+      headers: {},
+    }, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.records[0].info.summary).toEqual({
+      diffCount: 1,
+      hasDiffs: true,
+    });
+    expect(res.body.records[0].info.summary.diffs).toBeUndefined();
+    expect(res.body.records[0].parts[0]).toEqual({
+      id: 'prt_1',
+      type: 'text',
+      text: 'full recovery text',
+    });
+    expect(JSON.stringify(res.body)).not.toContain(patch);
+    expect(JSON.stringify(res.body)).not.toContain('src/large.ts');
+  });
+
   it('returns HTTP 200 for resetRequired (anchor lost / budget rebuild)', async () => {
     const reconcile = vi.fn(async () => successPage({
       records: [],

package/server/lib/session-turn-pages/reconcile.service.js

@@ -14,6 +14,8 @@
 
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 
+import { projectMessageDiffSummaries } from './service.js';
+
 /** Host-owned signed reconcile continuation version prefix. */
 const CONTINUATION_PREFIX = 'ocr2.';
 
@@ -666,7 +668,7 @@ export const createSessionReconcileService = ({
         state.scannedRecords += records.length;
         state.scannedBytes += measureRecordsBytes(records);
 
-        candidates.unshift(...prepend);
+        candidates.unshift(...projectMessageDiffSummaries(prepend));
 
         if (state.returnedThroughID) {
           applyReturnedBoundary();

package/server/lib/session-turn-pages/reconcile.service.test.js

@@ -481,6 +481,46 @@ describe('createSessionReconcileService', () => {
     expect(result.records.length).toBeLessThan(5);
   });
 
+  it('counts summarized message diff snapshots against the reconcile byte budget', async () => {
+    const patch = 'diff-body-'.repeat(20_000);
+    const fetchPage = vi.fn(async () => pageResult([
+      user('msg_u1', [], {
+        summary: {
+          diffs: [{
+            file: 'src/large.ts',
+            status: 'modified',
+            additions: 7,
+            deletions: 2,
+            patch,
+          }],
+        },
+      }),
+      assistant('msg_a1'),
+    ]));
+    const service = createSessionReconcileService(serviceOptions(fetchPage, {
+      pageRecordLimit: 10,
+      pageByteLimit: 1024,
+      totalPageLimit: 10,
+      totalByteLimit: 10_000,
+    }));
+
+    const result = await service.reconcile({
+      sessionID: 'ses_1',
+      directory: '/repo',
+      anchor: 'msg_u1',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.records[0].info.summary).toEqual({
+      diffCount: 1,
+      hasDiffs: true,
+    });
+    expect(result.records[0].info.summary.diffs).toBeUndefined();
+    expect(result.responseBytes).toBeLessThanOrEqual(1024);
+    expect(JSON.stringify(result.records)).not.toContain(patch);
+    expect(JSON.stringify(result.records)).not.toContain('src/large.ts');
+  });
+
   it('rejects continuation that does not bind runtime/directory/session/anchor/head', async () => {
     const fetchPage = vi.fn(async () => pageResult([user('msg_u1')], null));
     const service = createSessionReconcileService(serviceOptions(fetchPage));