@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/client/hooks/chat/omp/session-statuses.test.ts

@@ -0,0 +1,277 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The sidebar/navbar live-status cluster: `session-statuses` and `status`.
+ *
+ * These two small modules are the only wiring between a server-tracked run
+ * state and the pixels the user watches, so each case pins a way the UI could
+ * silently disagree with reality:
+ *
+ * - `isSessionStreaming` is the EXACT `streamStatus === 'stream'` test the
+ *   sidebar spinner and the timeline's generating indicator share; a second
+ *   tab or a background process must still light the spinner, while a stale
+ *   `finish`/`abort` badge must not.
+ * - `useSessionStatusAck` must POST exactly once per (session, status) so the
+ *   one-shot terminal check cannot flicker, and must never ack a live row.
+ * - `useAgentStreamStatus` seeds from the last published value so a navbar
+ *   mounted mid-run paints the current transport instead of waiting.
+ *
+ * The sidebar's own poll and throttle used to be pinned here; both are gone,
+ * replaced by the realtime socket's `sidebar:status` topic (see
+ * `session-list.test.ts`, which drives them through a real server).
+ *
+ * Rendered with `h()` against happy-dom, the way the other hook tests do.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, jest, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+
+import {
+  buildSidebarSessionStatus,
+  isChatRunning,
+  isSessionStreaming,
+  useSessionStatusAck,
+} from '@/client/hooks/chat/omp/session-statuses';
+import { useAgentStreamStatus, type AgentStreamStatus } from '@/client/hooks/chat/omp/status';
+import { realtimeClient, resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
+import { startRealtimeTestServer } from '@/test-support/realtime-server';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+import type { SessionItemData } from '@/shared/types';
+
+/** The runner's own fetch — `installFetch` replaces it for the whole process. */
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+const nativeFetch = Bun.fetch;
+
+let container: HTMLElement;
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+});
+
+
+
+afterEach(() => {
+  if (container) render(null, container);
+  container?.remove();
+  jest.useRealTimers();
+  // `installFetch` replaces the global for the WHOLE process; left in place it
+  // answers every later suite's requests with this file's `{deleted}` body
+  // (measured: `listPlugins` read `[]`, every live-listener probe read `null`).
+  globalThis.fetch = nativeFetch;
+  // The status store is module state too: a suite that asserts the pristine
+  // seed must not read this file's `sse` transition.
+});
+
+async function mount(vnode: Parameters<typeof render>[0]) {
+  container ??= document.body.appendChild(document.createElement('div'));
+  await act(async () => {
+    render(vnode, container as HTMLElement);
+  });
+}
+
+/** Drain the promise chain a stubbed `fetch` starts (no timers involved). */
+async function settle() {
+  await act(async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+/** One sidebar row, so every fixture below agrees on the item shape. */
+function session(id: number | string, streamStatus?: SessionItemData['streamStatus']): SessionItemData {
+  const item: SessionItemData = { id, folder_id: 1, title: `s-${id}` };
+  if (streamStatus !== undefined) item.streamStatus = streamStatus;
+  return item;
+}
+
+describe('buildSidebarSessionStatus', () => {
+  test('keys only sessions carrying a status, by stringified id', () => {
+    const map = buildSidebarSessionStatus([
+      { sessions: [session(7, 'stream'), session('abc', 'finish'), session(8)] },
+    ]);
+    expect(map).toEqual({ '7': 'stream', abc: 'finish' });
+  });
+
+  test('walks every folder and lets the last duplicate id win', () => {
+    const map = buildSidebarSessionStatus([
+      { sessions: [session(1, 'finish')] },
+      { sessions: [session(1, 'abort')] },
+      { sessions: undefined },
+    ]);
+    expect(map['1']).toBe('abort');
+  });
+});
+
+describe('isSessionStreaming', () => {
+  const statusMap = { a: 'stream', b: 'finish', c: 'abort', 4: 'stream' } as const;
+
+  test('is true only for the exact `stream` status, across id shapes', () => {
+    expect(isSessionStreaming(statusMap, 'a')).toBe(true);
+    expect(isSessionStreaming(statusMap, 4)).toBe(true);
+    expect(isSessionStreaming(statusMap, '4')).toBe(true);
+    expect(isSessionStreaming(statusMap, 'b')).toBe(false);
+    expect(isSessionStreaming(statusMap, 'c')).toBe(false);
+  });
+
+  test('is false for a session absent from the map', () => {
+    expect(isSessionStreaming(statusMap, 'missing')).toBe(false);
+    expect(isSessionStreaming({}, 'a')).toBe(false);
+  });
+
+  test('is false for a null/undefined selection (nothing is open yet)', () => {
+    expect(isSessionStreaming(statusMap, null)).toBe(false);
+    expect(isSessionStreaming(statusMap, undefined)).toBe(false);
+  });
+
+  test('is false when no status map has arrived', () => {
+    // The provider's map is `{}` before the first snapshot; a caller outside
+    // the provider gets the same shape. Neither may read as a live run.
+    expect(isSessionStreaming(null, 'a')).toBe(false);
+    expect(isSessionStreaming(undefined, 'a')).toBe(false);
+  });
+});
+
+/**
+ * The CHAT-level flag. One source is the point: the server's `stream` row, the
+ * same one the sidebar spinner reads. The only other term is a run the server
+ * cannot name yet (a pending `new-…` chat, no omp id until the spawn answers),
+ * and the caller supplies that — never a general optimistic mark.
+ */
+describe('isChatRunning', () => {
+  const statusMap = { a: 'stream', b: 'finish' } as const;
+
+  test('follows the server row, with no local flag involved', () => {
+    expect(isChatRunning(statusMap, 'a', false)).toBe(true);
+    expect(isChatRunning(statusMap, 'b', false)).toBe(false);
+    expect(isChatRunning({}, 'a', false)).toBe(false);
+  });
+
+  test('counts a run the server cannot name yet (a pending new-… chat)', () => {
+    // No row can exist for a session omp has not created, so the caller's
+    // pending term is the only thing that can report the spawn window.
+    expect(isChatRunning({}, 'new-1750000000000', true)).toBe(true);
+  });
+
+  test('never invents a run the server has already settled', () => {
+    // The pending term is for the spawn window only. With it false — which is
+    // what every real session passes — a terminal row is the answer, and the
+    // indicator cannot outlive the run.
+    expect(isChatRunning(statusMap, 'b', false)).toBe(false);
+    expect(isChatRunning({ b: 'finish' }, 'b', false)).toBe(false);
+    expect(isChatRunning(null, 'a', false)).toBe(false);
+  });
+});
+
+interface AckApi {
+  statusMap: Record<string, 'stream' | 'finish' | 'abort'>;
+  activeSessionId: string | null;
+  skip?: (id: number | string) => boolean;
+}
+
+describe('useSessionStatusAck', () => {
+  const calls: Array<{ url: string; method: string }> = [];
+  let revalidated = 0;
+  let deleted = true;
+
+  function installFetch() {
+    calls.length = 0;
+    revalidated = 0;
+    deleted = true;
+    (globalThis as unknown as Record<string, unknown>).fetch = async (input: unknown, init?: { method?: string }) => {
+      calls.push({ url: String(input), method: init?.method ?? 'GET' });
+      return new Response(JSON.stringify({ deleted }), { status: 200, headers: { 'content-type': 'application/json' } });
+    };
+  }
+
+  function Probe({ api }: { api: AckApi }) {
+    useSessionStatusAck(api.statusMap, api.activeSessionId, () => { revalidated += 1; }, api.skip);
+    return null;
+  }
+
+  test('acks a terminal badge for the open session exactly once, then revalidates', async () => {
+    installFetch();
+    const api: AckApi = { statusMap: { s1: 'finish' }, activeSessionId: 's1' };
+    await mount(h(Probe, { api }));
+    await settle();
+
+    expect(calls).toEqual([{ url: '/api/sessions/s1/stream-seen', method: 'POST' }]);
+    expect(revalidated).toBe(1);
+
+    // Re-render with an identical map: the effect must not re-POST.
+    await act(async () => { render(h(Probe, { api }), container as HTMLElement); });
+    await settle();
+    expect(calls.length).toBe(1);
+  });
+
+  test('never acks a live `stream` row', async () => {
+    installFetch();
+    await mount(h(Probe, { api: { statusMap: { s1: 'stream' }, activeSessionId: 's1' } }));
+    await settle();
+    expect(calls.length).toBe(0);
+  });
+
+  test('honours skip() so a click-acked badge is not double-POSTed', async () => {
+    installFetch();
+    await mount(h(Probe, { api: { statusMap: { s1: 'abort' }, activeSessionId: 's1', skip: () => true } }));
+    await settle();
+    expect(calls.length).toBe(0);
+    expect(revalidated).toBe(0);
+  });
+
+  test('does nothing with no open session', async () => {
+    installFetch();
+    await mount(h(Probe, { api: { statusMap: { s1: 'finish' }, activeSessionId: null } }));
+    await settle();
+    expect(calls.length).toBe(0);
+  });
+});
+
+describe('useAgentStreamStatus', () => {
+  function StatusProbe({ seen }: { seen: { current: AgentStreamStatus | null } }) {
+    seen.current = useAgentStreamStatus();
+    return null;
+  }
+
+  test('reports the shared channel, not a per-session transport', async () => {
+    // The status now describes the ONE realtime socket, so it is driven by the
+    // client itself. A real listener is what makes the transition observable:
+    // the value flips when the handshake completes, which is event-loop work.
+    const server = await startRealtimeTestServer(new Map<string, TopicResolver>([
+      ['sidebar', async () => ({ folders: [], isMock: false })],
+    ]));
+    // The client builds its socket URL from `window.location`, so the DOM must
+    // sit on the listener's origin — this file's `beforeAll` window is a bare
+    // `http://localhost`, which would dial port 80 and never connect.
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      writable: true,
+      value: new Window({ url: `http://127.0.0.1:${server.port}` }),
+    });
+    (globalThis as unknown as Record<string, unknown>).WebSocket = pristineWebSocket;
+    const seen: { current: AgentStreamStatus | null } = { current: null };
+    await mount(h(StatusProbe, { seen }));
+    expect(seen.current?.connected).toBe(false);
+
+    // Subscribing is what dials; the harness waits on the client's own value.
+    const stop = realtimeClient.subscribe('sidebar', () => {});
+    await server.waitForTopic('sidebar', (value) => value !== null);
+    await act(async () => { await settle(); });
+    expect(seen.current?.connected).toBe(true);
+
+    stop();
+    server.stop();
+    resetRealtimeClient();
+  });
+});
+
+afterAll(() => {
+  globalThis.fetch = nativeFetch;
+  restoreDomGlobals();
+});

