ompchamber 0.8.0 → 1.1.0

package/src/client/hooks/chat/timeline/deferred-model.test.ts

@@ -0,0 +1,219 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A composer model/thinking pick made while a turn is streaming must not reach
+ * the live session: omp applies `set_model` to the RUNNING turn, so pushing it
+ * immediately re-targets the answer in flight (verified against omp's RPC
+ * handler and by driving a live session — one run answered its first turn on
+ * the old model and its next turns on the new one).
+ *
+ * The pick is held and pushed right before the next prompt instead. These run
+ * against a real DOM (happy-dom) because the hooks are Preact hooks: the
+ * modules below are imported inside `beforeAll`, after those globals exist,
+ * since Preact binds its environment at evaluation time.
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { useChatTimelineActions as UseChatTimelineActions, ChatTimelineActionsResult } from '@/client/hooks/chat/timeline/actions';
+import type { ComposerModelPick, DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
+import { flushDeferredPick } from '@/client/hooks/chat/timeline/deferred-model';
+import type { OmpAgentHandle } from '@/shared/types';
+
+let useChatTimelineActions: typeof UseChatTimelineActions;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+let container: HTMLElement;
+
+interface Harness {
+  calls: string[];
+  deferred: { current: ComposerModelPick | null };
+  actions: ChatTimelineActionsResult;
+}
+
+/** A recording agent handle plus the calls it received. */
+function makeAgent() {
+  const calls: string[] = [];
+  const agent = {
+    setModel: async (provider: string, modelId: string) => { calls.push(`set_model:${provider}/${modelId}`); },
+    setThinkingLevel: async (level: string) => { calls.push(`set_thinking_level:${level}`); },
+  } as unknown as OmpAgentHandle;
+  return { calls, agent };
+}
+
+/** Mounts the real hook and records every model/thinking RPC it pushes. */
+async function mountActions(isGenerating: boolean, stashed: ComposerModelPick | null): Promise<Harness> {
+  const deferred: { current: ComposerModelPick | null } = { current: stashed };
+  const { calls, agent } = makeAgent();
+
+  const captured: ChatTimelineActionsResult[] = [];
+  const Probe = () => {
+    captured.push(useChatTimelineActions({
+      inputValue: '',
+      setInputValue: () => {},
+      setInputAttachments: () => {},
+      isGenerating,
+      isOmpSession: true,
+      sessionId: '01a0ca36-f3be-7252-a95c-3d45d180c539',
+      appSettings: {},
+      messageQueue: [],
+      enqueueMessage: () => {},
+      removeMessage: () => {},
+      executeSend: async () => {},
+      steerOmpAgent: async () => {},
+      ompAgent: agent,
+      abortControllerRef: { current: null },
+      setGenerating: () => {},
+      stopHoldRef: { current: false },
+      persistMessages: () => {},
+      setLocalMessages: () => {},
+      pendingComposerModelRef: { current: null },
+      pendingThinkingLevelRef: { current: null },
+      composerModelRef: { current: null },
+      deferredComposerPickRef: deferred,
+      accessModeRef: { current: 'yolo' },
+      setSearchParams: () => {},
+    }));
+    return null;
+  };
+  await act(async () => {
+    render(h(Probe, {}), container);
+  });
+  // The handlers fire-and-forget their RPC, so let the microtask chain settle.
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+  return { calls, deferred, actions: captured[captured.length - 1] };
+}
+
+/** The DOM surface this file installs for Preact to render into. */
+function domGlobals(win: Window): Record<string, unknown> {
+  return {
+    window: win,
+    document: win.document,
+    navigator: win.navigator,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+  };
+}
+
+const installed: Record<string, unknown> = {};
+const displaced: Record<string, unknown> = {};
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  for (const [key, value] of Object.entries(domGlobals(win))) {
+    displaced[key] = (globalThis as Record<string, unknown>)[key];
+    installed[key] = value;
+    (globalThis as Record<string, unknown>)[key] = value;
+  }
+  ({ useChatTimelineActions } = await import('@/client/hooks/chat/timeline/actions'));
+  ({ h, render } = await import('preact'));
+  ({ act } = await import('preact/test-utils'));
+});
+
+// Every test file shares one process, so the globals go back the way they were.
+afterAll(() => {
+  for (const key of Object.keys(installed)) {
+    if (displaced[key] === undefined) delete (globalThis as Record<string, unknown>)[key];
+    else (globalThis as Record<string, unknown>)[key] = displaced[key];
+  }
+});
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+describe('composer model/thinking picks during a stream', () => {
+  test('a mid-stream model pick sends no RPC and is stashed', async () => {
+    const { calls, deferred, actions } = await mountActions(true, null);
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toEqual({ provider: 'kenari', modelId: 'deepseek-v4-pro' });
+  });
+
+  test('a mid-stream thinking pick sends no RPC and is stashed', async () => {
+    const { calls, deferred, actions } = await mountActions(true, null);
+    actions.handleThinkingLevelChange('high');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toEqual({ thinkingLevel: 'high' });
+  });
+
+  test('model then thinking mid-stream both survive to the next prompt', async () => {
+    const { calls, deferred, actions } = await mountActions(true, null);
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+    actions.handleThinkingLevelChange('max');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toEqual({ provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max' });
+  });
+
+  test('an idle pick reaches the session immediately', async () => {
+    const { calls, deferred, actions } = await mountActions(false, null);
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+    actions.handleThinkingLevelChange('high');
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro', 'set_thinking_level:high']);
+    expect(deferred.current).toBeNull();
+  });
+
+  test('an idle model pick leaves a stashed thinking level pending', async () => {
+    const { calls, deferred, actions } = await mountActions(false, { thinkingLevel: 'high' });
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    // The level was never applied here, so it must still wait for the next
+    // prompt rather than being dropped or pushed now.
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro']);
+    expect(deferred.current).toEqual({ thinkingLevel: 'high' });
+  });
+
+  test("'auto' thinking is never pushed onto the live session", async () => {
+    const { calls, deferred, actions } = await mountActions(false, null);
+    actions.handleThinkingLevelChange('auto');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toBeNull();
+  });
+});
+
+describe('flushing a pick onto the session', () => {
+  test('pushes the stashed model and thinking level, then clears the slot', async () => {
+    const { calls, agent } = makeAgent();
+    const store: DeferredModelStore = { current: { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max' } };
+
+    await flushDeferredPick(agent, store);
+
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro', 'set_thinking_level:max']);
+    expect(store.current).toBeNull();
+  });
+
+  test("a stashed 'auto' level is not pushed as a concrete level", async () => {
+    const { calls, agent } = makeAgent();
+    const store: DeferredModelStore = { current: { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'auto' } };
+
+    await flushDeferredPick(agent, store);
+
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro']);
+    expect(store.current).toBeNull();
+  });
+
+  test('flushing an empty slot sends nothing', async () => {
+    const { calls, agent } = makeAgent();
+    const store: DeferredModelStore = { current: null };
+
+    await flushDeferredPick(agent, store);
+
+    expect(calls).toEqual([]);
+  });
+});

package/src/client/hooks/chat/timeline/deferred-model.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Composer model/thinking picks that must NOT reach the live session yet.
+ *
+ * omp applies `set_model` / `set_thinking_level` to the RUNNING turn: the next
+ * LLM call inside the stream (the one after a tool result) goes out on the new
+ * model, so a pick made while an answer streams visibly re-targets that answer
+ * mid-flight. A composer pick is intent for the NEXT prompt, so while a turn is
+ * running it is stashed here and pushed to the session right before the next
+ * prompt the composer starts (plain send, steer, or queued delivery).
+ *
+ * The slot holds only what has NOT reached the session yet, so a pick applied
+ * directly (idle composer) clears exactly the fields it applied — a stashed
+ * thinking level survives a later model change instead of being resurrected
+ * over it.
+ *
+ * Verified against omp's RPC handler: `set_model` resolves the model and calls
+ * the session's `setModel` immediately — nothing defers it to a turn boundary.
+ */
+
+import type { OmpAgentHandle } from '@/shared/types';
+
+/** Fields a composer pick can carry; each handler owns its own. */
+export interface ComposerModelPick {
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+}
+
+/** Mutable slot the timeline hook owns; the composer and send paths share it. */
+export interface DeferredModelStore {
+  current: ComposerModelPick | null;
+}
+
+/**
+ * Slot that never holds a pick, for composers with no stream to defer against
+ * (the New Chat modal): every guard reads it as "nothing pending", so their
+ * adoption behaviour stays exactly as it was.
+ */
+export const NO_PENDING_PICK: DeferredModelStore = { current: null };
+
+/** A pick that names a model must name both halves of it. */
+function hasModel(pick: ComposerModelPick): pick is ComposerModelPick & { provider: string; modelId: string } {
+  return Boolean(pick.provider && pick.modelId);
+}
+
+/**
+ * Record a pick made while a turn is streaming. Merged over the previous stash
+ * so a model pick and a later thinking pick both survive to the next prompt.
+ */
+export function stashComposerPick(store: DeferredModelStore, pick: ComposerModelPick): void {
+  store.current = { ...store.current, ...pick };
+}
+
+/**
+ * Drop the fields a pick just applied directly, keeping any still-pending ones.
+ * Without this, a stashed pick would be flushed over the newer selection on the
+ * next send and silently revert the user's latest choice.
+ */
+export function consumeComposerPick(store: DeferredModelStore, pick: ComposerModelPick): void {
+  const pending = store.current;
+  if (!pending) return;
+  const next: ComposerModelPick = { ...pending };
+  if (pick.provider || pick.modelId) {
+    delete next.provider;
+    delete next.modelId;
+  }
+  if (pick.thinkingLevel) delete next.thinkingLevel;
+  store.current = next.provider || next.modelId || next.thinkingLevel ? next : null;
+}
+
+/**
+ * Push a pick onto the live session. `thinkingLevel: 'auto'` means "leave omp's
+ * level alone" — the same rule the send path applies — so it is skipped rather
+ * than translated into a concrete level.
+ */
+export async function applyComposerPick(agent: OmpAgentHandle, pick: ComposerModelPick): Promise<void> {
+  if (hasModel(pick)) await agent.setModel(pick.provider, pick.modelId);
+  if (pick.thinkingLevel && pick.thinkingLevel !== 'auto') await agent.setThinkingLevel(pick.thinkingLevel);
+}
+
+/** Push the stashed pick (if any) onto the session and clear the slot. */
+export async function flushDeferredPick(agent: OmpAgentHandle, store: DeferredModelStore): Promise<void> {
+  const pick = store.current;
+  if (!pick) return;
+  store.current = null;
+  await applyComposerPick(agent, pick);
+}

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

@@ -8,6 +8,7 @@ import { useChatTimelineScroll } from '@/client/hooks/chat/timeline/scroll';
 import { useTimelineAutoScroll } from '@/client/hooks/chat/timeline/auto-scroll';
 import { useChatTimelineActions } from '@/client/hooks/chat/timeline/actions';
 import { useChatTimelineSend } from '@/client/hooks/chat/timeline/send';
+import type { ComposerModelPick } from '@/client/hooks/chat/timeline/deferred-model';
 import { useSessionLoad } from '@/client/hooks/chat/timeline/session-load';
 import { useBrowserPageContextInsert } from '@/client/hooks/chat/timeline/browser-context';
 import { cancelStreamingCoalescer, createOmpAgentCallbacks } from '@/shared/lib/chat/timeline/omp-callbacks';
@@ -148,6 +149,15 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
   // Live mirror of the composer's model/thinking pick: the enqueue path
   // snapshots it onto queued items so auto-delivery replays those settings.
   const composerModelRef = useRef<{ provider: string; modelId: string; thinkingLevel: string } | null>(null);
+  // Picks made WHILE a turn streams: held here so they cannot re-target the
+  // answer in flight (omp applies set_model to the running turn), and pushed
+  // onto the session right before the next prompt.
+  const deferredComposerPickRef = useRef<ComposerModelPick | null>(null);
+  // A stashed pick belongs to ONE session's next prompt: carrying it across a
+  // switch would silently re-target the session the user just opened.
+  useEffect(() => {
+    deferredComposerPickRef.current = null;
+  }, [sessionId]);
 
   // Access-control mode is a global, persisted user preference (unlike the
   // per-session model/thinking picks): it hydrates from appSettings at first
@@ -177,10 +187,11 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
 
   const {
     messageQueue,
-    setMessageQueue,
+    enqueueMessage,
+    removeMessage,
+    reorderMessages,
     steeringQueue,
     setSteeringQueue,
-    removeDeliveredFromQueue,
   } = useChatTimelineQueue(sessionId);
   const {
     pending: extensionDialogs,
@@ -190,7 +201,6 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
   } = useExtensionDialogQueue(sessionId);
 
   const ompAgent = useOmpAgent(isOmpSession ? sessionId : null, createOmpAgentCallbacks({
-    removeDeliveredFromQueue,
     setGenerating,
     setGeneratingVerb,
     scrollToBottom,
@@ -229,28 +239,18 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     seedSession,
     pendingComposerModelRef,
     pendingThinkingLevelRef,
-    composerModelRef,
+    deferredComposerPickRef,
     accessModeRef,
     abortControllerRef,
     setInputValue,
     setSearchParams,
   });
 
-  // Auto-process queue: when the run ends (or was never active), deliver the
-  // head item. Both modes queue client-side now — omp sends it as a normal
-  // prompt via executeSend (which routes to the omp bridge); the mock path
-  // streams the same way. A user Stop arms `stopHoldRef`: the run ends but the
-  // queue stays put (stop-all semantics — the toast offers Send now); the next
-  // explicit send disarms it.
-  useEffect(() => {
-    if (stopHoldRef.current) return;
-    if (!isGenerating && messageQueue.length > 0) {
-      const nextMessage = messageQueue[0];
-      setMessageQueue(q => q.slice(1));
-      // The queued snapshot re-applies model/thinking/access before the prompt.
-      executeSend(nextMessage.text, nextMessage.attachments, { model: nextMessage.model });
-    }
-  }, [isGenerating, messageQueue, executeSend, setMessageQueue]);
+  // Queue auto-delivery moved server-side: the wrapper's terminal `agent_end`
+  // schedules the next queued prompt (`lib/queue/delivery.server.ts`), with a
+  // transactional head claim so no reload/tab race can double-send or wipe the
+  // table. The client panel is a view; the mount nudge lives in the queue
+  // hook. `stopHoldRef` remains only for the mock path below.
 
   const {
     handleSend,
@@ -271,7 +271,8 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     sessionId,
     appSettings,
     messageQueue,
-    setMessageQueue,
+    enqueueMessage,
+    removeMessage,
     executeSend,
     steerOmpAgent,
     ompAgent,
@@ -283,6 +284,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     pendingComposerModelRef,
     pendingThinkingLevelRef,
     composerModelRef,
+    deferredComposerPickRef,
     accessModeRef,
     setSearchParams,
   });
@@ -303,7 +305,8 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     loadOlder,
     generatingVerb,
     messageQueue,
-    setMessageQueue,
+    removeMessage,
+    reorderMessages,
     steeringQueue,
     setSteeringQueue,
     inputValue,
@@ -329,6 +332,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     accessMode,
     handleAccessModeChange,
     composerModelRef,
+    deferredComposerPickRef,
     extensionDialogs,
     resolveExtensionDialog,
     respondToExtensionUi: ompAgent.respondToExtensionUi,

package/src/client/hooks/chat/timeline/queue.ts

@@ -4,84 +4,148 @@
  */
 
 /**
- * Follow-up + steering queue state for the chamber chat, backed by the SQLite
- * `queued_messages` table via /api/sessions/:id/queue (one row per item with a
- * model snapshot, so auto-delivery replays the settings the item was queued
- * with).
+ * Client view of the follow-up queue (SQLite `queued_messages`, owned by the
+ * server). The panel is a VIEW: mutations go through the per-item endpoints
+ * (`POST/PATCH/DELETE /api/sessions/:id/queue[/:itemId]`) and every response
+ * carries the canonical queue, which replaces local state wholesale. The old
+ * client-side replace-on-write mirror is gone — it was what let a reload
+ * hydrating over an empty state wipe the table, and a session switch PUT one
+ * session's list into another's rows.
  *
- * The client panel stays the source of truth while the session is open: every
- * mutation updates React state first, then PUTs the full remaining list to the
- * route (replace-on-write keeps ids stable for reorder/edit/delete). The queue
- * hydrates from the table on mount — a page reload mid-stream restores it.
- * Steering mirrors live in the session-state blob under a separate key.
- *
- * Kept out of useChatTimeline so that hook stays under the size ceiling.
+ * Steering still mirrors into the per-session session-state blob (client-only
+ * by design: an interrupt-and-reply is only meaningful while a client watches
+ * the run).
  */
 
-import type { SetStateAction } from 'preact/compat';
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 import type { QueuedMessage } from '@/shared/types';
 import { useSessionState } from '@/client/hooks/workspace/session-state';
 
 const STEERING_STATE_KEY = 'chat.steeringQueue';
 
+function queueUrl(sessionId: string): string {
+  return `/api/sessions/${encodeURIComponent(sessionId)}/queue`;
+}
+
+async function readQueueResponse(res: Response): Promise<QueuedMessage[] | null> {
+  if (!res.ok) return null;
+  const data = (await res.json().catch(() => null)) as { queue?: unknown } | null;
+  return Array.isArray(data?.queue) ? (data.queue as QueuedMessage[]) : null;
+}
+
 export interface ChatTimelineQueueResult {
   messageQueue: QueuedMessage[];
-  setMessageQueue: (updater: SetStateAction<QueuedMessage[]>) => void;
+  /** Append one item; local state updates optimistically, then reconciles
+   *  from the canonical response. No-op without a session. */
+  enqueueMessage: (item: Omit<QueuedMessage, 'id'>) => void;
+  /** Edit one item's text (PATCH). */
+  editMessageText: (id: string, text: string) => void;
+  /** Remove one item by id (DELETE). */
+  removeMessage: (id: string) => void;
+  /** Reorder the queue to these ids (PUT, drag-and-drop). */
+  reorderMessages: (orderedIds: string[]) => void;
+  /** Replace the local list from a fetch (mount hydration, manual refresh). */
+  refresh: () => void;
+  /** Client-only steering mirror (session-state blob). */
   steeringQueue: QueuedMessage[];
-  setSteeringQueue: (updater: SetStateAction<QueuedMessage[]>) => void;
-  /** Drop an exactly-matching text from whichever mirror queue holds it. */
-  removeDeliveredFromQueue: (text: string) => void;
+  setSteeringQueue: (value: QueuedMessage[] | ((prev: QueuedMessage[]) => QueuedMessage[])) => void;
 }
 
 export function useChatTimelineQueue(sessionId: string | null): ChatTimelineQueueResult {
   const [messageQueue, setMessageQueueState] = useState<QueuedMessage[]>([]);
   const [steeringQueue, setSteeringQueue] = useSessionState<QueuedMessage[]>(STEERING_STATE_KEY, []);
 
-  // Hydrate from the table once per session. A generation-safe ref skips the
-  // stale-response race when the user switches sessions quickly.
+  // Hydrate from the table once per session, and re-read when the tab
+  // regains focus (a second tab may have claimed/delivered the head). A
+  // generation-safe ref skips the stale-response race on quick switches.
   const hydrateEpochRef = useRef(0);
-  useEffect(() => {
+  const cancelledRef = useRef(false);
+  const refresh = useCallback(() => {
     if (!sessionId) {
       setMessageQueueState([]);
       return;
     }
     const epoch = ++hydrateEpochRef.current;
-    let cancelled = false;
-    fetch(`/api/sessions/${encodeURIComponent(sessionId)}/queue`)
-      .then(res => (res.ok ? res.json() : { queue: [] }))
-      .then((data: { queue?: QueuedMessage[] }) => {
-        if (cancelled || hydrateEpochRef.current !== epoch) return;
-        setMessageQueueState(Array.isArray(data.queue) ? data.queue : []);
+    fetch(queueUrl(sessionId))
+      .then((res) => readQueueResponse(res))
+      .then((queue) => {
+        if (cancelledRef.current || hydrateEpochRef.current !== epoch) return;
+        setMessageQueueState(queue ?? []);
       })
       .catch(() => {});
-    return () => { cancelled = true; };
   }, [sessionId]);
+  useEffect(() => {
+    cancelledRef.current = false;
+    refresh();
+    const onFocus = () => refresh();
+    window.addEventListener('focus', onFocus);
+    return () => {
+      cancelledRef.current = true;
+      window.removeEventListener('focus', onFocus);
+    };
+  }, [refresh]);
 
-  // Replace-on-write mirror: every client mutation PUTs the full list so the
-  // table always matches the panel (order, edits, deletions included).
-  const mirrorQueue = useCallback((next: QueuedMessage[]) => {
+  // Mounted session with queued items: offer the server a delivery slot. The
+  // server-side claim makes this harmless when a run is active or another tab
+  // already took the head — this used to be the client auto-delivery effect,
+  // which fired into whatever session was open at the time.
+  useEffect(() => {
+    if (!sessionId || messageQueue.length === 0) return;
+    fetch(`${queueUrl(sessionId)}/deliver`, { method: 'POST' }).catch(() => {});
+  }, [sessionId, messageQueue.length > 0]);
+
+  const enqueueMessage = useCallback((item: Omit<QueuedMessage, 'id'>) => {
     if (!sessionId) return;
-    fetch(`/api/sessions/${encodeURIComponent(sessionId)}/queue`, {
-      method: 'PUT',
+    const optimistic: QueuedMessage = { ...item, id: `queue-${Date.now()}` };
+    setMessageQueueState((prev) => [...prev, optimistic]);
+    fetch(queueUrl(sessionId), {
+      method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ queue: next }),
-    }).catch(console.error);
+      body: JSON.stringify(item),
+    })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
   }, [sessionId]);
 
-  const setMessageQueue = useCallback((updater: SetStateAction<QueuedMessage[]>) => {
-    setMessageQueueState(prev => {
-      const next = typeof updater === 'function' ? updater(prev) : updater;
-      mirrorQueue(next);
-      return next;
-    });
-  }, [mirrorQueue]);
+  const editMessageText = useCallback((id: string, text: string) => {
+    if (!sessionId) return;
+    fetch(`${queueUrl(sessionId)}/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+    })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
+  }, [sessionId]);
+
+  const removeMessage = useCallback((id: string) => {
+    if (!sessionId) return;
+    // Optimistic removal, reconciled only on failure (404 = already claimed —
+    // the item is gone either way).
+    setMessageQueueState((prev) => prev.filter((i) => i.id !== id));
+    fetch(`${queueUrl(sessionId)}/${encodeURIComponent(id)}`, { method: 'DELETE' })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
+  }, [sessionId]);
 
-  const removeDeliveredFromQueue = useCallback((text: string) => {
-    const exact = (q: QueuedMessage[]) => q.some(i => i.text === text);
-    setSteeringQueue(q => (exact(q) ? q.filter(i => i.text !== text) : q));
-    setMessageQueue(q => (exact(q) ? q.filter(i => i.text !== text) : q));
-  }, [setSteeringQueue, setMessageQueue]);
+  const reorderMessages = useCallback((orderedIds: string[]) => {
+    if (!sessionId) return;
+    setMessageQueueState((prev) => {
+      const byId = new Map(prev.map((i) => [i.id, i]));
+      return orderedIds.map((id) => byId.get(id)).filter((i): i is QueuedMessage => Boolean(i));
+    });
+    fetch(queueUrl(sessionId), {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ orderedIds }),
+    })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
+  }, [sessionId]);
 
-  return { messageQueue, setMessageQueue, steeringQueue, setSteeringQueue, removeDeliveredFromQueue };
+  return { messageQueue, enqueueMessage, editMessageText, removeMessage, reorderMessages, refresh, steeringQueue, setSteeringQueue };
 }