@openchambery/web 1.19.21-beta.1 → 2.0.0-beta.1

package/server/lib/session-metadata/session-metadata-store.js

@@ -0,0 +1,235 @@
+/**
+ * OpenChamber-owned session metadata.
+ *
+ * OpenCode 2.x accepts `metadata` only when a session is created; the v1
+ * `PATCH /session/{id}` route is gone and nothing replaces it. Session goal
+ * progress (and later assist / pinned notes) live here: one JSON file per data
+ * dir, `{ [sessionID]: metadata }`, folded back onto the sessions the proxy
+ * serves so clients keep reading `session.metadata` where they always did.
+ *
+ * Writes are a JSON Merge Patch (RFC 7386): nested objects merge key by key and
+ * a `null` deletes. That is what the old PATCH did, and it is what keeps two
+ * features writing into the same `openchamber` namespace from erasing each
+ * other — goal mode saving progress must not drop an assist recap.
+ */
+
+import fsDefault from 'node:fs';
+import pathDefault from 'node:path';
+
+const METADATA_FILE_NAME = 'sessions-metadata.json';
+
+const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * RFC 7386 merge. Returns a new object; `null` in the patch removes the key,
+ * and a non-object patch value replaces whatever was there.
+ */
+export const mergeMetadataPatch = (current, patch) => {
+  const base = isPlainObject(current) ? { ...current } : {};
+  if (!isPlainObject(patch)) return base;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete base[key];
+      continue;
+    }
+    base[key] = isPlainObject(value) ? mergeMetadataPatch(base[key], value) : value;
+  }
+  return base;
+};
+
+/**
+ * @param {object} options
+ * @param {string} options.dataDir OpenChamber data directory for this instance.
+ * @param {typeof fsDefault.promises} [options.fsPromises]
+ * @param {typeof pathDefault} [options.path]
+ * @param {() => number} [options.now]
+ */
+export const createSessionMetadataStore = ({
+  dataDir,
+  fsPromises = fsDefault.promises,
+  path = pathDefault,
+  now = Date.now,
+}) => {
+  const filePath = path.join(dataDir, METADATA_FILE_NAME);
+
+  /** sessionID → metadata object. Authoritative once `loaded` is true. */
+  const entries = new Map();
+  let loaded = false;
+  let loadPromise = null;
+  /**
+   * Writes stay disabled until one load has told us what is already on disk.
+   * A failed read is not evidence that nothing is stored, and writing over a
+   * file we could not read would drop exactly the state we are protecting.
+   */
+  let writable = false;
+  let writeChain = Promise.resolve();
+
+  const snapshot = () => Object.fromEntries(entries);
+
+  const parseStored = (raw) => {
+    const parsed = JSON.parse(raw);
+    if (!isPlainObject(parsed)) {
+      throw new Error('session metadata file is not a JSON object');
+    }
+    const result = new Map();
+    for (const [sessionID, value] of Object.entries(parsed)) {
+      const id = asNonEmptyString(sessionID);
+      // A non-object entry is not metadata; dropping it is better than handing
+      // a consumer something it will read fields off.
+      if (id && isPlainObject(value)) result.set(id, value);
+    }
+    return result;
+  };
+
+  const readFile = async () => {
+    let raw;
+    try {
+      raw = await fsPromises.readFile(filePath, 'utf8');
+    } catch (error) {
+      // No file yet is the normal first run: nothing is stored, and writing is
+      // safe because there is no state to lose.
+      if (error?.code === 'ENOENT') return { ok: true, stored: new Map() };
+      console.warn('[session-metadata] could not read the session metadata file:', error?.message ?? error);
+      return { ok: false, stored: null };
+    }
+
+    try {
+      return { ok: true, stored: parseStored(raw) };
+    } catch (error) {
+      // Malformed bytes are kept for the user instead of being overwritten on
+      // the next write, and whatever this process already knows stays in memory
+      // rather than collapsing to "no metadata".
+      const backup = `${filePath}.corrupt-${now()}`;
+      await fsPromises.rename(filePath, backup).catch(() => undefined);
+      console.warn(
+        `[session-metadata] session metadata file was unreadable and was moved to ${backup}: ${error?.message ?? error}`,
+      );
+      return { ok: true, stored: new Map() };
+    }
+  };
+
+  const load = () => {
+    if (!loadPromise) {
+      loadPromise = readFile().then((result) => {
+        if (result.ok) {
+          // Merge rather than replace: a write that happened while the first
+          // load was still running must survive it.
+          for (const [id, metadata] of result.stored) {
+            if (!entries.has(id)) entries.set(id, metadata);
+          }
+          loaded = true;
+          writable = true;
+        } else {
+          // Let a later call retry; until one succeeds the store answers reads
+          // from memory and refuses writes.
+          loadPromise = null;
+        }
+        return { ok: result.ok, entries: snapshot() };
+      });
+    }
+    return loadPromise;
+  };
+
+  const persist = () => {
+    const payload = JSON.stringify(snapshot());
+    const write = async () => {
+      await fsPromises.mkdir(dataDir, { recursive: true });
+      // Temp file in the same directory so the rename is atomic on one device:
+      // a reader sees either the previous file or the complete new one.
+      const tmpPath = `${filePath}.${process.pid}.tmp`;
+      await fsPromises.writeFile(tmpPath, payload, 'utf8');
+      await fsPromises.rename(tmpPath, filePath);
+    };
+    // Serialized so two overlapping writes cannot interleave their renames.
+    const next = writeChain.then(write, write);
+    writeChain = next.catch(() => undefined);
+    return next;
+  };
+
+  const get = async (sessionID) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) return {};
+    await load();
+    return entries.get(id) ?? {};
+  };
+
+  /** Whether the store holds anything for the session (an empty object counts as nothing). */
+  const has = async (sessionID) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) return false;
+    await load();
+    return entries.has(id);
+  };
+
+  /**
+   * Applies a merge patch and returns the session's full metadata afterwards.
+   * A failed write rolls the memory back and throws, so a caller never believes
+   * it saved something it did not.
+   */
+  const setSessionMetadata = async (sessionID, patch) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) throw new Error('a session id is required to store session metadata');
+    if (!isPlainObject(patch)) throw new Error('a session metadata patch must be an object');
+
+    const loadResult = await load();
+    if (!loadResult.ok || !writable) {
+      throw new Error('session metadata is unavailable: its file could not be read');
+    }
+
+    const had = entries.has(id);
+    const previous = entries.get(id);
+    const merged = mergeMetadataPatch(previous, patch);
+    if (Object.keys(merged).length === 0) entries.delete(id);
+    else entries.set(id, merged);
+
+    try {
+      await persist();
+    } catch (error) {
+      if (had) entries.set(id, previous);
+      else entries.delete(id);
+      throw error;
+    }
+
+    return merged;
+  };
+
+  const removeSession = async (sessionID) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) return false;
+    await load();
+    if (!writable || !entries.has(id)) return false;
+    const previous = entries.get(id);
+    entries.delete(id);
+    try {
+      await persist();
+    } catch (error) {
+      entries.set(id, previous);
+      console.warn('[session-metadata] failed to drop session metadata:', error?.message ?? error);
+      return false;
+    }
+    return true;
+  };
+
+  const getAll = async () => {
+    await load();
+    return snapshot();
+  };
+
+  return {
+    load,
+    get,
+    getAll,
+    list: getAll,
+    isLoaded: () => loaded,
+    has,
+    setSessionMetadata,
+    removeSession,
+    filePath,
+  };
+};

