ompchamber 0.8.0 → 1.1.0

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/chat.ts

@@ -187,71 +187,6 @@ export interface QueuedMessage {
   model: QueuedMessageModel | null;
 }
 
-export interface AIModelOption {
-  id: string;
-  name: string;
-  provider: string;
-  providerIcon?: string;
-  contextWindow?: string | number;
-  isCmdAgent?: boolean;
-  isFavorite?: boolean;
-  isRecent?: boolean;
-  thinkingLevel?: string;
-  /** Baked thinking ladder for this model: `["off", ...efforts]`. */
-  thinkingLevels?: string[];
-  capabilities?: string[];
-  input?: string;
-  output?: string;
-  cost?: {
-    input: string | number;
-    output: string | number;
-    cacheRead?: string | number;
-    cacheWrite?: string | number;
-  };
-  description?: string;
-}
-
-// ── Real omp model registry (forked from omp-web) ──────────────────────────
-
-/** One pickable model from the omp catalog (`/api/models` modelList). */
-export interface ModelEntry {
-  id: string;
-  name: string;
-  provider: string;
-  supportsFastMode?: boolean;
-  contextWindow?: number;
-  maxTokens?: number;
-  /** Baked thinking ladder for this model: `["off", ...efforts]`. */
-  thinkingLevels?: string[];
-  /** Cost in $/1M tokens (omp catalog). */
-  cost?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
-}
-
-/** A model selected by provider + modelId (omp's set_model shape). */
-export interface SelectedModel {
-  provider: string;
-  modelId: string;
-}
-
-/** Model-level thinking metadata read off the live session state. */
-export interface ThinkingModelMeta {
-  provider: string;
-  modelId: string;
-  name?: string;
-  reasoning?: boolean;
-  thinking?: { efforts?: string[] };
-}
-
-/** Response shape of GET /api/models (mirrors omp-web ModelsData). */
-export interface ModelsData {
-  models: Record<string, string>;
-  modelList: ModelEntry[];
-  defaultModel: SelectedModel | null;
-  thinkingLevels: Record<string, string[]>;
-  connectedProviders?: { id: string; name: string; disabled: boolean }[];
-  modelError?: string;
-}
-
 // ── Composer autocomplete (@file/agent / /command+skill) ───────────────────
 
 /** Trigger group that opened the composer autocomplete: `@` → mention, `/` → command. */
@@ -259,6 +194,13 @@ export type ComposerPickKind = 'mention' | 'command';
 /** Origin of a pickable item: an `@` mention is an agent or a workspace file. */
 export type ComposerPickSource = 'agent' | 'file' | 'command' | 'skill';
 
