@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/guests/surface.test.js

@@ -0,0 +1,486 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import http from 'node:http';
+
+import { SURFACE_FRAME_PATH, SURFACE_INPUT_PATH, SURFACE_CONTROL_PATH, SURFACE_RESIZE_PATH, SURFACE_CLIPBOARD_PATH } from '@openchamber/sdk';
+import WebSocket from 'ws';
+
+import { GuestServiceError } from './service.js';
+import { createGuestSurfaceRuntime, isSurfaceGuest } from './surface.js';
+
+const surfaceGuest = (overrides = {}) => ({
+  id: 'sim',
+  name: 'Simulator',
+  packageRoot: '/ext/sim',
+  enabled: true,
+  service: { entry: 'service/main.js', runtime: 'host', surface: true },
+  capabilityGrants: ['service'],
+  panel: { id: 'sim', name: 'Simulator', icon: 'window' },
+  ...overrides,
+});
+
+/**
+ * A service that never spawns: frames are pushed by the test, every other
+ * call is recorded. The frame request waits like a real service would.
+ */
+const createFakeService = () => {
+  const calls = [];
+  const frames = [];
+  const waiters = [];
+  let failWith = null;
+  /** Test hook: a promise the input handler awaits before answering. */
+  let inputGate = null;
+  const pushFrame = (frame) => {
+    frames.push(frame);
+    for (const wake of waiters.splice(0)) wake();
+  };
+  const nextFrameAfter = (seq) => frames.find((frame) => frame.seq > seq) ?? null;
+  const completed = [];
+  const openServiceRequest = async ({ path, method, body, query, signal }) => {
+    calls.push({ path, method, body: body ? JSON.parse(body) : undefined, query });
+    if (failWith) throw failWith;
+    if (path === SURFACE_INPUT_PATH && inputGate) {
+      const gate = inputGate;
+      inputGate = null;
+      await gate;
+    }
+    if (path === SURFACE_INPUT_PATH) completed.push(JSON.parse(body).events[0]);
+    let response;
+    if (path === SURFACE_FRAME_PATH) {
+      const after = Number(query.after);
+      let frame = nextFrameAfter(after);
+      if (!frame) {
+        await new Promise((resolve) => {
+          const wake = () => resolve();
+          waiters.push(wake);
+          signal?.addEventListener('abort', () => resolve(), { once: true });
+          setTimeout(resolve, 300);
+        });
+        frame = nextFrameAfter(after);
+      }
+      if (signal?.aborted) throw new GuestServiceError('cancelled', 'CANCELLED');
+      response = frame
+        ? new Response(frame.bytes, {
+          status: 200,
+          headers: {
+            'content-type': frame.mime ?? 'image/png',
+            'x-surface-seq': String(frame.seq),
+            'x-surface-width': String(frame.width ?? 320),
+            'x-surface-height': String(frame.height ?? 200),
+            ...(frame.title ? { 'x-surface-title': frame.title } : {}),
+            ...(frame.agentActive ? { 'x-surface-agent-active': '1' } : {}),
+          },
+        })
+        : new Response(null, { status: 204 });
+    } else if (path === SURFACE_RESIZE_PATH) {
+      response = Response.json({ width: 640, height: 400 });
+    } else if (path === SURFACE_CLIPBOARD_PATH) {
+      response = Response.json({ text: 'copied inside' });
+    } else {
+      response = new Response(null, { status: 204 });
+    }
+    return { response, finished: () => undefined };
+  };
+  return {
+    calls,
+    completed,
+    pushFrame,
+    gateNextInput: (promise) => { inputGate = promise; },
+    fail: (error) => { failWith = error; for (const wake of waiters.splice(0)) wake(); },
+    openServiceRequest,
+    callsTo: (path) => calls.filter((call) => call.path === path),
+  };
+};
+
+const listen = (server) => new Promise((resolve) => {
+  server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+});
+
+const openViewer = (port, guestId = 'sim') => new Promise((resolve, reject) => {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}/api/guests/${guestId}/surface/ws`);
+  ws.binaryType = 'arraybuffer';
+  const inbox = [];
+  const waiting = [];
+  ws.on('message', (data, isBinary) => {
+    const item = isBinary ? { binary: Buffer.from(data) } : JSON.parse(data.toString());
+    const waiter = waiting.shift();
+    if (waiter) waiter(item);
+    else inbox.push(item);
+  });
+  const next = () => (inbox.length ? Promise.resolve(inbox.shift()) : new Promise((r) => waiting.push(r)));
+  const send = (message) => ws.send(JSON.stringify(message));
+  ws.on('open', () => resolve({ ws, next, send, closed: new Promise((r) => ws.on('close', r)) }));
+  ws.on('error', reject);
+  ws.on('unexpected-response', (_req, res) => reject(new Error(`upgrade ${res.statusCode}`)));
+});
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 30));
+
+const cleanups = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup();
+});
+
+const createHarness = async ({ guest = surfaceGuest(), rejectUpgradeAuth = false } = {}) => {
+  const server = http.createServer((_req, res) => { res.statusCode = 404; res.end(); });
+  const service = createFakeService();
+  const holds = [];
+  const rejected = [];
+  const runtime = createGuestSurfaceRuntime({
+    server,
+    uiAuthController: rejectUpgradeAuth ? { enabled: true, ensureSessionToken: async () => null } : null,
+    isRequestOriginAllowed: async () => true,
+    rejectWebSocketUpgrade: (socket, status, message) => {
+      rejected.push({ status, message });
+      socket.end(`HTTP/1.1 ${status} ${message}\r\n\r\n`);
+    },
+    persistPath: '/data/extensions.json',
+    findGuest: async (id) => (guest && guest.id === id ? guest : null),
+    idleStopMs: 60_000,
+    openServiceRequest: service.openServiceRequest,
+    holdService: (guestId) => {
+      const entry = { guestId, released: false };
+      holds.push(entry);
+      return () => { entry.released = true; };
+    },
+    createViewerId: (() => { let n = 0; return () => `viewer-${++n}`; })(),
+  });
+  const port = await listen(server);
+  cleanups.push(async () => {
+    runtime.stop();
+    await new Promise((resolve) => server.close(resolve));
+  });
+  return { port, runtime, service, holds, rejected };
+};
+
+describe('isSurfaceGuest', () => {
+  test('needs enabled, approved, and a declared surface', () => {
+    expect(isSurfaceGuest(surfaceGuest())).toBe(true);
+    expect(isSurfaceGuest(surfaceGuest({ enabled: false }))).toBe(false);
+    expect(isSurfaceGuest(surfaceGuest({ capabilityGrants: [] }))).toBe(false);
+    expect(isSurfaceGuest(surfaceGuest({ service: { entry: 'service/main.js', runtime: 'host' } }))).toBe(false);
+  });
+});
+
+describe('guest surface runtime', () => {
+  test('refuses an upgrade for an unknown or surface-less extension', async () => {
+    const { port, rejected } = await createHarness({ guest: surfaceGuest({ service: { entry: 'service/main.js', runtime: 'host' } }) });
+    await expect(openViewer(port)).rejects.toThrow('upgrade 404');
+    expect(rejected[0]).toMatchObject({ status: 404 });
+  });
+
+  test('refuses an upgrade without a UI session', async () => {
+    const { port, rejected } = await createHarness({ rejectUpgradeAuth: true });
+    await expect(openViewer(port)).rejects.toThrow('upgrade 401');
+    expect(rejected[0]).toMatchObject({ status: 401 });
+  });
+
+  test('delivers frames one at a time per viewer and skips to the newest after an ack', async () => {
+    const { port, service, holds } = await createHarness();
+    const viewer = await openViewer(port);
+    expect(await viewer.next()).toEqual({ type: 'hello', viewerId: 'viewer-1' });
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'none', mine: false });
+    expect(holds).toEqual([{ guestId: 'sim', released: false }]);
+
+    service.pushFrame({ seq: 1, bytes: Buffer.from('frame-1'), title: 'Home' });
+    const meta = await viewer.next();
+    expect(meta).toEqual({ type: 'frame', seq: 1, width: 320, height: 200, mime: 'image/png', bytes: 7, agentActive: false, title: 'Home' });
+    expect((await viewer.next()).binary.toString()).toBe('frame-1');
+
+    // Two more frames arrive before the viewer acknowledges: it gets only the newest.
+    service.pushFrame({ seq: 2, bytes: Buffer.from('frame-2') });
+    await settle();
+    service.pushFrame({ seq: 3, bytes: Buffer.from('frame-3') });
+    await settle();
+    viewer.send({ type: 'ack', seq: 1 });
+    expect(await viewer.next()).toMatchObject({ type: 'frame', seq: 3 });
+    expect((await viewer.next()).binary.toString()).toBe('frame-3');
+
+    viewer.ws.close();
+    await viewer.closed;
+    await settle();
+    expect(holds[0].released).toBe(true);
+    expect(service.callsTo(SURFACE_FRAME_PATH)[0].query).toEqual({ after: '0', wait: '25000' });
+  });
+
+  test('the first input takes control, is forwarded, and tells the service; release hands it back', async () => {
+    const { port, service, runtime } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next();
+    await viewer.next();
+
+    const click = { type: 'pointer', action: 'down', x: 10, y: 20, button: 0, buttons: 1, modifiers: { alt: false, ctrl: false, meta: false, shift: false } };
+    viewer.send({ type: 'input', events: [click] });
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'user', mine: true });
+    await settle();
+    expect(runtime.userControls('sim')).toBe(true);
+    expect(service.callsTo(SURFACE_INPUT_PATH)[0].body).toEqual({ events: [click] });
+    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user' }]);
+
+    viewer.send({ type: 'release' });
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'none', mine: false });
+    await settle();
+    expect(runtime.userControls('sim')).toBe(false);
+    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user' }, { controller: 'none' }]);
+  });
+
+  test('a second viewer cannot take control from the first and is told who has it', async () => {
+    const { port, service } = await createHarness();
+    const first = await openViewer(port);
+    await first.next(); await first.next();
+    const second = await openViewer(port);
+    await second.next(); await second.next();
+
+    const key = { type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers: { alt: false, ctrl: false, meta: false, shift: false } };
+    first.send({ type: 'input', events: [key] });
+    expect(await first.next()).toEqual({ type: 'control', controller: 'user', mine: true });
+    expect(await second.next()).toEqual({ type: 'control', controller: 'user', mine: false });
+
+    second.send({ type: 'input', events: [key] });
+    expect(await second.next()).toEqual({ type: 'control', controller: 'user', mine: false });
+    await settle();
+    expect(service.callsTo(SURFACE_INPUT_PATH)).toHaveLength(1);
+
+    // The holder disconnecting releases control for everyone.
+    first.ws.close();
+    expect(await second.next()).toEqual({ type: 'control', controller: 'none', mine: false });
+  });
+
+  test('agent activity holds control until the hold expires, and the user always wins', async () => {
+    const { port, runtime, service } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+
+    // Not attached to a session: nothing to note, nothing thrown.
+    runtime.noteAgentActivity('other');
+
+    runtime.noteAgentActivity('sim');
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'agent', mine: false });
+    expect(runtime.userControls('sim')).toBe(false);
+    // A second action while already agent-held does not re-broadcast.
+    runtime.noteAgentActivity('sim');
+
+    const text = { type: 'text', text: 'hello' };
+    viewer.send({ type: 'input', events: [text] });
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'user', mine: true });
+    await settle();
+    expect(service.callsTo(SURFACE_INPUT_PATH)[0].body).toEqual({ events: [text] });
+  });
+
+  test('the agent hold expires back to nobody', async () => {
+    const timers = [];
+    const server = http.createServer((_req, res) => { res.statusCode = 404; res.end(); });
+    const service = createFakeService();
+    const runtime = createGuestSurfaceRuntime({
+      server,
+      uiAuthController: null,
+      isRequestOriginAllowed: async () => true,
+      rejectWebSocketUpgrade: (socket) => socket.destroy(),
+      persistPath: '/data/extensions.json',
+      findGuest: async () => surfaceGuest(),
+      idleStopMs: 60_000,
+      openServiceRequest: service.openServiceRequest,
+      holdService: () => () => undefined,
+      setTimer: (fn) => { timers.push(fn); return { unref() {} }; },
+      clearTimer: () => undefined,
+    });
+    const port = await listen(server);
+    cleanups.push(async () => { runtime.stop(); await new Promise((resolve) => server.close(resolve)); });
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    runtime.noteAgentActivity('sim');
+    expect(await viewer.next()).toMatchObject({ type: 'control', controller: 'agent' });
+    expect(timers).toHaveLength(1);
+    timers[0]();
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'none', mine: false });
+  });
+
+  test('hovering over the picture does not take control; a click does', async () => {
+    const { port, service, runtime } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    viewer.send({ type: 'input', events: [{ type: 'pointer', action: 'move', x: 5, y: 5, button: -1, buttons: 0, modifiers }] });
+    await settle();
+    expect(runtime.userControls('sim')).toBe(false);
+    expect(service.callsTo(SURFACE_INPUT_PATH)).toHaveLength(0);
+
+    runtime.noteAgentActivity('sim');
+    expect(await viewer.next()).toMatchObject({ type: 'control', controller: 'agent' });
+    viewer.send({ type: 'input', events: [{ type: 'pointer', action: 'move', x: 6, y: 6, button: -1, buttons: 0, modifiers }] });
+    await settle();
+    expect(runtime.userControls('sim')).toBe(false);
+
+    viewer.send({ type: 'input', events: [{ type: 'pointer', action: 'down', x: 6, y: 6, button: 0, buttons: 1, modifiers }] });
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'user', mine: true });
+    // Now moves flow, as the holder's.
+    viewer.send({ type: 'input', events: [{ type: 'pointer', action: 'move', x: 7, y: 7, button: -1, buttons: 0, modifiers }] });
+    await settle();
+    expect(service.callsTo(SURFACE_INPUT_PATH)).toHaveLength(2);
+  });
+
+  test('input batches reach the service in socket order even when one is slow', async () => {
+    const { port, service } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    let open;
+    service.gateNextInput(new Promise((resolve) => { open = resolve; }));
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers }] });
+    await viewer.next(); // control
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'b', code: 'KeyB', modifiers }] });
+    viewer.send({ type: 'clipboard-read', id: 'c1' });
+    await settle();
+    expect(service.completed).toHaveLength(0);
+    expect(service.callsTo(SURFACE_CLIPBOARD_PATH)).toHaveLength(0);
+    open();
+    expect(await viewer.next()).toEqual({ type: 'clipboard', id: 'c1', text: 'copied inside' });
+    expect(service.completed.map((event) => event.key)).toEqual(['a', 'b']);
+  });
+
+  test('a session ended while the user held control never talks to the service again', async () => {
+    const { port, service, runtime, holds } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers }] });
+    expect(await viewer.next()).toMatchObject({ type: 'control', controller: 'user', mine: true });
+    await settle();
+    const callsBefore = service.calls.length;
+
+    // Approval withdrawn: the guest routes end the session; the socket closes after.
+    runtime.endForGuest('sim');
+    expect(await viewer.next()).toEqual({ type: 'ended', reason: 'extension-unavailable' });
+    await viewer.closed;
+    await settle();
+    expect(service.calls.length).toBe(callsBefore);
+    expect(holds[0].released).toBe(true);
+  });
+
+  test('the last viewer leaving while holding control tells the service it let go', async () => {
+    const { port, service } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers }] });
+    await viewer.next();
+    await settle();
+    viewer.ws.close();
+    await viewer.closed;
+    await settle();
+    expect(service.callsTo(SURFACE_CONTROL_PATH).map((call) => call.body)).toEqual([{ controller: 'user' }, { controller: 'none' }]);
+  });
+
+  test('a queued input from before a hand-back does not take control again', async () => {
+    const { port, service, runtime } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    let open;
+    service.gateNextInput(new Promise((resolve) => { open = resolve; }));
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers }] });
+    expect(await viewer.next()).toMatchObject({ type: 'control', controller: 'user', mine: true });
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'b', code: 'KeyB', modifiers }] });
+    viewer.send({ type: 'release' });
+    expect(await viewer.next()).toEqual({ type: 'control', controller: 'none', mine: false });
+    expect(runtime.userControls('sim')).toBe(false);
+    open();
+    await settle();
+    await settle();
+    expect(runtime.userControls('sim')).toBe(false);
+    // B was typed before the release and still belonged to the holder: it is
+    // not re-taken, and it is not delivered under nobody's control either.
+    expect(service.completed.map((event) => event.key)).toEqual(['a']);
+  });
+
+  test('a queued input from a viewer that left never makes it the controller', async () => {
+    const { port, service, runtime } = await createHarness();
+    const first = await openViewer(port);
+    await first.next(); await first.next();
+    const second = await openViewer(port);
+    await second.next(); await second.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    let open;
+    service.gateNextInput(new Promise((resolve) => { open = resolve; }));
+    first.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers }] });
+    await first.next();
+    expect(await second.next()).toEqual({ type: 'control', controller: 'user', mine: false });
+    first.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'b', code: 'KeyB', modifiers }] });
+    first.ws.close();
+    expect(await second.next()).toEqual({ type: 'control', controller: 'none', mine: false });
+    open();
+    await settle();
+    await settle();
+    expect(runtime.userControls('sim')).toBe(false);
+    second.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'c', code: 'KeyC', modifiers }] });
+    expect(await second.next()).toEqual({ type: 'control', controller: 'user', mine: true });
+    await settle();
+    expect(service.completed.map((event) => event.key)).toEqual(['a', 'c']);
+  });
+
+  test('a deactivation while the closed panel\'s farewell is still queued cancels it', async () => {
+    const { port, service, runtime, holds } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    let open;
+    service.gateNextInput(new Promise((resolve) => { open = resolve; }));
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'a', code: 'KeyA', modifiers }] });
+    await viewer.next();
+    await settle();
+    viewer.ws.close();
+    await viewer.closed;
+    await settle();
+    // The session is still registered: its final "none" waits behind the slow input.
+    expect(runtime.sessionOf('sim')).not.toBeNull();
+    const callsBefore = service.calls.length;
+    runtime.endForGuest('sim');
+    open();
+    await settle();
+    await settle();
+    expect(service.calls.length).toBe(callsBefore);
+    expect(runtime.sessionOf('sim')).toBeNull();
+    expect(holds[0].released).toBe(true);
+  });
+
+  test('resize and clipboard reads round-trip through the service; clipboard needs control', async () => {
+    const { port, service } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    viewer.send({ type: 'resize', width: 800, height: 600 });
+    expect(await viewer.next()).toEqual({ type: 'resized', width: 640, height: 400 });
+    expect(service.callsTo(SURFACE_RESIZE_PATH)[0].body).toEqual({ width: 800, height: 600 });
+    viewer.send({ type: 'clipboard-read', id: 'c0' });
+    expect(await viewer.next()).toMatchObject({ type: 'error', code: 'NOT_CONTROLLING' });
+    expect(service.callsTo(SURFACE_CLIPBOARD_PATH)).toHaveLength(0);
+    const modifiers = { alt: false, ctrl: false, meta: false, shift: false };
+    viewer.send({ type: 'input', events: [{ type: 'key', action: 'down', key: 'c', code: 'KeyC', modifiers: { ...modifiers, meta: true } }] });
+    await viewer.next();
+    viewer.send({ type: 'clipboard-read', id: 'c1' });
+    expect(await viewer.next()).toEqual({ type: 'clipboard', id: 'c1', text: 'copied inside' });
+  });
+
+  test('a malformed viewer message is answered with an error, not a drop', async () => {
+    const { port } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    viewer.ws.send('{"type":"input","events":[{"type":"pointer"}]}');
+    expect(await viewer.next()).toMatchObject({ type: 'error', code: 'BAD_MESSAGE' });
+  });
+
+  test('a service that stops ends the session for every viewer; deactivation does too', async () => {
+    const { port, service, runtime } = await createHarness();
+    const viewer = await openViewer(port);
+    await viewer.next(); await viewer.next();
+    service.fail(new GuestServiceError('gone', 'SERVICE_FAILED'));
+    expect(await viewer.next()).toEqual({ type: 'ended', reason: 'service-stopped' });
+    await viewer.closed;
+
+    service.fail(null);
+    const again = await openViewer(port);
+    await again.next(); await again.next();
+    runtime.endForGuest('sim');
+    expect(await again.next()).toEqual({ type: 'ended', reason: 'extension-unavailable' });
+    await again.closed;
+    expect(runtime.sessionOf('sim')).toBeNull();
+  });
+});

package/server/lib/markdown-image-grants/routes.js

@@ -1,6 +1,7 @@
 import express from 'express';
 import { constants as fsConstants } from 'node:fs';
 import { mintOutsideFileGrant } from '../fs/routes.js';
+import { unwrapOpenCodeResponse } from '../opencode/response-envelope.js';
 
 const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
 const MAX_IMAGE_SOURCES = 12;
@@ -128,9 +129,20 @@ const parseDefinitionDestination = (value) => {
   return match ? unescapeMarkdownDestination(match[0]) : '';
 };
 
+/**
+ * v2 messages are flat records: an assistant one carries `content[]` and a user
+ * one a single `text`. Both are read here, because an image link can come from
+ * either side of the conversation.
+ */
+const messageTextParts = (message) => {
+  if (Array.isArray(message?.content)) return message.content;
+  if (typeof message?.text === 'string') return [{ type: 'text', text: message.text }];
+  return [];
+};
+
 const collectMarkdownLinesOutsideCode = (message) => {
   const lines = [];
-  for (const part of Array.isArray(message?.parts) ? message.parts : []) {
+  for (const part of messageTextParts(message)) {
     if (part?.type !== 'text' || typeof part.text !== 'string') continue;
     let fence = null;
     for (const line of part.text.split('\n')) {
@@ -193,7 +205,7 @@ const markdownImageSources = (message) => {
 
 const fetchMessage = async ({ sessionId, messageId, directory, buildOpenCodeUrl, getOpenCodeAuthHeaders }) => {
   const url = new URL(buildOpenCodeUrl(
-    `/session/${encodeURIComponent(sessionId)}/message/${encodeURIComponent(messageId)}`,
+    `/api/session/${encodeURIComponent(sessionId)}/message/${encodeURIComponent(messageId)}`,
     '',
   ));
   url.searchParams.set('directory', directory);
@@ -209,8 +221,8 @@ const fetchMessage = async ({ sessionId, messageId, directory, buildOpenCodeUrl,
   });
   if (response.status === 404) return null;
   if (!response.ok) throw new Error(`OpenCode returned ${response.status}`);
-  const message = await response.json().catch(() => null);
-  return message?.info && Array.isArray(message.parts) ? message : null;
+  const message = unwrapOpenCodeResponse(await response.json().catch(() => null));
+  return message && typeof message === 'object' && typeof message.id === 'string' ? message : null;
 };
 
 const inspectImage = async ({ source, directory, approvedTempRoot, fsPromises, path }) => {
@@ -289,7 +301,8 @@ export const registerMarkdownImageGrantRoutes = (app, dependencies) => {
           buildOpenCodeUrl,
           getOpenCodeAuthHeaders,
         });
-        if (!message || message.info?.id !== messageId || message.info?.role !== 'assistant') {
+        // v2 messages are flat records with a `type` discriminator.
+        if (!message || message.id !== messageId || message.type !== 'assistant') {
           return res.status(404).json({ error: 'Assistant message not found' });
         }
         // Assistant text is authoritative: a remote client cannot mint grants for unreferenced paths.

package/server/lib/markdown-image-grants/routes.test.js

@@ -32,8 +32,9 @@ const createFixture = async ({ sources, markdown } = {}) => {
   const requestedSources = sources ?? [new URL(`file://${defaultPath}`).toString()];
   const text = markdown ?? requestedSources.map((source) => `![image](${source})`).join('\n');
   const fetchMock = vi.fn(async () => new Response(JSON.stringify({
-    info: { id: 'msg_1', role: 'assistant' },
-    parts: [{ type: 'text', text }],
+    id: 'msg_1',
+    type: 'assistant',
+    content: [{ type: 'text', text }],
   }), { status: 200, headers: { 'content-type': 'application/json' } }));
   vi.stubGlobal('fetch', fetchMock);
 
@@ -95,8 +96,9 @@ describe('session image assets', () => {
     await fs.writeFile(temporaryPath, PNG);
     const temporarySource = new URL(`file://${temporaryPath}`).toString();
     fixture.fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({
-      info: { id: 'msg_1', role: 'assistant' },
-      parts: [{ type: 'text', text: `![workspace](workspace.png)\n![temporary](${temporarySource})` }],
+      id: 'msg_1',
+      type: 'assistant',
+      content: [{ type: 'text', text: `![workspace](workspace.png)\n![temporary](${temporarySource})` }],
     }), { status: 200, headers: { 'content-type': 'application/json' } }));
 
     const response = await prepare(fixture.app, fixture.directory, ['workspace.png', temporarySource]);
@@ -212,8 +214,9 @@ describe('session image assets', () => {
     await fs.writeFile(outsidePath, PNG);
     const source = new URL(`file://${outsidePath}`).toString();
     fixture.fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({
-      info: { id: 'msg_1', role: 'assistant' },
-      parts: [{ type: 'text', text: `![outside](${source})` }],
+      id: 'msg_1',
+      type: 'assistant',
+      content: [{ type: 'text', text: `![outside](${source})` }],
     }), { status: 200, headers: { 'content-type': 'application/json' } }));
 
     const response = await prepare(fixture.app, fixture.directory, [source]);

package/server/lib/message-queue/DOCUMENTATION.md

@@ -24,9 +24,11 @@ JSON bodies enabled in `opencode/core-routes.js`; stopped by
 
 ## Auto routing
 
-`resolvePromptBody` (the routing runtime) runs on the assembled body right
-before the prompt or command send, turning a queued `openchamber/auto` model
-into a real one. The queue captures the sentinel like any other send config.
+`resolveAutoSelection` (the routing runtime) runs right before the send when
+the queued send config names `openchamber/auto`, and answers with the real
+model and agent. OpenCode 2.x holds both on the session, so the queue applies
+them with the `POST /api/session/:id/model` and `/agent` calls it already
+makes. The queue captures the sentinel like any other send config.
 
 ## Item
 
@@ -100,30 +102,39 @@ persisted "sending" flag would strand a message forever.
    old behavior: a stop is not immediately followed by the next prompt) or
    while the head item is in retry backoff.
 4. Idleness is re-verified against OpenCode before sending, because
