ompchamber 1.0.0 → 1.2.0

package/src/server/lib/omp/session/reader.ts

@@ -15,8 +15,8 @@
  *   - cwd → repository root      → lib/omp/worktree.ts
  *   - managed projects registry  → lib/omp/project-registry.ts
  *
- * All reads are bounded (4 KiB prefix per session file), cached by mtime, and
- * never mutate the agent's files.
+ * All reads are bounded (a 4 KiB prefix plus a 16 KiB tail window per session
+ * file), cached by file mtime, and never mutate the agent's files.
  */
 
 import { listAllSessionInfos, type OmpSessionInfo } from '@/server/lib/omp/session/files';

package/src/server/lib/omp/session/subagent-presence.ts

@@ -12,10 +12,13 @@
  * megabytes, and doing that per session per poll dominated the endpoint's cost
  * (the dataset scan itself is cached; this probe was not).
  *
- * The roster can only change when the session file or its sibling artifacts
- * directory changes, so that (session mtime, sibling-dir mtime) pair is a
- * sufficient cache version. Both cost one stat — orders of magnitude cheaper
- * than the parse they gate.
+ * The roster can only change when the session file gains entries or its
+ * sibling artifacts directory changes, so that (last-entry timestamp,
+ * sibling-dir mtime) pair is a sufficient cache version. Both cost one stat —
+ * orders of magnitude cheaper than the parse they gate. The timestamp is the
+ * file's last ENTRY time, not its mtime: a title-slot rewrite bumps mtime
+ * without appending anything, and a spurious version bump would re-run the
+ * parse it exists to avoid.
  */
 
 import { promises as fs } from 'fs';
