@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/cloud/rush.js

@@ -10,7 +10,7 @@ import * as os from 'os';
 import * as crypto from 'crypto';
 import * as yaml from 'yaml';
 import { getCloudDir } from '../state.js';
-import { resolveDispatchRepos } from './types.js';
+import { resolveDispatchRepos, MAX_IMAGES_PER_DISPATCH } from './types.js';
 import { parseSSE } from './stream.js';
 import { listInstalledVersions, getVersionHomePath } from '../versions.js';
 import { getAccountInfo } from '../agents.js';
@@ -286,6 +286,12 @@ export function buildDispatchBody(input) {
     if (input.accountTokens && input.accountTokens.length > 0) {
         body.account_tokens = input.accountTokens;
     }
+    if (input.skills && input.skills.length > 0) {
+        body.skills = input.skills;
+    }
+    if (input.images && input.images.length > 0) {
+        body.images = input.images.slice(0, MAX_IMAGES_PER_DISPATCH);
+    }
     return body;
 }
 /** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
@@ -332,8 +338,8 @@ export class RushCloudProvider {
             cancel: true,
             message: true,
             multiRepo: true,
-            skills: false,
-            images: false,
+            skills: true,
+            images: true,
         };
     }
     async dispatch(options) {
@@ -387,6 +393,8 @@ export class RushCloudProvider {
             resolvedRepos,
             accountManifest,
             strategy,
+            skills: options.skills,
+            images: options.images,
         });
         let res = await api('POST', '/api/v1/cloud-runs', token, body);
         // Server detects drift (new account or rotated token) by comparing the
@@ -429,6 +437,8 @@ export class RushCloudProvider {
                     resolvedRepos,
                     accountManifest,
                     accountTokens,
+                    skills: options.skills,
+                    images: options.images,
                 });
                 res = await api('POST', '/api/v1/cloud-runs', token, retryBody);
                 // Persist consent on first successful upload so we don't re-prompt

package/dist/lib/cloud/types.d.ts

@@ -5,6 +5,7 @@
  * Factory) implement, plus the shared task and event types that flow through
  * the dispatch pipeline.
  */
