@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/routes/auth/routes.test.ts

@@ -0,0 +1,322 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `/api/auth/*` request contract: login, password change, revoke, logout,
+ * and state.
+ *
+ * These routes are the only door into the app, so each refusal branch is pinned
+ * separately: a wrong password must not be distinguishable from a malformed
+ * body (both are the same locked 401), a too-short new password must not be
+ * accepted, and a revoked or password-changed token must stop verifying. The
+ * state route is the client's only signal for "show login or show the app", so
+ * its two booleans are pinned against a real minted cookie rather than a stub.
+ *
+ * Everything runs against a throwaway data dir: the module slot in
+ * `lib/auth/guard` is process-wide, so `initAuth(null)` restores it for the
+ * sibling suites that run in the same `bun test` process.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { action as login } from '@/server/routes/auth/login';
+import { action as changePassword, MIN_PASSWORD_LENGTH } from '@/server/routes/auth/password';
+import { action as logout } from '@/server/routes/auth/logout';
+import { loader as authState } from '@/server/routes/auth/state';
+import { initAuth, loadAuthConfig, revokeAllSessions } from '@/server/lib/auth/guard';
+import { verifyPassword } from '@/server/lib/auth/config';
+import { issueSessionToken, SESSION_TTL_MS, TRUSTED_DEVICE_TTL_MS } from '@/server/lib/auth/token';
+import { resetLoginRateLimits } from '@/server/lib/auth/rate-limit';
+
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'omc-auth-routes-'));
+const PASSWORD = 'correct-horse-battery';
+
+beforeEach(async () => {
+  // The login budget is keyed by the (unrecorded) client address, which is the
+  // shared unknown-client key here, so every test would otherwise inherit the
+  // previous test's failures.
+  resetLoginRateLimits();
+  Bun.env.KABMO_DATA_DIR = DATA_DIR;
+  await initAuth(PASSWORD);
+});
+
+afterAll(async () => {
+  await initAuth(null);
+  delete Bun.env.KABMO_DATA_DIR;
+  fs.rmSync(DATA_DIR, { recursive: true, force: true });
+});
+
+function post(url: string, body: unknown, init: RequestInit = {}): Request {
+  return new Request(url, {
+    method: 'POST',
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+    ...init,
+  });
+}
+
+async function body(res: Response): Promise<Record<string, unknown>> {
+  return (await res.json()) as Record<string, unknown>;
+}
+
+/** The auth state a browser carrying `token` would be served. */
+async function stateWith(token: string): Promise<Record<string, unknown>> {
+  const req = new Request('http://localhost/api/auth/state', {
+    headers: { cookie: `omp_session=${encodeURIComponent(token)}` },
+  });
+  return body((await authState({ request: req } as never)) as Response);
+}
+
+function tokenFrom(res: Response): string {
+  const header = res.headers.get('set-cookie') ?? '';
+  const match = /omp_session(?:_\d+)?=([^;]*)/.exec(header);
+  return match ? decodeURIComponent(match[1]) : '';
+}
+
+describe('POST /api/auth/login', () => {
+  test('refuses a wrong password with the locked 401 envelope', async () => {
+    const res = (await login({
+      request: post('http://localhost/api/auth/login', { password: 'nope' }),
+    } as never)) as Response;
+    expect(res.status).toBe(401);
+    expect(await body(res)).toEqual({ error: 'Invalid password', locked: true });
+    // One failure spent of the unknown-client budget of three.
+    expect(res.headers.get('x-ratelimit-limit')).toBe('3');
+    expect(res.headers.get('x-ratelimit-remaining')).toBe('2');
+  });
+
+  test('a malformed JSON body is a wrong password, not a 400', async () => {
+    const res = (await login({
+      request: post('http://localhost/api/auth/login', 'not json'),
+    } as never)) as Response;
+    expect(res.status).toBe(401);
+    expect((await body(res)).error).toBe('Invalid password');
+  });
+
+  test('a missing password field is a wrong password', async () => {
+    const res = (await login({ request: post('http://localhost/api/auth/login', {}) } as never)) as Response;
+    expect(res.status).toBe(401);
+  });
+
+  test('the correct password mints a session cookie', async () => {
+    const res = (await login({
+      request: post('http://localhost/api/auth/login', { password: PASSWORD }),
+    } as never)) as Response;
+    expect(res.status).toBe(200);
+    expect(await body(res)).toEqual({ authenticated: true, expiresInSec: SESSION_TTL_MS / 1000 });
+    const header = res.headers.get('set-cookie') ?? '';
+    expect(header).toContain('omp_session=');
+    expect(header).toContain('HttpOnly');
+    expect(header).toContain('SameSite=Lax');
+    expect(header).toContain(`Max-Age=${SESSION_TTL_MS / 1000}`);
+    expect(await stateWith(tokenFrom(res))).toEqual({ required: true, authenticated: true });
+  });
+
+  test('trustDevice extends the cookie to the trusted-device TTL', async () => {
+    const res = (await login({
+      request: post('http://localhost/api/auth/login', { password: PASSWORD, trustDevice: true }),
+    } as never)) as Response;
+    expect(await body(res)).toEqual({ authenticated: true, expiresInSec: TRUSTED_DEVICE_TTL_MS / 1000 });
+    expect(res.headers.get('set-cookie')).toContain(`Max-Age=${TRUSTED_DEVICE_TTL_MS / 1000}`);
+  });
+
+  test('a lockout answers 429 and blocks even the correct password', async () => {
+    const wrong = () =>
+      login({ request: post('http://localhost/api/auth/login', { password: 'nope' }) } as never) as Promise<Response>;
+    expect((await wrong()).status).toBe(401);
+    expect((await wrong()).status).toBe(401);
+    const third = await wrong();
+    expect(third.status).toBe(429);
+    expect(third.headers.get('retry-after')).toBe('900');
+    expect((await body(third)).retryAfter).toBe(900);
+
+    const correct = (await login({
+      request: post('http://localhost/api/auth/login', { password: PASSWORD }),
+    } as never)) as Response;
+    expect(correct.status).toBe(429);
+  });
+
+  test('a wrong verb is a 405', async () => {
+    const res = (await login({
+      request: new Request('http://localhost/api/auth/login', { method: 'GET' }),
+    } as never)) as Response;
+    expect(res.status).toBe(405);
+    expect((await body(res)).error).toBe('Method not allowed');
+  });
+});
+
+describe('GET /api/auth/state', () => {
+  test('reports required and unauthenticated without a cookie', async () => {
+    const res = (await authState({ request: new Request('http://localhost/api/auth/state') } as never)) as Response;
+    expect(await body(res)).toEqual({ required: true, authenticated: false });
+    expect(res.headers.get('cache-control')).toBe('no-store');
+  });
+
+  test('a token minted for the active password is authenticated', async () => {
+    const config = loadAuthConfig()!;
+    const token = issueSessionToken({ sessionSecret: config.sessionSecret, credentialKey: config.credentialKey });
+    expect(await stateWith(token)).toEqual({ required: true, authenticated: true });
+  });
+
+  test('a token signed with the pre-revocation secret is not authenticated', async () => {
+    const config = loadAuthConfig()!;
+    const token = issueSessionToken({ sessionSecret: config.sessionSecret, credentialKey: config.credentialKey });
+    await revokeAllSessions();
+    expect(await stateWith(token)).toEqual({ required: true, authenticated: false });
+  });
+});
+
+describe('POST /api/auth/password', () => {
+  const url = 'http://localhost/api/auth/password';
+
+  test('refuses a wrong current password', async () => {
+    const res = (await changePassword({
+      request: post(url, { currentPassword: 'wrong', newPassword: 'brand-new-pass' }),
+    } as never)) as Response;
+    expect(res.status).toBe(401);
+    expect((await body(res)).error).toBe('Current password is incorrect');
+  });
+
+  test('rejects a new password below the minimum length', async () => {
+    const short = 'a'.repeat(MIN_PASSWORD_LENGTH - 1);
+    const res = (await changePassword({
+      request: post(url, { currentPassword: PASSWORD, newPassword: short }),
+    } as never)) as Response;
+    expect(res.status).toBe(400);
+    expect((await body(res)).error).toBe(`New password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  });
+
+  test('rejects a new password equal to the current one', async () => {
+    const res = (await changePassword({
+      request: post(url, { currentPassword: PASSWORD, newPassword: PASSWORD }),
+    } as never)) as Response;
+    expect(res.status).toBe(400);
+    expect((await body(res)).error).toBe('New password must differ from the current one');
+  });
+
+  test('a malformed body is a 400 before any password check', async () => {
+    const res = (await changePassword({ request: post(url, 'not json') } as never)) as Response;
+    expect(res.status).toBe(400);
+    expect((await body(res)).error).toBe('Invalid request body');
+  });
+
+  test('verifies the current password before the length rule', async () => {
+    const res = (await changePassword({
+      request: post(url, { currentPassword: 'wrong', newPassword: 'x' }),
+    } as never)) as Response;
+    expect(res.status).toBe(401);
+  });
+
+  test('changes the password and invalidates tokens minted for the old one', async () => {
+    const before = loadAuthConfig()!;
+    const oldToken = issueSessionToken({ sessionSecret: before.sessionSecret, credentialKey: before.credentialKey });
+
+    const res = (await changePassword({
+      request: post(url, { currentPassword: PASSWORD, newPassword: 'brand-new-pass' }),
+    } as never)) as Response;
+    expect(res.status).toBe(200);
+    expect(await body(res)).toEqual({ success: true, sessionsRevoked: true, persistsUntilRestart: true });
+
+    const after = loadAuthConfig()!;
+    expect(await verifyPassword('brand-new-pass', after.passwordHash)).toBe(true);
+    expect(await verifyPassword(PASSWORD, after.passwordHash)).toBe(false);
+    // The old cookie carries a fingerprint of the old credential key, so it
+    // dies here.
+    expect(await stateWith(oldToken)).toEqual({ required: true, authenticated: false });
+    // This browser got a replacement cookie for the new key.
+    expect(await stateWith(tokenFrom(res))).toEqual({ required: true, authenticated: true });
+  });
+
+  // Same regression as revoke, different cause: the new password derives a new
+  // credential key, so the presented token stops verifying the moment it is
+  // applied. The lifetime has to be read BEFORE that.
+  test('the replacement cookie keeps the lifetime the session already had', async () => {
+    const config = loadAuthConfig()!;
+    const weekToken = issueSessionToken({
+      sessionSecret: config.sessionSecret,
+      credentialKey: config.credentialKey,
+      ttlMs: TRUSTED_DEVICE_TTL_MS,
+    });
+    const res = (await changePassword({
+      request: post(url, { currentPassword: PASSWORD, newPassword: 'brand-new-pass' }, {
+        headers: { cookie: `omp_session=${encodeURIComponent(weekToken)}` },
+      }),
+    } as never)) as Response;
+    const maxAge = Number(/Max-Age=(\d+)/.exec(res.headers.get('set-cookie') ?? '')?.[1]);
+    expect(maxAge).toBeGreaterThan(TRUSTED_DEVICE_TTL_MS / 1000 - 60);
+    expect(maxAge).toBeLessThanOrEqual(TRUSTED_DEVICE_TTL_MS / 1000);
+  });
+
+  test('a wrong verb is a 405', async () => {
+    const res = (await changePassword({
+      request: new Request(url, { method: 'GET' }),
+    } as never)) as Response;
+    expect(res.status).toBe(405);
+  });
+});
+
+describe('POST /api/auth/logout', () => {
+  test('clears the cookie for the requesting host:port', async () => {
+    const res = (await logout({
+      request: new Request('http://localhost:5173/api/auth/logout', {
+        method: 'POST',
+        headers: { host: 'localhost:5173' },
+      }),
+    } as never)) as Response;
+    expect(res.status).toBe(200);
+    expect(await body(res)).toEqual({ success: true });
+    const header = res.headers.get('set-cookie') ?? '';
+    // Port-scoped: signing out of one instance must not sign the user out of
+    // another instance on a different port.
+    expect(header).toContain('omp_session_5173=');
+    expect(header).toContain('Max-Age=0');
+    expect(header).toContain('Expires=Thu, 01 Jan 1970 00:00:00 GMT');
+  });
+
+  test('is public: it works with no auth configured at all', async () => {
+    await initAuth(null);
+    const res = (await logout({
+      request: new Request('http://localhost/api/auth/logout', { method: 'POST' }),
+    } as never)) as Response;
+    expect(res.status).toBe(200);
+    expect(await body(res)).toEqual({ success: true });
+  });
+
+  test('a wrong verb is a 405', async () => {
+    const res = (await logout({
+      request: new Request('http://localhost/api/auth/logout', { method: 'GET' }),
+    } as never)) as Response;
+    expect(res.status).toBe(405);
+  });
+});
+
+describe('auth routes when no password is configured', () => {
+  beforeEach(async () => {
+    await initAuth(null);
+  });
+
+  test('login refuses with 400 rather than pretending to check', async () => {
+    const res = (await login({
+      request: post('http://localhost/api/auth/login', { password: PASSWORD }),
+    } as never)) as Response;
+    expect(res.status).toBe(400);
+    expect((await body(res)).error).toBe('UI authentication is not enabled');
+  });
+
+  test('password change refuses with 400', async () => {
+    const res = (await changePassword({
+      request: post('http://localhost/api/auth/password', { currentPassword: '', newPassword: 'whatever-1' }),
+    } as never)) as Response;
+    expect(res.status).toBe(400);
+    expect((await body(res)).error).toBe('UI authentication is not enabled');
+  });
+
+  test('state reports not required and authenticated', async () => {
+    const res = (await authState({ request: new Request('http://localhost/api/auth/state') } as never)) as Response;
+    expect(await body(res)).toEqual({ required: false, authenticated: true });
+  });
+});

package/src/server/routes/auth/state.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `GET /api/auth/state` — whether a password is required, and whether THIS
+ * request carries a valid session.
+ *
+ * Public by necessity: the client asks before it has a session, and the answer
+ * is the only thing that tells it whether to render the login screen or the app.
+ * It therefore reports two booleans and nothing else — no version, no hint about
+ * the password, no session detail.
+ */
+
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import type { LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { loadAuthConfig } from '@/server/lib/auth/guard';
+import { readSessionCookie, verifySessionToken } from '@/server/lib/auth/token';
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const config = loadAuthConfig();
+
+  if (!config) {
+    return json({ required: false, authenticated: true }, { headers: NO_STORE_HEADERS });
+  }
+
+  const authenticated = verifySessionToken(readSessionCookie(request), {
+    sessionSecret: config.sessionSecret,
+    credentialKey: config.credentialKey,
+  });
+
+  return json({ required: true, authenticated }, { headers: NO_STORE_HEADERS });
+}

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

@@ -0,0 +1,6 @@
+import { bindingsFor, type HandlerBinding } from '@/server/lib/route-adapter';
+import * as browserStream from '@/server/routes/browser/stream';
+
+export const browserBindings: HandlerBinding[] = [
+  ...bindingsFor(browserStream, '/api/browser/:sessionId/stream'),
+];

package/src/server/routes/browser/stream.test.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The SSE contract of `GET /api/browser/:sessionId/stream`.
+ *
+ * This is the browser-panel transport: the route answers with a long-lived
+ * `text/event-stream` rather than a JSON body, and it deliberately does NOT
+ * error when the agent, the shared browser, or a tab is missing — each of those
+ * can appear later in the session's life, so the stream reports a coarse state
+ * and keeps polling. The two states reachable without a real Chromium are the
+ * ones pinned here: `browser-offline` under MOCK, and `agent-offline` for a
+ * session this process does not run. The stream must also be cancellable —
+ * a client disconnect has to clear the 1s poll timer, or the test process (and
+ * the server) would keep a timer alive for every abandoned panel.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { loader } from '@/server/routes/browser/stream';
+
+const originalMock = Bun.env.MOCK;
+const UNKNOWN_SESSION = 'stream-test-unknown-session';
+
+beforeEach(() => {
+  delete Bun.env.MOCK;
+});
+
+afterEach(() => {
+  if (originalMock === undefined) delete Bun.env.MOCK;
+  else Bun.env.MOCK = originalMock;
+});
+
+afterAll(() => {
+  delete Bun.env.MOCK;
+});
+
+function requestFor(sessionId: string, target?: string): Request {
+  const url = new URL(`http://localhost/api/browser/${sessionId}/stream`);
+  if (target !== undefined) url.searchParams.set('target', target);
+  return new Request(url);
+}
+
+/**
+ * Read exactly one SSE frame from the stream, then cancel it so the route's
+ * poll timer and heartbeat are torn down with it.
+ */
+async function firstFrame(res: Response): Promise<{ frame: string; text: string }> {
+  const reader = res.body!.getReader();
+  const { value } = await reader.read();
+  const text = new TextDecoder().decode(value);
+  await reader.cancel();
+  const end = text.indexOf('\n\n');
+  return { frame: text.slice(0, end === -1 ? text.length : end + 2), text };
+}
+
+describe('browser stream framing', () => {
+  test('answers a cancellable SSE response with its own cache policy', async () => {
+    const res = (await loader({ params: { sessionId: UNKNOWN_SESSION }, request: requestFor(UNKNOWN_SESSION) } as never)) as Response;
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/event-stream');
+    // Overrides the shared default: a proxy must not transform or buffer frames.
+    expect(res.headers.get('cache-control')).toBe('no-cache, no-transform');
+    await res.body!.cancel();
+  });
+
+  test('MOCK mode reports the browser offline instead of touching a daemon', async () => {
+    Bun.env.MOCK = '1';
+    const res = (await loader({ params: { sessionId: UNKNOWN_SESSION }, request: requestFor(UNKNOWN_SESSION) } as never)) as Response;
+    const { frame } = await firstFrame(res);
+    expect(frame).toBe('event: state\ndata: {"status":"browser-offline","tabs":[]}\n\n');
+  });
+
+  test('a session this process does not run reports the agent offline', async () => {
+    const res = (await loader({ params: { sessionId: UNKNOWN_SESSION }, request: requestFor(UNKNOWN_SESSION) } as never)) as Response;
+    const { frame } = await firstFrame(res);
+    expect(frame).toBe('event: state\ndata: {"status":"agent-offline","tabs":[]}\n\n');
+  });
+
+  test('an absent sessionId is treated as an unknown session, not a crash', async () => {
+    const res = (await loader({ params: {}, request: requestFor('x') } as never)) as Response;
+    const { frame } = await firstFrame(res);
+    expect(frame).toContain('"status":"agent-offline"');
+  });
+
+  test('the target query parameter is accepted without changing the framing', async () => {
+    const res = (await loader({
+      params: { sessionId: UNKNOWN_SESSION },
+      request: requestFor(UNKNOWN_SESSION, 'target-42'),
+    } as never)) as Response;
+    expect(res.status).toBe(200);
+    const { frame } = await firstFrame(res);
+    expect(frame).toContain('"status":"agent-offline"');
+  });
+
+  test('cancelling the stream closes it and stops the poll timer', async () => {
+    const res = (await loader({ params: { sessionId: UNKNOWN_SESSION }, request: requestFor(UNKNOWN_SESSION) } as never)) as Response;
+    const reader = res.body!.getReader();
+    await reader.read();
+    await reader.cancel();
+    // The cancel tears the stream down, so the poll interval and heartbeat are
+    // cleared with it and the next read is already done.
+    expect((await reader.read()).done).toBe(true);
+  });
+});

package/src/server/routes/browser/stream.ts

@@ -0,0 +1,217 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * GET /api/browser/:sessionId/stream — SSE stream of the browser tab that the
+ * session's own omp process drives inside the project-shared Chromium.
+ *
+ * Events:
+ * - `state` → BrowserViewState JSON (status: agent-offline | browser-offline |
+ *   no-tab | live, plus url/title/targetId/tabs when known)
+ * - `frame` → BrowserViewFrame JSON (base64 JPEG + dimensions + targetId)
+ *
+ * While the agent, the shared browser, or an agent-owned tab is missing, the
+ * route emits a coarse state and keeps polling every 1s instead of erroring —
+ * any of those can appear later in the session's life. The stream stays scoped
+ * to this session's own tabs: the daemon is project-shared, so neither the
+ * framebuffer nor the tab list ever falls back to another session's page.
+ * Frames are dropped under
+ * consumer backpressure (desiredSize < 0); the screencast itself is already
+ * acked upstream, so dropping is lossless latest-wins.
+ */
+
+import type { LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { isMockMode } from '@/server/mock.server';
+import { extractEvalActions } from '@/shared/lib/browser/activity';
+
+import { isRecord } from '@/shared/lib/util/guards';
+import { getRpcSession } from '@/server/lib/omp/rpc/session-registry';
+import { findProjectRuntimeDir, readOwnedTargetIds } from '@/server/lib/browser/runtime';
+import { openScreencast, type ScreencastHandle } from '@/shared/lib/browser/viewer';
+import { type TargetWatcherHandle, watchOwnedTargets } from '@/shared/lib/browser/watcher';
+import type { BrowserPanelAction, BrowserViewFrame, BrowserViewState } from '@/shared/types';
+import { createSseStream } from '@/server/lib/sse';
+import { BROWSER_POLL_MS, STREAM_HEARTBEAT_MS } from '@/shared/lib/workspace/refresh-cadence';
+
+const BROWSER_OFFLINE: BrowserViewState = { status: 'browser-offline', tabs: [] };
+
+export async function loader({ params, request }: LoaderFunctionArgs) {
+  const sessionId = params.sessionId ?? '';
+  const preferTargetId = new URL(request.url).searchParams.get('target') ?? undefined;
+
+  let closed = false;
+
+  const stream = createSseStream({
+    heartbeatMs: STREAM_HEARTBEAT_MS,
+    signal: request.signal,
+    headers: { 'Cache-Control': 'no-cache, no-transform' },
+    onStart(handlers) {
+      let lastStateKey = '';
+      let viewer: ScreencastHandle | null = null;
+      let viewerWsUrl: string | null = null;
+      let watcher: TargetWatcherHandle | null = null;
+      let watcherWsUrl: string | null = null;
+      let tickInFlight = false;
+      let pollTimer: ReturnType<typeof setInterval> | null = null;
+      let actionSeq = 0;
+      let agentSource: unknown = null;
+      let unsubscribeAgent: (() => void) | null = null;
+
+      const detachViewer = (): void => {
+        const current = viewer;
+        viewer = null;
+        viewerWsUrl = null;
+        if (!current) return;
+        try {
+          current.close();
+        } catch {
+          // Already closed by a disconnect callback.
+        }
+      };
+
+      const dropWatcher = (): void => {
+        const current = watcher;
+        watcher = null;
+        watcherWsUrl = null;
+        current?.close();
+      };
+
+      const cleanup = (): void => {
+        if (closed) return;
+        closed = true;
+        detachViewer();
+        dropWatcher();
+        unsubscribeAgent?.();
+        unsubscribeAgent = null;
+        agentSource = null;
+        if (pollTimer !== null) clearInterval(pollTimer);
+        pollTimer = null;
+        handlers.close();
+      };
+
+      const emitState = (state: BrowserViewState): void => {
+        const key = JSON.stringify(state);
+        if (key === lastStateKey) return;
+        lastStateKey = key;
+        handlers.send('state', state);
+      };
+
+      const emitAction = (action: { kind: BrowserPanelAction['kind']; label: string }): void => {
+        actionSeq += 1;
+        const payload: BrowserPanelAction = { id: `act-${actionSeq}`, kind: action.kind, label: action.label };
+        handlers.send('action', payload);
+      };
+
+      const emitFrame = (frame: BrowserViewFrame): void => {
+        // Backpressure: keep at most a couple of pending frames; drop the rest.
+        if (handlers.isBackpressured()) return;
+        handlers.send('frame', frame);
+      };
+
+      const tick = async (): Promise<void> => {
+        if (closed || tickInFlight) return;
+        tickInFlight = true;
+        try {
+          if (isMockMode()) {
+            detachViewer();
+            emitState(BROWSER_OFFLINE);
+            return;
+          }
+          const session = getRpcSession(sessionId);
+          if (!session || !session.isAlive()) {
+            dropWatcher();
+            unsubscribeAgent?.();
+            unsubscribeAgent = null;
+            agentSource = null;
+            detachViewer();
+            emitState({ status: 'agent-offline', tabs: [] });
+            return;
+          }
+          if (agentSource !== session) {
+            unsubscribeAgent?.();
+            agentSource = session;
+            unsubscribeAgent = session.onEvent((event) => {
+              if (typeof event.toolName !== 'string' || event.toolName !== 'eval') return;
+              if (event.type === 'tool_execution_start') {
+                const args = isRecord(event.args) ? event.args : {};
+                for (const action of extractEvalActions({ code: args.code, title: args.title })) {
+                  emitAction(action);
+                }
+                void tick();
+              } else if (event.type === 'tool_execution_update') {
+                void tick();
+              } else if (event.type === 'tool_execution_end' && event.isError === true) {
+                emitAction({ kind: 'error', label: 'Aksi browser gagal' });
+              }
+            });
+          }
+          const pid = session.pid;
+          const runtime = pid === undefined ? null : await findProjectRuntimeDir(session.cwd);
+          if (closed) return;
+          if (!runtime || pid === undefined) {
+            dropWatcher();
+            detachViewer();
+            emitState(BROWSER_OFFLINE);
+            return;
+          }
+          if (!watcher || watcherWsUrl !== runtime.wsUrl) {
+            dropWatcher();
+            const started = await watchOwnedTargets(runtime.wsUrl, {
+              getOwnedTargetIds: () => readOwnedTargetIds(runtime.runtimeDir, runtime.daemonName, pid),
+              onOwnedTarget: () => {
+                void tick();
+              },
+            }).catch(() => null);
+            if (closed) {
+              started?.close();
+              return;
+            }
+            watcher = started;
+            watcherWsUrl = started ? runtime.wsUrl : null;
+          }
+          const ownedIds = await readOwnedTargetIds(runtime.runtimeDir, runtime.daemonName, pid);
+          if (closed) return;
+          if (ownedIds.length === 0) {
+            detachViewer();
+            emitState({ status: 'no-tab', tabs: [] });
+            return;
+          }
+          if (viewer && viewerWsUrl !== runtime.wsUrl) detachViewer();
+          if (!viewer) {
+            const handle = await openScreencast(runtime.wsUrl, {
+              preferTargetId,
+              getOwnedTargetIds: () => readOwnedTargetIds(runtime.runtimeDir, runtime.daemonName, pid),
+              onFrame: emitFrame,
+              onAction: (action) => emitAction(action),
+              onState: (state) => {
+                emitState(state);
+                if (state.status === 'browser-offline') detachViewer();
+              },
+            });
+            if (closed) {
+              handle.close();
+              return;
+            }
+            viewer = handle;
+            viewerWsUrl = runtime.wsUrl;
+          }
+        } catch {
+          // Transient fs/CDP failure: keep the stream open and retry next tick.
+        } finally {
+          tickInFlight = false;
+        }
+      };
+
+      pollTimer = setInterval(() => {
+        void tick();
+      }, BROWSER_POLL_MS);
+      void tick();
+
+      return cleanup;
+    },
+  });
+
+  return stream.response;
+}