beehaven 0.8.16

package/dist/ipc-server.js

@@ -0,0 +1,684 @@
+/**
+ * IPC Server — bidirectional Unix socket for local clients (Electron, CLI tools).
+ *
+ * Provides request-response RPCs and broadcast subscriptions over a line-based
+ * JSON protocol on /tmp/beehaven-ipc.sock.
+ *
+ * Local clients send messages to the daemon, which forwards them to the DO
+ * via the relay WebSocket. DO responses and broadcasts are forwarded back
+ * to connected local clients.
+ *
+ * Protocol: newline-delimited JSON. Each message is a single JSON object.
+ *
+ * Client → Daemon:
+ *   { "type": "rpc", "action": "chat", "input": {...}, "rid": "req_1" }
+ *   { "type": "send", "msg": { "type": "avatar-presence", ... } }
+ *   { "type": "subscribe", "patterns": ["agent:*", "avatar-*"] }
+ *   { "type": "ping" }
+ *
+ * Daemon → Client:
+ *   { "type": "rpc-result", "rid": "req_1", "result": {...} }
+ *   { "type": "rpc-error", "rid": "req_1", "error": "..." }
+ *   { "type": "broadcast", "msg": { "type": "agent:text", ... } }
+ *   { "type": "pong" }
+ *   { "type": "status", "connected": true, "daemonPid": 1234 }
+ */
+import { createConnection, createServer } from 'net';
+import { existsSync, unlinkSync, chmodSync, statSync } from 'fs';
+import { EventEmitter } from 'events';
+import { resolveAuthScope } from './ipc-auth.js';
+const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+/**
+ * Message types the daemon will process without authentication.
+ *
+ * `ping` is side-effect-free and used by liveness probes; `auth` is the
+ * scope-handshake itself. Everything else requires the client to first
+ * present a valid token via `auth` and be tagged with a scope.
+ */
+const UNAUTH_ALLOWED_TYPES = new Set(['ping', 'auth']);
+/**
+ * Verbs that require *developer* scope. A client authenticated with the
+ * consumer token (the default — what mwah and other consumer-facing
+ * tools use) cannot invoke any of these.
+ *
+ * Why these specifically:
+ *   - get-token        leaks the Firebase ID token to the calling process
+ *   - daemon-fetch     arbitrary HTTP egress, can hit admin worker routes
+ *   - shell / sql      raw exec on a connected DO
+ *
+ * RPCs with admin:* / marketplace:install action names are gated
+ * separately inside the `rpc` case (see requireDeveloperForRpc below).
+ */
+const DEVELOPER_ONLY_VERBS = new Set(['get-token', 'daemon-fetch', 'shell', 'sql']);
+/**
+ * RPC action prefixes that require developer scope. These are admin-side
+ * verbs (rejected by the worker anyway, but failing early here avoids
+ * leaking a Firebase token into the request envelope) and the marketplace
+ * installer (executes shell commands on the user's Mac).
+ */
+// SECURITY: `shell:`/`sql:` actions are arbitrary command / raw-SQL execution
+// on the target DO. The verb-type gate (DEVELOPER_ONLY_VERBS) blocks
+// {type:'shell'|'sql'}, but the real transport is {type:'rpc',
+// action:'shell:exec'} — so these prefixes MUST be developer-only here too, or
+// a consumer-scope client (mwah / any process that read ~/.beehaven/ipc-auth)
+// bypasses the scope split and runs raw SQL/shell on the user's home DO.
+const DEVELOPER_ONLY_RPC_PREFIXES = ['admin:', 'marketplace:install', 'shell:', 'sql:'];
+/**
+ * Actions that CARRY another action, and therefore hide it from a prefix test.
+ *
+ * ⚠⚠ THE GATE BELOW READ `msg.action` AND NOTHING ELSE, SO ANY WRAPPER DEFEATED IT. `agent-invoke`
+ * takes the real verb in `input.action`, and the CLI wraps every call in it the moment an agent is
+ * signed in — so `agent-invoke { action: 'shell:exec' }` presented as `agent-invoke`, matched no
+ * prefix, and would run raw shell on the user's home DO from a CONSUMER-scope client. That is
+ * exactly the bypass the comment above says must not exist ("a consumer-scope client … bypasses the
+ * scope split and runs raw SQL/shell on the user's home DO"); it simply checked the envelope
+ * instead of the letter inside it.
+ *
+ * ⚠ THE PROXIES BELONG HERE TOO. `admin:*-rpc` is caught by its own prefix, but `workspace-rpc` is
+ * deliberately NOT `admin:`-prefixed — it is the member-facing one — so without unwrapping it a
+ * `workspace-rpc { action: 'shell:exec' }` would carry a developer verb to another workspace under
+ * a consumer token.
+ */
+const ACTION_CARRIERS = new Set([
+    'agent-invoke', 'workspace-rpc', 'admin:team-rpc', 'admin:store-rpc', 'admin:workspace-rpc',
+]);
+/**
+ * Every action a message would actually run — the envelope AND whatever it carries.
+ *
+ * ⚠ BOUNDED, NEVER AN UNBOUNDED WALK OVER CALLER INPUT. A wrapper inside a wrapper is a real shape
+ * (the CLI sends `workspace-rpc { agent-invoke { verb } }`); a third level is not. Three is one
+ * more than anything produces.
+ *
+ * ⚠ IT RETURNS THE WHOLE CHAIN, NOT THE INNERMOST. Gating on the innermost alone would wave through
+ * `agent-invoke { admin:migration-run { … } }` whenever the innermost happened to be ordinary —
+ * every link has to satisfy the scope.
+ */
+export function actionChain(action, input, depth = 0) {
+    const name = typeof action === 'string' ? action.trim() : '';
+    if (!name)
+        return [];
+    if (depth >= 2 || !ACTION_CARRIERS.has(name))
+        return [name];
+    const inner = input;
+    return [name, ...actionChain(inner?.action, inner?.input, depth + 1)];
+}
+/**
+ * Probe the IPC socket synchronously-ish to see whether another daemon is
+ * already serving it. Resolves true if a live server answered (= another
+ * daemon exists), false if the socket is stale or missing.
+ *
+ * Used as a defense-in-depth check: the daemon's own single-instance guard
+ * (findLiveDaemons in daemon.ts) handles the common case via the PID file
+ * and pgrep. This fallback catches the edge case where the PID file is
+ * missing but a live daemon somehow still holds the socket.
+ */
+function probeIpcSocket(timeoutMs = 400) {
+    return new Promise((resolve) => {
+        if (!existsSync(IPC_SOCKET_PATH))
+            return resolve(false);
+        const client = createConnection(IPC_SOCKET_PATH);
+        const done = (alive) => {
+            try {
+                client.destroy();
+            }
+            catch { }
+            resolve(alive);
+        };
+        const timer = setTimeout(() => done(false), timeoutMs);
+        client.once('connect', () => {
+            clearTimeout(timer);
+            done(true);
+        });
+        client.once('error', () => {
+            clearTimeout(timer);
+            done(false);
+        });
+    });
+}
+export { probeIpcSocket };
+export class IpcServer extends EventEmitter {
+    server = null;
+    clients = new Map();
+    clientCounter = 0;
+    virtualClientCounter = 0;
+    consumerAuthToken;
+    developerAuthToken;
+    constructor(opts = {}) {
+        super();
+        this.consumerAuthToken = opts.consumerAuthToken ?? null;
+        this.developerAuthToken = opts.developerAuthToken ?? null;
+    }
+    /**
+     * Start listening for local client connections.
+     *
+     * Caller MUST have already verified no other daemon is running — the
+     * daemon's startDaemon() calls findLiveDaemons() before reaching us. We
+     * unlink any leftover socket file here because it's expected to be stale
+     * at this point; a live server would have been caught upstream.
+     */
+    start() {
+        // Clean up stale socket
+        try {
+            if (existsSync(IPC_SOCKET_PATH))
+                unlinkSync(IPC_SOCKET_PATH);
+        }
+        catch { }
+        this.server = createServer((socket) => {
+            const clientId = `ipc_${++this.clientCounter}`;
+            // Connections start unauthenticated and scope=null. The client must
+            // present a token via the `auth` handshake; the matching token
+            // determines scope (consumer or developer). Until then, only
+            // UNAUTH_ALLOWED_TYPES (ping, auth) are processed. This is stricter
+            // than the previous "socket perms is the boundary" model — any
+            // same-user process can still *connect*, but cannot invoke verbs
+            // until it proves it knows the right token, and cannot escalate to
+            // developer scope unless dev mode is on.
+            const client = {
+                id: clientId,
+                socket,
+                subscriptions: ['*'], // Default: receive everything
+                buffer: '',
+                authenticated: false,
+                scope: null,
+            };
+            this.clients.set(clientId, client);
+            // Send initial status. `requireAuth: true` always — clients are
+            // expected to send `auth` with a token from ~/.beehaven/ipc-auth
+            // (or ipc-auth-dev for developer scope).
+            this.sendToClient(client, {
+                type: 'status',
+                connected: true,
+                clientId,
+                daemonPid: process.pid,
+                requireAuth: true,
+            });
+            socket.on('data', (data) => {
+                client.buffer += data.toString();
+                const lines = client.buffer.split('\n');
+                client.buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        this.handleClientMessage(client, msg);
+                    }
+                    catch { }
+                }
+            });
+            socket.on('close', () => {
+                if (client.label) {
+                    this.broadcast({
+                        type: 'session:leave',
+                        clientId,
+                        label: client.label,
+                        app: client.sessionApp,
+                    });
+                }
+                this.clients.delete(clientId);
+                this.runDisconnectHooks(clientId);
+            });
+            socket.on('error', () => {
+                if (client.label) {
+                    this.broadcast({
+                        type: 'session:leave',
+                        clientId,
+                        label: client.label,
+                        app: client.sessionApp,
+                    });
+                }
+                this.clients.delete(clientId);
+                this.runDisconnectHooks(clientId);
+            });
+        });
+        // Chmod the socket file after bind instead of changing the
+        // process-wide umask — umask changes are global and race with any
+        // other mkdirSync / writeFileSync happening in parallel (e.g.
+        // LocalHive pre-creating building data dirs during startup).
+        this.server.listen(IPC_SOCKET_PATH, () => {
+            /**
+             * ⚠⚠ CHMOD, THEN **VERIFY**. This was `chmodSync(…, 0o600)` inside an empty `catch {}`, and
+             * the mode it claims has been wrong on every start measured: the live socket comes up
+             * `srwxr-xr-x` (0755), reproducibly, in both dev and normal mode. `chmod` is not being
+             * refused — it succeeds from plain node AND from the packaged Electron binary — so the
+             * binding path simply is not this one in a shipped build. Either way the effect is the same:
+             * a security property that TWO docstrings state as fact ("chmod 0600 — the kernel proving the
+             * caller is this UNIX user") was never checked and was never true.
+             *
+             * ⚠ THE PROPERTY STILL HOLDS TODAY, BY A NARROWER MARGIN THAN DOCUMENTED. Connecting to a
+             * unix socket requires WRITE permission, and 0755 grants group/other only `r-x` — so no other
+             * user can connect. The protection is the absent write bit, not the documented mode, and the
+             * distance to an exploitable state is one umask change nobody would notice.
+             *
+             * ⚠ IT WARNS RATHER THAN REFUSING TO LISTEN. A daemon that will not start because a mode bit
+             * is 0755 turns a hardening check into an outage, on a socket that is still same-user-only.
+             * The line is what makes it findable; making it fatal is a separate decision with a migration.
+             */
+            /**
+             * ⚠⚠ `require` IS NOT DEFINED HERE — THIS HARDENING NEVER RAN, ON ANY BUILD. The package is
+             * `"type": "module"` and ships as unbundled ESM, so both lines threw `require is not defined`
+             * on every daemon start; the catch turned that into a warning, `mode` stayed null, and the
+             * mode assertion below was skipped along with it. The socket kept its umask default for the
+             * life of the feature while the log said only that the chmod "could not" be set.
+             *
+             * ⚠ THE SAME LESSON IS ALREADY WRITTEN DOWN ONE FILE OVER — `relay.ts`'s keychain read
+             * carries the comment "require() fails in ESM" and uses execSync for exactly this reason. It
+             * was learned once and not applied here. Import at the top; never reach for `require` in this
+             * package.
+             */
+            let mode = null;
+            try {
+                chmodSync(IPC_SOCKET_PATH, 0o600);
+                mode = statSync(IPC_SOCKET_PATH).mode & 0o777;
+            }
+            catch (err) {
+                console.warn(`[ipc] SECURITY: could not set 0600 on ${IPC_SOCKET_PATH} — ${err?.code ?? err?.message ?? err}`);
+            }
+            if (mode !== null && mode !== 0o600) {
+                console.warn(`[ipc] SECURITY: socket mode is 0${mode.toString(8)}, expected 0600. Other-user connect is still `
+                    + `blocked (no write bit), but the documented guarantee does not hold — do not weaken it further.`);
+            }
+            console.log(`[ipc] Listening on ${IPC_SOCKET_PATH}${mode !== null ? ` (mode 0${mode.toString(8)})` : ''}`);
+        });
+        this.server.on('error', (err) => {
+            console.warn(`[ipc] Server error: ${err.message}`);
+        });
+    }
+    /** Stop the IPC server */
+    stop() {
+        for (const client of this.clients.values()) {
+            if (client.socket)
+                client.socket.destroy();
+        }
+        this.clients.clear();
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+        }
+        try {
+            if (existsSync(IPC_SOCKET_PATH))
+                unlinkSync(IPC_SOCKET_PATH);
+        }
+        catch { }
+    }
+    /** Broadcast a message from the DO to all subscribed local clients */
+    /**
+     * ⚠ RETURNS THE NUMBER OF CLIENTS IT REACHED. It returned `void`, which meant a caller could
+     * not tell "delivered to the desktop app" from "nobody is listening" — and the whole point of
+     * a local fallback is deciding between exactly those two. Same defect as `broadcastToWeb` in
+     * the worker, where an always-zero `delivered` sent an agent chasing a tab that was never there.
+     * ⚠ Additive: every existing caller ignores the value and is unaffected.
+     */
+    broadcast(msg) {
+        const type = msg?.type || '';
+        let sent = 0;
+        for (const client of this.clients.values()) {
+            if (this.matchesSubscription(client, type)) {
+                this.sendToClient(client, { type: 'broadcast', msg });
+                sent++;
+            }
+        }
+        return sent;
+    }
+    /** Send an RPC result back to a specific client */
+    sendRpcResult(clientId, rid, result) {
+        const client = this.clients.get(clientId);
+        if (client) {
+            this.sendToClient(client, { type: 'rpc-result', rid, result });
+        }
+    }
+    /** Send an RPC error back to a specific client */
+    sendRpcError(clientId, rid, error) {
+        const client = this.clients.get(clientId);
+        if (client) {
+            this.sendToClient(client, { type: 'rpc-error', rid, error });
+        }
+    }
+    /** Number of connected local clients */
+    get clientCount() {
+        return this.clients.size;
+    }
+    /** Get info about all active sessions (clients that announced themselves) */
+    getSessionInfo() {
+        const sessions = [];
+        for (const client of this.clients.values()) {
+            if (client.label) {
+                sessions.push({ clientId: client.id, label: client.label, app: client.sessionApp });
+            }
+        }
+        return sessions;
+    }
+    // ─── Internal ───
+    handleClientMessage(client, msg) {
+        // ── Auth gate ──────────────────────────────────────────────────────
+        // Real-socket clients must complete the `auth` handshake before any
+        // sensitive message type is honored. Virtual clients (in-process)
+        // are pre-authenticated by construction. `UNAUTH_ALLOWED_TYPES`
+        // lists what's safe to process before auth completes (ping, auth).
+        //
+        // If the server was constructed without an authToken (authToken=null),
+        // fail closed: reject everything except the allowlist. This makes a
+        // misconfigured daemon unreachable rather than silently permissive.
+        if (!client.authenticated && !UNAUTH_ALLOWED_TYPES.has(msg.type)) {
+            if (msg.rid) {
+                this.sendToClient(client, {
+                    type: 'rpc-error',
+                    rid: msg.rid,
+                    error: 'IPC auth required — send { type: "auth", token: "…" } first',
+                    code: 'UNAUTHENTICATED',
+                });
+            }
+            else {
+                this.sendToClient(client, {
+                    type: 'error',
+                    error: 'IPC auth required',
+                    code: 'UNAUTHENTICATED',
+                });
+            }
+            return;
+        }
+        // ── Scope gate ─────────────────────────────────────────────────────
+        // Developer-only verbs are blocked for consumer-scope clients even
+        // after a successful auth handshake. The error surfaces as a normal
+        // RPC error so the CLI can render a useful "needs HIVE_DEV_MODE"
+        // message rather than a hung connection.
+        if (client.scope !== 'developer') {
+            /**
+             * ⚠⚠ EVERY ACTION IN THE CHAIN, NOT JUST THE ENVELOPE — see `actionChain`. A wrapper used to
+             * defeat this gate completely: the CLI wraps each call in `agent-invoke` whenever an agent is
+             * signed in, so the prefix test saw `agent-invoke` and the carried verb was never examined.
+             */
+            const chain = msg.type === 'rpc' ? actionChain(msg.action, msg.input) : [];
+            const offender = chain.find((a) => DEVELOPER_ONLY_RPC_PREFIXES.some((p) => a.startsWith(p)));
+            const blocked = DEVELOPER_ONLY_VERBS.has(msg.type) || !!offender;
+            if (blocked) {
+                /**
+                 * ⚠ NAME THE ACTION THAT WAS ACTUALLY REFUSED, not the envelope. "`agent-invoke` requires
+                 * developer scope" is false — it does not — and it sends the reader looking in the wrong
+                 * place for a verb that is perfectly ordinary.
+                 */
+                const detail = msg.type === 'rpc'
+                    ? `RPC '${offender ?? msg.action}' requires developer scope`
+                        + (offender && offender !== msg.action ? ` (carried by '${msg.action}')` : '')
+                    : `verb '${msg.type}' requires developer scope`;
+                this.sendToClient(client, {
+                    type: 'rpc-error',
+                    rid: msg.rid ?? undefined,
+                    error: `${detail}. Enable Developer Mode in the Hive Mac app (or set HIVE_DEV_MODE=1) and relaunch.`,
+                    code: 'FORBIDDEN_SCOPE',
+                });
+                return;
+            }
+        }
+        switch (msg.type) {
+            case 'auth': {
+                // Scope-aware handshake. The presented token is matched against
+                // both the consumer and developer tokens; the matching one
+                // determines client.scope. A null scope means rejection.
+                const presented = typeof msg.token === 'string' ? msg.token : '';
+                const scope = resolveAuthScope(presented, {
+                    consumer: this.consumerAuthToken,
+                    developer: this.developerAuthToken,
+                });
+                if (!scope) {
+                    this.sendToClient(client, {
+                        type: 'auth-result',
+                        ok: false,
+                        error: 'Invalid auth token',
+                    });
+                    try {
+                        client.socket?.end();
+                    }
+                    catch { }
+                    return;
+                }
+                client.authenticated = true;
+                client.scope = scope;
+                this.sendToClient(client, {
+                    type: 'auth-result',
+                    ok: true,
+                    scope,
+                });
+                return;
+            }
+            case 'ping':
+                this.sendToClient(client, { type: 'pong' });
+                break;
+            case 'subscribe':
+                if (Array.isArray(msg.patterns)) {
+                    client.subscriptions = msg.patterns;
+                }
+                break;
+            case 'session:announce':
+                // Client labels itself (e.g. "terminal", "browser", "claude")
+                client.label = msg.label;
+                client.sessionApp = msg.app;
+                this.broadcast({
+                    type: 'session:join',
+                    clientId: client.id,
+                    label: msg.label,
+                    app: msg.app,
+                });
+                break;
+            case 'rpc':
+                // Forward RPC to relay → DO. Emit event for daemon to handle.
+                this.emit('rpc', {
+                    clientId: client.id,
+                    rid: msg.rid,
+                    action: msg.action,
+                    input: msg.input || {},
+                });
+                break;
+            case 'send':
+                // Forward raw message to relay → DO
+                this.emit('send', msg.msg);
+                break;
+            case 'app-rpc':
+                // Forward RPC to a local app building (not the cloud relay).
+                // Used by the CLI for controlling local buildings like AbletonWorkspace.
+                this.emit('app-rpc', {
+                    clientId: client.id,
+                    rid: msg.rid,
+                    action: msg.action,
+                    input: msg.input || {},
+                    building: msg.building || 'ableton',
+                    instanceId: msg.instanceId || 'live',
+                    // Optional signed AgentIdentity token — the daemon verifies it and
+                    // attaches a CallerContext to the building call.
+                    agent: typeof msg.agent === 'string' ? msg.agent : undefined,
+                });
+                break;
+            case 'pipeline':
+                // Chained app-rpc: steps run in sequence, each step's result is
+                // bound to `$<id>` for later steps. Progress is emitted as
+                // `pipeline:step` broadcasts so the UI + Claude can observe.
+                this.emit('pipeline', {
+                    clientId: client.id,
+                    rid: msg.rid,
+                    title: msg.title,
+                    steps: Array.isArray(msg.steps) ? msg.steps : [],
+                    defaultBuilding: msg.building || 'ableton',
+                    defaultInstance: msg.instanceId || 'live',
+                });
+                break;
+            case 'daemon-fetch':
+                // HTTP fetch proxy: the daemon makes the HTTP request with its
+                // Firebase ID token attached as `Authorization: Bearer …` and
+                // returns the response. Lets local CLI tools (beehaven admin,
+                // smoke tests, scripts) hit any worker route without ever
+                // touching the keychain token themselves.
+                this.emit('daemon-fetch', {
+                    clientId: client.id,
+                    rid: msg.rid,
+                    method: msg.method || 'GET',
+                    url: msg.url,
+                    body: msg.body,
+                    headers: msg.headers || {},
+                });
+                break;
+            // ── Daemon Omni (Claude Agent SDK, hosted in this process) ──────
+            //
+            // These MUST be explicit cases. The `default` arm below forwards an
+            // unrecognised message to the RELAY — so a missing case here would not
+            // fail loudly, it would quietly ship the user's prompt to the cloud,
+            // which is both wrong and the exact path disabled for Anthropic
+            // credential-use compliance. Adding an `omni:*` verb means adding it
+            // here too.
+            //
+            // Deliberately NOT in DEVELOPER_ONLY_VERBS: the avatar and mwah are
+            // consumer-scope clients and this is the runtime behind their chat. The
+            // security boundary for driving your own Claude subscription is the
+            // socket's 0600 mode — the kernel proving the caller is this UNIX user —
+            // not which CLI happened to connect.
+            case 'omni:prompt':
+            case 'omni:end':
+            case 'omni:sessions':
+            case 'omni:branch':
+            /**
+             * ⚠ THESE THREE WERE MISSING, AND THE FAILURE WAS A TEN-MINUTE HANG.
+             *
+             * The note above says it plainly — "adding an `omni:*` verb means adding
+             * it here too" — and adding the verbs to the daemon and the client without
+             * this line meant they fell through to the CLOUD branch instead of being
+             * emitted locally. `omni:answer` never reached the ask registry, so a
+             * question the turn was parked on could only ever end by timing out:
+             * measured at 10m12s, after which Omni correctly reported "no response —
+             * you may have been away". Every part looked right in isolation.
+             */
+            case 'omni:answer':
+            case 'omni:interrupt':
+            case 'omni:surface':
+            /**
+             * ⚠ AND I MADE THE SAME OMISSION ONE VERB LATER. `omni:set-cwd` was added to the daemon and
+             * to `IpcClient`, both correct in isolation, and without this line it fell through to the
+             * CLOUD branch and every call timed out at 30s. The note above says exactly this and it was
+             * still missed — which is why there is now a test that reads BOTH files and fails when they
+             * disagree, rather than a third warning comment.
+             */
+            case 'omni:set-cwd':
+            /**
+             * ⚠ FOUND BY THE GUARD ON ITS FIRST RUN, already committed and already broken.
+             * `omni:company-status` was added to the daemon earlier the same day and never routed here,
+             * so the company-mode diagnostics — the surface whose entire job is reporting that something
+             * is silently wrong — would itself have hung silently.
+             */
+            case 'omni:company-status':
+                this.emit(msg.type, {
+                    clientId: client.id,
+                    rid: msg.rid,
+                    input: msg.input || {},
+                });
+                break;
+            case 'get-token':
+                // Return the daemon's current Firebase ID token. Use sparingly
+                // — `daemon-fetch` is the preferred pattern because it keeps the
+                // token inside the daemon process. `get-token` exists for tools
+                // that need to call third-party services with a Firebase JWT
+                // (e.g. Cloud Run endpoints, Firestore REST).
+                this.emit('get-token', { clientId: client.id, rid: msg.rid });
+                break;
+            default:
+                // Forward unknown messages as raw sends
+                this.emit('send', msg);
+                break;
+        }
+    }
+    sendToClient(client, msg) {
+        try {
+            // Virtual clients (dashboard /apps/ws bridge, in-process
+            // integrations) provide their own send callback instead of a socket.
+            if (client.virtualSend) {
+                client.virtualSend(msg);
+                return;
+            }
+            if (client.socket && !client.socket.destroyed) {
+                client.socket.write(JSON.stringify(msg) + '\n');
+            }
+        }
+        catch { }
+    }
+    // ── Virtual client API ────────────────────────────────────────────────
+    //
+    // A virtual client is an in-process IPC client that has no socket — its
+    // outgoing messages are delivered to a `virtualSend` callback instead.
+    // The dashboard uses this to bridge browser WebSocket connections to the
+    // IPC bus so the same pipeline/app-rpc handlers serve both Claude and
+    // the human UI.
+    /** Register a virtual client and return its id. */
+    createVirtualClient(virtualSend, initialSubscriptions = ['*']) {
+        const id = `virt_${++this.virtualClientCounter}`;
+        const client = {
+            id,
+            virtualSend,
+            subscriptions: initialSubscriptions,
+            buffer: '',
+            // Virtual clients are in-process — they're already inside the trust
+            // boundary. The dashboard /apps/ws bridge enforces its own auth
+            // (session cookie, origin check) before creating the virtual client,
+            // so we hand them developer scope to mirror what a logged-in tray
+            // user can already do.
+            authenticated: true,
+            scope: 'developer',
+        };
+        this.clients.set(id, client);
+        // Mimic the on-connect status frame real clients receive so the bridge
+        // client's logic (and therefore the browser) can key off the same event.
+        this.sendToClient(client, {
+            type: 'status',
+            connected: true,
+            clientId: id,
+            daemonPid: process.pid,
+        });
+        return id;
+    }
+    /** Deliver a parsed message as if the virtual client had sent it. */
+    injectMessage(clientId, msg) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return;
+        this.handleClientMessage(client, msg);
+    }
+    /** Remove a virtual client (on WebSocket close). */
+    releaseVirtualClient(clientId) {
+        this.clients.delete(clientId);
+        this.runDisconnectHooks(clientId);
+    }
+    /**
+     * Run something when a client goes away.
+     *
+     * ⚠ EXISTS BECAUSE A CAPABILITY DECLARED BY A CLIENT MUST DIE WITH IT. The Mac
+     * app declares that it can render floating windows; if it quits without that
+     * being undone, the daemon goes on believing a windowing surface is attached
+     * and Omni keeps reporting that it opened windows nobody can see. Anything
+     * else a client claims about itself has the same shape.
+     */
+    disconnectHooks = new Map();
+    onClientDisconnect(clientId, fn) {
+        const list = this.disconnectHooks.get(clientId) ?? [];
+        list.push(fn);
+        this.disconnectHooks.set(clientId, list);
+    }
+    runDisconnectHooks(clientId) {
+        const list = this.disconnectHooks.get(clientId);
+        if (!list)
+            return;
+        this.disconnectHooks.delete(clientId);
+        for (const fn of list) {
+            try {
+                fn();
+            }
+            catch { /* a hook must not take down the cleanup path */ }
+        }
+    }
+    matchesSubscription(client, type) {
+        return client.subscriptions.some((pattern) => {
+            if (pattern === '*')
+                return true;
+            if (pattern.endsWith('*')) {
+                return type.startsWith(pattern.slice(0, -1));
+            }
+            return type === pattern;
+        });
+    }
+}
+export { IPC_SOCKET_PATH };