@parall/cli 1.45.0 → 1.47.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;AA8BpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAuJpD"}
+{"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"}

package/dist/commands/clip.js

@@ -1,4 +1,5 @@
 import { resolveCredentials } from '../lib/client.js';
+import { invokeClipAwaitingActivation } from '../lib/clip-invoke.js';
 import { printJson, printError } from '../lib/output.js';
 /**
  * Derive a CLI-friendly alias from a registry source string.
@@ -143,7 +144,10 @@ export function registerClipCommands(program) {
                 input: parsedInput,
                 timeout_ms: timeoutMs,
             };
-            const result = await client.invokeClip(orgId, req);
+            // Hosted-browser clips may hit a cold profile: absorb the (pre-dispatch,
+            // side-effect-free) BROWSER_PROFILE_ACTIVATING window here instead of
+            // making every agent hand-roll a retry loop. See lib/clip-invoke.ts.
+            const result = await invokeClipAwaitingActivation(client, orgId, req);
             if (result.error) {
                 printError(new Error(result.error));
             }

package/dist/commands/slack.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+/**
+ * `parall slack …` — the per-vendor platform verb for a channel whose vendor
+ * ships no agent-grade CLI (tier B in the multi-channel architecture). The
+ * agent sends as its bound bot identity; Slack credentials never reach the
+ * runtime — api-server performs the vendor call in-process.
+ * Design: docs/engineering-design/multi-channel-architecture-design.md §8.2.
+ */
+export declare function registerSlackCommands(program: Command): void;
+//# sourceMappingURL=slack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"slack.d.ts","sourceRoot":"","sources":["../../src/commands/slack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,QAgIrD"}

package/dist/commands/slack.js

@@ -0,0 +1,131 @@
+import { resolveCredentials } from '../lib/client.js';
+import { printError, printJson } from '../lib/output.js';
+/**
+ * `parall slack …` — the per-vendor platform verb for a channel whose vendor
+ * ships no agent-grade CLI (tier B in the multi-channel architecture). The
+ * agent sends as its bound bot identity; Slack credentials never reach the
+ * runtime — api-server performs the vendor call in-process.
+ * Design: docs/engineering-design/multi-channel-architecture-design.md §8.2.
+ */
+export function registerSlackCommands(program) {
+    const slack = program
+        .command('slack')
+        .description('Slack channel platform verbs (agent-only; sends as the bound bot)');
+    slack
+        .command('send')
+        .description('Send a message to a Slack conversation this connection has seen inbound')
+        .requiredOption('--channel <channelId>', 'Vendor-native conversation id from the inbound event (C…/G…/D…)')
+        .requiredOption('--text <text>', 'Message text (plain text)')
+        .option('--reply-to <messageId>', 'Inbound message id you are answering ({channel}:{ts}, thread children {channel}:{root}#{ts}); REQUIRED in channels (reply lands in its thread). In DMs pass it too: a thread-child id lands the reply in that thread, a bare id keeps the main flow — the session never forks either way')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            const sent = await client.sendChannelMessage(orgId, {
+                channel_type: 'slack',
+                conversation_id: opts.channel,
+                text: opts.text,
+                ...(opts.replyTo ? { reply_to: opts.replyTo } : {}),
+            });
+            printJson(sent);
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+    // Read verbs: workspace visibility as the bot sees it. Authorization is
+    // the bot's own Slack permissions (invite it to a channel to read that
+    // channel's history) — reads are not limited to seen conversations.
+    // Fail fast on a malformed --limit instead of silently falling back to
+    // the server default page size.
+    const page = (opts) => {
+        let limit;
+        if (opts.limit !== undefined) {
+            limit = Number(opts.limit);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+                throw new Error('--limit must be an integer between 1 and 200');
+            }
+        }
+        return {
+            ...(opts.cursor ? { cursor: opts.cursor } : {}),
+            ...(limit !== undefined ? { limit } : {}),
+        };
+    };
+    slack
+        .command('channels')
+        .description('List workspace channels as the bot sees them (is_member marks joined ones)')
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--limit <n>', 'Page size (max 200)')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            printJson(await client.listSlackChannels(orgId, page(opts)));
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+    slack
+        .command('users')
+        .description('List workspace members')
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--limit <n>', 'Page size (max 200)')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            printJson(await client.listSlackUsers(orgId, page(opts)));
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+    slack
+        .command('history')
+        .description('Read a conversation message history (bot must be able to see it)')
+        .requiredOption('--conversation <id>', 'Vendor-native conversation id (C…/G…/D…)')
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--limit <n>', 'Page size (max 200)')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            printJson(await client.slackHistory(orgId, opts.conversation, page(opts)));
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+    slack
+        .command('status')
+        .description('Set/clear the Agents-pane typing indicator on an assistant thread (cosmetic)')
+        .requiredOption('--conversation <id>', 'DM conversation id (D…)')
+        .requiredOption('--thread <rootTs>', "The assistant thread's root ts")
+        .option('--text <status>', 'Status text (omit to clear)', '')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            await client.setSlackStatus(orgId, {
+                conversation: opts.conversation,
+                thread_ts: opts.thread,
+                status: opts.text ?? '',
+            });
+            printJson({ ok: true });
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+    slack
+        .command('members')
+        .description('List a conversation member ids (resolve names via `parall slack users`)')
+        .requiredOption('--conversation <id>', 'Vendor-native conversation id (C…/G…)')
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--limit <n>', 'Page size (max 200)')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            printJson(await client.slackMembers(orgId, opts.conversation, page(opts)));
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+}

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerSearchCommands } from './commands/search.js';
 import { registerFileCommands } from './commands/files.js';
 import { registerMachineCommands } from './commands/machines.js';
 import { registerClipCommands } from './commands/clip.js';
