ompchamber 0.3.0

package/src/client/hooks/chat/omp/session-sidebar-controller.ts

@@ -0,0 +1,249 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared session-sidebar controller for the desktop and mobile sidebars.
+ *
+ * Owns the pieces both sidebars used to clone: the sort preference (seeded
+ * from the server, debounced persistence), search state, the filtered/sorted
+ * folder list, the `omp:workspace-updated` listener, the live session-status
+ * wiring (ack + stream poll + throttled revalidation), and session selection.
+ *
+ * The two sidebars differ in two places, both parameterised here rather than
+ * forked: the desktop injects a pending-session placeholder and force-expands
+ * search hits, while the mobile sidebar delegates selection to its layout and
+ * closes the drawer afterwards.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import { useSearchParams } from '@/client/lib/router/search-params';
+import { isValidSessionSortOption, sortFolders } from '@/shared/lib/workspace/sidebar-sort';
+import { pendingSessionCreatedAt, pendingSessionTitle } from '@/shared/lib/omp/session/default-title';
+import { buildSidebarSessionStatus, useSessionStatusAck } from '@/client/hooks/chat/omp/session-statuses';
+import { useStreamPoll } from '@/client/hooks/chat/omp/stream-poll';
+import { useSidebarRevalidation } from '@/client/hooks/chat/omp/revalidation-throttle';
+import { useSidebarData } from '@/client/hooks/chat/omp/session-list';
+import { useChamberEvent } from '@/client/hooks/ui/window-event';
+import { writeSetting } from '@/shared/lib/settings/client';
+import type { SessionItemData, SessionSortOption, WorkspaceFolderData } from '@/shared/types';
+
+/** Debounce before the sort preference is POSTed to /api/settings (ms). */
+const SORT_PERSIST_DEBOUNCE_MS = 200;
+
+export interface SessionSidebarControllerOptions {
+  /**
+   * Desktop only: inject a pending `new-…` session placeholder and force-expand
+   * search matches. Mobile filters without expanding.
+   */
+  includePendingSessions?: boolean;
+  /**
+   * Mobile only: hand selection to the layout (which owns the URL + screen),
+   * instead of performing the URL swap here.
+   */
+  onSelectSession?: (id: number | string) => void;
+  /** Called after selection — mobile closes the drawer here. */
+  onAfterSelect?: () => void;
+}
+
+export interface SessionSidebarController {
+  folders: WorkspaceFolderData[];
+  initializing: boolean;
+  refresh: () => void;
+  activeSessionId: number | string | null;
+  sessionParam: string | null;
+  searchQuery: string;
+  setSearchQuery: (value: string) => void;
+  showArchived: boolean;
+  setShowArchived: (value: boolean) => void;
+  optionsOpen: boolean;
+  setOptionsOpen: (value: boolean) => void;
+  sortOption: SessionSortOption;
+  handleSortChange: (opt: SessionSortOption) => void;
+  processedFolders: WorkspaceFolderData[];
+  sessionStatus: Record<string, 'stream' | 'finish' | 'abort' | 'error'>;
+  handleSelectSession: (id: number | string) => void;
+}
+
+export function useSessionSidebarController(
+  appSettings: Record<string, any> = {},
+  options: SessionSidebarControllerOptions = {},
+): SessionSidebarController {
+  const { includePendingSessions = false, onSelectSession, onAfterSelect } = options;
+  const { folders, initializing, refresh, markSeen, hasSeen } = useSidebarData();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const sessionParam = searchParams.get('sessionId');
+  const activeSessionId = sessionParam
+    ? (Number.isNaN(Number(sessionParam)) ? sessionParam : Number(sessionParam))
+    : null;
+
+  // A stable refresh reference keeps the revalidation/ack/poll hooks subscribed
+  // once while always calling the latest refresh.
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+  const revalidate = useCallback(() => refreshRef.current(), []);
+
+  // Refresh the session list when a new omp session is spawned or its title
+  // changes. No SSE — a plain event + throttled refetch keeps it cheap, and the
+  // trailing throttle coalesces per-frame dispatches during a run into one list
+  // fetch per second.
+  useSidebarRevalidation(revalidate);
+
+  useChamberEvent('omp:workspace-updated', () => refreshRef.current());
+
+  const [searchQuery, setSearchQuery] = useState('');
+  const [showArchived, setShowArchived] = useState(false);
+  const [optionsOpen, setOptionsOpen] = useState(false);
+  // Seeded from the server (app_settings.omp_sidebar_sort) so the SSR HTML and
+  // the first client render agree.
+  const [sortOption, setSortOption] = useState<SessionSortOption>(() =>
+    isValidSessionSortOption(appSettings.omp_sidebar_sort) ? appSettings.omp_sidebar_sort : 'A-Z',
+  );
+
+  const sortPersistTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const persistSort = useCallback((opt: SessionSortOption) => {
+    if (sortPersistTimerRef.current) clearTimeout(sortPersistTimerRef.current);
+    sortPersistTimerRef.current = setTimeout(() => {
+      writeSetting('omp_sidebar_sort', opt);
+    }, SORT_PERSIST_DEBOUNCE_MS);
+  }, []);
+
+  useEffect(() => () => {
+    if (sortPersistTimerRef.current) clearTimeout(sortPersistTimerRef.current);
+  }, []);
+
+  const handleSortChange = (opt: SessionSortOption) => {
+    setSortOption(opt);
+    setOptionsOpen(false);
+    persistSort(opt);
+  };
+
+  // Live session status — server-tracked via SQLite, riding the same loader
+  // data as the session list. Spinner while `stream`; a one-shot terminal
+  // badge (acknowledged server-side on open, dropped by the next revalidate).
+  const sessionStatus = useMemo(() => buildSidebarSessionStatus(folders), [folders]);
+  // hasSeen: clicks already acked + optimistically stripped these badges, so
+  // the effect must not re-POST while the authoritative list is still stale.
+  useSessionStatusAck(sessionStatus, activeSessionId, revalidate, hasSeen);
+  // Background sessions finishing while the user sits elsewhere: refetch on a
+  // cadence — but only while something is actually streaming.
+  useStreamPoll(sessionStatus, revalidate);
+
+  const handleSelectSession = (id: number | string) => {
+    // One-shot terminal badge (check) clears on open: optimistic strip + server
+    // ack. Keep BEFORE the URL swap so the click feels instant.
+    markSeen(id);
+    if (onSelectSession) {
+      onSelectSession(id);
+    } else {
+      setSearchParams(prev => {
+        prev.set('sessionId', id.toString());
+        // Navigating away from a session must also exit its transcript view.
+        if (prev.has('subagent')) prev.delete('subagent');
+        return prev;
+      }, { replace: true });
+    }
+    onAfterSelect?.();
+  };
+
+  // Filter and sort folders
+  const processedFolders = useMemo(() => {
+    let result = [...folders];
+
+    if (includePendingSessions) {
+      // The active session may not be in the sidebar list yet: a pending
+      // "new-…" session, or a freshly spawned omp session whose JSONL has not
+      // been scanned (the chat timeline signals omp:session-updated once it is).
+      // Render it with the timestamped default title so there is never a gap
+      // between sending a chat and the session appearing with its real title.
+      const sessionExists = result.some(f => f.sessions?.some((s) => String(s.id) === String(sessionParam)));
+      const pendingId = sessionParam && !sessionExists ? sessionParam : null;
+      if (pendingId) {
+        const folderIdParam = searchParams.get('folderId');
+        const target = folderIdParam
+          ? result.find(f => String(f.id) === String(folderIdParam))
+          : result[0];
+        // The placeholder only bridges the gap before the JSONL scan surfaces
+        // the real row; rendering it alongside a row the folder already lists
+        // is what made the item blink.
+        const alreadyListed = Boolean(
+          target?.sessions?.some((s) => String(s.id) === String(pendingId)),
+        );
+        if (target && !alreadyListed) {
+          // A pending id carries its creation epoch, so the stamp is stable
+          // across recomputes instead of reshuffling LATEST_SESSION on every
+          // revalidate. An adopted real id has no epoch; the row is newest by
+          // definition then.
+          const epochMs = pendingSessionCreatedAt(pendingId);
+          const stamp = Number.isFinite(epochMs)
+            ? new Date(epochMs).toISOString()
+            : new Date().toISOString();
+          result = result.map(f => {
+            if (f.id !== target.id) return f;
+            const pending: SessionItemData = {
+              id: pendingId,
+              folder_id: f.id,
+              title: pendingSessionTitle(pendingId),
+              // Read by @/shared/lib/workspace/sidebar-sort to rank this folder newest.
+              created_at: stamp,
+              updated_at: stamp,
+            };
+            return { ...f, isExpanded: true, sessions: [pending, ...(f.sessions || [])] };
+          });
+        }
+      }
+    }
+
+    // Search filter
+    if (searchQuery.trim()) {
+      const q = searchQuery.toLowerCase();
+      if (includePendingSessions) {
+        result = result.filter(folder => {
+          const matchFolder = folder.name.toLowerCase().includes(q);
+          const matchSession = folder.sessions?.some((s) => s.title.toLowerCase().includes(q));
+          return matchFolder || matchSession;
+        }).map(folder => {
+          // If we are searching, we also filter the sessions within the folder
+          const filteredSessions = folder.sessions?.filter((s) =>
+            folder.name.toLowerCase().includes(q) || s.title.toLowerCase().includes(q)
+          );
+          return { ...folder, sessions: filteredSessions, isExpanded: true };
+        });
+      } else {
+        result = result.map(folder => {
+          const matchesFolderName = folder.name.toLowerCase().includes(q);
+          const filteredSessions = (folder.sessions || []).filter(s =>
+            s.title.toLowerCase().includes(q)
+          );
+          if (matchesFolderName) return folder;
+          return { ...folder, sessions: filteredSessions };
+        }).filter(f => f.sessions && f.sessions.length > 0);
+      }
+    }
+
+    // Ordering is shared with the other sidebar so the two cannot drift.
+    result = sortFolders(result, sortOption);
+
+    return result;
+  }, [folders, searchQuery, sortOption, sessionParam, searchParams, includePendingSessions]);
+
+  return {
+    folders,
+    initializing,
+    refresh: revalidate,
+    activeSessionId,
+    sessionParam,
+    searchQuery,
+    setSearchQuery,
+    showArchived,
+    setShowArchived,
+    optionsOpen,
+    setOptionsOpen,
+    sortOption,
+    handleSortChange,
+    processedFolders,
+    sessionStatus,
+    handleSelectSession,
+  };
+}