package/src/client/hooks/chat/omp/session-statuses.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sidebar session stream status — server-authoritative via SQLite.
+ *
+ * The status rides the realtime `sidebar:status` topic, so the spinner and
+ * check update with the list they belong to. Opening a session acknowledges the one-shot terminal badge
+ * (`finish` / `abort` / `error`) via POST /api/sessions/:id/stream-seen so
+ * the check shows exactly once, then disappears from the rendered list.
+ *
+ * A run in flight is reported by ONE source: the `stream` row the server writes
+ * at prompt dispatch (`session_stream_state`). There is deliberately no
+ * client-side optimistic mark — a second writer that the client owned the
+ * lifecycle of is exactly what left a spinner and a generating indicator
+ * turning after the run had ended (a mark armed under one session id and
+ * released under another is never released at all).
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+import type { SessionItemData } from '@/shared/types';
+
+export type SessionStreamStatus = NonNullable<SessionItemData['streamStatus']>;
+
+/** Derive { sessionId → status } from the loader-provided folders. */
+export function buildSidebarSessionStatus(
+  folders: { sessions?: SessionItemData[] }[],
+): Record<string, SessionStreamStatus> {
+  const map: Record<string, SessionStreamStatus> = {};
+  for (const folder of folders) {
+    for (const session of folder.sessions ?? []) {
+      if (session.streamStatus) map[String(session.id)] = session.streamStatus;
+    }
+  }
+  return map;
+}
+
+/**
+ * Whether the session item for `sessionId` currently draws the run spinner —
+ * the exact `status === 'stream'` test `SessionItem` / `SessionRow` render
+ * `Loader2` from.
+ *
+ * The chat timeline's generating indicator asks THIS, so the two surfaces
+ * cannot disagree about whether a run is in flight. The status row is
+ * server-authoritative and lives in the shared database, so it is the only
+ * condition that holds for a run this client did not start: a second tab, a
+ * second Kabmo instances, or a page that never attached to the session's
+ * event stream (`GET /api/agent/:id` answers `running: false` for a child
+ * owned by another process, so no `onResumeStream` fires here).
+ */
+export function isSessionStreaming(
+  statusMap: Record<string, SessionStreamStatus | undefined> | null | undefined,
+  sessionId: string | number | null | undefined,
+): boolean {
+  if (sessionId === null || sessionId === undefined) return false;
+  return statusMap?.[String(sessionId)] === 'stream';
+}
+
+/**
+ * Whether a CHAT has a run in flight — the one definition the docked
+ * generating indicator, the Stop button and the withheld run footer read.
+ *
+ * The server's `stream` row is the answer, exactly as it is for the sidebar
+ * spinner: one source, so the two surfaces cannot disagree. The single
+ * exception is a run the server cannot NAME yet — a pending `new-…` chat has no
+ * omp id until the spawn answers, so there is no row to carry and nothing on
+ * the server can report it. `pendingRun` covers exactly that window and is
+ * supplied by the caller, which is the only place that knows the id is still
+ * pending; it is never a general-purpose optimistic mark.
+ */
+export function isChatRunning(
+  statusMap: Record<string, SessionStreamStatus | undefined> | null | undefined,
+  sessionId: string | number | null | undefined,
+  pendingRun: boolean,
+): boolean {
+  return pendingRun || isSessionStreaming(statusMap, sessionId);
+}
+
+/**
+ * Opening a session with a terminal badge acknowledges it on the server
+ * (one POST per session+status) so the check shows EXACTLY ONCE: the badge
+ * keeps rendering on this pass — stripping it here would suppress the paint
+ * entirely for an open session. Once the POST lands, a revalidate pulls
+ * loader data without the deleted row, dropping the check from the list.
+ *
+ * Click paths call `markSeen` (optimistic strip + ack) BEFORE the status map
+ * can even carry the badge; `skip` lets the caller suppress this effect for
+ * sessions the click already handled, so the two never double-POST.
+ */
+export function useSessionStatusAck(
+  statusMap: Record<string, SessionStreamStatus>,
+  activeSessionId: number | string | null,
+  revalidate: () => void,
+  skip?: (sessionId: number | string) => boolean,
+): void {
+  const activeId = activeSessionId === null ? null : String(activeSessionId);
+  const activeStatus = activeId !== null ? statusMap[activeId] : undefined;
+  // One POST per (session, status): between the ack and the revalidate that
+  // drops the row, identity changes in statusMap would re-fire the effect.
+  const ackedRef = useRef<string | null>(null);
+  const revalidateRef = useRef(revalidate);
+  revalidateRef.current = revalidate;
+  const skipRef = useRef(skip);
+  skipRef.current = skip;
+
+  useEffect(() => {
+    if (!activeStatus || activeStatus === 'stream') return;
+    if (skipRef.current?.(activeId as string)) return;
+    const ackKey = `${activeId}:${activeStatus}`;
+    if (ackedRef.current === ackKey) return;
+    ackedRef.current = ackKey;
+    // Stale-map guard: statusMap can lag a busy list by up to one fetch. If
+    // the badge was actually overwritten by a fresh `stream` (agent_start
+    // raced the sidebar refetch), the server now refuses to delete the row
+    // and reports deleted:false — treat the POST as void so the effect can
+    // re-ack the real terminal badge when the run later ends.
+    fetch(`/api/sessions/${encodeURIComponent(activeId as string)}/stream-seen`, { method: 'POST' })
+      .then((res) => res.json() as Promise<{ deleted?: boolean }>)
+      .then((body) => {
+        if (body.deleted === false) ackedRef.current = null;
+        revalidateRef.current();
+      })
+      .catch(() => {
+        ackedRef.current = null;
+      });
+  }, [activeId, activeStatus]);
+}