+/**
+ * Which part of a slash invocation the popup is completing. oh-my-pi splits
+ * these the same way: `name` completes the command token itself, `args`
+ * completes a declarative subcommand after `<command> `.
+ */
+export type ComposerTriggerPhase = 'name' | 'args';
+
 /** A detected trigger: the `@`/`/` char plus the query typed after it. */
 export interface ComposerTrigger {
   kind: ComposerPickKind;
@@ -267,6 +209,18 @@ export interface ComposerTrigger {
   start: number;
   /** Caret index when detected. */
   end: number;
+  /** Command completion phase; `mention` triggers are always `name`. */
+  phase: ComposerTriggerPhase;
+  /** Index the accepted text replaces from — equals `start` in the `name` phase. */
+  replaceFrom: number;
+  /** Command the `args` phase belongs to (name or alias as typed). */
+  command?: string;
+  /**
+   * The `/token` sits mid-prompt (prose precedes it on the line or an earlier
+   * line exists), so only skill entries may surface — oh-my-pi's
+   * `buildMidPromptSkillCompletions` gate.
+   */
+  midPrompt?: boolean;
 }
 
 /** One autocomplete item surfaced in the composer popover. */
@@ -281,6 +235,25 @@ export interface ComposerPickItem {
   token: string;
   /** Workspace-relative path (file items only). */
   path?: string;
+  /**
+   * Suppress the trailing space on insertion. Set on the collapsed `/skill:`
+   * namespace row so the popup reopens with the individual skills, matching
+   * oh-my-pi's accept path.
+   */
+  insertWithoutSpace?: boolean;
+  /** Command aliases from oh-my-pi (`/models` for `/model`). */
+  aliases?: string[];
+  /** Declarative subcommands; drives the `args` phase. */
+  subcommands?: ComposerSubcommand[];
+  /** Argument hint (`[on|off|status]`), prefixed to the description like omp. */
+  inputHint?: string;
+}
+
+/** One declarative subcommand of an oh-my-pi slash command. */
+export interface ComposerSubcommand {
+  name: string;
+  description?: string;
+  usage?: string;
 }
 
 /** A pick item after filtering, with the matched range within `name` (or null). */

package/src/shared/types/index.ts

@@ -2,6 +2,7 @@ export * from '@/shared/types/workspace';
 export * from '@/shared/types/fs';
 export * from '@/shared/types/git';
 export * from '@/shared/types/chat';
+export * from '@/shared/types/models';
 export * from '@/shared/types/terminal';
 export * from '@/shared/types/settings/state';
 export * from '@/shared/types/tokenUsage';

package/src/shared/types/models.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Model catalog types shared by the composer picker, the settings pages and
+ * the `/api/models` route: the picker row (`AIModelOption`), the registry entry
+ * (`ModelEntry`), the selection reference omp's `set_model` takes, and the
+ * stored favorite/recent preference pair.
+ *
+ * Split out of `chat.ts` so that file stays under the per-file ceiling — the
+ * picker's row shape is not part of the chat message model it was nested in.
+ */
+
+export interface AIModelOption {
+  id: string;
+  name: string;
+  provider: string;
+  providerIcon?: string;
+  contextWindow?: string | number;
+  isCmdAgent?: boolean;
+  /**
+   * Favorite / last-used flag. On a picker row these are DERIVED from the
+   * stored preference keys (`ModelPreferences`), never read off the registry —
+   * a favorite is a chamber-local preference, not a property of omp's config.
+   * On the MOCK catalog they are the seed for a fresh install's rails.
+   */
+  isFavorite?: boolean;
+  /** MOCK seed only — the RECENT rail is ordered by `ModelPreferences.recentKeys`. */
+  isRecent?: boolean;
+  thinkingLevel?: string;
+  /** Baked thinking ladder for this model: `["off", ...efforts]`. */
+  thinkingLevels?: string[];
+  capabilities?: string[];
+  input?: string;
+  output?: string;
+  cost?: {
+    input: string | number;
+    output: string | number;
+    cacheRead?: string | number;
+    cacheWrite?: string | number;
+  };
+  description?: string;
+}
+
+// ── Real omp model registry (forked from omp-web) ──────────────────────────
+
+/** One pickable model from the omp catalog (`/api/models` modelList). */
+export interface ModelEntry {
+  id: string;
+  name: string;
+  provider: string;
+  supportsFastMode?: boolean;
+  contextWindow?: number;
+  maxTokens?: number;
+  /** Baked thinking ladder for this model: `["off", ...efforts]`. */
+  thinkingLevels?: string[];
+  /** Cost in $/1M tokens (omp catalog). */
+  cost?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+}
+
+/** A model selected by provider + modelId (omp's set_model shape). */
+export interface SelectedModel {
+  provider: string;
+  modelId: string;
+}
+
+/** Model-level thinking metadata read off the live session state. */
+export interface ThinkingModelMeta {
+  provider: string;
+  modelId: string;
+  name?: string;
+  reasoning?: boolean;
+  thinking?: { efforts?: string[] };
+}
+
+/**
+ * The user's favorite + last-used models, keyed by the composite `provider:id`
+ * identity (`modelKey`). Stored separately from the model registry because the
+ * registry is a read-only view of omp's config — a favorite is a chamber-local
+ * preference, and an id-only key would light up every provider serving it.
+ */
+export interface ModelPreferences {
+  /** Composite keys in the order the FAVORITES rail renders them. */
+  favorites: string[];
+  /** Composite keys, most recently used first, capped at `RECENT_MODELS_LIMIT`. */
+  recentKeys: string[];
+}
+
+/** Response shape of GET /api/models (mirrors omp-web ModelsData). */
+export interface ModelsData {
+  models: Record<string, string>;
+  modelList: ModelEntry[];
+  defaultModel: SelectedModel | null;
+  thinkingLevels: Record<string, string[]>;
+  connectedProviders?: { id: string; name: string; disabled: boolean }[];
+  modelError?: string;
+  /** Absent when the settings row has never been written. */
+  modelPreferences?: ModelPreferences;
+}

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

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

@@ -150,6 +150,10 @@ export interface SubagentInfo {
   detached?: boolean;
   progress?: SubagentProgress;
   lastUpdate?: number;
+  /** Model role the run resolved to. On-disk history entries carry it here
+   *  (folded from the parent's task toolResult); live snapshots carry it on
+   *  `progress` instead, because it arrives with the progress frame. */
+  modelRole?: string;
   /** Settled result for history entries (SingleResult-derived). */
   result?: SubagentHistoryResult;
   /** Roster origin: live frames/snapshots (default) vs on-disk history. */

package/src/shared/types/settings/command.ts

@@ -1,5 +1,12 @@
 export type CommandScope = 'system' | 'user' | 'project';
 
+/** Declarative subcommand of an oh-my-pi builtin (drives `/cmd <sub>` completion). */
+export interface CommandSubcommand {
+  name: string;
+  description?: string;
+  usage?: string;
+}
+
 export interface CommandItem {
   id: string;
   name: string;
@@ -9,4 +16,10 @@ export interface CommandItem {
   overrideModel?: string;
   template: string;
   isBuiltIn?: boolean;
+  /** oh-my-pi aliases (`/models` for `/model`); live agent commands only. */
+  aliases?: string[];
+  /** Declarative subcommands; live agent commands only. */
+  subcommands?: CommandSubcommand[];
+  /** Argument hint (`[on|off|status]`); live agent commands only. */
+  inputHint?: string;
 }

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,8 @@ 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. */