ompchamber 1.0.0 → 1.1.0

package/src/shared/lib/workspace/panel-widths.ts

@@ -8,75 +8,192 @@
  * like a reset. The chat column is the group's filler — flexbox sizes it — so
  * it has no remembered width, only a floor it may not be pushed below.
  *
- * Sizes are pixels — the unit the panel constraints are written in — and are
- * persisted as `app_settings.desktopLayoutSizes`.
+ * Two units, deliberately:
+ *
+ * - The **sidebar** is pixels. It holds a session list, which does not get more
+ *   useful on a wider monitor, and OpenChamber's sidebar is pixels too.
+ * - The **editor and right panels** are a *share of the group's available
+ *   area*. A pixel width is only right on the display it was dragged on; a
+ *   fraction follows a window resize. A remembered pixel value is kept
+ *   alongside as the fallback for the window before the area is measured and
+ *   for blobs written before the fraction existed.
+ *
+ * Sizes persist as `app_settings.desktopLayoutSizes`.
  */
 import { isRightPanelType, type RightPanelType } from '@/shared/lib/workspace/right-panels';
 
 /** The editor panel keeps a separate width while a diff tab is active. */
 export type EditorWidthMode = 'editor' | 'diff';
 
+/**
+ * A panel width in both units. `fraction` is authoritative once the group's
+ * area is known; `px` is what the panel falls back to before then, and what a
+ * blob written before fractions existed carries.
+ */
+export interface PanelWidth {
+  px?: number;
+  fraction?: number;
+}
+
 export interface PanelWidths {
-  /** Session sidebar. */
+  /** Session sidebar. Pixels only — it does not scale with the window. */
   left?: number;
   /** Editor panel while a source file tab is active. */
-  editor?: number;
+  editor?: PanelWidth;
   /** Editor panel while a diff tab is active. */
-  diff?: number;
+  diff?: PanelWidth;
   /** Right panel, keyed by the activity-bar view it currently shows. */
-  right?: Partial<Record<RightPanelType, number>>;
+  right?: Partial<Record<RightPanelType, PanelWidth>>;
 }
 