package/src/client/hooks/chat/omp/sidebar-overlay.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The sidebar's two CLIENT-side overlays, and nothing else.
+ *
+ * Neither of them is a run state. `stream` comes from the server's
+ * `session_stream_state` row alone (`sidebar:status` topic) — see
+ * `session-statuses.ts` for why a client-side mark was removed.
+ *
+ *   - the SEEN strip: a one-shot terminal badge (`finish`/`abort`) this mount
+ *     already acknowledged, hidden until the list refetches without it. It can
+ *     only ever REMOVE a status, never invent one.
+ *   - the TITLE hint: the text the user just sent, shown by the placeholder row
+ *     until omp's transcript scan can name the session (omp writes its file only
+ *     when the first assistant message settles, measured ~17s).
+ */
+
+import type { WorkspaceFolderData } from '@/shared/types';
+import { publishClientSignal } from '@/client/lib/signals';
+
+/** The title-hint signal name, for a consumer that subscribes. */
+export const SESSION_TITLE_HINT_SIGNAL = 'session-title-hint' as const;
+
+export interface SessionTitleHintDetail {
+  sessionId: string;
+  title: string;
+}
+
+/**
+ * Seed a session's sidebar row with the text the user just sent.
+ *
+ * The row's real title comes from omp's transcript scan, and for a new session
+ * that scan cannot see it yet: omp creates the session file only when the first
+ * assistant message settles (measured ~17s on a plain prompt, because its
+ * writes are buffered). Until then the sidebar's placeholder row is the only
+ * thing on screen, and it used to say `New Session - <timestamp>` for the whole
+ * first run — the operator's own words, which the client already has at send
+ * time, name the row far better than a clock.
+ *
+ * A hint, not a rename: the placeholder stops using it the moment omp's row
+ * exists, so nothing here can overwrite the title omp derived.
+ */
+export function setSessionTitleHint(sessionId: string, title: string): void {
+  const trimmed = title.trim();
+  if (!trimmed) return;
+  publishClientSignal(SESSION_TITLE_HINT_SIGNAL, { sessionId, title: trimmed });
+}
+
+/**
+ * Hide a terminal badge this mount already acked, so the check renders exactly
+ * once and disappears with the click instead of waiting for the refetch.
+ *
+ * A live `stream` row is never stripped: it is a run in flight, and the click's
+ * optimistic strip exists only for the one-shot badge. Applied BEFORE anything
+ * reads the list, so the ack effect cannot double-POST against a stale map.
+ */
+export function applySeenStrip(
+  folders: WorkspaceFolderData[],
+  seen: Set<string>,
+): WorkspaceFolderData[] {
+  if (seen.size === 0) return folders;
+  return folders.map((folder) => ({
+    ...folder,
+    sessions: (folder.sessions ?? []).map((session) => {
+      const key = String(session.id);
+      if (!seen.has(key) || !session.streamStatus || session.streamStatus === 'stream') return session;
+      return { ...session, streamStatus: undefined };
+    }),
+  }));
+}

