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

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

@@ -0,0 +1,41 @@
+/**
+ * Type surface for session-projection.js (consumed by VS Code Extension Host facades).
+ * Runtime implementation stays in the .js module.
+ */
+
+export const HOST_ARCHIVE_METADATA_KEY: string;
+
+export function normalizeSessionEventType(type: unknown): string;
+
+export function isSessionLifecycleEventType(type: unknown): boolean;
+
+export function extractSessionInfoFromPayload(
+  payload: unknown,
+): { id: string; [key: string]: unknown } | null;
+
+export function resolveSessionDirectory(session: unknown): string | null;
+
+export function readHostArchivedAt(metadata: unknown): number | null;
+
+export function resolveProjectedArchivedAt(
+  upstreamArchived: unknown,
+  hostArchivedAt: unknown,
+): number | null | undefined;
+
+export function isSessionArchived(session: unknown): boolean;
+
+export function projectSessionWithHostMetadata(
+  session: unknown,
+  hostMetadata: unknown,
+): unknown;
+
+export function projectSessionWithStoredMap(
+  session: unknown,
+  storedBySessionId: unknown,
+): unknown;
+
+export function projectSessionLifecyclePayload(
+  payload: unknown,
+  readHostMetadata: (sessionId: string) => unknown,
+  options?: { hostReady?: boolean },
+): unknown;

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

