ompchamber 0.3.0

package/src/shared/lib/omp/subagent/parse.ts

@@ -0,0 +1,284 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Lenient parsers + roster fold for oh-my-pi subagent frames and snapshots.
+ * Defensive by design: unknown statuses / malformed payloads must never
+ * fabricate a live roster entry. Wire shapes live in `@/types/omp/subagent`.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import type { SubagentActivityEvent, SubagentAgentSource, SubagentInfo, SubagentProgress, SubagentSnapshotLike } from '@/shared/types/omp/subagent';
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function asAgentSource(value: unknown): SubagentAgentSource | undefined {
+  return value === 'bundled' || value === 'user' || value === 'project' ? value : undefined;
+}
+
+function asProgressStatus(value: unknown): SubagentProgress['status'] | undefined {
+  return value === 'pending' || value === 'running' || value === 'completed' || value === 'failed' || value === 'aborted'
+    ? value
+    : undefined;
+}
+
+/** Defensively copy an AgentProgress-shaped object into a SubagentProgress. */
+export function parseSubagentProgress(value: unknown): SubagentProgress | undefined {
+  if (!isRecord(value)) return undefined;
+  const out: SubagentProgress = {};
+  const index = asNumber(value.index);
+  if (index !== undefined) out.index = index;
+  const id = asString(value.id);
+  if (id !== undefined) out.id = id;
+  const agent = asString(value.agent);
+  if (agent !== undefined) out.agent = agent;
+  const agentSource = asAgentSource(value.agentSource);
+  if (agentSource !== undefined) out.agentSource = agentSource;
+  const status = asProgressStatus(value.status);
+  if (status !== undefined) out.status = status;
+  const task = asString(value.task);
+  if (task !== undefined) out.task = task;
+  const assignment = asString(value.assignment);
+  if (assignment !== undefined) out.assignment = assignment;
+  const description = asString(value.description);
+  if (description !== undefined) out.description = description;
+  const lastIntent = asString(value.lastIntent);
+  if (lastIntent !== undefined) out.lastIntent = lastIntent;
+  const currentTool = asString(value.currentTool);
+  if (currentTool !== undefined) out.currentTool = currentTool;
+  const currentToolArgs = asString(value.currentToolArgs);
+  if (currentToolArgs !== undefined) out.currentToolArgs = currentToolArgs;
+  const currentToolStartMs = asNumber(value.currentToolStartMs);
+  if (currentToolStartMs !== undefined) out.currentToolStartMs = currentToolStartMs;
+  if (Array.isArray(value.recentTools)) out.recentTools = value.recentTools as SubagentProgress['recentTools'];
+  if (Array.isArray(value.recentOutput)) out.recentOutput = value.recentOutput.filter((x): x is string => typeof x === 'string');
+  const toolCount = asNumber(value.toolCount);
+  if (toolCount !== undefined) out.toolCount = toolCount;
+  const requests = asNumber(value.requests);
+  if (requests !== undefined) out.requests = requests;
+  const tokens = asNumber(value.tokens);
+  if (tokens !== undefined) out.tokens = tokens;
+  const contextTokens = asNumber(value.contextTokens);
+  if (contextTokens !== undefined) out.contextTokens = contextTokens;
+  const contextWindow = asNumber(value.contextWindow);
+  if (contextWindow !== undefined) out.contextWindow = contextWindow;
+  const cost = asNumber(value.cost);
+  if (cost !== undefined) out.cost = cost;
+  const durationMs = asNumber(value.durationMs);
+  if (durationMs !== undefined) out.durationMs = durationMs;
+  if (typeof value.modelOverride === 'string' || (Array.isArray(value.modelOverride) && value.modelOverride.every((x) => typeof x === 'string'))) {
+    out.modelOverride = value.modelOverride;
+  }
+  const modelRole = asString(value.modelRole);
+  if (modelRole !== undefined) out.modelRole = modelRole;
+  const resolvedModel = asString(value.resolvedModel);
+  if (resolvedModel !== undefined) out.resolvedModel = resolvedModel;
+  if (typeof value.resolvedModelIsFallback === 'boolean') out.resolvedModelIsFallback = value.resolvedModelIsFallback;
+  if (isRecord(value.retryState)) {
+    const attempt = asNumber(value.retryState.attempt);
+    const maxAttempts = asNumber(value.retryState.maxAttempts);
+    const delayMs = asNumber(value.retryState.delayMs);
+    const errorMessage = asString(value.retryState.errorMessage);
+    const startedAtMs = asNumber(value.retryState.startedAtMs);
+    // All fields are documented as required upstream; fabricating defaults for
+    // a partial frame would render a false "retrying" state.
+    if (attempt !== undefined && maxAttempts !== undefined && delayMs !== undefined && errorMessage !== undefined && startedAtMs !== undefined) {
+      out.retryState = { attempt, maxAttempts, delayMs, errorMessage, startedAtMs };
+    }
+  }
+  if (isRecord(value.retryFailure)) {
+    const attempt = asNumber(value.retryFailure.attempt);
+    const errorMessage = asString(value.retryFailure.errorMessage);
+    if (attempt !== undefined && errorMessage !== undefined) {
+      out.retryFailure = { attempt, errorMessage };
+    }
+  }
+  if (value.inflightTaskDetails !== undefined) out.inflightTaskDetails = value.inflightTaskDetails;
+  if (isRecord(value.extractedToolData)) out.extractedToolData = value.extractedToolData as Record<string, unknown[]>;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Map a get_subagents snapshot to roster form. */
+export function parseSubagentSnapshot(value: unknown): SubagentInfo | undefined {
+  if (!isRecord(value)) return undefined;
+  const id = asString(value.id);
+  const agent = asString(value.agent);
+  if (!id || !agent) return undefined;
+  let status: SubagentInfo['status'];
+  if (value.status === 'started' || value.status === 'completed' || value.status === 'failed' || value.status === 'aborted') {
+    status = value.status;
+  } else if (value.status === 'pending' || value.status === 'running') {
+    status = 'started';
+  } else {
+    // Unknown/future lifecycle status — a malformed frame must not fabricate a
+    // live chip.
+    return undefined;
+  }
+  const info: SubagentInfo = {
+    id,
+    agent,
+    status,
+    index: asNumber(value.index) ?? -1,
+    source: 'live',
+  };
+  const agentSource = asAgentSource(value.agentSource);
+  if (agentSource !== undefined) info.agentSource = agentSource;
+  const description = asString(value.description);
+  if (description !== undefined) info.description = description;
+  const task = asString(value.task);
+  if (task !== undefined) info.task = task;
+  const assignment = asString(value.assignment);
+  if (assignment !== undefined) info.assignment = assignment;
+  const sessionFile = asString(value.sessionFile);
+  if (sessionFile !== undefined) info.sessionFile = sessionFile;
+  const parentToolCallId = asString(value.parentToolCallId);
+  if (parentToolCallId !== undefined) info.parentToolCallId = parentToolCallId;
+  // Snapshots without a wire-carried lastUpdate would be treated as
+  // infinitely new by mergeSubagentRoster's skipNewerThan guard, letting
+  // back-to-back stale snapshots regress terminal status — stamp read time.
+  const lastUpdate = asNumber(value.lastUpdate) ?? Date.now();
+  info.lastUpdate = lastUpdate;
+  const progress = parseSubagentProgress(value.progress);
+  if (progress !== undefined) info.progress = progress;
+  return info;
+}
+
+/** Map a subagent_lifecycle frame to roster form. Stricter than a snapshot:
+ * requires id + status, and unlike snapshots the wire may omit `agent` (it
+ * defaults to "subagent"). Unknown statuses must not fabricate a live chip. */
+export function parseSubagentLifecycle(value: unknown): SubagentInfo | undefined {
+  if (!isRecord(value)) return undefined;
+  const id = asString(value.id);
+  const statusRaw = asString(value.status);
+  if (!id || !statusRaw) return undefined;
+  if (statusRaw !== 'started' && statusRaw !== 'completed' && statusRaw !== 'failed' && statusRaw !== 'aborted') return undefined;
+  const info: SubagentInfo = {
+    id,
+    agent: asString(value.agent) ?? 'subagent',
+    status: statusRaw,
+    index: asNumber(value.index) ?? -1,
+    lastUpdate: Date.now(),
+    source: 'live',
+  };
+  const agentSource = asAgentSource(value.agentSource);
+  if (agentSource !== undefined) info.agentSource = agentSource;
+  const description = asString(value.description);
+  if (description !== undefined) info.description = description;
+  const sessionFile = asString(value.sessionFile);
+  if (sessionFile !== undefined) info.sessionFile = sessionFile;
+  const parentToolCallId = asString(value.parentToolCallId);
+  if (parentToolCallId !== undefined) info.parentToolCallId = parentToolCallId;
+  if (typeof value.detached === 'boolean') info.detached = value.detached;
+  return info;
+}
+
+/** Extract a compact live-activity entry from a subagent_event payload. */
+export function parseSubagentActivityEvent(value: unknown): SubagentActivityEvent | null {
+  if (!isRecord(value)) return null;
+  const event = isRecord(value.event) ? value.event : null;
+  if (!event) return null;
+  const type = asString(event.type);
+  const ts = Date.now();
+  if (type === 'tool_execution_start') {
+    const toolName = asString(event.toolName) ?? 'tool';
+    const intent = asString(event.intent)?.trim();
+    if (intent) return { kind: 'tool', label: `→ ${toolName} — ${intent}`, ts };
+    const args = isRecord(event.args) ? Object.keys(event.args).slice(0, 3).join(', ') : undefined;
+    return { kind: 'tool', label: args ? `→ ${toolName} (${args})` : `→ ${toolName}`, ts };
+  }
+  if (type === 'message_end') {
+    const message = isRecord(event.message) ? event.message : null;
+    if (message && message.role === 'assistant') {
+      const content = message.content;
+      const text = typeof content === 'string'
+        ? content
+        : Array.isArray(content)
+          ? content
+            .filter((block): block is { type: 'text'; text?: unknown } => isRecord(block) && block.type === 'text')
+            .map((block) => (typeof block.text === 'string' ? block.text : ''))
+            .join('\n')
+          : '';
+      const trimmed = text.trim();
+      if (trimmed) return { kind: 'text', label: trimmed.slice(0, 140), ts };
+    }
+  }
+  if (type === 'notice') {
+    const message = asString(event.message);
+    if (message) return { kind: 'notice', label: message.slice(0, 140), ts };
+  }
+  return null;
+}
+
+/** Parse a get_subagents response body into roster entries. */
+export function parseSubagentRosterResponse(value: unknown): SubagentInfo[] {
+  if (!isRecord(value)) return [];
+  const raw = value.subagents;
+  if (!Array.isArray(raw)) return [];
+  const out: SubagentInfo[] = [];
+  for (const entry of raw) {
+    const parsed = parseSubagentSnapshot(entry as SubagentSnapshotLike | unknown);
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+
+/** Ordinal for sorting: a batch the file has not recorded yet sorts last. */
+const batchSeqOf = (subagent: SubagentInfo): number =>
+  subagent.batchSeq ?? Number.MAX_SAFE_INTEGER;
+
+/** Spawning call first, then position inside that call, then id. */
+export function compareSubagents(a: SubagentInfo, b: SubagentInfo): number {
+  return batchSeqOf(a) - batchSeqOf(b) || a.index - b.index || a.id.localeCompare(b.id);
+}
+
+/**
+ * Fold roster entries into the previous list, ordered by spawning call and then
+ * position within that call.
+ *
+ * Live frames win over on-disk history for the same id. `skipNewerThan` lets a
+ * caller refuse to overwrite entries that live frames touched after a
+ * point-in-time snapshot was requested, so a stale snapshot cannot regress a
+ * child's terminal status.
+ *
+ * `batchSeq` is the one field that survives every precedence rule: only the
+ * session file knows launch order, and the history entry carrying it is often
+ * the one that loses to a newer live frame. A batch the file has not recorded
+ * yet simply sorts last until the next history merge supplies its ordinal.
+ */
+export function mergeSubagentRoster(
+  prev: SubagentInfo[],
+  incoming: SubagentInfo[],
+  skipNewerThan?: number,
+): SubagentInfo[] {
+  const byId = new Map(prev.map((subagent) => [subagent.id, subagent]));
+  for (const entry of incoming) {
+    const existing = byId.get(entry.id);
+    if (!existing) {
+      byId.set(entry.id, entry);
+      continue;
+    }
+    const batchSeq = existing.batchSeq ?? entry.batchSeq;
+    if (skipNewerThan !== undefined && (existing.lastUpdate ?? 0) >= skipNewerThan) {
+      if (batchSeq !== existing.batchSeq) byId.set(entry.id, { ...existing, batchSeq });
+      continue;
+    }
+    if (entry.source === 'history' && existing.source !== 'history') {
+      if (batchSeq !== existing.batchSeq) byId.set(entry.id, { ...existing, batchSeq });
+      continue;
+    }
+    if (entry.source !== 'history' && existing.source === 'history') {
+      byId.set(entry.id, { ...entry, batchSeq });
+      continue;
+    }
+    byId.set(entry.id, { ...existing, ...entry, batchSeq });
+  }
+  return [...byId.values()].sort(compareSubagents);
+}

package/src/shared/lib/omp/subagent/result-details.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Small lenient guards + task SingleResult projections shared by subagent
+ * history extraction. Kept out of `history.ts` so the roster fold stays the
+ * only concern of that module (and under the file-size ceiling).
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import type { SubagentAgentSource, SubagentHistoryResult } from '@/shared/types/omp/subagent';
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+export function asAgentSource(value: unknown): SubagentAgentSource | undefined {
+  return value === 'bundled' || value === 'user' || value === 'project' ? value : undefined;
+}
+
+/** Settled cost rides `usage.cost` on a task SingleResult; top-level `cost` is
+ *  absent there, so both shapes feed the same projection. */
+export function taskResultUsageCost(usage: unknown): number | undefined {
+  if (!isRecord(usage)) return undefined;
+  const cost = isRecord(usage.cost) ? usage.cost : undefined;
+  if (!cost) return undefined;
+  const total = asNumber(cost.total);
+  if (total !== undefined) return total;
+  const input = asNumber(cost.input);
+  const output = asNumber(cost.output);
+  if (input !== undefined && output !== undefined) return input + output;
+  return undefined;
+}
+
+/** Project `structuredOutput` to its documented UI fields only — `data` is
+ *  arbitrary upstream payload and must never ride the roster response. */
+export function taskResultStructuredOutput(
+  value: unknown,
+): NonNullable<SubagentHistoryResult['structuredOutput']> | undefined {
+  if (!isRecord(value)) return undefined;
+  const out: NonNullable<SubagentHistoryResult['structuredOutput']> = {};
+  for (const key of ['source', 'mode', 'status', 'error'] as const) {
+    const text = asString(value[key]);
+    if (text !== undefined) out[key] = text;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}

package/src/shared/lib/omp/subagent/transcript-client.ts

@@ -0,0 +1,178 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Subagent transcript page plumbing shared by the live RPC path
+ * (`get_subagent_messages`) and the on-disk history route
+ * (`GET /api/sessions/:id/subagents/:subagentId`): wire → ChatMessageData
+ * conversion and byte-offset paging.
+ */
+
+import type { ChatMessageData, SubagentMessagesPage } from '@/shared/types';
+import { toChatMessage } from '@/shared/lib/omp/session/mapper';
+import { extractText } from '@/shared/lib/omp/session/parse-message-blocks';
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** Normalize one wire message: the RPC may hand back bare omp AgentMessages
+ *  or JSONL entries wrapping them as `{ message: {...} }`. */
+function normalizeRawMessage(value: unknown): Record<string, unknown> | null {
+  if (!isRecord(value)) return null;
+  const inner = isRecord(value.message) ? value.message : null;
+  if (!inner) return value;
+  const out: Record<string, unknown> = { ...inner };
+  if (out.id === undefined && typeof value.id === 'string') out.id = value.id;
+  if (out.timestamp === undefined && typeof value.timestamp === 'number') out.timestamp = value.timestamp;
+  return out;
+}
+
+export function convertMessages(raw: unknown[], streaming: boolean): ChatMessageData[] {
+  const out: ChatMessageData[] = [];
+  for (const item of raw) {
+    if (isRecord(item)) {
+      const entryType = typeof item.type === 'string' ? item.type : '';
+      if (entryType === 'custom' || entryType === 'custom_message') {
+        const customType = typeof item.customType === 'string' ? item.customType : '';
+        if (customType === 'session_exit') {
+          // Runtime plumbing — exit notices are never rendered.
+          continue;
+        }
+        if (customType === 'launch-completion' || typeof item.content === 'string') {
+          const contentStr = typeof item.content === 'string' ? item.content : '';
+          const notice = contentStr.replace(/<\/?system-notice[^>]*>/g, '').trim();
+          if (notice) {
+            out.push({
+              id: typeof item.id === 'string' ? item.id : `notice-${Date.now()}`,
+              role: 'ai',
+              content: '',
+              notice,
+              date: typeof item.timestamp === 'string' ? new Date(item.timestamp).toISOString() : undefined,
+            });
+          }
+          continue;
+        }
+      }
+      if (entryType && entryType !== 'message') continue;
+    }
+    const record = normalizeRawMessage(item);
+    if (!record) continue;
+
+    // toolResult rows are plumbing; pair their output & details with matching tool call.
+    if (record.role === 'toolResult') {
+      const toolCallId = typeof record.toolCallId === 'string' ? record.toolCallId : undefined;
+      const outputText = extractText(record.content);
+      const details = isRecord(record.details) ? record.details : undefined;
+      const isError = record.isError === true;
+      for (let i = out.length - 1; i >= 0; i--) {
+        const tc = out[i].toolCalls?.find((t) => (toolCallId ? t.id === toolCallId : t.name === record.toolName));
+        if (tc) {
+          if (outputText) tc.output = outputText;
+          if (details) tc.details = details;
+          tc.status = isError ? 'error' : 'success';
+          break;
+        }
+      }
+      continue;
+    }
+
+    const converted = toChatMessage(record, streaming);
+    if (converted) out.push(converted);
+  }
+  return out;
+}
+
+/** Append/replace by message id so tail refetches do not duplicate rows and a
+ *  streamed message is replaced in place once finalized. */
+export function mergeMessages(prev: ChatMessageData[], incoming: ChatMessageData[]): ChatMessageData[] {
+  if (incoming.length === 0) return prev;
+  const positions = new Map(prev.map((message, index) => [message.id, index]));
+  const next = [...prev];
+  for (const message of incoming) {
+    const index = positions.get(message.id);
+    if (index === undefined) {
+      positions.set(message.id, next.length);
+      next.push(message);
+    } else {
+      next[index] = message;
+    }
+  }
+  return next;
+}
+
+/** Read the `{ success, data }` RPC envelope (accepting a bare page too). */
+function asMessagesPage(value: unknown, fallbackFrom: number, fallbackFile: string | undefined): SubagentMessagesPage | null {
+  if (!isRecord(value) || !Array.isArray(value.messages)) return null;
+  const fromByte = typeof value.fromByte === 'number' ? value.fromByte : fallbackFrom;
+  return {
+    sessionFile: typeof value.sessionFile === 'string' && value.sessionFile ? value.sessionFile : (fallbackFile ?? ''),
+    fromByte,
+    nextByte: typeof value.nextByte === 'number' ? value.nextByte : fromByte,
+    reset: value.reset === true,
+    messages: value.messages,
+    totalBytes: typeof value.totalBytes === 'number' ? value.totalBytes : undefined,
+  };
+}
+
+export async function requestSubagentPage(
+  sessionId: string,
+  subagentId: string,
+  sessionFile: string | undefined,
+  fromByte: number,
+): Promise<SubagentMessagesPage | null> {
+  try {
+    const res = await fetch(`/api/agent/${encodeURIComponent(sessionId)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        type: 'get_subagent_messages',
+        subagentId,
+        ...(sessionFile ? { sessionFile } : {}),
+        fromByte,
+      }),
+    });
+    if (!res.ok) return null;
+    const body: unknown = await res.json().catch(() => null);
+    const payload = isRecord(body) && 'data' in body ? body.data : body;
+    return asMessagesPage(payload, fromByte, sessionFile);
+  } catch {
+    return null;
+  }
+}
+
+/** In-flight GET dedupe: identical page requests share one promise. Strict
+ *  mode/hydration double-runs and re-renders must not double-hit the disk. */
+const inflightHistory = new Map<string, Promise<SubagentMessagesPage | null>>();
+
+/** On-disk history page (`{ page }`, or a bare page); null = end/unavailable. */
+export async function requestHistoryPage(
+  sessionId: string,
+  subagentId: string,
+  fromByte: number,
+): Promise<SubagentMessagesPage | null> {
+  const url = `/api/sessions/${encodeURIComponent(sessionId)}/subagents/${encodeURIComponent(subagentId)}?fromByte=${fromByte}`;
+  const inflight = inflightHistory.get(url);
+  if (inflight) return inflight;
+  let cleanup = () => {};
+  const promise = new Promise<SubagentMessagesPage | null>((resolve) => {
+    cleanup = () => {
+      // Only the owner removes itself; a shared waiter must not.
+      if (inflightHistory.get(url) === promise) inflightHistory.delete(url);
+    };
+    void (async () => {
+      try {
+        const res = await fetch(url);
+        if (!res.ok) return resolve(null);
+        const body: unknown = await res.json().catch(() => null);
+        const payload = isRecord(body) && 'page' in body ? body.page : body;
+        if (payload === null || payload === undefined) return resolve(null);
+        resolve(asMessagesPage(payload, fromByte, undefined));
+      } catch {
+        resolve(null);
+      }
+    })();
+  });
+  promise.then(cleanup, cleanup);
+  inflightHistory.set(url, promise);
+  return promise;
+}

package/src/shared/lib/settings/client.test.ts

@@ -0,0 +1,62 @@
+import { test, expect, beforeEach } from 'bun:test';
+import {
+  primeChamberSettings,
+  readChamberSetting,
+  mergeChamberSettings,
+  writeSetting,
+  writeChamberSettings,
+} from '@/shared/lib/settings/client';
+
+const bootstrap = {
+  omp_sidebar_sort: 'A-Z',
+  desktopLayoutSizes: { sidebar: 268 },
+  omp_chamber_settings: { theme: 'paper', streamTransport: 'websocket' },
+};
+
+beforeEach(() => {
+  primeChamberSettings(bootstrap);
+});
+
+test('reads expose top-level keys and blob keys flat', () => {
+  expect(readChamberSetting<string>('omp_sidebar_sort')).toBe('A-Z');
+  expect(readChamberSetting<string>('theme')).toBe('paper');
+  expect(readChamberSetting<string>('streamTransport')).toBe('websocket');
+  expect(readChamberSetting('absent')).toBeUndefined();
+});
+
+test('the raw blob key is not exposed as a flat key', () => {
+  expect(readChamberSetting('omp_chamber_settings')).toBeUndefined();
+});
+
+test('readChamberSetting accepts candidate key lists in priority order', () => {
+  expect(readChamberSetting<string>(['missing', 'theme'])).toBe('paper');
+  expect(readChamberSetting<string>(['theme', 'missing'])).toBe('paper');
+  expect(readChamberSetting(['missing', 'alsoMissing'])).toBeUndefined();
+});
+
+test('mergeChamberSettings layers only the blob, never top-level keys', () => {
+  const merged = mergeChamberSettings({ theme: 'fallback', fontSize: 14 });
+  expect(merged.theme).toBe('paper');
+  expect(merged.fontSize).toBe(14);
+  expect((merged as Record<string, unknown>).omp_sidebar_sort).toBeUndefined();
+  expect((merged as Record<string, unknown>).desktopLayoutSizes).toBeUndefined();
+});
+
+test('writeSetting updates the snapshot so the next read sees it', () => {
+  writeSetting('omp_sidebar_sort', 'Z-A');
+  expect(readChamberSetting<string>('omp_sidebar_sort')).toBe('Z-A');
+});
+
+test('writeChamberSettings updates flat keys and keeps sibling blob keys', () => {
+  writeChamberSettings({ theme: 'noir' });
+  expect(readChamberSetting<string>('theme')).toBe('noir');
+  expect(readChamberSetting<string>('streamTransport')).toBe('websocket');
+  expect(readChamberSetting('omp_chamber_settings')).toBeUndefined();
+});
+
+test('a later write does not clobber previously written flat keys', () => {
+  writeSetting('showRightPanel', false);
+  writeChamberSettings({ theme: 'noir' });
+  expect(readChamberSetting<boolean>('showRightPanel')).toBe(false);
+  expect(readChamberSetting<string>('theme')).toBe('noir');
+});

package/src/shared/lib/settings/client.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client-side chamber settings. SQLite is the single source of truth: the
+ * server reads `app_settings` and injects the whole map into the page as
+ * `window.__OMP_BOOTSTRAP__.appSettings`, and every write POSTs back to
+ * `/api/settings`.
+ *
+ * There is deliberately no localStorage. An in-memory snapshot — primed once
+ * from the bootstrap — keeps reads synchronous, so a theme flip or transport
+ * change applies to the next render without waiting for a loader round-trip,
+ * while the durable copy lives in SQLite and survives a reload.
+ *
+ * Reads are flat: top-level `app_settings` keys (`omp_sidebar_sort`,
+ * `desktopLayoutSizes`, …) and the `omp_chamber_settings` blob (`theme`,
+ * `streamTransport`, …) share one namespace, with the blob's keys overlaid.
+ */
+
+const CHAMBER_SETTINGS_KEY = 'omp_chamber_settings';
+
+let snapshot: Record<string, any> | null = null;
+let chamberBlob: Record<string, any> = {};
+
+/**
+ * Prime the snapshot from the server-injected bootstrap. Call once at boot
+ * (see `main.tsx`); calling again re-primes from the same payload.
+ */
+export function primeChamberSettings(appSettings?: Record<string, any>): void {
+  chamberBlob = { ...(appSettings?.[CHAMBER_SETTINGS_KEY] ?? {}) };
+  const flat = { ...(appSettings ?? {}) };
+  delete flat[CHAMBER_SETTINGS_KEY];
+  snapshot = { ...flat, ...chamberBlob };
+}
+
+function current(appSettings?: Record<string, any>): Record<string, any> {
+  if (!snapshot) primeChamberSettings(appSettings);
+  return snapshot ?? {};
+}
+
+/**
+ * Resolve one setting (or the first present of several candidate keys) from the
+ * snapshot. Returns `undefined` when no candidate is present.
+ */
+export function readChamberSetting<T>(
+  keys: string | string[],
+  appSettings?: Record<string, any>,
+): T | undefined {
+  const keyList = Array.isArray(keys) ? keys : [keys];
+  const source = current(appSettings);
+  for (const key of keyList) {
+    if (source[key] !== undefined) return source[key] as T;
+  }
+  return undefined;
+}
+
+/**
+ * `defaults` layered under the `omp_chamber_settings` blob only. Used to seed
+ * the settings-editor state, so unrelated top-level keys must not leak in and
+ * get written back into the blob.
+ */
+export function mergeChamberSettings<T extends Record<string, any>>(
+  defaults: T,
+  appSettings?: Record<string, any>,
+): T {
+  current(appSettings);
+  return { ...defaults, ...chamberBlob };
+}
+
+/** Write one top-level `app_settings` key: snapshot first, then SQLite. */
+export function writeSetting(key: string, value: unknown): void {
+  snapshot = { ...current(), [key]: value };
+  sendSettings({ [key]: value });
+}
+
+/**
+ * Write a patch of chamber-blob keys (`theme`, `streamTransport`, …). The blob
+ * is kept whole so the durable copy stays one round-trippable object, while the
+ * snapshot exposes its keys flat.
+ */
+export function writeChamberSettings(patch: Record<string, any>): void {
+  chamberBlob = { ...chamberBlob, ...patch };
+  snapshot = { ...current(), ...patch };
+  sendSettings({ [CHAMBER_SETTINGS_KEY]: chamberBlob });
+}
+
+/** POST a settings patch to SQLite. Fire-and-forget; failures are non-fatal. */
+function sendSettings(patch: Record<string, unknown>): void {
+  fetch('/api/settings', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(patch),
+  }).catch(() => {});
+}