@prompteryx/sdk 0.4.0

package/dist/page-8LsjwpEo.d.mts

@@ -0,0 +1,879 @@
+/**
+ * Browser-agent model catalog — the ids `px.autopilot.run({ model })` accepts.
+ *
+ * ⚠️ MUST MIRROR `components/unified-chat-v2/browser-models.ts`
+ * `V2_BROWSER_MODELS` in the platform repo — that file is the canonical
+ * catalog the server validates against (an unknown id hard-400s with
+ * `UNSUPPORTED_MODEL` under strict validation). When that list changes,
+ * regenerate this one. Last synced: 2026-09-03 — 32 ids.
+ *
+ * The type stays open (`| (string & {})`) so a model the server adds
+ * tomorrow works without an SDK release, while editors still autocomplete
+ * the known catalog.
+ */
+declare const AUTOPILOT_MODELS: readonly ["gemini-3.5-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-default", "gemini-3-flash-preview", "gemini-3.5-flash-lite", "model-a", "model-a1", "model-b", "model-j", "model-k", "model-k37", "claude-sonnet-4-6", "claude-opus-4-8", "gpt-5.6-terra", "gpt-5.6-sol", "gpt-5.5", "claude-fable-5-vision", "claude-opus-5-vision", "claude-sonnet-5-vision", "claude-sonnet-4-6-vision", "gpt-5.6-luna-vision", "gpt-5.4-vision", "gpt-4o-vision", "kimi-k3-vision", "modelc", "model-d", "model-d1", "model-e", "model-f", "model-h", "model-i"];
+/** A model id from the known catalog. */
+type AutopilotModelId = (typeof AUTOPILOT_MODELS)[number];
+/** Open union: known ids autocomplete, forward-compatible strings still pass. */
+type AutopilotModel = AutopilotModelId | (string & {});
+/** The platform default when `model` is omitted. */
+declare const DEFAULT_AUTOPILOT_MODEL = "gemini-3.5-flash";
+
+/**
+ * Shared types for the Prompteryx SDK.
+ *
+ * Two important framing decisions reflected here:
+ *
+ * 1. NAMING: We use Prompteryx-native names throughout — `copilot`,
+ *    `autopilot`, `read`, `scan`, `do`, `run`. We deliberately don't
+ *    use the Stagehand vocabulary (act/extract/observe/agent).
+ * 2. EXTENSIBILITY: Many fields accept `string` rather than enums so
+ *    new Visual Studio nodes / new Gemini models / new providers
+ *    work the moment they're available server-side, without the SDK
+ *    needing a release. Where we DO enum, the type adds `| string`
+ *    so callers can still pass forward-compatible values.
+ */
+
+type ExecutionStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
+type Region = 'us-east-1' | 'us-west-2' | 'eu-west-1' | 'eu-central-1' | 'ap-southeast-1' | (string & {});
+type ProxyLocation = 'auto' | 'us' | 'gb' | 'ca' | 'de' | 'fr' | 'au' | 'in' | 'br' | 'jp' | (string & {});
+/** Where a workflow runs. Cloud = our infrastructure (always works).
+ *  Local = the user's own Chrome via the Prompteryx plugin (more
+ *  capable for tasks needing the user's real logins). */
+type ExecutionTarget = 'cloud' | 'local';
+interface WorkflowSummary {
+    /** `wf_…` */
+    id: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+    nodeCount?: number;
+    /** True if the workflow has an active schedule attached. */
+    scheduled?: boolean;
+    /** Tags / categories the user has assigned. */
+    tags?: string[];
+}
+/**
+ * Every option the Visual Studio UI exposes when you run a workflow.
+ * Adding a new option in the UI? Add it here too. Anything passed in
+ * an `executionOptions` field unrecognised by the SDK still rides
+ * through (passthrough = future-proof).
+ */
+interface WorkflowExecutionOptions {
+    /** Run on cloud browser (default) or via the user's local Chrome
+     *  through the Prompteryx plugin. */
+    target?: ExecutionTarget;
+    /** Chrome profile id (cloud or local). Override the workflow's
+     *  saved profile for this one run. */
+    chromeProfile?: string;
+    /** 'visible' = headed; 'headless' = no UI. */
+    runMode?: 'visible' | 'headless';
+    /** Capture a video recording. */
+    videoRecording?: boolean;
+    /** "Turbo" mode skips visual polish + delay tweaks for speed. */
+    turboBoost?: boolean;
+    /** Max execution time in ms. */
+    timeout?: number;
+    /** Return every node's output in the execution record (heavy). */
+    includeNodeOutputs?: boolean;
+    /** Override viewport size. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Run in a specific region (cloud only). */
+    region?: Region;
+    /** Use residential proxy. */
+    useProxy?: boolean;
+    /** Proxy exit country. */
+    proxyLocation?: ProxyLocation;
+    /** Auto-solve CAPTCHAs during the run. */
+    useCaptcha?: boolean;
+    /** Free-form passthrough — anything unrecognised by the SDK is
+     *  forwarded to the server intact. Use for new server-side
+     *  options before the SDK gets a release for them. */
+    passthrough?: Record<string, unknown>;
+}
+interface RunWorkflowOptions {
+    /** Workflow variables / input the workflow expects. */
+    input?: Record<string, unknown>;
+    /** Execution options — overrides the workflow's saved settings. */
+    execution?: WorkflowExecutionOptions;
+}
+interface RunWorkflowResult {
+    executionId: string;
+    status: ExecutionStatus;
+    workflowId: string;
+    startedAt?: string;
+}
+interface ExecutionRecord {
+    id: string;
+    workflowId: string;
+    status: ExecutionStatus;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    outputs?: Record<string, unknown>;
+    /** Detailed final state of every node (only when
+     *  `execution.includeNodeOutputs` was set to true). */
+    nodeOutputs?: Record<string, unknown>;
+    error?: {
+        message: string;
+        nodeId?: string;
+        nodeLabel?: string;
+    };
+    nodeErrors?: Array<{
+        nodeId: string;
+        nodeLabel?: string;
+        message: string;
+    }>;
+    /** AI Credit + cloud-minute + proxy-MB + CAPTCHA consumption. */
+    usage?: {
+        aiCredits?: number;
+        cloudBrowserMinutes?: number;
+        proxyDataMB?: number;
+        captchaSolves?: number;
+        connectHubCalls?: number;
+    };
+}
+interface ExecutionLogEvent {
+    type: 'log' | 'progress' | 'node-start' | 'node-end' | 'error' | 'done';
+    message?: string;
+    nodeId?: string;
+    nodeLabel?: string;
+    timestamp: string;
+    level?: 'info' | 'warn' | 'error' | 'debug';
+    data?: unknown;
+}
+interface CreateSessionOptions {
+    /**
+     * Where the browser should actually run.
+     *  • 'cloud' (default) — Prompteryx Cloud / AWS fleet, billed in
+     *    cloud-browser minutes.
+     *  • 'local' — your own Chrome via the Prompteryx plugin + Electron
+     *    runner. ZERO cloud minutes, but requires the plugin to be
+     *    running on the SAME machine as the SDK consumer (your script
+     *    talks to localhost). Best for personal dev work where you want
+     *    a real browser but don't want to spend cloud minutes.
+     * See README "Local mode" for the prereqs.
+     */
+    target?: 'cloud' | 'local';
+    recordSession?: boolean;
+    captureDownloads?: boolean;
+    /** Storage keys for bring-your-own Chrome extensions
+     *  (.tar.gz bundles uploaded via the platform). */
+    extensions?: string[];
+    /** Route the session through a residential proxy (sent as the wire
+     *  field `proxy`). */
+    useProxy?: boolean;
+    /** Proxy exit country (sent as the wire field `country`, e.g. 'us'). */
+    proxyLocation?: ProxyLocation;
+    /** Auto-close the session after this many minutes. */
+    sessionTimeoutMinutes?: number;
+    /**
+     * Reuse a named cloud profile (preserves cookies + storage state
+     * across sessions). OPTIONAL — when omitted the session is
+     * ephemeral: nothing is loaded at start, nothing is saved at close,
+     * which is usually what you want for one-off automations. Naming a
+     * profile implicitly opts in to persistence — you don't need to set
+     * `persistContext` as well.
+     */
+    profileId?: string;
+    /**
+     * Explicit persistence opt-in WITHOUT naming a profile. Uses the
+     * account's Default profile. Most users should leave this alone and
+     * either pass `profileId` (named profile) or nothing (ephemeral).
+     */
+    persistContext?: boolean;
+    /** Custom viewport. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Anything unrecognised by the SDK is forwarded as-is. */
+    passthrough?: Record<string, unknown>;
+}
+/** Response of `sessions.create` — matches POST /api/v1/cloud-browser/sessions. */
+interface CloudSession {
+    id: string;
+    /** CDP endpoint — pass to `chromium.connectOverCDP(connectUrl)`. */
+    connectUrl: string;
+    /** Watch-it-live URL (when the provider supports it). */
+    liveURL?: string | null;
+    status: 'launching' | 'active' | 'closed' | 'failed' | (string & {});
+    startedAt: string;
+    recordSession?: boolean;
+}
+/** Row returned by `sessions.list` / `sessions.get` — durable session
+ *  history, NOT a live handle (no connectUrl). */
+interface CloudSessionSummary {
+    id: string;
+    status: string;
+    provider?: string;
+    startedAt?: string;
+    endedAt?: string | null;
+    durationMs?: number | null;
+    region?: string;
+    hasRecording?: boolean;
+}
+/** Options for the one-shot `cloudBrowser.fetch` — matches
+ *  POST /api/v1/cloud-browser/fetch. */
+interface CloudFetchOptions {
+    url: string;
+    /** What to return in `content`. Default 'text' (readable text —
+     *  token-efficient for LLMs). 'links' fills `links` instead. */
+    format?: 'text' | 'markdown' | 'html' | 'links';
+    /** Navigation wait state. Default 'domcontentloaded'. */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    /** Page-load budget in ms (5000–60000, default 30000). */
+    timeoutMs?: number;
+    /** Route through a residential proxy. */
+    proxy?: boolean;
+    /** Proxy exit country (with `proxy: true`), e.g. 'us'. */
+    country?: string;
+    /** After load, wait until this CSS selector exists (JS-rendered content). */
+    waitForSelector?: string;
+    /** Extra settle time after load/selector, ms (capped at 10000). */
+    waitMs?: number;
+    /** Up to 10 CSS selectors extracted deterministically — per selector the
+     *  match count and the first 50 elements' text + outerHTML (capped). */
+    selectors?: string[];
+    /** Include a base64 JPEG of the viewport in the response. */
+    screenshot?: boolean;
+}
+/** Response of `cloudBrowser.fetch`. */
+interface CloudFetchResult {
+    url: string;
+    finalUrl: string;
+    title: string;
+    status: string;
+    /** Page content in the requested `format` (absent for format 'links'). */
+    content?: string;
+    /** Present for format 'links'. */
+    links?: Array<{
+        text: string;
+        href: string;
+    }>;
+    /** Present when `waitForSelector` was given — whether it appeared in time. */
+    waitedSelector?: boolean;
+    /** Present when `selectors` were given. */
+    extracted?: Array<{
+        selector: string;
+        count?: number;
+        elements?: Array<{
+            text: string;
+            html: string;
+        }>;
+        error?: string;
+    }>;
+    /** Present when `screenshot: true`. */
+    screenshotBase64?: string;
+}
+interface CloudSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * Every option exposed by the in-app AI Browser Agent surface, plus
+ * SDK-only hooks. Naming is `autopilot` not `agent` — autopilot
+ * implies "runs the whole task end-to-end without you", which is
+ * what this actually does.
+ */
+interface AutopilotRunOptions {
+    /** What the autopilot should accomplish, in plain English. */
+    goal: string;
+    /** Where to start. The autopilot navigates here before reasoning. */
+    startUrl?: string;
+    /** Max reasoning steps before giving up. Default 30. */
+    maxSteps?: number;
+    /** Hard cap on AI Credits this run may spend — the run stops once reached.
+     *  A cost guardrail for unattended/automated runs (pairs with maxSteps). */
+    maxCredits?: number;
+    /** Cost-saving action batching — let the model chain several safe actions per
+     *  screenshot before taking the next one (cheaper on simple same-page tasks).
+     *  Default false. */
+    costSaving?: boolean;
+    /** When `costSaving` is on: max actions the model may chain per screenshot
+     *  (2–20, default 5). Higher = cheaper on simple pages; lower = safer. */
+    costSavingMaxBatch?: number;
+    /** When `costSaving` is on: "careful batching" — take a fresh screenshot after
+     *  each submit/commit action in a batch, so the agent never types the next
+     *  record blind. Fewer skipped/duplicated rows on form loops. Default false. */
+    carefulBatching?: boolean;
+    /** AI Vision quality preset. Lower presets are cheaper and faster per step;
+     *  higher presets read small text and dense pages more accurately.
+     *  One of: 'ultra-saver' | 'low' | 'saver' | 'efficient' | 'balanced' |
+     *  'detailed' | 'enhanced' | 'precision' | 'max-precision'. */
+    aiVision?: 'ultra-saver' | 'low' | 'saver' | 'efficient' | 'balanced' | 'detailed' | 'enhanced' | 'precision' | 'max-precision' | (string & {});
+    /** Final-step quality boost: one extra look at the finished page at this
+     *  preset right before the answer is written — sharper reads of prices,
+     *  dates and small text for one screenshot's extra cost.
+     *  'same' (default) = off. */
+    finalStepVision?: 'same' | 'ultra-saver' | 'low' | 'saver' | 'efficient' | 'balanced' | 'detailed' | 'enhanced' | 'precision' | 'max-precision' | (string & {});
+    /** Structured output: a JSON Schema object for the final answer. When set,
+     *  `finalAnswer` is JSON conforming to this schema (the server also accepts
+     *  the snake_case `output_schema` spelling via passthrough). */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Safety checkpoints. 'auto' (default) auto-consents past the model's safety
+     * decisions (e.g. submitting a form) — best for unattended runs. 'ask' pauses
+     * the job (status becomes terminal `awaiting_input`, with the checkpoint in
+     * `finalAnswer`) so you can review and resume it. Mirrors the settings dialog's
+     * "Auto-consent to safety checkpoints" toggle.
+     */
+    safetyConsent?: 'auto' | 'ask';
+    /**
+     * "Check unclear or risky tasks" (default ON). When on, a too-vague goal makes
+     * the agent ask a clarifying question first, and it confirms before an
+     * irreversible/costly action instead of guessing — surfacing as a terminal
+     * `awaiting_input` with the question in `finalAnswer`. Pass false to always
+     * proceed with a best guess.
+     */
+    confirmUnclear?: boolean;
+    /**
+     * Smart Context Compression (default OFF). Summarises long sessions to cut token
+     * cost (~70% on long tasks). `compressionThreshold` = compress after this many
+     * steps (default 8).
+     */
+    enableContextCompression?: boolean;
+    compressionThreshold?: number;
+    /**
+     * Fresh-session reset (default OFF) — an alternative long-task cost saver. Every
+     * N turns it starts a clean session from a verified progress summary so per-step
+     * cost stops climbing. `sessionResetThreshold` = reset every N turns (default 12).
+     */
+    enableSessionReset?: boolean;
+    sessionResetThreshold?: number;
+    /**
+     * Where the autopilot should drive the browser.
+     *  • 'cloud' (default) — cloud browser, bills cloud-browser minutes.
+     *  • 'local' (v0.3+) — YOUR local Chrome via the Prompteryx desktop app.
+     *    ZERO cloud-browser minutes; AI Credits still apply. Requirements:
+     *    the desktop app must be RUNNING and SIGNED IN on this machine, and
+     *    your code must run on the same machine (the SDK talks to the app
+     *    directly at http://localhost:61337 — override with `runnerUrl`).
+     *    The browser tab stays open after the run for inspection/follow-ups.
+     */
+    target?: 'cloud' | 'local';
+    /** Local target only: the desktop app's local address.
+     *  Default 'http://localhost:61337'. */
+    runnerUrl?: string;
+    /** Which browser-agent model to use. Default: 'gemini-3.5-flash'.
+     *  The known catalog is `AUTOPILOT_MODELS` (see models.ts — mirrored from
+     *  the platform's canonical V2_BROWSER_MODELS list); any other string is
+     *  forwarded as-is for forward compatibility, but an id the server doesn't
+     *  know hard-400s with UNSUPPORTED_MODEL. */
+    model?: AutopilotModel;
+    /**
+     * Capture the discovered action sequence as a permanent workflow
+     * the user can replay forever at zero AI cost — the action-caching
+     * pattern, materialised as a first-class Visual Studio workflow
+     * (schedulable, shareable, editable, multi-option-selector
+     * resilient). The response includes `savedWorkflowId`.
+     */
+    saveAsWorkflow?: boolean;
+    /** Display name for the saved workflow. Defaults to a slug of `goal`. */
+    savedWorkflowName?: string;
+    /** Hard timeout for the whole run in ms. Default 5 minutes. */
+    timeoutMs?: number;
+    /** Run on a pre-existing cloud session. If omitted the autopilot
+     *  spins up a fresh one + closes it on completion. */
+    sessionId?: string;
+    /** Override the autopilot's system prompt. Advanced — most users
+     *  shouldn't set this. Used for niche bespoke tasks where the
+     *  default prompt loses subtlety (e.g. "always confirm before
+     *  submitting any form"). */
+    systemPromptOverride?: string;
+    /** Restrict the tools the autopilot can use. By default all of
+     *  click / type / scroll / navigate / press_key / hover / extract
+     *  are available; pass a subset to constrain behaviour (e.g.
+     *  `['click', 'extract']` for a read-only task). */
+    allowedTools?: string[];
+    /** Viewport for the cloud browser session the autopilot uses. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Per-session controls forwarded to the underlying cloud-browser
+     *  session creation. Ignored when `sessionId` is set. */
+    session?: Omit<CreateSessionOptions, 'viewport'>;
+    /**
+     * MULTI-AGENT SWARM. Run the goal across N parallel cloud agents instead of
+     * one. Default 1 (a normal single-agent run). When > 1 the response gains a
+     * `swarm` block with per-agent answers/usage, and `finalAnswer` is the merged
+     * result across all agents. Each agent still respects `maxCredits`; use
+     * `maxRunCredits` to bound the whole run.
+     */
+    agents?: number;
+    /**
+     * Swarm coordination style (only meaningful when `agents` > 1):
+     *  • false (default) — N INDEPENDENT agents, each runs the FULL `goal` in its
+     *    own browser (fastest for "do the same thing N ways / N places").
+     *  • true — COLLABORATE via a shared work-queue: the goal (or the attached
+     *    spreadsheet, one item per row) is split into work items that agents claim
+     *    atomically — none done twice, none missed, idle agents work-steal.
+     */
+    collaborate?: boolean;
+    /** Collaborate mode: a spreadsheet's TEXT (CSV / TSV / pipe table). When it looks
+     *  like a row table the shared queue is seeded ONE work item per ROW. */
+    attachmentContext?: string;
+    /** Swarm whole-run credit budget (admission control). Once the run's total AI
+     *  Credits reach this, agents stop claiming new work items and wrap up what's in
+     *  flight. 0/undefined = no cap. Distinct from per-agent `maxCredits`. */
+    maxRunCredits?: number;
+    /** Passthrough for future server-side options. */
+    passthrough?: Record<string, unknown>;
+}
+interface AutopilotStep {
+    step: number;
+    action: string;
+    reasoning?: string;
+    /** Base64 JPEG screenshot taken before the step (debugging aid). */
+    screenshot?: string;
+    result?: unknown;
+}
+interface AutopilotRunResult {
+    success: boolean;
+    /** The autopilot's final summary / answer. */
+    finalAnswer?: string;
+    steps: AutopilotStep[];
+    /** `wf_…` if `saveAsWorkflow` was true. Run it later with
+     *  `px.workflows.run(savedWorkflowId)` for zero-AI-cost replay. */
+    savedWorkflowId?: string;
+    /** AI Credit + token usage telemetry. Sums ALL agents on a swarm run. */
+    usage?: {
+        aiCredits: number;
+        tokensIn?: number;
+        tokensOut?: number;
+        /** USD cost the platform charged the user (1 credit = $0.01). */
+        costUSD?: number;
+        /** Model turns (think-and-act cycles) the run took. */
+        turns?: number;
+    };
+    /** Present only when `agents` > 1 — the multi-agent swarm detail. `finalAnswer`
+     *  above is the merged answer across every agent; this exposes each agent's own
+     *  answer/usage/session and (collaborate mode) the shared work-queue coverage. */
+    swarm?: {
+        mode: 'collaborate' | 'independent';
+        status: 'completed' | 'partial' | 'error';
+        agents: Array<{
+            idx: number;
+            title: string;
+            status: 'completed' | 'error' | 'stopped';
+            finalAnswer: string;
+            costUSD: number;
+            inTokens: number;
+            outTokens: number;
+            turns: number;
+            sessionId: string;
+            recordingUrl?: string;
+            error?: string;
+        }>;
+        /** Shared-queue coverage (collaborate mode): items total / done / failed / etc. */
+        coverage?: {
+            total: number;
+            done: number;
+            failed: number;
+            claimed: number;
+            unclaimed: number;
+        };
+    };
+}
+interface CopilotDoResult {
+    success: boolean;
+    action: string;
+    selector?: string;
+    /** True when every ranked selector failed and the AI-vision coordinate
+     *  fallback was used instead. Lets you spot pages where stable selectors
+     *  aren't resolving so you can tighten them. */
+    usedVisionFallback?: boolean;
+    durationMs: number;
+    error?: string;
+}
+interface DiscoveredAction {
+    /** Semantic intent: 'click', 'fill', 'select', 'hover'. */
+    type: string;
+    selector: string;
+    alternativeSelectors?: string[];
+    description: string;
+    /** Natural-language instruction the user would describe this with
+     *  ("click the Sign up button"). Useful for `px.copilot.do(page, a.example)`. */
+    example?: string;
+}
+interface ConnectHubAppSummary {
+    /** Pipedream slug ('gmail', 'google-sheets', ...). */
+    slug: string;
+    name: string;
+    iconUrl?: string;
+    /** Categories the app belongs to. */
+    categories?: string[];
+}
+interface ConnectHubActionSummary {
+    app: string;
+    /** Action key ('send_message', 'create_row', etc.). */
+    action: string;
+    name: string;
+    description?: string;
+    /** Parameter spec — the schema the user must satisfy in `params`. */
+    parameters?: Record<string, unknown>;
+}
+interface RunConnectHubActionOptions {
+    app: string;
+    action: string;
+    /** Action parameters. Shape depends on the action — call
+     *  `px.connectHub.getAction(app, action)` to fetch the schema. */
+    params: Record<string, unknown>;
+    /** Optional credential id if the user has multiple accounts of the
+     *  same app connected. Defaults to the most recently used. */
+    credentialId?: string;
+}
+interface CustomNodeSummary {
+    id: string;
+    name: string;
+    description?: string;
+    /** 'http' (one external call) or 'expression' (data transform) or
+     *  'composition' (sub-workflow). */
+    kind: 'http' | 'expression' | 'composition';
+    /** Input schema the node accepts. */
+    inputSchema?: Record<string, unknown>;
+    /** Output schema the node returns. */
+    outputSchema?: Record<string, unknown>;
+}
+interface ScheduleSummary {
+    id: string;
+    workflowId: string;
+    workflowName?: string;
+    /** Cron expression in the schedule's timezone. */
+    cronExpression: string;
+    timezone: string;
+    active: boolean;
+    nextRun?: string;
+    lastRun?: string;
+    createdAt: string;
+}
+interface CreateScheduleOptions {
+    workflowId: string;
+    cronExpression: string;
+    /** IANA timezone ('America/New_York'). */
+    timezone?: string;
+    /** Initial state. Default true. */
+    active?: boolean;
+    /** Override the workflow's saved execution options for scheduled
+     *  runs. */
+    execution?: WorkflowExecutionOptions;
+    /** Input variables passed every scheduled run. */
+    input?: Record<string, unknown>;
+}
+interface TemplateSummary {
+    id: string;
+    name: string;
+    description?: string;
+    categories?: string[];
+    /** Author of the template (the platform team or another user). */
+    author?: string;
+    /** Indicative complexity. */
+    nodeCount?: number;
+}
+interface ProfileSummary {
+    id: string;
+    name: string;
+    /** 'cloud' = persistent cloud profile; 'local' = Chrome profile
+     *  on the user's machine (requires the Prompteryx plugin). */
+    kind: 'cloud' | 'local';
+    /** Cookies / storage size. */
+    sizeBytes?: number;
+    lastUsedAt?: string;
+}
+interface SubscriptionStatus {
+    tier: 'free' | 'starter' | 'developer' | 'pro' | 'enterprise' | (string & {});
+    renewedAt?: string;
+    /** Plan-included balances. */
+    balances: {
+        aiCredits: {
+            remaining: number;
+            included: number;
+        };
+        cloudBrowserMinutes: {
+            remaining: number;
+            included: number;
+        };
+        proxyDataMB: {
+            remaining: number;
+            included: number;
+        };
+        captchaSolves: {
+            remaining: number;
+            included: number;
+        };
+        connectHubCalls: {
+            remaining: number;
+            included: number;
+        };
+        monthlyExecutions: {
+            remaining: number;
+            included: number;
+        };
+    };
+    /** Top-up balances (don't reset monthly). */
+    topUpBalances: {
+        aiCredits: number;
+        cloudBrowserMinutes: number;
+        proxyDataMB: number;
+        captchaSolves: number;
+        connectHubCalls: number;
+    };
+}
+interface SessionRecording {
+    sessionId: string;
+    startedAt: string;
+    endedAt?: string;
+    url: string;
+    durationMs?: number;
+    sizeBytes?: number;
+}
+interface ApiKeySummary {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    expiresAt?: string;
+    status: 'active' | 'expired' | 'revoked';
+    usageCount: number;
+}
+interface PrompteryxClientOptions {
+    /** Platform API key (`px_live_…`) — sent as `Authorization: Bearer`.
+     *  Rate limits: 60 requests/minute, 10,000/day. */
+    apiKey: string;
+    /**
+     * Cloud Browser API key (`pcb_live_…`) — a SEPARATE key family, created
+     * under Cloud Platform → API Keys. Required for `px.cloudBrowser.*`
+     * (sessions / fetch / search), which authenticates with `x-api-key`
+     * rather than the platform Bearer key. Calls to `px.cloudBrowser.*`
+     * throw an AuthError explaining this when it's absent.
+     */
+    cloudBrowserKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    defaultHeaders?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+
+/**
+ * HTTP client for the Prompteryx SDK.
+ *
+ * Thin layer over `fetch` that adds:
+ *   - Bearer auth from the configured API key
+ *   - JSON serialisation + content-type
+ *   - Status-to-typed-error mapping (see errors.ts)
+ *   - Configurable timeout via AbortController
+ *   - Bounded retry for idempotent ops on 5xx / network errors
+ *   - Optional SSE streaming for execution logs / agent traces
+ *
+ * Anything that needs raw `Response` (e.g. downloading a recording
+ * binary) can use `rawRequest()`. Everything else should use
+ * `request<T>()` which returns the parsed JSON body typed as T.
+ */
+
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    /** Object that will be JSON.stringified into the body. Skip for GET/DELETE. */
+    body?: unknown;
+    /** Extra headers merged into the defaults. */
+    headers?: Record<string, string>;
+    /** Override the client default timeout for this single call. */
+    timeoutMs?: number;
+    /** Whether this op is safe to retry on transient failure. Defaults
+     *  based on method: GET = yes, others = no. The caller can force
+     *  retry for idempotent POSTs (e.g. a poll loop). */
+    retry?: boolean;
+    /** Query string params (URI-encoded automatically). */
+    query?: Record<string, string | number | boolean | undefined | null>;
+    /** Optional AbortSignal for caller-side cancellation. */
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    /** Optional Cloud Browser key (`pcb_live_…`) — a separate key family used
+     *  only by the /api/v1/cloud-browser/* endpoints (sent as `x-api-key`). */
+    readonly cloudBrowserKey?: string;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly defaultHeaders;
+    private readonly fetchImpl;
+    constructor(opts: PrompteryxClientOptions);
+    /** Returns the JSON-parsed body typed as T. Throws typed errors on non-2xx. */
+    request<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
+    /** Returns the raw Response. Throws typed errors on non-2xx, but does
+     *  not attempt to read the body. Useful for downloading binaries. */
+    rawRequest(path: string, opts?: RequestOptions): Promise<Response>;
+    /**
+     * Stream a Server-Sent Events response line-by-line as JSON-parsed
+     * payloads. Yields each event's `data:` payload parsed as JSON. The
+     * caller is responsible for breaking the loop / cancelling the
+     * AbortSignal when done.
+     */
+    streamSse<T = unknown>(path: string, opts?: RequestOptions): AsyncGenerator<T, void, void>;
+    private sendOnce;
+    private buildUrl;
+    private errorFromResponse;
+    private wrapTransport;
+    private isRetryable;
+    private backoff;
+}
+
+/**
+ * Copilot primitives — `do`, `read`, `scan` — operating on a Playwright
+ * page.
+ *
+ * Two namespaces in the Prompteryx SDK:
+ *   • Copilot  → SDK helps with ONE step you describe in plain English.
+ *                Your code drives Playwright; copilot just figures out
+ *                which selector to click / what data to pull / what's
+ *                discoverable on the current page.
+ *   • Autopilot → SDK runs an autonomous multi-step task with no per-
+ *                 action involvement from you. See ./resources/autopilot.ts.
+ *
+ * The copilot primitives:
+ *   • `do(page, instruction)` — execute a single natural-language
+ *     action ("click the Sign up button", "fill the email field with
+ *     hello@example.com"). Returns a structured result describing
+ *     what was done.
+ *   • `read(page, schema)` — pull typed data from the page. Pass a
+ *     Zod schema or a raw JSON Schema; the SDK returns the populated
+ *     object validated against your schema.
+ *   • `scan(page, hint?)` — list discoverable actions on the page.
+ *     Useful as a pre-step to `do()` for resilient automations:
+ *     scan → pick the action whose description matches your intent →
+ *     do() against it.
+ *
+ * Architecturally the SDK never drives the browser server-side. The
+ * server returns a structured plan and the SDK executes it locally
+ * against your Playwright page, so your trace, debugger, and any
+ * custom event handlers continue to work normally.
+ */
+
+/** Minimal Page surface — anything satisfying this works (Playwright's
+ *  Page does, by structural typing, without an explicit import). */
+interface PageLike {
+    url(): string;
+    title(): Promise<string>;
+    screenshot(opts?: {
+        type?: 'png' | 'jpeg';
+        quality?: number;
+        fullPage?: boolean;
+    }): Promise<Buffer | Uint8Array>;
+    evaluate<T>(fn: (...args: unknown[]) => T): Promise<T>;
+    click(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    fill(selector: string, value: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    selectOption(selector: string, value: string | string[], opts?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    goto(url: string, opts?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    hover(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    keyboard: {
+        press(key: string): Promise<void>;
+        type(text: string, opts?: {
+            delay?: number;
+        }): Promise<void>;
+    };
+    mouse?: {
+        click(x: number, y: number): Promise<void>;
+        move?(x: number, y: number): Promise<void>;
+    };
+    viewportSize?(): {
+        width: number;
+        height: number;
+    } | null;
+    locator(selector: string): {
+        first(): {
+            isVisible(opts?: {
+                timeout?: number;
+            }): Promise<boolean>;
+            textContent(opts?: {
+                timeout?: number;
+            }): Promise<string | null>;
+        };
+    };
+}
+interface ZodLikeSchema<T> {
+    parse(input: unknown): T;
+    _def?: unknown;
+}
+declare class CopilotHelpers {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Execute a single natural-language action against the page.
+     *
+     * ```ts
+     * await px.copilot.do(page, 'click the Sign up button')
+     * await px.copilot.do(page, 'fill the email field with hello@example.com')
+     * ```
+     *
+     * Internally: snapshot the page → POST `/api/v1/copilot/do` → server
+     * returns a structured action plan (ranked selector + alternatives +
+     * value + a normalised vision point) → SDK executes locally, trying the
+     * ranked selectors in order, and ONLY if every selector fails, falling
+     * back to an AI-vision coordinate click. Costs 1 AI Credit per call.
+     *
+     * This is the key resilience advantage over a pure-LLM `act()`: the cheap,
+     * deterministic ranked selectors are tried first (no flakiness, no re-asking
+     * the model); the vision fallback is a safety net, not the default path. Pass
+     * `{ visionFallback: false }` to disable the fallback (selectors-only).
+     */
+    do(page: PageLike, instruction: string, opts?: {
+        timeout?: number;
+        visionFallback?: boolean;
+    }): Promise<CopilotDoResult>;
+    /**
+     * Pull typed structured data from the page conforming to a schema.
+     *
+     * ```ts
+     * import { z } from 'zod'
+     * const product = await px.copilot.read(page, z.object({
+     *   name: z.string(),
+     *   pricePerMonth: z.number(),
+     *   features: z.array(z.string()),
+     * }))
+     * // product is fully typed; ValidationError is thrown if the model
+     * // returns data that doesn't match the schema.
+     * ```
+     *
+     * Accepts a Zod schema (preferred — gives you compile-time types)
+     * OR a raw JSON Schema via `{ jsonSchema: ... }` if you don't want
+     * a `zod` peer dep.
+     */
+    read<T>(page: PageLike, schema: ZodLikeSchema<T> | {
+        jsonSchema: unknown;
+    }): Promise<T>;
+    /**
+     * Scan the page for available actions. Returns a ranked list of
+     * actions a user / agent could take next, with selectors + multi-
+     * option fallbacks + human-readable descriptions.
+     *
+     * Useful as a pre-step to `do()` for resilient automations:
+     *   const actions = await px.copilot.scan(page, 'sign up flow')
+     *   const target = actions.find(a => a.description.includes('Sign up'))
+     *   if (target) await px.copilot.do(page, target.example ?? `click ${target.description}`)
+     */
+    scan(page: PageLike, hint?: string): Promise<DiscoveredAction[]>;
+    private snapshotPage;
+    /** Execute the plan. Returns true if the AI-vision fallback was used. */
+    private runAction;
+    private zodToJsonSchema;
+}
+
+export { type AutopilotRunOptions as A, type Region as B, type CreateSessionOptions as C, type DiscoveredAction as D, type ExecutionRecord as E, type RunConnectHubActionOptions as F, type SessionRecording as G, HttpClient as H, type WorkflowExecutionOptions as I, type ProfileSummary as P, type RunWorkflowOptions as R, type ScheduleSummary as S, type TemplateSummary as T, type WorkflowSummary as W, type AutopilotRunResult as a, type AutopilotStep as b, type CloudSession as c, type CloudSessionSummary as d, type CloudFetchOptions as e, type CloudFetchResult as f, type CloudSearchResult as g, type ExecutionLogEvent as h, type CreateScheduleOptions as i, type SubscriptionStatus as j, type RunWorkflowResult as k, CopilotHelpers as l, type PageLike as m, type CopilotDoResult as n, type PrompteryxClientOptions as o, AUTOPILOT_MODELS as p, type ApiKeySummary as q, type AutopilotModel as r, type AutopilotModelId as s, type ConnectHubActionSummary as t, type ConnectHubAppSummary as u, type CustomNodeSummary as v, DEFAULT_AUTOPILOT_MODEL as w, type ExecutionStatus as x, type ExecutionTarget as y, type ProxyLocation as z };