@oya-ai/browser 1.0.73 → 1.0.75

package/README.md

@@ -44,6 +44,45 @@ const answer = await browser.ask("What are the top 3 stories and their points?")
 console.log(answer);
 ```
 
+### Data pass-through: the model never sees your values
+
+```ts
+await browser.ask("Search for order {{orderNumber}} and download its invoice", {
+  data: { orderNumber: "1042" }, // typed into the page; the LLM only reads {{orderNumber}}
+});
+```
+
+### Playbooks: ask once, replay without the LLM
+
+```ts
+const pb = await browser.toPlaybook("download-invoice");
+console.log(pb.variables); // ["orderNumber"]
+console.log(pb.code);      // the same flow as Playwright
+
+// Later, on any browser. If the site changed, the agent finishes the task
+// and saves its fix as a draft ("download-invoice:draft").
+const result = await browser.play("download-invoice", { orderNumber: "2077" });
+if (result.healed) await oya.playbooks.promote("download-invoice"); // after reviewing it
+// autoHeal: false throws at the broken step instead.
+```
+
+### Submit and get called back
+
+```ts
+const run = await browser.submit({ playbook: "download-invoice" }, {
+  data: { orderNumber: "2077" },
+  onSuccess: (result) => console.log("done", result),
+  onFailure: (error) => console.error("failed", error.message),
+  // CAPTCHA or MFA it could not clear, the agent asking a question, or a replay it could not heal.
+  onHumanAttention: async (req) => {
+    console.log(req.reason, req.message, req.liveViewUrl);
+    await req.respond("done"); // or your answer, when req.reason === "agent"
+  },
+  onHealed: (result) => console.log("fix saved as", result.draft),
+});
+await run.done;
+```
+
 > **Universal Lifecycle:** If you are not using `await using`, manage lifecycle with `try / finally`:
 > ```ts
 > const browser = await oya.browser.start();

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   Browser: () => Browser,
   Oya: () => Oya,
   OyaError: () => OyaError,
+  Run: () => Run,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -185,16 +186,57 @@ var Browser = class {
     if (result.liveViewUrl) result.liveViewUrl = new URL(result.liveViewUrl, this.http.baseUrl).href;
     return result;
   }