package/src/client/hooks/chat/omp/session-statuses.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sidebar session stream status — server-authoritative via SQLite.
+ *
+ * The status rides the loader's session items (`streamStatus` field); the
+ * sidebar already revalidates on stream events (`omp:session-updated`
+ * dispatch → revalidator), so spinner and check update with the list they
+ * belong to. Opening a session acknowledges the one-shot terminal badge
+ * (`finish` / `abort` / `error`) via POST /api/sessions/:id/stream-seen so
+ * the check shows exactly once, then disappears from the rendered list.
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+import type { SessionItemData } from '@/shared/types';
+
+export type SessionStreamStatus = NonNullable<SessionItemData['streamStatus']>;
+
+/** Derive { sessionId → status } from the loader-provided folders. */
+export function buildSidebarSessionStatus(
+  folders: { sessions?: SessionItemData[] }[],
+): Record<string, SessionStreamStatus> {
+  const map: Record<string, SessionStreamStatus> = {};
+  for (const folder of folders) {
+    for (const session of folder.sessions ?? []) {
+      if (session.streamStatus) map[String(session.id)] = session.streamStatus;
+    }
+  }
+  return map;
+}
+
+/**
+ * Opening a session with a terminal badge acknowledges it on the server
+ * (one POST per session+status) so the check shows EXACTLY ONCE: the badge
+ * keeps rendering on this pass — stripping it here would suppress the paint
+ * entirely for an open session. Once the POST lands, a revalidate pulls
+ * loader data without the deleted row, dropping the check from the list.
+ *
+ * Click paths call `markSeen` (optimistic strip + ack) BEFORE the status map
+ * can even carry the badge; `skip` lets the caller suppress this effect for
+ * sessions the click already handled, so the two never double-POST.
+ */
+export function useSessionStatusAck(
+  statusMap: Record<string, SessionStreamStatus>,
+  activeSessionId: number | string | null,
+  revalidate: () => void,
+  skip?: (sessionId: number | string) => boolean,
+): void {
+  const activeId = activeSessionId === null ? null : String(activeSessionId);
+  const activeStatus = activeId !== null ? statusMap[activeId] : undefined;
+  // One POST per (session, status): between the ack and the revalidate that
+  // drops the row, identity changes in statusMap would re-fire the effect.
+  const ackedRef = useRef<string | null>(null);
+  const revalidateRef = useRef(revalidate);
+  revalidateRef.current = revalidate;
+  const skipRef = useRef(skip);
+  skipRef.current = skip;
+
+  useEffect(() => {
+    if (!activeStatus || activeStatus === 'stream') return;
+    if (skipRef.current?.(activeId as string)) return;
+    const ackKey = `${activeId}:${activeStatus}`;
+    if (ackedRef.current === ackKey) return;
+    ackedRef.current = ackKey;
+    // Stale-map guard: statusMap can lag a busy list by up to one fetch. If
+    // the badge was actually overwritten by a fresh `stream` (agent_start
+    // raced the sidebar refetch), the server now refuses to delete the row
+    // and reports deleted:false — treat the POST as void so the effect can
+    // re-ack the real terminal badge when the run later ends.
+    fetch(`/api/sessions/${encodeURIComponent(activeId as string)}/stream-seen`, { method: 'POST' })
+      .then((res) => res.json() as Promise<{ deleted?: boolean }>)
+      .then((body) => {
+        if (body.deleted === false) ackedRef.current = null;
+        revalidateRef.current();
+      })
+      .catch(() => {
+        ackedRef.current = null;
+      });
+  }, [activeId, activeStatus]);
+}

