@parall/daemon 1.32.0 → 1.33.0

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

@@ -11,6 +11,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { pipeline } from 'node:stream/promises';
+import { findBunBinary } from './bun-resolver.js';
 const DEFAULT_REGISTRY_URL = 'https://api.pinixai.com';
 // ---------------------------------------------------------------------------
 // Source parsing
@@ -406,28 +407,68 @@ function installDeps(clipDir) {
     catch {
         /* ignore parse error, try install anyway */
     }
-    const runners = [
-        { cmd: 'bun', args: ['install', '--frozen-lockfile'] },
-        { cmd: 'bun', args: ['install'] },
-        { cmd: 'npm', args: ['install', '--production'] },
-    ];
-    for (const runner of runners) {
-        try {
-            execFileSync(runner.cmd, runner.args, {
-                cwd: clipDir,
-                stdio: 'pipe',
-                timeout: 120_000,
-            });
-            return;
-        }
-        catch {
-            // try next runner
+    // Reasons each attempt failed — surfaced in the thrown error so a clip that
+    // genuinely needs deps reports *why* installation failed, not just "no
+    // package manager succeeded".
+    const failures = [];
+    // Bun is the reliable path. Resolve it the same way the process manager
+    // resolves the runtime bun (embedded-first, then ~/.bun / Homebrew / PATH) —
+    // a bare `bun` would not be found under the daemon's minimal launchd PATH
+    // (/usr/bin:/bin:/usr/sbin:/sbin). We invoke bun by absolute path below, and
+    // also prepend its directory to the child PATH so a dependency's postinstall
+    // hook that shells out to `bun` by name resolves it. The embedded binary is
+    // landed under the canonical name `bun` (Frameworks/bun) precisely so this
+    // by-name lookup works — a `parall-bun` filename would defeat it.
+    let bunPath = null;
+    try {
+        bunPath = findBunBinary();
+    }
+    catch (err) {
+        failures.push(`resolve bun: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (bunPath) {
+        const bunEnv = {
+            ...process.env,
+            PATH: `${path.dirname(bunPath)}${path.delimiter}${process.env.PATH ?? ''}`,
+        };
+        // Prefer a reproducible install when a lockfile is present, then fall back
+        // to a plain install (no lockfile / lockfile drift).
+        for (const args of [['install', '--frozen-lockfile'], ['install']]) {
+            try {
+                execFileSync(bunPath, args, {
+                    cwd: clipDir,
+                    stdio: 'pipe',
+                    timeout: 120_000,
+                    env: bunEnv,
+                });
+                return;
+            }
+            catch (err) {
+                failures.push(`bun ${args.join(' ')}: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
+    // Best-effort npm fallback. The packaged desktop app embeds bun but NOT npm,
+    // so this only succeeds on dev/CLI hosts that already have npm on PATH; it is
+    // never the reliable path. Kept so a developer running the bare daemon with
+    // npm-but-no-bun still resolves dependencies.
+    try {
+        execFileSync('npm', ['install', '--production'], {
+            cwd: clipDir,
+            stdio: 'pipe',
+            timeout: 120_000,
+        });
+        return;
+    }
+    catch (err) {
+        failures.push(`npm install: ${err instanceof Error ? err.message : String(err)}`);
+    }
     if (hasDeps) {
-        throw new Error(`failed to install dependencies in ${clipDir} — clip declares dependencies but no package manager succeeded`);
+        throw new Error(`failed to install dependencies in ${clipDir} — clip declares dependencies but no ` +
+            `package manager succeeded:\n  ${failures.join('\n  ')}`);
     }
-    console.warn(`[clip-installer] could not run package manager in ${clipDir} (no dependencies declared, continuing)`);
+    console.warn(`[clip-installer] could not run a package manager in ${clipDir} ` +
+        `(no dependencies declared, continuing): ${failures.join('; ')}`);
 }
 // ---------------------------------------------------------------------------
 // Public API

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

@@ -19,7 +19,7 @@ export interface ClipProviderOptions {
     serviceUrl: string;
     /** mck_xxx machine key for authorization. */
     authKey: string;
-    /** Org to register for. */
+    /** Machine org, used for local logging; Hub derives org from auth. */
     orgId: string;
     /** Unique provider name (typically machine ID). */
     providerName: string;
@@ -31,6 +31,14 @@ export interface ClipProviderOptions {
         warn(msg: string): void;
         error(msg: string): void;
     };
+    /**
+     * Invoked after several consecutive reconnect failures (throttled by backoff).
+     * Lets the supervisor refetch machine config and, if the endpoint changed,
+     * rebuild this provider — e.g. when clip_provider_url rolls out server-side
+     * after this daemon booted while its ws-gateway WS never bounced to
+     * re-trigger machine.hello. Optional.
+     */
+    onPersistentFailure?: () => void;
 }
 export declare class ClipProvider {
     private readonly opts;
@@ -44,10 +52,11 @@ export declare class ClipProvider {
     private statusUnsubscribe;
     private manifestUnsubscribe;
     private needsReregister;
-    private intentionalClose;
+    private streamGeneration;
     private static RECONNECT_BASE_MS;
     private static RECONNECT_MAX_MS;
     private static HEARTBEAT_INTERVAL_MS;
+    private static PERSISTENT_FAILURE_ATTEMPT;
     constructor(opts: ClipProviderOptions);
     /** Connect to the Clip Service and register local clips. Reconnects on failure. */
     connect(): Promise<void>;
@@ -72,5 +81,7 @@ export declare class ClipProvider {
     private buildClipRegistrations;
     private clipConfigToRegistration;
     private commandDetailToInfo;
+    private dependencyNames;
+    private stringEntities;
 }
 //# sourceMappingURL=clip-provider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"clip-provider.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/clip-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA4H/D,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,WAAW,EAAE,kBAAkB,CAAC;IAChC,mBAAmB;IACnB,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACrF;AAED,qBAAa,YAAY;IAiBX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAhBjC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAS;IACzC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAU;IACzC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAU;gBAEjB,IAAI,EAAE,mBAAmB;IAEtD,mFAAmF;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,wCAAwC;IAClC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC,WAAW,IAAI,OAAO;YAQR,UAAU;IAoExB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,sBAAsB;IAyB9B,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,gBAAgB;YAeV,mBAAmB;YAsDnB,YAAY;YAWZ,mBAAmB;IAiBjC,OAAO,CAAC,sBAAsB;IAK9B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,mBAAmB;CAU5B"}
+{"version":3,"file":"clip-provider.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/clip-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA+I/D,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,WAAW,EAAE,kBAAkB,CAAC;IAChC,mBAAmB;IACnB,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpF;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,qBAAa,YAAY;IAwBX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAvBjC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,eAAe,CAAS;IAIhC,OAAO,CAAC,gBAAgB,CAAK;IAE7B,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAS;IACzC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAU;IACzC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAU;IAI9C,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAK;gBAEjB,IAAI,EAAE,mBAAmB;IAEtD,mFAAmF;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,wCAAwC;IAClC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC,WAAW,IAAI,OAAO;YAQR,UAAU;IAuExB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,sBAAsB;IAyB9B,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,gBAAgB;YAeV,mBAAmB;YA0EnB,YAAY;YAUZ,mBAAmB;IAiBjC,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,cAAc;CAUvB"}

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 ProviderRegister as the first message
+            // 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,17 +223,15 @@ 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;
             }
-            this.sendProviderMessage({ heartbeat: {} }).catch((err) => {
+            this.sendProviderMessage({ ping: { sentAtUnixMs: Date.now() } }).catch((err) => {
                 this.opts.log.warn(`[clip-provider] heartbeat send failed: ${String(err)}`);
             });
         }, ClipProvider.HEARTBEAT_INTERVAL_MS);
@@ -242,16 +265,16 @@ export class ClipProvider {
     subscribeStatusChanges() {
         const mgr = this.opts.clipManager;
         // Forward clip status changes to the Hub
-        this.statusUnsubscribe = mgr.addStatusListener((name, status, _message) => {
+        this.statusUnsubscribe = mgr.addStatusListener((name, status, message) => {
             if (!this.connected)
                 return;
             const protoStatus = status === 'running'
-                ? 'CLIP_ONLINE_STATUS_ONLINE'
+                ? 'CLIP_STATUS_RUNNING'
                 : status === 'error'
-                    ? 'CLIP_ONLINE_STATUS_ERROR'
-                    : 'CLIP_ONLINE_STATUS_OFFLINE';
+                    ? 'CLIP_STATUS_ERROR'
+                    : 'CLIP_STATUS_SLEEPING';
             this.sendProviderMessage({
-                clipStatusChanged: { alias: name, status: protoStatus },
+                clipStatusChanged: { name, status: protoStatus, message },
             }).catch((err) => {
                 this.opts.log.warn(`[clip-provider] status change send failed: ${String(err)}`);
             });
@@ -271,20 +294,22 @@ export class ClipProvider {
     // Message handling
     // ---------------------------------------------------------------------------
     handleHubMessage(msg) {
-        if (msg.registered) {
-            this.handleRegistered(msg.registered);
+        if (msg.registerResponse) {
+            this.handleRegistered(msg.registerResponse);
         }
         else if (msg.invokeCommand) {
             void this.handleInvokeCommand(msg.invokeCommand);
         }
-        else if (msg.heartbeat !== undefined) {
-            // Respond to hub heartbeat with provider heartbeat
-            this.sendProviderMessage({ heartbeat: {} }).catch(() => { });
+        else if (msg.pong !== undefined) {
+            // Pong is the hub's keepalive ack. Do NOT echo a ping here — the
+            // heartbeat timer (startHeartbeat) is the sole ping driver. Replying to
+            // every pong with a ping turns the 30s interval into an unbounded
+            // ping↔pong loop the moment the first timer tick fires.
         }
     }
     handleRegistered(reg) {
         if (reg.accepted) {
-            this.opts.log.info(`[clip-provider] registered with hub (org=${reg.orgId})`);
+            this.opts.log.info(`[clip-provider] registered with hub (org=${this.opts.orgId})`);
             this.connected = true;
             this.reconnectAttempt = 0;
             this.startHeartbeat();
@@ -298,7 +323,7 @@ export class ClipProvider {
         }
     }
     async handleInvokeCommand(cmd) {
-        const { requestId, clipAlias, commandName } = cmd;
+        const { requestId, clipName, command } = cmd;
         const timeoutMs = cmd.timeoutMs ?? 30_000;
         try {
             let input;
@@ -311,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(clipAlias, commandName, input),
+                invocation,
                 new Promise((_, reject) => {
                     timer = setTimeout(() => reject(new Error('invoke timeout')), timeoutMs);
                 }),
@@ -336,7 +377,10 @@ export class ClipProvider {
             await this.sendProviderMessage({
                 invokeResult: {
                     requestId,
-                    error: isCommandError ? err.message : String(err),
+                    error: {
+                        code: isCommandError ? 'CLIP_COMMAND_ERROR' : 'INVOKE_FAILED',
+                        message: isCommandError ? err.message : String(err),
+                    },
                     errorIsCommand: isCommandError,
                     done: true,
                 },
@@ -352,7 +396,6 @@ export class ClipProvider {
             register: {
                 providerName: this.opts.providerName,
                 clips,
-                orgId: this.opts.orgId,
             },
         });
     }
@@ -374,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) {
@@ -382,21 +428,45 @@ export class ClipProvider {
         const commands = manifest
             ? manifest.commandDetails.map((cmd) => this.commandDetailToInfo(cmd))
             : [];
+        const pkg = manifest?.package ?? clip.package ?? clip.name;
         return {
             alias: clip.name,
-            name: manifest?.package ?? clip.package ?? clip.name,
+            package: pkg,
             version: manifest?.version ?? clip.version ?? '',
+            domain: manifest?.domain,
             commands,
+            hasWeb: manifest?.hasWeb ?? false,
+            dependencies: this.dependencyNames(manifest?.dependencies, manifest?.dependencySlots),
+            tokenProtected: Boolean(clip.token),
+            name: pkg,
+            patterns: manifest?.patterns,
+            entities: this.stringEntities(manifest?.entities),
+            description: manifest?.description,
         };
     }
     commandDetailToInfo(detail) {
         return {
             name: detail.name,
             description: detail.description ?? '',
-            inputSchema: detail.input ? Buffer.from(detail.input, 'utf-8').toString('base64') : undefined,
-            outputSchema: detail.output
-                ? Buffer.from(detail.output, 'utf-8').toString('base64')
-                : undefined,
+            input: detail.input,
+            output: detail.output,
         };
     }
+    dependencyNames(...depMaps) {
+        const names = depMaps
+            .flatMap((deps) => (deps ? Object.entries(deps) : []))
+            .map(([slot, dep]) => dep.package ?? slot)
+            .filter((name) => name.length > 0);
+        const uniqueNames = Array.from(new Set(names));
+        return uniqueNames.length > 0 ? uniqueNames : undefined;
+    }
+    stringEntities(entities) {
+        if (!entities)
+            return undefined;
+        const out = {};
+        for (const [key, value] of Object.entries(entities)) {
+            out[key] = typeof value === 'string' ? value : JSON.stringify(value);
+        }
+        return out;
+    }
 }

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"}