-  /** Natural-language control, using this key's configured model. */
-  async ask(prompt) {
+  /**
+   * Natural-language control, using this key's configured model. Refer to `data`
+   * as `{{name}}` in the prompt: the agent types the placeholder, the page gets the
+   * value, and the model never sees it.
+   */
+  async ask(prompt, { data } = {}) {
     const res = await this.http.request(
       "POST",
       `/api/browsers/${this.id}/chat`,
-      { messages: [{ role: "user", content: prompt }] },
+      { messages: [{ role: "user", content: prompt }], data },
       6e5
     );
+    if (res.error) throw new OyaError(res.error, 500, res);
     return res.text;
   }
+  /**
+   * Save the last `ask()` on this browser as a named playbook. Values that came
+   * from the prompt (names, IDs, dates) become variables; `code` is the same
+   * flow as a Playwright module, to read or run yourself.
+   */
+  toPlaybook(name) {
+    return this.http.request("POST", `/api/browsers/${this.id}/playbooks`, { name }, 12e4);
+  }
+  /**
+   * Replay a playbook with no LLM in the loop. Variables left out reuse the
+   * recorded values where there are any. If a step no longer fits the page and
+   * `autoHeal` is on (the default), the agent finishes the task and its fix is
+   * saved as a draft (`healed`, `draft`); off, the step's error is thrown.
+   * Play `'<name>:draft'` to try a draft before promoting it.
+   */
+  async play(name, data = {}, { autoHeal = true } = {}) {
+    const res = await this.http.request(
+      "POST",
+      `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`,
+      { variables: data, autoHeal },
+      6e5
+    );
+    if (res.error) throw new OyaError(res.error, 500, res);
+    return res;
+  }
+  /**
+   * Start a prompt or playbook in the background and hear back through callbacks.
+   * `onHumanAttention` fires for an unsolved CAPTCHA, an unfinished MFA, the agent
+   * asking for help, or a replay the agent could not heal; the run waits (up to 30
+   * minutes) until you call `respond()`.
+   */
+  async submit(task, options = {}) {
+    const { onSuccess, onFailure, onHumanAttention, onHealed, pollMs, ...body } = options;
+    const started = await this.http.request("POST", `/api/browsers/${this.id}/runs`, { ...task, ...body });
+    return new Run(this.http, started.id, { onSuccess, onFailure, onHumanAttention, onHealed }, pollMs);
+  }
   /**
    * Watch it work: the console, opened on this browser.
    *
@@ -266,6 +308,72 @@ var Browser = class {
     await this.stop();
   }
 };
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var Run = class {
+  constructor(http, id, callbacks, pollMs = 2e3) {
+    this.http = http;
+    this.id = id;
+    this.done = this.watch(callbacks, pollMs);
+    this.done.catch(() => {
+    });
+  }
+  http;
+  id;
+  done;
+  status() {
+    return this.http.request("GET", `/api/runs/${encodeURIComponent(this.id)}`);
+  }
+  /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+  async respond(response = "done") {
+    await this.http.request("POST", `/api/runs/${encodeURIComponent(this.id)}/respond`, { response });
+  }
+  async watch(cb, pollMs) {
+    const call = async (fn) => {
+      try {
+        await fn();
+      } catch (err) {
+        console.error("[oya] run callback threw:", err);
+      }
+    };
+    let seen;
+    for (let errors = 0; ; ) {
+      let run;
+      try {
+        run = await this.status();
+        errors = 0;
+      } catch (err) {
+        if (++errors < 5) {
+          await sleep(pollMs);
+          continue;
+        }
+        const failure = err instanceof OyaError ? err : new OyaError(String(err), 0, null);
+        await call(() => cb.onFailure?.(failure));
+        throw failure;
+      }
+      if (run.status === "needs_attention" && run.attention && run.attention.id !== seen) {
+        seen = run.attention.id;
+        const request = {
+          ...run.attention,
+          liveViewUrl: run.attention.liveViewUrl && new URL(run.attention.liveViewUrl, this.http.baseUrl).href,
+          respond: (response) => this.respond(response)
+        };
+        void call(() => cb.onHumanAttention?.(request));
+      }
+      if (run.status === "succeeded") {
+        const result = run.result || {};
+        if (result.healed) await call(() => cb.onHealed?.(result));
+        await call(() => cb.onSuccess?.(result));
+        return result;
+      }
+      if (run.status === "failed") {
+        const failure = new OyaError(run.error || "Run failed", 500, run);
+        await call(() => cb.onFailure?.(failure));
+        throw failure;
+      }
+      await sleep(pollMs);
+    }
+  }
+};
 
 // src/index.ts
 var DEFAULT_BASE_URL = "https://browser.getoya.ai";
@@ -342,6 +450,16 @@ var Oya = class {
     removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
     replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
   };
+  /** Playbooks saved with `browser.toPlaybook()`. */
+  playbooks = {
+    list: async () => (await this.http.request("GET", "/api/playbooks")).playbooks,
+    /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
+    remove: async (name) => {
+      await this.http.request("DELETE", `/api/playbooks/${encodeURIComponent(name)}`);
+    },
+    /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
+    promote: (name) => this.http.request("POST", `/api/playbooks/${encodeURIComponent(name)}/promote`, {})
+  };
   /**
    * Proxy exits for your personas. A persona takes one at first connect (by its
    * geo hint) or by `personas.pinProxy`, and keeps it.
@@ -413,5 +531,6 @@ var index_default = Oya;
 0 && (module.exports = {
   Browser,
   Oya,
-  OyaError
+  OyaError,
+  Run
 });

package/dist/index.d.cts

@@ -54,6 +54,74 @@ interface StartResult {
     cdpUrl?: string;
     note?: string;
 }
+interface Playbook {
+    name: string;
+    /** Inputs `play()` accepts; any left out reuse the recorded value. */
+    variables: string[];
+    steps: number;
+    /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
+    code: string;
+}
+interface PlayResult {
+    /** Steps replayed before finishing or handing over to the agent. */
+    steps: number;
+    total: number;
+    /** A step no longer fit the page and the agent finished the task. */
+    fellBack: boolean;
+    /** The agent's fix was saved as `draft`; promote it with `oya.playbooks.promote(name)`. */
+    healed?: boolean;
+    draft?: string;
+    /** The agent's summary, when it fell back. */
+    text?: string;
+}
+interface PlaybookSummary extends Playbook {
+    createdAt: string | null;
+    promotedAt: string | null;
+    /** A healed replay's fix, waiting for `promote()` or `remove('<name>:draft')`. */
+    draft: (Playbook & {
+        healedAt: string;
+        healedFrom: number;
+    }) | null;
+}
+/** Values passed through to the page as `{{name}}` placeholders; the model never sees them. */
+type RunData = Record<string, string | number>;
+interface AttentionRequest {
+    id: string;
+    /** captcha / mfa: finish it in the live view. agent: the agent's question. heal_failed: replay and the agent both gave up. */
+    reason: 'captcha' | 'mfa' | 'agent' | 'heal_failed';
+    message: string;
+    liveViewUrl?: string;
+    at: number;
+}
+type RunResult = Partial<PlayResult> & {
+    text?: string;
+};
+interface RunInfo {
+    id: string;
+    browserId: string;
+    status: 'running' | 'needs_attention' | 'succeeded' | 'failed';
+    createdAt: number;
+    endedAt?: number;
+    attention: AttentionRequest | null;
+    result?: RunResult;
+    error?: string;
+}
+interface SubmitOptions {
+    /** Passed through as `{{name}}` placeholders; for a playbook, its variables. */
+    data?: RunData;
+    /** Playbooks only: let the agent finish a broken replay and save its fix as a draft. Default true. */
+    autoHeal?: boolean;
+    onSuccess?: (result: RunResult) => unknown;
+    onFailure?: (error: OyaError) => unknown;
+    /** Call `respond()` once it is handled: `'done'` after finishing by hand, or your answer to the agent. */
+    onHumanAttention?: (request: AttentionRequest & {
+        respond(response?: string): Promise<void>;
+    }) => unknown;
+    /** Fires before onSuccess when a replay was healed; `result.draft` names the draft. */
+    onHealed?: (result: RunResult) => unknown;
+    /** How often to check on the run. Default 2000. */
+    pollMs?: number;
+}
 interface Element {
     id: number;
     type: string;
@@ -357,8 +425,41 @@ declare class Browser {
      * answer it, `liveViewUrl` is where a person finishes by hand.
      */
     completeMfa(): Promise<MfaResult>;
-    /** Natural-language control, using this key's configured model. */
-    ask(prompt: string): Promise<string>;
+    /**
+     * Natural-language control, using this key's configured model. Refer to `data`
+     * as `{{name}}` in the prompt: the agent types the placeholder, the page gets the
+     * value, and the model never sees it.
+     */
+    ask(prompt: string, { data }?: {
+        data?: RunData;
+    }): Promise<string>;
+    /**
+     * Save the last `ask()` on this browser as a named playbook. Values that came
+     * from the prompt (names, IDs, dates) become variables; `code` is the same
+     * flow as a Playwright module, to read or run yourself.
+     */
+    toPlaybook(name: string): Promise<Playbook>;
+    /**
+     * Replay a playbook with no LLM in the loop. Variables left out reuse the
+     * recorded values where there are any. If a step no longer fits the page and
+     * `autoHeal` is on (the default), the agent finishes the task and its fix is
+     * saved as a draft (`healed`, `draft`); off, the step's error is thrown.
+     * Play `'<name>:draft'` to try a draft before promoting it.
+     */
+    play(name: string, data?: RunData, { autoHeal }?: {
+        autoHeal?: boolean;
+    }): Promise<PlayResult>;
+    /**
+     * Start a prompt or playbook in the background and hear back through callbacks.
+     * `onHumanAttention` fires for an unsolved CAPTCHA, an unfinished MFA, the agent
+     * asking for help, or a replay the agent could not heal; the run waits (up to 30
+     * minutes) until you call `respond()`.
+     */
+    submit(task: {
+        prompt: string;
+    } | {
+        playbook: string;
+    }, options?: SubmitOptions): Promise<Run>;
     /**
      * Watch it work: the console, opened on this browser.
      *
@@ -411,6 +512,18 @@ declare class Browser {
     /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
     close(): Promise<void>;
 }
+type RunCallbacks = Pick<SubmitOptions, 'onSuccess' | 'onFailure' | 'onHumanAttention' | 'onHealed'>;
+/** A submitted task. Callbacks fire as it changes; `done` settles when it ends. */
+declare class Run {
+    private readonly http;
+    readonly id: string;
+    readonly done: Promise<RunResult>;
+    constructor(http: Http, id: string, callbacks: RunCallbacks, pollMs?: number);
+    status(): Promise<RunInfo>;
+    /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+    respond(response?: string): Promise<void>;
+    private watch;
+}
 
 /**
  * @oya-ai/browser — thousands of browsers, one API.
@@ -496,6 +609,14 @@ declare class Oya {
             ok: boolean;
         }>;
     };
+    /** Playbooks saved with `browser.toPlaybook()`. */
+    readonly playbooks: {
+        list: () => Promise<PlaybookSummary[]>;
+        /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
+        remove: (name: string) => Promise<void>;
+        /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
+        promote: (name: string) => Promise<Playbook>;
+    };
     /**
      * Proxy exits for your personas. A persona takes one at first connect (by its
      * geo hint) or by `personas.pinProxy`, and keeps it.
@@ -624,4 +745,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type StartOptions, type StartResult, type StopResult, Oya as default };
+export { type Activity, type Analysis, type AttentionRequest, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, Run, type RunData, type RunInfo, type RunResult, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default };

package/dist/index.d.ts

@@ -54,6 +54,74 @@ interface StartResult {
     cdpUrl?: string;
     note?: string;
 }
+interface Playbook {
+    name: string;
+    /** Inputs `play()` accepts; any left out reuse the recorded value. */
+    variables: string[];
+    steps: number;
+    /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
+    code: string;
+}
+interface PlayResult {
+    /** Steps replayed before finishing or handing over to the agent. */
+    steps: number;
+    total: number;
+    /** A step no longer fit the page and the agent finished the task. */
+    fellBack: boolean;
+    /** The agent's fix was saved as `draft`; promote it with `oya.playbooks.promote(name)`. */
+    healed?: boolean;
+    draft?: string;
+    /** The agent's summary, when it fell back. */
+    text?: string;
+}
+interface PlaybookSummary extends Playbook {
+    createdAt: string | null;
+    promotedAt: string | null;
+    /** A healed replay's fix, waiting for `promote()` or `remove('<name>:draft')`. */
+    draft: (Playbook & {
+        healedAt: string;
+        healedFrom: number;
+    }) | null;
+}
+/** Values passed through to the page as `{{name}}` placeholders; the model never sees them. */
+type RunData = Record<string, string | number>;
+interface AttentionRequest {
+    id: string;
+    /** captcha / mfa: finish it in the live view. agent: the agent's question. heal_failed: replay and the agent both gave up. */
+    reason: 'captcha' | 'mfa' | 'agent' | 'heal_failed';
+    message: string;
+    liveViewUrl?: string;
+    at: number;
+}
+type RunResult = Partial<PlayResult> & {
+    text?: string;
+};
+interface RunInfo {
+    id: string;
+    browserId: string;
+    status: 'running' | 'needs_attention' | 'succeeded' | 'failed';
+    createdAt: number;
+    endedAt?: number;
+    attention: AttentionRequest | null;
+    result?: RunResult;
+    error?: string;
+}
+interface SubmitOptions {
+    /** Passed through as `{{name}}` placeholders; for a playbook, its variables. */
+    data?: RunData;
+    /** Playbooks only: let the agent finish a broken replay and save its fix as a draft. Default true. */
+    autoHeal?: boolean;
+    onSuccess?: (result: RunResult) => unknown;
+    onFailure?: (error: OyaError) => unknown;
+    /** Call `respond()` once it is handled: `'done'` after finishing by hand, or your answer to the agent. */
+    onHumanAttention?: (request: AttentionRequest & {
+        respond(response?: string): Promise<void>;
+    }) => unknown;
+    /** Fires before onSuccess when a replay was healed; `result.draft` names the draft. */
+    onHealed?: (result: RunResult) => unknown;
+    /** How often to check on the run. Default 2000. */
+    pollMs?: number;
+}
 interface Element {
     id: number;
     type: string;
@@ -357,8 +425,41 @@ declare class Browser {
      * answer it, `liveViewUrl` is where a person finishes by hand.
      */
     completeMfa(): Promise<MfaResult>;
-    /** Natural-language control, using this key's configured model. */
-    ask(prompt: string): Promise<string>;
+    /**
+     * Natural-language control, using this key's configured model. Refer to `data`
+     * as `{{name}}` in the prompt: the agent types the placeholder, the page gets the
+     * value, and the model never sees it.
+     */
+    ask(prompt: string, { data }?: {
+        data?: RunData;
+    }): Promise<string>;
+    /**
+     * Save the last `ask()` on this browser as a named playbook. Values that came
+     * from the prompt (names, IDs, dates) become variables; `code` is the same
+     * flow as a Playwright module, to read or run yourself.
+     */
+    toPlaybook(name: string): Promise<Playbook>;
+    /**
+     * Replay a playbook with no LLM in the loop. Variables left out reuse the
+     * recorded values where there are any. If a step no longer fits the page and
+     * `autoHeal` is on (the default), the agent finishes the task and its fix is
+     * saved as a draft (`healed`, `draft`); off, the step's error is thrown.
+     * Play `'<name>:draft'` to try a draft before promoting it.
+     */
+    play(name: string, data?: RunData, { autoHeal }?: {
+        autoHeal?: boolean;
+    }): Promise<PlayResult>;
+    /**
+     * Start a prompt or playbook in the background and hear back through callbacks.
+     * `onHumanAttention` fires for an unsolved CAPTCHA, an unfinished MFA, the agent
+     * asking for help, or a replay the agent could not heal; the run waits (up to 30
+     * minutes) until you call `respond()`.
+     */
+    submit(task: {
+        prompt: string;
+    } | {
+        playbook: string;
+    }, options?: SubmitOptions): Promise<Run>;
     /**
      * Watch it work: the console, opened on this browser.
      *
@@ -411,6 +512,18 @@ declare class Browser {
     /** @deprecated use stop() — close() only dropped the socket, and a cloud browser redialled. */
     close(): Promise<void>;
 }
+type RunCallbacks = Pick<SubmitOptions, 'onSuccess' | 'onFailure' | 'onHumanAttention' | 'onHealed'>;
+/** A submitted task. Callbacks fire as it changes; `done` settles when it ends. */
+declare class Run {
+    private readonly http;
+    readonly id: string;
+    readonly done: Promise<RunResult>;
+    constructor(http: Http, id: string, callbacks: RunCallbacks, pollMs?: number);
+    status(): Promise<RunInfo>;
+    /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+    respond(response?: string): Promise<void>;
+    private watch;
+}
 
 /**
  * @oya-ai/browser — thousands of browsers, one API.
@@ -496,6 +609,14 @@ declare class Oya {
             ok: boolean;
         }>;
     };
+    /** Playbooks saved with `browser.toPlaybook()`. */
+    readonly playbooks: {
+        list: () => Promise<PlaybookSummary[]>;
+        /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
+        remove: (name: string) => Promise<void>;
+        /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
+        promote: (name: string) => Promise<Playbook>;
+    };
     /**
      * Proxy exits for your personas. A persona takes one at first connect (by its
      * geo hint) or by `personas.pinProxy`, and keeps it.
@@ -624,4 +745,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type StartOptions, type StartResult, type StopResult, Oya as default };
+export { type Activity, type Analysis, type AttentionRequest, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Element, type Fingerprint, type Health, type HumanInputAction, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, Run, type RunData, type RunInfo, type RunResult, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default };

package/dist/index.js

@@ -156,16 +156,57 @@ var Browser = class {
     if (result.liveViewUrl) result.liveViewUrl = new URL(result.liveViewUrl, this.http.baseUrl).href;
     return result;
   }
-  /** Natural-language control, using this key's configured model. */
-  async ask(prompt) {
+  /**
+   * Natural-language control, using this key's configured model. Refer to `data`
+   * as `{{name}}` in the prompt: the agent types the placeholder, the page gets the
+   * value, and the model never sees it.
+   */
+  async ask(prompt, { data } = {}) {
     const res = await this.http.request(
       "POST",
       `/api/browsers/${this.id}/chat`,
-      { messages: [{ role: "user", content: prompt }] },
+      { messages: [{ role: "user", content: prompt }], data },
       6e5
     );
+    if (res.error) throw new OyaError(res.error, 500, res);
     return res.text;
   }
+  /**
+   * Save the last `ask()` on this browser as a named playbook. Values that came
+   * from the prompt (names, IDs, dates) become variables; `code` is the same
+   * flow as a Playwright module, to read or run yourself.
+   */
+  toPlaybook(name) {
+    return this.http.request("POST", `/api/browsers/${this.id}/playbooks`, { name }, 12e4);
+  }
+  /**
+   * Replay a playbook with no LLM in the loop. Variables left out reuse the
+   * recorded values where there are any. If a step no longer fits the page and
+   * `autoHeal` is on (the default), the agent finishes the task and its fix is
+   * saved as a draft (`healed`, `draft`); off, the step's error is thrown.
+   * Play `'<name>:draft'` to try a draft before promoting it.
+   */
+  async play(name, data = {}, { autoHeal = true } = {}) {
+    const res = await this.http.request(
+      "POST",
+      `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`,
+      { variables: data, autoHeal },
+      6e5
+    );
+    if (res.error) throw new OyaError(res.error, 500, res);
+    return res;
+  }
+  /**
+   * Start a prompt or playbook in the background and hear back through callbacks.
+   * `onHumanAttention` fires for an unsolved CAPTCHA, an unfinished MFA, the agent
+   * asking for help, or a replay the agent could not heal; the run waits (up to 30
+   * minutes) until you call `respond()`.
+   */
+  async submit(task, options = {}) {
+    const { onSuccess, onFailure, onHumanAttention, onHealed, pollMs, ...body } = options;
+    const started = await this.http.request("POST", `/api/browsers/${this.id}/runs`, { ...task, ...body });
+    return new Run(this.http, started.id, { onSuccess, onFailure, onHumanAttention, onHealed }, pollMs);
+  }
   /**
    * Watch it work: the console, opened on this browser.
    *
@@ -237,6 +278,72 @@ var Browser = class {
     await this.stop();
   }
 };
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var Run = class {
+  constructor(http, id, callbacks, pollMs = 2e3) {
+    this.http = http;
+    this.id = id;
+    this.done = this.watch(callbacks, pollMs);
+    this.done.catch(() => {
+    });
+  }
+  http;
+  id;
+  done;
+  status() {
+    return this.http.request("GET", `/api/runs/${encodeURIComponent(this.id)}`);
+  }
+  /** Answer the open attention request: `'done'` after handling it by hand, or your reply to the agent. */
+  async respond(response = "done") {
+    await this.http.request("POST", `/api/runs/${encodeURIComponent(this.id)}/respond`, { response });
+  }
+  async watch(cb, pollMs) {
+    const call = async (fn) => {
+      try {
+        await fn();
+      } catch (err) {
+        console.error("[oya] run callback threw:", err);
+      }
+    };
+    let seen;
+    for (let errors = 0; ; ) {
+      let run;
+      try {
+        run = await this.status();
+        errors = 0;
+      } catch (err) {
+        if (++errors < 5) {
+          await sleep(pollMs);
+          continue;
+        }
+        const failure = err instanceof OyaError ? err : new OyaError(String(err), 0, null);
+        await call(() => cb.onFailure?.(failure));
+        throw failure;
+      }
+      if (run.status === "needs_attention" && run.attention && run.attention.id !== seen) {
+        seen = run.attention.id;
+        const request = {
+          ...run.attention,
+          liveViewUrl: run.attention.liveViewUrl && new URL(run.attention.liveViewUrl, this.http.baseUrl).href,
+          respond: (response) => this.respond(response)
+        };
+        void call(() => cb.onHumanAttention?.(request));
+      }
+      if (run.status === "succeeded") {
+        const result = run.result || {};
+        if (result.healed) await call(() => cb.onHealed?.(result));
+        await call(() => cb.onSuccess?.(result));
+        return result;
+      }
+      if (run.status === "failed") {
+        const failure = new OyaError(run.error || "Run failed", 500, run);
+        await call(() => cb.onFailure?.(failure));
+        throw failure;
+      }
+      await sleep(pollMs);
+    }
+  }
+};
 
 // src/index.ts
 var DEFAULT_BASE_URL = "https://browser.getoya.ai";
@@ -313,6 +420,16 @@ var Oya = class {
     removeWebhook: (id) => this.http.request("DELETE", `/api/control/webhooks/${encodeURIComponent(id)}`),
     replayDelivery: (id) => this.http.request("POST", `/api/control/deliveries/${encodeURIComponent(id)}/replay`, {})
   };
+  /** Playbooks saved with `browser.toPlaybook()`. */
+  playbooks = {
+    list: async () => (await this.http.request("GET", "/api/playbooks")).playbooks,
+    /** Delete a playbook and its draft, or only the draft with `'<name>:draft'`. */
+    remove: async (name) => {
+      await this.http.request("DELETE", `/api/playbooks/${encodeURIComponent(name)}`);
+    },
+    /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
+    promote: (name) => this.http.request("POST", `/api/playbooks/${encodeURIComponent(name)}/promote`, {})
+  };
   /**
    * Proxy exits for your personas. A persona takes one at first connect (by its
    * geo hint) or by `personas.pinProxy`, and keeps it.
@@ -384,5 +501,6 @@ export {
   Browser,
   Oya,
   OyaError,
+  Run,
   index_default as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oya-ai/browser",
-  "version": "1.0.73",
+  "version": "1.0.75",
   "description": "Rotate thousands of browsers behind one API — personas, proxies, stealth, CAPTCHA and MFA.",
   "license": "MIT",
   "homepage": "https://browser.getoya.ai",