@parall/cli 1.47.0 → 1.48.0

package/dist/commands/clip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clip.d.ts","sourceRoot":"","sources":["../../src/commands/clip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA0JpD"}
+{"version":3,"file":"clip.d.ts","sourceRoot":"","sources":["../../src/commands/clip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA4OpD"}

package/dist/commands/clip.js

@@ -1,6 +1,7 @@
 import { resolveCredentials } from '../lib/client.js';
 import { invokeClipAwaitingActivation } from '../lib/clip-invoke.js';
-import { printJson, printError } from '../lib/output.js';
+import { execEdgeClipAwaitingActivation } from '../lib/edge-exec.js';
+import { printJson, printError, parsePositiveInt } from '../lib/output.js';
 /**
  * Derive a CLI-friendly alias from a registry source string.
  * Handles scoped packages ("@scope/name@1.0.0" → "name") and
@@ -159,6 +160,66 @@ export function registerClipCommands(program) {
             printError(err);
         }
     });
+    clip
+        .command('exec')
+        .description('Execute a registry (Edge) clip command on an Edge device. A cloud (hosted) profile is reachable ONLY via --connection; with neither --connection nor --edge, the server resolves just your OWN online desktop device (legacy BYOC fallback — never a cloud profile)')
+        .argument('<clip>', 'Clip name in the org clip registry')
+        .argument('<command>', 'Command name to execute')
+        .argument('[args]', 'Command arguments (JSON string or plain text)')
+        .option('--connection <ref>', 'Clip connection id (ccn_…) or alias. REQUIRED to reach a cloud (hosted) profile — the binding its maintainer created is the authorization')
+        .option('--edge <edgeId>', 'A desktop (BYOC) device you own. Mutually exclusive with --connection')
+        .option('--profile <name>', 'Browser profile (with --connection it may only restate the granted one)')
+        .option('--timeout <ms>', 'Execution timeout in milliseconds', '30000')
+        .action(async (clipName, command, args, opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            let parsedArgs;
+            if (args !== undefined) {
+                try {
+                    parsedArgs = JSON.parse(args);
+                }
+                catch {
+                    parsedArgs = args;
+                }
+            }
+            // Strict grammar, validated BEFORE the wire: parseInt would accept
+            // "5000ms" or "1.5", and the server silently replaces an out-of-range
+            // timeout with its 30s default — so a malformed flag would run with a
+            // deadline the caller never asked for. printError never returns.
+            let timeoutMs;
+            if (opts?.timeout) {
+                timeoutMs = parsePositiveInt(opts.timeout);
+                if (timeoutMs === undefined || timeoutMs > 120_000) {
+                    printError(new Error('--timeout must be an integer between 1 and 120000 (milliseconds)'));
+                }
+            }
+            const req = {
+                clip: clipName,
+                command,
+                args: parsedArgs,
+                connection: opts?.connection,
+                edge_id: opts?.edge,
+                profile: opts?.profile,
+                timeout: timeoutMs,
+            };
+            // A cold cloud profile answers 503 EDGE_ACTIVATING BEFORE anything is
+            // dispatched; absorb that one retryable window here (bounded, one
+            // correlation id) instead of making every agent hand-roll a loop.
+            // Everything else — OUTCOME_UNKNOWN above all — propagates untouched:
+            // a dispatched command may have executed, and retrying it is not this
+            // tool's call. See lib/edge-exec.ts.
+            const result = await execEdgeClipAwaitingActivation(client, orgId, req);
+            if (result.success) {
+                printJson(result.data ?? null);
+            }
+            else {
+                printError(new Error(result.error ?? 'execution failed'));
+            }
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
     clip
         .command('remove')
         .description('Remove a clip by alias')

package/dist/lib/edge-exec.d.ts

@@ -0,0 +1,55 @@
+import type { EdgeClipExecResult, ExecEdgeClipRequest, ParallClient } from '@parall/sdk';
+/**
+ * Cloud (hosted) Edge activation wait — CLI-side bounded retry for `clip exec`.
+ *
+ * A clip connection bound to a `placement=hosted` Edge whose pod is cold returns
+ * 503 EDGE_ACTIVATING from the exec pre-flight: the platform is starting the
+ * pod, and the command has NOT been dispatched (the server answers before any
+ * publish), so retrying the identical request cannot double-execute anything.
+ * This module absorbs that one precise error so a single `parall clip exec`
+ * rides through cold start instead of forcing the caller (agent or human) into
+ * a blind retry loop.
+ *
+ * Everything else propagates on first occurrence — especially OUTCOME_UNKNOWN
+ * (504): the command was dispatched and MAY HAVE EXECUTED; an automatic retry
+ * could post, order or delete twice. That decision belongs to the caller, with
+ * the request id from the error message, never to a loop in here.
+ *
+ * Deliberately NOT in the SDK: `execEdgeClip()` keeps its throw-on-503
+ * semantics for every other consumer; only the CLI exec behavior waits.
+ * Mirrors lib/clip-invoke.ts (the v2 hosted-browser wait) — same budget, same
+ * schedule, same exact-code matching discipline.
+ */
+/** Total activation wait budget. Independent of the clip command --timeout:
+ *  each attempt keeps its own full command timeout, so worst-case wall clock is
+ *  roughly this budget plus one command timeout. */
+export declare const EDGE_ACTIVATION_WAIT_BUDGET_MS = 60000;
+/** Backoff schedule between activation retries; the last entry repeats. */
+export declare const EDGE_ACTIVATION_BACKOFF_MS: number[];
+/** Injectable time hooks so tests never really sleep. */
+export type EdgeActivationWaitHooks = {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+/**
+ * The ONLY retryable error: a typed ApiError carrying exactly 503 +
+ * EDGE_ACTIVATING. Everything else — routing errors, EDGE_BUSY, capacity,
+ * repair, command failures, timeouts, OUTCOME_UNKNOWN, other 5xx — means
+ * retrying is either pointless or unsafe, so it propagates unchanged on the
+ * first occurrence.
+ */
+export declare function isEdgeActivationPending(err: unknown): boolean;
+/**
+ * Execute an Edge clip, transparently absorbing the cloud-profile activation
+ * window.
+ *
+ * Retries the IDENTICAL request while the server reports EDGE_ACTIVATING,
+ * backing off 500ms → 1s → 2s (capped) until the 60s activation budget is
+ * spent. The whole loop carries one `correlation_id` (the caller's, or one
+ * minted here) so the server's exec audit reads the retries as a single
+ * logical call. Once the budget is spent, the LAST typed ApiError is rethrown
+ * as-is — status/code intact — so the printed error stays machine-readable.
+ * Any other failure is rethrown immediately.
+ */
+export declare function execEdgeClipAwaitingActivation(client: Pick<ParallClient, 'execEdgeClip'>, orgId: string, req: ExecEdgeClipRequest, hooks?: EdgeActivationWaitHooks): Promise<EdgeClipExecResult>;
+//# sourceMappingURL=edge-exec.d.ts.map

package/dist/lib/edge-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-exec.d.ts","sourceRoot":"","sources":["../../src/lib/edge-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzF;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;oDAEoD;AACpD,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAErD,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,UAAsB,CAAC;AAE9D,yDAAyD;AACzD,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,EAC1C,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,mBAAmB,EACxB,KAAK,CAAC,EAAE,uBAAuB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAuB7B"}

package/dist/lib/edge-exec.js

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { ApiError } from '@parall/sdk';
+/**
+ * Cloud (hosted) Edge activation wait — CLI-side bounded retry for `clip exec`.
+ *
+ * A clip connection bound to a `placement=hosted` Edge whose pod is cold returns
+ * 503 EDGE_ACTIVATING from the exec pre-flight: the platform is starting the
+ * pod, and the command has NOT been dispatched (the server answers before any
+ * publish), so retrying the identical request cannot double-execute anything.
+ * This module absorbs that one precise error so a single `parall clip exec`
+ * rides through cold start instead of forcing the caller (agent or human) into
+ * a blind retry loop.
+ *
+ * Everything else propagates on first occurrence — especially OUTCOME_UNKNOWN
+ * (504): the command was dispatched and MAY HAVE EXECUTED; an automatic retry
+ * could post, order or delete twice. That decision belongs to the caller, with
+ * the request id from the error message, never to a loop in here.
+ *
+ * Deliberately NOT in the SDK: `execEdgeClip()` keeps its throw-on-503
+ * semantics for every other consumer; only the CLI exec behavior waits.
+ * Mirrors lib/clip-invoke.ts (the v2 hosted-browser wait) — same budget, same
+ * schedule, same exact-code matching discipline.
+ */
+/** Total activation wait budget. Independent of the clip command --timeout:
+ *  each attempt keeps its own full command timeout, so worst-case wall clock is
+ *  roughly this budget plus one command timeout. */
+export const EDGE_ACTIVATION_WAIT_BUDGET_MS = 60_000;
+/** Backoff schedule between activation retries; the last entry repeats. */
+export const EDGE_ACTIVATION_BACKOFF_MS = [500, 1_000, 2_000];
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * The ONLY retryable error: a typed ApiError carrying exactly 503 +
+ * EDGE_ACTIVATING. Everything else — routing errors, EDGE_BUSY, capacity,
+ * repair, command failures, timeouts, OUTCOME_UNKNOWN, other 5xx — means
+ * retrying is either pointless or unsafe, so it propagates unchanged on the
+ * first occurrence.
+ */
+export function isEdgeActivationPending(err) {
+    return err instanceof ApiError && err.status === 503 && err.code === 'EDGE_ACTIVATING';
+}
+/**
+ * Execute an Edge clip, transparently absorbing the cloud-profile activation
+ * window.
+ *
+ * Retries the IDENTICAL request while the server reports EDGE_ACTIVATING,
+ * backing off 500ms → 1s → 2s (capped) until the 60s activation budget is
+ * spent. The whole loop carries one `correlation_id` (the caller's, or one
+ * minted here) so the server's exec audit reads the retries as a single
+ * logical call. Once the budget is spent, the LAST typed ApiError is rethrown
+ * as-is — status/code intact — so the printed error stays machine-readable.
+ * Any other failure is rethrown immediately.
+ */
+export async function execEdgeClipAwaitingActivation(client, orgId, req, hooks) {
+    const sleep = hooks?.sleep ?? realSleep;
+    const now = hooks?.now ?? Date.now;
+    const pinned = {
+        ...req,
+        correlation_id: req.correlation_id ?? randomUUID(),
+    };
+    const deadline = now() + EDGE_ACTIVATION_WAIT_BUDGET_MS;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await client.execEdgeClip(orgId, pinned);
+        }
+        catch (err) {
+            if (!isEdgeActivationPending(err))
+                throw err;
+            const remaining = deadline - now();
+            if (remaining <= 0)
+                throw err;
+            const backoff = EDGE_ACTIVATION_BACKOFF_MS[Math.min(attempt, EDGE_ACTIVATION_BACKOFF_MS.length - 1)];
+            // Clamp to the remaining budget so the final sleep can't overrun it.
+            await sleep(Math.min(backoff, remaining));
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/cli",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "description": "CLI client for Parall — universal agent & human access to Parall API",
   "license": "MIT",
   "repository": {
@@ -36,14 +36,14 @@
     "diff": "^8.0.3",
     "js-yaml": "^4.1.0",
     "zod": "^4.3.6",
-    "@parall/agent-core": "1.47.0",
-    "@parall/sdk": "1.47.0"
+    "@parall/agent-core": "1.48.0",
+    "@parall/sdk": "1.48.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.47.0"
+    "@parall/agent-core": "1.48.0"
   },
   "scripts": {
     "build": "tsc",