@openchambery/web 1.19.22-beta.1 → 2.0.0-beta.3

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

@@ -0,0 +1,193 @@
+/**
+ * HTTP surface for OpenChamber-owned session metadata and Host archive.
+ *
+ * OpenCode 2.x has no session-metadata update route. Clients (and Host
+ * features such as session goal) merge-patch state here; the proxy folds the
+ * store back onto session list/detail responses.
+ *
+ * Archive is a separate Host operation:
+ * `PUT /api/openchamber/sessions/:sessionId/archive` body `{ archivedAt: number }`.
+ *
+ * This module exports the store factory, archive service helpers, and the route
+ * registrar. Wire them from `server/index.js` / `feature-routes-runtime.js`.
+ */
+
+import express from 'express';
+
+import { withGoalExecutionGeneration } from '../session-goal/runtime.js';
+import { createSessionMetadataStore } from './session-metadata-store.js';
+import { SessionArchiveError } from './session-archive.js';
+
+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);
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} deps
+ * @param {{ get: Function, setSessionMetadata: Function }} deps.sessionMetadataStore
+ * @param {{ setArchive: Function } | null} [deps.sessionArchiveService]
+ * @param {(event: { type: string, properties: object }) => void} [deps.broadcastGlobalUiEvent]
+ * @param {(event: { sessionID: string, directory: string, metadata: object }) => void} [deps.onMetadataWritten]
+ */
+export const registerSessionMetadataRoutes = (app, deps = {}) => {
+  const {
+    sessionMetadataStore = null,
+    sessionArchiveService = null,
+    broadcastGlobalUiEvent = null,
+    onMetadataWritten = null,
+  } = deps;
+
+  if (!sessionMetadataStore || typeof sessionMetadataStore.setSessionMetadata !== 'function') {
+    throw new Error('registerSessionMetadataRoutes requires a sessionMetadataStore');
+  }
+
+  const putMetadata = async (req, res) => {
+    const sessionId = asNonEmptyString(req.params?.sessionId);
+    if (!sessionId) {
+      return res.status(400).json({ error: 'a session id is required' });
+    }
+
+    const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {};
+    const patch = body.patch;
+    if (!isPlainObject(patch)) {
+      return res.status(400).json({ error: 'patch must be an object' });
+    }
+
+    try {
+      // Goal pause/resume/condition writes must advance executionGeneration so
+      // in-flight audits lose commit rights. Normalize inside the exclusive
+      // mutate boundary (same lock as persist) for UI merge-patches.
+      let metadata;
+      if (
+        typeof sessionMetadataStore.mutateSessionMetadata === 'function'
+        && isPlainObject(patch.openchamber)
+        && Object.prototype.hasOwnProperty.call(patch.openchamber, 'goal')
+        && isPlainObject(patch.openchamber.goal)
+      ) {
+        const result = await sessionMetadataStore.mutateSessionMetadata(sessionId, (current) => {
+          const previousGoal = isPlainObject(current?.openchamber?.goal)
+            ? current.openchamber.goal
+            : null;
+          return {
+            ok: true,
+            patch: {
+              ...patch,
+              openchamber: {
+                ...patch.openchamber,
+                goal: withGoalExecutionGeneration(previousGoal, patch.openchamber.goal),
+              },
+            },
+          };
+        });
+        if (!result?.committed) {
+          throw new Error(result?.reason || 'session metadata mutate was rejected');
+        }
+        metadata = result.metadata;
+      } else {
+        metadata = await sessionMetadataStore.setSessionMetadata(sessionId, patch);
+      }
+      const directory = asNonEmptyString(body.directory) || '';
+      if (typeof onMetadataWritten === 'function') {
+        try {
+          onMetadataWritten({ sessionID: sessionId, directory, metadata });
+        } catch (error) {
+          console.warn('[session-metadata] metadata listener failed:', error?.message ?? error);
+        }
+      }
+      if (typeof broadcastGlobalUiEvent === 'function') {
+        try {
+          broadcastGlobalUiEvent({
+            type: 'openchamber:session-metadata',
+            properties: { sessionID: sessionId, metadata },
+          });
+        } catch (error) {
+          console.warn('[session-metadata] broadcast failed:', error?.message ?? error);
+        }
+      }
+      return res.json({ metadata });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to store session metadata';
+      // Load/read failure must not be answered as empty success — clients must
+      // not treat a refused write as cleared metadata.
+      const status = /could not be read|unavailable/i.test(message) ? 503 : 500;
+      console.error('[session-metadata] failed to store session metadata:', message);
+      return res.status(status).json({ error: message });
+    }
+  };
+
+  const putArchive = async (req, res) => {
+    if (!sessionArchiveService || typeof sessionArchiveService.setArchive !== 'function') {
+      return res.status(503).json({ error: 'session archive is not configured' });
+    }
+
+    const sessionId = asNonEmptyString(req.params?.sessionId);
+    if (!sessionId) {
+      return res.status(400).json({ error: 'a session id is required' });
+    }
+
+    const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {};
+    if (typeof body.archivedAt !== 'number' || !Number.isFinite(body.archivedAt)) {
+      return res.status(400).json({ error: 'archivedAt must be a finite number' });
+    }
+
+    try {
+      const result = await sessionArchiveService.setArchive({
+        sessionID: sessionId,
+        archivedAt: body.archivedAt,
+        directory: asNonEmptyString(body.directory) || undefined,
+      });
+      // Metadata is committed; index may report retryable failure separately.
+      return res.json({
+        session: result.session,
+        ...(result.index ? { index: result.index } : {}),
+      });
+    } catch (error) {
+      if (error instanceof SessionArchiveError) {
+        return res.status(error.status || 400).json({
+          error: error.message,
+          code: error.code,
+        });
+      }
+      const message = error instanceof Error ? error.message : 'Failed to archive session';
+      const status = /could not be read|unavailable/i.test(message) ? 503 : 500;
+      console.error('[session-archive] failed:', message);
+      return res.status(status).json({ error: message });
+    }
+  };
+
+  app.put(
+    '/api/openchamber/sessions/:sessionId/metadata',
+    express.json({ limit: '1mb' }),
+    putMetadata,
+  );
+
+  app.put(
+    '/api/openchamber/sessions/:sessionId/archive',
+    express.json({ limit: '32kb' }),
+    putArchive,
+  );
+};
+
+export { createSessionMetadataStore, mergeMetadataPatch } from './session-metadata-store.js';
+export {
+  createSessionArchiveService,
+  createUpstreamSessionFetcher,
+  SessionArchiveError,
+} from './session-archive.js';
+export {
+  projectSessionWithHostMetadata,
+  projectSessionWithStoredMap,
+  projectSessionLifecyclePayload,
+  resolveProjectedArchivedAt,
+  readHostArchivedAt,
+  isSessionArchived,
+  normalizeSessionEventType,
+  extractSessionInfoFromPayload,
+  resolveSessionDirectory,
+  isSessionLifecycleEventType,
+} from './session-projection.js';

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

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import request from 'supertest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSessionMetadataStore, registerSessionMetadataRoutes } from './routes.js';
+
+const tempDirs = [];
+
+const makeDataDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-metadata-routes-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+  vi.restoreAllMocks();
+});
+
+const mount = (overrides = {}) => {
+  const store = overrides.sessionMetadataStore
+    ?? createSessionMetadataStore({ dataDir: makeDataDir() });
+  const broadcastGlobalUiEvent = overrides.broadcastGlobalUiEvent ?? vi.fn();
+  const app = express();
+  registerSessionMetadataRoutes(app, {
+    sessionMetadataStore: store,
+    sessionArchiveService: overrides.sessionArchiveService ?? null,
+    broadcastGlobalUiEvent,
+    onMetadataWritten: overrides.onMetadataWritten,
+  });
+  return { app, store, broadcastGlobalUiEvent };
+};
+
+describe('registerSessionMetadataRoutes', () => {
+  it('merge-patches metadata and broadcasts the full merged object', async () => {
+    const { app, store, broadcastGlobalUiEvent } = mount();
+
+    const first = await request(app)
+      .put('/api/openchamber/sessions/ses_1/metadata')
+      .send({ patch: { openchamber: { assist: { recap: 'a' } } } })
+      .expect(200);
+    expect(first.body.metadata).toEqual({ openchamber: { assist: { recap: 'a' } } });
+
+    const second = await request(app)
+      .put('/api/openchamber/sessions/ses_1/metadata')
+      .send({ patch: { openchamber: { goal: { status: 'active' } } }, directory: '/repo' })
+      .expect(200);
+    expect(second.body.metadata).toEqual({
+      openchamber: { assist: { recap: 'a' }, goal: { status: 'active', executionGeneration: 0 } },
+    });
+    await expect(store.get('ses_1')).resolves.toEqual(second.body.metadata);
+    expect(broadcastGlobalUiEvent).toHaveBeenLastCalledWith({
+      type: 'openchamber:session-metadata',
+      properties: { sessionID: 'ses_1', metadata: second.body.metadata },
+    });
+  });
+
+  it('notifies the metadata listener with the session directory', async () => {
+    const onMetadataWritten = vi.fn();
+    const { app } = mount({ onMetadataWritten });
+
+    await request(app)
+      .put('/api/openchamber/sessions/ses_2/metadata')
+      .send({ patch: { openchamber: { goal: { id: 'g1', status: 'active', objective: 'ship' } } }, directory: '/repo' })
+      .expect(200);
+
+    expect(onMetadataWritten).toHaveBeenCalledWith({
+      sessionID: 'ses_2',
+      directory: '/repo',
+      metadata: {
+        openchamber: {
+          goal: { id: 'g1', status: 'active', objective: 'ship', executionGeneration: 0 },
+        },
+      },
+    });
+  });
+
+  it('rejects a blank session id and a non-object patch with 400', async () => {
+    const { app } = mount();
+    await request(app)
+      .put('/api/openchamber/sessions/%20%20/metadata')
+      .send({ patch: { a: 1 } })
+      .expect(400);
+    await request(app)
+      .put('/api/openchamber/sessions/ses_1/metadata')
+      .send({})
+      .expect(400);
+    await request(app)
+      .put('/api/openchamber/sessions/ses_1/metadata')
+      .send({ patch: 'nope' })
+      .expect(400);
+    await request(app)
+      .put('/api/openchamber/sessions/ses_1/metadata')
+      .send({ patch: ['a'] })
+      .expect(400);
+  });
+
+  it('does not answer a failed store load as empty success', async () => {
+    const store = {
+      setSessionMetadata: async () => {
+        throw new Error('session metadata is unavailable: its file could not be read');
+      },
+    };
+    const { app } = mount({ sessionMetadataStore: store });
+    const res = await request(app)
+      .put('/api/openchamber/sessions/ses_1/metadata')
+      .send({ patch: { a: 1 } })
+      .expect(503);
+    expect(res.body).toMatchObject({ error: expect.stringMatching(/could not be read/) });
+  });
+
+  it('archives via PUT /archive and returns the projected session', async () => {
+    const setArchive = vi.fn(async ({ sessionID, archivedAt }) => ({
+      session: {
+        id: sessionID,
+        title: 'Alpha',
+        directory: '/repo',
+        time: { created: 1, updated: 2, archived: archivedAt },
+        metadata: { openchamber: { archive: { archivedAt } } },
+      },
+    }));
+    const { app } = mount({
+      sessionArchiveService: { setArchive },
+    });
+
+    const res = await request(app)
+      .put('/api/openchamber/sessions/ses_1/archive')
+      .send({ archivedAt: 99, directory: '/repo' })
+      .expect(200);
+
+    expect(setArchive).toHaveBeenCalledWith({
+      sessionID: 'ses_1',
+      archivedAt: 99,
+      directory: '/repo',
+    });
+    expect(res.body.session).toMatchObject({
+      id: 'ses_1',
+      time: { archived: 99 },
+    });
+  });
+
+  it('rejects archive without a finite archivedAt', async () => {
+    const { app } = mount({
+      sessionArchiveService: { setArchive: vi.fn() },
+    });
+    await request(app)
+      .put('/api/openchamber/sessions/ses_1/archive')
+      .send({})
+      .expect(400);
+  });
+});

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

