ompchamber 1.0.0 → 1.2.0

package/src/client/components/workspace/editor/Toolbar.tsx

@@ -6,6 +6,8 @@ interface EditorToolbarProps {
   wordWrap: boolean;
   isMd: boolean;
   isPreview: boolean;
+  /** Raster image: no text to save or wrap, and zoom belongs to the picture. */
+  isImage?: boolean;
   onSave: () => void;
   onTogglePreview: () => void;
   onToggleWordWrap: () => void;
@@ -22,6 +24,7 @@ export function EditorToolbar({
   wordWrap,
   isMd,
   isPreview,
+  isImage = false,
   onSave,
   onTogglePreview,
   onToggleWordWrap,
@@ -40,22 +43,24 @@ export function EditorToolbar({
 
       {/* Right actions */}
       <div className="flex items-center space-x-3 text-ink/40">
-        <div className="flex items-center pr-3 border-r border-ink/10">
-          <button
-            type="button"
-            onClick={onSave}
-            className="flex items-center justify-center rounded hover:bg-ink/5 transition-colors"
-            title="Save file (Ctrl+S)"
-          >
-            {saveStatus === 'saving' ? (
-              <Save size={14} className="text-amber-500 animate-pulse" />
-            ) : saveStatus === 'saved' ? (
-              <Check size={14} className="text-success" />
-            ) : (
-              <Save size={14} className="hover:text-ink cursor-pointer" />
-            )}
-          </button>
-        </div>
+        {!isImage && (
+          <div className="flex items-center pr-3 border-r border-ink/10">
+            <button
+              type="button"
+              onClick={onSave}
+              className="flex items-center justify-center rounded hover:bg-ink/5 transition-colors"
+              title="Save file (Ctrl+S)"
+            >
+              {saveStatus === 'saving' ? (
+                <Save size={14} className="text-amber-500 animate-pulse" />
+              ) : saveStatus === 'saved' ? (
+                <Check size={14} className="text-success" />
+              ) : (
+                <Save size={14} className="hover:text-ink cursor-pointer" />
+              )}
+            </button>
+          </div>
+        )}
 
         {isMd && (
           <div onClick={onTogglePreview} className="flex items-center pr-3 border-r border-ink/10">
@@ -67,14 +72,18 @@ export function EditorToolbar({
           </div>
         )}
 
-        <div className="flex items-center space-x-2 pr-3 border-r border-ink/10">
-          <WrapText size={14} className={`cursor-pointer ${wordWrap ? 'text-ink' : 'hover:text-ink'}`} onClick={onToggleWordWrap} />
-        </div>
+        {!isImage && (
+          <>
+            <div className="flex items-center space-x-2 pr-3 border-r border-ink/10">
+              <WrapText size={14} className={`cursor-pointer ${wordWrap ? 'text-ink' : 'hover:text-ink'}`} onClick={onToggleWordWrap} />
+            </div>
 
-        <div className="flex items-center space-x-2 pr-3 border-r border-ink/10">
-          <ZoomOut size={14} className="hover:text-ink cursor-pointer" onClick={onZoomOut} />
-          <ZoomIn size={14} className="hover:text-ink cursor-pointer" onClick={onZoomIn} />
-        </div>
+            <div className="flex items-center space-x-2 pr-3 border-r border-ink/10">
+              <ZoomOut size={14} className="hover:text-ink cursor-pointer" onClick={onZoomOut} />
+              <ZoomIn size={14} className="hover:text-ink cursor-pointer" onClick={onZoomIn} />
+            </div>
+          </>
+        )}
 
         <div className="flex items-center space-x-2 pr-3 border-r border-ink/10">
           <Copy size={14} className="hover:text-ink cursor-pointer" onClick={onCopy} />

package/src/client/components/workspace/editor/index.tsx

@@ -5,6 +5,7 @@ import { MarkdownRenderer } from '@/client/components/common/MarkdownRenderer';
 import { useScrollbarFade, scrollbarFadeClass } from '@/client/hooks/ui/scrollbar-fade';
 import { EditorTabs } from '@/client/components/workspace/editor/Tabs';
 import { EditorToolbar } from '@/client/components/workspace/editor/Toolbar';
+import { ImageViewer } from '@/client/components/common/image-viewer';
 import { getDefaultContent } from '@/shared/lib/code/editor-utils';
 import { DiffPanel } from '@/client/components/workspace/diff-panel';
 import { useSessionState } from '@/client/hooks/workspace/session-state';
@@ -134,6 +135,7 @@ export function Editor({
               wordWrap={wordWrap}
               isMd={isMd}
               isPreview={isPreview}
+              isImage={editor.isImage}
               onSave={editor.saveNow}
               onTogglePreview={togglePreview}
               onToggleWordWrap={() => setWordWrap(!wordWrap)}
@@ -144,42 +146,49 @@ export function Editor({
               onToggleMaximize={() => setIsMaximized(!isMaximized)}
             />
 
-            <div onScroll={handleScroll} className={`flex-1 overflow-auto bg-paper flex ${scrollbarFadeClass(isScrolling)}`}>
-              {(isMd && isPreview) ? (
-                <div className="p-6 prose prose-sm max-w-4xl mx-auto font-sans flex-1" style={{ fontSize: `${zoomLevel}px` }}>
-                  <MarkdownRenderer content={currentContent} />
-                </div>
-              ) : (
-                <CodeSurface
-                  value={currentContent}
-                  onValueChange={editor.onChange}
-                  language={editor.language}
-                  wordWrap={wordWrap}
-                  rootClassName="flex"
-                  gutterClassName="flex flex-col text-right pl-4 pr-3 select-none text-ink/30 font-mono border-r border-ink/10 bg-canvas sticky left-0 z-10"
-                  gutterStyle={{
-                    fontSize: zoomLevel,
-                    paddingTop: 16,
-                    paddingBottom: 16,
-                    lineHeight: 1.5,
-                    fontFamily: '"Fira Code", "JetBrains Mono", "SF Mono", Consolas, monospace',
-                  }}
-                  gutterLineClassName="min-w-[1.5rem]"
-                  // `min-w-max` keeps a long line intact and lets the panel
-                  // scroll sideways; while wrapping it would instead widen the
-                  // column past the panel, so the toggle had no effect at all.
-                  editorWrapperClassName={`flex-1 code-surface ${wordWrap ? 'min-w-0' : 'min-w-max'}`}
-                  editorPadding={16}
-                  editorClassName="font-mono focus:outline-none"
-                  editorStyle={{
-                    fontFamily: '"Fira Code", "JetBrains Mono", "SF Mono", Consolas, monospace',
-                    fontSize: zoomLevel,
-                    lineHeight: 1.5,
-                    minHeight: '100%',
-                  }}
-                />
-              )}
-            </div>
+            {editor.isImage && editor.imageUrl ? (
+              // The picture owns its own pan/zoom, so it must NOT sit inside
+              // the scrolling text container — a wheel there would scroll the
+              // pane instead of zooming the image.
+              <ImageViewer src={editor.imageUrl} name={activeFile.name} className="flex-1 min-h-0" />
+            ) : (
+              <div onScroll={handleScroll} className={`flex-1 overflow-auto bg-paper flex ${scrollbarFadeClass(isScrolling)}`}>
+                {(isMd && isPreview) ? (
+                  <div className="p-6 prose prose-sm max-w-4xl mx-auto font-sans flex-1" style={{ fontSize: `${zoomLevel}px` }}>
+                    <MarkdownRenderer content={currentContent} />
+                  </div>
+                ) : (
+                  <CodeSurface
+                    value={currentContent}
+                    onValueChange={editor.onChange}
+                    language={editor.language}
+                    wordWrap={wordWrap}
+                    rootClassName="flex"
+                    gutterClassName="flex flex-col text-right pl-4 pr-3 select-none text-ink/30 font-mono border-r border-ink/10 bg-canvas sticky left-0 z-10"
+                    gutterStyle={{
+                      fontSize: zoomLevel,
+                      paddingTop: 16,
+                      paddingBottom: 16,
+                      lineHeight: 1.5,
+                      fontFamily: '"Fira Code", "JetBrains Mono", "SF Mono", Consolas, monospace',
+                    }}
+                    gutterLineClassName="min-w-[1.5rem]"
+                    // `min-w-max` keeps a long line intact and lets the panel
+                    // scroll sideways; while wrapping it would instead widen the
+                    // column past the panel, so the toggle had no effect at all.
+                    editorWrapperClassName={`flex-1 code-surface ${wordWrap ? 'min-w-0' : 'min-w-max'}`}
+                    editorPadding={16}
+                    editorClassName="font-mono focus:outline-none"
+                    editorStyle={{
+                      fontFamily: '"Fira Code", "JetBrains Mono", "SF Mono", Consolas, monospace',
+                      fontSize: zoomLevel,
+                      lineHeight: 1.5,
+                      minHeight: '100%',
+                    }}
+                  />
+                )}
+              </div>
+            )}
           </>
         )
       ) : (

package/src/client/components/workspace/model-dropdown/groups.ts

@@ -1,3 +1,8 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 import type { AIModelOption } from '@/shared/types';
 import { modelKey } from '@/shared/lib/models/identity';
 
@@ -13,6 +18,25 @@ export interface ModelPickerGroups {
   index: Record<string, number>;
 }
 
+/**
+ * Models named by an ordered key list, in that order.
+ *
+ * The order is the point: RECENT means "most recently used first", and the
+ * catalog's own order is alphabetical by name — so reading recents off a flag
+ * (the previous `isRecent`) could not express the ranking at all, and a
+ * re-picked model never moved back to the top.
+ */
+function modelsInKeyOrder(models: AIModelOption[], keys: readonly string[]): AIModelOption[] {
+  if (keys.length === 0) return [];
+  const byKey = new Map(models.map((model) => [modelKey(model), model]));
+  const ordered: AIModelOption[] = [];
+  for (const key of keys) {
+    const match = byKey.get(key);
+    if (match) ordered.push(match);
+  }
+  return ordered;
+}
+
 /**
  * All derived picker state in one place: search filtering, the favorites/recent
  * rails, the per-provider grouping, and the flattened key→index map the
@@ -21,11 +45,16 @@ export interface ModelPickerGroups {
  * Keying `index` on the composite identity matters — the same model id is served
  * by several providers, so an id-only key collapsed their rows onto one index
  * and hovering one highlighted every other provider's row.
+ *
+ * A row never appears twice: a favorite that is also recent is only listed under
+ * FAVORITES, and neither rail repeats the row in its provider section.
  */
 export function buildPickerGroups(
   models: AIModelOption[],
   search: string,
   collapsedSections: Record<string, boolean>,
+  favoriteKeys: readonly string[],
+  recentKeys: readonly string[],
 ): ModelPickerGroups {
   const query = search.trim().toLowerCase();
   const filtered = query
@@ -37,8 +66,12 @@ export function buildPickerGroups(
       )
     : models;
 
-  const favorites = filtered.filter(m => m.isFavorite);
-  const recent = filtered.filter(m => m.isRecent && !m.isFavorite);
+  // The rails are ordered by the stored key lists, not by the catalog order.
+  // A search narrows them like every other section — a starred model that does
+  // not match the query must not sit above the results.
+  const favorites = modelsInKeyOrder(filtered, favoriteKeys);
+  const favoriteSet = new Set(favoriteKeys);
+  const recent = modelsInKeyOrder(filtered, recentKeys).filter(m => !favoriteSet.has(modelKey(m)));
 
   const byProvider: Record<string, AIModelOption[]> = {};
   for (const model of filtered) {

package/src/client/components/workspace/model-dropdown/index.tsx

@@ -1,13 +1,14 @@
 import type { TargetedMouseEvent } from 'preact';
 import { useMemo, useRef, useState } from 'preact/hooks';
 import { ChevronDown, Sparkles } from 'lucide-preact';
-import type { AIModelOption } from '@/shared/types';
+import type { AIModelOption, ModelPreferences } from '@/shared/types';
 import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
 import { invalidateModelsCache } from '@/shared/lib/models/client';
 import { ModelDropdownPanel } from '@/client/components/workspace/model-dropdown/Panel';
 import { useModelCatalog } from '@/client/components/workspace/model-dropdown/use-catalog';
 import { buildPickerGroups } from '@/client/components/workspace/model-dropdown/groups';
 import { modelKey } from '@/shared/lib/models/identity';
+import { RECENT_MODELS_LIMIT, filterKnownKeys, readModelPreferences, recordRecentKey, toggleFavoriteKey } from '@/shared/lib/models/preferences';
 
 interface ModelDropdownProps {
   selectedModel?: AIModelOption;
@@ -29,7 +30,15 @@ export function ModelDropdown({
   const [focusedIndex, setFocusedIndex] = useState<number>(-1);
   const [hoveredModel, setHoveredModel] = useState<AIModelOption | null>(null);
   const [collapsedSections, setCollapsedSections] = useState<Record<string, boolean>>({});
-  const { models, isLoading, setModels, selectedModel, setSelectedModel } = useModelCatalog(externalSelectedModel);
+  const {
+    models,
+    isLoading,
+    setModels,
+    selectedModel,
+    setSelectedModel,
+    preferences,
+    applyPreferences,
+  } = useModelCatalog(externalSelectedModel);
 
   const containerRef = useRef<HTMLDivElement>(null);
   useOnClickOutside(containerRef, () => {
@@ -46,8 +55,8 @@ export function ModelDropdown({
     visibleFlatList,
     index: modelIndex,
   } = useMemo(
-    () => buildPickerGroups(models, search, collapsedSections),
-    [models, search, collapsedSections],
+    () => buildPickerGroups(models, search, collapsedSections, preferences.favorites, preferences.recentKeys),
+    [models, search, collapsedSections, preferences],
   );
 
   const selectedModelKey = modelKey(selectedModel);
@@ -70,17 +79,40 @@ export function ModelDropdown({
     setCollapsedSections(prev => ({ ...prev, [section]: !prev[section] }));
   };
 
+  /**
+   * Flip one row's star. The optimistic stamp and the rollback both go through
+   * the preference pair — the flag on a row is derived state, so patching the
+   * row alone would be undone by the next `applyModelPreferences` (every reload
+   * re-stamps rows from the store).
+   */
   const handleToggleFavorite = async (model: AIModelOption, e: TargetedMouseEvent<HTMLElement>) => {
     e.stopPropagation();
     const key = modelKey(model);
-    setModels(prev => prev.map(m => modelKey(m) === key ? { ...m, isFavorite: !m.isFavorite } : m));
+    const previous = preferences;
+    const optimistic: ModelPreferences = {
+      ...previous,
+      favorites: toggleFavoriteKey(previous.favorites, key),
+    };
+    applyPreferences(optimistic);
     try {
-      await fetch('/api/models', {
+      const response = await fetch('/api/models', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ actionType: 'toggleFavorite', provider: model.provider, modelId: model.id }),
       });
-    } catch {}
+      if (!response.ok) throw new Error(`toggleFavorite failed: ${response.status}`);
+      const data = await response.json() as { modelPreferences?: unknown };
+      // The server is the authority on the resulting list — it also drops keys
+      // the registry no longer serves. An absent/malformed payload keeps the
+      // optimistic list rather than blanking the rail.
+      if (data.modelPreferences) {
+        applyPreferences(readModelPreferences(data.modelPreferences));
+      }
+    } catch {
+      // A failed write must not leave the star lit: the next reload would show
+      // it unlit anyway, so the rollback keeps the panel honest immediately.
+      applyPreferences(previous);
+    }
   };
 
   const cycleThinkingLevel = (model: AIModelOption) => {
@@ -125,6 +157,15 @@ export function ModelDropdown({
     onSelectModel?.(model);
     setIsOpen(false);
     setHoveredModel(null);
+    // Move the pick to the top of RECENT straight away — the server records it
+    // alongside the selection, and waiting for the round trip would leave the
+    // rail stale until the next full reload. Same rules as the server's write:
+    // pruned to the models the registry serves, de-duplicated, capped.
+    const known = new Set(models.map(modelKey));
+    applyPreferences({
+      favorites: filterKnownKeys(preferences.favorites, known),
+      recentKeys: recordRecentKey(filterKnownKeys(preferences.recentKeys, known), modelKey(model), RECENT_MODELS_LIMIT),
+    });
     try {
       await fetch('/api/models', {
         method: 'POST',

package/src/client/components/workspace/model-dropdown/use-catalog.ts

@@ -1,6 +1,11 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
-import type { AIModelOption, ModelEntry } from '@/shared/types';
+import type { AIModelOption, ModelEntry, ModelPreferences } from '@/shared/types';
 import { fetchModelsData, subscribeModelsUpdated } from '@/shared/lib/models/client';
+import {
+  EMPTY_MODEL_PREFERENCES,
+  applyModelPreferences,
+  readModelPreferences,
+} from '@/shared/lib/models/preferences';
 
 function toOption(m: ModelEntry): AIModelOption {
   const ladder = Array.isArray(m.thinkingLevels) ? m.thinkingLevels : [];
@@ -28,6 +33,10 @@ export interface ModelCatalogState {
   setModels: (updater: (prev: AIModelOption[]) => AIModelOption[]) => void;
   selectedModel: AIModelOption | null;
   setSelectedModel: (model: AIModelOption | null) => void;
+  /** Favorite + recent rails, ordered by the stored key lists. */
+  preferences: ModelPreferences;
+  /** Merge a server-returned preference pair into the rails. */
+  applyPreferences: (preferences: ModelPreferences) => void;
 }
 
 /**
@@ -42,11 +51,17 @@ export interface ModelCatalogState {
  * An externally-driven selection (the composer's session model) always wins over
  * the API's own default — it is read through a ref so a thinking-level change
  * flowing back through the prop does not re-arm the fetch.
+ *
+ * Favorites arrive as a key list, never as a flag on the registry rows: the
+ * registry is a read-only view of omp's config, so the only place a star can
+ * live is the preference store. The rows are stamped from it here, which is why
+ * a toggle must go through {@link applyPreferences} rather than patching a row.
  */
 export function useModelCatalog(externalSelectedModel?: AIModelOption): ModelCatalogState {
   const [models, setModelsState] = useState<AIModelOption[]>([]);
   const [isLoading, setIsLoading] = useState(true);
   const [selectedModel, setSelectedModel] = useState<AIModelOption | null>(externalSelectedModel ?? null);
+  const [preferences, setPreferences] = useState<ModelPreferences>(EMPTY_MODEL_PREFERENCES);
 
   const externalSelectedRef = useRef(externalSelectedModel);
   externalSelectedRef.current = externalSelectedModel;
@@ -56,11 +71,18 @@ export function useModelCatalog(externalSelectedModel?: AIModelOption): ModelCat
     setModelsState(updater);
   }, []);
 
+  const applyPreferences = useCallback((next: ModelPreferences) => {
+    setPreferences(next);
+    setModelsState(prev => applyModelPreferences(prev, next));
+  }, []);
+
   const load = useCallback(async () => {
     try {
       const data = await fetchModelsData();
       if (Array.isArray(data.modelList) && data.modelList.length > 0) {
-        const realModels = data.modelList.map(toOption);
+        const prefs = readModelPreferences(data.modelPreferences);
+        const realModels = applyModelPreferences(data.modelList.map(toOption), prefs);
+        setPreferences(prefs);
         // Keep a thinking level the user already picked, but only when it is
         // still a real level of this model's ladder (legacy mock values like
         // 'Default'/'High' must not be preserved).
@@ -76,7 +98,9 @@ export function useModelCatalog(externalSelectedModel?: AIModelOption): ModelCat
           if (match) setSelectedModel(match);
         }
       } else if (Array.isArray(data.models) && data.models.length > 0) {
-        setModelsState(data.models);
+        const prefs = readModelPreferences(data.modelPreferences);
+        setPreferences(prefs);
+        setModelsState(applyModelPreferences(data.models, prefs));
       }
       if (data.selectedModel && !externalSelectedRef.current) {
         setSelectedModel(data.selectedModel);
@@ -107,5 +131,5 @@ export function useModelCatalog(externalSelectedModel?: AIModelOption): ModelCat
     ));
   }, [externalSelectedModel]);
 
-  return { models, isLoading, setModels, selectedModel, setSelectedModel };
+  return { models, isLoading, setModels, selectedModel, setSelectedModel, preferences, applyPreferences };
 }

package/src/client/hooks/chat/btw/index.ts

@@ -0,0 +1,180 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Live BTW state for one session: the topic list, the answer streaming right
+ * now, and the commands that drive them.
+ *
+ * The server owns the state — every frame is a full snapshot or a delta, and
+ * every command answers with the canonical state — so this hook keeps no
+ * merge logic of its own and a reload can never disagree with the server.
+ * The stream is attached only while the panel is open: a side question is a
+ * deliberate action, not background traffic.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import type { AgentImage, BtwState, StreamTransport } from '@/shared/types';
+import { BtwRequestError, abortBtwQuestion, askBtwQuestion, connectBtwStream, deleteBtwTopic, fetchBtwState, promoteBtwTopic } from '@/shared/lib/chat/btw/client';
+import type { StreamConnection } from '@/shared/lib/chat/omp/transport';
+
+/** Images the side session accepts, already read as base64. */
+export type BtwImage = AgentImage;
+
+/** The turn streaming right now; `text` accumulates its deltas. */
+export interface BtwLiveAnswer {
+  topicId: string;
+  turnIndex: number;
+  text: string;
+}
+
+export interface BtwSessionHandle {
+  state: BtwState | null;
+  live: BtwLiveAnswer | null;
+  error: string | null;
+  /** A command is in flight — the panel disables its actions meanwhile. */
+  busy: boolean;
+  /** Resolves with the canonical state the command produced, or null when it
+   *  was refused (the reason is then in `error`). */
+  ask: (question: string, images?: BtwImage[], topicId?: string) => Promise<BtwState | null>;
+  abort: (topicId: string) => Promise<void>;
+  /** Returns the new session id to open, or null when it was refused. */
+  promote: (topicId: string) => Promise<string | null>;
+  remove: (topicId: string) => Promise<void>;
+  clearError: () => void;
+}
+
+export interface BtwSessionOptions {
+  /** Attach the frame stream (the panel is open). */
+  enabled: boolean;
+  transport: StreamTransport;
+}
+
+export function useBtwSession(sessionId: string | null, options: BtwSessionOptions): BtwSessionHandle {
+  const [state, setState] = useState<BtwState | null>(null);
+  const [live, setLive] = useState<BtwLiveAnswer | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const { enabled, transport } = options;
+
+  // Commands must not be bound to the render that produced them: `/btw <q>`
+  // asks from the same tick that opens the form, before the stream attached and
+  // before this hook re-rendered with a session — a captured `sessionId` there
+  // would be null and the question would silently go nowhere.
+  const sessionIdRef = useRef(sessionId);
+  sessionIdRef.current = sessionId;
+
+  useEffect(() => {
+    if (!enabled || !sessionId) return;
+
+    const connection: StreamConnection = connectBtwStream(sessionId, transport, {
+      onOpen: () => {},
+      onFrame: (frame) => {
+        switch (frame.type) {
+          case 'btw_state':
+            setState(frame.state);
+            // A settled turn's text is in the snapshot now; holding the live
+            // buffer any longer would keep painting the partial answer.
+            setLive((current) => {
+              if (!current) return null;
+              const topic = frame.state.topics.find((candidate) => candidate.id === current.topicId);
+              const turn = topic?.turns.find((candidate) => candidate.index === current.turnIndex);
+              return turn && turn.status === 'running' ? current : null;
+            });
+            break;
+          case 'btw_delta':
+            setLive((current) =>
+              current && current.topicId === frame.topicId && current.turnIndex === frame.turnIndex
+                ? { ...current, text: current.text + frame.text }
+                : { topicId: frame.topicId, turnIndex: frame.turnIndex, text: frame.text },
+            );
+            break;
+          case 'btw_error':
+            setError(frame.message);
+            break;
+          default:
+            break;
+        }
+      },
+      onClose: () => {},
+    });
+
+    void fetchBtwState(sessionId)
+      .then(setState)
+      .catch((cause: unknown) => setError(cause instanceof Error ? cause.message : String(cause)));
+
+    return () => connection.close();
+  }, [enabled, sessionId, transport]);
+
+  const run = useCallback(
+    async (operation: (id: string) => Promise<BtwState>): Promise<BtwState | null> => {
+      const id = sessionIdRef.current;
+      if (!id) return null;
+      setBusy(true);
+      try {
+        const next = await operation(id);
+        setState(next);
+        return next;
+      } catch (cause) {
+        setError(cause instanceof BtwRequestError || cause instanceof Error ? cause.message : String(cause));
+        return null;
+      } finally {
+        setBusy(false);
+      }
+    },
+    [],
+  );
+
+  const ask = useCallback(
+    async (question: string, images?: BtwImage[], topicId?: string): Promise<BtwState | null> => {
+      setError(null);
+      const next = await run((id) => askBtwQuestion(id, { question, images, topicId }));
+      setLive(null);
+      if (next && !next.runningTopicId) {
+        setError('The side question was accepted but did not start running.');
+      }
+      return next;
+    },
+    [run],
+  );
+
+  const abort = useCallback(
+    async (topicId: string) => {
+      setError(null);
+      await run((id) => abortBtwQuestion(id, topicId));
+    },
+    [run],
+  );
+
+  const remove = useCallback(
+    async (topicId: string) => {
+      setError(null);
+      await run((id) => deleteBtwTopic(id, topicId));
+    },
+    [run],
+  );
+
+  const promote = useCallback(
+    async (topicId: string): Promise<string | null> => {
+      const id = sessionIdRef.current;
+      if (!id) return null;
+      setError(null);
+      setBusy(true);
+      try {
+        const created = await promoteBtwTopic(id, topicId);
+        return created.sessionId;
+      } catch (cause) {
+        setError(cause instanceof BtwRequestError || cause instanceof Error ? cause.message : String(cause));
+        return null;
+      } finally {
+        setBusy(false);
+      }
+    },
+    [],
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { state, live, error, busy, ask, abort, promote, remove, clearError };
+}

package/src/client/hooks/chat/btw/intercept.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `/btw [question]` typed into the main composer is the side-question entry
+ * point, not chat text: the panel owns the token (omp's `/btw` is TUI-only, so
+ * nothing downstream would understand it). This module is the whole
+ * interception — recognize the command, carry the composer's images across as
+ * provider payloads, and hand the question to the panel over `omp:btw`.
+ *
+ * It lives beside the rest of the client-side btw state (`hooks/chat/btw/`)
+ * rather than in the send handler: the attachment read goes through the shared
+ * accessors, because `Attachment.file` is absent on every replayed attachment.
+ */
+
+import type { Attachment } from '@/shared/types';
+import { attachmentImage } from '@/shared/lib/chat/attachments';
+
+/** A bare `/btw` opens the form on the current history; anything after it is
+ *  the first question. Case-insensitive, because omp's command tokens are. */
+const BTW_COMMAND_RE = /^\/btw(?:\s+([\s\S]*))?$/i;
+
+/**
+ * Hand a `/btw` draft to the side-question panel. Returns false when the text
+ * is not a btw command, so the caller keeps its normal send path.
+ */
+export function dispatchBtwCommand(text: string, attachments: Attachment[]): boolean {
+  const match = BTW_COMMAND_RE.exec(text);
+  if (!match) return false;
+
+  const images = attachments
+    .map((attachment) => attachmentImage(attachment))
+    .filter((image): image is NonNullable<typeof image> => image !== null);
+
+  window.dispatchEvent(
+    new CustomEvent('omp:btw', {
+      detail: { question: match[1]?.trim() ?? '', ...(images.length ? { images } : {}) },
+    }),
+  );
+  return true;
+}