package/src/client/hooks/chat/omp/status.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The navbar's view of the realtime channel's connection state. Kept as its own
+ * module path because the layout's props are typed against it; the value itself
+ * comes from the shared client.
+ */
+
+export { useAgentStreamStatus, type AgentStreamStatus } from '@/shared/lib/chat/omp/status';

package/src/client/hooks/chat/omp/stream-rpc.test.ts

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** The `useOmpAgent` RPC-command half of `stream.test.ts`: follow-ups,
+ * interrupts, model/thinking picks and dialog answers posted through the
+ * bridge. Split verbatim so both files stay under the repo's 350-line
+ * ceiling. */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { useRef } from 'preact/hooks';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+import { act } from 'preact/test-utils';
+import { useOmpAgent } from '@/client/hooks/chat/omp/index';
+
+import type { OmpAgentCallbacks, OmpAgentEvent, OmpAgentHandle } from '@/shared/types';
+
+
+
+let container: HTMLElement;
+
+/** Minimal WebSocket double: records instances and lets a test drive events. */
+class StubSocket {
+  static latest: StubSocket[] = [];
+  url: string;
+  closed = false;
+  onopen: (() => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onclose: (() => void) | null = null;
+  onerror: unknown = null;
+
+  constructor(url: string) {
+    this.url = url;
+    StubSocket.latest.push(this);
+  }
+
+  close() { this.closed = true; }
+  open() { this.onopen?.(); }
+  frame(data: OmpAgentEvent) { this.onmessage?.({ data: JSON.stringify(data) }); }
+  drop() { this.onclose?.(); }
+}
+
+class StubEventSource {
+  static latest: StubEventSource[] = [];
+  static CLOSED = 2;
+  static readonly instances: StubEventSource[] = StubEventSource.latest;
+  url: string;
+  readyState = 0;
+  closed = false;
+  onopen: (() => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onerror: (() => void) | null = null;
+
+  constructor(url: string) {
+    this.url = url;
+    StubEventSource.latest.push(this);
+  }
+
+  close() { this.closed = true; }
+  open() { this.readyState = 1; this.onopen?.(); }
+  frame(data: OmpAgentEvent) { this.onmessage?.({ data: JSON.stringify(data) }); }
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  // The RPC commands are exercised through stubs; the agent stream's own
+  // transport is covered by `stream.test.ts` against a real socket.
+  const target = globalThis as unknown as Record<string, unknown>;
+  target.WebSocket = StubSocket;
+  target.EventSource = StubEventSource;
+});
+
+afterEach(() => {
+  if (container) render(null, container);
+  container?.remove();
+  StubSocket.latest = [];
+  StubEventSource.latest = [];
+});
+
+function mount(vnode: Parameters<typeof render>[0]) {
+  container ??= document.body.appendChild(document.createElement('div'));
+  return act(async () => { render(vnode, container as HTMLElement); });
+}
+
+
+
+/** Mounts `useOmpAgentStream` with fresh refs and exposes its api + state. */
+interface StubCall { url: string; method: string; body: Record<string, unknown>; }
+
+function stubFetch(answers: Record<string, unknown>) {
+  const calls: StubCall[] = [];
+  (globalThis as unknown as Record<string, unknown>).fetch = async (input: unknown, init?: { method?: string; body?: string }) => {
+    const url = String(input);
+    calls.push({ url, method: init?.method ?? 'GET', body: init?.body ? JSON.parse(init.body) : {} });
+    const answer = answers[url];
+    if (answer === undefined) return new Response('{}', { status: 200 });
+    return new Response(JSON.stringify(answer), { status: 200, headers: { 'content-type': 'application/json' } });
+  };
+  return calls;
+}
+
+/** Mounts `useOmpAgent` and exposes the handle plus the refs it owns. */
+function mountAgent(sessionId: string | null, callbacks: OmpAgentCallbacks = {}) {
+  const seen: { handle: OmpAgentHandle | null } = { handle: null };
+
+  function Probe({ id }: { id: string | null }) {
+    seen.handle = useOmpAgent(id, callbacks, useRef(''));
+    return null;
+  }
+
+  return {
+    mount: () => mount(h(Probe, { id: sessionId })),
+    rerender: (id: string | null) => act(async () => { render(h(Probe, { id }), container as HTMLElement); }),
+    handle: () => seen.handle as OmpAgentHandle,
+  };
+}
+
+/** Flush the promise chain behind the mount-time GET probe. */
+async function settle() {
+  await act(async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+
+describe('useOmpAgent RPC commands', () => {
+  const SID = 'sess/1';
+  const ROUTE = `/api/agent/${encodeURIComponent(SID)}`;
+
+  test('steering posts `steer` (not abort_and_prompt) and reports the refusal', async () => {
+    const calls = stubFetch({ [ROUTE]: { success: true } });
+    const probe = mountAgent(SID);
+    await probe.mount();
+    await settle();
+
+    expect(await probe.handle().steerOmpRun('pivot')).toEqual({ ok: true, busy: false });
+    // `steer` delivers INTO the running turn. `abort_and_prompt` would cancel
+    // it — measured on omp 18.8.3: steer keeps one agent_start/agent_end pair
+    // for the run, abort_and_prompt produces two.
+    expect(calls.at(-1)?.body).toEqual({ type: 'steer', message: 'pivot' });
+
+    // A refusal resolves with the server's own reason instead of a bare false:
+    // the composer is already cleared, so the caller has to be able to say why.
+    stubFetch({ [ROUTE]: { error: 'The session is waiting on an approval dialog — answer or dismiss it first.' } });
+    const refused = await probe.handle().steerOmpRun('pivot');
+    expect(refused.ok).toBe(false);
+    expect(refused.error).toContain('approval dialog');
+    // A steer does not create a run boundary, so no interrupt guard is armed
+    // and none can be left swallowing a later agent_end.
+    expect(probe.handle().isGenerating).toBe(false);
+  });
+
+  test('model, thinking level and dialog answers post their RPC bodies', async () => {
+    const calls = stubFetch({ [ROUTE]: { success: true } });
+    const probe = mountAgent(SID);
+    await probe.mount();
+    await settle();
+
+    await probe.handle().setModel('anthropic', 'claude');
+    expect(calls.at(-1)?.body).toEqual({ type: 'set_model', provider: 'anthropic', modelId: 'claude' });
+
+    await probe.handle().setThinkingLevel('high');
+    expect(calls.at(-1)?.body).toEqual({ type: 'set_thinking_level', level: 'high' });
+
+    await probe.handle().respondToExtensionUi({ id: 'ui-7' } as never, { confirmed: true });
+    expect(calls.at(-1)?.body).toEqual({ type: 'extension_ui_response', id: 'ui-7', confirmed: true });
+  });
+
+  test('abort posts the stop command and drops the interrupt guard', async () => {
+    const calls = stubFetch({ [ROUTE]: { success: true } });
+    const probe = mountAgent(SID);
+    await probe.mount();
+    await settle();
+
+    await probe.handle().abort();
+    expect(calls.at(-1)?.body).toEqual({ type: 'abort' });
+    expect(probe.handle().isGenerating).toBe(false);
+  });
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});