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

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

@@ -1,19 +1,22 @@
 /**
- * HTTP surface for OpenChamber-owned session metadata.
+ * 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.
  *
- * This module exports the store factory and the route registrar. Wire them
- * from `server/index.js` (store instance, proxy `getStoredSessionMetadata`,
- * session-goal / scheduled-tasks `readSessionMetadata` / `persistSessionGoal`,
- * then `registerSessionMetadataRoutes`).
+ * 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;
@@ -27,12 +30,14 @@ const isPlainObject = (value) => value !== null && typeof value === 'object' &&
  * @param {import('express').Express} app
  * @param {object} deps
  * @param {{ get: Function, setSessionMetadata: Function }} deps.sessionMetadataStore
-  * @param {(event: { type: string, properties: object }) => void} [deps.broadcastGlobalUiEvent]
-   * @param {(event: { sessionID: string, directory: string, metadata: object }) => void} [deps.onMetadataWritten]
-   */
+ * @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;
@@ -54,7 +59,38 @@ export const registerSessionMetadataRoutes = (app, deps = {}) => {
     }
 
     try {
-      const metadata = await sessionMetadataStore.setSessionMetadata(sessionId, patch);
+      // 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 {
@@ -84,11 +120,74 @@ export const registerSessionMetadataRoutes = (app, deps = {}) => {
     }
   };
 
+  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

@@ -29,6 +29,7 @@ const mount = (overrides = {}) => {
   const app = express();
   registerSessionMetadataRoutes(app, {
     sessionMetadataStore: store,
+    sessionArchiveService: overrides.sessionArchiveService ?? null,
     broadcastGlobalUiEvent,
     onMetadataWritten: overrides.onMetadataWritten,
   });
@@ -50,7 +51,7 @@ describe('registerSessionMetadataRoutes', () => {
       .send({ patch: { openchamber: { goal: { status: 'active' } } }, directory: '/repo' })
       .expect(200);
     expect(second.body.metadata).toEqual({
-      openchamber: { assist: { recap: 'a' }, goal: { status: 'active' } },
+      openchamber: { assist: { recap: 'a' }, goal: { status: 'active', executionGeneration: 0 } },
     });
     await expect(store.get('ses_1')).resolves.toEqual(second.body.metadata);
     expect(broadcastGlobalUiEvent).toHaveBeenLastCalledWith({
@@ -71,7 +72,11 @@ describe('registerSessionMetadataRoutes', () => {
     expect(onMetadataWritten).toHaveBeenCalledWith({
       sessionID: 'ses_2',
       directory: '/repo',
-      metadata: { openchamber: { goal: { id: 'g1', status: 'active', objective: 'ship' } } },
+      metadata: {
+        openchamber: {
+          goal: { id: 'g1', status: 'active', objective: 'ship', executionGeneration: 0 },
+        },
+      },
     });
   });
 
@@ -108,4 +113,44 @@ describe('registerSessionMetadataRoutes', () => {
       .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>;