@parall/cli 1.50.1 → 1.52.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;AAgCpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAmQpD"}
+{"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,QAiSpD"}

package/dist/commands/clip.js

@@ -1,6 +1,6 @@
 import { resolveCredentials } from '../lib/client.js';
 import { invokeClipAwaitingActivation } from '../lib/clip-invoke.js';
-import { execEdgeClipAwaitingActivation } from '../lib/edge-exec.js';
+import { execEdgeClipWithBoundedWait } from '../lib/edge-exec.js';
 import { printJson, printError, parsePositiveInt } from '../lib/output.js';
 /**
  * Derive a CLI-friendly alias from a registry source string.
@@ -134,6 +134,32 @@ export function registerClipCommands(program) {
             printError(err);
         }
     });
+    clip
+        .command('tools')
+        .description('List the MCP tool schemas (name, description, inputSchema) of an MCP clip by alias — the discovery step before `clip exec <clip> <tool>`')
+        .argument('<alias>', 'Clip alias')
+        .action(async (alias) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            // Resolve alias to clip ID — same lookup `clip connections`/`info` use.
+            const clips = await client.listClips(orgId);
+            const found = clips.find((c) => c.alias === alias);
+            if (!found) {
+                printError(new Error(`Clip with alias "${alias}" not found`));
+            }
+            // MCP tools are NOT frozen in the clip manifest, so `clip info` cannot
+            // show them; the live server snapshot behind getClipMCPConfig is the
+            // only source. name/description/inputSchema ride verbatim in each tool
+            // object — print it as-is (untrusted external data, not instructions).
+            // A non-MCP clip has no config here: the server answers 404 NOT_FOUND
+            // ("this clip has no MCP config"), which printError surfaces faithfully.
+            const config = await client.getClipMCPConfig(orgId, found.id);
+            printJson(config.tools ?? []);
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
     clip
         .command('invoke')
         .description('Invoke a clip command')
@@ -225,13 +251,15 @@ export function registerClipCommands(program) {
                 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);
+            // The three provably-safe refusals — EDGE_ACTIVATING (cold start),
+            // EDGE_BUSY (single exec slot), EDGE_CONCURRENCY_LIMIT (org capacity)
+            // — are absorbed here with a bounded wait (per-code Retry-After
+            // pacing, one absolute deadline, 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 execEdgeClipWithBoundedWait(client, orgId, req);
             if (result.success) {
                 printJson(result.data ?? null);
             }

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

@@ -1,55 +1,71 @@
 import type { EdgeClipExecResult, ExecEdgeClipRequest, ParallClient } from '@parall/sdk';
 /**
- * Cloud (hosted) Edge activation wait — CLI-side bounded retry for `clip exec`.
+ * Cloud (hosted) Edge bounded wait — CLI-side retry for `clip exec` across the
+ * three refusals that are provably safe to retry
+ * (edge-concurrency-reclaim-redesign §2.3 / §3.1):
  *
- * 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.
+ *   - 503 EDGE_ACTIVATING        — the pod is cold-starting. Answered before
+ *     any publish; "nothing happened" is locally provable.
+ *   - 429 EDGE_CONCURRENCY_LIMIT — the org is at capacity. Same pre-publish
+ *     guarantee, from the EnsureLease branch.
+ *   - 409 EDGE_BUSY              — the pod is running another exec. STRICTLY
+ *     WEAKER guarantee: the request DID reach the pod, which refused it before
+ *     starting the worker. Its safety rests on that reply being received — a
+ *     reply lost on the way back surfaces as OUTCOME_UNKNOWN, never as
+ *     EDGE_BUSY, so "thought busy, actually ran" cannot happen.
  *
- * Everything else propagates on first occurrence — especially OUTCOME_UNKNOWN
+ * Each code follows its own pace: the server's Retry-After wins when present;
+ * without it (older servers) each code falls back to its own default schedule.
+ * All three share ONE absolute deadline — the CLI's task boundary — never a
+ * per-code sum. On expiry the LAST typed ApiError is rethrown as-is, so the
+ * error's code names which class of wait ran out.
+ *
+ * Everything else propagates on first occurrence — above all 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
+ * Deliberately NOT in the SDK: `execEdgeClip()` keeps its throw-on-error
  * 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. */
+/** One absolute wait deadline shared by ALL waitable codes (never per-code).
+ *  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_EXEC_WAIT_BUDGET_MS = 120000;
+/** EDGE_ACTIVATING fallback schedule when the server sends no Retry-After
+ *  (matches the pre-Retry-After deployed behavior); the last entry repeats. */
 export declare const EDGE_ACTIVATION_BACKOFF_MS: number[];
