@harness-fe/mcp-server 3.0.1

package/src/dashboardSpa.ts

@@ -0,0 +1,195 @@
+/**
+ * HTTP handler that serves the React SPA built by `@harness-fe/dashboard-ui`.
+ *
+ * Routing rules (after the `isAuthorized` middleware in bridge.ts):
+ *   - GET /                          → 302 to /dashboard/?token=<preserved> (legacy root)
+ *   - GET /sessions/:id              → 302 to /dashboard/sessions/:id?token=… (legacy bookmarks)
+ *   - GET /dashboard                 → 302 to /dashboard/?token=<preserved>
+ *   - GET /dashboard/                → serve index.html (SPA shell)
+ *   - GET /dashboard/<asset.ext>     → serve that file from dist/ (if it exists)
+ *   - GET /dashboard/<other-path>    → serve index.html (SPA client-side routing)
+ *
+ * The dist directory is resolved at module load via `require.resolve()` on
+ * the dashboard-ui package — same trick `replayViewer.ts` uses for
+ * rrweb-player. No copy step needed; pnpm workspace symlinks just work in
+ * dev, and `pnpm deploy` bundles the dist into the published tarball.
+ */
+
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, join, resolve as resolvePath } from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { DEFAULT_COOKIE_NAME } from './auth.js';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * If a request arrived with `?token=` AND no harness_fe_token cookie yet,
+ * stamp the cookie and 302 back to the same path without the query.
+ *
+ * Why this matters: the SPA bundle is loaded by the browser as
+ * `<script src="/dashboard/assets/index-XXX.js">` — relative paths without
+ * the token query — which would 401 against the upstream auth middleware.
+ * Setting the cookie on the first HTML request means every subsequent
+ * same-origin fetch (assets, /api/*, WebSocket upgrade) is automatically
+ * authenticated, and the visible URL stays clean.
+ */
+function maybeHandleTokenHandoff(req: IncomingMessage, res: ServerResponse, url: URL): boolean {
+    const tokenInQuery = url.searchParams.get('token');
+    if (!tokenInQuery) return false;
+    // If the cookie's already set with the same value, nothing to do —
+    // pass through (the browser will follow links without ?token=).
+    const cookies = req.headers.cookie ?? '';
+    if (cookies.includes(`${DEFAULT_COOKIE_NAME}=`)) return false;
+    // Strip token from the URL and 302 back to the canonical path so the
+    // browser bookmarks / shares clean URLs. The cookie carries auth from
+    // here on. Also normalize `/dashboard` → `/dashboard/` in the same hop
+    // so we don't waste a second redirect chasing the trailing slash.
+    url.searchParams.delete('token');
+    const canonicalPath = url.pathname === '/dashboard' ? '/dashboard/' : url.pathname;
+    const remaining = url.searchParams.toString();
+    const clean = `${canonicalPath}${remaining ? '?' + remaining : ''}`;
+    const cookie =
+        `${DEFAULT_COOKIE_NAME}=${encodeURIComponent(tokenInQuery)}; ` +
+        // Path=/ so /api/*, /replay/*, /dashboard/* all see it.
+        // SameSite=Lax keeps the cookie on cross-tab nav.
+        // No HttpOnly: the SPA's WS code may want to surface the token in
+        //   a Bearer header for tools that don't share cookies (rare —
+        //   browsers attach cookies to WS, so this is just defense in depth).
+        // 30-day Max-Age matches the /__auth login flow.
+        `Path=/; SameSite=Lax; Max-Age=2592000`;
+    res.statusCode = 302;
+    res.setHeader('set-cookie', cookie);
+    res.setHeader('location', clean);
+    res.setHeader('cache-control', 'no-store');
+    res.end();
+    return true;
+}
+
+function resolveDashboardDist(): string | undefined {
+    try {
+        const pkgPath = require.resolve('@harness-fe/dashboard-ui/package.json');
+        const dist = join(dirname(pkgPath), 'dist');
+        return existsSync(join(dist, 'index.html')) ? dist : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.txt': 'text/plain; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+};
+
+function contentTypeFor(filePath: string): string {
+    return CONTENT_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+
+export function createDashboardSpaHandler(): (
+    req: IncomingMessage,
+    res: ServerResponse,
+) => boolean {
+    const dist = resolveDashboardDist();
+    return (req, res) => {
+        if (!req.url) return false;
+        const url = new URL(req.url, 'http://localhost');
+        const path = url.pathname;
+        const method = req.method ?? 'GET';
+        if (method !== 'GET' && method !== 'HEAD') return false;
+
+        // Legacy paths from the old server-rendered dashboard — redirect into
+        // the SPA preserving the token query so the user stays authenticated.
+        if (path === '/' || path === '/index.html') {
+            res.statusCode = 302;
+            res.setHeader('location', `/dashboard/${url.search ?? ''}`);
+            res.end();
+            return true;
+        }
+        const legacySession = path.match(/^\/sessions\/([^/]+)$/);
+        if (legacySession) {
+            const sid = legacySession[1];
+            res.statusCode = 302;
+            res.setHeader('location', `/dashboard/sessions/${sid}${url.search ?? ''}`);
+            res.end();
+            return true;
+        }
+
+        if (!path.startsWith('/dashboard')) return false;
+
+        // First-load token handoff: ?token=… → cookie + redirect.
+        // Skip for static asset paths; setting the cookie there would still
+        // work but the redirect would break the script tag's request chain.
+        if (!path.startsWith('/dashboard/assets/') && !path.startsWith('/dashboard/static/')) {
+            if (maybeHandleTokenHandoff(req, res, url)) return true;
+        }
+
+        // If dashboard-ui isn't installed (someone using an older deploy
+        // or running tests in isolation), fall through with a friendly
+        // 503 rather than 404 — clearer signal than silent miss.
+        if (!dist) {
+            res.statusCode = 503;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+            res.end('Dashboard UI is not bundled with this build.');
+            return true;
+        }
+
+        // /dashboard with no trailing slash → redirect, preserving token.
+        if (path === '/dashboard') {
+            const search = url.search ?? '';
+            res.statusCode = 302;
+            res.setHeader('location', `/dashboard/${search}`);
+            res.end();
+            return true;
+        }
+
+        // Strip the `/dashboard/` prefix to get the relative path inside dist.
+        const rel = path.slice('/dashboard/'.length) || 'index.html';
+
+        // Path traversal defense: resolve against dist and require the
+        // result is still inside dist. Without this, a crafted URL like
+        // `/dashboard/../../etc/passwd` would escape.
+        const candidate = resolvePath(dist, rel);
+        if (!candidate.startsWith(dist + (dist.endsWith('/') ? '' : '/')) && candidate !== dist) {
+            res.statusCode = 403;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+            res.end('Forbidden');
+            return true;
+        }
+
+        // Serve the file if it exists; otherwise fall back to index.html
+        // so the SPA's client-side router can take over (this is how /sessions/:id
+        // works without server config).
+        const target = existsSync(candidate) ? candidate : join(dist, 'index.html');
+        try {
+            const body = readFileSync(target);
+            res.statusCode = 200;
+            res.setHeader('content-type', contentTypeFor(target));
+            // Hashed assets are immutable; HTML shells should never cache.
+            const isHashed = /\/assets\/.+-[A-Za-z0-9_-]{6,}\.[a-z0-9]+$/.test(target);
+            res.setHeader(
+                'cache-control',
+                isHashed ? 'public, max-age=31536000, immutable' : 'no-store',
+            );
+            res.end(body);
+        } catch (err) {
+            res.statusCode = 500;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+            res.end(`dashboard read error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return true;
+    };
+}

package/src/dashboardUrl.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { buildDashboardUrl } from './dashboardUrl.js';
+import type { IBridge } from './bridge.js';
+
+function makeBridge(opts: { base?: string; token?: string }): IBridge {
+    return {
+        getViewerBaseUrl: () => opts.base,
+        getAuthToken: () => opts.token,
+    } as unknown as IBridge;
+}
+
+describe('buildDashboardUrl', () => {
+    it('returns the project-list URL with token when both are set', () => {
+        const bridge = makeBridge({ base: 'http://127.0.0.1:47729', token: 'abc' });
+        expect(buildDashboardUrl(bridge)).toBe('http://127.0.0.1:47729/dashboard/?token=abc');
+    });
+
+    it('deep-links into a session detail when sessionId is provided', () => {
+        const bridge = makeBridge({ base: 'http://127.0.0.1:47729', token: 'abc' });
+        expect(buildDashboardUrl(bridge, { sessionId: 'sess-1' })).toBe(
+            'http://127.0.0.1:47729/dashboard/sessions/sess-1?token=abc',
+        );
+    });
+
+    it('URL-encodes the session id', () => {
+        const bridge = makeBridge({ base: 'http://127.0.0.1:47729', token: 'tok' });
+        expect(buildDashboardUrl(bridge, { sessionId: 'a/b c' })).toBe(
+            'http://127.0.0.1:47729/dashboard/sessions/a%2Fb%20c?token=tok',
+        );
+    });
+
+    it('omits the token query when no token is configured', () => {
+        const bridge = makeBridge({ base: 'http://127.0.0.1:47729' });
+        expect(buildDashboardUrl(bridge)).toBe('http://127.0.0.1:47729/dashboard/');
+    });
+
+    it('returns undefined when the bridge has no base URL (no bound port yet)', () => {
+        const bridge = makeBridge({});
+        expect(buildDashboardUrl(bridge)).toBeUndefined();
+    });
+
+    it('URL-encodes the token (defensive against weird characters in HARNESS_FE_TOKEN)', () => {
+        const bridge = makeBridge({ base: 'http://127.0.0.1:47729', token: 'a b&c' });
+        expect(buildDashboardUrl(bridge)).toBe('http://127.0.0.1:47729/dashboard/?token=a%20b%26c');
+    });
+});

package/src/dashboardUrl.ts

@@ -0,0 +1,28 @@
+/**
+ * Compose dashboard URLs the user (or agent) should hit.
+ *
+ * Carries the configured auth token in the query string so the browser
+ * lands pre-authenticated. On loopback hosts with no token configured,
+ * the URL is left bare.
+ */
+
+import type { IBridge } from './bridge.js';
+
+export interface DashboardUrlOptions {
+    /** When provided, deep-link to a specific session detail page. */
+    sessionId?: string;
+}
+
+export function buildDashboardUrl(
+    bridge: IBridge,
+    opts: DashboardUrlOptions = {},
+): string | undefined {
+    const base = bridge.getViewerBaseUrl();
+    if (!base) return undefined;
+    const path = opts.sessionId
+        ? `/dashboard/sessions/${encodeURIComponent(opts.sessionId)}`
+        : '/dashboard/';
+    const token = bridge.getAuthToken();
+    const qs = token ? `?token=${encodeURIComponent(token)}` : '';
+    return `${base}${path}${qs}`;
+}

package/src/eventsHandler.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Unit tests for createEventsHandler — POST /events, GET /events/ping, CORS.
+ */
+
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { PROTOCOL_VERSION } from '@harness-fe/protocol';
+import { createEventsHandler } from './eventsHandler.js';
+
+// ─── Minimal IncomingMessage / ServerResponse mocks ──────────────────────────
+
+function makeReq(opts: {
+    url: string;
+    method: string;
+    host?: string;
+    body?: string;
+}): IncomingMessage {
+    const { Readable } = require('node:stream') as typeof import('node:stream');
+    const stream = new Readable({ read() {} });
+    const req = stream as unknown as IncomingMessage;
+    req.url = opts.url;
+    req.method = opts.method;
+    req.headers = opts.host ? { host: opts.host } : {};
+    if (opts.body !== undefined) {
+        process.nextTick(() => {
+            stream.push(Buffer.from(opts.body!));
+            stream.push(null);
+        });
+    } else {
+        process.nextTick(() => stream.push(null));
+    }
+    return req;
+}
+
+interface MockRes {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+    setHeader(name: string, value: string): void;
+    end(data?: string): void;
+}
+
+function makeRes(): MockRes {
+    const res: MockRes = {
+        statusCode: 200,
+        headers: {},
+        body: '',
+        setHeader(name, value) { this.headers[name.toLowerCase()] = value; },
+        end(data) { if (data) this.body = data; },
+    };
+    return res;
+}
+
+// ─── Bridge stub ─────────────────────────────────────────────────────────────
+
+function makeBridge(onBatch?: (hello: unknown, events: unknown[]) => void) {
+    return {
+        handleHttpBatch: vi.fn((hello: unknown, events: unknown[]) => {
+            onBatch?.(hello, events);
+        }),
+    };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('eventsHandler', () => {
+    describe('GET /events/ping', () => {
+        it('returns 200 with ok + version', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events/ping', method: 'GET' });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(true);
+            expect(res.statusCode).toBe(200);
+            const payload = JSON.parse(res.body) as { ok: boolean; version: string };
+            expect(payload.ok).toBe(true);
+            expect(payload.version).toBe(PROTOCOL_VERSION);
+        });
+
+        it('does not set CORS when host is not loopback', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events/ping', method: 'GET', host: 'example.com' });
+            const res = makeRes();
+            await handler(req, res as unknown as ServerResponse);
+            expect(res.headers['access-control-allow-origin']).toBeUndefined();
+        });
+
+        it('sets CORS when host is localhost', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events/ping', method: 'GET', host: 'localhost:47729' });
+            const res = makeRes();
+            await handler(req, res as unknown as ServerResponse);
+            expect(res.headers['access-control-allow-origin']).toBe('*');
+        });
+
+        it('sets CORS when host is 127.0.0.1', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events/ping', method: 'GET', host: '127.0.0.1:47729' });
+            const res = makeRes();
+            await handler(req, res as unknown as ServerResponse);
+            expect(res.headers['access-control-allow-origin']).toBe('*');
+        });
+    });
+
+    describe('OPTIONS preflight', () => {
+        it('returns 204 for /events', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events', method: 'OPTIONS', host: 'localhost:47729' });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(true);
+            expect(res.statusCode).toBe(204);
+        });
+
+        it('returns 204 for /events/ping', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events/ping', method: 'OPTIONS', host: 'localhost:47729' });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(true);
+            expect(res.statusCode).toBe(204);
+        });
+    });
+
+    describe('POST /events', () => {
+        it('returns 204 and calls handleHttpBatch with valid body', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const body = JSON.stringify({
+                hello: {
+                    role: 'node-runtime',
+                    projectId: 'test-proj',
+                    sessionId: 'sess-abc',
+                    buildId: 'build-1',
+                },
+                events: [
+                    { id: 'e1', name: 'server-err', ts: 1000, payload: { message: 'boom' } },
+                    { id: 'e2', name: 'server-log', ts: 1001, payload: { level: 'info' } },
+                ],
+            });
+            const req = makeReq({ url: '/events', method: 'POST', host: 'localhost:47729', body });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(true);
+            expect(res.statusCode).toBe(204);
+            expect(bridge.handleHttpBatch).toHaveBeenCalledOnce();
+            const [hello, events] = bridge.handleHttpBatch.mock.calls[0] as [unknown, unknown[]];
+            expect((hello as { projectId: string }).projectId).toBe('test-proj');
+            expect(events).toHaveLength(2);
+        });
+
+        it('returns 400 for invalid JSON', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events', method: 'POST', host: 'localhost:47729', body: '{bad json' });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(true);
+            expect(res.statusCode).toBe(400);
+            expect(bridge.handleHttpBatch).not.toHaveBeenCalled();
+        });
+
+        it('returns 400 when body fails schema validation (bad role)', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const body = JSON.stringify({
+                hello: {
+                    role: 'runtime-client', // wrong role
+                    projectId: 'test',
+                },
+                events: [],
+            });
+            const req = makeReq({ url: '/events', method: 'POST', host: 'localhost:47729', body });
+            const res = makeRes();
+            await handler(req, res as unknown as ServerResponse);
+            expect(res.statusCode).toBe(400);
+        });
+
+        it('returns 400 when hello.projectId is missing', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const body = JSON.stringify({
+                hello: { role: 'node-runtime' },
+                events: [],
+            });
+            const req = makeReq({ url: '/events', method: 'POST', host: 'localhost:47729', body });
+            const res = makeRes();
+            await handler(req, res as unknown as ServerResponse);
+            expect(res.statusCode).toBe(400);
+        });
+
+        it('returns 500 when handleHttpBatch throws', async () => {
+            const bridge = {
+                handleHttpBatch: vi.fn(() => { throw new Error('store error'); }),
+            };
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const body = JSON.stringify({
+                hello: { role: 'node-runtime', projectId: 'test', sessionId: 's1' },
+                events: [],
+            });
+            const req = makeReq({ url: '/events', method: 'POST', host: 'localhost:47729', body });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(true);
+            expect(res.statusCode).toBe(500);
+        });
+    });
+
+    describe('fall-through for unmatched routes', () => {
+        it('returns false for /other', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/other', method: 'GET' });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(false);
+        });
+
+        it('returns false for /events/unknown-sub-path', async () => {
+            const bridge = makeBridge();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const handler = createEventsHandler(bridge as any);
+            const req = makeReq({ url: '/events/unknown', method: 'GET' });
+            const res = makeRes();
+            const handled = await handler(req, res as unknown as ServerResponse);
+            expect(handled).toBe(false);
+        });
+    });
+});

package/src/eventsHandler.ts

@@ -0,0 +1,136 @@
+/**
+ * HTTP POST /events handler — stateless alternative to the WebSocket path.
+ *
+ * Accepts a JSON body matching `httpBatchSchema`:
+ *   { hello: { role: 'node-runtime', projectId, sessionId, ... },
+ *     events: [ { id, name, ts, payload, ... }, ... ] }
+ *
+ * Each POST is treated as a one-shot hello+events sequence:
+ *   1. Register (or re-register) the peer via the same bridge internals.
+ *   2. Persist every event to the right session timeline.
+ *   3. Respond 204 No Content.
+ *
+ * Also handles:
+ *   GET /events/ping  → 200 { ok: true, version }
+ *   OPTIONS /events   → 204 CORS preflight
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { PROTOCOL_VERSION, httpBatchSchema } from '@harness-fe/protocol';
+import type { Bridge } from './bridge.js';
+
+// ─── CORS helpers ────────────────────────────────────────────────────────────
+
+function isLoopback(req: IncomingMessage): boolean {
+    const host = req.headers['host'] ?? '';
+    // Match 127.0.0.1:* and localhost:*
+    return /^(127\.0\.0\.1|localhost)(:\d+)?$/.test(host);
+}
+
+function setCorsHeaders(res: ServerResponse): void {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'content-type');
+}
+
+// ─── Body reader ─────────────────────────────────────────────────────────────
+
+function readBody(req: IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const chunks: Buffer[] = [];
+        req.on('data', (chunk: Buffer) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a handler that matches /events/* routes and returns `true` when it
+ * handled the request (so the bridge can short-circuit its 404 fallback).
+ */
+export function createEventsHandler(
+    bridge: Bridge,
+): (req: IncomingMessage, res: ServerResponse) => Promise<boolean> {
+    return async (req, res): Promise<boolean> => {
+        const url = req.url ?? '';
+        const method = req.method ?? 'GET';
+
+        // Only intercept /events and /events/ping
+        if (url !== '/events' && url !== '/events/ping') return false;
+
+        // CORS: only emit headers when request comes from loopback
+        if (isLoopback(req)) {
+            setCorsHeaders(res);
+        }
+
+        // Preflight for both routes
+        if (method === 'OPTIONS') {
+            res.statusCode = 204;
+            res.end();
+            return true;
+        }
+
+        // GET /events/ping
+        if (url === '/events/ping' && method === 'GET') {
+            res.statusCode = 200;
+            res.setHeader('content-type', 'application/json; charset=utf-8');
+            res.end(JSON.stringify({ ok: true, version: PROTOCOL_VERSION }));
+            return true;
+        }
+
+        // POST /events
+        if (url === '/events' && method === 'POST') {
+            let rawBody: string;
+            try {
+                rawBody = await readBody(req);
+            } catch {
+                res.statusCode = 400;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ error: 'failed to read request body' }));
+                return true;
+            }
+
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(rawBody);
+            } catch {
+                res.statusCode = 400;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ error: 'invalid JSON' }));
+                return true;
+            }
+
+            const validated = httpBatchSchema.safeParse(parsed);
+            if (!validated.success) {
+                res.statusCode = 400;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ error: validated.error.message }));
+                return true;
+            }
+
+            const { hello, events } = validated.data;
+
+            try {
+                bridge.handleHttpBatch(hello, events);
+            } catch (err) {
+                res.statusCode = 500;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({
+                    error: err instanceof Error ? err.message : 'internal error',
+                }));
+                return true;
+            }
+
+            res.statusCode = 204;
+            res.end();
+            return true;
+        }
+
+        return false;
+    };
+}
+
+export type EventsHandler = ReturnType<typeof createEventsHandler>;

package/src/index.ts

@@ -0,0 +1,26 @@
+export { Bridge, defaultDataDir, type BridgeOptions } from './bridge.js';
+export { createDaemon, type DaemonOptions, type DaemonHandle } from './daemon.js';
+export { SessionRouter, type PeerSession } from './sessionRouter.js';
+export { startMcpStdioServer } from './mcp.js';
+export { startMcpHttpServer, type McpHttpOptions, type McpHttpHandle } from './mcpHttp.js';
+export {
+    JsonlStore,
+    JsonTaskStore,
+    JsonMemoryStore,
+    MemoryEventStore,
+    sanitizeId,
+    type MemoryEventStoreOptions,
+} from './store/index.js';
+export type {
+    IStore,
+    ITaskStore,
+    IMemoryStore,
+    EventStore,
+    EventId,
+    StreamId,
+    ProjectMeta,
+    ProjectTreeNode,
+    BuildMeta,
+    SessionMeta,
+    TabMeta,
+} from './store/index.js';