ompchamber 0.8.0 → 1.0.0

package/src/server/routes/terminal/ws.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Terminal WebSocket: the only transport between a terminal panel and its PTY.
+ *
+ * Text frames are JSON control, binary frames are raw PTY bytes in both
+ * directions. The client's first frame is `attach`, which also creates the
+ * shell when the id is new — one round trip, and no separate create endpoint to
+ * race against.
+ *
+ * The upgrade is origin-checked. Browsers happily open a WebSocket to
+ * `localhost` from any page, and there is no preflight to stop them, so a
+ * cross-origin page could otherwise drive a shell on this machine.
+ *
+ * Per-connection state lives on `ws.data`, not in a `WeakMap` keyed by the `ws`
+ * object: Elysia hands a *different* wrapper to `message`/`close` than the one
+ * `open` received (verified on 1.4.30), so a WeakMap lookup finds nothing and
+ * every frame is silently dropped. `ws.data` is the same object throughout.
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  attachTerminal,
+  closeTerminal,
+  detachTerminal,
+  resizeTerminalDebounced,
+  writeTerminalInput,
+} from '@/server/lib/terminal/runtime.server';
+import { TerminalRuntimeError, type TerminalViewer } from '@/server/lib/terminal/session.server';
+import {
+  decodeClientFrame,
+  encodeServerFrame,
+  isValidTerminalId,
+} from '@/shared/lib/workspace/terminal/protocol';
+
+interface Attachment {
+  id: string;
+  viewer: TerminalViewer;
+  /** One attach per socket; a duplicate would replay the scrollback twice. */
+  attached: boolean;
+}
+
+/** Elysia's ws context, narrowed to the per-connection store this route adds. */
+type TerminalWsData = { params: { terminalId: string }; terminal?: Attachment };
+
+export const terminalWsRoutes = new Elysia({ prefix: '/api/terminal' }).ws('/:terminalId/ws', {
+  params: t.Object({ terminalId: t.String() }),
+
+  beforeHandle({ request, status }) {
+    if (!isSameOriginUpgrade(request)) return status(403, 'Cross-origin terminal upgrade rejected');
+  },
+
+  open(ws) {
+    const data = ws.data as unknown as TerminalWsData;
+    const id = data.params.terminalId;
+    if (!isValidTerminalId(id)) {
+      ws.close();
+      return;
+    }
+    data.terminal = {
+      id,
+      attached: false,
+      viewer: {
+        send(frame) {
+          try {
+            ws.send(frame);
+          } catch {
+            // Socket closed mid-send; the close handler detaches.
+          }
+        },
+      },
+    };
+  },
+
+  async message(ws, raw) {
+    const attachment = (ws.data as unknown as TerminalWsData).terminal;
+    if (!attachment) return;
+
+    // Raw PTY input (keystrokes, paste, mouse reports) — never JSON-escaped.
+    if (raw instanceof Uint8Array) {
+      writeTerminalInput(attachment.id, raw);
+      return;
+    }
+
+    const frame = decodeClientFrame(raw);
+    if (!frame) return;
+
+    if (frame.t === 'resize') {
+      resizeTerminalDebounced(attachment.id, frame.cols, frame.rows);
+      return;
+    }
+
+    if (frame.t === 'close') {
+      closeTerminal(attachment.id);
+      return;
+    }
+
+    if (attachment.attached) return;
+
+    try {
+      const { snapshot, replay } = await attachTerminal(attachment.viewer, {
+        id: attachment.id,
+        cols: frame.cols,
+        rows: frame.rows,
+        root: frame.root,
+        repo: frame.repo,
+        theme: frame.theme,
+      });
+      attachment.attached = true;
+      ws.send(encodeServerFrame({ t: 'ready', ...snapshot, replayBytes: replay.length }));
+      // Ordering is safe without sequence numbers: attach captured the history
+      // and registered this viewer in one synchronous block, so nothing can be
+      // delivered between this frame and the replay that follows it.
+      if (replay.length > 0) ws.send(replay);
+    } catch (error) {
+      const code = error instanceof TerminalRuntimeError ? error.code : 'unknown';
+      const message = error instanceof Error ? error.message : String(error);
+      ws.send(encodeServerFrame({ t: 'error', code, message }));
+    }
+  },
+
+  close(ws) {
+    const data = ws.data as unknown as TerminalWsData;
+    const attachment = data.terminal;
+    if (!attachment) return;
+    data.terminal = undefined;
+    detachTerminal(attachment.viewer, attachment.id);
+  },
+});
+
+/**
+ * A WebSocket upgrade carries the page's `Origin`, and no preflight protects
+ * it. Requests without one (curl, tests) are allowed: they are not a browser
+ * being tricked into dialing localhost.
+ */
+function isSameOriginUpgrade(request: Request): boolean {
+  const origin = request.headers.get('origin');
+  if (!origin) return true;
+  const host = request.headers.get('host');
+  if (!host) return false;
+  try {
+    return new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}

package/src/shared/lib/chat/omp/agent-events.test.ts

@@ -25,10 +25,14 @@ const ABORTED_TURN = {
 function makeDeps() {
   const ended: ChatMessageData[] = [];
   const activity: string[] = [];
+  const commandOutputs: string[] = [];
+  let settledCount = 0;
   let state: OmpAgentState = { isGenerating: false, connected: true, error: null };
   const callbacks: OmpAgentCallbacks = {
     onMessageEnd: (msg) => ended.push(msg),
     onActivity: (verb) => activity.push(verb),
+    onPromptSettled: () => { settledCount += 1; },
+    onCommandOutput: (text) => commandOutputs.push(text),
   };
   const deps: OmpAgentFoldDeps = {
     sessionId: 's1',
@@ -43,7 +47,7 @@ function makeDeps() {
     currentThinkingLevelRef: { current: undefined },
     fileMutatingCallsRef: { current: new Set<string>() },
   };
-  return { deps, ended, activity };
+  return { deps, ended, activity, commandOutputs, settled: () => settledCount, state: () => state };
 }
 
 describe('toChatMessage error derivation', () => {
@@ -60,6 +64,38 @@ describe('toChatMessage error derivation', () => {
   });
 });
 
+describe('foldAgentEvent prompt_result (builtin slash commands)', () => {
+  test('agentInvoked:false settles generating state and fires onPromptSettled', () => {
+    const { deps, state, settled } = makeDeps();
+    foldAgentEvent({ type: 'agent_start' }, deps);
+    expect(state().isGenerating).toBe(true);
+    foldAgentEvent({ type: 'prompt_result', agentInvoked: false }, deps);
+    expect(state().isGenerating).toBe(false);
+    expect(settled()).toBe(1);
+  });
+
+  test('prompt_result with agentInvoked:true does not settle (a run follows)', () => {
+    const { deps, settled } = makeDeps();
+    foldAgentEvent({ type: 'prompt_result', agentInvoked: true }, deps);
+    expect(settled()).toBe(0);
+  });
+});
+
+describe('foldAgentEvent command_output (builtin slash output)', () => {
+  test('forwards trimmed text to onCommandOutput', () => {
+    const { deps, commandOutputs } = makeDeps();
+    foldAgentEvent({ type: 'command_output', text: 'Usage\nInput tokens: 0\n' }, deps);
+    expect(commandOutputs).toEqual(['Usage\nInput tokens: 0']);
+  });
+
+  test('drops empty output frames', () => {
+    const { deps, commandOutputs } = makeDeps();
+    foldAgentEvent({ type: 'command_output', text: '   ' }, deps);
+    foldAgentEvent({ type: 'command_output' }, deps);
+    expect(commandOutputs).toEqual([]);
+  });
+});
+
 describe('foldAgentEvent activity phrases', () => {
   test('names the tool being executed, not a generic reasoning verb', () => {
     const { deps, activity } = makeDeps();

package/src/shared/lib/chat/omp/agent-events.ts

@@ -165,6 +165,11 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       callbacks?.onAgentStart?.();
       break;
 
+    case 'turn_start':
+      setActivity(PHASE_VERBS.thinking, deps);
+      callbacks?.onTurnStart?.();
+      break;
+
     case 'message_start':
     case 'message_update': {
       const msg = data.message as Record<string, unknown> | undefined;
@@ -177,6 +182,10 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       // Assistant phases (thinking / prose / tool-call assembly) name the
       // action directly — a tool that never starts still shows its phrase.
       setActivity(describeAssistantPhase(data.assistantMessageEvent), deps);
+      // The first message frame of a turn is another proof the run is live —
+      // re-signal so the sidebar can restore a lost `stream` status row.
+      // message_update frames arrive per delta and must stay silent here.
+      if (data.type === 'message_start') callbacks?.onTurnStart?.();
       // Steering (abort_and_prompt) and follow-up deliveries create no
       // optimistic bubble — the user turn only exists on the stream. Convert
       // it here so the bubble renders live instead of after a JSONL reload.
@@ -298,6 +307,27 @@ export function foldAgentEvent(data: OmpAgentEvent, deps: OmpAgentFoldDeps): voi
       break;
     }
 
+    // omp's prompt ack ran a built-in slash command instead of an agent turn
+    // (`agentInvoked:false`, mirrored server-side as this frame): there will be
+    // no agent_start/agent_end pair. Clear the optimistic generating state —
+    // the callbacks drop the AI placeholder and keep the user's message row.
+    case 'prompt_result': {
+      if (data.agentInvoked === false) {
+        deps.setState((prev) => ({ ...prev, isGenerating: false }));
+        deps.activityRef.current = '';
+        callbacks?.onPromptSettled?.();
+      }
+      break;
+    }
+
+    // Built-in slash command output (/usage, /compact result, …). Rendered as
+    // a notice row — see the callback type note: this frame is the ONLY copy.
+    case 'command_output': {
+      const text = typeof data.text === 'string' ? data.text.trim() : '';
+      if (text) callbacks?.onCommandOutput?.(text);
+      break;
+    }
+
     case 'notice': {
       callbacks?.onNotice?.(
         typeof data.level === 'string' ? data.level : 'info',

package/src/shared/lib/chat/timeline/omp-callbacks.test.ts

@@ -63,7 +63,6 @@ describe('createOmpAgentCallbacks first-assistant sidebar signal', () => {
 
   function makeCallbacks(): OmpAgentCallbacks {
     const deps: OmpAgentCallbacksDeps = {
-      removeDeliveredFromQueue: () => {},
       setGenerating: () => {},
       setGeneratingVerb: () => {},
       scrollToBottom: () => {},
@@ -133,6 +132,15 @@ describe('createOmpAgentCallbacks first-assistant sidebar signal', () => {
     expect(signals).toHaveLength(2);
   });
 
+  test('onTurnStart signals the sidebar on every turn of the run', () => {
+    const callbacks = makeCallbacks();
+
+    callbacks.onTurnStart?.();
+    callbacks.onTurnStart?.();
+    expect(signals).toHaveLength(2);
+    expect(signals.every(s => s.name === 'omp:session-updated' && s.sessionId === 'sess-1')).toBe(true);
+  });
+
   test('never signals from user turns or notice rows alone', () => {
     const callbacks = makeCallbacks();
 

package/src/shared/lib/chat/timeline/omp-callbacks.ts

@@ -47,7 +47,6 @@ export function cancelStreamingCoalescer(): void {
 }
 
 export interface OmpAgentCallbacksDeps {
-  removeDeliveredFromQueue: (text: string) => void;
   setGenerating: (v: boolean) => void;
   setGeneratingVerb: (v: string) => void;
   scrollToBottom: (behavior?: ScrollBehavior) => void;
@@ -73,7 +72,6 @@ export interface OmpAgentCallbacksDeps {
 
 export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCallbacks {
   const {
-    removeDeliveredFromQueue,
     setGenerating,
     setGeneratingVerb,
     scrollToBottom,
@@ -97,12 +95,6 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
   scrollAfterFlush = () => scrollToBottom('smooth');
 
   return {
-    // A queued steer/follow-up text was picked up by the agent (user turn
-    // arrived) — drop it from whichever queue mirrors it so the panel stays
-    // truthful without a chat bubble for every delivery.
-    onQueuedMessageDelivered: (text) => {
-      removeDeliveredFromQueue(text);
-    },
     onAgentStart: () => {
       setGenerating(true);
       setGeneratingVerb(PHASE_VERBS.thinking);
@@ -122,6 +114,15 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
         }
       }
     },
+    onTurnStart: () => {
+      // Every turn inside the run re-signals the sidebar: the throttle makes
+      // this cheap, and it recovers the `stream` status row if a previous
+      // dispatch raced with the status write (or the row was healed away).
+      const sid = adoptedSessionIdRef.current ?? sessionIdRef.current;
+      if (sid && typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: sid } }));
+      }
+    },
     // Reload recovery: the omp process kept running server-side, so the event
     // stream is reattached and the generating UI must resume (the timeline
     // fetch already loaded the committed messages; live updates continue).
@@ -308,6 +309,42 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       abortControllerRef.current = null;
       console.error('OMP prompt error:', errorMessage);
     },
+    // The prompt ran a built-in slash command (omp answered on the command
+    // path, no agent run): drop the optimistic AI placeholder and settle the
+    // optimistic user row — it stays as the record of what the user invoked.
+    onPromptSettled: () => {
+      disposeStreamingCoalescer();
+      setGenerating(false);
+      abortControllerRef.current = null;
+      optimisticUserIdRef.current = null;
+      const placeholderId = aiPlaceholderIdRef.current;
+      aiPlaceholderIdRef.current = null;
+      if (placeholderId) {
+        setLocalMessages(prev => {
+          if (!prev.some(m => m.id === placeholderId)) return prev;
+          return prev.filter(m => m.id !== placeholderId);
+        });
+      }
+    },
+    // Built-in slash command output only rides the live stream — append it as
+    // a notice row before any active placeholder, exactly like omp notices.
+    onCommandOutput: (text) => {
+      const row: ChatMessageData = {
+        id: `cmdout-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        role: 'ai',
+        content: '',
+        notice: text,
+      };
+      setLocalMessages(prev => {
+        const placeholderId = aiPlaceholderIdRef.current;
+        if (placeholderId) {
+          const pIdx = prev.findIndex(m => m.id === placeholderId);
+          if (pIdx !== -1) return [...prev.slice(0, pIdx), row, ...prev.slice(pIdx)];
+        }
+        if (prev.some(m => m.notice === text)) return prev;
+        return [...prev, row];
+      });
+    },
     onNotice: (_level, message) => {
       console.info('OMP notice:', message);
     },

package/src/shared/lib/omp/session/stream-state.server.ts

@@ -11,7 +11,6 @@
  *   stream  — a run is in flight (prompt dispatch → agent_start)
  *   finish  — the run ended normally (agent_end), not yet seen
  *   abort   — the user stopped it, not yet seen
- *   error   — the run failed (prompt_error / process exit), not yet seen
  *
  * A terminal status is a one-shot badge: opening the session acknowledges it
  * (`markStreamSeen` deletes the row), which is exactly the "check appears
@@ -25,7 +24,7 @@
 
 import { getDb } from '@/server/db.server';
 
-export type SessionStreamStatus = 'stream' | 'finish' | 'abort' | 'error';
+export type SessionStreamStatus = 'stream' | 'finish' | 'abort';
 
 export async function markStreamStatus(sessionId: string, status: SessionStreamStatus): Promise<void> {
   try {
@@ -87,7 +86,7 @@ export async function loadStreamStatuses(): Promise<Record<string, SessionStream
     }[];
     const map: Record<string, SessionStreamStatus> = {};
     for (const row of rows) {
-      if (row.status === 'stream' || row.status === 'finish' || row.status === 'abort' || row.status === 'error') {
+      if (row.status === 'stream' || row.status === 'finish' || row.status === 'abort') {
         map[row.session_id] = row.status;
       }
     }

package/src/shared/lib/workspace/session-state/store.ts

@@ -28,10 +28,7 @@
  * - userBrowser.viewportMode  string
  * - userBrowser.zoomLevel     number
  * - terminal.activeRepo       string
- * - terminal.cwd              string
- * - terminal.commandHistory   string[]
- * - terminal.input            string
- * - terminal.output           string (trimmed tail)
+ * - terminal.id               string (server-side PTY id; reattached on reload)
  * - git.viewMode              'flat' | 'tree'
  * - git.commitDraft           string
  * - git.stagedExpanded        boolean

package/src/shared/lib/workspace/terminal/protocol.ts

@@ -0,0 +1,222 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Wire contract for the terminal socket — the only transport a terminal panel
+ * uses.
+ *
+ * Two frame kinds share one duplex socket:
+ *
+ * - **text** frames are JSON control (`attach`, `resize`, `close` upstream;
+ *   `ready`, `exit`, `error` downstream). Elysia hands inbound JSON to the
+ *   handler already parsed and inbound binary as a `Uint8Array`, so the split
+ *   is unambiguous on both ends.
+ * - **binary** frames are raw PTY bytes in both directions. Keystrokes are
+ *   never JSON-escaped, so `\x03`, `\x1b[A` and paste payloads reach the shell
+ *   byte-for-byte, and output is written straight into xterm without a decode
+ *   step in between.
+ *
+ * The first binary frame after `ready` is the retained scrollback (it may be
+ * empty); everything after it is live output.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** Grid bounds both ends clamp to, so a bogus size can never reach the PTY. */
+export const TERMINAL_MIN_COLS = 2;
+export const TERMINAL_MAX_COLS = 1000;
+export const TERMINAL_MIN_ROWS = 1;
+export const TERMINAL_MAX_ROWS = 500;
+
+/** Largest single input frame accepted from a client (keystrokes or paste). */
+export const TERMINAL_MAX_INPUT_BYTES = 64 * 1024;
+
+/** Ids key a server-side map and appear in a path segment. */
+const TERMINAL_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+export type TerminalStatus = 'running' | 'exited';
+
+export interface TerminalSnapshot {
+  id: string;
+  /** Working directory the shell was launched in. */
+  cwd: string;
+  shell: string;
+  cols: number;
+  rows: number;
+  status: TerminalStatus;
+  exitCode: number | null;
+  signal: string | null;
+  bunVersion: string;
+  nodeVersion: string;
+  /**
+   * True when a command holds the terminal's foreground. An idle shell sitting
+   * at its prompt is running but not busy, which is the distinction the cap and
+   * the status badge both use.
+   */
+  busy?: boolean;
+  /**
+   * Size the retained scrollback was drawn for. The client replays at this
+   * size and only then fits its own viewport: re-wrapping history drawn for
+   * another width leaves fragments the shell's own redraw never clears.
+   */
+  replayCols: number;
+  replayRows: number;
+}
+
+export interface TerminalAttachFrame {
+  t: 'attach';
+  cols: number;
+  rows: number;
+  root?: string;
+  repo?: string;
+  theme?: 'light' | 'dark';
+}
+
+export interface TerminalResizeFrame {
+  t: 'resize';
+  cols: number;
+  rows: number;
+}
+
+export interface TerminalCloseFrame {
+  t: 'close';
+}
+
+export type TerminalClientFrame = TerminalAttachFrame | TerminalResizeFrame | TerminalCloseFrame;
+
+export interface TerminalReadyFrame extends TerminalSnapshot {
+  t: 'ready';
+  /**
+   * Length of the replay frame that follows. Zero means the scrollback is
+   * empty; either way the client counts these bytes before it treats anything
+   * as live output, so it can replay at `replayCols`/`replayRows` first.
+   */
+  replayBytes: number;
+}
+
+export interface TerminalExitFrame {
+  t: 'exit';
+  exitCode: number | null;
+  signal: string | null;
+}
+
+export type TerminalErrorCode = 'capacity' | 'cwd' | 'shell' | 'spawn' | 'unknown';
+
+export interface TerminalErrorFrame {
+  t: 'error';
+  code: TerminalErrorCode;
+  message: string;
+}
+
+export type TerminalServerFrame = TerminalReadyFrame | TerminalExitFrame | TerminalErrorFrame;
+
+/**
+ * Terminal ids are client-generated. `randomUUID` needs a secure context, and
+ * the chamber is reachable over plain http on a LAN address (`--lan`), so the
+ * fallback is what keeps that deployment working.
+ */
+export function newTerminalId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  return `t-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function isValidTerminalId(value: string): boolean {
+  return TERMINAL_ID_PATTERN.test(value);
+}
+
+/** Clamp a proposed grid to the bounds the PTY runtime accepts. */
+export function clampTerminalSize(cols: number, rows: number): { cols: number; rows: number } {
+  return {
+    cols: clampDimension(cols, TERMINAL_MIN_COLS, TERMINAL_MAX_COLS),
+    rows: clampDimension(rows, TERMINAL_MIN_ROWS, TERMINAL_MAX_ROWS),
+  };
+}
+
+export function encodeServerFrame(frame: TerminalServerFrame): string {
+  return JSON.stringify(frame);
+}
+
+export function encodeClientFrame(frame: TerminalClientFrame): string {
+  return JSON.stringify(frame);
+}
+
+/** Decode a control frame from either a parsed object or raw JSON text. */
+export function decodeClientFrame(raw: unknown): TerminalClientFrame | null {
+  const value = typeof raw === 'string' ? tryParse(raw) : raw;
+  if (!isRecord(value)) return null;
+
+  if (value.t === 'attach') {
+    const cols = readDimension(value.cols);
+    const rows = readDimension(value.rows);
+    if (cols === null || rows === null) return null;
+    const frame: TerminalAttachFrame = { t: 'attach', cols, rows };
+    if (typeof value.root === 'string') frame.root = value.root;
+    if (typeof value.repo === 'string') frame.repo = value.repo;
+    if (value.theme === 'light' || value.theme === 'dark') frame.theme = value.theme;
+    return frame;
+  }
+
+  if (value.t === 'resize') {
+    const cols = readDimension(value.cols);
+    const rows = readDimension(value.rows);
+    if (cols === null || rows === null) return null;
+    return { t: 'resize', cols, rows };
+  }
+
+  if (value.t === 'close') return { t: 'close' };
+  return null;
+}
+
+export function decodeServerFrame(raw: string): TerminalServerFrame | null {
+  const value = tryParse(raw);
+  if (!isRecord(value)) return null;
+
+  if (value.t === 'ready') {
+    if (typeof value.id !== 'string' || typeof value.cwd !== 'string') return null;
+    const replayBytes = typeof value.replayBytes === 'number' ? value.replayBytes : 0;
+    return { ...(value as unknown as TerminalSnapshot), t: 'ready', replayBytes };
+  }
+
+  if (value.t === 'exit') {
+    return {
+      t: 'exit',
+      exitCode: typeof value.exitCode === 'number' ? value.exitCode : null,
+      signal: typeof value.signal === 'string' ? value.signal : null,
+    };
+  }
+
+  if (value.t === 'error' && typeof value.message === 'string') {
+    return { t: 'error', code: readErrorCode(value.code), message: value.message };
+  }
+
+  return null;
+}
+
+/** WebSocket endpoint for one terminal. Browser-only: reads `window.location`. */
+export function terminalSocketUrl(terminalId: string): string {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${window.location.host}/api/terminal/${encodeURIComponent(terminalId)}/ws`;
+}
+
+function clampDimension(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+function readDimension(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : null;
+}
+
+function readErrorCode(value: unknown): TerminalErrorCode {
+  return value === 'capacity' || value === 'cwd' || value === 'shell' || value === 'spawn' ? value : 'unknown';
+}
+
+function tryParse(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}

package/src/shared/types/omp/agent.ts

@@ -22,10 +22,22 @@ export interface OmpAgentEvent {
  *  into ChatMessageData lands on one of these. */
 export interface OmpAgentCallbacks {
   onAgentStart?: () => void;
+  /** A single turn inside the run began (multi-turn runs emit several). */
+  onTurnStart?: () => void;
   onMessageUpdate?: (msg: ChatMessageData) => void;
   onMessageEnd?: (msg: ChatMessageData) => void;
   onAgentEnd?: (info: { errorMessage?: string; message?: string }) => void;
   onPromptError?: (errorMessage: string) => void;
+  /** The dispatched prompt ran no agent turn: omp executed a built-in slash
+   *  command itself (ack `agentInvoked:false`, e.g. /usage, /compact). No
+   *  agent_start/agent_end follows, so the timeline must clear the optimistic
+   *  generating state here or the AI placeholder spins forever. */
+  onPromptSettled?: () => void;
+  /** Output of a built-in slash command omp executed on the prompt path
+   *  (`command_output` frame — /usage, /model, /compact result, …). Lives only
+   *  on the live stream: it never enters get_state.messages or the session
+   *  JSONL, so the timeline must render it from this frame or it is lost. */
+  onCommandOutput?: (text: string) => void;
   onNotice?: (level: string, message: string) => void;
   onConnected?: () => void;
   /** Mount-time probe found the session mid-run → the stream was reattached