@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/browser/service.js

@@ -11,7 +11,7 @@ import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { clearProfileRuntime } from './runtime-state.js';
 import { resolveDomainSkill } from './domain-skills.js';
 import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
-import { getRefs, resolveRefToCoords } from './refs.js';
+import { getRefs, resolveRefToCoords, describeRefs, healRef } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
 import { detectUploadPattern, stageUploadFile, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
@@ -672,6 +672,31 @@ export class BrowserService {
             { width: 0, height: 0 };
         return { path: finalPath, bytes: buffer.length, width: dims.width, height: dims.height };
     }
+    /**
+     * Export the current tab as a PDF via CDP `Page.printToPDF`. Reuses the
+     * screenshot session + tab resolution so `--tab`, path sandboxing, and the
+     * auto-path (`sessions/<task>/<ts>.pdf`) all behave identically to
+     * `screenshot`. `printBackground: true` matches Chrome's default print flow
+     * — without it, dark-mode pages render on a blank sheet.
+     */
+    async printToPdf(taskId, tabHint, outputPath) {
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target) {
+            throw new Error(`Tab ${shortId} not found`);
+        }
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const { data } = (await conn.cdp.send('Page.printToPDF', { printBackground: true, preferCSSPageSize: true }, sessionId));
+        const buffer = Buffer.from(data, 'base64');
+        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const automaticPath = path.join(sessionsDir, `${Date.now()}.pdf`);
+        const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
+        await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
+        await fs.promises.writeFile(finalPath, buffer);
+        return { path: finalPath, bytes: buffer.length };
+    }
     // ─── Recording ──────────────────────────────────────────────────────────────
     //
     // CDP `Page.startScreencast` emits a JPEG frame per `everyNthFrame`. We pipe
@@ -722,7 +747,7 @@ export class BrowserService {
             '-vsync', 'vfr',
             '-y',
             outputPath,
-        ], { stdio: ['pipe', 'ignore', 'pipe'] });
+        ], { stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true });
         // Wait for the spawn to confirm (or fail) before we wire CDP frames into a
         // dead pipe. ENOENT from a missing ffmpeg surfaces here as a real error
         // instead of a silently empty .webm.
@@ -880,7 +905,6 @@ export class BrowserService {
             return { recording: false };
         return { recording: true, path: rec.outputPath, elapsedMs: Date.now() - rec.startedAt };
     }