package/src/client/hooks/chat/omp/status.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Subscribe to the live agent-stream status for UI that lives outside the chat
+ * subtree — the top navbar's transport indicator. Published by
+ * `useOmpAgentStream`, which owns the socket lifecycle.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+import { AGENT_STREAM_STATUS_EVENT, readAgentStreamStatus, type AgentStreamStatus } from '@/shared/lib/chat/omp/status';
+
+export function useAgentStreamStatus(): AgentStreamStatus {
+  const [status, setStatus] = useState<AgentStreamStatus>(readAgentStreamStatus);
+
+  useEffect(() => {
+    const onStatus = (event: Event) => {
+      const detail = (event as CustomEvent<AgentStreamStatus>).detail;
+      if (!detail) return;
+      setStatus({ transport: detail.transport, connected: detail.connected });
+    };
+    window.addEventListener(AGENT_STREAM_STATUS_EVENT, onStatus);
+    // Re-sync in case a transition landed between render and subscribe.
+    setStatus(readAgentStreamStatus());
+    return () => window.removeEventListener(AGENT_STREAM_STATUS_EVENT, onStatus);
+  }, []);
+
+  return status;
+}

package/src/client/hooks/chat/omp/stream-poll.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sidebar poll in the shape of the context panel's `usePanelRefresh`: one
+ * stable interval for the hook's lifetime; each tick checks the LIVE stream
+ * status through a ref and revalidates only when some session is mid-stream.
+ *
+ * This is the belt to the `omp:session-updated` suspenders: it closes the
+ * case where a background session finishes while the user sits on another
+ * one (no event dispatch fires on this client). The status snapshot flows
+ * through the loader, so the tick only ever observes the latest revalidated
+ * state — a stale snapshot can never keep the timer armed.
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+import { SIDEBAR_STREAM_POLL_MS } from '@/shared/lib/workspace/refresh-cadence';
+import type { SessionStreamStatus } from '@/client/hooks/chat/omp/session-statuses';
+
+export function useStreamPoll(
+  sessionStatus: Record<string, SessionStreamStatus>,
+  revalidate: () => void,
+): void {
+  const hasStreamingRef = useRef(Object.values(sessionStatus).includes('stream'));
+  hasStreamingRef.current = Object.values(sessionStatus).includes('stream');
+  const revalidateRef = useRef(revalidate);
+  revalidateRef.current = revalidate;
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      if (hasStreamingRef.current) revalidateRef.current();
+    }, SIDEBAR_STREAM_POLL_MS);
+    return () => clearInterval(id);
+  }, []);
+}

