browxai 0.7.0

package/dist/page/perf.js

@@ -0,0 +1,373 @@
+// Performance tracing — capability `action` (writes a file).
+//
+// "This click took 4s — why?" has no diagnostic surface in browxai's read-only
+// tools: a screenshot/snapshot/network slice shows *what* happened, not *why*
+// it was slow. CDP `Tracing.start` / `Tracing.end` produces a chromium trace
+// blob that's the same shape Lighthouse / DevTools Performance consume; this
+// module wraps it as a per-session lifecycle and pairs it with a minimal
+// insights extractor over the resulting JSON so the agent gets a structured
+// summary (long tasks, layout shifts, render-blocking resources, LCP /
+// navigation timing candidates) without having to ship a megabyte of trace
+// back through the MCP channel.
+//
+// Lifecycle (per session):
+//   - perf_start({categories?})  → enables tracing on the CDP target.
+//   - perf_stop({path?})         → flushes events to a workspace-rooted file
+//                                  (default `<workspace>/perf-traces/<id>-<ts>.json`),
+//                                  returns the path + a tiny inline summary.
+//                                  Always idempotent: a second `perf_stop`
+//                                  without a matching `perf_start` returns
+//                                  `notRunning:true`, not an error.
+//   - perf_insights({tracePath}) → reads the trace JSON and returns
+//                                  structured insights.
+//
+// Idempotency guarantee (invariant 6): `perf_start` while a trace is already
+// running first cleanly stops the in-flight one (events discarded) before
+// starting fresh, so an agent that lost track of state can always recover by
+// just calling `perf_start` again. `perf_stop` is safe to call any number of
+// times.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+/** Default trace categories — covers the cases DevTools' Performance panel
+ *  uses for its core insights (frames, paint, layout, long tasks, user
+ *  timing, loading). Smaller than the everything-on default to keep traces
+ *  manageable. */
+export const DEFAULT_TRACE_CATEGORIES = [
+    "devtools.timeline",
+    "loading",
+    "blink.user_timing",
+    "disabled-by-default-devtools.timeline",
+    "disabled-by-default-devtools.timeline.frame",
+    "latencyInfo",
+];
+/** Per-session trace state machine. One instance per SessionEntry. */
+export class PerfTracingState {
+    running = false;
+    events = [];
+    /** Hook teardowns from the most recent `start`. */
+    listeners = [];
+    /** Resolved-when the in-flight `Tracing.end` flushes all events. */
+    completePromise = null;
+    completeResolve = null;
+    /** Categories the current/last trace was started with — surfaced on stop. */
+    categories = [];
+    startedAt = 0;
+    /** True iff a trace is currently being collected. */
+    isRunning() {
+        return this.running;
+    }
+    /** Start tracing on `cdp`. If a trace is already running, stops it cleanly
+     *  first (events discarded) — guarantees the caller never gets stuck in a
+     *  "tracing already started" CDP error from a stale start. */
+    async start(cdp, opts = {}) {
+        let restarted = false;
+        if (this.running) {
+            restarted = true;
+            // Clean restart: stop the in-flight trace; throw away its events.
+            await this.stopInternal(cdp).catch(() => undefined);
+        }
+        const categories = opts.categories && opts.categories.length > 0 ? opts.categories : DEFAULT_TRACE_CATEGORIES;
+        this.events = [];
+        this.categories = [...categories];
+        this.startedAt = Date.now();
+        const onData = (e) => {
+            if (Array.isArray(e?.value)) {
+                for (const ev of e.value)
+                    this.events.push(ev);
+            }
+        };
+        const onComplete = () => {
+            if (this.completeResolve)
+                this.completeResolve();
+        };
+        cdp.on("Tracing.dataCollected", onData);
+        cdp.on("Tracing.tracingComplete", onComplete);
+        this.listeners = [
+            () => cdp.off("Tracing.dataCollected", onData),
+            () => cdp.off("Tracing.tracingComplete", onComplete),
+        ];
+        // Tracing.start with traceConfig — pass `includedCategories` for fine
+        // control. CDP also accepts a comma-separated `categories` string for
+        // legacy; the typed `traceConfig` is the supported shape.
+        await cdp.send("Tracing.start", {
+            transferMode: "ReportEvents",
+            traceConfig: {
+                recordMode: "recordContinuously",
+                includedCategories: [...categories],
+            },
+        });
+        this.running = true;
+        return { categories: [...categories], restarted };
+    }
+    /** Stop tracing and return the buffered events. Safe to call when no trace
+     *  is running — returns `notRunning:true` with an empty event list. */
+    async stop(cdp) {
+        if (!this.running) {
+            return { notRunning: true, events: [], categories: [...this.categories], durationMs: 0 };
+        }
+        const durationMs = Date.now() - this.startedAt;
+        await this.stopInternal(cdp);
+        const evts = this.events;
+        this.events = [];
+        return { events: evts, categories: [...this.categories], durationMs };
+    }
+    /** Force-clean teardown for session close paths. Tolerates double calls. */
+    async closeIfRunning(cdp) {
+        if (!this.running)
+            return;
+        await this.stopInternal(cdp).catch(() => undefined);
+        this.events = [];
+    }
+    /** Internal stop: send `Tracing.end`, wait for the `tracingComplete` flush,
+     *  detach listeners. Guarantees `running=false` even on errors so the
+     *  next start always works. */
+    async stopInternal(cdp) {
+        this.completePromise = new Promise((res) => {
+            this.completeResolve = res;
+        });
+        try {
+            await cdp.send("Tracing.end").catch(() => undefined);
+            // Bounded wait: the `tracingComplete` flush is normally near-instant
+            // but a runaway target shouldn't deadlock us. 30s is generous.
+            await Promise.race([
+                this.completePromise,
+                new Promise((res) => setTimeout(res, 30_000)),
+            ]);
+        }
+        finally {
+            for (const off of this.listeners) {
+                try {
+                    off();
+                }
+                catch {
+                    /* listener removal is best-effort */
+                }
+            }
+            this.listeners = [];
+            this.completePromise = null;
+            this.completeResolve = null;
+            this.running = false;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Workspace path helper. Mirrors `resolveWorkspacePath` in session/storage.ts
+// but kept local so this module doesn't reach across page → session.
+export function resolvePerfTracePath(workspaceRoot, p, tool) {
+    const resolved = resolve(workspaceRoot, p);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`${tool}: \`path\` must resolve inside $BROWX_WORKSPACE — got "${p}".`);
+    }
+    return resolved;
+}
+/** Default trace filename under `<workspace>/perf-traces/<sessionId>-<ts>.json`. */
+export function defaultTracePath(workspaceRoot, sessionId) {
+    // sanitize the session id for the filename — only safe chars survive.
+    const safe = (sessionId || "default").replace(/[^A-Za-z0-9._-]/g, "_");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(workspaceRoot, "perf-traces", `${safe}-${ts}.json`);
+}
+/** Write a trace event array as a chrome-tracing-compatible JSON file. The
+ *  format the chromium ecosystem expects is `{ traceEvents: [...] }`; we
+ *  also include `metadata` so a roundtrip through tracingControl tools is
+ *  cleanly identifiable. */
+export function writeTraceFile(workspaceRoot, filePath, events, meta, tool) {
+    // Path is workspace-rooted by construction via `resolvePerfTracePath`.
+    const resolved = resolvePerfTracePath(workspaceRoot, filePath, tool);
+    const parent = dirname(resolved);
+    // ws.sub-style: ensure parent exists under workspace.root.
+    if (parent && !existsSync(parent))
+        mkdirSync(parent, { recursive: true });
+    const payload = JSON.stringify({
+        traceEvents: events,
+        metadata: {
+            source: "browxai",
+            sessionId: meta.sessionId,
+            categories: meta.categories,
+            durationMs: meta.durationMs,
+            eventCount: events.length,
+            capturedAt: new Date().toISOString(),
+        },
+    });
+    // ws.root-rooted path — see resolvePerfTracePath above for the guard.
+    writeFileSync(resolved, payload, "utf8");
+    return { resolved, bytes: Buffer.byteLength(payload, "utf8") };
+}
+/** Read a trace file and return the event array. */
+export function readTraceFile(workspaceRoot, filePath, tool) {
+    const resolved = resolvePerfTracePath(workspaceRoot, filePath, tool);
+    if (!existsSync(resolved)) {
+        throw new Error(`${tool}: trace file not found at "${resolved}" — call perf_stop first`);
+    }
+    const raw = readFileSync(resolved, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${tool}: trace file "${resolved}" is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (Array.isArray(parsed)) {
+        return { events: parsed };
+    }
+    if (parsed &&
+        typeof parsed === "object" &&
+        Array.isArray(parsed.traceEvents)) {
+        const obj = parsed;
+        return { events: obj.traceEvents, metadata: obj.metadata };
+    }
+    throw new Error(`${tool}: trace file "${resolved}" doesn't look like a chrome trace (missing traceEvents array)`);
+}
+// ---------------------------------------------------------------------------
+// Minimal insights extractor over the trace event array.
+//
+// We deliberately avoid pulling in chrome-devtools-frontend's full Insights
+// pipeline (it would dominate the dependency tree). The four extracts below
+// cover the cases an agent diagnosing "why was that slow" actually asks:
+//   - Long tasks: blocking work on the main thread
+//   - Layout shifts: visual instability (CLS contributors)
+//   - Render-blocking resources: critical-path CSS / sync JS
+//   - LCP candidates: which element + when
+const LONG_TASK_THRESHOLD_MS = 50;
+const MAX_LIST_ENTRIES = 50;
+/** Extract structured insights from a trace event array. Pure — exported for
+ *  unit tests. */
+/** chromium trace ts is microseconds; surface ms for the agent. */
+function usToMs(us) {
+    return typeof us === "number" ? us / 1000 : 0;
+}
+function handleLayoutShift(acc, ts, data) {
+    const score = typeof data.score === "number"
+        ? data.score
+        : typeof data.weighted_score_delta === "number"
+            ? data.weighted_score_delta
+            : 0;
+    const entry = { startMs: ts, score };
+    if (data.had_recent_input === true)
+        entry.hadRecentInput = true;
+    acc.layoutShifts.push(entry);
+}
+/** Render-blocking resources are stitched: a `blocking`/`in_body_parser_blocking`
+ *  `ResourceSendRequest` records the start; the matching `ResourceFinish` emits
+ *  the duration. */
+function handleResourceEvent(acc, name, ts, data) {
+    const requestId = typeof data.requestId === "string" ? data.requestId : undefined;
+    if (!requestId)
+        return;
+    if (name === "ResourceSendRequest") {
+        const url = typeof data.url === "string" ? data.url : "";
+        const blocking = typeof data.renderBlocking === "string" ? data.renderBlocking : "";
+        if (url && (blocking === "blocking" || blocking === "in_body_parser_blocking")) {
+            acc.sendStartByRequestId.set(requestId, {
+                url,
+                tsMs: ts,
+                blocking,
+                type: typeof data.resourceType === "string" ? data.resourceType : undefined,
+            });
+        }
+    }
+    else if (name === "ResourceFinish" && acc.sendStartByRequestId.has(requestId)) {
+        const start = acc.sendStartByRequestId.get(requestId);
+        acc.renderBlocking.push({ url: start.url, type: start.type, durationMs: ts - start.tsMs });
+        acc.sendStartByRequestId.delete(requestId);
+    }
+}
+function handleLcpCandidate(acc, ts, data) {
+    const entry = { startMs: ts };
+    if (typeof data.size === "number")
+        entry.size = data.size;
+    if (typeof data.DOMNodeId === "number")
+        entry.nodeName = `#${String(data.DOMNodeId)}`;
+    if (typeof data.nodeName === "string")
+        entry.nodeName = data.nodeName;
+    if (typeof data.url === "string")
+        entry.url = data.url;
+    acc.lcpCandidates.push(entry);
+}
+const NAV_MILESTONE_BY_NAME = {
+    navigationStart: "navigationStartMs",
+    firstPaint: "firstPaintMs",
+    firstContentfulPaint: "firstContentfulPaintMs",
+    MarkDOMContent: "domContentLoadedMs",
+    domContentLoadedEventEnd: "domContentLoadedMs",
+    MarkLoad: "loadEventMs",
+    loadEventEnd: "loadEventMs",
+};
+/** Dispatch one trace event into the accumulator. */
+function ingestEvent(acc, e) {
+    if (!e || typeof e !== "object")
+        return;
+    const name = typeof e.name === "string" ? e.name : "";
+    if (!name)
+        return;
+    const ts = usToMs(e.ts);
+    const data = ((e.args ?? {}).data ?? {});
+    // Long tasks: `RunTask` / `LongTask` on the main thread with dur ≥ threshold.
+    if ((name === "RunTask" || name === "LongTask") && usToMs(e.dur) >= LONG_TASK_THRESHOLD_MS) {
+        acc.longTasks.push({ startMs: ts, durationMs: usToMs(e.dur) });
+    }
+    else if (name === "LayoutShift") {
+        handleLayoutShift(acc, ts, data);
+    }
+    else if (name === "ResourceSendRequest" || name === "ResourceFinish") {
+        handleResourceEvent(acc, name, ts, data);
+    }
+    else if (name === "largestContentfulPaint::Candidate") {
+        handleLcpCandidate(acc, ts, data);
+    }
+    const navKey = NAV_MILESTONE_BY_NAME[name];
+    if (navKey)
+        acc.nav[navKey] = ts;
+}
+/** Relativise navigation timing against navigationStart — raw monotonic ts
+ *  numbers aren't interpretable; offsets are. */
+function buildNavigation(nav) {
+    if (nav.navigationStartMs === undefined)
+        return undefined;
+    const start = nav.navigationStartMs;
+    const out = { navigationStartMs: start };
+    if (nav.firstPaintMs !== undefined)
+        out.firstPaintMs = nav.firstPaintMs - start;
+    if (nav.firstContentfulPaintMs !== undefined)
+        out.firstContentfulPaintMs = nav.firstContentfulPaintMs - start;
+    if (nav.domContentLoadedMs !== undefined)
+        out.domContentLoadedMs = nav.domContentLoadedMs - start;
+    if (nav.loadEventMs !== undefined)
+        out.loadEventMs = nav.loadEventMs - start;
+    return out;
+}
+export function extractInsights(events) {
+    const acc = {
+        longTasks: [],
+        layoutShifts: [],
+        renderBlocking: [],
+        lcpCandidates: [],
+        sendStartByRequestId: new Map(),
+        nav: {},
+    };
+    for (const e of events)
+        ingestEvent(acc, e);
+    // Sort by impact (top contributors first). LCP candidates stay in input order
+    // (chronological) — the final candidate is the effective LCP.
+    acc.longTasks.sort((a, b) => b.durationMs - a.durationMs);
+    acc.renderBlocking.sort((a, b) => b.durationMs - a.durationMs);
+    acc.layoutShifts.sort((a, b) => b.score - a.score);
+    const cap = (arr) => arr.length > MAX_LIST_ENTRIES ? arr.slice(0, MAX_LIST_ENTRIES) : arr;
+    const insights = {
+        longTasks: cap(acc.longTasks),
+        layoutShifts: cap(acc.layoutShifts),
+        renderBlocking: cap(acc.renderBlocking),
+        lcpCandidates: cap(acc.lcpCandidates),
+        totals: {
+            events: events.length,
+            longTaskCount: acc.longTasks.length,
+            layoutShiftCount: acc.layoutShifts.length,
+            layoutShiftScoreSum: acc.layoutShifts.reduce((s, l) => s + l.score, 0),
+            renderBlockingCount: acc.renderBlocking.length,
+        },
+    };
+    const navigation = buildNavigation(acc.nav);
+    if (navigation)
+        insights.navigation = navigation;
+    return insights;
+}

package/dist/page/plan.d.ts

@@ -0,0 +1,192 @@
+import type { CDPSession, Page } from "playwright-core";
+import { type FindCandidate } from "./find.js";
+import type { SnapshotSubstrate } from "./snapshot-substrate.js";
+import type { RefRegistry } from "./refs.js";
+import type { ActionContext, ActionResult } from "./actionresult.js";
+/** Action verbs `plan()`/`execute()` understand. Single-target verbs only —
+ *  page-level / multi-step verbs (`navigate`, `scroll`, `wait_for`, `choose_option`)
+ *  are out of scope here; they're either trivially planned (`navigate(url)` doesn't
+ *  need a ranked candidate) or expand into multiple action-window dispatches and
+ *  belong in their own primitives. */
+export declare const PLAN_VERBS: readonly ["click", "fill", "hover", "press", "select"];
+export type PlanVerb = (typeof PLAN_VERBS)[number];
+/** Per-verb args envelope. `value` is the typed-in string for `fill`, `values`
+ *  the option list for `select`, `key` the Playwright key syntax for `press`,
+ *  `button` the mouse button for `click`. Click / hover have no extra args
+ *  beyond the descriptor's bound `ref`. */
+export interface PlanVerbArgs {
+    /** `fill` value. */
+    value?: string;
+    /** `select` option labels/values. */
+    values?: string[];
+    /** `press` key. */
+    key?: string;
+    /** `click` mouse button (default left). */
+    button?: "left" | "right" | "middle";
+}
+/** The plan/execute envelope. The agent receives one, may inspect it, may
+ *  cache it, and later hands it back verbatim to `execute()`. */
+export interface ActionDescriptor {
+    /** Stable id for this descriptor (not a ref — a descriptor id; useful for
+     *  caches that key on "this plan attempt"). */
+    id: string;
+    /** The bound element ref. Uses the **same** `eN` namespace as `find()` /
+     *  `snapshot()` / `name_ref` — descriptors do NOT have a parallel id system. */
+    ref: string;
+    /** Action verb to dispatch. */
+    verb: PlanVerb;
+    /** Verb-specific args. Empty `{}` for click/hover with default button. */
+    args: PlanVerbArgs;
+    /** Evidence captured at plan time so the caller can decide whether to execute. */
+    evidence: PlanEvidence;
+    /** Epoch-ms past which `execute()` returns a structured "descriptor expired"
+     *  failure. Defaults to `plan() + 60_000`. */
+    expiresAt: number;
+}
+export interface PlanEvidence {
+    query: string;
+    /** The top candidate's selectorHint — the same string `find()` would emit. */
+    selectorHint: string;
+    /** Tier (1–5) and stability (high/medium/low) of the picked locator. */
+    selectorTier: 1 | 2 | 3 | 4 | 5;
+    stability: FindCandidate["stability"];
+    /** The picked candidate's role / name / testId. */
+    role: string;
+    name?: string;
+    testId?: string;
+    /** The picked candidate's score under `find()`'s ranker. */
+    score: number;
+    /** Whether the candidate was visible+enabled+on-screen at plan time. */
+    actionable: FindCandidate["actionable"];
+    /** Whether `find()` issued any warnings (low confidence, no visible
+     *  candidate, etc.). Caller can refuse to execute on this signal. */
+    warnings: string[];
+    /** Up to 4 lower-ranked alternatives (without `selectorHint` repetition).
+     *  Useful when an agent wants to retry against a sibling after a failure. */
+    alternatives: Array<{
+        ref: string;
+        role: string;
+        name?: string;
+        testId?: string;
+        score: number;
+    }>;
+}
+export interface PlanOptions {
+    query: string;
+    verb: PlanVerb;
+    /** Verb args. Required ones (value for fill, key for press, values for
+     *  select) are validated by `plan()` itself, not at `execute()` time — the
+     *  point is to fail fast at capture, not at dispatch. */
+    verbArgs?: PlanVerbArgs;
+    /** Same semantics as `find()`'s `contextRef` — scope the candidate walk
+     *  to this ref's subtree. */
+    contextRef?: string;
+    /** Same semantics as `find()` — return no descriptor if no candidate
+     *  scored above the floor. Default 0 (off). */
+    confidenceFloor?: number;
+    /** Descriptor lifetime in ms. Default 60_000 (1 minute). Clamped to
+     *  [1_000, 30 * 60_000] (1s..30min) — anything longer is almost certainly
+     *  a misuse (the page WILL have moved on; re-plan instead). */
+    ttlMs?: number;
+    /** Configured test-attribute list, same as `find()`. */
+    testAttributes: string[];
+    /** Capability-aware fallback hints for the underlying `find()` call. */
+    fallbackHints?: {
+        coords: boolean;
+        evalJs: boolean;
+    };
+}
+export type PlanOutcome = {
+    ok: true;
+    descriptor: ActionDescriptor;
+    warnings: string[];
+    tokensEstimate: number;
+} | {
+    ok: false;
+    error: string;
+    warnings: string[];
+    tokensEstimate: number;
+};
+/** Validate per-verb args at plan time so a bad descriptor can never reach
+ *  `execute()`. Pure; exported for tests. */
+export declare function validateVerbArgs(verb: PlanVerb, args: PlanVerbArgs | undefined): string | null;
+/** Clamp a caller-supplied ttl into the sane range. Pure; exported for tests. */
+export declare function clampTtl(ttlMs: number | undefined): number;
+/** Project a `find()` candidate into a descriptor's `evidence` block.
+ *  Pure; exported for tests. */
+export declare function evidenceFromCandidate(query: string, picked: FindCandidate, alternatives: FindCandidate[], warnings: string[]): PlanEvidence;
+/** Build a descriptor from a resolved candidate + caller args. Pure; exported
+ *  for tests. */
+export declare function buildDescriptor(args: {
+    picked: FindCandidate;
+    alternatives: FindCandidate[];
+    query: string;
+    verb: PlanVerb;
+    verbArgs: PlanVerbArgs;
+    warnings: string[];
+    ttlMs: number;
+    now?: number;
+}): ActionDescriptor;
+/** rough JSON-byte/4 token estimate for a descriptor — matches the
+ *  shape `tokensEstimate` uses across other tools. Pure; exported for tests. */
+export declare function estimateDescriptorTokens(d: ActionDescriptor): number;
+/**
+ * `plan()`: rank `query` against the live tree, pick the top candidate,
+ * validate the verb's args, return a serialisable descriptor (no dispatch).
+ *
+ * Returns `{ ok: false }` with structured reasons when:
+ *   - the verb's required args are missing/wrong-shape (validated up front),
+ *   - `find()` returned no candidates (or none above `confidenceFloor`).
+ *
+ * Note: a descriptor IS returned even if the top candidate is non-actionable
+ * (off-screen / disabled). The caller can inspect `evidence.actionable` and
+ * decide; we don't silently refuse to plan against a hidden modal, because
+ * sometimes that's exactly what the caller wants to confirm.
+ */
+export declare function plan(page: Page, substrate: SnapshotSubstrate, refs: RefRegistry, opts: PlanOptions, 
+/** CDP handle for find()'s visible-rect bbox fast path — chromium only. */
+cdp?: CDPSession): Promise<PlanOutcome>;
+/** structured `execute()` failure shape — distinguishes a *dispatched*
+ *  ActionResult (the dispatch ran; ok=true|false reflects the action's outcome)
+ *  from a *refused* dispatch (descriptor expired / ref gone) where the action
+ *  was never attempted. */
+export type ExecuteOutcome = {
+    ok: true;
+    result: ActionResult;
+    tokensEstimate: number;
+} | {
+    ok: false;
+    error: string;
+    reason: "expired" | "ref-gone" | "invalid";
+    tokensEstimate: number;
+};
+/** Reasons we may refuse to dispatch a descriptor without ever running it. */
+export type ExecuteRefusal = Exclude<ExecuteOutcome, {
+    ok: true;
+}>;
+export interface ExecuteOptions {
+    /** Optional dispatch-window overrides (mode/maxResultTokens/timeoutMs/
+     *  recordingHint flow through to the underlying action). Mirrors
+     *  `ActionWindowOptions` but the descriptor itself is the source of truth
+     *  for the target. */
+    mode?: import("./actionresult.js").SnapshotMode;
+    maxResultTokens?: number;
+    deadlineMs?: number;
+    deadlineWarning?: string;
+    recordingHint?: {
+        selectorHint: string;
+        stability?: FindCandidate["stability"];
+    };
+    /** Override "now" — for tests of expiry semantics. */
+    now?: number;
+}
+/** Static descriptor validation (shape only — does not touch the page).
+ *  Pure; exported for tests. */
+export declare function validateDescriptor(d: unknown): {
+    ok: true;
+    descriptor: ActionDescriptor;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function execute(ctx: ActionContext, rawDescriptor: unknown, opts?: ExecuteOptions): Promise<ExecuteOutcome>;