npm - ompchamber - Versions diffs - 3.1.1 → 3.3.0 - Mend

ompchamber 3.1.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (151) hide show

package/src/server/plugins/ssr.ts CHANGED Viewed

@@ -1,26 +1,47 @@
 import { Elysia } from 'elysia';
 import { getDb } from '@/server/db.server';
 import { tryServeStatic } from '@/server/plugins/static';
-import { renderShell } from '@/server/plugins/shell.server';
+import { renderShell, SHELL_MARKER } from '@/server/plugins/shell.server';
+import {
+  DEV_ASSETS_ENABLED,
+  devAssetUpstreamPath,
+  rewriteDevAssetUrls,
+  serveDevAsset,
+} from '@/server/lib/assets/dev-assets.server';
+import { listenerUrl } from '@/server/lib/lifecycle/listener';
 import { FONT_STYLESHEET_ROUTE } from '@/server/lib/assets/font-css.server';
 import { resolveTheme } from '@/shared/lib/theme/catalog';
 import { THEME_STYLE_ELEMENT_ID, themeStyleSheet } from '@/shared/lib/theme/css';
+/** HTML-escape a string for interpolation into the failure page's `<pre>`. */
+function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
 /**
  * Actionable message instead of a bare 500 when the shell cannot be rendered.
  *
  * The shell is a Bun HTML route now, not a file on disk, so "not found" is no
  * longer the failure mode — a bundle error is, and Bun renders its own error
- * page for that. This covers the remaining path: the bundle is fine but the
- * markup could not be read back.
+ * page for that, with the file and line locked inside a payload only the
+ * browser can decode. `plugins/shell.server.ts` rebuilds the entrypoint to get
+ * those facts in readable form and passes them here as the reason, so this page
+ * names the edit that broke the bundle rather than the status it produced.
  */
 function shellUnavailableResponse(reason: string): Response {
+  // Escaped, not interpolated raw: the reason carries the failed build's own
+  // source lines, which are arbitrary code — a `<` in one would otherwise
+  // truncate the page at the first tag.
   return new Response(
     `<!doctype html><meta charset="utf-8"><title>OMPChamber</title>
 <body style="font:14px/1.6 ui-monospace,monospace;padding:2rem">
 <h1 style="font-size:1.1rem">Shell not available</h1>
 <p>The server could not render its HTML shell.</p>
-<pre style="background:#f4f1ea;padding:1rem;border-radius:6px">${reason}</pre>
+<pre style="background:#f4f1ea;padding:1rem;border-radius:6px">${escapeHtmlText(reason)}</pre>
 </body>`,
     { status: 503, headers: HTML_HEADERS },
   );
@@ -83,7 +104,17 @@ export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }
     });
   }
-  const asset = await tryServeStatic(pathname);
+  // The dev asset proxy, before the static lookup: its prefix is this server's
+  // own, and Bun's table never sees it. See `lib/assets/dev-assets.server`.
+  if (DEV_ASSETS_ENABLED && devAssetUpstreamPath(pathname)) {
+    const base = listenerUrl();
+    if (base) {
+      const proxied = await serveDevAsset(request, pathname, base);
+      if (proxied) return proxied;
+    }
+  }
+  const asset = await tryServeStatic(pathname, request);
   if (asset) return asset;
   const settings = await readSettings();
@@ -110,13 +141,18 @@ export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }
   // loader and fail the same way.
   const fontLink = `<link rel="stylesheet" href="${FONT_STYLESHEET_ROUTE}">`;