package/server/lib/session-metadata/session-metadata-store.test.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSessionMetadataStore, mergeMetadataPatch } from './session-metadata-store.js';
+
+const tempDirs = [];
+
+const makeDataDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-metadata-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+const readFile = (dataDir) => fs.readFileSync(path.join(dataDir, 'sessions-metadata.json'), 'utf8');
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+  vi.restoreAllMocks();
+});
+
+describe('mergeMetadataPatch', () => {
+  it('merges nested objects key by key instead of replacing them', () => {
+    const current = { openchamber: { goal: { id: 'g1', status: 'active' }, assist: { recap: 'r' } } };
+    const merged = mergeMetadataPatch(current, { openchamber: { goal: { status: 'complete' } } });
+
+    expect(merged).toEqual({
+      openchamber: { goal: { id: 'g1', status: 'complete' }, assist: { recap: 'r' } },
+    });
+    // The input is untouched: callers keep whatever they already held.
+    expect(current.openchamber.goal.status).toBe('active');
+  });
+
+  it('deletes a key when its patch value is null', () => {
+    expect(mergeMetadataPatch({ a: 1, b: 2 }, { b: null })).toEqual({ a: 1 });
+    expect(mergeMetadataPatch({ openchamber: { goal: {}, assist: {} } }, { openchamber: { assist: null } }))
+      .toEqual({ openchamber: { goal: {} } });
+  });
+
+  it('replaces arrays and scalars rather than merging into them', () => {
+    expect(mergeMetadataPatch({ pins: ['a', 'b'] }, { pins: ['c'] })).toEqual({ pins: ['c'] });
+    expect(mergeMetadataPatch({ a: { nested: true } }, { a: 'flat' })).toEqual({ a: 'flat' });
+  });
+
+  it('treats a missing or non-object base as empty', () => {
+    expect(mergeMetadataPatch(undefined, { a: 1 })).toEqual({ a: 1 });
+    expect(mergeMetadataPatch('nope', { a: 1 })).toEqual({ a: 1 });
+    expect(mergeMetadataPatch({ a: 1 }, 'nope')).toEqual({ a: 1 });
+  });
+});
+
+describe('createSessionMetadataStore', () => {
+  it('starts empty when the file does not exist', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await expect(store.getAll()).resolves.toEqual({});
+    await expect(store.get('ses_1')).resolves.toEqual({});
+  });
+
+  it('stores a patch, persists it, and reads it back in a fresh store', async () => {
+    const dataDir = makeDataDir();
+    const store = createSessionMetadataStore({ dataDir });
+
+    const merged = await store.setSessionMetadata('ses_1', { openchamber: { goal: { id: 'g1' } } });
+    expect(merged).toEqual({ openchamber: { goal: { id: 'g1' } } });
+    expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { openchamber: { goal: { id: 'g1' } } } });
+
+    const reopened = createSessionMetadataStore({ dataDir });
+    await expect(reopened.get('ses_1')).resolves.toEqual({ openchamber: { goal: { id: 'g1' } } });
+  });
+
+  it('keeps a neighbouring namespace when another feature writes', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'done' } } });
+    const merged = await store.setSessionMetadata('ses_1', { openchamber: { goal: { status: 'active' } } });
+
+    expect(merged).toEqual({ openchamber: { assist: { recap: 'done' }, goal: { status: 'active' } } });
+  });
+
+  it('deletes a key with a null patch value and drops a session that empties out', async () => {
+    const dataDir = makeDataDir();
+    const store = createSessionMetadataStore({ dataDir });
+    await store.setSessionMetadata('ses_1', { openchamber: { goal: { id: 'g1' } } });
+
+    await expect(store.setSessionMetadata('ses_1', { openchamber: null })).resolves.toEqual({});
+    await expect(store.getAll()).resolves.toEqual({});
+    expect(JSON.parse(readFile(dataDir))).toEqual({});
+  });
+
+  it('scopes metadata per session', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', { a: 1 });
+    await store.setSessionMetadata('ses_2', { b: 2 });
+
+    await expect(store.getAll()).resolves.toEqual({ ses_1: { a: 1 }, ses_2: { b: 2 } });
+  });
+
+  it('rejects a blank session id and a non-object patch', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await expect(store.setSessionMetadata('  ', { a: 1 })).rejects.toThrow(/session id is required/);
+    await expect(store.setSessionMetadata('ses_1', 'nope')).rejects.toThrow(/must be an object/);
+    await expect(store.setSessionMetadata('ses_1', ['a'])).rejects.toThrow(/must be an object/);
+  });
+
+  it('writes atomically: the visible file is never a partial payload', async () => {
+    const dataDir = makeDataDir();
+    const seen = [];
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        // The visible file must still be the previous one at this point.
+        seen.push(fs.existsSync(path.join(dataDir, 'sessions-metadata.json')) ? readFile(dataDir) : null);
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+
+    await store.setSessionMetadata('ses_1', { a: 1 });
+    await store.setSessionMetadata('ses_2', { b: 2 });
+
+    expect(seen).toEqual([null, JSON.stringify({ ses_1: { a: 1 } })]);
+    expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { a: 1 }, ses_2: { b: 2 } });
+  });
+
+  it('treats a malformed file as empty, keeps a backup, and still accepts writes', async () => {
+    const dataDir = makeDataDir();
+    fs.writeFileSync(path.join(dataDir, 'sessions-metadata.json'), '{ not json', 'utf8');
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const store = createSessionMetadataStore({ dataDir });
+    await expect(store.getAll()).resolves.toEqual({});
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).resolves.toEqual({ a: 1 });
+    expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { a: 1 } });
+    expect(fs.readdirSync(dataDir).some((name) => name.includes('sessions-metadata.json.'))).toBe(true);
+  });
+
+  it('drops entries that are not metadata objects', async () => {
+    const dataDir = makeDataDir();
+    fs.writeFileSync(
+      path.join(dataDir, 'sessions-metadata.json'),
+      JSON.stringify({ ses_ok: { a: 1 }, ses_list: ['a'], ses_text: 'nope', ses_null: null }),
+      'utf8',
+    );
+    const store = createSessionMetadataStore({ dataDir });
+    await expect(store.getAll()).resolves.toEqual({ ses_ok: { a: 1 } });
+  });
+
+  it('refuses to write when the file could not be read, so unknown state is never overwritten', async () => {
+    const dataDir = makeDataDir();
+    fs.writeFileSync(path.join(dataDir, 'sessions-metadata.json'), '{}', 'utf8');
+    const unreadable = Object.assign(new Error('EACCES'), { code: 'EACCES' });
+    const fsPromises = {
+      ...fs.promises,
+      readFile: async () => { throw unreadable; },
+      writeFile: async () => { throw new Error('must not write'); },
+    };
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/could not be read/);
+    expect(readFile(dataDir)).toBe('{}');
+  });
+
+  it('rolls memory back and reports failure when persisting fails', async () => {
+    const dataDir = makeDataDir();
+    const fsPromises = { ...fs.promises, writeFile: async () => { throw new Error('disk full'); } };
+
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow('disk full');
+    await expect(store.get('ses_1')).resolves.toEqual({});
+  });
+
+  it('forgets a session on request', async () => {
+    const dataDir = makeDataDir();
+    const store = createSessionMetadataStore({ dataDir });
+    await store.setSessionMetadata('ses_1', { a: 1 });
+
+    await expect(store.removeSession('ses_1')).resolves.toBe(true);
+    await expect(store.removeSession('ses_1')).resolves.toBe(false);
+    expect(JSON.parse(readFile(dataDir))).toEqual({});
+  });
+});

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