package/src/client/hooks/chat/omp/stream.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Live agent stream wiring for the omp bridge. Owns the transport lifecycle —
+ * the WebSocket socket by default, Server-Sent Events when the Chat setting
+ * asks for it — and hands every decoded frame to the shared folder in
+ * `@/lib/chat/omp/agent-events`, so both transports produce identical timeline
+ * behavior. Kept out of useOmpAgent so that hook only owns RPC command sends +
+ * agent state.
+ */
+
+import { useCallback, useEffect, useRef } from 'preact/hooks';
+import type { Dispatch, RefObject, SetStateAction } from 'preact/compat';
+import type { ChatMessageData, OmpAgentCallbacks, OmpAgentEvent, OmpAgentState, StreamTransport } from '@/shared/types';
+import { foldAgentEvent, type ToolResultRecord } from '@/shared/lib/chat/omp/agent-events';
+import { connectAgentSocket } from '@/shared/lib/chat/omp/socket';
+import { connectAgentEvents } from '@/shared/lib/chat/omp/sse';
+import type { AgentStreamConnection, AgentStreamHandlers } from '@/shared/lib/chat/omp/transport';
+import { publishAgentStreamStatus } from '@/shared/lib/chat/omp/status';
+
+export interface OmpStreamRefs {
+  toolResultsRef: RefObject<Map<string, ToolResultRecord>>;
+  lastToolMessageRef: RefObject<ChatMessageData>;
+  interruptPendingRef: RefObject<boolean>;
+  /** Last activity phrase published to the indicator (repeat suppression). */
+  activityRef: RefObject<string>;
+  /** Live thinking level (last `thinking_level_changed` frame). */
+  currentThinkingLevelRef: RefObject<string | undefined>;
+  /** toolCallIds of in-flight file-mutating calls (see file-mutations.ts). */
+  fileMutatingCallsRef: RefObject<Set<string>>;
+}
+
+interface UseOmpAgentStreamOptions extends OmpStreamRefs {
+  setState: Dispatch<SetStateAction<OmpAgentState>>;
+  callbacksRef: RefObject<OmpAgentCallbacks>;
+  transport: StreamTransport;
+}
+
+const CONNECTORS = {
+  websocket: connectAgentSocket,
+  sse: connectAgentEvents,
+} as const;
+
+export function useOmpAgentStream({
+  setState,
+  callbacksRef,
+  toolResultsRef,
+  lastToolMessageRef,
+  interruptPendingRef,
+  activityRef,
+  currentThinkingLevelRef,
+  fileMutatingCallsRef,
+  transport,
+}: UseOmpAgentStreamOptions) {
+  const connectionRef = useRef<AgentStreamConnection | null>(null);
+
+  // The navbar indicator needs the transport in force even before the first
+  // dial, and a transport switch invalidates any live socket — so announce it
+  // on mount/change and retract on unmount.
+  useEffect(() => {
+    publishAgentStreamStatus({ transport, connected: false });
+    return () => publishAgentStreamStatus({ transport, connected: false });
+  }, [transport]);
+
+  const disconnect = useCallback(() => {
+    const connection = connectionRef.current;
+    connectionRef.current = null;
+    connection?.close();
+    setState((prev) => ({ ...prev, connected: false }));
+    publishAgentStreamStatus({ transport, connected: false });
+  }, [setState, transport]);
+
+  const connect = useCallback((sid: string) => {
+    disconnect();
+    const handlers: AgentStreamHandlers = {
+      onOpen: () => {
+        setState((prev) => ({ ...prev, connected: true }));
+        publishAgentStreamStatus({ transport, connected: true });
+        callbacksRef.current?.onConnected?.();
+      },
+      onFrame: (data: OmpAgentEvent) => {
+        foldAgentEvent(data, {
+          sessionId: sid,
+          setState,
+          callbacksRef,
+          toolResultsRef,
+          lastToolMessageRef,
+          interruptPendingRef,
+          activityRef,
+          currentThinkingLevelRef,
+          fileMutatingCallsRef,
+        });
+      },
+      onClose: () => {
+        setState((prev) => ({ ...prev, connected: false }));
+        publishAgentStreamStatus({ transport, connected: false });
+      },
+    };
+    connectionRef.current = CONNECTORS[transport](sid, handlers);
+  }, [disconnect, setState, callbacksRef, toolResultsRef, lastToolMessageRef, interruptPendingRef, activityRef, currentThinkingLevelRef, fileMutatingCallsRef, transport]);
+
+  return { connect, disconnect };
+}
+
+export type { ToolResultRecord };