ompchamber 0.7.0 → 1.0.0

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

@@ -5,8 +5,8 @@
 
 /**
  * omp agent event surface types shared by useOmpAgent, the chamber timeline
- * and the AskDialog renderer. Kept separate so the hook file stays under the
- * repo's per-file size ceiling.
+ * and the extension-dialog renderer. Kept separate so the hook file stays under
+ * the repo's per-file size ceiling.
  */
 
 import type { ChatMessageData } from '@/shared/types/chat';
@@ -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

package/src/shared/types/terminal.ts

@@ -1,19 +1,21 @@
-export interface TerminalLogItem {
-  id: string;
-  command: string;
-  stdout?: string;
-  stderr?: string;
-  exitCode: number;
-  durationMs?: number;
-  timestamp: string;
-  cwd?: string;
+/**
+ * Live terminal inventory, as served by `GET /api/terminal/sessions`.
+ *
+ * The frame types themselves live in `@/shared/lib/workspace/terminal/protocol`
+ * — they are the wire contract the socket encodes and decodes, not domain data.
+ */
+
+import type { TerminalSnapshot } from '@/shared/lib/workspace/terminal/protocol';
+
+export interface TerminalSessionsResponse {
+  terminals: TerminalSnapshot[];
 }
 
-export interface TerminalRunResponse {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  durationMs: number;
+/** Launch context for the terminal header (`GET /api/terminal/run`). */
+export interface TerminalContextResponse {
+  bunVersion: string;
+  nodeVersion: string;
+  gitBranch: string;
   cwd: string;
-  error?: string;
+  relativePath: string;
 }

package/src/shared/types/workspace.ts

@@ -15,8 +15,12 @@ export interface SessionItemData {
   hasSubagents?: boolean;
   subagentCount?: number;
   /** Server-tracked stream state: `stream` while a run is in flight, then a
-   *  one-shot `finish`/`abort`/`error` badge cleared when the session opens. */
-  streamStatus?: 'stream' | 'finish' | 'abort' | 'error';
+   *  one-shot `finish`/`abort` badge cleared when the session opens. */
+  streamStatus?: 'stream' | 'finish' | 'abort';
+  /** Live-only: the session's omp process is BLOCKED on an ask/approval dialog
+   *  waiting for a user answer. Derived from the running process registry, never
+   *  persisted — the process it describes is the same thing that owns the flag. */
+  awaitingInput?: boolean;
 }
 
 /**