+import { registerSlackCommands } from './commands/slack.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 const program = new Command();
@@ -46,4 +47,5 @@ registerSearchCommands(program);
 registerFileCommands(program);
 registerMachineCommands(program);
 registerClipCommands(program);
+registerSlackCommands(program);
 program.parse();

package/dist/lib/clip-invoke.d.ts

@@ -0,0 +1,45 @@
+import type { InvokeClipRequest, InvokeClipResponse, ParallClient } from '@parall/sdk';
+/**
+ * Hosted browser activation wait — CLI-side bounded retry for `clip invoke`.
+ *
+ * A clip bound to a `placement=hosted` BrowserProfile whose pod is cold returns
+ * 503 BROWSER_PROFILE_ACTIVATING from the invoke pre-flight: the controller is
+ * spawning + registering the pod, and the clip command has NOT been dispatched
+ * yet, so retrying the same request cannot double-execute anything. This module
+ * absorbs that one precise error so a single `parall clip invoke` rides through
+ * cold start instead of forcing the caller (agent or human) into a blind
+ * retry loop.
+ *
+ * Deliberately NOT in the SDK: `invokeClip()` keeps its throw-on-503 semantics
+ * for every other consumer; only the CLI invoke behavior waits.
+ */
+/** 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 ACTIVATION_WAIT_BUDGET_MS = 60000;
+/** Backoff schedule between activation retries; the last entry repeats. */
+export declare const ACTIVATION_BACKOFF_MS: number[];
+/** Injectable time hooks so tests never really sleep. */
+export type ActivationWaitHooks = {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+/**
+ * The ONLY retryable error: a typed ApiError carrying exactly 503 +
+ * BROWSER_PROFILE_ACTIVATING. Everything else — consent, permission, provider
+ * offline/not-running, command errors, timeouts, other 5xx — means retrying is
+ * either pointless or unsafe (the command may have been dispatched), so it
+ * propagates unchanged on the first occurrence.
+ */
+export declare function isActivationPending(err: unknown): boolean;
+/**
+ * Invoke a clip, transparently absorbing the hosted-browser activation window.
+ *
+ * Retries the identical request while the server reports
+ * BROWSER_PROFILE_ACTIVATING, backing off 500ms → 1s → 2s (capped) until the
+ * 60s activation budget is spent. Once 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 invokeClipAwaitingActivation(client: Pick<ParallClient, 'invokeClip'>, orgId: string, req: InvokeClipRequest, hooks?: ActivationWaitHooks): Promise<InvokeClipResponse>;
+//# sourceMappingURL=clip-invoke.d.ts.map

package/dist/lib/clip-invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clip-invoke.d.ts","sourceRoot":"","sources":["../../src/lib/clip-invoke.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGvF;;;;;;;;;;;;;GAaG;AAEH;;oDAEoD;AACpD,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,UAAsB,CAAC;AAEzD,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG;IAChC,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,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,EACxC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,iBAAiB,EACtB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAiB7B"}

package/dist/lib/clip-invoke.js

@@ -0,0 +1,61 @@
+import { ApiError } from '@parall/sdk';
+/**
+ * Hosted browser activation wait — CLI-side bounded retry for `clip invoke`.
+ *
+ * A clip bound to a `placement=hosted` BrowserProfile whose pod is cold returns
+ * 503 BROWSER_PROFILE_ACTIVATING from the invoke pre-flight: the controller is
+ * spawning + registering the pod, and the clip command has NOT been dispatched
+ * yet, so retrying the same request cannot double-execute anything. This module
+ * absorbs that one precise error so a single `parall clip invoke` rides through
+ * cold start instead of forcing the caller (agent or human) into a blind
+ * retry loop.
+ *
+ * Deliberately NOT in the SDK: `invokeClip()` keeps its throw-on-503 semantics
+ * for every other consumer; only the CLI invoke behavior waits.
+ */
+/** 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 ACTIVATION_WAIT_BUDGET_MS = 60_000;
+/** Backoff schedule between activation retries; the last entry repeats. */
+export const 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 +
+ * BROWSER_PROFILE_ACTIVATING. Everything else — consent, permission, provider
+ * offline/not-running, command errors, timeouts, other 5xx — means retrying is
+ * either pointless or unsafe (the command may have been dispatched), so it
+ * propagates unchanged on the first occurrence.
+ */
+export function isActivationPending(err) {
+    return err instanceof ApiError && err.status === 503 && err.code === 'BROWSER_PROFILE_ACTIVATING';
+}
+/**
+ * Invoke a clip, transparently absorbing the hosted-browser activation window.
+ *
+ * Retries the identical request while the server reports
+ * BROWSER_PROFILE_ACTIVATING, backing off 500ms → 1s → 2s (capped) until the
+ * 60s activation budget is spent. Once 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 invokeClipAwaitingActivation(client, orgId, req, hooks) {
+    const sleep = hooks?.sleep ?? realSleep;
+    const now = hooks?.now ?? Date.now;
+    const deadline = now() + ACTIVATION_WAIT_BUDGET_MS;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await client.invokeClip(orgId, req);
+        }
+        catch (err) {
+            if (!isActivationPending(err))
+                throw err;
+            const remaining = deadline - now();
+            if (remaining <= 0)
+                throw err;
+            const backoff = ACTIVATION_BACKOFF_MS[Math.min(attempt, 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.45.0",
+  "version": "1.47.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.45.0",
-    "@parall/sdk": "1.45.0"
+    "@parall/agent-core": "1.47.0",
+    "@parall/sdk": "1.47.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.45.0"
+    "@parall/agent-core": "1.47.0"
   },
   "scripts": {
     "build": "tsc",