-    refsCache = new Map();
     async refs(taskId, tabHint, opts = {}) {
         const { conn, task } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
@@ -889,7 +913,51 @@ export class BrowserService {
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
-        return getRefs(conn.cdp, sessionId, opts);
+        const result = await getRefs(conn.cdp, sessionId, opts);
+        // Snapshot the stable descriptors AND the opts they were numbered against
+        // so a later click/type can self-heal a drifted ref by rebuilding with the
+        // same filter. `refs()` is the sole owner of this cache — actions read it,
+        // never overwrite it. Persist to tasks.json so it survives a daemon
+        // restart.
+        this.cacheRefDescriptors(task, shortId, result.nodeMap, result.opts);
+        await this.saveTaskState(task.profile, conn.tasks);
+        return { refs: result.refs, nodeMap: result.nodeMap };
+    }
+    /** Record the last ref listing (descriptors + opts) for a tab into state. */
+    cacheRefDescriptors(task, shortId, nodeMap, opts) {
+        if (!task.refDescriptors)
+            task.refDescriptors = {};
+        task.refDescriptors[shortId] = { descriptors: describeRefs(nodeMap), opts };
+    }
+    /**
+     * Re-resolve a caller-supplied ref against a freshly-built node map, healing
+     * it back to the right element when the integer ref has drifted since the
+     * cached `refs` listing. Shared by `click` and `type` so both self-heal
+     * identically. Returns the ref to act on plus, when a heal occurred, the
+     * {@link HealInfo} to surface. Throws when the cached element is gone.
+     */
+    resolveHealedRef(snapshot, nodeMap, ref) {
+        const cached = snapshot?.descriptors.find((d) => d.ref === ref);
+        if (!cached)
+            return { targetRef: ref };
+        const fresh = nodeMap.get(ref);
+        const stillMatches = fresh !== undefined &&
+            fresh.role === cached.role &&
+            fresh.name === cached.name &&
+            fresh.backendNodeId !== undefined;
+        if (stillMatches)
+            return { targetRef: ref };
+        const newRef = healRef(cached, nodeMap);
+        if (newRef === null) {
+            throw new Error(`Ref ${ref} (${cached.role} "${cached.name}") could not be re-resolved: ` +
+                `no matching element on the current page. Re-run 'browser refs' to ` +
+                `refresh the ref numbers, or act by position with 'browser click --at X,Y'.`);
+        }
+        if (newRef === ref)
+            return { targetRef: ref };
+        console.error(`[browser] self-healed ref ${ref} -> ${newRef} (${cached.role} "${cached.name}") — ` +
+            `cached descriptor re-matched after the ref drifted`);
+        return { targetRef: newRef, healed: { from: ref, to: newRef, role: cached.role, name: cached.name } };
     }
     async click(taskId, ref, tabHint) {
         const { conn, task } = await this.findTask(taskId);
@@ -899,8 +967,38 @@ export class BrowserService {
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
-        const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, ref);
+        // Rebuild the node map with the SAME opts the cached listing was numbered
+        // against, so the caller's ref lands on the element they saw in `browser
+        // refs`. Rebuilding with a different filter (the old interactive:false)
+        // renumbers every ref and defeats self-heal on the second click. Default
+        // to the user-facing interactive numbering when no listing was cached yet.
+        const snapshot = task.refDescriptors?.[shortId];
+        const buildOpts = snapshot?.opts ?? { interactive: true, limit: 500 };
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, buildOpts);
+        // Self-heal: the integer ref is positional and drifts on re-render. If the
+        // fresh node at this position no longer matches the cached descriptor,
+        // re-resolve (by attrs/proximity-tie-broken role+name) BEFORE clicking the
+        // wrong element. The cache is owned by refs() and NOT rewritten here — the
+        // caller's ref numbers stay anchored to the listing they came from.
+        const { targetRef, healed } = this.resolveHealedRef(snapshot, nodeMap, ref);
+        const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, targetRef);
+        await clickAtCoords(conn.cdp, sessionId, x, y);
+        return healed ? { healed } : {};
+    }
+    /**
+     * Click raw viewport coordinates, bypassing ref resolution entirely. Backs
+     * `browser click --at X,Y` — the escape hatch when the accessibility tree
+     * exposes no usable ref (canvas apps, custom-drawn UI) and the caller has
+     * located the target from a screenshot.
+     */
+    async clickAt(taskId, x, y, tabHint) {
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target)
+            throw new Error(`Tab ${shortId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
         await clickAtCoords(conn.cdp, sessionId, x, y);
     }
     async type(taskId, ref, text, tabHint, clear) {
@@ -911,8 +1009,14 @@ export class BrowserService {
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
-        const node = nodeMap.get(ref);
+        // Same self-healing story as click(): rebuild against the cached listing's
+        // opts so refs line up with what the user saw, then heal a drifted ref
+        // before typing into the wrong field.
+        const snapshot = task.refDescriptors?.[shortId];
+        const buildOpts = snapshot?.opts ?? { interactive: true, limit: 500 };
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, buildOpts);
+        const { targetRef } = this.resolveHealedRef(snapshot, nodeMap, ref);
+        const node = nodeMap.get(targetRef);
         if (!node)
             throw new Error(`Ref ${ref} not found`);
         if (node.editor) {

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

@@ -78,6 +78,15 @@ export interface Task {
     currentTabId?: string;
     createdAt: number;
     pid: number;
+    /**
+     * Per-tab snapshot of the last ref listing captured for that tab
+     * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
+     * `click`/`type <ref>` can self-heal a drifted ref — the cached `opts` let
+     * the action rebuild its node map with the SAME accessibility filter the
+     * listing was numbered against. Owned by `refs()`; actions never overwrite
+     * it. See RefSnapshot / RefDescriptor.
+     */
+    refDescriptors?: Record<string, import('./refs.js').RefSnapshot>;
 }
 export interface TabInfo {
     id: string;
@@ -118,7 +127,7 @@ export interface HistoricalTask {
     domains: string[];
     tabCount: number;
 }
-export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
+export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -129,6 +138,8 @@ export interface IPCRequest {
     expr?: string;
     path?: string;
     ref?: number;
+    atX?: number;
+    atY?: number;
     text?: string;
     key?: string;
     scrollX?: number;
@@ -194,6 +205,8 @@ export interface IPCResponse {
     height?: number;
     refs?: string;
     nodes?: RefNodeJson[];
+    /** Human-readable note surfaced to the CLI (e.g. a self-heal notice on click). */
+    message?: string;
     port?: number;
     pid?: number;
     fps?: number;

package/dist/lib/budget/live-cloud.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Live budget kill-switch for `agents cloud` dispatch (issue #399).
+ *
+ * Follow-up to #346, which shipped a pre-flight budget gate for cloud runs but
+ * no live mid-run enforcement — a runaway cloud task would keep spending until
+ * the user hit Ctrl-C. This wires the same `makeLiveSpendWatcher` the local
+ * headless run uses (src/lib/exec.ts) into the cloud SSE stream: each `usage`
+ * event from the provider feeds the watcher, and on breach we call
+ * `provider.cancel(taskId)` to terminate server-side.
+ *
+ * Wrapper shape mirrors `renderStream`'s input — it takes an
+ * `AsyncIterable<CloudEvent>` and yields the same events downstream. Dormant
+ * (returns the source stream unchanged) when no caps are configured.
+ */
+import type { CloudProvider, CloudEvent } from '../cloud/types.js';
+import { type BreachInfo } from './enforce.js';
+/** Result surface exposed to the caller so it can act on a mid-stream breach. */
+export interface CloudBudgetGate {
+    /** True once a cap crossed and cancel() was invoked. */
+    breached(): boolean;
+    breach(): BreachInfo | null;
+}
+/**
+ * Wrap a cloud event stream with a live budget watcher. On a `usage` event we
+ * feed the shared watcher; on the first breach we call `provider.cancel(taskId)`
+ * and forward a synthetic `status:'cancelled'` + `error` frame so the renderer
+ * shows why the task stopped. Returns null when no caps are configured; callers
+ * fall through to the raw stream in that case.
+ */
+export declare function wrapStreamWithBudgetGate(args: {
+    provider: CloudProvider;
+    taskId: string;
+    /** Project attribution key — repo slug for Rush, or cwd. */
+    project: string;
+    /** Agent the dispatch runs under (for per_agent cap accounting). */
+    agent: string;
+    /** cwd used to resolve the effective budget config. */
+    cwd?: string;
+}): {
+    wrap: (source: AsyncIterable<CloudEvent>) => AsyncIterable<CloudEvent>;
+    gate: CloudBudgetGate;
+} | null;

package/dist/lib/budget/live-cloud.js

@@ -0,0 +1,79 @@
+import { capsFromConfig, makeLiveSpendWatcher, } from './enforce.js';
+import { resolveBudgetConfig, hasAnyCap } from './config.js';
+import { loadLedger, localDay, spendForDay, spendForProject } from './ledger.js';
+/**
+ * Wrap a cloud event stream with a live budget watcher. On a `usage` event we
+ * feed the shared watcher; on the first breach we call `provider.cancel(taskId)`
+ * and forward a synthetic `status:'cancelled'` + `error` frame so the renderer
+ * shows why the task stopped. Returns null when no caps are configured; callers
+ * fall through to the raw stream in that case.
+ */
+export function wrapStreamWithBudgetGate(args) {
+    const cfg = resolveBudgetConfig(args.cwd);
+    if (!hasAnyCap(cfg))
+        return null;
+    const today = localDay();
+    const entries = loadLedger();
+    const caps = capsFromConfig(cfg, {
+        daySpend: spendForDay(today, entries),
+        projectSpend: spendForProject(args.project, entries),
+    });
+    let firstBreach = null;
+    const watcher = makeLiveSpendWatcher({
+        caps,
+        onBreach: (b) => {
+            firstBreach = b;
+        },
+    });
+    async function* wrap(source) {
+        try {
+            for await (const event of source) {
+                if (event.type === 'usage') {
+                    watcher.feedUsage({
+                        agent: args.agent,
+                        model: event.model,
+                        inputTokens: event.inputTokens ?? 0,
+                        outputTokens: event.outputTokens ?? 0,
+                    });
+                    if (watcher.breached() && firstBreach) {
+                        // Cancel server-side FIRST so we stop the meter; then surface the
+                        // breach to the renderer as an error + cancelled status so the CLI
+                        // exits with a visible reason (not a silent stream close).
+                        try {
+                            await args.provider.cancel(args.taskId);
+                        }
+                        catch (err) {
+                            // Best-effort — even if cancel fails, break the stream: the
+                            // caller sees the error frame and can retry manually.
+                            yield {
+                                type: 'error',
+                                message: `[budget] cap ${firstBreach.cap} exceeded ($${firstBreach.spend.toFixed(2)} > $${firstBreach.limit.toFixed(2)}); cancel FAILED: ${err.message}`,
+                                timestamp: new Date().toISOString(),
+                            };
+                            yield { type: 'status', status: 'cancelled', timestamp: new Date().toISOString() };
+                            return;
+                        }
+                        yield {
+                            type: 'error',
+                            message: `[budget] cap ${firstBreach.cap} exceeded ($${firstBreach.spend.toFixed(2)} > $${firstBreach.limit.toFixed(2)}) — cancelled cloud task ${args.taskId}`,
+                            timestamp: new Date().toISOString(),
+                        };
+                        yield { type: 'status', status: 'cancelled', timestamp: new Date().toISOString() };
+                        return;
+                    }
+                }
+                yield event;
+            }
+        }
+        finally {
+            watcher.dispose();
+        }
+    }
+    return {
+        wrap,
+        gate: {
+            breached: () => watcher.breached(),
+            breach: () => firstBreach,
+        },
+    };
+}

package/dist/lib/budget/live-team.d.ts

@@ -0,0 +1,31 @@
+import type { AgentManager } from '../teams/agents.js';
+import { type BreachInfo } from './enforce.js';
+/** Public surface of the team-scoped budget watcher. */
+export interface TeamBudgetWatcher {
+    /** Feed any new usage events from every running teammate's stdout.log. */
+    poll(): Promise<void>;
+    /** True once any cap has been crossed (mirrors LiveSpendWatcher). */
+    breached(): boolean;
+    /** The first breach seen, or null if none yet. */
+    breach(): BreachInfo | null;
+    /** Release references and stop tapping streams. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Build a team-scoped budget watcher for the given team. Returns null when the
+ * effective budget config has no caps — matching the local watcher's dormant
+ * contract so callers pay nothing when the feature is off.
+ *
+ * The watcher is seeded with prior-day and prior-project spend from the ledger
+ * so a partway-through day counts today's earlier runs against `per_day`.
+ * Each `poll()` reads new bytes from every running teammate's stdout.log and
+ * feeds parsed usage events into the shared watcher — `onBreach` fires exactly
+ * once, mirroring `makeLiveSpendWatcher`.
+ */
+export declare function createTeamBudgetWatcher(args: {
+    manager: AgentManager;
+    team: string;
+    /** Project/cwd used to (a) resolve budget config and (b) seed project spend. */
+    cwd: string;
+    onBreach: (breach: BreachInfo) => void;
+}): TeamBudgetWatcher | null;

package/dist/lib/budget/live-team.js

@@ -0,0 +1,115 @@
+/**
+ * Live budget kill-switch for `agents teams` supervisor (issue #399).
+ *
+ * Follow-up to #346, which wired `makeLiveSpendWatcher` into local `agents run`
+ * only. Teams spawns each teammate as its own `agents run --headless --json`
+ * process, so per-teammate `per_run` caps already fire from those child
+ * watchers. What was still missing was aggregate cross-teammate enforcement
+ * (`per_project` / `per_day` / `per_agent` combined), because the ledger only
+ * gets written on child close — a long-running teammate would blow the shared
+ * cap without any single child watcher noticing.
+ *
+ * This module reuses `makeLiveSpendWatcher` verbatim: on each supervisor wave
+ * we tail every running teammate's stdout.log through `extractUsageEvents`
+ * (the same primitive the local run path uses in src/lib/exec.ts), feed the
+ * usage events into ONE shared watcher, and expose `breached()` so the
+ * supervisor can call `stopByTask` to terminate the whole team.
+ *
+ * Dormant (returns null) when no caps are configured — same zero-cost contract
+ * as the local watcher.
+ */
+import * as fs from 'fs';
+import { capsFromConfig, extractUsageEvents, makeLiveSpendWatcher, } from './enforce.js';
+import { resolveBudgetConfig, hasAnyCap } from './config.js';
+import { loadLedger, localDay, spendForDay, spendForProject } from './ledger.js';
+/**
+ * Build a team-scoped budget watcher for the given team. Returns null when the
+ * effective budget config has no caps — matching the local watcher's dormant
+ * contract so callers pay nothing when the feature is off.
+ *
+ * The watcher is seeded with prior-day and prior-project spend from the ledger
+ * so a partway-through day counts today's earlier runs against `per_day`.
+ * Each `poll()` reads new bytes from every running teammate's stdout.log and
+ * feeds parsed usage events into the shared watcher — `onBreach` fires exactly
+ * once, mirroring `makeLiveSpendWatcher`.
+ */
+export function createTeamBudgetWatcher(args) {
+    const cfg = resolveBudgetConfig(args.cwd);
+    if (!hasAnyCap(cfg))
+        return null;
+    const today = localDay();
+    const entries = loadLedger();
+    const caps = capsFromConfig(cfg, {
+        daySpend: spendForDay(today, entries),
+        projectSpend: spendForProject(args.cwd, entries),
+    });
+    let firstBreach = null;
+    const watcher = makeLiveSpendWatcher({
+        caps,
+        onBreach: (b) => {
+            firstBreach = b;
+            args.onBreach(b);
+        },
+    });
+    const cursors = new Map();
+    let disposed = false;
+    return {
+        async poll() {
+            if (disposed || watcher.breached())
+                return;
+            const teammates = await args.manager.listByTask(args.team);
+            for (const agent of teammates) {
+                // Only tap running local teammates: PENDING has no output yet, cloud
+                // teammates emit through a different channel (their own SSE stream),
+                // and terminal states produce no new bytes.
+                if (agent.status !== 'running')
+                    continue;
+                if (agent.cloudProvider)
+                    continue;
+                const stdoutPath = await agent.getStdoutPath();
+                let stat;
+                try {
+                    stat = fs.statSync(stdoutPath);
+                }
+                catch {
+                    continue; // File not yet created — nothing to read.
+                }
+                const cursor = cursors.get(agent.agentId) ?? { offset: 0, pending: '' };
+                if (stat.size <= cursor.offset) {
+                    cursors.set(agent.agentId, cursor);
+                    continue;
+                }
+                const fd = fs.openSync(stdoutPath, 'r');
+                try {
+                    const toRead = stat.size - cursor.offset;
+                    const buffer = Buffer.alloc(toRead);
+                    const bytesRead = fs.readSync(fd, buffer, 0, toRead, cursor.offset);
+                    const chunk = buffer.toString('utf-8', 0, bytesRead);
+                    cursor.offset += bytesRead;
+                    const { events, rest } = extractUsageEvents(chunk, cursor.pending, undefined, agent.agentType);
+                    cursor.pending = rest;
+                    for (const ev of events) {
+                        watcher.feedUsage(ev);
+                        if (watcher.breached())
+                            break;
+                    }
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                cursors.set(agent.agentId, cursor);
+                if (watcher.breached())
+                    return;
+            }
+        },
+        breached: () => watcher.breached(),
+        breach: () => firstBreach,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            watcher.dispose();
+            cursors.clear();
+        },
+    };
+}

package/dist/lib/cloud/codex.js

@@ -104,6 +104,10 @@ export class CodexCloudProvider {
             cancel: false,
             message: false,
             multiRepo: false,
+            // `codex cloud exec --env <id> <prompt>` is the only dispatch surface the
+            // codex CLI exposes — it has no flag to attach images or ride-along skills,
+            // and the env bundles its own context at creation time. Both stay false
+            // until the upstream CLI grows an attachment surface.
             skills: false,
             images: false,
         };

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

@@ -4,7 +4,7 @@
  * Auth: reads the session token from ~/.rush/user.yaml (written by `rush login`).
  * Requires the Rush GitHub App installed on the target repo.
  */
-import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities, ImageAttachment, SkillRef } from './types.js';
 export declare const RUSH_CONSENT_PATH: string;
 export declare function hasRushUploadConsent(accountFingerprint: string, opts?: DispatchOptions, consentPath?: string): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
@@ -63,6 +63,17 @@ export declare function buildDispatchBody(input: {
     }>;
     accountManifest?: AccountManifest | null;
     accountTokens?: AccountTokenEntry[] | null;
+    /**
+     * Skill ride-alongs so the cloud pod isn't context-blind. Forwarded verbatim
+     * as `skills` so the Factory Floor can mount them by id/version before the
+     * agent runs. Omitted when empty.
+     */
+    skills?: SkillRef[] | null;
+    /**
+     * Base64 image attachments for vision dispatch. Sliced to
+     * MAX_IMAGES_PER_DISPATCH — extras are dropped, never sent. Omitted when empty.
+     */
+    images?: ImageAttachment[] | null;
 }): Record<string, unknown>;
 /** A single account registered in Rush Cloud's multi-account rotation pool. */
 export interface RemoteAccount {

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 };