@@ -0,0 +1,255 @@
+/**
+ * Host authority projection for OpenCode sessions.
+ *
+ * OpenCode 2.x has no durable archive write. OpenChamber stores archive state
+ * under `metadata.openchamber.archive.archivedAt` and folds it onto session
+ * list/detail/event payloads so clients keep reading `time.archived`.
+ *
+ * Authority:
+ * - positive archivedAt → Host archive wins
+ * - 0 → explicit unarchive (clears time.archived even if upstream still has history)
+ * - missing Host archive key → fall back to upstream time.archived
+ */
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** RFC 7386 merge (local copy — avoid circular import with the metadata store). */
+const mergeMetadataPatch = (current, patch) => {
+  const base = isPlainObject(current) ? { ...current } : {};
+  if (!isPlainObject(patch)) return base;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete base[key];
+      continue;
+    }
+    base[key] = isPlainObject(value) ? mergeMetadataPatch(base[key], value) : value;
+  }
+  return base;
+};
+
+export const HOST_ARCHIVE_METADATA_KEY = 'archive';
+
+const SESSION_LIFECYCLE_BASE = new Set([
+  'session.created',
+  'session.updated',
+  'session.deleted',
+]);
+
+/**
+ * Strip optional version suffixes: `session.updated.v2` → `session.updated`.
+ * @param {unknown} type
+ * @returns {string}
+ */
+export const normalizeSessionEventType = (type) => {
+  if (typeof type !== 'string' || !type) return '';
+  const match = type.match(/^(session\.(?:created|updated|deleted|status|idle|error))(?:\.|$)/);
+  return match ? match[1] : type;
+};
+
+export const isSessionLifecycleEventType = (type) => SESSION_LIFECYCLE_BASE.has(normalizeSessionEventType(type));
+
+/**
+ * Resolve session info from legacy `properties.info`, native v2 `data.info`,
+ * or a bare session object under properties/data.
+ * @param {object | null | undefined} payload
+ */
+export const extractSessionInfoFromPayload = (payload) => {
+  if (!isPlainObject(payload)) return null;
+  const properties = isPlainObject(payload.properties) ? payload.properties : null;
+  const data = isPlainObject(payload.data) ? payload.data : null;
+
+  const candidates = [
+    properties?.info,
+    data?.info,
+    // Bare session on properties/data when shape is already a Session.
+    properties && typeof properties.id === 'string' ? properties : null,
+    data && typeof data.id === 'string' ? data : null,
+  ];
+  for (const candidate of candidates) {
+    if (isPlainObject(candidate) && typeof candidate.id === 'string' && candidate.id) {
+      return candidate;
+    }
+  }
+  return null;
+};
+
+/**
+ * Authoritative worktree directory: v2 `location.directory`, then legacy fields.
+ * @param {object | null | undefined} session
+ */
+export const resolveSessionDirectory = (session) => {
+  if (!isPlainObject(session)) return null;
+  const candidates = [
+    session.location?.directory,
+    session.directory,
+    session.project?.worktree,
+  ];
+  for (const value of candidates) {
+    if (typeof value !== 'string') continue;
+    const normalized = value.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    if (normalized) return normalized;
+  }
+  return null;
+};
+
+/**
+ * @param {unknown} value
+ * @returns {number | null} finite number including 0, else null when absent/invalid
+ */
+export const readHostArchivedAt = (metadata) => {
+  if (!isPlainObject(metadata)) return null;
+  const openchamber = metadata.openchamber;
+  if (!isPlainObject(openchamber)) return null;
+  if (!Object.prototype.hasOwnProperty.call(openchamber, HOST_ARCHIVE_METADATA_KEY)) return null;
+  const archive = openchamber[HOST_ARCHIVE_METADATA_KEY];
+  if (!isPlainObject(archive) || !Object.prototype.hasOwnProperty.call(archive, 'archivedAt')) return null;
+  const value = archive.archivedAt;
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  return value;
+};
+
+/**
+ * @param {unknown} upstreamArchived
+ * @param {number | null} hostArchivedAt
+ * @returns {number | undefined}
+ */
+export const resolveProjectedArchivedAt = (upstreamArchived, hostArchivedAt) => {
+  if (hostArchivedAt === 0) return undefined;
+  if (typeof hostArchivedAt === 'number' && hostArchivedAt > 0) return Math.trunc(hostArchivedAt);
+  if (typeof upstreamArchived === 'number' && Number.isFinite(upstreamArchived) && upstreamArchived > 0) {
+    return Math.trunc(upstreamArchived);
+  }
+  return undefined;
+};
+
+export const isSessionArchived = (session) => {
+  const archived = session?.time?.archived;
+  return typeof archived === 'number' && Number.isFinite(archived) && archived > 0;
+};
+
+/**
+ * Deep-merge Host metadata onto an upstream session and apply archive authority
+ * to `time.archived`. Does not mutate created/updated.
+ *
+ * @param {object | null | undefined} session
+ * @param {object | null | undefined} hostMetadata single session metadata object
+ * @returns {object | null | undefined}
+ */
+export const projectSessionWithHostMetadata = (session, hostMetadata) => {
+  if (!session || typeof session !== 'object' || Array.isArray(session)) return session;
+  if (typeof session.id !== 'string' || !session.id) return session;
+
+  const theirs = isPlainObject(session.metadata) ? session.metadata : {};
+  const ours = isPlainObject(hostMetadata) ? hostMetadata : null;
+  const metadata = ours ? mergeMetadataPatch(theirs, ours) : theirs;
+
+  const hostArchivedAt = readHostArchivedAt(ours ?? metadata);
+  const upstreamArchived = session.time && typeof session.time === 'object'
+    ? session.time.archived
+    : undefined;
+  const projectedArchived = resolveProjectedArchivedAt(upstreamArchived, hostArchivedAt);
+
+  const timeBase = session.time && typeof session.time === 'object' && !Array.isArray(session.time)
+    ? { ...session.time }
+    : {};
+  if (projectedArchived === undefined) delete timeBase.archived;
+  else timeBase.archived = projectedArchived;
+
+  const directory = resolveSessionDirectory(session);
+  const next = {
+    ...session,
+    metadata: Object.keys(metadata).length > 0 ? metadata : (session.metadata ?? metadata),
+    time: timeBase,
+    ...(directory ? { directory } : {}),
+  };
+  if (Object.keys(metadata).length === 0 && session.metadata === undefined) {
+    delete next.metadata;
+  }
+  return next;
+};
+
+/**
+ * @param {object | null | undefined} session
+ * @param {Record<string, object> | null | undefined} storedBySessionId
+ */
+export const projectSessionWithStoredMap = (session, storedBySessionId) => {
+  if (!session || typeof session !== 'object' || typeof session.id !== 'string') return session;
+  if (!storedBySessionId || typeof storedBySessionId !== 'object') {
+    return projectSessionWithHostMetadata(session, null);
+  }
+  const host = storedBySessionId[session.id];
+  return projectSessionWithHostMetadata(session, isPlainObject(host) ? host : null);
+};
+
+const projectLifecycleInner = (payload, readHostMetadata) => {
+  const baseType = normalizeSessionEventType(payload.type);
+  if (baseType !== 'session.created' && baseType !== 'session.updated') return payload;
+
+  const info = extractSessionInfoFromPayload(payload);
+  if (!info) return payload;
+
+  let host = null;
+  if (typeof readHostMetadata === 'function') {
+    try {
+      host = readHostMetadata(info.id);
+    } catch {
+      host = null;
+    }
+  }
+  const projected = projectSessionWithHostMetadata(info, isPlainObject(host) ? host : null);
+  if (projected === info) return payload;
+
+  const next = { ...payload };
+  if (isPlainObject(payload.properties) && payload.properties.info === info) {
+    next.properties = { ...payload.properties, info: projected };
+  } else if (isPlainObject(payload.properties) && payload.properties === info) {
+    next.properties = projected;
+  }
+  if (isPlainObject(payload.data) && payload.data.info === info) {
+    next.data = { ...payload.data, info: projected };
+  } else if (isPlainObject(payload.data) && payload.data === info) {
+    next.data = projected;
+  }
+  // Keep original type string (including version suffix).
+  return next;
+};
+
+/**
+ * Project session.created / session.updated event payloads.
+ * Supports GlobalEvent wrap, versioned types, legacy properties.info, and
+ * native v2 data.info. Non-lifecycle payloads are returned unchanged.
+ * Envelope fields outside the inner payload are preserved.
+ *
+ * @param {unknown} payload
+ * @param {(sessionId: string) => object | null | undefined} readHostMetadata
+ * @param {{ hostReady?: boolean }} [options]
+ *   When `hostReady === false`, lifecycle payloads return `null` (caller drops
+ *   outbound publish). Transcript/message events are unaffected.
+ */
+export const projectSessionLifecyclePayload = (payload, readHostMetadata, options = {}) => {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
+
+  // GlobalEvent wrap: { directory, payload: { type, ... } } — preserve envelope.
+  if (isPlainObject(payload.payload) && typeof payload.payload.type === 'string') {
+    const innerType = normalizeSessionEventType(payload.payload.type);
+    if (SESSION_LIFECYCLE_BASE.has(innerType) || innerType.startsWith('session.')) {
+      if (options.hostReady === false && isSessionLifecycleEventType(payload.payload.type)) {
+        return null;
+      }
+      const inner = projectSessionLifecyclePayload(payload.payload, readHostMetadata, options);
+      if (inner == null) return null;
+      return inner === payload.payload ? payload : { ...payload, payload: inner };
+    }
+  }
+
+  const type = typeof payload.type === 'string' ? payload.type : '';
+  if (options.hostReady === false && isSessionLifecycleEventType(type)) {
+    return null;
+  }
+  if (!isSessionLifecycleEventType(type) && normalizeSessionEventType(type) !== 'session.created'
+    && normalizeSessionEventType(type) !== 'session.updated') {
+    return payload;
+  }
+
+  return projectLifecycleInner(payload, readHostMetadata);
+};

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

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  extractSessionInfoFromPayload,
+  normalizeSessionEventType,
+  projectSessionLifecyclePayload,
+  resolveSessionDirectory,
+} from './session-projection.js';
+
+describe('session projection event shapes', () => {
+  it('normalizes version suffixes', () => {
+    expect(normalizeSessionEventType('session.updated.v2')).toBe('session.updated');
+    expect(normalizeSessionEventType('session.created')).toBe('session.created');
+  });
+
+  it('extracts info from properties.info and data.info', () => {
+    expect(extractSessionInfoFromPayload({
+      type: 'session.updated',
+      properties: { info: { id: 'ses_a' } },
+    })?.id).toBe('ses_a');
+    expect(extractSessionInfoFromPayload({
+      type: 'session.updated.v2',
+      data: { info: { id: 'ses_b' } },
+    })?.id).toBe('ses_b');
+  });
+
+  it('prefers location.directory', () => {
+    expect(resolveSessionDirectory({
+      location: { directory: '/loc' },
+      directory: '/legacy',
+    })).toBe('/loc');
+  });
+
+  it('projects GlobalEvent wrap and preserves envelope directory', () => {
+    const projected = projectSessionLifecyclePayload({
+      directory: '/repo',
+      payload: {
+        type: 'session.updated.v2',
+        data: {
+          info: {
+            id: 'ses_1',
+            time: { created: 1, updated: 2, archived: 50 },
+          },
+        },
+      },
+    }, () => ({ openchamber: { archive: { archivedAt: 99 } } }));
+
+    expect(projected.directory).toBe('/repo');
+    expect(projected.payload.type).toBe('session.updated.v2');
+    expect(projected.payload.data.info.time.archived).toBe(99);
+  });
+
+  it('returns null for lifecycle when hostReady is false', () => {
+    expect(projectSessionLifecyclePayload({
+      type: 'session.updated',
+      properties: { info: { id: 'ses_1', time: {} } },
+    }, () => null, { hostReady: false })).toBeNull();
+  });
+
+  it('leaves message events alone when hostReady is false', () => {
+    const msg = { type: 'message.updated', properties: { info: { role: 'user' } } };
+    expect(projectSessionLifecyclePayload(msg, () => null, { hostReady: false })).toBe(msg);
+  });
+});

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

