@parall/daemon 1.32.1 → 1.34.0

package/dist/clip-runtime/clip-provider.js

@@ -15,6 +15,7 @@
  */
 import * as http2 from 'node:http2';
 import { ClipCommandError } from './process.js';
+import { isBrowserDependencyName } from './browser-dependency.js';
 // ---------------------------------------------------------------------------
 // Connect envelope helpers
 // ---------------------------------------------------------------------------
@@ -66,10 +67,17 @@ export class ClipProvider {
     statusUnsubscribe = null;
     manifestUnsubscribe = null;
     needsReregister = false;
-    intentionalClose = false;
+    // Monotonic stream id, bumped by openStream(). Handlers from a stream that a
+    // newer openStream() has superseded bail in handleDisconnect(gen), so their
+    // late close/end/error can't reconnect against the healthy replacement.
+    streamGeneration = 0;
     static RECONNECT_BASE_MS = 5_000;
     static RECONNECT_MAX_MS = 60_000;
     static HEARTBEAT_INTERVAL_MS = 30_000;
+    // After this many consecutive reconnect failures (and every multiple
+    // thereafter), ask the supervisor to refetch the endpoint. See
+    // onPersistentFailure.
+    static PERSISTENT_FAILURE_ATTEMPT = 3;
     constructor(opts) {
         this.opts = opts;
     }
@@ -99,6 +107,8 @@ export class ClipProvider {
     async openStream() {
         if (this.stopped)
             return;
+        // Bind this stream's handlers to a fresh generation; older streams go stale.
+        const gen = ++this.streamGeneration;
         try {
             this.closeStream();
             this.closeSession();
@@ -107,10 +117,10 @@ export class ClipProvider {
             this.session = http2.connect(authority);
             this.session.on('error', (err) => {
                 this.opts.log.warn(`[clip-provider] h2 session error: ${String(err)}`);
-                this.handleDisconnect();
+                this.handleDisconnect(gen);
             });
             this.session.on('close', () => {
-                this.handleDisconnect();
+                this.handleDisconnect(gen);
             });
             this.stream = this.session.request({
                 ':method': 'POST',
@@ -121,7 +131,7 @@ export class ClipProvider {
             });
             this.stream.on('error', (err) => {
                 this.opts.log.warn(`[clip-provider] stream error: ${String(err)}`);
-                this.handleDisconnect();
+                this.handleDisconnect(gen);
             });
             // Read response envelopes
             const decoder = new EnvelopeDecoder();
@@ -144,21 +154,23 @@ export class ClipProvider {
             });
             this.stream.on('end', () => {
                 this.opts.log.info('[clip-provider] stream ended by hub');
-                this.handleDisconnect();
+                this.handleDisconnect(gen);
             });
             this.stream.on('close', () => {
-                this.handleDisconnect();
+                this.handleDisconnect(gen);
             });
             // Send RegisterRequest as the first message.
             await this.sendRegister();
         }
         catch (err) {
             this.opts.log.warn(`[clip-provider] connect failed: ${String(err)}`);
-            this.scheduleReconnect();
+            this.handleDisconnect(gen);
         }
     }
-    handleDisconnect() {
-        if (this.stopped || this.intentionalClose)
+    handleDisconnect(gen) {
+        if (gen !== this.streamGeneration)
+            return; // stale event from a superseded stream
+        if (this.stopped)
             return;
         if (!this.connected && this.reconnectTimer)
             return; // already scheduling
@@ -172,6 +184,19 @@ export class ClipProvider {
         const delay = Math.min(ClipProvider.RECONNECT_BASE_MS * Math.pow(2, this.reconnectAttempt), ClipProvider.RECONNECT_MAX_MS);
         this.reconnectAttempt++;
         this.opts.log.info(`[clip-provider] reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})`);
+        if (this.reconnectAttempt % ClipProvider.PERSISTENT_FAILURE_ATTEMPT === 0) {
+            // The endpoint may have changed server-side since we booted (e.g.
+            // clip_provider_url rolled out while our ws-gateway WS never bounced to
+            // re-trigger machine.hello). Ask the supervisor to refetch machine config;
+            // if the URL changed, applyClipProviderState rebuilds this provider against
+            // the new endpoint. Backoff naturally throttles these refetches.
+            try {
+                this.opts.onPersistentFailure?.();
+            }
+            catch (err) {
+                this.opts.log.warn(`[clip-provider] onPersistentFailure threw: ${String(err)}`);
+            }
+        }
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             void this.openStream();
@@ -198,13 +223,11 @@ export class ClipProvider {
             if (this.needsReregister) {
                 this.needsReregister = false;
                 this.opts.log.info('[clip-provider] manifest updated — reconnecting to re-register clips');
-                this.intentionalClose = true;
-                this.closeStream();
-                this.closeSession();
-                this.intentionalClose = false;
                 this.connected = false;
                 this.clearHeartbeatTimer();
                 this.clearReconnectTimer();
+                // openStream() bumps the generation before closing the old stream, so its
+                // late close events fail the gen check (closing inline would re-arm the flap).
                 void this.openStream();
                 return;
             }
@@ -313,9 +336,25 @@ export class ClipProvider {
                     input = decoded;
                 }
             }
+            // Two routing shapes share this handler, distinguished by clip_name:
+            //  - "browser" capability (cross-machine host hop): clip_token is the
+            //    PLAINTEXT browser_profile_id (used directly as the bb-browser
+            //    account). No local subprocess — serve it against the host
+            //    BrowserProfileManager.
+            //  - ordinary main invoke (this machine is the execution machine): the
+            //    hub carries the executing clip_id in clip_token (Pinix wire
+            //    compatibility — no dedicated field). It shards the process pool and
+            //    fixes the caller identity so the clip's nested browser dependency
+            //    invoke can resolve its binding via the hub. Empty clip_token (plain
+            //    non-browser clips) falls back to the default unsharded process.
+            const invocation = isBrowserDependencyName(clipName)
+                ? this.opts.clipManager.invokeBrowserCapability(cmd.clipToken ?? '', command, input)
+                : this.opts.clipManager.invoke(clipName, command, input, {
+                    clipId: cmd.clipToken || undefined,
+                });
             let timer;
             const output = await Promise.race([
-                this.opts.clipManager.invoke(clipName, command, input),
+                invocation,
                 new Promise((_, reject) => {
                     timer = setTimeout(() => reject(new Error('invoke timeout')), timeoutMs);
                 }),
@@ -378,7 +417,10 @@ export class ClipProvider {
     // Clip registration helpers
     // ---------------------------------------------------------------------------
     buildClipRegistrations() {
-        const clips = this.opts.clipManager.getRegisteredClips();
+        // getProviderClips() appends the synthetic "browser" capability on hosts
+        // that can serve BrowserProfiles, so the hub can route cross-machine
+        // browser invokes to this provider.
+        const clips = this.opts.clipManager.getProviderClips();
         return clips.map((clip) => this.clipConfigToRegistration(clip));
     }
     clipConfigToRegistration(clip) {
@@ -394,7 +436,7 @@ export class ClipProvider {
             domain: manifest?.domain,
             commands,
             hasWeb: manifest?.hasWeb ?? false,
-            dependencies: this.dependencyNames(manifest?.dependencies),
+            dependencies: this.dependencyNames(manifest?.dependencies, manifest?.dependencySlots),
             tokenProtected: Boolean(clip.token),
             name: pkg,
             patterns: manifest?.patterns,
@@ -410,13 +452,13 @@ export class ClipProvider {
             output: detail.output,
         };
     }
-    dependencyNames(deps) {
-        if (!deps)
-            return undefined;
-        const names = Object.entries(deps)
+    dependencyNames(...depMaps) {
+        const names = depMaps
+            .flatMap((deps) => (deps ? Object.entries(deps) : []))
             .map(([slot, dep]) => dep.package ?? slot)
             .filter((name) => name.length > 0);
-        return names.length > 0 ? names : undefined;
+        const uniqueNames = Array.from(new Set(names));
+        return uniqueNames.length > 0 ? uniqueNames : undefined;
     }
     stringEntities(entities) {
         if (!entities)

package/dist/clip-runtime/hub-client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * HubClient — Connect-RPC unary/server-streaming client the execution-side
+ * daemon uses to resolve cross-machine dependency bindings and forward
+ * dependency invokes through the Clip Service (Hub).
+ *
+ * The execution daemon (machine A) does NOT verify the binding's clip_token —
+ * it reads its binding via GetBindings, then passes clip_token straight to
+ * Invoke(clip_name="browser", ...). The hub verifies the signed token, resolves
+ * the bound BrowserProfile's host machine (B), and forwards the InvokeCommand
+ * there. See docs/engineering-design/browser-profile-clip-integration.md §11.3.
+ *
+ * Protocol (same Connect envelope framing as clip-provider.ts):
+ *   POST /clip.v1.ClipHubService/GetBindings   (unary)
+ *   POST /clip.v1.ClipHubService/Invoke        (server-streaming)
+ *   Content-Type: application/connect+json
+ *   Authorization: Bearer mck_xxx               (scope-gated to the caller's
+ *                                                own executing Clip)
+ *   Body / Response: envelope-framed JSON
+ *     [flags:1][length:4 big-endian][JSON payload]
+ *     flags=0x00 data, flags=0x02 end-of-stream (trailers)
+ */
+/** Pinix v2 ClipBinding — a resolved dependency-slot target. */
+export interface ClipBinding {
+    alias?: string;
+    hub?: string;
+    hubToken?: string;
+    clipToken?: string;
+}
+/**
+ * Error surfaced by a hub Invoke that the hub flagged as a clip
+ * application-level rejection (errorIsCommand=true). The execution-side IPC
+ * layer maps this to a non-fatal ClipCommandError so the calling clip is not
+ * crashed by a recoverable browser command failure.
+ */
+export declare class HubCommandError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+export interface HubClientOptions {
+    /** Clip Service URL (grey-cloud clip-rpc host for BYOC). */
+    serviceUrl: string;
+    /** mck_xxx machine key — scope-gated by the hub to this machine's Clips. */
+    authKey: string;
+    /** Optional per-request timeout. */
+    requestTimeoutMs?: number;
+}
+/**
+ * Stateless Connect-RPC client. Each call opens a short-lived HTTP/2 session;
+ * dependency invokes are infrequent relative to the agent dispatch loop, so a
+ * pooled session is not worth the lifecycle complexity here.
+ */
+export declare class HubClient {
+    private readonly opts;
+    constructor(opts: HubClientOptions);
+    /**
+     * GetBindings(clip_name=clipId) → slot→binding map. The hub gates
+     * this to Clips the caller machine actually executes. GetBindings is a
+     * UNARY Connect RPC, so it uses raw JSON framing (not the streaming envelope).
+     */
+    getBindings(clipId: string): Promise<Record<string, ClipBinding>>;
+    /**
+     * Invoke a clip command through the hub, passing the binding's clip_token
+     * through untouched. Aggregates server-streamed output chunks into one value.
+     * The execution daemon does not verify clip_token — the hub does.
+     */
+    invoke(clipName: string, command: string, input: unknown, clipToken: string): Promise<unknown>;
+    /**
+     * Unary Connect call: raw JSON body (no envelope), Content-Type
+     * application/json. The response is raw JSON; a non-2xx status carries a
+     * Connect error envelope ({code,message}) in the body.
+     */
+    private unary;
+    /**
+     * Server-streaming Connect call: enveloped frames over
+     * application/connect+json. Collects all response envelopes.
+     */
+    private serverStream;
+}
+//# sourceMappingURL=hub-client.d.ts.map

package/dist/clip-runtime/hub-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-client.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/hub-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAgDH,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAK3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,gBAAgB;IAEnD;;;;OAIG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAOvE;;;;OAIG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAgCnB;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAgEb;;;OAGG;IACH,OAAO,CAAC,YAAY;CAiGrB"}

package/dist/clip-runtime/hub-client.js

@@ -0,0 +1,320 @@
+/**
+ * HubClient — Connect-RPC unary/server-streaming client the execution-side
+ * daemon uses to resolve cross-machine dependency bindings and forward
+ * dependency invokes through the Clip Service (Hub).
+ *
+ * The execution daemon (machine A) does NOT verify the binding's clip_token —
+ * it reads its binding via GetBindings, then passes clip_token straight to
+ * Invoke(clip_name="browser", ...). The hub verifies the signed token, resolves
+ * the bound BrowserProfile's host machine (B), and forwards the InvokeCommand
+ * there. See docs/engineering-design/browser-profile-clip-integration.md §11.3.
+ *
+ * Protocol (same Connect envelope framing as clip-provider.ts):
+ *   POST /clip.v1.ClipHubService/GetBindings   (unary)
+ *   POST /clip.v1.ClipHubService/Invoke        (server-streaming)
+ *   Content-Type: application/connect+json
+ *   Authorization: Bearer mck_xxx               (scope-gated to the caller's
+ *                                                own executing Clip)
+ *   Body / Response: envelope-framed JSON
+ *     [flags:1][length:4 big-endian][JSON payload]
+ *     flags=0x00 data, flags=0x02 end-of-stream (trailers)
+ */
+import * as http2 from 'node:http2';
+// ---------------------------------------------------------------------------
+// Connect envelope helpers (mirror clip-provider.ts; JSON mode)
+// ---------------------------------------------------------------------------
+const ENVELOPE_FLAG_DATA = 0x00;
+const ENVELOPE_FLAG_TRAILER = 0x02;
+const MAX_FRAME_LENGTH = 16 * 1024 * 1024; // 16 MiB
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+function encodeEnvelope(msg) {
+    const json = Buffer.from(JSON.stringify(msg), 'utf-8');
+    const header = Buffer.alloc(5);
+    header[0] = ENVELOPE_FLAG_DATA;
+    header.writeUInt32BE(json.length, 1);
+    return Buffer.concat([header, json]);
+}
+class EnvelopeDecoder {
+    buf = Buffer.alloc(0);
+    push(chunk) {
+        this.buf = this.buf.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.buf, chunk]);
+    }
+    *flush() {
+        while (this.buf.length >= 5) {
+            const flags = this.buf[0];
+            const length = this.buf.readUInt32BE(1);
+            if (length > MAX_FRAME_LENGTH) {
+                this.buf = Buffer.alloc(0);
+                throw new Error(`envelope frame too large: ${length} bytes`);
+            }
+            if (this.buf.length < 5 + length)
+                break; // incomplete frame
+            const payload = this.buf.subarray(5, 5 + length);
+            this.buf = Buffer.from(this.buf.subarray(5 + length));
+            yield { flags, payload };
+        }
+    }
+}
+/**
+ * Error surfaced by a hub Invoke that the hub flagged as a clip
+ * application-level rejection (errorIsCommand=true). The execution-side IPC
+ * layer maps this to a non-fatal ClipCommandError so the calling clip is not
+ * crashed by a recoverable browser command failure.
+ */
+export class HubCommandError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'HubCommandError';
+        this.code = code;
+    }
+}
+/**
+ * Stateless Connect-RPC client. Each call opens a short-lived HTTP/2 session;
+ * dependency invokes are infrequent relative to the agent dispatch loop, so a
+ * pooled session is not worth the lifecycle complexity here.
+ */
+export class HubClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * GetBindings(clip_name=clipId) → slot→binding map. The hub gates
+     * this to Clips the caller machine actually executes. GetBindings is a
+     * UNARY Connect RPC, so it uses raw JSON framing (not the streaming envelope).
+     */
+    async getBindings(clipId) {
+        const res = await this.unary('GetBindings', {
+            clipName: clipId,
+        });
+        return res.bindings ?? {};
+    }
+    /**
+     * Invoke a clip command through the hub, passing the binding's clip_token
+     * through untouched. Aggregates server-streamed output chunks into one value.
+     * The execution daemon does not verify clip_token — the hub does.
+     */
+    async invoke(clipName, command, input, clipToken) {
+        const inputBytes = Buffer.from(input === undefined ? '{}' : JSON.stringify(input), 'utf-8').toString('base64');
+        const responses = await this.serverStream('Invoke', {
+            clipName,
+            command,
+            input: inputBytes,
+            clipToken,
+        });
+        const chunks = [];
+        for (const resp of responses) {
+            if (resp.error) {
+                const message = resp.error.message || 'hub invoke failed';
+                if (resp.errorIsCommand)
+                    throw new HubCommandError(message, resp.error.code);
+                throw new Error(message);
+            }
+            if (resp.output)
+                chunks.push(decodeOutput(resp.output));
+        }
+        if (chunks.length === 0)
+            return null;
+        if (chunks.length === 1)
+            return chunks[0];
+        return chunks;
+    }
+    // -------------------------------------------------------------------------
+    // Transport
+    // -------------------------------------------------------------------------
+    /**
+     * Unary Connect call: raw JSON body (no envelope), Content-Type
+     * application/json. The response is raw JSON; a non-2xx status carries a
+     * Connect error envelope ({code,message}) in the body.
+     */
+    unary(method, request) {
+        const timeoutMs = this.opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const url = new URL(this.opts.serviceUrl);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const session = http2.connect(url.origin);
+            const chunks = [];
+            let status = 0;
+            const cleanup = () => {
+                clearTimeout(timer);
+                try {
+                    session.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            };
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(err);
+            };
+            const timer = setTimeout(() => fail(new Error(`hub ${method} timed out`)), timeoutMs);
+            timer.unref?.();
+            session.on('error', (err) => fail(new Error(`hub h2 session error: ${String(err)}`)));
+            const body = Buffer.from(JSON.stringify(request), 'utf-8');
+            const stream = session.request({
+                ':method': 'POST',
+                ':path': `/clip.v1.ClipHubService/${method}`,
+                'content-type': 'application/json',
+                'connect-protocol-version': '1',
+                authorization: `Bearer ${this.opts.authKey}`,
+            });
+            stream.on('response', (headers) => {
+                status = Number(headers[':status'] ?? 0);
+            });
+            stream.on('error', (err) => fail(new Error(`hub ${method} stream error: ${String(err)}`)));
+            stream.on('data', (chunk) => chunks.push(chunk));
+            stream.on('end', () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                const text = Buffer.concat(chunks).toString('utf-8');
+                if (status < 200 || status >= 300) {
+                    reject(new Error(`hub ${method} failed (${status}): ${connectErrorMessage(text)}`));
+                    return;
+                }
+                try {
+                    resolve((text ? JSON.parse(text) : {}));
+                }
+                catch (err) {
+                    reject(new Error(`hub ${method} bad response: ${String(err)}`));
+                }
+            });
+            stream.end(body);
+        });
+    }
+    /**
+     * Server-streaming Connect call: enveloped frames over
+     * application/connect+json. Collects all response envelopes.
+     */
+    serverStream(method, request) {
+        const timeoutMs = this.opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const url = new URL(this.opts.serviceUrl);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const session = http2.connect(url.origin);
+            const decoder = new EnvelopeDecoder();
+            const messages = [];
+            const rawChunks = [];
+            let status = 0;
+            const cleanup = () => {
+                clearTimeout(timer);
+                try {
+                    session.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            };
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(err);
+            };
+            const succeed = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(messages);
+            };
+            const timer = setTimeout(() => fail(new Error(`hub ${method} timed out`)), timeoutMs);
+            timer.unref?.();
+            session.on('error', (err) => fail(new Error(`hub h2 session error: ${String(err)}`)));
+            const stream = session.request({
+                ':method': 'POST',
+                ':path': `/clip.v1.ClipHubService/${method}`,
+                'content-type': 'application/connect+json',
+                'connect-protocol-version': '1',
+                authorization: `Bearer ${this.opts.authKey}`,
+            });
+            stream.on('response', (headers) => {
+                status = Number(headers[':status'] ?? 0);
+            });
+            stream.on('error', (err) => fail(new Error(`hub ${method} stream error: ${String(err)}`)));
+            stream.on('data', (chunk) => {
+                try {
+                    // A non-2xx response is NOT a Connect envelope stream (auth/arg/server
+                    // failures return a JSON error body); buffer it raw so we surface the
+                    // hub's code/message instead of a misleading frame-decode error.
+                    if (status < 200 || status >= 300) {
+                        rawChunks.push(chunk);
+                        return;
+                    }
+                    decoder.push(chunk);
+                    for (const envelope of decoder.flush()) {
+                        if (envelope.flags === ENVELOPE_FLAG_TRAILER) {
+                            const trailer = parseTrailer(envelope.payload);
+                            if (trailer?.error) {
+                                fail(new Error(`hub ${method} error: ${trailer.error}`));
+                                return;
+                            }
+                            continue;
+                        }
+                        messages.push(JSON.parse(envelope.payload.toString('utf-8')));
+                    }
+                }
+                catch (err) {
+                    fail(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+            const finish = () => {
+                if (status !== 0 && (status < 200 || status >= 300)) {
+                    fail(new Error(`hub ${method} failed (${status}): ${connectErrorMessage(Buffer.concat(rawChunks).toString('utf-8'))}`));
+                    return;
+                }
+                succeed();
+            };
+            stream.on('end', finish);
+            stream.on('close', finish);
+            stream.end(encodeEnvelope(request));
+        });
+    }
+}
+/**
+ * Connect unary errors carry a JSON body {"code","message"} alongside the HTTP
+ * status. Surface the message (with code) so a hub rejection is actionable.
+ */
+function connectErrorMessage(text) {
+    try {
+        const obj = JSON.parse(text);
+        if (obj?.message)
+            return obj.code ? `${obj.code}: ${obj.message}` : obj.message;
+    }
+    catch {
+        /* not JSON */
+    }
+    return text || 'unknown error';
+}
+function decodeOutput(output) {
+    const decoded = Buffer.from(output, 'base64').toString('utf-8');
+    try {
+        return JSON.parse(decoded);
+    }
+    catch {
+        return decoded;
+    }
+}
+/**
+ * Connect end-of-stream trailers carry an `error` object when the RPC failed.
+ * Surface its message so a hub-level rejection (e.g. 403 BROWSER_BINDING_INVALID)
+ * does not silently resolve to an empty stream.
+ */
+function parseTrailer(payload) {
+    try {
+        const obj = JSON.parse(payload.toString('utf-8'));
+        if (obj?.error)
+            return { error: obj.error.message || 'hub error' };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/clip-runtime/index.d.ts

@@ -3,5 +3,7 @@ export { ClipProcess, ClipCommandError, type ClipProcessStatus, type InvokeEvent
 export { type IpcMessage, type IpcManifest, type ListClipInfo, type ListCommandInfo, type IpcError, MessageType, NdjsonReader, NdjsonWriter, } from './ipc.js';
 export { type ClipConfig, type ManifestCache, type CommandDetail, type ClipJson, } from './manifest.js';
 export { ClipProvider, type ClipProviderOptions } from './clip-provider.js';
+export { HubClient, HubCommandError, type HubClientOptions, type ClipBinding, } from './hub-client.js';
+export { BrowserProfileManager } from './browser-profile-manager.js';
 export { installClip, removeClip, parseSource, type InstallOptions, type InstallResult, } from './clip-installer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/clip-runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,SAAS,EACT,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/clip-runtime/index.js

@@ -2,4 +2,6 @@ export { ClipProcessManager } from './process-manager.js';
 export { ClipProcess, ClipCommandError, } from './process.js';
 export { MessageType, NdjsonReader, NdjsonWriter, } from './ipc.js';
 export { ClipProvider } from './clip-provider.js';
+export { HubClient, HubCommandError, } from './hub-client.js';
+export { BrowserProfileManager } from './browser-profile-manager.js';
 export { installClip, removeClip, parseSource, } from './clip-installer.js';

package/dist/clip-runtime/ipc.d.ts

@@ -22,6 +22,8 @@ export interface IpcMessage {
     input?: unknown;
     output?: unknown;
     error?: string;
+    processExit?: boolean;
+    process_exit?: boolean;
     manifest?: IpcManifest;
     clips?: ListClipInfo[];
     operation?: string;
@@ -43,6 +45,10 @@ export interface IpcManifest {
         package?: string;
         version?: string;
     }>;
+    dependency_slots?: Record<string, {
+        package?: string;
+        version?: string;
+    }>;
     patterns?: string[];
     entities?: Record<string, unknown>;
 }

package/dist/clip-runtime/ipc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/ipc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/ipc.ts"],"names":[],"mappings":"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"}