@clearlysh/beehaven 0.8.16

package/dist/ipc-client.js

@@ -0,0 +1,495 @@
+/**
+ * IPC Client — connects to the beehaven daemon via Unix socket.
+ *
+ * Used by CLI commands (actions, call, pipe, watch, ls, cat) to communicate
+ * with the running daemon, which forwards requests to the cloud DO.
+ *
+ * Protocol: newline-delimited JSON over /tmp/beehaven-ipc.sock
+ */
+import { existsSync } from 'node:fs';
+import { createConnection } from 'net';
+import { EventEmitter } from 'events';
+import { resolveClientAuthToken } from './ipc-auth.js';
+import { activeAgentWrap } from './agent-attribution.js';
+const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+/** Default timeout for RPC calls (ms) */
+const DEFAULT_TIMEOUT = 30_000;
+/**
+ * How long to wait for a daemon that is UP but has not minted its token yet.
+ *
+ * ⚠ Bounded by what the condition actually is, not by generosity: the daemon writes the token
+ * immediately after binding the socket, so the real window is well under a second. Three seconds
+ * covers a loaded machine and still fails fast enough that a genuinely broken daemon is reported
+ * rather than waited on.
+ */
+const TOKEN_MINT_WAIT_MS = 3_000;
+const TOKEN_MINT_POLL_MS = 50;
+/** Backing store for the synchronous sleep below — never written, only waited on. */
+const WAIT_CELL = new Int32Array(new SharedArrayBuffer(4));
+export class IpcClient extends EventEmitter {
+    socket = null;
+    buffer = '';
+    socketPath;
+    defaultTimeout;
+    ridCounter = 0;
+    pending = new Map();
+    _connected = false;
+    explicitAuthToken;
+    /**
+     * Pending auth handshake — resolves when the daemon confirms `auth-result`
+     * or rejects on timeout/mismatch. Held during connect() so callers only
+     * see a resolved promise after the socket is fully usable.
+     */
+    authResolver = null;
+    constructor(opts) {
+        super();
+        /**
+         * ⚠ `$BEEHAVEN_IPC_SOCKET` IS AN ADDRESS OVERRIDE, NOT A FEATURE FLAG. It exists so a test can
+         * stand a fake daemon in front of `rpcOnce` and read the frame that actually goes on the wire
+         * — the only way to guard the CALL SITE rather than the helper it calls, which is the exact
+         * distinction that let 28 verbs ship un-attributed. Unset, nothing changes.
+         */
+        this.socketPath = opts?.socketPath ?? process.env.BEEHAVEN_IPC_SOCKET ?? IPC_SOCKET_PATH;
+        this.defaultTimeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+        this.explicitAuthToken = opts?.authToken;
+    }
+    /**
+     * Connect to the daemon IPC socket. Resolves when the auth handshake
+     * completes and the client is ready to send RPCs.
+     *
+     * Flow:
+     *   1. Open socket, wait for the initial `status` frame.
+     *   2. Send `{ type: 'auth', token: ... }` with the token read from
+     *      ~/.beehaven/ipc-auth (or $BEEHAVEN_IPC_AUTH, or explicit option).
+     *   3. Wait for `auth-result`. On ok=true, resolve connect(). On ok=false,
+     *      reject with a clear message so the CLI can tell the user to restart
+     *      the daemon (tokens rotate every launch).
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error('Connection timeout — is the beehaven daemon running? Run `beehaven start --headless` (or open the Clearly Dev Mac app).'));
+            }, 5_000);
+            const socket = createConnection({ path: this.socketPath });
+            this.socket = socket;
+            let connectedInfo = null;
+            socket.on('connect', () => {
+                this._connected = true;
+            });
+            socket.on('data', (data) => {
+                this.buffer += data.toString();
+                const lines = this.buffer.split('\n');
+                this.buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        // Intercept the status + auth-result frames here so the
+                        // auth handshake stays encapsulated in connect().
+                        if (msg.type === 'status' && !connectedInfo) {
+                            connectedInfo = { clientId: msg.clientId, daemonPid: msg.daemonPid };
+                            // If the daemon doesn't require auth (old build, or
+                            // explicitly disabled for tests), skip the handshake.
+                            if (msg.requireAuth === false) {
+                                clearTimeout(timeout);
+                                resolve(connectedInfo);
+                                this.emit('status', msg);
+                                continue;
+                            }
+                            // Resolve the token: explicit override > env > file > keychain
+                            /**
+                             * ⚠⚠ THE TRANSIENT CASE IS WAITED OUT, NOT REPORTED. The daemon mints the token
+                             * immediately after its socket comes up, so a command arriving in that window is
+                             * not broken — it is early. Telling the caller to "wait a second and retry" made
+                             * every script and every agent implement that retry itself, and the ones that did
+                             * not read a startup race as a broken install.
+                             *
+                             * ⚠ ONLY WHEN THE SOCKET IS UP. No socket means nothing is running and no amount of
+                             * waiting produces a token, so that path must keep failing at once — otherwise
+                             * `beehaven call` with no daemon pauses before saying the obvious.
+                             */
+                            const readToken = () => this.explicitAuthToken === undefined
+                                ? resolveClientAuthToken()
+                                : this.explicitAuthToken;
+                            let token = readToken();
+                            if (!token && this.explicitAuthToken === undefined && existsSync(this.socketPath)) {
+                                const deadline = Date.now() + TOKEN_MINT_WAIT_MS;
+                                while (!token && Date.now() < deadline) {
+                                    /**
+                                     * ⚠ SYNCHRONOUS ON PURPOSE. This runs inside the socket's `data` handler; an
+                                     * `await` here would let the next frame interleave mid-handshake and be parsed
+                                     * against `authResolver === null`.
+                                     */
+                                    Atomics.wait(WAIT_CELL, 0, 0, TOKEN_MINT_POLL_MS);
+                                    token = readToken();
+                                }
+                            }
+                            if (!token) {
+                                clearTimeout(timeout);
+                                this._connected = false;
+                                try {
+                                    socket.destroy();
+                                }
+                                catch { }
+                                reject(new Error(
+                                /**
+                                 * ⚠⚠ Same trap as daemon-client.ts — and the same fix. `stop` scrubs both
+                                 * tokens; `start --headless` used to return before the replacement was minted,
+                                 * so a `stop && start && call` sequence landed in a window with no token at
+                                 * all. The old text advised a RESTART, which deletes the fresh token and
+                                 * re-enters that window.
+                                 *
+                                 * ⚠ THE SOCKET IS THE DISCRIMINATOR: up means "still starting, wait"; absent
+                                 * means "nothing is running, start one". Opposite actions.
+                                 */
+                                (existsSync(this.socketPath)
+                                    ? 'The daemon is still starting — its socket is up but it has not minted an IPC token yet. ' +
+                                        'Wait a second and retry. (Do NOT restart: `stop` scrubs the token, which re-enters this window.)'
+                                    : 'No IPC auth token and no daemon socket — nothing is running. ' +
+                                        'Start one: `beehaven start --headless` (prefix HIVE_DEV_MODE=1 for admin/shell verbs), ' +
+                                        'or open the Clearly Dev Mac app if it owns the daemon.')));
+                                return;
+                            }
+                            // Send the handshake and wait for auth-result.
+                            this.authResolver = {
+                                resolve: () => {
+                                    clearTimeout(timeout);
+                                    resolve(connectedInfo);
+                                    this.emit('status', msg);
+                                },
+                                reject: (e) => {
+                                    clearTimeout(timeout);
+                                    this._connected = false;
+                                    try {
+                                        socket.destroy();
+                                    }
+                                    catch { }
+                                    reject(e);
+                                },
+                            };
+                            try {
+                                socket.write(JSON.stringify({ type: 'auth', token }) + '\n');
+                            }
+                            catch { }
+                            continue;
+                        }
+                        if (msg.type === 'auth-result') {
+                            if (this.authResolver) {
+                                const { resolve: r, reject: rj } = this.authResolver;
+                                this.authResolver = null;
+                                if (msg.ok)
+                                    r();
+                                else
+                                    rj(new Error(msg.error || 'IPC auth rejected by daemon'));
+                            }
+                            continue;
+                        }
+                        this.handleMessage(msg, resolve, timeout);
+                    }
+                    catch { }
+                }
+            });
+            socket.on('close', () => {
+                this._connected = false;
+                if (this.authResolver) {
+                    const { reject: rj } = this.authResolver;
+                    this.authResolver = null;
+                    rj(new Error('Connection closed during auth handshake'));
+                }
+                this.rejectAll('Connection closed');
+                this.emit('close');
+            });
+            socket.on('error', (err) => {
+                clearTimeout(timeout);
+                this._connected = false;
+                if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+                    reject(new Error(
+                    // Name the CLI-owned fix FIRST. The Mac app is one of two valid
+                    // daemon owners, and an agent in a terminal cannot open it.
+                    //
+                    // ⚠⚠ IT NO LONGER PRESCRIBES `beehaven stop` — CBH2-22. It used to end *"If it
+                    // claims one is already running, `beehaven stop` first"*, and that sentence is the
+                    // destructive half of the ticket: a `stop` SCRUBS THE IPC TOKEN and drops the agent
+                    // session, and this error is reachable from a TRANSIENT connect failure on a daemon
+                    // that is alive and recovers by itself (observed: the PID was up throughout and the
+                    // next call succeeded). So the advice on a single failure is to look before acting.
+                    // `beehaven status` now distinguishes "alive but not answering" from "not running"
+                    // and names the right fix for each — which is the one place that decision belongs.
+                    'Cannot connect to daemon. Check with `beehaven status` first — it says whether one '
+                        + 'is alive but busy (retry) or genuinely absent (`beehaven start --headless`, or '
+                        + 'open the Clearly Dev Mac app).'));
+                }
+                else {
+                    reject(err);
+                }
+            });
+        });
+    }
+    /** Whether the socket is connected */
+    get connected() {
+        return this._connected;
+    }
+    /**
+     * Send an RPC request to the daemon → DO and wait for response.
+     *
+     * ⚠⚠ THIS IS THE ATTRIBUTION CHOKEPOINT — IT IS THE ONLY PLACE `type:'rpc'` IS BUILT.
+     *
+     * `ipc-server.ts` forwards every `type:'rpc'` frame to the relay; the daemon's other message
+     * types (`app-rpc`, `omni:*`, `daemon-fetch`, `send`) are the LOCAL doors and are sent by other
+     * methods. So "did this call reach the workspace?" and "did it come through here?" are the same
+     * question, which is what makes this the one place the wrap belongs.
+     *
+     * ⚠⚠ IT USED TO BE OPT-IN, AND THE OPT-IN IS WHAT FAILED. A verb was attributed only if its
+     * module imported `agentRpc` instead of `rpcOnce` — three modules did, twelve did not, and the
+     * difference was invisible: same call, same result, no error, just no `agent_activity` row and
+     * no `source`. 28 of 47 remote verbs were dark, and a traffic report over that column read their
+     * silence as "nobody uses this".
+     *
+     * ⚠⚠ AND `rpcOnce` WAS NOT LOW ENOUGH. Putting it there still missed every caller that holds a
+     * LONG-LIVED client: `omni`'s `describe-action`, the four workspace calls behind `beehaven pipe`,
+     * and the action-catalog fetch. Those are exactly the shape the original defect had — a second
+     * door nobody remembered — so the wrap belongs at the frame, not at one convenience wrapper
+     * around it. `agent-attribution.test.ts` fails on any module that opens a third.
+     *
+     * ⚠ THE WRAP IS IDEMPOTENT (`alreadyAttributed`), so `agentRpc`, `cmdCall` and the interactive
+     * shell — all of which still wrap ABOVE this — are unaffected. `cmdCall` in particular MUST keep
+     * wrapping first: it resolves the cross-DO building envelope afterwards, and `agent-invoke` has
+     * to travel INSIDE that proxy or the activity row lands in the wrong workspace.
+     *
+     * ⚠ NO AGENT ⇒ NO WRAP. A signed-out user, an expired identity, a bootstrap verb and a
+     * daemon-local verb all pass through untouched — attribution is added where there is something
+     * to attribute, never invented.
+     */
+    call(action, input = {}, timeout) {
+        const wrapped = activeAgentWrap(action, input, {});
+        action = wrapped.action;
+        input = wrapped.input;
+        return new Promise((resolve, reject) => {
+            if (!this.socket || !this._connected) {
+                return reject(new Error('Not connected'));
+            }
+            const rid = `cli_${++this.ridCounter}_${Date.now().toString(36)}`;
+            const ms = timeout ?? this.defaultTimeout;
+            // Forward `_timeout` inside the payload so the daemon's relay-forward window
+            // matches our wait (the daemon strips it before dispatch; default is 60s, too
+            // short for long jobs). Give the local timer a small grace so the daemon's
+            // own timeout fires FIRST and returns a clean error instead of us abandoning.
+            const timer = setTimeout(() => {
+                this.pending.delete(rid);
+                reject(new Error(`Request timeout after ${ms}ms`));
+            }, ms + 5_000);
+            this.pending.set(rid, { resolve, reject, timer });
+            this.send({ type: 'rpc', action, input: { ...input, _timeout: ms }, rid });
+        });
+    }
+    /**
+     * Drive DAEMON OMNI — the Claude Agent SDK session hosted in the daemon.
+     *
+     * Resolves when the turn is ACCEPTED, not when it finishes. The answer
+     * arrives as `omni:event` broadcasts (`agent:text-delta`, `agent:tool-call`,
+     * `agent:done`, …), so subscribe BEFORE calling this if you want the reply —
+     * a coding turn can run for minutes and a call that blocked for it would be
+     * indistinguishable from a hang.
+     *
+     * Its own method rather than `call()` because `call()` sends `type:'rpc'`,
+     * which the daemon forwards to the CLOUD. These verbs are local-only.
+     */
+    omni(
+    // `answer` resolves a question the turn is parked on; `interrupt` stops the
+    // turn without ending the conversation.
+    /**
+     * ⚠⚠ `company-status` WAS MISSING FROM THIS UNION, AND THAT IS WHY THE DIAGNOSTIC HAD NO CALLER.
+     * The daemon handled it and `ipc-server` routed it — both correct, both committed — but nothing
+     * could reach it: the documented invocation (`beehaven call --ipc omni:company-status`) is not a
+     * real flag, and TypeScript refused any other caller because the verb was not in this list. A
+     * surface whose entire job is reporting that something is silently wrong was itself silently
+     * unreachable. Add the verb HERE when you add one to `ipc-server`'s switch.
+     */
+    verb, input = {}, timeout) {
+        return new Promise((resolve, reject) => {
+            if (!this.socket || !this._connected)
+                return reject(new Error('Not connected'));
+            const rid = `cli_${++this.ridCounter}_${Date.now().toString(36)}`;
+            const ms = timeout ?? this.defaultTimeout;
+            const timer = setTimeout(() => {
+                this.pending.delete(rid);
+                reject(new Error(`Request timeout after ${ms}ms`));
+            }, ms);
+            this.pending.set(rid, { resolve, reject, timer });
+            this.send({ type: `omni:${verb}`, input, rid });
+        });
+    }
+    /** Send a app-rpc to a local (or cloud-routed) building and wait for response */
+    appCall(action, input = {}, opts) {
+        return new Promise((resolve, reject) => {
+            if (!this.socket || !this._connected) {
+                return reject(new Error('Not connected'));
+            }
+            const rid = `cli_${++this.ridCounter}_${Date.now().toString(36)}`;
+            const ms = opts?.timeout ?? this.defaultTimeout;
+            const timer = setTimeout(() => {
+                this.pending.delete(rid);
+                reject(new Error(`Request timeout after ${ms}ms`));
+            }, ms);
+            this.pending.set(rid, { resolve, reject, timer });
+            this.send({
+                type: 'app-rpc',
+                action,
+                input,
+                rid,
+                building: opts?.building ?? 'ableton',
+                instanceId: opts?.instanceId ?? 'live',
+                // Optional signed AgentIdentity token — the daemon verifies it and
+                // attaches a CallerContext to the building call. Absent ⇒ anonymous.
+                ...(opts?.agent ? { agent: opts.agent } : {}),
+            });
+        });
+    }
+    /** Run a multi-step pipeline against one or more buildings and wait for result */
+    pipeline(steps, opts) {
+        return new Promise((resolve, reject) => {
+            if (!this.socket || !this._connected) {
+                return reject(new Error('Not connected'));
+            }
+            const rid = `cli_${++this.ridCounter}_${Date.now().toString(36)}`;
+            const ms = opts?.timeout ?? 120_000; // pipelines can take longer
+            const timer = setTimeout(() => {
+                this.pending.delete(rid);
+                reject(new Error(`Pipeline timeout after ${ms}ms`));
+            }, ms);
+            this.pending.set(rid, { resolve, reject, timer });
+            this.send({
+                type: 'pipeline',
+                steps,
+                rid,
+                title: opts?.title,
+                building: opts?.building ?? 'ableton',
+                instanceId: opts?.instanceId ?? 'live',
+            });
+        });
+    }
+    /** Send a raw message (fire-and-forget) */
+    send(msg) {
+        if (!this.socket || !this._connected)
+            return;
+        try {
+            this.socket.write(JSON.stringify(msg) + '\n');
+        }
+        catch { }
+    }
+    /** Subscribe to broadcast patterns (e.g. "agent:*", "stream:*") */
+    subscribe(patterns) {
+        this.send({ type: 'subscribe', patterns });
+    }
+    /** Disconnect from daemon */
+    disconnect() {
+        if (this.socket) {
+            this.rejectAll('Disconnected');
+            this.socket.destroy();
+            this.socket = null;
+            this._connected = false;
+        }
+    }
+    // ── Internal ───
+    handleMessage(msg, initialResolve, initialTimeout) {
+        switch (msg.type) {
+            case 'status':
+                // Initial connection status — resolve the connect() promise
+                if (initialResolve) {
+                    if (initialTimeout)
+                        clearTimeout(initialTimeout);
+                    initialResolve({ clientId: msg.clientId, daemonPid: msg.daemonPid });
+                }
+                this.emit('status', msg);
+                break;
+            case 'rpc-result':
+                if (msg.rid && this.pending.has(msg.rid)) {
+                    const p = this.pending.get(msg.rid);
+                    clearTimeout(p.timer);
+                    this.pending.delete(msg.rid);
+                    p.resolve(msg.result);
+                }
+                break;
+            case 'rpc-error':
+                if (msg.rid && this.pending.has(msg.rid)) {
+                    const p = this.pending.get(msg.rid);
+                    clearTimeout(p.timer);
+                    this.pending.delete(msg.rid);
+                    p.reject(new Error(msg.error));
+                }
+                break;
+            case 'broadcast':
+                this.emit('broadcast', msg.msg);
+                break;
+            case 'pong':
+                this.emit('pong');
+                break;
+        }
+    }
+    rejectAll(reason) {
+        for (const [rid, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+}
+// ── Convenience: one-shot RPC ──
+/**
+ * Connect to daemon, execute a single RPC, disconnect.
+ * For CLI commands that need a single request-response.
+ *
+ * ⚠ ATTRIBUTION IS NOT DONE HERE — see `IpcClient.call`, which is the frame this eventually sends
+ * and therefore the chokepoint. It was briefly applied at this level and that was one layer too
+ * high: every caller holding a LONG-LIVED client (`omni`, `beehaven pipe`, the catalog fetch)
+ * still went out un-attributed, which is the same "second door nobody remembered" shape as the
+ * defect being fixed.
+ */
+export async function rpcOnce(action, input = {}, timeout) {
+    const client = new IpcClient();
+    try {
+        await client.connect();
+        const result = await client.call(action, input, timeout);
+        return result;
+    }
+    finally {
+        client.disconnect();
+    }
+}
+/**
+ * Connect to daemon, execute a single app-rpc against a local building, disconnect.
+ */
+export async function appRpcOnce(action, input = {}, opts) {
+    const client = new IpcClient();
+    try {
+        await client.connect();
+        return await client.appCall(action, input, opts);
+    }
+    finally {
+        client.disconnect();
+    }
+}
+/**
+ * Connect to daemon, run a multi-step pipeline, disconnect.
+ */
+export async function pipelineOnce(steps, opts) {
+    const client = new IpcClient();
+    try {
+        await client.connect();
+        return await client.pipeline(steps, opts);
+    }
+    finally {
+        client.disconnect();
+    }
+}
+/**
+ * Connect to daemon and return a connected client.
+ * For commands that need persistent connection (pipe, watch).
+ */
+export async function connectClient(opts) {
+    const client = new IpcClient(opts);
+    await client.connect();
+    return client;
+}
+export { IPC_SOCKET_PATH };