@openchambery/web 1.18.2-beta.2 → 1.18.2-beta.21

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,58 @@ 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({
+      diffs: [{
+        file: 'src/large.ts',
+        status: 'modified',
+        additions: 5,
+        deletions: 1,
+      }],
+      diffCount: 1,
+      hasDiffs: true,
+    });
+    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);
+  });
+
   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,50 @@ 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({
+      diffs: [{
+        file: 'src/large.ts',
+        status: 'modified',
+        additions: 7,
+        deletions: 2,
+      }],
+      diffCount: 1,
+      hasDiffs: true,
+    });
+    expect(result.responseBytes).toBeLessThanOrEqual(1024);
+    expect(JSON.stringify(result.records)).not.toContain(patch);
+  });
+
   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));

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

@@ -1,4 +1,8 @@
 import { createOpencodeClient } from '@opencode-ai/sdk/v2';
+import { projectMessageSummaryDiffCounts } from '../event-stream/diff-summary.js';
+import {
+  createSessionChangesService,
+} from './changes.service.js';
 import {
   createSessionReconcileService,
   MAX_ANCHOR_LENGTH,
@@ -6,6 +10,7 @@ import {
 } from './reconcile.service.js';
 import {
   createSessionTurnPageService,
+  projectMessageDiffSummaries,
   projectSlimParts,
   SLIM_PARTS_PROJECTION,
 } from './service.js';
@@ -76,15 +81,27 @@ const RECONCILE_TOTAL_BYTE_LIMIT = (() => {
 /** Test/inspect helper — resolved host-local scan chunk. */
 export const getInnerSessionTurnScanLimit = () => _inner_scanLimit;
 
+const MESSAGE_ID_MIN = 1;
+const MESSAGE_ID_MAX = 512;
+const SESSION_ID_MIN = 1;
+const SESSION_ID_MAX = 512;
+const FILE_PATH_MIN = 1;
+const FILE_PATH_MAX = 4096;
+const EXACT_MESSAGE_TIMEOUT_MS = 45_000;
+const CHANGES_TIMEOUT_MS = 45_000;
+
 /** Safe client-facing error strings — no paths, tokens, or upstream bodies. */
 const SAFE_ERRORS = {
   invalid_turns: 'turns must be an integer between 1 and 10',
   invalid_scan_limit: 'scanLimit must be an integer between 10 and 200',
   invalid_session: 'sessionID is required',
+  invalid_message: 'messageID is required',
+  invalid_file: 'file is invalid',
   invalid_cursor: 'invalid cursor',
   invalid_anchor: 'anchor is required and must be a non-empty message id',
   invalid_continuation: 'invalid continuation',
   invalid_reconcile_params: 'provide exactly one of anchor or continuation',
+  change_not_found: 'change file not found',
   upstream: 'upstream',
   unavailable: 'upstream unavailable',
   aborted: 'aborted',
@@ -97,6 +114,23 @@ const SAFE_ERRORS = {
   internal: 'internal error',
 };
 
+/** Reject control characters / NUL in change file selectors. */
+const hasControlOrNul = (value) => {
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code === 0 || (code >= 1 && code <= 31) || code === 127) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const isBoundedId = (value, { min = MESSAGE_ID_MIN, max = MESSAGE_ID_MAX } = {}) => (
+  typeof value === 'string'
+  && value.length >= min
+  && value.length <= max
+);
+
 const parsePositiveInt = (value) => {
   if (value === undefined || value === null || value === '') return null;
   if (typeof value === 'number' && Number.isFinite(value)) {
@@ -172,11 +206,22 @@ const requestSignal = (req, res) => {
   return controller.signal;
 };
 
+const createSdkClient = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders }) => {
+  const baseUrl = buildOpenCodeUrl('/', '').replace(/\/$/, '');
+  const headers = typeof getOpenCodeAuthHeaders === 'function' ? getOpenCodeAuthHeaders() : {};
+  return createOpencodeClient({ baseUrl, headers });
+};
+
+const throwUpstream = (logger, label) => {
+  logger?.warn?.(label);
+  const error = new Error('upstream');
+  error.code = 'upstream';
+  throw error;
+};
+
 const createSdkFetchPage = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }) => {
   return async ({ sessionID, directory, before, limit, signal }) => {
-    const baseUrl = buildOpenCodeUrl('/', '').replace(/\/$/, '');
-    const headers = typeof getOpenCodeAuthHeaders === 'function' ? getOpenCodeAuthHeaders() : {};
-    const client = createOpencodeClient({ baseUrl, headers });
+    const client = createSdkClient({ buildOpenCodeUrl, getOpenCodeAuthHeaders });
 
     const result = await client.session.messages({
       sessionID,
@@ -186,10 +231,7 @@ const createSdkFetchPage = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }
     }, { signal });
 
     if (result?.error) {
-      logger?.warn?.('[session-turn-pages] session.messages SDK error');
-      const error = new Error('upstream');
-      error.code = 'upstream';
-      throw error;
+      throwUpstream(logger, '[session-turn-pages] session.messages SDK error');
     }
 
     const data = result?.data;
@@ -199,10 +241,7 @@ const createSdkFetchPage = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }
         ? data.items
         : null;
     if (!records) {
-      logger?.warn?.('[session-turn-pages] session.messages malformed payload');
-      const error = new Error('upstream');
-      error.code = 'upstream';
-      throw error;
+      throwUpstream(logger, '[session-turn-pages] session.messages malformed payload');
     }
 
     const headerCursor = result?.response?.headers?.get?.('x-next-cursor');
@@ -218,6 +257,70 @@ const createSdkFetchPage = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }
   };
 };
 