@@ -34,7 +34,7 @@ Official OpenCode pagination is message-count based and uses **opaque** cursors
 | `scanLimit` | **omitted** | `10..200` when present | Optional override only. Host→OpenCode local page size; when omitted it resolves to `_inner_scanLimit`. Clients should omit this. |
 | `before` | omitted | opaque string ≤ 8192 chars | Resume older history: host cursor (`oc1.…`) or raw OpenCode SDK cursor on first page |
 | `directory` | omitted | path string | Forwarded to directory-scoped OpenCode client |
-| `includeReasoning` | omitted (include) | strict `'false'` only disables | OpenChamber projection control. When `'false'`, drop `type=reasoning` parts from turn-page / reconcile / exact responses after other projections. Missing or any other value keeps existing behavior (slim reasoning identity on turn pages; full parts on reconcile/exact). **Never forwarded to OpenCode.** Same contract on transcript-cache reads, official `session.messages` list proxy, and event SSE/WS send boundaries — see `event-stream/reasoning-projection.js`. |
+| `includeReasoning` | omitted (include) | strict `'false'` only disables | OpenChamber projection control. When `'false'`, drop `type=reasoning` parts from turn-page / reconcile / exact responses. Host order is **normalize native SessionMessageInfo → slim/L1 bounds → reasoning strip** so `content`/`text` carriers cannot rebuild filtered parts or leak through `info` expansion. Missing or any other value keeps existing behavior (slim reasoning identity on turn pages; full parts on reconcile/exact). **Never forwarded to OpenCode.** Same contract on transcript-cache reads, official `session.messages` list proxy, and event SSE/WS send boundaries — see `event-stream/reasoning-projection.js`. |
 
 Invalid `turns`, explicit invalid `scanLimit`, or `before` (malformed/stale host token, oversize) → HTTP 400.
 