+import type { JobTrigger } from '../routines.js';
 /**
  * Identifier for a supported cloud dispatch backend.
  *
@@ -119,6 +120,14 @@ export declare const MAX_IMAGES_PER_DISPATCH = 5;
 export interface DispatchOptions {
     prompt: string;
     agent?: string;
+    /**
+     * Event/webhook trigger to register with this dispatch. Set by
+     * `agents cloud run --on <event>`: instead of dispatching immediately, the
+     * dispatch is persisted as a trigger-bound routine so the local webhook
+     * receiver can fire it when the event arrives. Remote firing of the trigger
+     * is a follow-up; today the flag parses, validates, and persists.
+     */
+    trigger?: JobTrigger;
     /**
      * Legacy single-repo target. Still honored: if `repos` is empty, this
      * becomes the only repo. Providers that support multi-repo treat

package/dist/lib/computer/dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { ComputerClient } from '../computer-rpc.js';
+import { type AppInfo } from '../../commands/computer-actions.js';
+import type { VerbDispatcher } from './loop.js';
+declare function rpcMethodFor(verb: string): string;
+declare function toRpcParams(verb: string, input: Record<string, unknown>, pid?: number): Record<string, unknown>;
+export declare function makeVerbDispatcher(client: ComputerClient): VerbDispatcher;
+export { rpcMethodFor, toRpcParams };
+export type { AppInfo };

package/dist/lib/computer/dispatch.js

@@ -0,0 +1,125 @@
+// Verb dispatcher for the `computer run` loop.
+//
+// Maps a loop VerbCall (CLI-verb name + friendly input) onto the EXISTING
+// computer-helper RPC methods over the daemon socket. It reimplements no verb —
+// it names the same RPC methods the explicit `agents computer <verb>` commands
+// call, so the external-agent verb surface is untouched. The daemon stays the
+// single authority on permissions and targeting.
+import { resolveTargetPidDecision } from '../../commands/computer-actions.js';
+// CLI verb -> daemon RPC method. Only the rename cases need listing; the rest
+// pass through by name.
+const RPC_METHOD = {
+    apps: 'list_apps',
+    'get-text': 'get_text',
+    'type-text': 'type_text',
+    'ax-action': 'ax_action',
+    'right-click': 'right_click',
+    launch: 'launch_app',
+    focus: 'set_focus',
+    raise: 'focus_window',
+};
+// Verbs that do not need a resolved target pid.
+const NO_TARGET = new Set(['apps', 'launch']);
+function rpcMethodFor(verb) {
+    return RPC_METHOD[verb] ?? verb;
+}
+// Translate the model's friendly input keys into the daemon's param names.
+// pid is injected by the caller after target resolution.
+function toRpcParams(verb, input, pid) {
+    const p = {};
+    if (pid != null)
+        p.pid = pid;
+    const copyIf = (from, to) => {
+        if (input[from] != null)
+            p[to] = input[from];
+    };
+    switch (verb) {
+        case 'describe':
+            copyIf('depth', 'max_depth');
+            break;
+        case 'screenshot':
+            copyIf('quality', 'quality');
+            break;
+        case 'get-text':
+            copyIf('id', 'element_id');
+            copyIf('maxChars', 'max_chars');
+            break;
+        case 'click':
+        case 'right-click':
+        case 'scroll':
+            copyIf('id', 'element_id');
+            copyIf('x', 'x');
+            copyIf('y', 'y');
+            copyIf('count', 'count');
+            copyIf('dx', 'dx');
+            copyIf('dy', 'dy');
+            break;
+        case 'type':
+            copyIf('id', 'element_id');
+            copyIf('x', 'x');
+            copyIf('y', 'y');
+            copyIf('text', 'text');
+            copyIf('commit', 'commit');
+            break;
+        case 'type-text':
+            copyIf('text', 'text');
+            copyIf('commit', 'commit');
+            break;
+        case 'key':
+            copyIf('keys', 'keys');
+            break;
+        case 'ax-action':
+            copyIf('id', 'element_id');
+            copyIf('action', 'action');
+            break;
+        case 'focus':
+            copyIf('id', 'element_id');
+            break;
+        case 'launch':
+            copyIf('bundle', 'bundle_id');
+            copyIf('path', 'path');
+            copyIf('name', 'name');
+            break;
+        case 'wait': {
+            if (input.duration != null)
+                p.duration_ms = input.duration;
+            copyIf('id', 'element_id');
+            copyIf('until', 'until');
+            const locator = {};
+            for (const k of ['role', 'label', 'identifier']) {
+                if (input[k] != null)
+                    locator[k] = input[k];
+            }
+            if (Object.keys(locator).length > 0)
+                p.locator = locator;
+            break;
+        }
+        default:
+            break;
+    }
+    return p;
+}
+// Build a dispatcher bound to a live client. Every call is a single daemon
+// round-trip; errors are returned (never thrown) so the loop can feed them
+// back to the model as a tool_result.
+export function makeVerbDispatcher(client) {
+    return async (call) => {
+        const verb = call.name;
+        const input = call.input ?? {};
+        let pid;
+        if (!NO_TARGET.has(verb) && !(verb === 'wait' && input.duration != null)) {
+            const resolved = await resolveTargetPidDecision(client, { pid: input.pid, bundle: input.bundle });
+            if (!resolved.ok)
+                return { ok: false, error: resolved.error };
+            pid = resolved.pid;
+        }
+        const method = rpcMethodFor(verb);
+        const params = toRpcParams(verb, input, pid);
+        const res = await client.call(method, params);
+        if (res.error)
+            return { ok: false, error: `${res.error.code}: ${res.error.message}` };
+        return { ok: true, result: res.result ?? {} };
+    };
+}
+// Exposed for tests/diagnostics.
+export { rpcMethodFor, toRpcParams };

package/dist/lib/computer/loop.d.ts

@@ -0,0 +1,62 @@
+export interface VerbCall {
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface VerbResult {
+    ok: boolean;
+    result?: Record<string, unknown>;
+    error?: string;
+}
+export interface LoopStep {
+    call: VerbCall;
+    result: VerbResult;
+    visionFallback?: boolean;
+}
+export interface LoopState {
+    task: string;
+    steps: LoopStep[];
+    visionMode: boolean;
+}
+export interface ModelDecision {
+    toolCalls: VerbCall[];
+    done?: {
+        text: string;
+    };
+}
+export type ModelResponder = (state: LoopState) => ModelDecision | Promise<ModelDecision>;
+export type VerbDispatcher = (call: VerbCall) => VerbResult | Promise<VerbResult>;
+export interface LoopConfig {
+    task: string;
+    responder: ModelResponder;
+    dispatch: VerbDispatcher;
+    maxSteps: number;
+    onEvent?: (event: LoopEvent) => void;
+}
+export type LoopEvent = {
+    kind: 'turn';
+    index: number;
+} | {
+    kind: 'dispatch';
+    call: VerbCall;
+    result: VerbResult;
+    visionFallback?: boolean;
+} | {
+    kind: 'vision_switch';
+    describe: VerbResult;
+} | {
+    kind: 'done';
+    text: string;
+} | {
+    kind: 'max_steps';
+};
+export interface LoopResult {
+    status: 'done' | 'max_steps';
+    finalText?: string;
+    steps: LoopStep[];
+    dispatched: string[];
+    visionMode: boolean;
+    turns: number;
+}
+export declare const AX_OPAQUE_ELEMENT_THRESHOLD = 3;
+export declare function isAxOpaque(result: VerbResult): boolean;
+export declare function runComputerLoop(config: LoopConfig): Promise<LoopResult>;

package/dist/lib/computer/loop.js

@@ -0,0 +1,98 @@
+// The embedded observe -> act -> verify loop behind `agents computer run`.
+//
+// This module owns ONLY the decision logic: given a reasoning model (a
+// boundary, injected as `responder`) and a verb dispatcher (the existing
+// computer-helper RPC surface, injected as `dispatch`), it drives the model's
+// tool calls against the daemon, step by step, until the model declares the
+// task done or `maxSteps` is hit.
+//
+// The model and the daemon are boundaries — neither is code under test. The
+// loop itself (verb ordering, max-steps, the AX -> vision fallback) is the
+// unit under test. See loop.test.ts, which injects a scripted fake responder
+// and a fake dispatcher.
+// Below this many AX elements the tree is treated as opaque — a WebView, a
+// Qt/Electron surface that never populated its AX tree, or a canvas app. The
+// model then works from pixels + coordinate clicks instead of element ids.
+export const AX_OPAQUE_ELEMENT_THRESHOLD = 3;
+// Describe-time heuristic. An explicit `ax_opaque: true` from the daemon wins.
+// Otherwise: a failed describe is NOT opaque (it's an error, surface it), and a
+// successful one is opaque when its element_count is at/under the threshold or
+// its tree has no children. Pure so the rule is unit-testable in isolation.
+export function isAxOpaque(result) {
+    const r = result.result ?? {};
+    if (r.ax_opaque === true)
+        return true;
+    if (!result.ok)
+        return false;
+    const count = typeof r.element_count === 'number' ? r.element_count : undefined;
+    if (count !== undefined)
+        return count <= AX_OPAQUE_ELEMENT_THRESHOLD;
+    const tree = r.tree;
+    const children = tree && Array.isArray(tree.children) ? tree.children : [];
+    return children.length === 0;
+}
+// Drive the loop to completion. Returns the transcript, the ordered verb names
+// dispatched, and whether the vision fallback ever fired.
+export async function runComputerLoop(config) {
+    const state = { task: config.task, steps: [], visionMode: false };
+    const dispatched = [];
+    const emit = config.onEvent ?? (() => { });
+    let turns = 0;
+    while (turns < config.maxSteps) {
+        emit({ kind: 'turn', index: turns });
+        turns++;
+        const decision = await config.responder(state);
+        if (decision.done) {
+            emit({ kind: 'done', text: decision.done.text });
+            return {
+                status: 'done',
+                finalText: decision.done.text,
+                steps: state.steps,
+                dispatched,
+                visionMode: state.visionMode,
+                turns,
+            };
+        }
+        for (const call of decision.toolCalls) {
+            const result = await config.dispatch(call);
+            dispatched.push(call.name);
+            // AX -> vision fallback. When a describe comes back opaque, the element
+            // ids the model would click are useless, so the loop flips visionMode and
+            // immediately hands the model pixels: it auto-dispatches a screenshot of
+            // the same target. The explicit verbs stay untouched for external callers
+            // — this switch lives entirely in the loop.
+            if (call.name === 'describe' && isAxOpaque(result)) {
+                state.visionMode = true;
+                state.steps.push({ call, result, visionFallback: true });
+                emit({ kind: 'dispatch', call, result, visionFallback: true });
+                emit({ kind: 'vision_switch', describe: result });
+                const shotCall = { name: 'screenshot', input: pickTargetInput(call.input) };
+                const shot = await config.dispatch(shotCall);
+                dispatched.push(shotCall.name);
+                state.steps.push({ call: shotCall, result: shot });
+                emit({ kind: 'dispatch', call: shotCall, result: shot });
+                continue;
+            }
+            state.steps.push({ call, result });
+            emit({ kind: 'dispatch', call, result });
+        }
+    }
+    emit({ kind: 'max_steps' });
+    return {
+        status: 'max_steps',
+        steps: state.steps,
+        dispatched,
+        visionMode: state.visionMode,
+        turns,
+    };
+}
+// Carry the target selector (pid/bundle) from the describe call onto the
+// auto-injected screenshot so the vision fallback captures the same surface.
+function pickTargetInput(input) {
+    const out = {};
+    if (input.pid != null)
+        out.pid = input.pid;
+    if (input.bundle != null)
+        out.bundle = input.bundle;
+    return out;
+}

package/dist/lib/computer/model.d.ts

@@ -0,0 +1,44 @@
+import type { LoopState, ModelDecision, ModelResponder } from './loop.js';
+interface ToolSpec {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare const COMPUTER_TOOLS: ToolSpec[];
+export interface ClaudeResponderConfig {
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    maxTokens?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare const DEFAULT_CLAUDE_BASE_URL = "https://api.anthropic.com";
+export declare const DEFAULT_CLAUDE_MODEL = "claude-sonnet-4-6";
+export declare const ANTHROPIC_VERSION = "2023-06-01";
+export declare function resolveApiKey(config: ClaudeResponderConfig, env?: NodeJS.ProcessEnv): string;
+export declare function buildSystemPrompt(state: LoopState): string;
+type AnthropicBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+};
+interface AnthropicMessage {
+    role: 'user' | 'assistant';
+    content: AnthropicBlock[];
+}
+export declare function buildMessages(state: LoopState): AnthropicMessage[];
+export declare function parseDecision(body: unknown): ModelDecision;
+export declare function makeClaudeResponder(config?: ClaudeResponderConfig): ModelResponder;
+export {};

package/dist/lib/computer/model.js

@@ -0,0 +1,157 @@
+// Default reasoning model for the `computer run` loop.
+//
+// This is a BOUNDARY, not loop logic. It turns the loop's LoopState into an
+// Anthropic Messages API request (tool use), sends it to the Claude API by
+// default OR to a configurable base URL (Ollama / vLLM / LiteLLM serving the
+// Anthropic wire shape) for local/offline parity, and parses the reply back
+// into a ModelDecision the loop can act on.
+//
+// The loop (loop.ts) never imports this — it takes a ModelResponder callback,
+// so the unit tests inject a scripted fake instead of ever hitting a network.
+const TARGET_PROPS = {
+    bundle: { type: 'string', description: 'Bundle id of the target app (default: frontmost allow-listed app)' },
+    pid: { type: 'number', description: 'Target pid (overrides bundle)' },
+};
+export const COMPUTER_TOOLS = [
+    { name: 'apps', description: 'List allow-listed apps currently running.', input_schema: { type: 'object', properties: {} } },
+    {
+        name: 'describe',
+        description: 'Dump the accessibility tree of the target app. Element ids feed click/type via id. If the tree is opaque the loop auto-captures a screenshot for you.',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, depth: { type: 'number' } } },
+    },
+    {
+        name: 'screenshot',
+        description: 'Capture the target app window as an image (the vision path — use coordinate clicks off it).',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS } },
+    },
+    {
+        name: 'get-text',
+        description: 'Extract visible text from the target app (or a subtree via id).',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, id: { type: 'string' } } },
+    },
+    {
+        name: 'click',
+        description: 'Click an element (id from describe) or a screen coordinate (x,y). Use x,y after a vision screenshot.',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, id: { type: 'string' }, x: { type: 'number' }, y: { type: 'number' } } },
+    },
+    {
+        name: 'type',
+        description: 'Set a field value (id) or paste at a coordinate. Set commit=true to submit.',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, id: { type: 'string' }, x: { type: 'number' }, y: { type: 'number' }, text: { type: 'string' }, commit: { type: 'boolean' } }, required: ['text'] },
+    },
+    {
+        name: 'type-text',
+        description: 'Type a unicode string into the focused field. Focus it first with click or focus.',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, text: { type: 'string' }, commit: { type: 'boolean' } }, required: ['text'] },
+    },
+    {
+        name: 'key',
+        description: 'Send a key chord, e.g. "cmd+s", "enter", "esc".',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, keys: { type: 'string' } }, required: ['keys'] },
+    },
+    {
+        name: 'launch',
+        description: 'Launch an app by bundle id, path, or name.',
+        input_schema: { type: 'object', properties: { bundle: { type: 'string' }, path: { type: 'string' }, name: { type: 'string' } } },
+    },
+    {
+        name: 'wait',
+        description: 'Wait for a duration (ms) or for an element to appear.',
+        input_schema: { type: 'object', properties: { ...TARGET_PROPS, duration: { type: 'number' }, id: { type: 'string' }, role: { type: 'string' }, label: { type: 'string' } } },
+    },
+];
+export const DEFAULT_CLAUDE_BASE_URL = 'https://api.anthropic.com';
+export const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6';
+export const ANTHROPIC_VERSION = '2023-06-01';
+// Resolve the API key: explicit config, then the standard Anthropic env var,
+// then a computer-run-specific override. A local Anthropic-shaped endpoint
+// (Ollama/vLLM/LiteLLM) usually ignores the key, so an empty key is allowed
+// when a non-default base URL is set.
+export function resolveApiKey(config, env = process.env) {
+    return config.apiKey || env.AGENTS_COMPUTER_API_KEY || env.ANTHROPIC_API_KEY || '';
+}
+// Build the system prompt. In vision mode we steer the model onto coordinate
+// clicks off screenshots, because element ids from an opaque tree are useless.
+export function buildSystemPrompt(state) {
+    const lines = [
+        'You are driving a macOS desktop through accessibility + vision tools to accomplish a task.',
+        'Loop: observe (describe / screenshot / get-text), act (click / type / key), then verify the result before the next step.',
+        'Prefer element ids from describe. When you are confident the task is complete, stop calling tools and reply with a short completion summary.',
+        `Task: ${state.task}`,
+    ];
+    if (state.visionMode) {
+        lines.push('NOTE: the accessibility tree for the current surface is opaque (WebView / canvas). Work from the screenshot and click by x,y coordinates instead of element ids.');
+    }
+    return lines.join('\n');
+}
+// Reconstruct the Anthropic message array from the loop transcript. We rebuild
+// from scratch each turn (the loop holds canonical state), synthesizing stable
+// tool_use ids per step so each tool_result pairs with its call.
+export function buildMessages(state) {
+    const messages = [
+        { role: 'user', content: [{ type: 'text', text: `Begin. Task: ${state.task}` }] },
+    ];
+    state.steps.forEach((step, i) => {
+        const id = `call_${i}`;
+        messages.push({ role: 'assistant', content: [{ type: 'tool_use', id, name: step.call.name, input: step.call.input }] });
+        const summary = step.result.ok
+            ? JSON.stringify(step.result.result ?? {}).slice(0, 4000)
+            : `error: ${step.result.error ?? 'unknown'}`;
+        const note = step.visionFallback ? ' [ax tree opaque — auto-captured screenshot follows; use coordinate clicks]' : '';
+        messages.push({ role: 'user', content: [{ type: 'tool_result', tool_use_id: id, content: summary + note }] });
+    });
+    return messages;
+}
+// Parse the Anthropic response body into a ModelDecision. tool_use blocks
+// become tool calls; a reply with no tool calls is treated as the model
+// finishing, with its text as the summary.
+export function parseDecision(body) {
+    const content = body.content;
+    const blocks = Array.isArray(content) ? content : [];
+    const toolCalls = [];
+    const texts = [];
+    for (const block of blocks) {
+        const b = block;
+        if (b.type === 'tool_use' && typeof b.name === 'string') {
+            toolCalls.push({ name: b.name, input: b.input ?? {} });
+        }
+        else if (b.type === 'text' && typeof b.text === 'string') {
+            texts.push(b.text);
+        }
+    }
+    if (toolCalls.length === 0) {
+        return { toolCalls: [], done: { text: texts.join('\n').trim() || 'no further action' } };
+    }
+    return { toolCalls };
+}
+// The default responder: one Anthropic Messages call per turn.
+export function makeClaudeResponder(config = {}) {
+    const baseUrl = (config.baseUrl || DEFAULT_CLAUDE_BASE_URL).replace(/\/+$/, '');
+    const model = config.model || DEFAULT_CLAUDE_MODEL;
+    const maxTokens = config.maxTokens ?? 1024;
+    const doFetch = config.fetchImpl ?? fetch;
+    const apiKey = resolveApiKey(config);
+    return async (state) => {
+        const res = await doFetch(`${baseUrl}/v1/messages`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': ANTHROPIC_VERSION,
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: maxTokens,
+                system: buildSystemPrompt(state),
+                tools: COMPUTER_TOOLS,
+                messages: buildMessages(state),
+            }),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`model request failed: ${res.status} ${res.statusText} ${text.slice(0, 500)}`);
+        }
+        const body = await res.json();
+        return parseDecision(body);
+    };
+}

package/dist/lib/concurrency.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bounded, order-preserving async mapper.
+ *
+ * Runs `fn` over `items` with at most `concurrency` calls in flight, and — when
+ * `staggerMs` is set — spaces successive task starts at least that far apart so
+ * spawns trickle out instead of firing as one simultaneous burst. Results come
+ * back in input order regardless of completion order.
+ *
+ * The stagger matters beyond scheduling: a burst of identical child spawns (per-PID
+ * `lsof`, multi-dotfile scans) reads to behavioral EDR as recon/enumeration. A
+ * bounded, spread-out spawn rate produces the same data without the burst signature.
+ */
+export interface BoundedMapOptions {
+    /** Maximum number of `fn` calls running at once. Coerced to >= 1. */
+    concurrency: number;
+    /** Minimum spacing (ms) between successive task starts. 0 (default) = no spacing. */
+    staggerMs?: number;
+}
+export declare function mapBounded<T, R>(items: readonly T[], fn: (item: T, index: number) => Promise<R>, opts: BoundedMapOptions): Promise<R[]>;

package/dist/lib/concurrency.js

@@ -0,0 +1,33 @@
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export async function mapBounded(items, fn, opts) {
+    const concurrency = Math.max(1, Math.floor(opts.concurrency));
+    const stagger = Math.max(0, opts.staggerMs ?? 0);
+    const results = new Array(items.length);
+    if (items.length === 0)
+        return results;
+    let cursor = 0;
+    // Shared gate: the earliest time the next task is allowed to start. Updated
+    // atomically (no await between read and write) so parallel workers each claim
+    // a distinct slot spaced `stagger` apart.
+    let nextStart = 0;
+    async function worker() {
+        for (;;) {
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            if (stagger > 0) {
+                const now = performance.now();
+                const wait = Math.max(0, nextStart - now);
+                nextStart = Math.max(now, nextStart) + stagger;
+                if (wait > 0)
+                    await delay(wait);
+            }
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const workers = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    return results;
+}