+/** EDGE_BUSY fallback: the in-flight exec finishes within its command timeout,
+ *  so poll on the order of seconds. */
+export declare const EDGE_BUSY_FALLBACK_BACKOFF_MS = 5000;
+/** EDGE_CONCURRENCY_LIMIT fallback: capacity frees only through another
+ *  lease's full release + teardown — slower and high-variance. */
+export declare const EDGE_CONCURRENCY_FALLBACK_BACKOFF_MS = 15000;
 /** 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.
- */
+type WaitableCode = 'EDGE_ACTIVATING' | 'EDGE_CONCURRENCY_LIMIT' | 'EDGE_BUSY';
+/** The waitable refusal this error carries, or null. Only a real SDK ApiError
+ *  with the exact status+code pairing counts — duck-typed shapes, bare
+ *  statuses and everything else (routing errors, repair, command failures,
+ *  timeouts, OUTCOME_UNKNOWN, other 5xx) mean waiting is pointless or unsafe. */
+export declare function waitableEdgeRefusal(err: unknown): WaitableCode | null;
+/** Back-compat predicate: exactly the cold-start signal. */
 export declare function isEdgeActivationPending(err: unknown): boolean;
 /**
- * Execute an Edge clip, transparently absorbing the cloud-profile activation
- * window.
+ * Execute an Edge clip, waiting (bounded) through activation, busy and
+ * capacity refusals.
  *
- * 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.
+ * Retries the IDENTICAL request, pacing each code by its server Retry-After
+ * (fallback: the code's own schedule), all under one absolute deadline. 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 deadline passes, the LAST typed ApiError is rethrown as-is —
+ * status/code intact — so the printed error stays machine-readable and names
+ * the class of wait that ran out. Any other failure is rethrown immediately.
  */
-export declare function execEdgeClipAwaitingActivation(client: Pick<ParallClient, 'execEdgeClip'>, orgId: string, req: ExecEdgeClipRequest, hooks?: EdgeActivationWaitHooks): Promise<EdgeClipExecResult>;
+export declare function execEdgeClipWithBoundedWait(client: Pick<ParallClient, 'execEdgeClip'>, orgId: string, req: ExecEdgeClipRequest, hooks?: EdgeActivationWaitHooks): Promise<EdgeClipExecResult>;
+export {};
 //# sourceMappingURL=edge-exec.d.ts.map

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;uDAEuD;AACvD,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD;+EAC+E;AAC/E,eAAO,MAAM,0BAA0B,UAAsB,CAAC;AAE9D;uCACuC;AACvC,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD;kEACkE;AAClE,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D,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,KAAK,YAAY,GAAG,iBAAiB,GAAG,wBAAwB,GAAG,WAAW,CAAC;AAgB/E;;;iFAGiF;AACjF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAIrE;AAED,4DAA4D;AAC5D,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,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,CAiC7B"}

package/dist/lib/edge-exec.js

@@ -1,74 +1,114 @@
 import { randomUUID } from 'node:crypto';
 import { ApiError } from '@parall/sdk';
 /**
- * Cloud (hosted) Edge activation wait — CLI-side bounded retry for `clip exec`.
+ * Cloud (hosted) Edge bounded wait — CLI-side retry for `clip exec` across the
+ * three refusals that are provably safe to retry
+ * (edge-concurrency-reclaim-redesign §2.3 / §3.1):
  *
- * 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.
+ *   - 503 EDGE_ACTIVATING        — the pod is cold-starting. Answered before
+ *     any publish; "nothing happened" is locally provable.
+ *   - 429 EDGE_CONCURRENCY_LIMIT — the org is at capacity. Same pre-publish
+ *     guarantee, from the EnsureLease branch.
+ *   - 409 EDGE_BUSY              — the pod is running another exec. STRICTLY
+ *     WEAKER guarantee: the request DID reach the pod, which refused it before
+ *     starting the worker. Its safety rests on that reply being received — a
+ *     reply lost on the way back surfaces as OUTCOME_UNKNOWN, never as
+ *     EDGE_BUSY, so "thought busy, actually ran" cannot happen.
  *
- * Everything else propagates on first occurrence — especially OUTCOME_UNKNOWN
+ * Each code follows its own pace: the server's Retry-After wins when present;
+ * without it (older servers) each code falls back to its own default schedule.
+ * All three share ONE absolute deadline — the CLI's task boundary — never a
+ * per-code sum. On expiry the LAST typed ApiError is rethrown as-is, so the
+ * error's code names which class of wait ran out.
+ *
+ * Everything else propagates on first occurrence — above all 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
+ * Deliberately NOT in the SDK: `execEdgeClip()` keeps its throw-on-error
  * 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. */