@@ -82,7 +82,7 @@ Every turn-page response summarizes `tool`, `reasoning`, and `file` parts plus m
 |---|---|---|
 | **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 a **slim file list** `[{ file, status?, additions, deletions }]` plus additive markers `summary.diffCount: number` and `summary.hasDiffs: boolean`. Patch/before/after/from/to and other heavy bodies are stripped. Other lightweight summary fields are preserved. `diffCount` equals the slim array length; `hasDiffs === diffCount > 0`. Consumers may use either the slim array or the markers. |
 | **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' }`. Older hosts may ignore `file=` and answer 200 `{ files }` (L2 only). Current clients treat a 200 without `{ diff }` as missing L3 and fall back to official `session.diff`. |
+| **L3** | Same route with `file=` | Host currently still reads `info.summary.diffs` from the exact message payload when present. **v2 `SessionMessageInfo` has no `summary.diffs`**, so L3 fails closed with upstream 502 until a parent follow-up lands an authoritative per-message diff source. Do **not** substitute working-tree / `vcs.diff` here. When diffs are available, returns `{ diff: SnapshotFileDiff }` for the exact `file` string match. No match → HTTP 404 `{ error: 'change file not found', code: 'change_not_found' }`. Older hosts may ignore `file=` and answer 200 `{ files }` (L2 only). |
 
 Exact message GET keeps the official `{ info, parts }` response shape and only applies L1 summary projection so materialize/recovery never relays raw multi-megabyte patch bodies through the generic proxy. Abort/45s timeout semantics match the turn-page routes. Global `/api` auth still applies.
 