@@ -0,0 +1,55 @@
+/**
+ * Host-owned isolation markers for system sessions.
+ *
+ * Sidebar / session-index / notifications hide a session only when these
+ * fields are present. Title prefixes are labels and never ownership.
+ *
+ * Every system session creator (scheduled tasks, LLM attachment gateway,
+ * Assistant bindings) must persist the matching patch through the Host
+ * session-metadata store. OpenCode create-time `metadata` is a hint only.
+ */
+
+export const LLM_SESSION_PURPOSE = 'chat-completions';
+
+const nonEmpty = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+
+export const buildScheduledTaskMetadata = ({ projectID, taskID, runID, name } = {}) => {
+  const id = nonEmpty(taskID);
+  if (!id) {
+    throw new Error('scheduled-task metadata requires taskID');
+  }
+  return {
+    openchamber: {
+      scheduledTask: {
+        taskID: id,
+        ...(nonEmpty(projectID) ? { projectID: nonEmpty(projectID) } : {}),
+        ...(nonEmpty(runID) ? { runID: nonEmpty(runID) } : {}),
+        ...(nonEmpty(name) ? { name: nonEmpty(name) } : {}),
+      },
+    },
+  };
+};
+
+export const buildLlmSessionMetadata = (purpose = LLM_SESSION_PURPOSE) => {
+  const resolved = nonEmpty(purpose) || LLM_SESSION_PURPOSE;
+  return {
+    openchamber: {
+      llm: { purpose: resolved },
+    },
+  };
+};
+
+export const buildAssistantSessionMetadata = ({ assistantID, name } = {}) => {
+  const id = nonEmpty(assistantID);
+  if (!id) {
+    throw new Error('assistant session metadata requires assistantID');
+  }
+  return {
+    openchamber: {
+      assistant: {
+        assistantID: id,
+        ...(nonEmpty(name) ? { name: nonEmpty(name) } : {}),
+      },
+    },
+  };
+};

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

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import {
+  LLM_SESSION_PURPOSE,
+  buildAssistantSessionMetadata,
+  buildLlmSessionMetadata,
+  buildScheduledTaskMetadata,
+} from './system-session.js';
+
+describe('system session metadata builders', () => {
+  it('builds scheduled-task isolation from a non-empty taskID', () => {
+    expect(buildScheduledTaskMetadata({
+      projectID: 'project-1',
+      taskID: 'task-1',
+      runID: 'run-1',
+      name: 'Morning Sync',
+    })).toEqual({
+      openchamber: {
+        scheduledTask: {
+          taskID: 'task-1',
+          projectID: 'project-1',
+          runID: 'run-1',
+          name: 'Morning Sync',
+        },
+      },
+    });
+  });
+
+  it('refuses scheduled-task metadata without taskID', () => {
+    expect(() => buildScheduledTaskMetadata({ projectID: 'project-1' })).toThrow(/taskID/);
+  });
+
+  it('builds llm isolation with the chat-completions purpose', () => {
+    expect(buildLlmSessionMetadata()).toEqual({
+      openchamber: { llm: { purpose: LLM_SESSION_PURPOSE } },
+    });
+    expect(buildLlmSessionMetadata('  ')).toEqual({
+      openchamber: { llm: { purpose: LLM_SESSION_PURPOSE } },
+    });
+  });
+
+  it('builds assistant isolation from a non-empty assistantID', () => {
+    expect(buildAssistantSessionMetadata({
+      assistantID: 'assistant_1',
+      name: 'Ops',
+    })).toEqual({
+      openchamber: {
+        assistant: { assistantID: 'assistant_1', name: 'Ops' },
+      },
+    });
+  });
+
+  it('refuses assistant metadata without assistantID', () => {
+    expect(() => buildAssistantSessionMetadata({ name: 'Ops' })).toThrow(/assistantID/);
+  });
+});

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