@@ -42,10 +45,10 @@ async function siblingDirMtimeMs(dir: string): Promise<number> {
 
 export async function sessionHasSubagents(
   sessionPath: string,
-  sessionModified: string,
+  sessionLastEntryAt: string,
 ): Promise<boolean> {
   const siblingDir = siblingDirForSession(sessionPath);
-  const version = `${sessionModified}:${await siblingDirMtimeMs(siblingDir)}`;
+  const version = `${sessionLastEntryAt}:${await siblingDirMtimeMs(siblingDir)}`;
 
   const cached = cache.get(sessionPath);
   if (cached && cached.version === version) return cached.hasSubagents;

package/src/server/lib/queue/delivery.server.test.ts

@@ -0,0 +1,260 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The follow-up queue must never wedge.
+ *
+ * A scheduled delivery whose timer never runs (a `bun --hot` module
+ * re-evaluation discards the pending closure; a wedged event loop drops the
+ * callback) used to poison the session permanently: the in-flight guard
+ * early-returned on the leftover entry, so no later trigger — another
+ * agent_end, a tab's mount nudge — could ever schedule again. The queue simply
+ * stopped draining, with no error anywhere. Observed live: a dev server whose
+ * `setTimeout` from request handlers had stopped firing left every queued
+ * follow-up stranded, while a freshly started server delivered the identical
+ * item correctly.
+ *
+ * The store is mocked so the contract under test is delivery's own: which RPCs
+ * a claimed item produces, and that a lost timer is superseded rather than
+ * allowed to wedge the session. Time is driven by fake timers, so nothing here
+ * waits on the wall clock.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, jest, mock, test } from 'bun:test';
+import type { QueuedMessage } from '@/shared/types/chat';
+import type { QueueDeliveryHost } from '@/server/lib/queue/delivery.server';
+
+/** In-memory stand-in for the SQLite-backed queue. */
+const queue = new Map<string, QueuedMessage[]>();
+
+mock.module('@/server/lib/queue/store.server', () => ({
+  claimHeadQueueItem: (sessionId: string): QueuedMessage | null => {
+    const items = queue.get(sessionId);
+    return items?.shift() ?? null;
+  },
+  requeueHeadQueueItem: async (sessionId: string, item: QueuedMessage): Promise<void> => {
+    const items = queue.get(sessionId) ?? [];
+    items.unshift(item);
+    queue.set(sessionId, items);
+  },
+}));
+
+const { scheduleQueueDelivery } = await import('@/server/lib/queue/delivery.server');
+
+const MODEL = { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max', accessMode: 'yolo' as const };
+
+function queueItem(text: string, model: QueuedMessage['model'] = MODEL): QueuedMessage {
+  return { id: `item-${text}`, text, attachments: [], model };
+}
+
+/** Records the RPCs a delivery pushes at the session. */
+function makeHost(sessionId: string) {
+  const sent: Record<string, unknown>[] = [];
+  const host: QueueDeliveryHost = {
+    sessionId,
+    isAlive: () => true,
+    isBusy: () => false,
+    send: async (command) => {
+      sent.push(command);
+      return {};
+    },
+  };
+  return { host, sent };
+}
+
+/** Let the delivery's promise chain settle without advancing the clock. */
+async function flush(): Promise<void> {
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+}
+
+let sessionId = '';
+let counter = 0;
+
+beforeEach(() => {
+  sessionId = `queue-test-${counter++}`;
+  queue.clear();
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+describe('queue delivery', () => {
+  test('delivers the head with the model snapshot it was queued with', async () => {
+    queue.set(sessionId, [queueItem('queued hello')]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([
+      { type: 'set_model', provider: 'kenari', modelId: 'deepseek-v4-pro' },
+      { type: 'set_thinking_level', level: 'max' },
+      { type: 'prompt', message: 'queued hello', accessMode: 'yolo' },
+    ]);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
+  test("an 'auto' thinking level is left to the session", async () => {
+    queue.set(sessionId, [queueItem('no level', { ...MODEL, thinkingLevel: 'auto' })]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([
+      { type: 'set_model', provider: 'kenari', modelId: 'deepseek-v4-pro' },
+      { type: 'prompt', message: 'no level', accessMode: 'yolo' },
+    ]);
+  });
+
+  test('an item with no model snapshot is sent without touching the model', async () => {
+    queue.set(sessionId, [queueItem('session model', null)]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([{ type: 'prompt', message: 'session model' }]);
+  });
+
+  test('a busy session holds the item instead of sending it', async () => {
+    queue.set(sessionId, [queueItem('held')]);
+    const { host, sent } = makeHost(sessionId);
+    host.isBusy = () => true;
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([]);
+    expect(queue.get(sessionId)?.length).toBe(1);
+  });
+
+  test('a failed dispatch returns the item to the head', async () => {
+    queue.set(sessionId, [queueItem('retry me')]);
+    const { host } = makeHost(sessionId);
+    host.send = async () => {
+      throw new Error('rpc down');
+    };
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(queue.get(sessionId)?.map((i) => i.text)).toEqual(['retry me']);
+  });
+
+  test('repeated triggers deliver the head exactly once', async () => {
+    queue.set(sessionId, [queueItem('once')]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    scheduleQueueDelivery(host);
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent.filter((c) => c.type === 'prompt').length).toBe(1);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
+  // Attachments reach the server as the persisted display fields only: the
+  // composer's `File` never survives the queue row's JSON round trip, and its
+  // image preview is a `blob:` object URL the server cannot read. These pin the
+  // fields the delivery must use instead — `dataBase64` for the bytes, `type`
+  // for the media type, `content` for an inline-able text file.
+  test('a queued image rides its persisted base64 payload', async () => {
+    const item = queueItem('with image', null);
+    item.attachments = [
+      { id: 'i', name: 'shot.png', type: 'image/png', size: 4, preview: 'blob:http://x/1', dataBase64: 'iVBORw0KGgo=' },
+    ] as QueuedMessage['attachments'];
+    queue.set(sessionId, [item]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([
+      {
+        type: 'prompt',
+        message: 'with image',
+        images: [{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' }],
+      },
+    ]);
+  });
+
+  test('a queued text file is inlined into the delivered prompt', async () => {
+    const item = queueItem('review this', null);
+    item.attachments = [
+      { id: 't', name: 'notes.md', type: 'text/markdown', size: 5, preview: '', content: '# hi' },
+    ] as QueuedMessage['attachments'];
+    queue.set(sessionId, [item]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    const prompt = sent.find((c) => c.type === 'prompt');
+    expect(prompt?.message).toBe('review this\n\nAttached file: notes.md\n```markdown\n# hi\n```');
+  });
+
+  test('an attachment without a payload is not sent as a blank image', async () => {
+    const item = queueItem('no payload', null);
+    item.attachments = [
+      { id: 'i', name: 'broken.png', type: 'image/png', size: 4, preview: 'blob:http://x/1', dataBase64: '' },
+    ] as QueuedMessage['attachments'];
+    queue.set(sessionId, [item]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([{ type: 'prompt', message: 'no payload' }]);
+  });
+
+  test('a lost timer delays the queue instead of wedging it', async () => {
+    queue.set(sessionId, [queueItem('recovered')]);
+    const { host, sent } = makeHost(sessionId);
+
+    // A delivery was scheduled but its callback never ran — the entry is left
+    // behind, which is exactly what a hot-reloaded module or a wedged event
+    // loop leaves. `clearAllTimers` drops the pending callback WITHOUT running
+    // it, so the bookkeeping outlives the timer.
+    scheduleQueueDelivery(host);
+    jest.clearAllTimers();
+    jest.advanceTimersByTime(600);
+    await flush();
+    expect(sent).toEqual([]);
+
+    // Inside the staleness bound a new trigger still defers to the pending
+    // entry: the head must not be double-booked.
+    jest.advanceTimersByTime(1000);
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+    expect(sent).toEqual([]);
+
+    // Past it, a later trigger recovers the queue rather than giving up.
+    jest.advanceTimersByTime(5000);
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent.filter((c) => c.type === 'prompt').length).toBe(1);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+});

package/src/server/lib/queue/delivery.server.ts

@@ -21,6 +21,7 @@
  */
 
 import { claimHeadQueueItem, requeueHeadQueueItem } from '@/server/lib/queue/store.server';
+import { composeMessageWithTextAttachments } from '@/shared/lib/chat/attachments';
 import type { QueuedMessage } from '@/shared/types/chat';
 
 /** Settling time between agent_end and the next prompt dispatch. Small on
@@ -28,16 +29,36 @@ import type { QueuedMessage } from '@/shared/types/chat';
  *  the same child, and an instant dispatch races it. */
 const DELIVERY_DELAY_MS = 500;
 
+/**
+ * How long a scheduled-but-not-yet-run delivery may sit before the next
+ * trigger supersedes it.
+ *
+ * Without this, one lost timer wedges the session's queue FOREVER: the guard
+ * below early-returns on any existing entry, so nothing would ever schedule
+ * again. A timer can be lost without the process dying — `bun --hot`
+ * re-evaluating this module discards the pending closure, and a wedged event
+ * loop drops the callback — and the symptom is silent: the queue simply never
+ * drains and no error is reported. Past this bound the entry is presumed lost
+ * and rescheduled, so a client nudge (sent whenever a session with queued
+ * items mounts or regains focus) always recovers the queue.
+ */
+const DELIVERY_STALE_MS = 5_000;
+
+interface PendingDelivery {
+  timer: ReturnType<typeof setTimeout>;
+  /** Wall-clock after which this entry is presumed lost and superseded. */
+  expiresAt: number;
+}
+
 /** Per-session pending delivery timer, so a second agent_end while one is
  *  already scheduled cannot double-book the head. */
-const pendingTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const pendingTimers = new Map<string, PendingDelivery>();
 
 function clearPendingTimer(sessionId: string): void {
-  const timer = pendingTimers.get(sessionId);
-  if (timer !== undefined) {
-    clearTimeout(timer);
-    pendingTimers.delete(sessionId);
-  }
+  const entry = pendingTimers.get(sessionId);
+  if (entry === undefined) return;
+  clearTimeout(entry.timer);
+  pendingTimers.delete(sessionId);
 }
 
 /** Send one queued item to the session as a normal prompt. The model snapshot
@@ -51,12 +72,33 @@ async function dispatchQueuedItem(session: QueueDeliveryHost, item: QueuedMessag
         await session.send({ type: 'set_thinking_level', level: item.model.thinkingLevel });
       }
     }
+    // Attachments reach this point as the persisted display fields — the live
+    // `File` never survived the queue's JSON round trip. The base64 payload and
+    // the MIME type are therefore read from the fields that DID persist:
+    // `dataBase64` for the bytes, `type` for the media type. (Matching on a
+    // `data:` preview used to yield zero images, because the composer's preview
+    // is a `blob:` object URL that the server cannot read.)
     const images = item.attachments
-      .filter((a) => typeof a?.preview === 'string' && a.preview.startsWith('data:image/') && typeof a?.dataBase64 === 'string')
-      .map((a) => ({ type: 'image' as const, data: a.dataBase64 as string, mimeType: a.preview.slice(5).split(';')[0] || 'image/png' }));
+      .filter((a) => typeof a?.dataBase64 === 'string' && a.dataBase64.length > 0)
+      .map((a) => ({
+        type: 'image' as const,
+        data: a.dataBase64 as string,
+        mimeType: typeof a.type === 'string' && a.type.startsWith('image/') ? a.type : 'image/png',
+      }));
+    // Text attachments are inlined into the prompt, exactly as the composer
+    // does at send time — the item's own `text` is the raw composer input, so
+    // without this a queued file would deliver as a bare filename mention.
+    const textFiles = item.attachments
+      .filter((a) => typeof a?.content === 'string' && a.content.length > 0)
+      .map((a) => ({
+        name: typeof a.name === 'string' && a.name ? a.name : 'attachment',
+        mimeType: typeof a.type === 'string' ? a.type : 'text/plain',
+        content: a.content as string,
+        size: typeof a.size === 'number' ? a.size : (a.content as string).length,
+      }));
     await session.send({
       type: 'prompt',
-      message: item.text,
+      message: composeMessageWithTextAttachments(item.text, textFiles),
       ...(images.length ? { images } : {}),
       ...(item.model ? { accessMode: item.model.accessMode } : {}),
     });
@@ -79,15 +121,25 @@ export interface QueueDeliveryHost {
  * Schedule the next queued delivery for this session. Called on terminal
  * agent_end and on a client's mount nudge. Idempotent: an in-flight timer is
  * reused, a claimed head can only be won by one caller.
+ *
+ * A pending entry older than {@link DELIVERY_STALE_MS} is presumed lost (see
+ * that constant) and replaced, so a dropped timer delays the queue instead of
+ * wedging it.
  */
 export function scheduleQueueDelivery(session: QueueDeliveryHost): void {
   const sessionId = session.sessionId;
-  if (!sessionId || pendingTimers.has(sessionId)) return;
+  if (!sessionId) return;
+  const pending = pendingTimers.get(sessionId);
+  if (pending !== undefined) {
+    if (Date.now() < pending.expiresAt) return;
+    // Lost timer: clear it so its callback cannot also fire and double-deliver.
+    clearTimeout(pending.timer);
+  }
   const timer = setTimeout(() => {
     pendingTimers.delete(sessionId);
     void deliverNext(session);
   }, DELIVERY_DELAY_MS);
-  pendingTimers.set(sessionId, timer);
+  pendingTimers.set(sessionId, { timer, expiresAt: Date.now() + DELIVERY_STALE_MS });
 }
 
 async function deliverNext(session: QueueDeliveryHost): Promise<void> {

package/src/server/plugins/ssr.ts

@@ -36,7 +36,7 @@ function missingBuildResponse(): Response {
 <p>For a rebuild-on-change loop while developing:</p>
 <pre style="background:#f4f1ea;padding:1rem;border-radius:6px">bunx rsbuild build --watch</pre>
 </body>`,
-    { status: 503, headers: { 'content-type': 'text/html; charset=utf-8' } },
+    { status: 503, headers: HTML_HEADERS },
   );
 }
 
@@ -64,6 +64,33 @@ function themeColor(theme: string): string {
 
 const MOBILE_UA = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|Mobile|mobile|CriOS/i;
 
+/**
+ * The HTML shell is generated per request, so its cacheability is declared
+ * rather than left to the browser's heuristics.
+ *
+ * It is not a static file: the theme and the bootstrap settings are injected on
+ * every request, and its only link to the bundle is a content hash inside the
+ * markup. A copy that outlives its build does not merely go stale — it points at
+ * an asset hash the build no longer emits, leaving the page running previous
+ * code with nothing in the response to signal it.
+ *
+ * Chrome does not currently cache it: the response carries no `Cache-Control`,
+ * `Last-Modified` or `ETag`, so there is no freshness to heuristically derive
+ * and every navigation re-fetches (measured: a second load of the shell reported
+ * the full 41 KB `transferSize`). That is the behaviour this header makes
+ * explicit — the day a validator is added for the template, heuristic caching
+ * would start and nothing else here would prevent it.
+ *
+ * `no-store` rather than `no-cache`: with no validator there is nothing to
+ * revalidate against, so a stored copy is never usable.
+ */
+const SHELL_CACHE = 'no-store';
+
+const HTML_HEADERS = {
+  'content-type': 'text/html; charset=utf-8',
+  'cache-control': SHELL_CACHE,
+} as const;
+
 export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }) => {
   const pathname = new URL(request.url).pathname;
 
@@ -95,6 +122,6 @@ export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }
       .replace('data-theme="paper"', `data-theme="${theme}"`)
       .replace('<!--app-head-->', `<meta name="theme-color" content="${themeColor(theme)}">`)
       .replace('<!--app-bootstrap-->', `<script>window.__OMP_BOOTSTRAP__=${bootstrap}</script>`),
-    { headers: { 'content-type': 'text/html; charset=utf-8' } },
+    { headers: HTML_HEADERS },
   );
 });

package/src/server/routes/btw/events.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `GET /api/btw/:sessionId/events` — SSE stream of a session's BTW frames.
+ *
+ * Unlike the agent stream this one is not observer-only: a side question's
+ * history must be readable for a session whose omp child is not running (that
+ * is the normal state of a session opened from the sidebar), so the route
+ * subscribes to the registry and never spawns anything.
+ */
+
+import { createEventCoalescer, createSseStream, type EventCoalescer } from '@/server/lib/sse';
+import { btwStateFor, subscribeBtw } from '@/server/lib/btw/registry.server';
+import type { BtwFrame } from '@/shared/types';
+
+/** Longest a coalesced frame may wait before it is flushed anyway. */
+const FLUSH_DELAY_MS = 50;
+
+export async function loader({ params, request }: { params: Record<string, string>; request: Request }) {
+  const { sessionId } = params;
+  if (!sessionId) return new Response('session id is required', { status: 400 });
+
+  let coalescer: EventCoalescer | null = null;
+
+  const stream = createSseStream({
+    heartbeatMs: 30_000,
+    signal: request.signal,
+    beforeHeartbeat: () => coalescer?.flush() ?? true,
+    onStart(handlers) {
+      let unsubscribe: (() => void) | null = null;
+      coalescer = createEventCoalescer({
+        send: (event, data) => handlers.send(event, data),
+        isBackpressured: handlers.isBackpressured,
+        flushDelayMs: FLUSH_DELAY_MS,
+      });
+      const push = (frame: BtwFrame) => coalescer?.push('', frame);
+
+      handlers.send('', { type: 'connected', sessionId });
+      if (handlers.isClosed()) return;
+      unsubscribe = subscribeBtw(sessionId, push);
+      void btwStateFor(sessionId)
+        .then((state) => push({ type: 'btw_state', state }))
+        .catch((error: unknown) => {
+          push({
+            type: 'btw_error',
+            topicId: null,
+            message: error instanceof Error ? error.message : String(error),
+          });
+        });
+
+      return () => {
+        coalescer?.dispose();
+        coalescer = null;
+        if (unsubscribe) {
+          try {
+            unsubscribe();
+          } catch {
+            // Subscriber cleanup is best-effort.
+          }
+          unsubscribe = null;
+        }
+      };
+    },
+  });
+
+  return stream.response;
+}

package/src/server/routes/btw/index.ts

@@ -0,0 +1,8 @@
+import { actionBindings, bindingsFor, type HandlerBinding } from '@/server/lib/route-adapter';
+import { action, loader } from '@/server/routes/btw/topics';
+import * as btwEvents from '@/server/routes/btw/events';
+
+export const btwBindings: HandlerBinding[] = [
+  ...actionBindings(action, '/api/btw/:sessionId', loader),
+  ...bindingsFor(btwEvents, '/api/btw/:sessionId/events'),
+];

package/src/server/routes/btw/topics.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * BTW commands: `GET /api/btw/:sessionId` returns a session's side questions,
+ * `POST` runs one action against them.
+ *
+ * Mutating verbs stay in one handler with its own dispatch (the ported Remix
+ * shape the rest of the API uses), so an unsupported action gets a named error
+ * instead of a silent success.
+ */
+
+import { json, type ActionFunctionArgs, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { toImageContents, validateAgentImages } from '@/server/lib/omp/rpc/constants';
+import { BtwError, type BtwImages } from '@/server/lib/btw/runtime.server';
+import { abortBtw, askBtw, getBtwState, promoteBtw, removeBtw } from '@/server/lib/btw/service.server';
+
+/** Actions that can reject for a reason the client should show as-is. */
+const STATUS_BY_CODE: Record<string, number> = {
+  btw_busy: 409,
+  btw_stale: 409,
+  session_not_found: 404,
+  btw_topic_not_found: 404,
+};
+
+function btwErrorResponse(error: unknown): Response {
+  if (error instanceof BtwError) {
+    return json({ error: error.message, code: error.code }, { status: STATUS_BY_CODE[error.code] ?? 400 });
+  }
+  return json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+}
+
+function readImages(raw: unknown): { images?: BtwImages } | { error: string } {
+  const problem = validateAgentImages(raw);
+  if (problem) return { error: problem };
+  const images = toImageContents(raw);
+  return images ? { images } : {};
+}
+
+export async function action({ params, request }: ActionFunctionArgs) {
+  const { sessionId } = params;
+  if (!sessionId) return json({ error: 'session id is required' }, { status: 400 });
+
+  const body = (await request.json().catch(() => null)) as Record<string, unknown> | null;
+  const action = typeof body?.action === 'string' ? body.action : '';
+  const topicId = typeof body?.topicId === 'string' ? body.topicId : undefined;
+  if (!action) return json({ error: 'action is required', code: 'action_required' }, { status: 400 });
+
+  try {
+    switch (action) {
+      case 'ask': {
+        const question = typeof body?.question === 'string' ? body.question : '';
+        const parsed = readImages(body?.images);
+        if ('error' in parsed) return json({ error: parsed.error, code: 'invalid_images' }, { status: 400 });
+        return json({ success: true, data: await askBtw(sessionId, { topicId, question, images: parsed.images }) });
+      }
+      case 'abort': {
+        if (!topicId) return json({ error: 'topicId is required', code: 'topic_required' }, { status: 400 });
+        return json({ success: true, data: await abortBtw(sessionId, topicId) });
+      }
+      case 'promote': {
+        if (!topicId) return json({ error: 'topicId is required', code: 'topic_required' }, { status: 400 });
+        return json({ success: true, data: await promoteBtw(sessionId, topicId) });
+      }
+      case 'delete': {
+        if (!topicId) return json({ error: 'topicId is required', code: 'topic_required' }, { status: 400 });
+        return json({ success: true, data: await removeBtw(sessionId, topicId) });
+      }
+      default:
+        return json({ error: `Unknown btw action: ${action}`, code: 'unknown_action' }, { status: 400 });
+    }
+  } catch (error) {
+    return btwErrorResponse(error);
+  }
+}
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const { sessionId } = params;
+  if (!sessionId) return json({ error: 'session id is required' }, { status: 400 });
+  try {
+    return json({ success: true, data: await getBtwState(sessionId) });
+  } catch (error) {
+    return btwErrorResponse(error);
+  }
+}