@@ -263,7 +263,7 @@ When the per-page budget fills before the gap is complete, the host returns `con
 - `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? })`
 - `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`
+- `routes.js` — Express registration for turn-page, reconcile, Changes, and exact message GET; optional injected `sessionTurnPageService` / `sessionReconcileService` / `sessionChangesService` / `fetchExactMessage` for tests; default wires `@opencode/client` `OpenCode.make` (`message.list` / `session.message`) via `buildOpenCodeUrl` + `getOpenCodeAuthHeaders`. Exact/not-found classification honors real client `_tag` (`MessageNotFoundError` / `SessionNotFoundError`) and preserves abort → HTTP 499 (never folds abort into 502).
 - `service.test.js` / `routes.test.js` / `reconcile.service.test.js` / `reconcile.routes.test.js` / `changes.service.test.js` — unit contracts
 
 ## Registration

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

@@ -47,7 +47,7 @@ const PROCESS_CONTINUATION_SECRET = randomBytes(32);
 const fail = (error) => ({ ok: false, error });
 
 const recordId = (record) => {
-  const id = record?.info?.id;
+  const id = record?.info?.id ?? record?.id;
   return typeof id === 'string' && id.length > 0 ? id : null;
 };
 

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

@@ -686,4 +686,20 @@ describe('createSessionReconcileService', () => {
     expect(result.ok).toBe(true);
     expect(result.resetRequired).toBe(true);
   });
+
+  it('locates a SessionMessageInfo anchor by top-level id', async () => {
+    const fetchPage = vi.fn(async () => pageResult([
+      { id: 'msg_u1', type: 'user', time: { created: 1 }, text: 'hi' },
+      { id: 'msg_a1', type: 'assistant', time: { created: 2, completed: 3 }, content: [{ type: 'text', text: 'ok' }] },
+    ], null));
+    const service = createSessionReconcileService(serviceOptions(fetchPage));
+    const result = await service.reconcile({
+      sessionID: 'ses_1',
+      directory: '/repo',
+      anchor: 'msg_u1',
+    });
+    expect(result.ok).toBe(true);
+    expect(result.anchorFound).toBe(true);
+    expect(result.records.map((entry) => entry.id)).toEqual(['msg_u1', 'msg_a1']);
+  });
 });