@openchambery/web 1.19.20 → 2.0.0-beta.1

package/server/lib/session-goal/runtime.js

@@ -319,11 +319,23 @@ export const createSessionGoalRuntime = ({
    * timers for the session tree (root + descendants).
    */
   onGoalPaused,
+  /**
+   * OpenChamber session-metadata store seams. When both are functions, goal
+   * state is read/written only through the Host store (OpenCode 2.x has no
+   * session-metadata PATCH). When either is missing, keep the legacy OpenCode
+   * PATCH path so existing tests and unwired servers still work.
+   */
+  persistSessionGoal = null,
+  readSessionMetadata = null,
 }) => {
   const timers = new Map();
   const inflight = new Set();
   let stopped = false;
 
+  const isMetadataStoreWired = () => (
+    typeof persistSessionGoal === 'function' && typeof readSessionMetadata === 'function'
+  );
+
   const clearTimer = (sessionId) => {
     const existing = timers.get(sessionId);
     if (existing) {
@@ -383,7 +395,28 @@ export const createSessionGoalRuntime = ({
   // metadata writes (assist payloads, dismissals, UI goal edits) survive.
   // Returns the written goal, or null when the stored goal no longer matches
   // the expected id (user replaced/cleared it while we worked).
+  /**
+   * When the Host metadata store is wired, the goal lives there — OpenCode 2.x
+   * accepts session metadata only at create time. Re-read before every write so
+   * a concurrent edit (the user pausing from the UI) is not overwritten.
+   */
+  const readGoal = async (sessionId, directory) => {
+    if (isMetadataStoreWired()) {
+      return parseGoalMetadata({ metadata: await readSessionMetadata(sessionId) });
+    }
+    const session = await openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, { directory });
+    return parseGoalMetadata(session);
+  };
+
   const writeGoal = async (sessionId, directory, expectedGoalId, mutate) => {
+    if (isMetadataStoreWired()) {
+      const currentGoal = await readGoal(sessionId, directory);
+      if (!currentGoal || currentGoal.id !== expectedGoalId) return null;
+      const nextGoal = { ...currentGoal, ...mutate(currentGoal), updatedAt: Date.now() };
+      await persistSessionGoal(sessionId, directory, nextGoal);
+      return nextGoal;
+    }
+
     const session = await openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, { directory });
     const currentGoal = parseGoalMetadata(session);
     if (!currentGoal || currentGoal.id !== expectedGoalId) return null;
@@ -537,7 +570,9 @@ export const createSessionGoalRuntime = ({
     // Sub-agent/task sessions never carry user goals — skip them.
     if (typeof session.parentID === 'string' && session.parentID) return;
 
-    const goal = parseGoalMetadata(session);
+    const goal = isMetadataStoreWired()
+      ? await readGoal(sessionId, directory)
+      : parseGoalMetadata(session);
     if (!goal || goal.status !== 'active') return;
 
     // File-backed objectives: the metadata carries only a flag; the objective
@@ -835,7 +870,9 @@ export const createSessionGoalRuntime = ({
   // auto-delegate timers are cancelled (abort path used to no-op on non-active).
   const pauseAfterAbort = async (sessionId, directory) => {
     const owner = await resolveGoalOwner(sessionId, directory);
-    const goal = parseGoalMetadata(owner.session);
+    const goal = isMetadataStoreWired()
+      ? await readGoal(owner.sessionId, owner.directory)
+      : parseGoalMetadata(owner.session);
     if (!goal) return;
     if (goal.status === 'paused') {
       if (!isQuestionDrivenPause(goal)) {
@@ -857,9 +894,14 @@ export const createSessionGoalRuntime = ({
   // from a child/sub-agent (any depth) pauses the root owner session's goal.
   const pauseForQuestion = async (sessionId, directory) => {
     const owner = await resolveGoalOwner(sessionId, directory);
-    if (!owner.session) return;
+    // When the Host store is wired, goal state does not live on the OpenCode
+    // record — owner.session may be null only if the session itself is missing.
+    if (!isMetadataStoreWired() && !owner.session) return;
+    if (isMetadataStoreWired() && !owner.sessionId) return;
     clearTimer(owner.sessionId);
-    const goal = parseGoalMetadata(owner.session);
+    const goal = isMetadataStoreWired()
+      ? await readGoal(owner.sessionId, owner.directory)
+      : parseGoalMetadata(owner.session);
     if (!goal || goal.status !== 'active') return;
     await writeGoal(owner.sessionId, owner.directory, goal.id, () => ({
       status: 'paused',

package/server/lib/session-goal/runtime.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'bun:test';
+import { describe, expect, it, vi } from 'vitest';
 import { accountGoalTokenSpend, createSessionGoalRuntime, messageTokenSpend } from './runtime.js';
 
 // A session whose last assistant message is an orphaned incomplete turn: the
@@ -641,3 +641,64 @@ describe('session-goal runtime — pause for question', () => {
     });
   });
 });
+
+describe('session-goal runtime — Host metadata store seams', () => {
+  it('writes through persistSessionGoal and never PATCHes OpenCode metadata when seams are injected', async () => {
+    const active = buildSession('active');
+    const goal = active.metadata.openchamber.goal;
+    const metadata = {
+      openchamber: {
+        goal: { ...goal },
+        assist: { recap: 'keep-me' },
+      },
+    };
+    const readSessionMetadata = vi.fn(async () => metadata);
+    const persistSessionGoal = vi.fn(async (_sessionId, _directory, nextGoal) => {
+      metadata.openchamber = { ...metadata.openchamber, goal: nextGoal };
+    });
+    const fetchMock = vi.fn(async (input, init = {}) => {
+      const url = String(input);
+      const path = url.split('?')[0];
+      if (init.method === 'PATCH') {
+        throw new Error(`OpenCode metadata PATCH must not run when store seams are wired: ${path}`);
+      }
+      // resolveGoalOwner walks parentID via GET /session/:id
+      if (path.endsWith('/session/ses-goal')) {
+        return new Response(JSON.stringify({ id: 'ses-goal', directory: '/repo' }), { status: 200 });
+      }
+      return new Response(JSON.stringify({}), { status: 200 });
+    });
+
+    await withFetch(fetchMock, async () => {
+      const runtime = createSessionGoalRuntime({
+        buildOpenCodeUrl: (pathname) => `http://opencode${pathname}`,
+        getOpenCodeAuthHeaders: () => ({}),
+        getSmallModelService: async () => {
+          throw new Error('small model must not run');
+        },
+        idleQuietMs: 1_000_000,
+        kickoffQuietMs: 1,
+        maxAutoTurns: 20,
+        readSessionMetadata,
+        persistSessionGoal,
+      });
+
+      await runtime.pauseForQuestion('ses-goal', '/repo');
+
+      expect(readSessionMetadata).toHaveBeenCalledWith('ses-goal');
+      expect(persistSessionGoal).toHaveBeenCalledTimes(1);
+      expect(persistSessionGoal.mock.calls[0][0]).toBe('ses-goal');
+      expect(persistSessionGoal.mock.calls[0][1]).toBe('/repo');
+      expect(persistSessionGoal.mock.calls[0][2]).toMatchObject({
+        id: goal.id,
+        status: 'paused',
+        statusReason: 'paused for question',
+      });
+      // Neighbouring Host namespaces must survive the goal write (caller owns
+      // merge; this seam only receives the goal object).
+      expect(metadata.openchamber.assist).toEqual({ recap: 'keep-me' });
+      expect(fetchMock.mock.calls.some(([, init]) => init?.method === 'PATCH')).toBe(false);
+      runtime.stop();
+    });
+  });
+});

package/server/lib/session-index/sync-runtime.js

@@ -117,21 +117,14 @@ export const createSessionIndexSyncRuntime = ({
 
   const fetchDirectory = async (task) => {
     const cached = readDirectory(task.directory);
-    // Empty snapshots are not incrementally eligible. A successful [] still
-    // stores lastSyncedAt as a worktree topology hint; using that watermark as
-    // start would hide older historical roots until the 24h full reconcile.
-    const useIncremental = Boolean(
-      (cached?.sessions?.length ?? 0) > 0
-      && cached?.lastSyncedAt > 0
-      && now() - cached.lastFullSyncedAt < FULL_RECONCILE_INTERVAL_MS
-    );
-    // Keep parity with @opencode-ai/sdk/v2 experimental.session.list. The
-    // regular /session endpoint has different pagination semantics.
-    const url = new URL(buildOpenCodeUrl('/experimental/session'));
+    // v2 `session.list` (`GET /api/session`) exposes cursor pagination only —
+    // no timestamp-incremental (`start`) or `roots` filter. Sync therefore
+    // always fetches a fresh full page and lets replaceDirectory reconcile.
+    // Empty snapshots still store lastSyncedAt as a worktree topology hint.
+    const useIncremental = false;
+    const url = new URL(buildOpenCodeUrl('/session'));
     url.searchParams.set('directory', task.directory);
-    url.searchParams.set('roots', 'true');
     url.searchParams.set('limit', String(SESSION_LIMIT));
-    if (useIncremental) url.searchParams.set('start', String(cached.lastSyncedAt));
 
     const controller = new AbortController();
     currentController = controller;
@@ -148,7 +141,10 @@ export const createSessionIndexSyncRuntime = ({
         error.status = response.status;
         throw error;
       }
-      const sessions = await response.json();
+      const payload = await response.json();
+      // v2 responds `{ data: Session[], cursor }`; tolerate a bare array for
+      // non-v2 test doubles.
+      const sessions = Array.isArray(payload) ? payload : payload?.data;
       if (!Array.isArray(sessions)) throw new Error('Invalid OpenCode session list payload');
       const nextSessions = useIncremental
         ? mergeIncrementalSessions(cached?.sessions, sessions)
@@ -187,7 +183,10 @@ export const createSessionIndexSyncRuntime = ({
     currentWasPreempted = false;
     const timeout = setTimer(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
-      const url = new URL(buildOpenCodeUrl(`/session/${encodeURIComponent(task.sessionID)}/children`));
+      // v2 protocol has no `/session/:id/children` route; child sessions are a
+      // `parentID` filter on the session list (`GET /api/session`).
+      const url = new URL(buildOpenCodeUrl('/session'));
+      url.searchParams.set('parentID', task.sessionID);
       url.searchParams.set('directory', task.directory);
       const response = await fetchFn(url, {
         method: 'GET',
@@ -199,8 +198,12 @@ export const createSessionIndexSyncRuntime = ({
         error.status = response.status;
         throw error;
       }
-      const children = await response.json();
-      if (!Array.isArray(children)) throw new Error('Invalid OpenCode child-session list payload');
+      const payload = await response.json();
+      // v2 wraps list responses in `{ data, cursor }`; accept a bare array too.
+      const children = Array.isArray(payload)
+        ? payload
+        : (Array.isArray(payload?.data) ? payload.data : null);
+      if (!children) throw new Error('Invalid OpenCode child-session list payload');
       sessionIndexService.replaceChildSessions(task.directory, task.sessionID, children);
       return 'completed';
     } catch (error) {

package/server/lib/session-index/sync-runtime.test.js

@@ -68,7 +68,7 @@ describe('session index background sync runtime', () => {
 
     expect(maxActive).toBe(1);
     expect(fetchFn).toHaveBeenCalledTimes(4);
-    expect(fetchFn.mock.calls[0][0].pathname).toBe('/experimental/session');
+    expect(fetchFn.mock.calls[0][0].pathname).toBe('/session');
     expect(service.replaceDirectory).toHaveBeenCalledTimes(2);
     expect(service.replaceChildSessions).toHaveBeenCalledTimes(2);
     expect(runtime.snapshot().sync).toMatchObject({ completed: 2, total: 2, failedDirectories: [] });
@@ -89,7 +89,7 @@ describe('session index background sync runtime', () => {
     await expect(changed).resolves.toMatchObject({ revision: initialRevision + 1 });
   });
 
-  it('uses the persisted watermark for a true incremental merge', async () => {
+  it('v2 session.list has no incremental start — always fetches a full page', async () => {
     const service = createService([{
       directory: '/repo',
       sessions: [session('ses_old', 10)],
@@ -105,7 +105,7 @@ describe('session index background sync runtime', () => {
       getOpenCodeAuthHeaders: () => ({}),
       waitForOpenCodeReady: async () => true,
       fetchFn: async (url) => {
-        if (url.pathname === '/experimental/session') requestedUrl = url;
+        if (url.pathname === '/session') requestedUrl = url;
         return new Response(JSON.stringify([session('ses_new', 20)]), { status: 200 });
       },
       now: () => 2000,
@@ -114,10 +114,11 @@ describe('session index background sync runtime', () => {
     runtime.enqueue(['/repo']);
     await waitUntil(() => isFullyIdle(runtime));
 
-    expect(requestedUrl.searchParams.get('start')).toBe('1000');
+    expect(requestedUrl.searchParams.get('start')).toBeNull();
+    expect(requestedUrl.searchParams.get('roots')).toBeNull();
     expect(service.replaceDirectory.mock.calls[0][0]).toMatchObject({
-      fullSync: false,
-      sessions: [expect.objectContaining({ id: 'ses_new' }), expect.objectContaining({ id: 'ses_old' })],
+      fullSync: true,
+      sessions: [expect.objectContaining({ id: 'ses_new' })],
     });
   });
 
@@ -195,7 +196,7 @@ describe('session index background sync runtime', () => {
     });
   });
 
-  it('omits start when recovering an empty cached directory', async () => {
+  it('recovers an empty cached directory with a full page', async () => {
     const service = createService([{
       directory: '/repo',
       sessions: [],
@@ -211,7 +212,7 @@ describe('session index background sync runtime', () => {
       getOpenCodeAuthHeaders: () => ({}),
       waitForOpenCodeReady: async () => true,
       fetchFn: async (url) => {
-        if (url.pathname === '/experimental/session') requestedUrl = url;
+        if (url.pathname === '/session') requestedUrl = url;
         return new Response(JSON.stringify([session('ses_history', 10)]), { status: 200 });
       },
       now: () => 2000,

package/server/lib/session-metadata/DOCUMENTATION.md

@@ -0,0 +1,41 @@
+# Session metadata store
+
+OpenChamber-owned per-session metadata for Host features that used to live on
+OpenCode `session.metadata`.
+
+## Why
+
+OpenCode 2.x accepts `metadata` only at session create time. There is no
+`PATCH /session/:id` (or equivalent) to update it afterwards. Session goal
+progress — and later other Host state under the same namespace — therefore
+lives in this Host store and is folded back onto proxy session list/detail
+responses so clients still read `session.metadata`.
+
+## Layout
+
+| File | Role |
+|---|---|
+| `session-metadata-store.js` | Durable store: one JSON file per data dir, `{ [sessionID]: metadata }`, RFC 7386 merge patch, refuse-failed-read refuses write |
+| `routes.js` | `PUT /api/openchamber/sessions/:sessionId/metadata` + re-exports `createSessionMetadataStore` |
+| `*.test.js` | Store + route contracts |
+
+## Contracts
+
+- Writes are JSON Merge Patch (RFC 7386): nested objects merge key-by-key; `null` deletes a key.
+- A failed file read is **not** empty success — the store refuses writes until a load succeeds, so unknown disk state is never overwritten with `{}`.
+- Entries are keyed by `sessionID` only (not directory).
+- Successful `PUT` may broadcast `openchamber:session-metadata` with the **full** merged metadata object.
+
+## Server wiring
+
+Wired from `packages/web/server/index.js`:
+
+1. `createSessionMetadataStore({ dataDir: OPENCHAMBER_DATA_DIR })`
+2. proxy `getStoredSessionMetadata: () => store.getAll()`
+3. session-goal `readSessionMetadata` / `persistSessionGoal`
+4. `registerSessionMetadataRoutes` — a successful PUT notifies the goal runtime with a synthetic `session.updated` so a UI create/resume arms the loop
+
+Capability is open (`supported: true`). Manual UI metadata writes, session-goal
+routes, and scheduled-task goal create all persist `openchamber.goal` through
+this store. After first create/resume persist, the server notifies the goal
+runtime with a synthetic `session.updated` so the loop can arm.

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

@@ -0,0 +1,94 @@
+/**
+ * HTTP surface for OpenChamber-owned session metadata.
+ *
+ * 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`).
+ */
+
+import express from 'express';
+
+import { createSessionMetadataStore } from './session-metadata-store.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 {(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,
+    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 {
+      const 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 });
+    }
+  };
+
+  app.put(
+    '/api/openchamber/sessions/:sessionId/metadata',
+    express.json({ limit: '1mb' }),
+    putMetadata,
+  );
+};
+
+export { createSessionMetadataStore, mergeMetadataPatch } from './session-metadata-store.js';

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

@@ -0,0 +1,111 @@
+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,
+    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' } },
+    });
+    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' } } },
+    });
+  });
+
+  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/) });
+  });
+});