+/** One absolute wait deadline shared by ALL waitable codes (never per-code).
+ *  Each attempt keeps its own full command timeout, so worst-case wall clock
+ *  is roughly this budget plus one command timeout. */
+export const EDGE_EXEC_WAIT_BUDGET_MS = 120_000;
+/** EDGE_ACTIVATING fallback schedule when the server sends no Retry-After
+ *  (matches the pre-Retry-After deployed behavior); the last entry repeats. */
 export const EDGE_ACTIVATION_BACKOFF_MS = [500, 1_000, 2_000];
+/** EDGE_BUSY fallback: the in-flight exec finishes within its command timeout,
+ *  so poll on the order of seconds. */
+export const EDGE_BUSY_FALLBACK_BACKOFF_MS = 5_000;
+/** EDGE_CONCURRENCY_LIMIT fallback: capacity frees only through another
+ *  lease's full release + teardown — slower and high-variance. */
+export const EDGE_CONCURRENCY_FALLBACK_BACKOFF_MS = 15_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.
- */
+/** Exact (status, code) pairs — a matching code on the wrong status is a
+ *  malformed answer and must fail fast, not wait. attempt counts per code so
+ *  the activation ramp is not consumed by interleaved busy/capacity waits. */
+const WAITABLE = {
+    EDGE_ACTIVATING: {
+        status: 503,
+        fallbackMs: (attempt) => EDGE_ACTIVATION_BACKOFF_MS[Math.min(attempt, EDGE_ACTIVATION_BACKOFF_MS.length - 1)],
+    },
+    EDGE_CONCURRENCY_LIMIT: { status: 429, fallbackMs: () => EDGE_CONCURRENCY_FALLBACK_BACKOFF_MS },
+    EDGE_BUSY: { status: 409, fallbackMs: () => EDGE_BUSY_FALLBACK_BACKOFF_MS },
+};
+/** The waitable refusal this error carries, or null. Only a real SDK ApiError
+ *  with the exact status+code pairing counts — duck-typed shapes, bare
+ *  statuses and everything else (routing errors, repair, command failures,
+ *  timeouts, OUTCOME_UNKNOWN, other 5xx) mean waiting is pointless or unsafe. */
+export function waitableEdgeRefusal(err) {
+    if (!(err instanceof ApiError) || !err.code)
+        return null;
+    const spec = WAITABLE[err.code];
+    return spec && err.status === spec.status ? err.code : null;
+}
+/** Back-compat predicate: exactly the cold-start signal. */
 export function isEdgeActivationPending(err) {
-    return err instanceof ApiError && err.status === 503 && err.code === 'EDGE_ACTIVATING';
+    return waitableEdgeRefusal(err) === 'EDGE_ACTIVATING';
 }
 /**
- * Execute an Edge clip, transparently absorbing the cloud-profile activation
- * window.
+ * Execute an Edge clip, waiting (bounded) through activation, busy and
+ * capacity refusals.
  *
- * 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.
+ * Retries the IDENTICAL request, pacing each code by its server Retry-After
+ * (fallback: the code's own schedule), all under one absolute deadline. 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 deadline passes, the LAST typed ApiError is rethrown as-is —
+ * status/code intact — so the printed error stays machine-readable and names
+ * the class of wait that ran out. Any other failure is rethrown immediately.
  */
-export async function execEdgeClipAwaitingActivation(client, orgId, req, hooks) {
+export async function execEdgeClipWithBoundedWait(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++) {
+    const deadline = now() + EDGE_EXEC_WAIT_BUDGET_MS;
+    const attempts = {
+        EDGE_ACTIVATING: 0,
+        EDGE_CONCURRENCY_LIMIT: 0,
+        EDGE_BUSY: 0,
+    };
+    for (;;) {
         try {
             return await client.execEdgeClip(orgId, pinned);
         }
         catch (err) {
-            if (!isEdgeActivationPending(err))
+            const code = waitableEdgeRefusal(err);
+            if (!code)
                 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)];
+            const retryAfterSeconds = err.retryAfterSeconds;
+            const backoff = typeof retryAfterSeconds === 'number' && retryAfterSeconds > 0
+                ? retryAfterSeconds * 1000
+                : WAITABLE[code].fallbackMs(attempts[code]);
+            attempts[code] += 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.50.1",
+  "version": "1.52.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.50.1",
-    "@parall/sdk": "1.50.1"
+    "@parall/sdk": "1.52.0",
+    "@parall/agent-core": "1.52.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.50.1"
+    "@parall/agent-core": "1.52.0"
   },
   "scripts": {
     "build": "tsc",