+const createSdkFetchMessage = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }) => {
+  return async ({ sessionID, messageID, directory, signal }) => {
+    const client = createSdkClient({ buildOpenCodeUrl, getOpenCodeAuthHeaders });
+    const result = await client.session.message({
+      sessionID,
+      messageID,
+      ...(typeof directory === 'string' && directory.length > 0 ? { directory } : {}),
+    }, { signal });
+
+    if (result?.error) {
+      const status = result?.response?.status;
+      if (status === 404) {
+        const error = new Error('not_found');
+        error.code = 'not_found';
+        throw error;
+      }
+      throwUpstream(logger, '[session-turn-pages] session.message SDK error');
+    }
+
+    const data = result?.data;
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throwUpstream(logger, '[session-turn-pages] session.message malformed payload');
+    }
+    return data;
+  };
+};
+
+const createSdkFetchDiff = ({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }) => {
+  return async ({ sessionID, messageID, directory, signal }) => {
+    const client = createSdkClient({ buildOpenCodeUrl, getOpenCodeAuthHeaders });
+    const result = await client.session.diff({
+      sessionID,
+      messageID,
+      ...(typeof directory === 'string' && directory.length > 0 ? { directory } : {}),
+    }, { signal });
+
+    if (result?.error) {
+      throwUpstream(logger, '[session-changes] session.diff SDK error');
+    }
+
+    const data = result?.data;
+    if (!Array.isArray(data)) {
+      throwUpstream(logger, '[session-changes] session.diff malformed payload');
+    }
+    return data;
+  };
+};
+
+/**
+ * Project exact message GET payload: keep original `{ info, parts }` shape,
+ * only L1-project `info.summary.diffs` → slim file list + diffCount/hasDiffs.
+ */
+export const projectExactMessagePayload = (payload) => {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return payload;
+  }
+  if (payload.info && typeof payload.info === 'object' && !Array.isArray(payload.info)) {
+    const nextInfo = projectMessageSummaryDiffCounts(payload.info);
+    if (nextInfo === payload.info) return payload;
+    return { ...payload, info: nextInfo };
+  }
+  return projectMessageSummaryDiffCounts(payload);
+};
+
 const mapServiceError = (error) => {
   const code = typeof error === 'string' ? error : String(error ?? 'upstream');
   if (
@@ -265,6 +368,21 @@ const mapServiceError = (error) => {
   if (code === 'invalid_reconcile_params') {
     return { status: 400, body: { error: SAFE_ERRORS.invalid_reconcile_params } };
   }
+  if (code === 'invalid_message' || code === 'invalid_params') {
+    return { status: 400, body: { error: SAFE_ERRORS.invalid_message, code: 'invalid_message' } };
+  }
+  if (code === 'invalid_file') {
+    return { status: 400, body: { error: SAFE_ERRORS.invalid_file, code: 'invalid_file' } };
+  }
+  if (code === 'change_not_found') {
+    return {
+      status: 404,
+      body: { error: SAFE_ERRORS.change_not_found, code: 'change_not_found' },
+    };
+  }
+  if (code === 'not_found') {
+    return { status: 404, body: { error: 'not found', code: 'not_found' } };
+  }
   return { status: 502, body: { error: SAFE_ERRORS.upstream } };
 };
 
@@ -291,6 +409,8 @@ const logInternalError = (logger, error, context = {}) => {
  * Register OpenChamber-owned session message routes:
  * - GET /api/openchamber/sessions/:sessionID/messages
  * - GET /api/openchamber/sessions/:sessionID/messages/reconcile
+ * - GET /api/openchamber/sessions/:sessionID/changes
+ * - GET /api/session/:sessionID/message/:messageID  (L1 exact message; before proxy)
  *
  * Global /api auth is enforced by core-routes requireApiAuth before feature
  * routes. This module does not add redundant auth middleware.
@@ -303,6 +423,8 @@ export const registerSessionTurnPageRoutes = (app, dependencies = {}) => {
   const {
     sessionTurnPageService: injectedService,
     sessionReconcileService: injectedReconcileService,
+    sessionChangesService: injectedChangesService,
+    fetchExactMessage: injectedFetchExactMessage,
     buildOpenCodeUrl,
     getOpenCodeAuthHeaders,
     logger = console,
@@ -332,6 +454,15 @@ export const registerSessionTurnPageRoutes = (app, dependencies = {}) => {
     scanLimit: _inner_scanLimit,
   });
 
+  const fetchExactMessage = injectedFetchExactMessage
+    ?? createSdkFetchMessage({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger });
+
+  const changesService = injectedChangesService ?? createSessionChangesService({
+    fetchMessage: fetchExactMessage,
+    fetchDiff: createSdkFetchDiff({ buildOpenCodeUrl, getOpenCodeAuthHeaders, logger }),
+    logger,
+  });
+
   // More-specific path first (before generic messages route).
   app.get('/api/openchamber/sessions/:sessionID/messages/reconcile', async (req, res) => {
     const sessionID = req.params?.sessionID;
@@ -379,7 +510,7 @@ export const registerSessionTurnPageRoutes = (app, dependencies = {}) => {
       }
 
       return res.status(200).json({
-        records: Array.isArray(result.records) ? result.records : [],
+        records: projectMessageDiffSummaries(Array.isArray(result.records) ? result.records : []),
         anchorFound: result.anchorFound === true,
         capturedHeadMessageID: result.capturedHeadMessageID ?? null,
         latestHeadMessageID: result.latestHeadMessageID ?? null,
@@ -491,4 +622,134 @@ export const registerSessionTurnPageRoutes = (app, dependencies = {}) => {
       timed.clear();
     }
   });
+
+  /**
+   * Exact message GET — registered before generic `/api` proxy so materialize /
+   * recovery never relay raw multi-megabyte patch bodies in `summary.diffs`.
+   * Returns the official `{ info, parts }` shape with L1 slim-list projection.
+   */
+  app.get('/api/session/:sessionID/message/:messageID', async (req, res) => {
+    const sessionID = req.params?.sessionID;
+    const messageID = req.params?.messageID;
+    if (!isBoundedId(sessionID, { min: SESSION_ID_MIN, max: SESSION_ID_MAX })) {
+      return res.status(400).json({ error: SAFE_ERRORS.invalid_session, code: 'invalid_session' });
+    }
+    if (!isBoundedId(messageID, { min: MESSAGE_ID_MIN, max: MESSAGE_ID_MAX })) {
+      return res.status(400).json({ error: SAFE_ERRORS.invalid_message, code: 'invalid_message' });
+    }
+
+    const directory = typeof req.query?.directory === 'string' && req.query.directory.length > 0
+      ? req.query.directory
+      : undefined;
+
+    const parentSignal = requestSignal(req, res);
+    const timed = timeoutSignal(EXACT_MESSAGE_TIMEOUT_MS, parentSignal);
+
+    try {
+      const payload = await fetchExactMessage({
+        sessionID,
+        messageID,
+        directory,
+        signal: timed.signal,
+      });
+      return res.status(200).json(projectExactMessagePayload(payload));
+    } catch (error) {
+      if (error?.name === 'AbortError' || error?.code === 'aborted') {
+        if (!res.headersSent) {
+          return res.status(499).json({ error: SAFE_ERRORS.aborted });
+        }
+        return undefined;
+      }
+      if (error?.code === 'not_found') {
+        if (!res.headersSent) {
+          return res.status(404).json({ error: 'not found', code: 'not_found' });
+        }
+        return undefined;
+      }
+      logger?.warn?.('[session-turn-pages] exact message failed', {
+        sessionID,
+        messageID,
+        hasDirectory: directory != null,
+      });
+      if (!res.headersSent) {
+        return res.status(502).json({ error: SAFE_ERRORS.upstream });
+      }
+      return undefined;
+    } finally {
+      timed.clear();
+    }
+  });
+
+  /**
+   * Changes API — L2 file list (no `file`) or L3 single-file patch (`file=`).
+   * Never returns the full message envelope or unrelated file patches.
+   */
+  app.get('/api/openchamber/sessions/:sessionID/changes', async (req, res) => {
+    const sessionID = req.params?.sessionID;
+    if (!isBoundedId(sessionID, { min: SESSION_ID_MIN, max: SESSION_ID_MAX })) {
+      return res.status(400).json({ error: SAFE_ERRORS.invalid_session, code: 'invalid_session' });
+    }
+
+    const messageIDRaw = req.query?.messageID;
+    if (!isBoundedId(messageIDRaw, { min: MESSAGE_ID_MIN, max: MESSAGE_ID_MAX })) {
+      return res.status(400).json({ error: SAFE_ERRORS.invalid_message, code: 'invalid_message' });
+    }
+
+    const fileRaw = req.query?.file;
+    let file;
+    if (fileRaw !== undefined && fileRaw !== null && fileRaw !== '') {
+      if (
+        typeof fileRaw !== 'string'
+        || fileRaw.length < FILE_PATH_MIN
+        || fileRaw.length > FILE_PATH_MAX
+        || hasControlOrNul(fileRaw)
+      ) {
+        return res.status(400).json({ error: SAFE_ERRORS.invalid_file, code: 'invalid_file' });
+      }
+      file = fileRaw;
+    }
+
+    const directory = typeof req.query?.directory === 'string' && req.query.directory.length > 0
+      ? req.query.directory
+      : undefined;
+
+    const parentSignal = requestSignal(req, res);
+    const timed = timeoutSignal(CHANGES_TIMEOUT_MS, parentSignal);
+
+    try {
+      const result = await changesService.loadChanges({
+        sessionID,
+        messageID: messageIDRaw,
+        directory,
+        file,
+        signal: timed.signal,
+      });
+
+      if (!result?.ok) {
+        const mapped = mapServiceError(result?.error);
+        return res.status(mapped.status).json(mapped.body);
+      }
+
+      return res.status(200).json(result.body);
+    } catch (error) {
+      if (error?.name === 'AbortError') {
+        if (!res.headersSent) {
+          return res.status(499).json({ error: SAFE_ERRORS.aborted });
+        }
+        return undefined;
+      }
+      logger?.warn?.('[session-changes] loadChanges failed', {
+        sessionID,
+        messageID: messageIDRaw,
+        hasDirectory: directory != null,
+        hasFile: file != null,
+      });
+      if (!res.headersSent) {
+        return res.status(502).json({ error: SAFE_ERRORS.upstream });
+      }
+      return undefined;
+    } finally {
+      timed.clear();
+    }
+  });
 };