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

package/server/lib/opencode/proxy.js

@@ -11,6 +11,10 @@ import {
   extractDirectoryFromRequest,
   isDirectoryTurnAdmissionPath,
 } from './instance-recovery-runtime.js';
+import {
+  runtimeContractExecutionBlockedBody,
+  shouldBlockRuntimeContractExecution,
+} from './runtime-contract.js';
 import {
   createReasoningOutboundFilter,
   createSseBlockSplitter,
@@ -20,6 +24,25 @@ import {
   readIncludeReasoningQuery,
   stripIncludeReasoningParam,
 } from '../event-stream/reasoning-projection.js';
+import {
+  isSessionLifecycleEventType,
+  projectSessionLifecyclePayload,
+  projectSessionWithStoredMap,
+} from '../session-metadata/session-projection.js';
+
+/**
+ * v2 protocol mounts every JSON/SSE route under `/api`
+ * (`@opencode-ai/protocol` groups). Host traffic is already `/api/*`.
+ * Express `app.use('/api', …)` strips that prefix from `req.url`; put it back
+ * before talking to opencode2. Passing a root `/session` path to v2 returns
+ * the bundled Web UI HTML (`text/html`) and the SDK throws UnsupportedContentType.
+ */
+export const toUpstreamOpenCodeApiPath = (requestUrl) => {
+  const raw = typeof requestUrl === 'string' ? requestUrl : '';
+  if (!raw || raw === '/') return '/api';
+  if (raw.startsWith('/api/') || raw === '/api' || raw.startsWith('/api?')) return raw;
+  return raw.startsWith('/') ? `/api${raw}` : `/api/${raw}`;
+};
 
 export const createDirectoryQueryCanonicalizer = ({ realpath, ...cacheOptions } = {}) => {
   const realpathCache = createRealpathCache({ fallbackOnError: true, realpath, ...cacheOptions });
@@ -183,10 +206,19 @@ const sanitizeSessionListItem = (session) => {
 };
 
 const sanitizeSessionListPayload = (payload) => {
-  if (!Array.isArray(payload)) {
-    return payload;
+  if (Array.isArray(payload)) {
+    return payload.map((session) => sanitizeSessionListItem(session));
+  }
+  if (payload && typeof payload === 'object' && Array.isArray(payload.data)) {
+    return { ...payload, data: payload.data.map((session) => sanitizeSessionListItem(session)) };
   }
-  return payload.map((session) => sanitizeSessionListItem(session));
+  return payload;
+};
+
+const sessionListRecords = (payload) => {
+  if (Array.isArray(payload)) return payload;
+  if (payload && typeof payload === 'object' && Array.isArray(payload.data)) return payload.data;
+  return null;
 };
 
 export const isInteractiveSessionRequest = (method, requestUrl) => {
@@ -221,13 +253,150 @@ export const registerOpenCodeProxy = (app, deps) => {
     SSE_UPSTREAM_CONNECT_TIMEOUT_MS,
     SSE_UPSTREAM_STALL_TIMEOUT_MS,
     getRuntime,
+    /** Optional DI: `{ allowMissingContract: true }` for unit factories only. */
+    getRuntimeContractGateOptions = null,
     getOpenCodeAuthHeaders,
     buildOpenCodeUrl,
     ensureOpenCodeApiPrefix,
     onInteractiveSessionRequest,
     onSessionTurnAdmission,
+    // OpenCode 2.x has no session-metadata update route. When the Host store is
+    // wired, fold its per-session metadata onto list/detail responses so
+    // clients keep reading `session.metadata` where they always did.
+    getStoredSessionMetadata = null,
+    /** Sync committed snapshot; null = not ready / unknown when store is wired. */
+    getStoredSessionMetadataSync = null,
+    /** Await Host metadata load before SSE fan-out (resolves ok/false, does not reject). */
+    ensureSessionMetadataReady = null,
+    /** Best-effort Host metadata cleanup after successful upstream session delete. */
+    onSessionDeleted = null,
   } = deps;
 
+  const storeConfigured = typeof getStoredSessionMetadata === 'function';
+
+  const waitForHostMetadataReady = async () => {
+    if (!storeConfigured) return true;
+    if (typeof ensureSessionMetadataReady === 'function') {
+      try {
+        return await ensureSessionMetadataReady() === true;
+      } catch {
+        return false;
+      }
+    }
+    // Fallback: one getAll attempt.
+    try {
+      await getStoredSessionMetadata();
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  /**
+   * When the Host store is wired, read failures are retryable errors — never
+   * silent upstream-without-overlay (that would look like authoritative empty
+   * Host state). When the store is not wired, leave upstream untouched.
+   * @returns {{ status: 'unconfigured' | 'ok' | 'unavailable', stored?: object, error?: string }}
+   */
+  const readStoredSessionMetadata = async () => {
+    if (!storeConfigured) return { status: 'unconfigured' };
+    try {
+      const stored = await getStoredSessionMetadata();
+      if (!stored || typeof stored !== 'object') {
+        return { status: 'unavailable', error: 'session metadata is unavailable' };
+      }
+      return { status: 'ok', stored };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'session metadata is unavailable';
+      console.warn('[proxy] session metadata unavailable:', message);
+      return { status: 'unavailable', error: message };
+    }
+  };
+
+  const readStoredSessionMetadataSync = () => {
+    if (typeof getStoredSessionMetadataSync !== 'function') {
+      return storeConfigured ? null : undefined;
+    }
+    try {
+      const stored = getStoredSessionMetadataSync();
+      if (stored && typeof stored === 'object') return stored;
+      return null;
+    } catch {
+      return null;
+    }
+  };
+
+  const metadataUnavailableResponse = (res, error) => {
+    res.status(503).json({
+      error: error || 'session metadata is unavailable',
+      code: 'session_metadata_unavailable',
+      retryable: true,
+    });
+  };
+
+  /**
+   * OpenChamber's stored metadata deep-merges onto upstream create-time
+   * metadata, and Host archive authority projects onto `time.archived`.
+   */
+  const overlaySession = (session, stored) => {
+    if (!stored) return session;
+    return projectSessionWithStoredMap(session, stored);
+  };
+
+  /**
+   * @returns {Promise<{ ok: true, payload: unknown } | { ok: false, error: string }>}
+   */
+  const overlayOwnedStateOnList = async (payload) => {
+    const records = sessionListRecords(payload);
+    if (!records) return { ok: true, payload };
+    const meta = await readStoredSessionMetadata();
+    if (meta.status === 'unconfigured') return { ok: true, payload };
+    if (meta.status === 'unavailable') return { ok: false, error: meta.error || 'session metadata is unavailable' };
+    const overlaid = records.map((session) => overlaySession(session, meta.stored));
+    // Preserve `{ data, cursor }` (and any other list envelope fields).
+    return {
+      ok: true,
+      payload: Array.isArray(payload) ? overlaid : { ...payload, data: overlaid },
+    };
+  };
+
+  const createHostSessionSseFilter = () => ({
+    projectEvent: (payload) => {
+      // Transcript/message hot path stays open. Only session lifecycle frames
+      // require Host authority; until the store is ready they are suppressed.
+      const stored = readStoredSessionMetadataSync();
+      if (storeConfigured && stored == null) {
+        const type = payload?.type || payload?.payload?.type;
+        if (isSessionLifecycleEventType(type)) return null;
+        return payload;
+      }
+      if (!stored) return payload;
+      return projectSessionLifecyclePayload(payload, (sessionId) => {
+        const host = stored[sessionId];
+        return host && typeof host === 'object' && !Array.isArray(host) ? host : null;
+      }, { hostReady: true });
+    },
+  });
+
+  const composeSseFilters = (...filters) => {
+    const active = filters.filter(Boolean);
+    if (active.length === 0) return null;
+    if (active.length === 1) return active[0];
+    return {
+      projectEvent: (payload) => {
+        let current = payload;
+        for (const filter of active) {
+          current = filter.projectEvent(current);
+          if (current == null) return null;
+        }
+        return current;
+      },
+      dispose: () => {
+        for (const filter of active) filter.dispose?.();
+      },
+    };
+  };
+
   if (app.get('opencodeProxyConfigured')) {
     return;
   }
@@ -378,6 +547,15 @@ export const registerOpenCodeProxy = (app, deps) => {
   };
 
   const forwardSseRequest = async (req, res) => {
+    // Gate session-lifecycle Host authority before attaching upstream SSE so we
+    // never drop the only lifecycle frame while metadata is still unknown.
+    if (storeConfigured) {
+      const ready = await waitForHostMetadataReady();
+      if (!ready) {
+        return metadataUnavailableResponse(res, 'session metadata is unavailable');
+      }
+    }
+
     const abortController = new AbortController();
     const closeUpstream = () => abortController.abort();
     let upstream = null;
@@ -395,7 +573,13 @@ export const registerOpenCodeProxy = (app, deps) => {
     const includeReasoning = readIncludeReasoningQuery(req.query)
       && readIncludeReasoningFromUrl(requestUrl);
     const reasoningFilter = includeReasoning ? null : createReasoningOutboundFilter();
-    const sseSplitter = includeReasoning ? null : createSseBlockSplitter();
+    const hostSessionFilter = typeof getStoredSessionMetadataSync === 'function'
+      ? createHostSessionSseFilter()
+      : null;
+    const outboundSseFilter = composeSseFilters(reasoningFilter, hostSessionFilter);
+    // Parse SSE blocks when any Host projection filter is active (reasoning
+    // strip and/or session archive authority). Otherwise byte-identical passthrough.
+    const sseSplitter = outboundSseFilter ? createSseBlockSplitter() : null;
 
     req.on('close', closeUpstream);
 
@@ -419,7 +603,7 @@ export const registerOpenCodeProxy = (app, deps) => {
     try {
       // Strip includeReasoning before building the upstream OpenCode path.
       const strippedUrl = stripIncludeReasoningParam(requestUrl);
-      const upstreamPath = strippedUrl.startsWith('/api') ? strippedUrl.slice(4) || '/' : strippedUrl;
+      const upstreamPath = toUpstreamOpenCodeApiPath(strippedUrl);
       const headers = normalizeForwardedDirectoryHeaders(
         collectForwardProxyHeaders(req.headers, getOpenCodeAuthHeaders())
       );
@@ -511,20 +695,20 @@ export const registerOpenCodeProxy = (app, deps) => {
         }
         if (value && value.length > 0) {
           resetStallTimer();
-          if (includeReasoning) {
-            // Enabled path: byte-identical passthrough (existing behavior).
+          if (!outboundSseFilter || !sseSplitter) {
+            // No Host projection: byte-identical passthrough.
             sseBoundary.observe(value);
             const canContinue = await enqueueSseWrite(value);
             if (!canContinue) {
               break;
             }
           } else {
-            // Disabled path: parse SSE blocks, drop reasoning, re-serialize.
-            // Preserves id/event lines and GlobalEvent wrap when unchanged drop-only.
+            // Parse SSE blocks, apply reasoning strip + Host archive authority.
+            // Preserves id/event lines and GlobalEvent wrap when unchanged.
             const blocks = sseSplitter.push(value);
             let canContinue = true;
             for (const block of blocks) {
-              const filtered = filterSseBlock(block, reasoningFilter);
+              const filtered = filterSseBlock(block, outboundSseFilter);
               if (!filtered) {
                 continue;
               }
@@ -539,9 +723,9 @@ export const registerOpenCodeProxy = (app, deps) => {
         }
       }
 
-      if (!includeReasoning && sseSplitter) {
+      if (outboundSseFilter && sseSplitter) {
         for (const block of sseSplitter.finish()) {
-          const filtered = filterSseBlock(block, reasoningFilter);
+          const filtered = filterSseBlock(block, outboundSseFilter);
           if (filtered) {
             sseBoundary.observe(filtered);
             await enqueueSseWrite(filtered);
@@ -570,7 +754,7 @@ export const registerOpenCodeProxy = (app, deps) => {
     } finally {
       clearConnectTimer();
       clearStallTimer();
-      reasoningFilter?.dispose?.();
+      outboundSseFilter?.dispose?.();
       if (heartbeatTimer) {
         clearTimeout(heartbeatTimer);
         heartbeatTimer = null;
@@ -588,7 +772,7 @@ export const registerOpenCodeProxy = (app, deps) => {
     }
   };
 
-  const fetchSessionListPayload = async (upstreamPath, { req = null, timeoutMs = null } = {}) => {
+  const fetchSessionListPayload = async (upstreamPath, { req = null, timeoutMs = null, method = 'GET' } = {}) => {
     const headers = req
       ? {
           ...normalizeForwardedDirectoryHeaders(collectForwardProxyHeaders(req.headers, getOpenCodeAuthHeaders())),
@@ -601,7 +785,7 @@ export const registerOpenCodeProxy = (app, deps) => {
           'accept-encoding': 'identity',
         };
     const upstream = await fetch(buildOpenCodeUrl(upstreamPath, ''), {
-      method: 'GET',
+      method: method || 'GET',
       headers,
       ...(typeof timeoutMs === 'number' ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
     });
@@ -625,8 +809,7 @@ export const registerOpenCodeProxy = (app, deps) => {
     const requestUrl = typeof req.originalUrl === 'string' && req.originalUrl.length > 0
       ? req.originalUrl
       : (typeof req.url === 'string' ? req.url : '');
-    const upstreamPathRaw = requestUrl.startsWith('/api') ? requestUrl.slice(4) || '/' : requestUrl;
-    return canonicalizeDirectoryQuery(upstreamPathRaw);
+    return canonicalizeDirectoryQuery(toUpstreamOpenCodeApiPath(requestUrl));
   };
 
   const forwardSanitizedSessionListRequest = async (req, res, next, logLabel) => {
@@ -643,14 +826,18 @@ export const registerOpenCodeProxy = (app, deps) => {
         return;
       }
 
-      if (result.parseError || !Array.isArray(result.payload)) {
+      if (result.parseError || !sessionListRecords(result.payload)) {
         res.setHeader('content-type', result.contentType);
         res.end(result.bodyText);
         return;
       }
 
       res.setHeader('content-type', result.contentType);
-      res.json(sanitizeSessionListPayload(result.payload));
+      const overlaid = await overlayOwnedStateOnList(sanitizeSessionListPayload(result.payload));
+      if (!overlaid.ok) {
+        return metadataUnavailableResponse(res, overlaid.error);
+      }
+      res.json(overlaid.payload);
     } catch (error) {
       if (isAbortError(error)) {
         return;
@@ -735,7 +922,7 @@ export const registerOpenCodeProxy = (app, deps) => {
   const READINESS_HOLD_POLL_MS = 75;
   const READINESS_HOLD_MAX_MS = 6000;
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-  const isStillWaiting = (runtimeState) => {
+  const isProcessWarmingUp = (runtimeState) => {
     const waitElapsed = runtimeState.openCodeNotReadySince === 0 ? 0 : Date.now() - runtimeState.openCodeNotReadySince;
     return (
       (!runtimeState.isOpenCodeReady && (runtimeState.openCodeNotReadySince === 0 || waitElapsed < OPEN_CODE_READY_GRACE_MS)) ||
@@ -744,6 +931,18 @@ export const registerOpenCodeProxy = (app, deps) => {
     );
   };
 
+  // Process warmup keeps the existing grace window. V1 migration is separate:
+  // admitTranscript=false holds with no grace until the gate admits or the
+  // client cancels. After grace, a still-running migration must not next()
+  // an empty session list through as an authoritative success.
+  const isMigrationBlockingTranscript = (runtimeState) => (
+    runtimeState?.v1Migration != null && runtimeState.v1Migration.admitTranscript !== true
+  );
+
+  const shouldHoldProxiedRequest = (runtimeState) => (
+    isProcessWarmingUp(runtimeState) || isMigrationBlockingTranscript(runtimeState)
+  );
+
   app.use('/api', async (req, res, next) => {
     if (
       req.path.startsWith('/themes/custom') ||
@@ -753,23 +952,62 @@ export const registerOpenCodeProxy = (app, deps) => {
       req.path.startsWith('/config/settings') ||
       req.path.startsWith('/config/skills') ||
       req.path === '/config/reload' ||
-      req.path === '/health'
+      req.path === '/health' ||
+      req.path === '/opencode/health' ||
+      req.path === '/opencode/version' ||
+      req.path === '/opencode/contract' ||
+      req.path === '/opencode/upgrade-status' ||
+      req.path === '/opencode/upgrade'
     ) {
       return next();
     }
 
-    if (!isStillWaiting(getRuntime())) {
+    // Ticket 11: limit execution when the running serve fails contract admission.
+    // Diagnostics, reads, and stop-task stay available; health success alone is not full semantics.
+    // Require explicit executionAllowed === true for the *current* instance (null/pending blocks).
+    // Gate again after readiness hold so initial-unknown → ready-incompatible cannot slip through.
+    const pathForGate = req.originalUrl || req.url || req.path;
+    const gateOptions = typeof getRuntimeContractGateOptions === 'function'
+      ? getRuntimeContractGateOptions()
+      : {};
+    const blockedByContract = () => {
+      const contract = getRuntime()?.runtimeContract;
+      if (shouldBlockRuntimeContractExecution(req.method, pathForGate, contract, gateOptions)) {
+        return runtimeContractExecutionBlockedBody(contract);
+      }
+      return null;
+    };
+
+    const earlyBlock = blockedByContract();
+    if (earlyBlock) {
+      return res.status(409).json(earlyBlock);
+    }
+
+    if (!shouldHoldProxiedRequest(getRuntime())) {
+      const lateBlock = blockedByContract();
+      if (lateBlock) {
+        return res.status(409).json(lateBlock);
+      }
       return next();
     }
 
-    const deadline = Date.now() + Math.min(OPEN_CODE_READY_GRACE_MS, READINESS_HOLD_MAX_MS);
-    while (Date.now() < deadline) {
+    const processDeadline = Date.now() + Math.min(OPEN_CODE_READY_GRACE_MS, READINESS_HOLD_MAX_MS);
+    while (true) {
       // Client gave up (closed/aborted) — stop holding.
       if (res.writableEnded || req.aborted) return;
-      await sleep(READINESS_HOLD_POLL_MS);
-      if (!isStillWaiting(getRuntime())) {
+      const runtimeState = getRuntime();
+      if (!shouldHoldProxiedRequest(runtimeState)) {
+        // Re-evaluate after wait: startup may have published incompatible/pending.
+        const afterHoldBlock = blockedByContract();
+        if (afterHoldBlock) {
+          return res.status(409).json(afterHoldBlock);
+        }
         return next();
       }
+      if (!isMigrationBlockingTranscript(runtimeState) && Date.now() >= processDeadline) {
+        break;
+      }
+      await sleep(READINESS_HOLD_POLL_MS);
     }
 
     if (!res.headersSent) {
@@ -852,7 +1090,11 @@ export const registerOpenCodeProxy = (app, deps) => {
           return bTime - aTime;
         });
         console.log(`[SessionMerge] ${globalSessions?.length || 0} global + ${extraSessions.length} extra = ${merged.length} total`);
-        return res.json(sanitizeSessionListPayload(merged));
+        const overlaid = await overlayOwnedStateOnList(sanitizeSessionListPayload(merged));
+        if (!overlaid.ok) {
+          return metadataUnavailableResponse(res, overlaid.error);
+        }
+        return res.json(overlaid.payload);
       } catch (error) {
         console.log(`[SessionMerge] Error: ${error.message}`);
         return res.status(500).json({ error: error.message || 'Failed to merge Windows sessions' });
@@ -864,6 +1106,102 @@ export const registerOpenCodeProxy = (app, deps) => {
     return forwardSanitizedSessionListRequest(req, res, next, 'session.list');
   });
 
+  // One session: the same metadata overlay as the list, so a detail read agrees
+  // with the list it came from. Everything else about the record is forwarded
+  // untouched. Without a store, fall through to the generic proxy.
+  app.get('/api/session/:sessionID', async (req, res, next) => {
+    if (!storeConfigured) return next();
+    // Nested routes (message, children, …) are registered separately; Express
+    // still matches this pattern for bare session ids only when no further
+    // segment is present — but be defensive if a child path slips through.
+    if (req.path.includes('/message') || String(req.params.sessionID || '').includes('/')) {
+      return next();
+    }
+    try {
+      const upstreamPath = await getRequestUpstreamPath(req);
+      const result = await fetchSessionListPayload(upstreamPath, { req });
+
+      const record = result.isJson && !result.parseError ? result.payload : null;
+      const session = record && typeof record === 'object' && !Array.isArray(record)
+        ? (record.data && typeof record.data === 'object' && !Array.isArray(record.data) ? record.data : record)
+        : null;
+      if (!session || typeof session.id !== 'string') {
+        res.status(result.upstream.status);
+        applyForwardProxyResponseHeaders(result.upstream.headers, res);
+        res.setHeader('content-type', result.contentType);
+        res.end(result.bodyText);
+        return;
+      }
+
+      const meta = await readStoredSessionMetadata();
+      if (meta.status === 'unavailable') {
+        return metadataUnavailableResponse(res, meta.error);
+      }
+
+      res.status(result.upstream.status);
+      applyForwardProxyResponseHeaders(result.upstream.headers, res);
+      res.setHeader('content-type', result.contentType);
+
+      if (meta.status === 'unconfigured') {
+        res.end(result.bodyText);
+        return;
+      }
+
+      const overlaid = overlaySession(session, meta.stored);
+      res.json(record.data && typeof record.data === 'object' && !Array.isArray(record.data)
+        ? { ...record, data: overlaid }
+        : overlaid);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      console.error('[proxy] OpenCode session.get proxy error:', error?.message ?? error);
+      if (!res.headersSent) {
+        res.status(503).json({ error: 'OpenCode service unavailable' });
+        return;
+      }
+      next(error);
+    }
+  });
+
+  // Successful upstream delete → idempotent Host metadata cleanup. Failures are
+  // observable (logged) and compensated by session.deleted event ingest.
+  app.delete('/api/session/:sessionID', async (req, res, next) => {
+    if (typeof onSessionDeleted !== 'function') return next();
+    const sessionID = typeof req.params?.sessionID === 'string' ? req.params.sessionID.trim() : '';
+    if (!sessionID || sessionID.includes('/')) return next();
+    try {
+      const upstreamPath = await getRequestUpstreamPath(req);
+      const result = await fetchSessionListPayload(upstreamPath, {
+        req,
+        method: 'DELETE',
+      });
+      res.status(result.upstream.status);
+      applyForwardProxyResponseHeaders(result.upstream.headers, res);
+      res.setHeader('content-type', result.contentType || 'application/json');
+      if (result.upstream.status >= 200 && result.upstream.status < 300) {
+        try {
+          const cleanup = onSessionDeleted(sessionID);
+          if (cleanup && typeof cleanup.catch === 'function') {
+            cleanup.catch((error) => {
+              console.warn('[proxy] session metadata cleanup after delete failed (retry via event):', error?.message ?? error);
+            });
+          }
+        } catch (error) {
+          console.warn('[proxy] session metadata cleanup after delete failed (retry via event):', error?.message ?? error);
+        }
+      }
+      // Upstream failure keeps Host metadata (do not cleanup).
+      res.end(result.bodyText);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      console.error('[proxy] OpenCode session.delete proxy error:', error?.message ?? error);
+      if (!res.headersSent) {
+        res.status(503).json({ error: 'OpenCode service unavailable' });
+        return;
+      }
+      next(error);
+    }
+  });
+
   // Official session.messages list (not exact message — that is owned by
   // session-turn-pages and registered before this proxy).
   app.get('/api/session/:sessionID/message', (req, res, next) => {
@@ -881,7 +1219,9 @@ export const registerOpenCodeProxy = (app, deps) => {
   const apiProxy = createProxyMiddleware({
     target: resolveProxyTarget(),
     changeOrigin: true,
-    pathRewrite: { '^/api': '' },
+    // Express already stripped the `/api` mount. Restore it so v2 receives
+    // `/api/agent` rather than `/agent` (which serves the Web UI HTML).
+    pathRewrite: (pathValue) => toUpstreamOpenCodeApiPath(pathValue),
     timeout: PROXY_REQUEST_TIMEOUT_MS,
     proxyTimeout: PROXY_REQUEST_TIMEOUT_MS,
     // Dynamic target — port can change after restart