@@ -0,0 +1,73 @@
+/**
+ * Type surface for session-archive.js (consumed by VS Code Extension Host facades).
+ * Runtime implementation stays in the .js module.
+ */
+
+export class SessionArchiveError extends Error {
+  code: string;
+  status: number;
+  constructor(code: string, message: string, status?: number);
+}
+
+export type SessionArchiveIndexResult =
+  | { ok: true; skipped?: boolean }
+  | { ok: false; error?: string; retryable?: boolean };
+
+export type SessionForgetResult =
+  | { ok: true; removed: boolean }
+  | { ok: false; removed: false; retryable?: boolean; error?: string };
+
+export type SessionArchiveService = {
+  setArchive: (input: {
+    sessionID: string;
+    archivedAt: number;
+    directory?: string;
+  }) => Promise<{
+    session: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    archivedAt: number;
+    index?: SessionArchiveIndexResult;
+  }>;
+  forgetSession: (sessionID: string) => Promise<SessionForgetResult | boolean>;
+  stop?: () => void;
+};
+
+export function createSessionArchiveService(deps?: {
+  sessionMetadataStore: {
+    setSessionMetadata: (
+      sessionID: string,
+      patch: object,
+      options?: { allowArchive?: boolean },
+    ) => Promise<Record<string, unknown>>;
+    get: (sessionID: string) => Promise<Record<string, unknown>>;
+    removeSession?: (sessionID: string) => Promise<boolean>;
+    getSnapshotSync?: () => Record<string, Record<string, unknown>> | null;
+  };
+  fetchUpstreamSession: (input: {
+    sessionID: string;
+    directory?: string | null;
+  }) => Promise<object | null>;
+  sessionIndexService?: {
+    upsert?: (...args: unknown[]) => unknown;
+    upsertAndReportChange?: (...args: unknown[]) => unknown;
+    remove?: (...args: unknown[]) => unknown;
+  } | null;
+  broadcastSessionEvent?: (
+    event: { type: string; properties: object },
+    options?: object,
+  ) => void;
+  onIndexChanged?: (sessionID: string) => void;
+  now?: () => number;
+  setTimer?: typeof setTimeout;
+  clearTimer?: typeof clearTimeout;
+}): SessionArchiveService;
+
+export function createUpstreamSessionFetcher(deps: {
+  buildOpenCodeUrl: (path: string) => string;
+  getOpenCodeAuthHeaders?: () => Record<string, string>;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}): (input: {
+  sessionID: string;
+  directory?: string | null;
+}) => Promise<object | null>;