@openchambery/web 2.0.0-beta.3 → 2.0.0-beta.5

package/server/lib/session-metadata/opencode-session-record.js

@@ -0,0 +1,316 @@
+/**
+ * OpenCode session-record ownership for OpenChamber metadata.
+ *
+ * OpenCode 2.0.15 `PATCH /api/session/:id` (`session.update`) replaces
+ * `metadata` wholesale and can set `title`. Archive stays in
+ * `metadata.openchamber.archive` on that same record, then projects onto
+ * `time.archived`. This module is the only place that knows that call.
+ *
+ * A client whose types do not yet expose `session.update` metadata still goes
+ * through `writeSessionRecordViaClient` / `createHttpSessionRecordClient`.
+ * Missing the API throws — it is never an empty success.
+ *
+ * The side store is a migration source. A failed load is not an empty catalog.
+ * One session's migration failure does not delete other sessions or their rows.
+ */
+
+import { mergeOwnedMetadata, projectSessionWithStoredMap } from './session-projection.js';
+
+export { mergeOwnedMetadata };
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const isSessionNotFoundError = (error) => {
+  const status = Number(error?.status ?? error?.statusCode);
+  if (status === 404) return true;
+  const tag = error?._tag || error?.name;
+  return tag === 'SessionNotFoundError' || tag === 'Session.NotFoundError';
+};
+
+const deepEqual = (left, right) => {
+  if (left === right) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((item, index) => deepEqual(item, right[index]));
+  }
+  if (!isPlainObject(left) || !isPlainObject(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  return leftKeys.every((key) => deepEqual(left[key], right[key]));
+};
+
+const unwrapSession = (payload) => {
+  if (!isPlainObject(payload)) return null;
+  if (isPlainObject(payload.data) && typeof payload.data.id === 'string') return payload.data;
+  if (typeof payload.id === 'string') return payload;
+  return null;
+};
+
+/**
+ * Structural adapter for `@opencode/client` session.update.
+ * Throws when the method is absent — never pretends the write landed.
+ *
+ * @param {{ session?: { update?: Function } } | null | undefined} client
+ * @param {{ sessionID: string, metadata?: object, title?: string, requestOptions?: object }} input
+ */
+export const writeSessionRecordViaClient = async (client, input) => {
+  const update = client?.session?.update;
+  if (typeof update !== 'function') {
+    const error = new Error('session.update is unavailable');
+    error.code = 'session_update_unavailable';
+    throw error;
+  }
+  const sessionID = asNonEmptyString(input?.sessionID);
+  if (!sessionID) throw new Error('a session id is required to update the OpenCode session record');
+  const body = { sessionID };
+  if (input.metadata !== undefined) body.metadata = input.metadata;
+  if (input.title !== undefined) body.title = input.title;
+  await update(body, input.requestOptions);
+};
+
+/**
+ * @param {{ session?: { get?: Function } } | null | undefined} client
+ * @param {{ sessionID: string, requestOptions?: object }} input
+ * @returns {Promise<object | null>} null only when OpenCode confirms the session is gone
+ */
+export const readSessionRecordViaClient = async (client, input) => {
+  const get = client?.session?.get;
+  if (typeof get !== 'function') {
+    const error = new Error('session.get is unavailable');
+    error.code = 'session_get_unavailable';
+    throw error;
+  }
+  const sessionID = asNonEmptyString(input?.sessionID);
+  if (!sessionID) throw new Error('a session id is required to read the OpenCode session record');
+  try {
+    const session = await get({ sessionID }, input.requestOptions);
+    return unwrapSession(session) || (isPlainObject(session) ? session : null);
+  } catch (error) {
+    if (isSessionNotFoundError(error)) return null;
+    throw error;
+  }
+};
+
+/**
+ * HTTP owner of `GET` / `PATCH /api/session/:id`. Callers supply the URL so
+ * web and VS Code keep their own prefix rules.
+ *
+ * @param {{
+ *   buildSessionUrl: (sessionID: string, directory?: string | null) => string,
+ *   getHeaders?: () => Record<string, string>,
+ *   fetchFn?: typeof fetch,
+ * }} options
+ */
+export const createHttpSessionRecordClient = ({
+  buildSessionUrl,
+  getHeaders = () => ({}),
+  fetchFn = null,
+}) => {
+  if (typeof buildSessionUrl !== 'function') {
+    throw new Error('createHttpSessionRecordClient requires buildSessionUrl');
+  }
+
+  const request = async (sessionID, { method, directory, body }) => {
+    const fetchImpl = fetchFn || globalThis.fetch;
+    const id = asNonEmptyString(sessionID);
+    if (!id) throw new Error('a session id is required');
+    const url = buildSessionUrl(id, directory);
+    const response = await fetchImpl(url, {
+      method,
+      headers: {
+        Accept: 'application/json',
+        ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...(typeof getHeaders === 'function' ? getHeaders() : {}),
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    return response;
+  };
+
+  const read = async (sessionID, directory) => {
+    const response = await request(sessionID, { method: 'GET', directory });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      const error = new Error(`OpenCode session.get failed (${response.status})`);
+      error.status = response.status;
+      throw error;
+    }
+    const payload = await response.json().catch(() => null);
+    const session = unwrapSession(payload);
+    if (!session) {
+      const error = new Error('OpenCode session.get returned an unreadable record');
+      error.status = 502;
+      throw error;
+    }
+    return session;
+  };
+
+  const write = async ({ sessionID, directory, metadata, title } = {}) => {
+    const body = {};
+    if (metadata !== undefined) body.metadata = metadata;
+    if (title !== undefined) body.title = title;
+    if (Object.keys(body).length === 0) {
+      throw new Error('session record write requires metadata or title');
+    }
+    const response = await request(sessionID, { method: 'PATCH', directory, body });
+    if (response.status === 404) {
+      const error = new Error(`session ${sessionID} was not found`);
+      error.status = 404;
+      throw error;
+    }
+    if (!response.ok) {
+      const error = new Error(`OpenCode session.update failed (${response.status})`);
+      error.status = response.status;
+      throw error;
+    }
+  };
+
+  return { read, write };
+};
+
+/**
+ * Copy side-store rows onto OpenCode records. Refuses a failed load instead of
+ * treating it as an empty catalog. A failed session is reported and skipped;
+ * other sessions, including ones OpenCode has and the side store does not, are
+ * left in place.
+ *
+ * @param {{
+ *   loadResult: { ok?: boolean, entries?: Record<string, object> | null } | null,
+ *   readSession: (sessionID: string) => Promise<object | null>,
+ *   writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>,
+ * }} input
+ */
+export const migrateLoadedSideStore = async ({ loadResult, readSession, writeMetadata }) => {
+  if (!loadResult || loadResult.ok !== true || !isPlainObject(loadResult.entries)) {
+    return { status: 'unavailable', migrated: [], failed: [], absent: [] };
+  }
+  if (typeof readSession !== 'function' || typeof writeMetadata !== 'function') {
+    throw new Error('side-store migration requires readSession and writeMetadata');
+  }
+
+  const migrated = [];
+  const failed = [];
+  const absent = [];
+
+  for (const [sessionID, sideMetadata] of Object.entries(loadResult.entries)) {
+    if (!isPlainObject(sideMetadata)) continue;
+    try {
+      const record = await readSession(sessionID);
+      if (record == null) {
+        absent.push(sessionID);
+        continue;
+      }
+      const merged = mergeOwnedMetadata(record.metadata, sideMetadata);
+      if (!deepEqual(merged, isPlainObject(record.metadata) ? record.metadata : {})) {
+        await writeMetadata(sessionID, merged, record);
+      }
+      migrated.push(sessionID);
+    } catch (error) {
+      failed.push({
+        id: sessionID,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    status: failed.length > 0 ? 'partial' : 'complete',
+    migrated,
+    failed,
+    absent,
+  };
+};
+
+/**
+ * Membership comes from OpenCode. A missing side-store row does not drop the
+ * session. A null side map is an unread store, not an empty catalog.
+ *
+ * @param {unknown} openCodeSessions
+ * @param {Record<string, object> | null | undefined} sideById
+ */
+export const retainOpenCodeSessions = (openCodeSessions, sideById) => {
+  if (!Array.isArray(openCodeSessions)) {
+    throw new Error('OpenCode session list is unavailable');
+  }
+  if (sideById == null || typeof sideById !== 'object' || Array.isArray(sideById)) {
+    throw new Error('session metadata is unavailable');
+  }
+  return openCodeSessions.map((session) => projectSessionWithStoredMap(session, sideById));
+};
+
+const MIGRATION_RETRY_MS = 2_000;
+
+/**
+ * Retry until every loaded side-store row is copied or confirmed absent.
+ * A failed load schedules another attempt and does not write empty metadata.
+ *
+ * @param {{
+ *   load: () => Promise<{ ok?: boolean, entries?: Record<string, object> }>,
+ *   readSession: (sessionID: string) => Promise<object | null>,
+ *   writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>,
+ *   setTimer?: typeof setTimeout,
+ *   clearTimer?: typeof clearTimeout,
+ * }} options
+ * @returns {() => void} stop
+ */
+export const startSideStoreMigration = ({
+  load,
+  readSession,
+  writeMetadata,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+}) => {
+  const finished = new Set();
+  let stopped = false;
+  let timer = null;
+
+  const schedule = () => {
+    if (stopped || timer) return;
+    timer = setTimer(() => {
+      timer = null;
+      void attempt();
+    }, MIGRATION_RETRY_MS);
+  };
+
+  const attempt = async () => {
+    if (stopped) return;
+    let loadResult;
+    try {
+      loadResult = await load();
+    } catch {
+      schedule();
+      return;
+    }
+    if (!loadResult || loadResult.ok !== true || !isPlainObject(loadResult.entries)) {
+      schedule();
+      return;
+    }
+    const pending = {};
+    for (const [id, metadata] of Object.entries(loadResult.entries)) {
+      if (!finished.has(id)) pending[id] = metadata;
+    }
+    if (Object.keys(pending).length === 0) return;
+    const result = await migrateLoadedSideStore({
+      loadResult: { ok: true, entries: pending },
+      readSession,
+      writeMetadata,
+    });
+    for (const id of result.migrated) finished.add(id);
+    for (const id of result.absent) finished.add(id);
+    if (result.failed.length > 0) schedule();
+  };
+
+  void attempt();
+  return () => {
+    stopped = true;
+    if (timer) clearTimer(timer);
+    timer = null;
+  };
+};

package/server/lib/session-metadata/opencode-session-record.test.js

@@ -0,0 +1,242 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createSessionArchiveService } from './session-archive.js';
+import { createSessionMetadataStore } from './session-metadata-store.js';
+import {
+  createHttpSessionRecordClient,
+  mergeOwnedMetadata,
+  migrateLoadedSideStore,
+  readSessionRecordViaClient,
+  retainOpenCodeSessions,
+  writeSessionRecordViaClient,
+} from './opencode-session-record.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const makeDataDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-record-'));
+
+describe('OpenCode session record ownership', () => {
+  it('keeps title and archive on the OpenCode record across archive and restore', async () => {
+    const dataDir = makeDataDir();
+    const records = new Map([
+      ['ses_1', {
+        id: 'ses_1',
+        title: 'Keep me',
+        metadata: { openchamber: { goal: { status: 'active' }, assistant: { assistantID: 'ast_1' } } },
+        time: { created: 1, updated: 2 },
+      }],
+    ]);
+    const writes = [];
+    const store = createSessionMetadataStore({
+      dataDir,
+      recordReader: async (sessionID) => records.get(sessionID) ?? null,
+      recordWriter: async (sessionID, metadata) => {
+        const current = records.get(sessionID);
+        if (!current) {
+          const error = new Error('missing');
+          error.status = 404;
+          throw error;
+        }
+        writes.push({ sessionID, metadata, title: current.title });
+        records.set(sessionID, { ...current, metadata });
+      },
+    });
+    const archive = createSessionArchiveService({
+      sessionMetadataStore: store,
+      fetchUpstreamSession: async ({ sessionID }) => records.get(sessionID) ?? null,
+    });
+
+    const archived = await archive.setArchive({ sessionID: 'ses_1', archivedAt: 50, directory: '/repo' });
+    expect(archived.session.title).toBe('Keep me');
+    expect(archived.session.time.archived).toBe(50);
+    expect(records.get('ses_1').title).toBe('Keep me');
+    expect(records.get('ses_1').metadata.openchamber.archive.archivedAt).toBe(50);
+    expect(records.get('ses_1').metadata.openchamber.goal.status).toBe('active');
+    expect(records.get('ses_1').metadata.openchamber.assistant.assistantID).toBe('ast_1');
+    expect(writes.at(-1).metadata.openchamber.assistant.assistantID).toBe('ast_1');
+
+    const restored = await archive.setArchive({ sessionID: 'ses_1', archivedAt: 0 });
+    expect(restored.session.title).toBe('Keep me');
+    expect(restored.session.time.archived).toBeUndefined();
+    expect(records.get('ses_1').title).toBe('Keep me');
+    expect(records.get('ses_1').metadata.openchamber.archive.archivedAt).toBe(0);
+    expect(records.get('ses_1').metadata.openchamber.goal.status).toBe('active');
+
+    const restarted = createSessionMetadataStore({
+      dataDir: makeDataDir(),
+      recordReader: async (sessionID) => records.get(sessionID) ?? null,
+      recordWriter: async () => undefined,
+    });
+    await expect(restarted.get('ses_1')).resolves.toMatchObject({
+      openchamber: {
+        archive: { archivedAt: 0 },
+        goal: { status: 'active' },
+        assistant: { assistantID: 'ast_1' },
+      },
+    });
+    const visible = retainOpenCodeSessions([records.get('ses_1')], {});
+    expect(visible).toHaveLength(1);
+    expect(visible[0].title).toBe('Keep me');
+    expect(visible[0].time.archived).toBeUndefined();
+  });
+
+  it('does not drop an OpenCode session when the side store has no row', () => {
+    const visible = retainOpenCodeSessions([
+      {
+        id: 'ses_1',
+        title: 'Still here',
+        metadata: { openchamber: { archive: { archivedAt: 9 } } },
+        time: { created: 1, updated: 2 },
+      },
+      { id: 'ses_2', title: 'Also here', time: { created: 1, updated: 2 } },
+    ], {});
+
+    expect(visible.map((session) => session.id)).toEqual(['ses_1', 'ses_2']);
+    expect(visible[0].title).toBe('Still here');
+    expect(visible[0].time.archived).toBe(9);
+    expect(visible[1].title).toBe('Also here');
+  });
+
+  it('does not treat an unread side store as an empty catalog', () => {
+    expect(() => retainOpenCodeSessions([{ id: 'ses_1', title: 'Stay' }], null)).toThrow(/unavailable/);
+    expect(() => retainOpenCodeSessions(null, {})).toThrow(/unavailable/);
+  });
+
+  it('does not treat a failed side-store load as an authoritative empty migration', async () => {
+    const writes = [];
+    const records = {
+      ses_1: { id: 'ses_1', title: 'Stay', metadata: { openchamber: { goal: { id: 'g1' } } } },
+    };
+    const result = await migrateLoadedSideStore({
+      loadResult: { ok: false, entries: {} },
+      readSession: async (id) => records[id] ?? null,
+      writeMetadata: async (id, metadata) => {
+        writes.push(id);
+        records[id] = { ...records[id], metadata };
+      },
+    });
+
+    expect(result.status).toBe('unavailable');
+    expect(writes).toEqual([]);
+    expect(records.ses_1.title).toBe('Stay');
+    expect(records.ses_1.metadata.openchamber.goal.id).toBe('g1');
+  });
+
+  it('keeps other sessions when one migration write fails', async () => {
+    const records = {
+      ses_ok: { id: 'ses_ok', title: 'Ok', metadata: {} },
+      ses_bad: { id: 'ses_bad', title: 'Bad', metadata: { openchamber: { llm: { purpose: 'keep' } } } },
+      ses_only_opencode: { id: 'ses_only_opencode', title: 'Stay', metadata: { fromOpenCode: true } },
+    };
+    const side = {
+      ses_ok: { openchamber: { goal: { id: 'g1' } } },
+      ses_bad: { openchamber: { assistant: { assistantID: 'ast_1' } } },
+    };
+
+    const result = await migrateLoadedSideStore({
+      loadResult: { ok: true, entries: side },
+      readSession: async (id) => records[id] ?? null,
+      writeMetadata: async (id, metadata) => {
+        if (id === 'ses_bad') throw new Error('write failed');
+        records[id] = { ...records[id], metadata };
+      },
+    });
+
+    expect(result.status).toBe('partial');
+    expect(result.migrated).toEqual(['ses_ok']);
+    expect(result.failed).toEqual([{ id: 'ses_bad', error: 'write failed' }]);
+    expect(records.ses_ok.metadata.openchamber.goal.id).toBe('g1');
+    expect(records.ses_ok.title).toBe('Ok');
+    expect(records.ses_bad.title).toBe('Bad');
+    expect(records.ses_bad.metadata.openchamber.llm.purpose).toBe('keep');
+    expect(records.ses_bad.metadata.openchamber.assistant).toBeUndefined();
+    expect(records.ses_only_opencode).toEqual({
+      id: 'ses_only_opencode',
+      title: 'Stay',
+      metadata: { fromOpenCode: true },
+    });
+    expect(side.ses_bad.openchamber.assistant.assistantID).toBe('ast_1');
+  });
+
+  it('fills side-store gaps without letting an empty side row wipe OpenCode fields', () => {
+    expect(mergeOwnedMetadata(
+      { openchamber: { goal: { status: 'paused' } }, fromOpenCode: true },
+      { openchamber: { goal: { id: 'g1' }, archive: { archivedAt: 4 } } },
+    )).toEqual({
+      fromOpenCode: true,
+      openchamber: { goal: { id: 'g1', status: 'paused' }, archive: { archivedAt: 4 } },
+    });
+    expect(mergeOwnedMetadata({ keep: true }, {})).toEqual({ keep: true });
+    expect(mergeOwnedMetadata({ keep: true }, null)).toEqual({ keep: true });
+  });
+
+  it('throws when the installed client has no session.update instead of writing nothing', async () => {
+    await expect(writeSessionRecordViaClient({ session: {} }, {
+      sessionID: 'ses_1',
+      metadata: { openchamber: { archive: { archivedAt: 1 } } },
+    })).rejects.toThrow(/session\.update is unavailable/);
+  });
+
+  it('writes metadata through session.update without sending title', async () => {
+    const update = vi.fn(async () => undefined);
+    await writeSessionRecordViaClient({ session: { update } }, {
+      sessionID: 'ses_1',
+      metadata: { openchamber: { archive: { archivedAt: 3 } } },
+    });
+    expect(update).toHaveBeenCalledWith({
+      sessionID: 'ses_1',
+      metadata: { openchamber: { archive: { archivedAt: 3 } } },
+    }, undefined);
+    expect(update.mock.calls[0][0].title).toBeUndefined();
+  });
+
+  it('reads a missing session as not-found and a transport failure as failure', async () => {
+    const missing = Object.assign(new Error('gone'), { status: 404 });
+    await expect(readSessionRecordViaClient({
+      session: { get: async () => { throw missing; } },
+    }, { sessionID: 'ses_1' })).resolves.toBeNull();
+
+    const down = Object.assign(new Error('down'), { status: 503 });
+    await expect(readSessionRecordViaClient({
+      session: { get: async () => { throw down; } },
+    }, { sessionID: 'ses_1' })).rejects.toThrow(/down/);
+  });
+
+  it('patches the session record over HTTP and does not turn a failed read into an empty session', async () => {
+    const calls = [];
+    const fetchFn = vi.fn(async (url, init) => {
+      calls.push({ url, method: init.method, body: init.body ? JSON.parse(init.body) : undefined });
+      if (init.method === 'PATCH' && String(url).includes('ses_ok')) {
+        return { ok: true, status: 204, json: async () => null };
+      }
+      if (String(url).includes('ses_missing')) {
+        return { ok: false, status: 404, json: async () => ({}) };
+      }
+      if (String(url).includes('ses_down')) {
+        return { ok: false, status: 503, json: async () => ({}) };
+      }
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ id: 'ses_ok', title: 'Keep', metadata: { fromOpenCode: true } }),
+      };
+    });
+    const client = createHttpSessionRecordClient({
+      buildSessionUrl: (sessionID) => `http://opencode.local/api/session/${sessionID}`,
+      fetchFn,
+    });
+
+    await expect(client.read('ses_ok')).resolves.toMatchObject({ id: 'ses_ok', title: 'Keep' });
+    await expect(client.read('ses_missing')).resolves.toBeNull();
+    await expect(client.read('ses_down')).rejects.toThrow(/503/);
+    await client.write({
+      sessionID: 'ses_ok',
+      metadata: { openchamber: { archive: { archivedAt: 8 } } },
+    });
+
+    const patch = calls.find((call) => call.method === 'PATCH');
+    expect(patch.body).toEqual({ metadata: { openchamber: { archive: { archivedAt: 8 } } } });
+    expect(patch.body.title).toBeUndefined();
+  });
+});

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