@@ -5,20 +5,53 @@ conversation's **main subject** (overall feature / goal) with the small model
 (`lib/small-model`), then PATCHes `title` plus `metadata.openchamber.titleRefresh`.
 
 OpenCode only auto-titles once from the first user message
-(`SessionPrompt.ensureTitle`). This module auto-refreshes sparsely (first idle
-of a new session, first newly-sent reply on a fork) and on explicit smart-title
+(`SessionPrompt.ensureTitle`). This module auto-refreshes sparsely (first user
+admission of a new session, first newly-sent reply on a fork) and on explicit smart-title
 requests, naming the durable work being done — not the last wrap-up utterance
 like "commit and push". Background auto refreshes still respect a 5-minute
 throttle (`TITLE_THROTTLE_MS`) when a refresh is armed.
 
 ## Flow
 
+### OpenCode 2 smart-title boundary
+
+Manual requests arrive as Host `openchamber:session-metadata` writes. The
+metadata route's committed-write callback explicitly notifies the title runtime;
+it must not rely on OpenCode echoing Host metadata as `session.updated`.
+`session-access.js` owns the production boundary: official client session reads
+and title updates, a bounded `message.list({ order: 'desc' })` page projected into
+chronological transcript records, and Host metadata reads/merge patches.
+Only changed `titleRefresh` fields are persisted. Transient fields are removed
+with RFC 7386 `null`, so `isGenerating` and `requestedAt` cannot survive a clear.
+Unrelated goal, archive, and ownership metadata is never replaced by a title read.
+
+After a successful title write or generation-state change, an authoritative full session row is published
+as `session.updated` and applied to the session index. Connected clients receive
+both loading metadata and the new title without reselecting the session. Neither
+event represents an execution-status transition: the original session's busy /
+retry status and subsequent execution events remain independently authoritative.
+Publishing the loading row also covers first-send admission arriving before the
+renderer inserts the new session: a metadata-only event would otherwise be ignored
+for that still-unknown row.
+This Host path serves web, Electron, and connected hosted/native mobile clients;
+extension-only VS Code retains the limitation below.
+
 1. `createSessionTitleRuntime` is a consumer of the server's global SSE
    fan-out (`index.js` → `globalMessageStreamHub.subscribeEvent`). Purely event-driven — dormant sessions never
    generate anything.
