@orboto/mcp 0.178.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright © 2026 Daniel Schemann
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @orboto/mcp
+
+Model Context Protocol server for [orboto](https://github.com/orboto/orboto) - a self-hosted ticket and project management platform. Connect Claude Desktop, Cursor, GitHub Copilot Chat, or any MCP-aware AI client and operate orboto as a structured set of tools.
+
+131 tools cover tickets, projects, milestones, time tracking, documents, primer facts, alerts and absences. Every call respects the caller's permission set - what the API key behind the MCP session cannot do in the web UI, the MCP session cannot do either.
+
+## Quickstart
+
+There are two ways to authenticate the stdio proxy:
+
+- **OAuth login (recommended for people).** Omit `ORBOTO_API_KEY`. On first use the proxy opens your browser to the orboto login (which is your SSO login when SSO is configured), you approve once, and it keeps a short-lived, self-refreshing session cached on disk. Nothing to paste, nothing long-lived.
+- **API key (service accounts / CI).** Set `ORBOTO_API_KEY` to an `orb_…` key from **Profile → API keys → Generate**. Best for headless machines with no browser.
+
+### Claude Desktop - OAuth login (no token)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "orboto": {
+      "command": "npx",
+      "args": ["-y", "@orboto/mcp"],
+      "env": {
+        "ORBOTO_API_URL": "https://orboto.example.com/api"
+      }
+    }
+  }
+}
+```
+
+The first launch opens your browser to authorize. The refresh token is cached at `~/.config/orboto/mcp-oauth.json` (mode `0600`), so subsequent launches reconnect silently. On a headless host with no browser, the proxy prints the authorization URL to stderr for manual paste, or fall back to the API-key form below.
+
+### Claude Desktop - API key (service accounts)
+
+```json
+{
+  "mcpServers": {
+    "orboto": {
+      "command": "npx",
+      "args": ["-y", "@orboto/mcp"],
+      "env": {
+        "ORBOTO_API_URL": "https://orboto.example.com/api",
+        "ORBOTO_API_KEY": "orb_…"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Same shape under `.cursor/mcp.json` or `.vscode/mcp.json` in your workspace root (or the user-level equivalent).
+
+### Verify
+
+Ask the AI: **"List my orboto projects."** The model picks `orboto_list_projects`, the call goes through MCP → REST API → back, and your projects come back as a list. If you see "no projects matched" but you know you're a member of some, the auth is working - re-check who the API key belongs to in **Profile → API keys**.
+
+## Self-Hosted-Inline mode (HTTP)
+
+If your orboto host runs the bundled MCP container (default on the official `docker-compose.yml`), every client on your network can use it directly via Streamable HTTP - no `npx` and no per-laptop install:
+
+```json
+{
+  "mcpServers": {
+    "orboto": {
+      "type": "streamable-http",
+      "url": "https://orboto.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer orb_…"
+      }
+    }
+  }
+}
+```
+
+The `/mcp` path on the main host is proxied to the bundled MCP container - no separate subdomain or cert needed. Both modes (stdio via npm, HTTP via host) hit the same tool surface.
+
+> **stdio-first CLIs (e.g. Codex):** prefer the stdio proxy (`npx @orboto/mcp`) over an HTTP+OAuth URL. Some CLIs handle the OAuth session refresh and session-expiry re-init poorly and can lose their tools after a while or after a server deploy; the stdio proxy avoids that churn. Claude Desktop, Cursor, and VS Code Copilot are known-good over HTTP+OAuth.
+
+**Codex CLI** reads TOML from `~/.codex/config.toml` - add an `[mcp_servers.orboto]` table pointing at the stdio proxy:
+
+```toml
+[mcp_servers.orboto]
+command = "npx"
+args = ["-y", "@orboto/mcp"]
+env = { ORBOTO_API_URL = "https://orboto.example.com/api", ORBOTO_API_KEY = "orb_…", ORBOTO_MCP_CLIENT = "codex" }
+```
+
+Omit `ORBOTO_API_KEY` to use OAuth login instead. `codex mcp add` writes the same block from the CLI.
+
+## Environment
+
+| Variable | Required | Effect |
+|---|---|---|
+| `ORBOTO_API_URL` | yes | Base URL of the orboto REST API. Typically `https://<your-host>/api`. No trailing slash. |
+| `ORBOTO_API_KEY` | no | API key starting with `orb_…`. When set, the proxy authenticates with it (service-account path). When omitted, the stdio proxy bootstraps via OAuth (browser login). |
+| `ORBOTO_AUTH` | no | `pat` or `oauth`. Defaults to `pat` when `ORBOTO_API_KEY` is set, else `oauth`. Force `oauth` to run the browser login even with a key present. |
+| `ORBOTO_MCP_TOKEN_CACHE` | no | Override the OAuth token cache path (default `~/.config/orboto/mcp-oauth.json`). |
+| `ORBOTO_MCP_NO_BROWSER` | no | Set to `1` to print the authorization URL instead of auto-opening a browser (headless hosts). |
+| `ORBOTO_MCP_TRANSPORT` | no | `stdio` (default) or `http`. Stdio is the right choice for `npx`-launched clients. |
+| `ORBOTO_MCP_TOOLSET` | no | `minimal`, `curated` (default) or `full`. Curated is the measured high-frequency set (31 tools, ~7.8k tokens of schemas at connect) - the whole REST API stays reachable via `orboto_api_search` + `orboto_api_call`. `full` registers every named tool (175, ~39.5k tokens). `minimal` is the daily loop only (12 tools, ~2.8k tokens including the instructions block) for local models with an 8k/16k context window. HTTP clients can pick per connection instead: `?toolset=minimal` on the `/mcp` URL or an `x-orboto-toolset: minimal` header. |
+| `ORBOTO_MCP_PORT` | no | Listen port when transport is `http`. Default `3100`. |
+| `ORBOTO_MCP_CLIENT` | no | User-agent suffix that lands in the API audit log. Useful for filtering audit rows by client. |
+
+## Version compatibility
+
+Each `@orboto/mcp` release matches a specific orboto API version - the tag on this package is the same as the `v*` tag on the source orboto repository. Tool schemas evolve with the API, so:
+
+- **Pin to your server's version** for reproducible setups: `npx @orboto/mcp@0.109.0` (or whichever your server is on).
+- **`@latest`** if you always run your orboto host on the most recent release. On a mismatch (package newer than server), some newer tools may 404 at call time - but the older tools keep working.
+
+The MCP server logs the server version it talks to on startup, so you'll see the alignment in your client's MCP logs.
+
+## License
+
+MIT. See [LICENSE.md](./LICENSE.md).
+
+## Source + issues
+
+This repository ([`orboto/orboto-mcp`](https://github.com/orboto/orboto-mcp)) is a public subtree-mirror of the `apps/mcp/` directory from the main orboto monorepo (private). Code changes land in the parent repo and are mirrored here on every tag push.
+
+**File issues here**: <https://github.com/orboto/orboto-mcp/issues>. Bug reports, feature requests, and questions about `@orboto/mcp` belong on this repo - that's where triage happens. Pull requests against the mirror are closed since the code is read-only; please open a discussion on the issue instead and the fix lands in the parent repo.

package/dist/event-bridge.js

@@ -0,0 +1,250 @@
+const HEARTBEAT_GRACE_MS = 90_000; // 3× the server's 30s ping
+const OVERFLOW_THRESHOLD = 100;
+const RECONNECT_DELAY_MS = 2_000;
+/** Map a raw event to the set of `orboto://` URIs that should be
+ *  notified. Returns an empty array for events that don't map to any
+ *  subscribed resource shape (no-op). */
+export function eventToUris(event) {
+    // Ticket-level events. Include the ticket URI (when the payload
+    // carries a ticketKey) AND the project URI so a project-scoped
+    // subscriber learns about activity inside it.
+    if (event.type === 'ticket:created' || event.type === 'ticket:updated' || event.type === 'ticket:deleted'
+        || event.type === 'ticket:activity'
+        || event.type === 'comment:created' || event.type === 'comment:updated' || event.type === 'comment:deleted'
+        || event.type === 'checklist:created' || event.type === 'checklist:updated' || event.type === 'checklist:deleted'
+        || event.type === 'checklist-item:created' || event.type === 'checklist-item:updated' || event.type === 'checklist-item:deleted') {
+        const uris = [];
+        const key = event.payload?.ticketKey;
+        if (key)
+            uris.push(`orboto://ticket/${key}`);
+        // The MCP bridge doesn't know each project's key; the project URI
+        // form uses the projectKey which isn't on the wire. We fall back
+        // to projectId, which the resource handler accepts via
+        // resolveProjectByKey's lookup path.
+        if (event.projectId)
+            uris.push(`orboto://project/${event.projectId}`);
+        // ORB-962 - hand-off "wake on close". When a ticket:updated
+        // payload's statusCategory is `done`, emit an additional URI
+        // dedicated to close-events so subscribers don't have to filter
+        // every ticket:updated client-side.
+        if (event.type === 'ticket:updated' && key && event.payload?.statusCategory === 'done') {
+            uris.push(`orboto://handoff/closed/${key}`);
+        }
+        return uris;
+    }
+    if (event.type === 'project:bulk-activity' || event.type === 'member:joined' || event.type === 'member:removed') {
+        return event.projectId ? [`orboto://project/${event.projectId}`] : [];
+    }
+    // ORB-1616 - dispatcher wake-on-unblock. Project-scoped (not per-ticket
+    // like `handoff/closed`) because a worker pool doesn't know in advance
+    // which ticket will become ready next - it subscribes to the PROJECT's
+    // ready channel and pulls via `orboto_work_next` on push. The
+    // notification carries no payload (the resource-subscription protocol
+    // never does) - `ticket.ready` is the webhook channel that carries the
+    // actual ticket key for external consumers.
+    if (event.type === 'ticket:ready') {
+        return event.projectId ? [`orboto://ready/${event.projectId}`] : [];
+    }
+    // ORB-1616 - escalation push: collision / failed checks / review
+    // rejection / missing decision / git failure. Project-scoped, same
+    // reasoning as `ready` above.
+    if (event.type === 'agent_escalation:raised') {
+        return event.projectId ? [`orboto://escalation/${event.projectId}`] : [];
+    }
+    if (event.type === 'doc:updated') {
+        return event.docId ? [`orboto://doc/${event.docId}`] : [];
+    }
+    if (event.type === 'timer:changed') {
+        return [`orboto://timer`];
+    }
+    // ORB-964 - agent broadcast. Map to the scope-specific URI so
+    // subscribers can register interest in just the scope they care
+    // about. For workspace scope, scopeId is the empty string.
+    if (event.type === 'agent_broadcast:posted') {
+        const p = event.payload;
+        if (p?.scopeType) {
+            const scopeId = p.scopeId ?? '';
+            return [`orboto://broadcast/${p.scopeType}/${scopeId}`];
+        }
+        return [];
+    }
+    // ORB-970 - quorum lifecycle.
+    if (event.type === 'agent_quorum:opened' || event.type === 'agent_quorum:approved') {
+        const p = event.payload;
+        return p?.topicKey ? [`orboto://quorum/${p.topicKey}`] : [];
+    }
+    // ORB-706 - mention real-time push. Every notification row firing
+    // for the calling user surfaces on `orboto://user/me/notifications`.
+    // The API-side SSE bridge already filters notification:new events
+    // to only deliver them to the matching user's session, so this
+    // URI is naturally per-user-scoped.
+    if (event.type === 'notification:new') {
+        return [`orboto://user/me/notifications`];
+    }
+    // restore:progress / system-task:* are user-scoped infrastructure
+    // events that don't map to a public resource URI today. The MCP
+    // bridge ignores them - the user gets them via the in-app UI.
+    return [];
+}
+export class EventBridge {
+    opts;
+    abort = new AbortController();
+    overflow = 0;
+    closed = false;
+    retryTimer = null;
+    log;
+    constructor(opts) {
+        this.opts = opts;
+        this.log = opts.log ?? ((msg) => { try {
+            process.stderr.write(`[orboto-mcp-bridge] ${msg}\n`);
+        }
+        catch { /* ignore */ } });
+    }
+    /** Open the SSE stream and start forwarding. Resolves immediately;
+     *  the actual forwarding happens on the returned background loop. */
+    start() {
+        void this.loop();
+    }
+    /** Stop the bridge. Safe to call multiple times. */
+    close() {
+        this.closed = true;
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        try {
+            this.abort.abort();
+        }
+        catch { /* ignore */ }
+    }
+    async loop() {
+        while (!this.closed) {
+            try {
+                await this.consume();
+            }
+            catch (err) {
+                if (this.closed)
+                    return;
+                const reason = err instanceof Error ? err.message : String(err);
+                this.log(`stream closed: ${reason} - retrying in ${RECONNECT_DELAY_MS}ms`);
+            }
+            if (this.closed)
+                return;
+            await new Promise((resolve) => {
+                this.retryTimer = setTimeout(resolve, RECONNECT_DELAY_MS);
+            });
+        }
+    }
+    async consume() {
+        const fetchFn = this.opts.fetchFn ?? fetch;
+        // Fresh abort controller per attempt so close() during a retry
+        // window doesn't leak the previous signal.
+        this.abort = new AbortController();
+        const url = `${this.opts.baseUrl.replace(/\/$/, '')}/sse/mcp-events`;
+        // ORB-1470 - resolve the current bearer per connect so a rotated OAuth
+        // access token is picked up on the next reconnect instead of pinning the
+        // stream to the session's creation-time token.
+        const bearer = this.opts.tokenProvider
+            ? await this.opts.tokenProvider.getAccessToken()
+            : (this.opts.apiKey ?? '');
+        const res = await fetchFn(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${bearer}`,
+                Accept: 'text/event-stream',
+            },
+            signal: this.abort.signal,
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`SSE bridge handshake failed (status=${res.status})`);
+        }
+        this.log(`SSE bridge connected → ${url}`);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        let lastFrame = Date.now();
+        const heartbeat = setInterval(() => {
+            // If the server's ping stops arriving the underlying TCP
+            // connection might be dead silent (Coolify / NAT timeout). Force
+            // a reconnect so we don't sit forever on a zombie stream.
+            if (Date.now() - lastFrame > HEARTBEAT_GRACE_MS) {
+                try {
+                    this.abort.abort();
+                }
+                catch { /* ignore */ }
+            }
+        }, 30_000);
+        try {
+            // Read until the stream ends, the request was aborted, or the
+            // process is shutting down.
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                lastFrame = Date.now();
+                buf += decoder.decode(value, { stream: true });
+                // SSE frames are split by '\n\n'. We handle both 'data: ...'
+                // and ': ping' (comment / heartbeat) lines; the latter become
+                // a no-op event.
+                let idx;
+                // eslint-disable-next-line no-cond-assign
+                while ((idx = buf.indexOf('\n\n')) !== -1) {
+                    const frame = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    const line = frame.split('\n').find((l) => l.startsWith('data: '));
+                    if (!line)
+                        continue;
+                    const json = line.slice(6);
+                    let event;
+                    try {
+                        event = JSON.parse(json);
+                    }
+                    catch {
+                        continue;
+                    }
+                    await this.dispatch(event);
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeat);
+            try {
+                reader.releaseLock();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    async dispatch(event) {
+        const uris = eventToUris(event);
+        if (uris.length === 0)
+            return;
+        const matched = [];
+        for (const uri of uris) {
+            if (this.opts.subscriptions.has(uri))
+                matched.push(uri);
+        }
+        if (matched.length === 0)
+            return;
+        if (this.overflow >= OVERFLOW_THRESHOLD) {
+            try {
+                await this.opts.mcp.server.sendResourceListChanged();
+            }
+            catch (err) {
+                this.log(`sendResourceListChanged failed: ${err.message}`);
+            }
+            this.overflow = 0;
+            return;
+        }
+        for (const uri of matched) {
+            try {
+                await this.opts.mcp.server.sendResourceUpdated({ uri });
+                this.log(`pushed resources/updated → ${uri} (event=${event.type})`);
+                this.overflow += 1;
+            }
+            catch (err) {
+                this.log(`sendResourceUpdated(${uri}) failed: ${err.message}`);
+            }
+        }
+    }
+}

package/dist/event-bridge.test.js

@@ -0,0 +1,165 @@
+/**
+ * ORB-940 - EventBridge unit tests.
+ *
+ * Three concerns:
+ *   1. Event → URI mapping (pure function, no I/O)
+ *   2. Dispatch behaviour - subscribed URIs trigger
+ *      sendResourceUpdated, unsubscribed do not
+ *   3. Backpressure - > 100 forwarded events → one
+ *      sendResourceListChanged instead of more updates
+ *
+ * The actual SSE consumption path is exercised via a streaming
+ * mock fetch; the response body is a ReadableStream that yields
+ * one frame per chunk, then closes.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { EventBridge, eventToUris } from './event-bridge.js';
+function mockMcp() {
+    const sendResourceUpdated = vi.fn().mockResolvedValue(undefined);
+    const sendResourceListChanged = vi.fn().mockResolvedValue(undefined);
+    return {
+        server: { sendResourceUpdated, sendResourceListChanged },
+        sendResourceUpdated,
+        sendResourceListChanged,
+    };
+}
+/** Build a Response with a body that emits the given SSE frames in
+ *  order, then closes. Each `frame` becomes `data: <json>\n\n`. */
+function mockSseResponse(frames) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            for (const frame of frames) {
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`));
+            }
+            controller.close();
+        },
+    });
+    return new Response(stream, {
+        status: 200,
+        headers: { 'content-type': 'text/event-stream' },
+    });
+}
+describe('eventToUris', () => {
+    it('maps ticket:updated to both ticket and project URIs', () => {
+        const uris = eventToUris({
+            type: 'ticket:updated',
+            projectId: 'p1',
+            payload: { ticketKey: 'ORB-42' },
+        });
+        expect(uris).toEqual(['orboto://ticket/ORB-42', 'orboto://project/p1']);
+    });
+    it('maps comment events to the ticket URI when ticketKey is present', () => {
+        const uris = eventToUris({
+            type: 'comment:created',
+            projectId: 'p1',
+            payload: { ticketKey: 'ORB-99' },
+        });
+        expect(uris).toEqual(['orboto://ticket/ORB-99', 'orboto://project/p1']);
+    });
+    it('maps doc:updated to a doc URI', () => {
+        expect(eventToUris({ type: 'doc:updated', docId: 'd1' })).toEqual(['orboto://doc/d1']);
+    });
+    it('maps timer:changed to the singleton timer URI', () => {
+        expect(eventToUris({ type: 'timer:changed', userId: 'u1' })).toEqual(['orboto://timer']);
+    });
+    it('maps notification:new to the calling user\'s notifications resource (ORB-706)', () => {
+        // The mcp-events SSE handler already filters notification:new
+        // to only deliver to the matching user; the URI is per-user
+        // scoped by construction.
+        expect(eventToUris({ type: 'notification:new', userId: 'u1' })).toEqual(['orboto://user/me/notifications']);
+    });
+    it('returns [] for restore-progress / system-task events (infrastructure-only)', () => {
+        expect(eventToUris({ type: 'restore:progress', userId: 'u1' })).toEqual([]);
+    });
+    it('emits orboto://handoff/closed/<key> on a ticket:updated to done (ORB-962)', () => {
+        const uris = eventToUris({
+            type: 'ticket:updated',
+            projectId: 'p1',
+            payload: { ticketKey: 'ORB-42', statusCategory: 'done' },
+        });
+        expect(uris).toContain('orboto://ticket/ORB-42');
+        expect(uris).toContain('orboto://handoff/closed/ORB-42');
+    });
+    it('does NOT emit handoff URI when a ticket:updated keeps a non-done status', () => {
+        const uris = eventToUris({
+            type: 'ticket:updated',
+            projectId: 'p1',
+            payload: { ticketKey: 'ORB-42', statusCategory: 'in_progress' },
+        });
+        expect(uris).not.toContain('orboto://handoff/closed/ORB-42');
+    });
+});
+describe('EventBridge.dispatch', () => {
+    it('forwards subscribed URIs and ignores the rest', async () => {
+        const mcp = mockMcp();
+        const subscriptions = new Set(['orboto://ticket/ORB-42']);
+        const fetchFn = vi.fn().mockResolvedValueOnce(mockSseResponse([
+            { type: 'ticket:updated', projectId: 'p1', payload: { ticketKey: 'ORB-42' } },
+            { type: 'ticket:updated', projectId: 'p1', payload: { ticketKey: 'ORB-99' } },
+        ]));
+        const bridge = new EventBridge({
+            baseUrl: 'https://orboto.example.com',
+            apiKey: 'orb_x',
+            mcp,
+            subscriptions,
+            fetchFn: fetchFn,
+            log: () => { },
+        });
+        bridge.start();
+        // Give the microtask loop a couple of ticks to drain.
+        await new Promise((r) => setTimeout(r, 50));
+        bridge.close();
+        expect(mcp.sendResourceUpdated).toHaveBeenCalledTimes(1);
+        expect(mcp.sendResourceUpdated).toHaveBeenCalledWith({ uri: 'orboto://ticket/ORB-42' });
+    });
+    it('falls back to sendResourceListChanged after the overflow threshold', async () => {
+        const mcp = mockMcp();
+        const subscriptions = new Set(['orboto://timer']);
+        // 101 timer events - one more than the threshold so the 101st
+        // round trips through the list_changed path.
+        const frames = Array.from({ length: 101 }, () => ({ type: 'timer:changed', userId: 'u1' }));
+        const fetchFn = vi.fn().mockResolvedValueOnce(mockSseResponse(frames));
+        const bridge = new EventBridge({
+            baseUrl: 'https://orboto.example.com',
+            apiKey: 'orb_x',
+            mcp,
+            subscriptions,
+            fetchFn: fetchFn,
+            log: () => { },
+        });
+        bridge.start();
+        await new Promise((r) => setTimeout(r, 100));
+        bridge.close();
+        expect(mcp.sendResourceUpdated).toHaveBeenCalledTimes(100);
+        expect(mcp.sendResourceListChanged).toHaveBeenCalledTimes(1);
+    });
+    it('survives malformed frames without aborting the stream', async () => {
+        const mcp = mockMcp();
+        const subscriptions = new Set(['orboto://ticket/ORB-42']);
+        // Inject one bad frame between two good ones - the bad frame is
+        // a non-JSON 'data:' line, which the bridge should skip.
+        const encoder = new TextEncoder();
+        const stream = new ReadableStream({
+            start(controller) {
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'ticket:updated', projectId: 'p1', payload: { ticketKey: 'ORB-42' } })}\n\n`));
+                controller.enqueue(encoder.encode('data: not-json\n\n'));
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'ticket:updated', projectId: 'p1', payload: { ticketKey: 'ORB-42' } })}\n\n`));
+                controller.close();
+            },
+        });
+        const fetchFn = vi.fn().mockResolvedValueOnce(new Response(stream, { status: 200 }));
+        const bridge = new EventBridge({
+            baseUrl: 'https://orboto.example.com',
+            apiKey: 'orb_x',
+            mcp,
+            subscriptions,
+            fetchFn: fetchFn,
+            log: () => { },
+        });
+        bridge.start();
+        await new Promise((r) => setTimeout(r, 50));
+        bridge.close();
+        expect(mcp.sendResourceUpdated).toHaveBeenCalledTimes(2);
+    });
+});