@@ -83,13 +83,17 @@ export const registerSessionMetadataRoutes = (app, deps = {}) => {
               },
             },
           };
+        }, {
+          directory: asNonEmptyString(body.directory) || undefined,
         });
         if (!result?.committed) {
           throw new Error(result?.reason || 'session metadata mutate was rejected');
         }
         metadata = result.metadata;
       } else {
-        metadata = await sessionMetadataStore.setSessionMetadata(sessionId, patch);
+        metadata = await sessionMetadataStore.setSessionMetadata(sessionId, patch, {
+          directory: asNonEmptyString(body.directory) || undefined,
+        });
       }
       const directory = asNonEmptyString(body.directory) || '';
       if (typeof onMetadataWritten === 'function') {

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

@@ -451,7 +451,7 @@ export const createSessionArchiveService = (deps = {}) => {
     const metadata = await sessionMetadataStore.setSessionMetadata(
       sessionID,
       { openchamber: { archive: { archivedAt } } },
-      { allowArchive: true },
+      { allowArchive: true, directory: upstreamDirectory || directoryHint },
     );
 
     // New Host mutation wins: bump generation and cancel older repair timers

package/server/lib/session-metadata/session-metadata-store.d.ts

@@ -33,4 +33,6 @@ export function createSessionMetadataStore(options: {
   fsPromises?: typeof import('node:fs').promises;
   path?: typeof import('node:path');
   now?: () => number;
+  recordReader?: (sessionID: string, directory?: string | null) => Promise<object | null>;
+  recordWriter?: (sessionID: string, metadata: object, directory?: string | null) => Promise<void>;
 }): SessionMetadataStore;