-  2. Auto title refresh is intentionally sparse (title stability first). A newly
-     observed root `session.created` generates its first title immediately on the
-     first `session.status: idle`. A fork title (`(fork #n)`) waits for its first
+   2. Auto title refresh is intentionally sparse (title stability first). A newly
+      observed root `session.created` generates its first title immediately on
+      the first native `session.inbox.enqueued` user item. Native `data` envelopes
+      are accepted alongside legacy `properties`. The admitted text is bounded
+      to the user-message limit and retained only until the generation starts;
+      it avoids a race with the not-yet-materialized message projection. Synthetic,
+      compaction, and move items cannot start this title. Busy/execution-start
+      events do not cancel this first-title timer: title generation and the main
+      assistant reply run concurrently. Generation publishes `isGenerating` via
+      the existing Host metadata path, then the final title through `session.updated`.
+      Later user admissions/idle events do not regenerate the initial title.
+      The legacy first-idle edge remains a fallback when no admission was observed.
+      A fork title (`(fork #n)`) waits for its first
      newly-created user message; the matching assistant completion triggers an
      immediate title refresh that bypasses inherited title metadata and throttle.
      If the fork's `session.created` was lost (SSE reconnect gap, server or
@@ -27,8 +60,8 @@ throttle (`TITLE_THROTTLE_MS`) when a refresh is armed.
      title + message created after the fork + activity timestamp not yet past
      the fork time), so the first-reply refresh still fires.
      Ordinary later idle transitions do **not** arm another refresh. Any
-     `busy`/`retry` status or a fresh user `message.updated` still clears an
-     already-armed timer (so initial/fork timers cancel if the user keeps going).
+      `busy`/`retry` status or a fresh user `message.updated` still clears an
+      ordinary already-armed timer; an admitted first-title timer is exempt.
      A sidebar smart-title request sets `titleRefresh.requestedAt`; its
      `session.updated` event arms the same flow immediately (forced / manual
      refresh is unaffected by the background gate).