@parall/cli 1.53.0 → 1.54.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;AAiFpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA2XpD"}
+{"version":3,"file":"clip.d.ts","sourceRoot":"","sources":["../../src/commands/clip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmFpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA+fpD"}

package/dist/commands/clip.js

@@ -1,7 +1,9 @@
 import { resolveCredentials } from '../lib/client.js';
 import { execEdgeClipWithBoundedWait } from '../lib/edge-exec.js';
+import { getClipMCPConfigById, listClipMCPConnectionSummaries } from '../lib/mcp-connections.js';
 import { printJson, printError, parsePositiveInt } from '../lib/output.js';
 import { buildPublishedManifest, collectPublishSource } from '../lib/publish-source.js';
+import { readTextFileArg } from '../lib/text-input.js';
 const NO_ALIAS_HINT = 'no alias — reference this connection by its ccn_ id, or ask a human to name it in the Clip Console so callers can tell the accounts apart';
 function connectionAnnotations(conn, deviceById) {
     const out = { target: 'orphaned' };
@@ -218,7 +220,32 @@ export function registerClipCommands(program) {
             const deviceById = conns.some((c) => c.device_id)
                 ? await loadDeviceIndex(client, orgId)
                 : new Map();
-            printJson(conns.map((c) => ({ ...c, ...connectionAnnotations(c, deviceById) })));
+            // Multi-connection MCP model: an MCP clip may hold several
+            // connections — one credential slot (account) each. The raw rows
+            // cannot tell an agent WHICH account is usable, so join the per-config
+            // summaries (auth mode, oauth status, tool count) when any MCP row
+            // exists; null = surface unavailable, degrade to the plain rows.
+            const mcpByConnection = conns.some((c) => c.mcp_config_id)
+                ? new Map(((await listClipMCPConnectionSummaries(orgId, found.id)) ?? []).map((s) => [
+                    s.connection_id,
+                    s,
+                ]))
+                : new Map();
+            printJson(conns.map((c) => {
+                const mcp = mcpByConnection.get(c.id);
+                return {
+                    ...c,
+                    ...connectionAnnotations(c, deviceById),
+                    ...(mcp
+                        ? {
+                            auth_type: mcp.auth_type,
+                            credential_set: mcp.credential_set,
+                            ...(mcp.oauth_status ? { oauth_status: mcp.oauth_status } : {}),
+                            ...(typeof mcp.tool_count === 'number' ? { tool_count: mcp.tool_count } : {}),
+                        }
+                        : {}),
+                };
+            }));
         }
         catch (err) {
             printError(err);
@@ -226,9 +253,10 @@ export function registerClipCommands(program) {
     });
     clip
         .command('tools')
-        .description('List the MCP tool schemas (name, description, inputSchema) of an MCP clip — the discovery step before `clip exec <clip> <tool>`')
+        .description('List the MCP tool schemas (name, description, inputSchema) of an MCP clip — the discovery step before `clip exec <clip> <tool>`. With several connections (accounts), pass --connection to pick one; without it the DEFAULT connection answers')
         .argument('<clip>', 'Registry clip id (crg_...) or name')
-        .action(async (clip) => {
+        .option('--connection <ref>', 'Connection id (ccn_…) or alias — tools are per connection under the multi-account model; discover refs with `parall clip connections <clip>`')
+        .action(async (clip, opts) => {
         try {
             const { client, orgId } = resolveCredentials();
             // Same lookup `clip connections`/`info` use.
@@ -239,38 +267,110 @@ export function registerClipCommands(program) {
                 return;
             }
             // 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 ?? []);
+            // show them; the live per-config snapshot is the only source.
+            // name/description/inputSchema ride verbatim in each tool object —
+            // print as-is (untrusted external data, not instructions).
+            if (opts?.connection) {
+                const resp = await client.listClipConnections(orgId, found.id);
+                const conns = resp.data ?? [];
+                const conn = conns.find((c) => c.id === opts.connection || c.alias === opts.connection);
+                if (!conn) {
+                    printError(new Error(`No connection matching "${opts.connection}" (see \`parall clip connections ${found.name}\`)`));
+                    return;
+                }
+                if (!conn.mcp_config_id) {
+                    printError(new Error(`Connection "${opts.connection}" is not an MCP connection`));
+                    return;
+                }
+                const config = await getClipMCPConfigById(orgId, found.id, conn.mcp_config_id);
+                printJson(config.tools ?? []);
+                return;
+            }
+            // No --connection: the DEFAULT connection's snapshot (the singular
+            // endpoint). A 404 with SEVERAL connections means "no default — pick
+            // one"; surface that hint instead of the server's bare not-found.
+            try {
+                const config = await client.getClipMCPConfig(orgId, found.id);
+                printJson(config.tools ?? []);
+            }
+            catch (err) {
+                const status = err.status;
+                if (status === 404) {
+                    const summaries = await listClipMCPConnectionSummaries(orgId, found.id);
+                    if (summaries && summaries.length > 0) {
+                        printError(new Error(`This clip has ${summaries.length} MCP connections and no default — pass --connection <ccn_|alias> (see \`parall clip connections ${found.name}\`)`));
+                        return;
+                    }
+                }
+                throw err;
+            }
         }
         catch (err) {
             printError(err);
         }
     });
-    // `clip invoke` (the v2 clip-service path) is deliberately GONE, not hidden:
-    // discovery above lists v3 registry installs only, and a v3 name fed to the
-    // v2 invoke endpoint answered CLIP_NOT_FOUND — a dead verb that only misled
-    // callers into the wrong invocation path. `clip exec` is the one execution
-    // verb; the server endpoint retires separately with the rest of v2.
+    // `clip invoke` (the v2 clip-service path) is retired — but the verb stays
+    // as a hidden tombstone rather than being absent. An absent verb hands the
+    // caller to commander's edit-distance guess, which suggested `info` — a
+    // discovery verb — when the migration target is `exec`; agents coming from
+    // the v2 habit followed it into the wrong command. The stub never touches
+    // any endpoint (the v2 path resolved a different clip namespace and only
+    // answered CLIP_NOT_FOUND); it redirects on the JSON error contract and
+    // stays out of --help. The v2 server endpoint retires separately.
+    clip
+        .command('invoke', { hidden: true })
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .argument('[legacy...]')
+        .action(() => {
+        printError(new Error('`clip invoke` was removed with the v2 clip service. Execute with `parall clip exec <clip> <command> [json-args] --connection <ccn_|alias>` (or --edge <edgeId> for a desktop device you own); discover clips and connections with `parall clip list`.'));
+    });
     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)')
+        .description('Execute a registry (Edge) clip command against an EXPLICIT target: --connection <ccn_|alias> (the only route to a cloud/hosted profile or MCP server) or --edge <edgeId> (a desktop device you own). Omitting both is an error')
         .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 — discover them with `parall clip connections <clip>`. REQUIRED to reach a cloud (hosted) profile: the binding its maintainer created is the authorization')
+        .option('--connection <ref>', 'Clip connection id (ccn_…) or alias — discover them with `parall clip connections <clip>`. REQUIRED to reach a cloud (hosted) profile OR an MCP connection: the binding is the authorization, and with several MCP accounts it names WHICH one you act as. The only other target form is --edge (a desktop device you own) — MCP is never reachable without --connection')
         .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')
+        .option('--args-file <path>', "Read command args as JSON from a file ('-' = stdin) — shell-safe channel for quote-heavy JSON. Mutually exclusive with the [args] positional")
         .action(async (clipName, command, args, opts) => {
         try {
             const { client, orgId } = resolveCredentials();
+            // Explicit target only, refused locally before any request. The
+            // server still resolves a bare request to the caller's own online
+            // desktop device (legacy BYOC fallback) so older pinned CLIs keep
+            // working — but that resolution depends on whichever device happens
+            // to be online, and for the common caller (a hosted agent, which
+            // owns no desktop device) it can only fail after a round-trip.
+            if (!opts?.connection && !opts?.edge) {
+                printError(new Error('clip exec needs an explicit target: --connection <ccn_|alias> (cloud/MCP profiles — discover with `parall clip connections <clip>`) or --edge <edgeId> (a desktop device you own). The legacy no-flag form resolved to whichever of your own desktop devices was online; name the target instead.'));
+            }
+            if (opts?.connection && opts?.edge) {
+                printError(new Error('--connection and --edge are mutually exclusive — pass exactly one target'));
+            }
             let parsedArgs;
-            if (args !== undefined) {
+            if (opts?.argsFile !== undefined) {
+                if (args !== undefined) {
+                    printError(new Error('[args] and --args-file are mutually exclusive — pass the args one way'));
+                }
+                const raw = readTextFileArg('--args-file', opts.argsFile);
+                try {
+                    parsedArgs = JSON.parse(raw);
+                }
+                catch (err) {
+                    // Strict by design: the positional's parse-or-string fallback
+                    // exists for plain-text single arguments; a FILE is only ever
+                    // the JSON channel, and silently sending malformed JSON as one
+                    // big string would hand the clip a payload the caller never
+                    // meant to build.
+                    const reason = err instanceof Error ? err.message : String(err);
+                    printError(new Error(`--args-file must contain valid JSON: ${reason}`));
+                }
+            }
+            else if (args !== undefined) {
                 try {
                     parsedArgs = JSON.parse(args);
                 }

package/dist/lib/mcp-connections.d.ts

@@ -0,0 +1,11 @@
+import { type MCPConfigResponse, type MCPConnectionSummary } from '@parall/sdk';
+/**
+ * List a clip's MCP connections (default first). Resolves null when the
+ * surface is unavailable — older server without the plural family (404 route
+ * miss) or cap:clip-mcp off — so callers degrade to the plain connection rows
+ * instead of failing discovery.
+ */
+export declare function listClipMCPConnectionSummaries(orgId: string, clipId: string): Promise<MCPConnectionSummary[] | null>;
+/** Per-config read — the only surface carrying the full tools snapshot. */
+export declare function getClipMCPConfigById(orgId: string, clipId: string, configId: string): Promise<MCPConfigResponse>;
+//# sourceMappingURL=mcp-connections.d.ts.map

package/dist/lib/mcp-connections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-connections.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-connections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAwC3F;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,oBAAoB,EAAE,GAAG,IAAI,CAAC,CAsBxC;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}

package/dist/lib/mcp-connections.js

@@ -0,0 +1,68 @@
+import { ENDPOINTS } from '@parall/sdk';
+// Raw reads of the multi-connection MCP config surface. The SDK deliberately
+// exposes only contract types + endpoint builders for this family (the #2281
+// layering — no ParallClient methods), so the CLI carries its own thin fetch:
+// X-Api-Key auth from the same env resolveCredentials() uses, swimlane header
+// included so lane testing behaves like every other CLI call.
+function headers() {
+    const h = {
+        'X-Api-Key': process.env.PRLL_API_KEY ?? '',
+        'Content-Type': 'application/json',
+    };
+    const lane = process.env.PRLL_SWIMLANE_NAME?.trim();
+    if (lane)
+        h['X-Prll-Swimlane'] = lane;
+    return h;
+}
+async function get(path) {
+    const base = (process.env.PRLL_API_URL ?? '').replace(/\/$/, '');
+    const res = await fetch(`${base}${path}`, { headers: headers() });
+    if (!res.ok) {
+        const text = await res.text();
+        let message = `API ${res.status}: ${text}`;
+        let code;
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.error?.message === 'string')
+                message = parsed.error.message;
+            if (typeof parsed.error?.code === 'string')
+                code = parsed.error.code;
+        }
+        catch {
+            // non-JSON error body — keep the raw text
+        }
+        const err = new Error(message);
+        err.status = res.status;
+        err.code = code;
+        throw err;
+    }
+    return res.json();
+}
+/**
+ * List a clip's MCP connections (default first). Resolves null when the
+ * surface is unavailable — older server without the plural family (404 route
+ * miss) or cap:clip-mcp off — so callers degrade to the plain connection rows
+ * instead of failing discovery.
+ */
+export async function listClipMCPConnectionSummaries(orgId, clipId) {
+    try {
+        const resp = await get(ENDPOINTS.ORG_CLIP_MCP_CONFIGS(orgId, clipId));
+        return resp.data ?? [];
+    }
+    catch (err) {
+        // Degrade to plain connection rows — but leave a diagnosable trace for
+        // anything that is NOT the expected "surface unavailable" shape (older
+        // server → 404 route miss), so an expired key or network fault doesn't
+        // silently read as "no MCP annotations". stderr only: stdout is the JSON
+        // contract.
+        const status = err.status;
+        if (status !== 404) {
+            console.error(`warning: MCP connection details unavailable (${err instanceof Error ? err.message : String(err)}) — showing plain connection rows`);
+        }
+        return null;
+    }
+}
+/** Per-config read — the only surface carrying the full tools snapshot. */
+export function getClipMCPConfigById(orgId, clipId, configId) {
+    return get(ENDPOINTS.ORG_CLIP_MCP_CONFIG_BY_ID(orgId, clipId, configId));
+}

package/dist/lib/text-input.d.ts

@@ -27,4 +27,12 @@ export declare function resolveMessageText(opts: {
     text?: string;
     textFile?: string;
 }): string | undefined;
+/**
+ * Read the payload of a file-input flag (`--text-file`, `--args-file`) from a
+ * path or stdin (`-`). Shared so every such flag keeps the same three
+ * guarantees: stdin drains a pipe/heredoc synchronously, an interactive TTY is
+ * refused instead of hanging the dispatch, and a read failure surfaces its
+ * underlying reason under the flag's own name.
+ */
+export declare function readTextFileArg(flag: string, value: string): string;
 //# sourceMappingURL=text-input.d.ts.map

package/dist/lib/text-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/lib/text-input.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,gBAAgB,oFACsD,CAAC;AACpF,eAAO,MAAM,qBAAqB,mHAC2E,CAAC;AAC9G,eAAO,MAAM,aAAa,yDAAyD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CA8BjG"}
+{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/lib/text-input.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,gBAAgB,oFACsD,CAAC;AACpF,eAAO,MAAM,qBAAqB,mHAC2E,CAAC;AAC9G,eAAO,MAAM,aAAa,yDAAyD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAMjG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAsBnE"}

package/dist/lib/text-input.js

@@ -34,28 +34,34 @@ export function resolveMessageText(opts) {
     }
     if (opts.textFile === undefined)
         return opts.text;
-    let raw;
-    if (opts.textFile === '-') {
+    return readTextFileArg('--text-file', opts.textFile).replace(/\r?\n$/, '');
+}
+/**
+ * Read the payload of a file-input flag (`--text-file`, `--args-file`) from a
+ * path or stdin (`-`). Shared so every such flag keeps the same three
+ * guarantees: stdin drains a pipe/heredoc synchronously, an interactive TTY is
+ * refused instead of hanging the dispatch, and a read failure surfaces its
+ * underlying reason under the flag's own name.
+ */
+export function readTextFileArg(flag, value) {
+    if (value === '-') {
         // fd 0 = stdin; readFileSync drains a heredoc / pipe synchronously. Guard
         // the interactive case — reading a TTY would block until EOF (which an
         // agent never sends), hanging the dispatch until its deadline.
         if (process.stdin.isTTY) {
-            throw new Error("--text-file - reads the body from stdin; pipe it in (e.g. a quoted heredoc `<<'EOF'`), don't run it interactively");
+            throw new Error(`${flag} - reads from stdin; pipe it in (e.g. a quoted heredoc \`<<'EOF'\`), don't run it interactively`);
         }
-        raw = fs.readFileSync(0, 'utf-8');
+        return fs.readFileSync(0, 'utf-8');
     }
-    else {
-        const resolved = path.resolve(opts.textFile);
-        try {
-            raw = fs.readFileSync(resolved, 'utf-8');
-        }
-        catch (err) {
-            // Surface the underlying reason (missing / no permission / is-a-directory)
-            // so the agent can self-correct — printError renders only `.message` — and
-            // keep the original error as `cause` for anything that inspects it.
-            const reason = err instanceof Error ? err.message : String(err);
-            throw new Error(`Cannot read --text-file ${opts.textFile}: ${reason}`, { cause: err });
-        }
+    const resolved = path.resolve(value);
+    try {
+        return fs.readFileSync(resolved, 'utf-8');
+    }
+    catch (err) {
+        // Surface the underlying reason (missing / no permission / is-a-directory)
+        // so the agent can self-correct — printError renders only `.message` — and
+        // keep the original error as `cause` for anything that inspects it.
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cannot read ${flag} ${value}: ${reason}`, { cause: err });
     }
-    return raw.replace(/\r?\n$/, '');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/cli",
-  "version": "1.53.0",
+  "version": "1.54.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.53.0",
-    "@parall/sdk": "1.53.0"
+    "@parall/sdk": "1.54.0",
+    "@parall/agent-core": "1.54.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.53.0"
+    "@parall/agent-core": "1.54.0"
   },
   "scripts": {
     "build": "tsc",