-   `prompt_async` into a running turn steers into it instead of starting the
-   next one: `GET /session/status` must not list the session as busy/retry,
-   and the trailing message must not be an unfinished assistant reply (the
-   status map only lists busy sessions, so a missed busy event leaves no
-   entry while a turn still streams). An unfinished reply created before this
+   a prompt into a running turn steers into it instead of starting the
+   next one: `GET /api/session/active` must not list the session, and the
+   trailing message must not be an unfinished assistant reply (that route
+   lists only running sessions, so a missed busy event leaves no entry while
+   a turn still streams). An unfinished reply created before this
    runtime started does not block: its run died with the previous server and
    will never complete, so a restored queue would wait on it forever. A reply
    with no `created` time still blocks. A failed fetch is unknown, never idle:
    the tick re-arms with backoff.
-5. The head is marked in flight (broadcast), then sent:
+   The turn must also be over for the session's subagents: a parent idles
+   while a background subagent works and runs again when OpenCode hands the
+   result back. While `../opencode/session-activity.js` finds a running child
+   the head waits (the rerun's idle event re-arms it, a 5 s recheck covers a
+   missed one); a failed check is unknown and backs off like the rest.
+5. The head is marked in flight (broadcast), then sent. The captured model and
+   agent are switched onto the session first (`POST /session/:id/model`,
+   `/agent`), because v2 holds both on the session rather than in the body; a
+   captured `openchamber/auto` is resolved into a real pair by the routing
+   runtime beforehand. Then the captured context goes ahead as synthetic
+   messages (`POST /session/:id/synthetic` with `resume: false`, an attached
+   item's metadata riding along), followed by pending project knowledge
+   (`sessionKnowledgeRuntime.resolvePendingForSession`, recorded as delivered
+   only after the send is accepted), and then the message itself:
    - text starting with `/` that names a command in OpenCode's `/command`
-     list (skills included) and carries no captured context goes to
-     `POST /session/:id/command` with the captured model, agent, variant, and
-     file parts. That route accepts file parts only, so a command queued
-     **with** context takes the prompt route instead, the same rule the
-     composer applies: the command's template is expanded with its arguments
-     (`$ARGUMENTS`, `$1..$N`, or appended), a skill keeps its `/name args` text
-     and gets an explicit "the user invoked this skill" synthetic part after
-     the context;
-   - otherwise `POST /session/:id/prompt_async` with the parts in the same
-     order a UI send uses: text, files, the captured context, the skill
-     invocation when there is one, pending project knowledge
-     (`sessionKnowledgeRuntime.resolvePendingForSession`, synthetic, recorded
-     as delivered only after the prompt is accepted), then the agent mention.
+     list (skills included) goes to `POST /session/:id/command` (body fields
+     `name` and `text` since OpenCode 2.0.8) with its file attachments. The
+     command route takes files only, which is why the context went ahead of
+     it; sending "/name args" as a prompt instead would skip the template
+     OpenCode expands only on that route. The command lookup runs before
+     anything is admitted, so a failed lookup fails the send without leaving
+     context behind for the retry to duplicate;
+   - otherwise `POST /session/:id/prompt` with the user's text, files and
+     agent mention.
    Success removes the item, persists, broadcasts, and marks the user
    message sent for notifications. Failure keeps the item, backs off
    2 s → 60 s (doubling per consecutive failure of that item), and re-arms.