-/** Fallbacks for panels that have never been resized. */
-export const DEFAULT_PANEL_WIDTHS: Record<EditorWidthMode | 'left', number> = {
-  left: 268,
+/**
+ * Fraction each editor mode opens at, and the px width used before the group's
+ * area is known. The diff fraction matches OpenChamber's `diff` surface (3/5);
+ * its px fallback stays wider than the source editor's because `SplitView`
+ * states a 700px floor of its own, so anything below it scrolls sideways.
+ */
+export const DEFAULT_EDITOR_FRACTIONS: Record<EditorWidthMode, number> = {
+  editor: 0.6,
+  diff: 0.6,
+};
+
+export const DEFAULT_EDITOR_WIDTHS: Record<EditorWidthMode, number> = {
   editor: 600,
-  // Side-by-side diffs need both halves readable at once: `SplitView` states a
-  // 700px floor of its own, so anything below it scrolls sideways on open.
   diff: 720,
 };
 
+/** Fallback for the sidebar, which has no fraction. */
+export const DEFAULT_LEFT_PANEL_WIDTH = 280;
+
 /**
  * Panel floors and ceilings. The sidebar ceiling and the chat floor are a pair:
  * `MIN_CHAT_PANEL_WIDTH` is what stops the workspace stack from eating the
- * conversation, and it is also why the sidebar cannot open past 520 and still
- * leave the editor (300) and a browser view (320) room on a 1440px display.
+ * conversation, and it is also why the sidebar cannot open past 500 and still
+ * leave the editor (320) and a browser view (320) room on a 1440px display.
+ *
+ * `MIN_EDITOR_PANEL_WIDTH` matches the shared right-panel floor so the two
+ * panels cannot disagree about the narrowest width the same content is shown
+ * at.
  */
-export const MIN_LEFT_PANEL_WIDTH = 200;
-export const MAX_LEFT_PANEL_WIDTH = 520;
-export const MIN_CHAT_PANEL_WIDTH = 420;
-export const MIN_EDITOR_PANEL_WIDTH = 300;
-export const MAX_EDITOR_PANEL_WIDTH = 1200;
+export const MIN_LEFT_PANEL_WIDTH = 264;
+export const MAX_LEFT_PANEL_WIDTH = 500;
+export const MIN_CHAT_PANEL_WIDTH = 400;
+export const MIN_EDITOR_PANEL_WIDTH = 320;
+
+/** Draggable separator width in px (`w-[3px]` in `ResizeHandle`). */
+export const HANDLE_WIDTH = 3;
+
+/** How much of a drag may re-apply the real width, in ms. */
+export const RESIZE_FOLLOW_INTERVAL_MS = 100;
+
+export interface ResolveWidthArgs {
+  /** Remembered width for this slot, if the user ever resized it. */
+  stored?: PanelWidth;
+  /** Fraction this slot opens at when nothing was remembered. */
+  defaultFraction: number;
+  /** px this slot opens at before the area is known. */
+  defaultPx: number;
+  /** Measured area of the group, or null before the observer reports. */
+  available: number | null;
+  min: number;
+  /** Floors the other fixed panels in the same group must keep. */
+  siblingMin: number;
+  /** Separators in the group, which also consume width. */
+  handleCount: number;
+}
 
-function pixelWidth(value: unknown): number | undefined {
+/**
+ * Resolve one panel's width in px.
+ *
+ * The ceiling is dynamic — `available − chat floor − the other panels' floors`
+ * — rather than a fixed number, because a fixed one either wastes a large
+ * monitor or eats the chat on a small one. Both the editor and the right panel
+ * compete for the same budget, so whichever renders first takes its share and
+ * the other gets what is left; the caller passes `siblingMin` to say which.
+ *
+ * Without a measured area there is no budget to divide, so the stored or
+ * default pixel width is used unchanged.
+ */
+export function resolvePanelWidth(args: ResolveWidthArgs): number {
+  const { stored, defaultFraction, defaultPx, available, min, siblingMin, handleCount } = args;
+
+  if (available === null || available <= 0) return Math.max(min, Math.round(stored?.px ?? defaultPx));
+
+  const ceiling = Math.max(
+    min,
+    Math.floor(available - MIN_CHAT_PANEL_WIDTH - siblingMin - handleCount * HANDLE_WIDTH),
+  );
+
+  // A remembered fraction wins. A px-only value is honoured as written — the
+  // conversion below is an identity, deliberately: a pixel width someone chose
+  // is not silently rescaled, and it starts following the window only once that
+  // slot is dragged, which stores a fraction beside it. Reading rather than
+  // rewriting the stored blob is also what keeps a session's own widths from
+  // being clobbered by the global seed before that session's blob has loaded.
+  const fraction = stored?.fraction
+    ?? (stored?.px != null ? Math.min(1, stored.px / available) : defaultFraction);
+  const wanted = Math.round(fraction * available);
+
+  return Math.min(Math.max(wanted, min), ceiling);
+}
+
+function panelWidth(value: unknown): PanelWidth | undefined {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value > 0 ? { px: Math.round(value) } : undefined;
+  }
+  if (!value || typeof value !== 'object') return undefined;
+
+  const source = value as Record<string, unknown>;
+  const px = Number.isFinite(source.px) && (source.px as number) > 0 ? Math.round(source.px as number) : undefined;
+  const fraction = Number.isFinite(source.fraction) && (source.fraction as number) > 0 && (source.fraction as number) <= 1
+    ? (source.fraction as number)
+    : undefined;
+
+  if (px === undefined && fraction === undefined) return undefined;
+  return { ...(px !== undefined ? { px } : {}), ...(fraction !== undefined ? { fraction } : {}) };
+}
+
+function sidebarWidth(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : undefined;
 }
 
 /**
- * Coerce a stored blob into the current shape. Blobs written before per-view
- * widths held the right panel as a single number shared by every view; that
- * number belongs to whichever view was open when it was written, so it seeds
- * `legacyView` alone instead of being copied onto all eight.
+ * Coerce a stored blob into the current shape.
+ *
+ * Three older shapes are accepted, because a user's layout must survive the
+ * upgrade rather than silently reset:
+ *
+ * - a bare number is the px-only shape this app shipped before fractions;
+ * - a single number under `right` is older still, holding one width shared by
+ *   every view — it belongs to whichever view was open when it was written, so
+ *   it seeds `legacyView` alone instead of being copied onto all eight;
+ * - an unknown `right` key is dropped rather than trusted.
+ *
+ * Nothing is converted to a fraction here: this function is pure and the
+ * conversion needs the group's measured area. The layout performs it once the
+ * area is known (see `usePanelWidths`).
  */
 export function normalizePanelWidths(raw: unknown, legacyView: RightPanelType): PanelWidths {
   if (!raw || typeof raw !== 'object') return {};
   const source = raw as Record<string, unknown>;
 
   const widths: PanelWidths = {};
-  for (const key of ['left', 'editor', 'diff'] as const) {
-    const value = pixelWidth(source[key]);
+  const left = sidebarWidth(source.left);
+  if (left !== undefined) widths.left = left;
+  for (const key of ['editor', 'diff'] as const) {
+    const value = panelWidth(source[key]);
     if (value !== undefined) widths[key] = value;
   }
 
-  const right: Partial<Record<RightPanelType, number>> = {};
+  const right: Partial<Record<RightPanelType, PanelWidth>> = {};
   if (source.right && typeof source.right === 'object') {
     for (const [view, value] of Object.entries(source.right as Record<string, unknown>)) {
       if (!isRightPanelType(view)) continue;
-      const size = pixelWidth(value);
+      const size = panelWidth(value);
       if (size !== undefined) right[view] = size;
     }
   } else {
-    const legacy = pixelWidth(source.right);
+    const legacy = panelWidth(source.right);
     if (legacy !== undefined) right[legacyView] = legacy;
   }
   if (Object.keys(right).length > 0) widths.right = right;
@@ -84,9 +201,23 @@ export function normalizePanelWidths(raw: unknown, legacyView: RightPanelType):
   return widths;
 }
 
-/** Fold a freshly measured patch over the stored widths (one level deep for `right`). */
+/**
+ * Fold a freshly measured patch over the stored widths (one level deep for
+ * `right`, and within a slot for its two units — a fraction patch must not
+ * discard the px fallback it was derived from).
+ */
 export function mergePanelWidths(current: PanelWidths, patch: PanelWidths): PanelWidths {
   const next: PanelWidths = { ...current, ...patch };
-  if (patch.right) next.right = { ...current.right, ...patch.right };
+  if (patch.right) {
+    const right: Partial<Record<RightPanelType, PanelWidth>> = { ...current.right };
+    for (const [view, value] of Object.entries(patch.right)) {
+      if (!isRightPanelType(view) || !value) continue;
+      right[view] = { ...current.right?.[view], ...value };
+    }
+    next.right = right;
+  }
+  for (const key of ['editor', 'diff'] as const) {
+    if (patch[key]) next[key] = { ...current[key], ...patch[key] };
+  }
   return next;
 }

package/src/shared/lib/workspace/right-panels.ts

@@ -1,6 +1,7 @@
 /**
- * Right developer panel catalog: the activity-bar views, the width each one
- * opens at, and the floor at which its content starts to clip.
+ * Right developer panel catalog: the activity-bar views, the share of the
+ * group's available area each one opens at, and the floor at which its content
+ * clips.
  *
  * The list lives here rather than in the activity bar component so the layout
  * can key one remembered width per view (`panel-widths.ts`) and validate a
@@ -21,36 +22,74 @@ export const RIGHT_PANEL_TYPES = [
 
 export type RightPanelType = (typeof RIGHT_PANEL_TYPES)[number];
 
-/** Width (px) a view opens at the first time it is shown. */
+/**
+ * Share of the group's available area a view takes the first time it is shown.
+ *
+ * A fraction rather than a pixel width is what lets a panel follow a window
+ * resize instead of holding a number that was only right on the display it was
+ * dragged on. Where OpenChamber ships the same surface its `defaultWidthFraction`
+ * is reused verbatim; the rest are derived.
+ *
+ * - `files` is the file tree *alone*. OpenChamber's 3/5 `file` surface holds a
+ *   tree **and** an editor column, so its fraction is not ours to borrow — their
+ *   tree-only column is 200–480px, which is what this 0.22 approximates at a
+ *   1440-class viewport.
+ * - `search` matches `files`: both are single narrow columns of rows.
+ * - `usage` has no OpenChamber counterpart; 0.48 keeps the pixel default it
+ *   shipped with.
+ * - `context`, `git`, `terminal` and both browsers take OpenChamber's values.
+ */
+export const DEFAULT_RIGHT_PANEL_FRACTIONS: Record<RightPanelType, number> = {
+  context: 0.45,
+  files: 0.22,
+  search: 0.22,
+  git: 0.4,
+  // 80 columns at the terminal's 12px Fira Code (≈7.2px/char) need ≈600px.
+  terminal: 0.6,
+  'user-browser': 0.45,
+  browser: 0.45,
+  usage: 0.48,
+};
+
+/**
+ * Width (px) a view opens at before the group's area has been measured. Kept at
+ * the values these views shipped with, so the first paint is unchanged and a
+ * window that never reports an area still opens sensibly.
+ */
 export const DEFAULT_RIGHT_PANEL_WIDTHS: Record<RightPanelType, number> = {
+  context: 536,
   files: 268,
   search: 268,
   git: 268,
-  // 80 columns at the terminal's 12px Fira Code (≈7.2px/char) need ≈600px
-  // before the scrollbar; the old 536 landed at ≈74 columns and wrapped.
   terminal: 640,
-  context: 536,
   'user-browser': 804,
   browser: 804,
   usage: 536,
 };
 
-/** Minimum width (px) each view needs before its toolbar or list breaks. */
+/**
+ * Minimum width (px) each view needs before its toolbar or list breaks.
+ *
+ * Per view, not one shared floor: a file tree reads fine at 200 while a shell
+ * does not, and OpenChamber draws the same line (its tree-only column floors at
+ * 200, its shared panel at 320). A uniform floor would either clip the tree or
+ * force every view to shell width.
+ */
 export const MIN_RIGHT_PANEL_WIDTHS: Record<RightPanelType, number> = {
   files: 200,
   search: 200,
+  // The commit graph is a fixed-width gutter plus a message column.
   git: 260,
-  // A 200px terminal is ≈27 columns — below every shell's assumption; 320
-  // holds a two-pane TUI or a git log with the graph.
+  // A 320px terminal is ≈27 columns — below every shell's assumption, but the
+  // point where a two-pane TUI or a git log with the graph still reads.
   terminal: 320,
+  // Telemetry charts and tables need room before they wrap.
   context: 420,
   'user-browser': 320,
   browser: 320,
   usage: 420,
 };
 
-export const MAX_RIGHT_PANEL_WIDTH = 1200;
-
 /** Guards a persisted or URL-provided view id before it keys a width. */
 export function isRightPanelType(value: unknown): value is RightPanelType {
   return typeof value === 'string' && (RIGHT_PANEL_TYPES as readonly string[]).includes(value);

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

@@ -12,6 +12,9 @@
  * Key namespace contract (dot-prefixed by owning panel):
  * - layout.activeRightPanel   RightPanelType
  * - layout.showRightPanel     boolean
+ * - layout.showLeftPanel      boolean
+ * - layout.userToggledEditor  boolean | null (null = follow whether a file is open)
+ * - layout.panelWidths        PanelWidths (per-panel widths, seeded from app_settings.desktopLayoutSizes)
  * - layout.openedFiles        editor file entries array
  * - layout.activeFileId       number | null
  * - editor.previewMode        Record<fileId, boolean>

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/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;
 }