+  // Bun's dev asset URLs move to this server's prefix so the proxy above can add
+  // the caching headers Bun omits. Rewritten BEFORE the bootstrap is injected,
+  // so a `/_bun/` string inside the settings payload is left alone.
+  const shellHtml = DEV_ASSETS_ENABLED ? rewriteDevAssetUrls(rendered.html) : rendered.html;
   return new Response(
-    rendered.html
+    shellHtml
       .replace('data-theme="paper"', `data-theme="${theme.id}"`)
       .replace('data-theme-variant="light"', `data-theme-variant="${theme.variant}"`)
       .replace('<meta name="theme-color" content="#faf8f3" />', `<meta name="theme-color" content="${theme.canvas}" />`)
       .replace('<!--app-head-->', themeStyle + fontLink)
-      .replace('<!--app-bootstrap-->', `<script>window.__OMP_BOOTSTRAP__=${bootstrap}</script>`),
+      .replace(SHELL_MARKER, `<script>window.__OMP_BOOTSTRAP__=${bootstrap}</script>`),
     { headers: HTML_HEADERS },
   );
 });

package/src/server/plugins/static.ts CHANGED Viewed

@@ -1,15 +1,20 @@
 import { extname, join, normalize, resolve, sep } from 'path';
+import { notModified } from '@/server/lib/assets/conditional.server';
 import { FONT_STYLESHEET_ROUTE, serveFontFile, serveFontStylesheet } from '@/server/lib/assets/font-css.server';
 import { FONT_ROUTE_PREFIX, packageRoot } from '@/server/lib/assets/fonts.server';
 /**
  * File serving for `public/` and the font routes.
  *
- * The client bundle is NOT served from here any more. Bun's own routing owns
- * the assets it emits — `/_bun/asset/*` and `/_bun/client/*` in development,
- * `/chunk-*` in production — and answers them from its bundle table before a
- * request reaches Elysia. `dist/client` no longer exists, so the `/static/`
+ * The client bundle is NOT served from here. Bun's own routing owns the assets
+ * it emits — `/_bun/asset/*` and `/_bun/client/*` in development, `/chunk-*` in
+ * production — and answers them from its bundle table before a request reaches
+ * Elysia. In development those responses are reached a second way, through
+ * `lib/assets/dev-assets.server.ts`: Bun's table wins for the paths it declares,
+ * so the shell points at `/_dev-assets/*` and that module fetches the bytes back
+ * from the listener to add the `Cache-Control` and `ETag`/`304` handling Bun's
+ * dev asset routes lack. `dist/client` no longer exists, so the `/static/`
  * branch and its content-hashed caching went with it.
  *
  * Hand-rolled rather than `@elysiajs/static`: that plugin registers its own
@@ -61,7 +66,17 @@ function resolveWithin(root: string, pathname: string): string | null {
   return candidate;
 }
-async function serveFile(filePath: string, cacheControl: string): Promise<Response | null> {
+/**
+ * The file's own bytes, or null when it cannot be read.
+ *
+ * `If-None-Match` is answered from a weak validator derived from the file's
+ * size and mtime. A content hash would be stronger, but it would mean reading
+ * every asset on every request to compute it — the opposite of the point.
+ * Size+mtime is what `plugins/static.ts` can produce from the `stat` it already
+ * performs, and a wrong `304` from it needs both a same-size edit and a
+ * preserved mtime, which is not something a build or an editor does.
+ */
+async function serveFile(filePath: string, cacheControl: string, request?: Request): Promise<Response | null> {
   let stat;
   try {
     stat = await Bun.file(filePath).stat();
@@ -71,14 +86,24 @@ async function serveFile(filePath: string, cacheControl: string): Promise<Respon
   if (!stat.isFile()) return null;
   const type = MIME[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
-  const stream = Bun.file(filePath).stream();
-  return new Response(stream, {
-    headers: {
-      'content-type': type,
-      'content-length': String(stat.size),
-      'cache-control': cacheControl,
-      'last-modified': stat.mtime.toUTCString(),
-    },
+  const lastModified = stat.mtime.toUTCString();
+  // Weak on purpose: the validator identifies the file as the same version, and
+  // byte equality is not what it promises.
+  const etag = `W/"${stat.size}-${Math.floor(stat.mtimeMs / 1000)}"`;
+  const headers = {
+    'content-type': type,
+    'cache-control': cacheControl,
+    'last-modified': lastModified,
+    etag,
+  };
+  if (request && notModified(request, etag, stat.mtimeMs)) {
+    // No `content-length`: a 304 describes the validator, not a body.
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(Bun.file(filePath).stream(), {
+    headers: { ...headers, 'content-length': String(stat.size) },
   });
 }
@@ -90,18 +115,22 @@ async function serveFile(filePath: string, cacheControl: string): Promise<Respon
  * going through the SSR route that injects the theme and bootstrap, and the
  * cache stays short because these filenames carry no content hash.
  */
-export async function servePublicAsset(pathname: string, roots: readonly string[]): Promise<Response | null> {
+export async function servePublicAsset(
+  pathname: string,
+  roots: readonly string[],
+  request?: Request,
+): Promise<Response | null> {
   for (const root of roots) {
     const filePath = resolveWithin(root, pathname);
     if (!filePath || filePath.endsWith('.html')) continue;
-    const response = await serveFile(filePath, SHORT);
+    const response = await serveFile(filePath, SHORT, request);
     if (response) return response;
   }
   return null;
 }
 /** A file for `pathname`, or null when the request should reach the app. */
-export async function tryServeStatic(pathname: string): Promise<Response | null> {
+export async function tryServeStatic(pathname: string, request?: Request): Promise<Response | null> {
   // The production bundle's own assets. `scripts/build-client.ts` emits the
   // server into `dist/client` with its chunks under `dist/client/static`, and
   // the generated HTML references them as `./static/...` — a page URL of `/`
@@ -110,7 +139,7 @@ export async function tryServeStatic(pathname: string): Promise<Response | null>
   // `/_bun/client/*`) and never reach here.
   if (pathname.startsWith('/static/')) {
     const filePath = resolveWithin(CLIENT_ROOT, pathname);
-    return filePath ? serveFile(filePath, ASSET_CACHE) : null;
+    return filePath ? serveFile(filePath, ASSET_CACHE, request) : null;
   }
   // The extracted `@font-face` stylesheet and the files it names. Bun's CSS
   // loader cannot carry either — every local `url()` is resolved, so a bundled
@@ -118,9 +147,13 @@ export async function tryServeStatic(pathname: string): Promise<Response | null>
   // than emitted. Both live outside `public/`: the stylesheet is assembled from
   // the faces `lib/bundler/css.ts` wrote, and the files come from the installed
   // packages.
+  //
+  // Neither is given a conditional here: the stylesheet is `no-store` (nothing
+  // is ever stored to revalidate) and a font file is `immutable` (the browser
+  // does not ask again). A validator on either would be dead code.
   if (pathname === FONT_STYLESHEET_ROUTE) return serveFontStylesheet();
   if (pathname.startsWith(FONT_ROUTE_PREFIX)) {
     return serveFontFile(decodeURIComponent(pathname.slice(FONT_ROUTE_PREFIX.length)));
   }
-  return servePublicAsset(pathname, [PUBLIC_ROOT]);
+  return servePublicAsset(pathname, [PUBLIC_ROOT], request);
 }

package/src/server/routes/agent/command.test.ts ADDED Viewed

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The spawn guard on POST /api/agent/:sessionId.
+ *
+ * This route is the chamber's ONLY lazy-spawn path: a command posted for a
+ * session it does not manage starts an `omp` child for it. That is right for a
+ * prompt — the user asked for work — and wrong for a read. The sidebar renders
+ * a subagent roster row for every session in the list, and the roster probes
+ * `get_subagents` to seed itself, so an unguarded route booted a whole omp
+ * process per finished session merely LOOKED at (measured: the process count
+ * grew on a session whose liveness probe had just answered `running: false`).
+ *
+ * Both observer-only commands have RPC-free on-disk equivalents, which is what
+ * a finished session is served from, so refusing them for a dead session costs
+ * the client nothing.
+ *
+ * No module is mocked. The assertions are about which response comes back
+ * BEFORE the spawn path is reached, so the real registry (empty for these ids)
+ * and the real on-disk resolver are exactly the inputs that matter. The
+ * "prompt" case proves the guard is not a blanket refusal: it reaches the
+ * resolver and 404s for an id with no session file — a spawn was attempted.
+ */
+import { describe, expect, test } from 'bun:test';
+import { sendCommand } from '@/server/routes/agent/command';
+/** Ids that no chamber instance manages and no session file backs. */
+const DEAD = 'spawn-guard-dead-session';
+const UNKNOWN = 'spawn-guard-unknown-session';
+function post(sessionId: string, body: Record<string, unknown>): Promise<Response> {
+  return sendCommand({
+    params: { sessionId },
+    request: new Request(`http://localhost/api/agent/${sessionId}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }),
+  } as never) as Promise<Response>;
+}
+async function payload(response: Response): Promise<Record<string, unknown>> {
+  return (await response.json()) as Record<string, unknown>;
+}
+describe('agent command spawn guard', () => {
+  test('refuses a roster snapshot for a session that is not running', async () => {
+    const response = await post(DEAD, { type: 'get_subagents' });
+    expect(response.status).toBe(409);
+    expect(await payload(response)).toMatchObject({ code: 'session_not_running' });
+  });
+  test('refuses a transcript page for a session that is not running', async () => {
+    const response = await post(DEAD, { type: 'get_subagent_messages', subagentId: 'child' });
+    expect(response.status).toBe(409);
+    expect(await payload(response)).toMatchObject({ code: 'session_not_running' });
+  });
+  test('does not refuse a command that asks for work', async () => {
+    const response = await post(UNKNOWN, { type: 'prompt', message: 'hello' });
+    // It reached the spawn path and failed there (no session file on disk),
+    // which is the opposite of the guard's 409.
+    expect(response.status).not.toBe(409);
+  });
+});

package/src/server/routes/agent/command.ts CHANGED Viewed

@@ -5,6 +5,7 @@ import { WebRpcError, getRpcSession, resolveSpawnCwd, startRpcSession, type Agen
 import { getSpawnApprovalMode, reconcileSpawnApprovalMode } from '@/server/lib/omp/rpc/session-registry';
 import { isApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { loadPersistedAccessMode } from '@/shared/lib/omp/config/access-mode.server';
+import { OBSERVER_ONLY_COMMANDS } from '@/server/lib/omp/rpc/constants';
 import { rpcErrorResponse } from '@/server/lib/omp/rpc/errors';
 // POST /api/agent/:sessionId — send a command to an existing session (or spawn
@@ -39,6 +40,19 @@ export async function sendCommand({ params, request }: ActionFunctionArgs) {
       }
     }
+    // Observer-only reads must never boot an omp child. This route is the spawn
+    // path, so a roster snapshot (`get_subagents`) or a transcript page
+    // (`get_subagent_messages`) posted for a session the chamber is not
+    // managing would start a whole process just to answer a read — measured:
+    // opening a FINISHED session's roster row grew the omp process count, and
+    // the sidebar renders those rows for every session in the list. Both reads
+    // have RPC-free on-disk equivalents (`GET /api/sessions/:id/subagents[/:sub]`),
+    // which is what a dead session is served from; the live registry is only
+    // consulted while a process exists to answer for.
+    if (OBSERVER_ONLY_COMMANDS.has(body.type)) {
+      return json({ error: 'Session is not managed by the chamber', code: 'session_not_running' }, { status: 409 });
+    }
     const resolved = await resolveSessionPathOr404(sessionId);
     if ('response' in resolved) return resolved.response;
     const { filePath, recordedCwd } = resolved;

package/src/server/routes/agent/ws.test.ts ADDED Viewed

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Regression test for the observer WebSocket routes' connection state.
+ *
+ * The bug this pins: `agent/ws.ts` and `btw/ws.ts` kept per-connection state in
+ * a `WeakMap` keyed by the `ws` object. Elysia's Bun adapter builds a NEW
+ * `ElysiaWS` wrapper for every callback and hands `pong` the RAW socket, so
+ * every lookup missed — the pong never cleared `awaitingPong`, the second
+ * heartbeat tore down a socket the client was still reading, and `close` leaked
+ * the interval and the session subscription for the life of the process.
+ *
+ * These assertions run through a real listener on purpose: the failure lived in
+ * the framework's callback identity, which a unit-level fake of `ws` cannot
+ * reproduce. That also makes the heartbeat a REAL timer here — the property
+ * under test is "the socket outlives N keepalive cycles", so the clock is the
+ * thing being measured. The interval is shrunk to 60ms to keep it cheap.
+ */
+import { afterAll, beforeAll, describe, expect, mock, test } from 'bun:test';
+import { Elysia } from 'elysia';
+/** Heartbeat for the test — several beats must fit inside a test timeout. */
+const HEARTBEAT_MS = 60;
+// The route reads the cadence constant at module scope, so the module is
+// replaced BEFORE the route module is imported.
+mock.module('@/shared/lib/workspace/refresh-cadence', () => ({
+  STREAM_HEARTBEAT_MS: HEARTBEAT_MS,
+  SIDEBAR_IDLE_REFRESH_MS: 30_000,
+  SIDEBAR_STREAM_POLL_MS: 8_000,
+  SIDEBAR_REVALIDATE_THROTTLE_MS: 1_000,
+  PANEL_REFRESH_MS: 5_000,
+  FILE_MUTATION_THROTTLE_MS: 500,
+  GIT_STATUS_POLL_MS: 15_000,
+  GIT_STATUS_EVENT_THROTTLE_MS: 1_000,
+  REPO_DISCOVERY_POLL_MS: 1_500,
+  TODO_REFRESH_EVENT_THROTTLE_MS: 400,
+  BROWSER_POLL_MS: 1_000,
+  SIDEBAR_DATA_TTL_MS: 4_000,
+  SESSION_META_RETRY_SCHEDULE_MS: [250],
+}));
+const { agentWsRoutes } = await import('@/server/routes/agent/ws');
+/** The live session the route subscribes to; records its own lifecycle. */
+interface SessionStub {
+  isAlive: () => boolean;
+  onEvent: (listener: (event: unknown) => void) => () => void;
+  listeners: Set<(event: unknown) => void>;
+  unsubscribes: number;
+}
+function makeSession(): SessionStub {
+  const stub: SessionStub = {
+    isAlive: () => true,
+    listeners: new Set(),
+    unsubscribes: 0,
+    onEvent(listener) {
+      stub.listeners.add(listener);
+      return () => {
+        stub.unsubscribes += 1;
+        stub.listeners.delete(listener);
+      };
+    },
+  };
+  return stub;
+}
+let session = makeSession();
+const app = new Elysia().use(agentWsRoutes);
+let baseUrl = '';
+beforeAll(async () => {
+  (globalThis as { __ompSessions?: unknown }).__ompSessions = {
+    get: (id: string) => (id === 'test-session' ? session : undefined),
+  };
+  await app.listen({ port: 0, hostname: '127.0.0.1' });
+  const port = (app.server as { port?: number } | null)?.port;
+  if (!port) throw new Error('test listener did not report a port');
+  baseUrl = `ws://127.0.0.1:${port}`;
+});
+afterAll(async () => {
+  await app.stop();
+});
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+/** One client, its received frames, and the promises for its lifecycle. */
+function connect(sessionId: string) {
+  const frames: unknown[] = [];
+  const client = new WebSocket(`${baseUrl}/api/agent/${sessionId}/ws`);
+  const opened = Promise.withResolvers<void>();
+  const closed = Promise.withResolvers<number>();
+  client.onopen = () => opened.resolve();
+  client.onmessage = (event) => {
+    try {
+      frames.push(JSON.parse(String(event.data)));
+    } catch {
+      // A non-JSON frame would be a protocol bug; assertions read `frames`.
+    }
+  };
+  client.onclose = (event) => closed.resolve(event.code);
+  return { client, frames, opened: opened.promise, closed: closed.promise };
+}
+describe('agent observer WebSocket', () => {
+  test('survives many heartbeats instead of being torn down by its own keepalive', async () => {
+    session = makeSession();
+    const { client, closed } = connect('test-session');
+    // Five beats: the old code closed the socket at the second one.
+    await sleep(HEARTBEAT_MS * 5);
+    expect(client.readyState).toBe(WebSocket.OPEN);
+    client.close();
+    await closed;
+  });
+  test('delivers the connected greeting and live session frames', async () => {
+    session = makeSession();
+    const { client, frames, opened, closed } = connect('test-session');
+    await opened;
+    for (const listener of session.listeners) listener({ type: 'agent_start' });
+    await sleep(30);
+    expect(frames).toEqual([
+      { type: 'connected', sessionId: 'test-session' },
+      { type: 'agent_start' },
+    ]);
+    client.close();
+    await closed;
+  });
+  test('releases the session subscription when the client disconnects', async () => {
+    session = makeSession();
+    const { client, opened, closed } = connect('test-session');
+    await opened;
+    expect(session.listeners.size).toBe(1);
+    client.close();
+    await closed;
+    await sleep(30);
+    expect(session.unsubscribes).toBe(1);
+    expect(session.listeners.size).toBe(0);
+  });
+  test('refuses a session the chamber does not manage', async () => {
+    const { opened, closed, client } = connect('unknown-session');
+    const outcome = await Promise.race([
+      opened.then(() => 'opened' as const),
+      closed.then(() => 'closed' as const),
+      sleep(400).then(() => 'timeout' as const),
+    ]);
+    // The upgrade is rejected before `open` runs, so the client never opens.
+    expect(outcome).not.toBe('opened');
+    client.close();
+  });
+});

package/src/server/routes/agent/ws.ts CHANGED Viewed

@@ -9,7 +9,7 @@
  *
  * Same frame vocabulary (JSON objects with a `type`, first frame `connected`),
  * same backpressure policy (replaceable `message_update` frames collapse to the
- * latest one while the client is behind) — the policy itself now lives in
+ * latest one while the client is behind) — the policy itself lives in
  * `createEventCoalescer`, shared with the SSE route — but carried by one duplex
  * socket: no per-event HTTP framing, no browser reconnect storm, and
  * protocol-level ping/pong keepalive instead of a comment frame every 30s.
@@ -17,18 +17,18 @@
  * Transport-only by design. It reads the live session registry off `globalThis`
  * (the map the server build populates) and duck-types the wrapper, so the
  * registry contract survives any HTTP framework owning the port.
+ *
+ * **Per-connection state lives on `ws.data`, not in a `WeakMap` keyed by the
+ * `ws` object.** Elysia's Bun adapter builds a fresh wrapper per callback and
+ * hands `pong` the raw socket, so a WeakMap lookup always missed: the pong
+ * never cleared `awaitingPong` and the second heartbeat closed a healthy
+ * socket at 60s, while `close` leaked the interval and the session
+ * subscription. `attachObserverStream` owns the lifecycle; see
+ * `@/server/lib/observer-ws` for the measurements.
  */
 import { Elysia, t } from 'elysia';
-import { createEventCoalescer, type EventCoalescer } from '@/server/lib/sse';
-import { STREAM_HEARTBEAT_MS } from '@/shared/lib/workspace/refresh-cadence';
-/** Coalesce `message_update` frames once this many bytes sit unsent. */
-const HIGH_WATER_BYTES = 256 * 1024;
-/** Longest a coalesced frame may wait before it is flushed anyway, so a burst
- *  that ends while the socket is still busy never strands the newest update. */
-const FLUSH_DELAY_MS = 50;
+import { attachObserverStream, createObserverState, type ObserverConnectionState } from '@/server/lib/observer-ws';
 interface AgentEventSession {
   isAlive?: () => boolean;
@@ -48,15 +48,8 @@ function findAgentSession(sessionId: string): AgentEventSession | null {
   return session;
 }
-interface ConnectionState {
-  closed: boolean;
-  unsubscribe: (() => void) | null;
-  heartbeat: ReturnType<typeof setInterval> | null;
-  awaitingPong: boolean;
-  coalescer: EventCoalescer | null;
-}
-const connections = new WeakMap<object, ConnectionState>();
+/** Elysia's ws context, narrowed to the per-connection store this route adds. */
+type AgentWsData = { params: { sessionId: string }; observer?: ObserverConnectionState };
 export const agentWsRoutes = new Elysia({ prefix: '/api/agent' }).ws('/:sessionId/ws', {
   params: t.Object({ sessionId: t.String() }),
@@ -68,81 +61,24 @@ export const agentWsRoutes = new Elysia({ prefix: '/api/agent' }).ws('/:sessionI
   },
   open(ws) {
-    const sessionId = ws.data.params.sessionId;
+    const data = ws.data as unknown as AgentWsData;
+    const sessionId = data.params.sessionId;
     const session = findAgentSession(sessionId);
     if (!session) {
       ws.close();
       return;
     }
-    const state: ConnectionState = {
-      closed: false,
-      unsubscribe: null,
-      heartbeat: null,
-      awaitingPong: false,
-      coalescer: null,
-    };
-    connections.set(ws, state);
+    const state = createObserverState();
+    data.observer = state;
+    const { push } = attachObserverStream(state, ws);
-    const teardown = () => {
-      if (state.closed) return;
-      state.closed = true;
-      state.coalescer?.dispose();
-      state.coalescer = null;
-      if (state.heartbeat !== null) {
-        clearInterval(state.heartbeat);
-        state.heartbeat = null;
-      }
-      if (state.unsubscribe) {
-        try {
-          state.unsubscribe();
-        } catch {
-          // Subscriber cleanup is best-effort.
-        }
-        state.unsubscribe = null;
-      }
-      try {
-        ws.close();
-      } catch {
-        // Already gone.
-      }
-    };
-    state.coalescer = createEventCoalescer({
-      send: (_event, data) => {
-        try {
-          ws.send(JSON.stringify(data));
-        } catch {
-          teardown();
-        }
-      },
-      isBackpressured: () => ((ws.raw as { bufferedAmount?: number }).bufferedAmount ?? 0) > HIGH_WATER_BYTES,
-      flushDelayMs: FLUSH_DELAY_MS,
-    });
-    // Protocol-level keepalive: a client that misses a full ping cycle is gone,
-    // and a live one answers without any application-level traffic.
-    state.heartbeat = setInterval(() => {
-      if (state.closed) return;
-      if (state.awaitingPong) {
-        teardown();
-        return;
-      }
-      state.awaitingPong = true;
-      if (!state.coalescer?.flush()) return;
-      try {
-        (ws.raw as { ping?: () => void }).ping?.();
-      } catch {
-        teardown();
-      }
-    }, STREAM_HEARTBEAT_MS);
-    state.unsubscribe = session.onEvent((event) => state.coalescer?.push('', event));
-    state.coalescer.push('', { type: 'connected', sessionId });
+    state.unsubscribe = session.onEvent((event) => push('', event));
+    push('', { type: 'connected', sessionId });
   },
   pong(ws) {
-    const state = connections.get(ws);
+    const state = (ws.data as unknown as AgentWsData).observer;
     if (state) state.awaitingPong = false;
   },
@@ -151,18 +87,7 @@ export const agentWsRoutes = new Elysia({ prefix: '/api/agent' }).ws('/:sessionI
   },
   close(ws) {
-    const state = connections.get(ws);
-    if (!state || state.closed) return;
-    state.closed = true;
-    state.coalescer?.dispose();
-    state.coalescer = null;
-    if (state.heartbeat !== null) clearInterval(state.heartbeat);
-    if (state.unsubscribe) {
-      try {
-        state.unsubscribe();
-      } catch {
-        // Subscriber cleanup is best-effort.
-      }
-    }
+    const state = (ws.data as unknown as AgentWsData).observer;
+    if (state) state.teardown();
   },
 });