@oya-ai/browser 1.0.130 → 1.0.131

package/README.md

@@ -122,8 +122,8 @@ try {
     ...(exists ? { data: { ...data, ...secrets } } : { data, secrets }),
     onSuccess: () => console.log('Run succeeded.'),
     onFailure: (error) => console.error('Run failed with status:', error.status),
-    onHealed: (result) => {
-      console.log('A repair draft is ready for review:', result.draft);
+    onHealed: () => {
+      console.log('A step no longer fit the page; the agent finished and fixed the playbook.');
     },
     onHumanAttention: async (request) => {
       console.log('Attention needed:', request.reason);
@@ -201,22 +201,26 @@ await browser.play('job-application', { name: 'Ada Lovelace', resume: await file
 
 The generated Playwright module calls `setInputFiles`, where the same variable is a plain path rather than a `file()` value.
 
-### Review a repaired playbook
+### When a replay heals
 
-Replay normally runs recorded steps without an LLM. With `autoHeal: true` (the default), a broken step can hand over to the agent, which saves a repair as `<name>:draft`. Promotion replaces the saved playbook with that draft.
+Replay normally runs recorded steps without an LLM. With `autoHeal: true` (the default), a broken step hands over to the agent, which finishes the task; its steps replace the broken ones in the playbook, so the next replay runs without the model again. The result says so with `healed: true`.
 
-The following continues with an active `browser` and the inputs above. Replaying a draft performs its actions, so review its code and use test inputs before promoting it.
+A replay that meets a sign-in page signs in with the profile's stored login and second factor (`oya.personas.setCredentials`, `setMfa`), returns to where the flow was, and carries on.
+
+Use `autoHeal: false` with `play()` or `submit({ playbook: name }, options)` to fail at a broken step without agent repair. `oya.playbooks.remove(name)` removes a playbook.
+
+### Free-text answers
+
+A field the agent wrote itself (a comment, the reason for a request, a question's answer), rather than copying it from your prompt, is not replayed word for word. Each replay asks your model for fresh text, from the prompt and that run's data. The playbook lists these fields in `answers`; pass a field's `key` in `data` to type fixed text instead. The Playwright export calls `oya.llm.answer(question, vars)` for them, so run it as `run(page, vars, oya)` with an `Oya` client.
+
+### Move a playbook to another environment
 
 ```js
-const saved = (await oya.playbooks.list()).find((p) => p.name === playbookName);
-if (saved?.draft) {
-  // Review saved.draft.code before executing it.
-  await browser.play(`${playbookName}:draft`, { ...data, ...secrets }, { autoHeal: false });
-  await oya.playbooks.promote(playbookName);
-}
+const doc = await oya.playbooks.export('new-request');   // JSON: steps, defaults, secret names (never values)
+await prodOya.playbooks.import(doc, { name: 'new-request', overwrite: false });
 ```
 
-Use `autoHeal: false` with `play()` or `submit({ playbook: name }, options)` to fail at a broken step without agent repair. `oya.playbooks.remove(name)` removes a playbook and its draft; `remove("<name>:draft")` removes only the draft.
+The CLI does the same with `oya playbooks export <name> --out file.json` and `oya playbooks import file.json`.
 
 ## Use your own model key
 

package/dist/index.cjs

@@ -510,9 +510,8 @@ var Browser = class {
   /**
    * 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.
+   * `autoHeal` is on (the default), the agent finishes the task and its fix
+   * replaces the broken steps in the playbook (`healed`); off, the step's error is thrown.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
     const path = `/api/browsers/${this.id}/playbooks/${segment(name, "name")}/play`;
@@ -738,7 +737,24 @@ var playbookApi = (http) => ({
     await http().request("DELETE", playbook(name));
   },
   /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {})
+  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {}),
+  ...transferApi(http)
+});
+var transferApi = (http) => ({
+  /** The playbook as one JSON document, to move it to another environment with `import()`. Secrets travel by name only. */
+  export: async (name) => http().request("GET", `${playbook(name)}/export`),
+  /**
+   * Save an exported playbook here, as `name` or the name it was exported with. A name
+   * already taken is refused unless `overwrite` is true.
+   */
+  import: async (doc, options = {}) => http().request("POST", "/api/playbooks/import", { playbook: doc, ...options })
+});
+var llmApi = (http) => ({
+  /**
+   * The text for one free-text field, written by this key's model: what an exported
+   * playbook calls as `oya.llm.answer(question, vars)` for a comment or a question's answer.
+   */
+  answer: async (question, values = {}, task) => (await http().request("POST", "/api/playbooks/answer", { question, values, task })).answer
 });
 
 // src/api/proxies.ts
@@ -1042,6 +1058,8 @@ var Oya = class {
   control = controlApi(() => this.http);
   /** Playbooks saved with `browser.toPlaybook()`. */
   playbooks = playbookApi(() => this.http);
+  /** This key's model for one-off text: `oya.llm.answer(question, vars)` fills a playbook's free-text field. */
+  llm = llmApi(() => this.http);
   /**
    * Proxy exits for your personas. A persona takes one at first connect (by its
    * geo hint) or by `personas.pinProxy`, and keeps it.

package/dist/index.d.cts

@@ -475,9 +475,36 @@ interface Playbook {
     defaults: Record<string, string>;
     /** How many steps it replays. */
     steps: number;
-    /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
+    /** Free-text fields the model writes fresh on each replay (pass the key in `play()` data to type fixed text). */
+    answers?: PlaybookAnswer[];
+    /** The same flow as a Playwright module: `export default async function run(page, vars, oya)`. */
     code: string;
 }
+/** A free-text field a replay asks the model to fill: a comment, a reason, a question's answer. */
+interface PlaybookAnswer {
+    /** The variable that overrides it with fixed text. */
+    key: string;
+    /** What the field asks, as its label says. */
+    question: string;
+}
+/** How `oya.playbooks.import()` saves an export. */
+interface ImportOptions {
+    /** The name to save it as; the name it was exported with when left out. */
+    name?: string;
+    /** Replace a playbook that already has that name. */
+    overwrite?: boolean;
+}
+/** A playbook as one JSON document, to import into another Oya environment. */
+interface PlaybookExport {
+    /** Always `'oya-playbook'`. */
+    format: 'oya-playbook';
+    /** The layout's version. */
+    version: number;
+    /** When it was exported. */
+    exportedAt: string;
+    /** The playbook: its prompt, steps, defaults and secret names (never secret values). */
+    playbook: Record<string, unknown>;
+}
 /** What a `play()` did. */
 interface PlayResult {
     /** Steps replayed before finishing or handing over to the agent. */
@@ -486,9 +513,9 @@ interface PlayResult {
     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)`. */
+    /** The agent's fix replaced the broken steps in the playbook, so the next replay runs it. */
     healed?: boolean;
-    /** The draft's name, when one was saved. */
+    /** The draft's name, from a server that saved fixes as drafts to promote by hand. */
     draft?: string;
     /** The agent's summary, when it fell back. */
     text?: string;
@@ -1381,9 +1408,8 @@ declare class Browser {
     /**
      * 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.
+     * `autoHeal` is on (the default), the agent finishes the task and its fix
+     * replaces the broken steps in the playbook (`healed`); off, the step's error is thrown.
      */
     play(name: string, data?: RunData, { autoHeal }?: PlayOptions): Promise<PlayResult>;
     /**
@@ -1502,10 +1528,16 @@ declare class Oya {
     };
     /** Playbooks saved with `browser.toPlaybook()`. */
     readonly playbooks: {
+        export: (name: string) => Promise<PlaybookExport>;
+        import: (doc: PlaybookExport, options?: ImportOptions) => Promise<Playbook>;
         list: () => Promise<PlaybookSummary[]>;
         remove: (name: string) => Promise<void>;
         promote: (name: string) => Promise<Playbook>;
     };
+    /** This key's model for one-off text: `oya.llm.answer(question, vars)` fills a playbook's free-text field. */
+    readonly llm: {
+        answer: (question: string, values?: Record<string, unknown>, task?: string) => Promise<string>;
+    };
     /**
      * Proxy exits for your personas. A persona takes one at first connect (by its
      * geo hint) or by `personas.pinProxy`, and keeps it.
@@ -1579,4 +1611,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type DesktopOptions, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmCatalogEntry, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type Signup, type SignupOptions, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };
+export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type DesktopOptions, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type ImportOptions, type LlmCatalogEntry, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookAnswer, type PlaybookExport, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type Signup, type SignupOptions, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.d.ts

@@ -475,9 +475,36 @@ interface Playbook {
     defaults: Record<string, string>;
     /** How many steps it replays. */
     steps: number;
-    /** The same flow as a Playwright module: `export default async function run(page, vars)`. */
+    /** Free-text fields the model writes fresh on each replay (pass the key in `play()` data to type fixed text). */
+    answers?: PlaybookAnswer[];
+    /** The same flow as a Playwright module: `export default async function run(page, vars, oya)`. */
     code: string;
 }
+/** A free-text field a replay asks the model to fill: a comment, a reason, a question's answer. */
+interface PlaybookAnswer {
+    /** The variable that overrides it with fixed text. */
+    key: string;
+    /** What the field asks, as its label says. */
+    question: string;
+}
+/** How `oya.playbooks.import()` saves an export. */
+interface ImportOptions {
+    /** The name to save it as; the name it was exported with when left out. */
+    name?: string;
+    /** Replace a playbook that already has that name. */
+    overwrite?: boolean;
+}
+/** A playbook as one JSON document, to import into another Oya environment. */
+interface PlaybookExport {
+    /** Always `'oya-playbook'`. */
+    format: 'oya-playbook';
+    /** The layout's version. */
+    version: number;
+    /** When it was exported. */
+    exportedAt: string;
+    /** The playbook: its prompt, steps, defaults and secret names (never secret values). */
+    playbook: Record<string, unknown>;
+}
 /** What a `play()` did. */
 interface PlayResult {
     /** Steps replayed before finishing or handing over to the agent. */
@@ -486,9 +513,9 @@ interface PlayResult {
     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)`. */
+    /** The agent's fix replaced the broken steps in the playbook, so the next replay runs it. */
     healed?: boolean;
-    /** The draft's name, when one was saved. */
+    /** The draft's name, from a server that saved fixes as drafts to promote by hand. */
     draft?: string;
     /** The agent's summary, when it fell back. */
     text?: string;
@@ -1381,9 +1408,8 @@ declare class Browser {
     /**
      * 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.
+     * `autoHeal` is on (the default), the agent finishes the task and its fix
+     * replaces the broken steps in the playbook (`healed`); off, the step's error is thrown.
      */
     play(name: string, data?: RunData, { autoHeal }?: PlayOptions): Promise<PlayResult>;
     /**
@@ -1502,10 +1528,16 @@ declare class Oya {
     };
     /** Playbooks saved with `browser.toPlaybook()`. */
     readonly playbooks: {
+        export: (name: string) => Promise<PlaybookExport>;
+        import: (doc: PlaybookExport, options?: ImportOptions) => Promise<Playbook>;
         list: () => Promise<PlaybookSummary[]>;
         remove: (name: string) => Promise<void>;
         promote: (name: string) => Promise<Playbook>;
     };
+    /** This key's model for one-off text: `oya.llm.answer(question, vars)` fills a playbook's free-text field. */
+    readonly llm: {
+        answer: (question: string, values?: Record<string, unknown>, task?: string) => Promise<string>;
+    };
     /**
      * Proxy exits for your personas. A persona takes one at first connect (by its
      * geo hint) or by `personas.pinProxy`, and keeps it.
@@ -1579,4 +1611,4 @@ declare class Oya {
     private waitUntilConnected;
 }
 
-export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type DesktopOptions, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type LlmCatalogEntry, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type Signup, type SignupOptions, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };
+export { type Activity, type Analysis, type AnalyzeOptions, type AttentionRequest, type Block, Browser, type BrowserDetail, type BrowserInfo, type CaptchaResult, type CaptchaSolver, type Config, type ConfigUpdate, type ControlCredential, type ControlEvent, type ControlOverview, type ControlRole, type ControlSession, type Cookie, type CookieFormat, type DesktopOptions, type EcsAuth, type EcsConfig, type Element, type FileValue, type Fingerprint, type Health, type HumanInputAction, type ImportOptions, type LlmCatalogEntry, type LlmProvider, MAX_FILE_BYTES, type MfaConfig, type MfaResult, Oya, OyaError, type OyaOptions, type PageFormat, type PersonaInfo, type PersonaPrefs, type PlayResult, type Playbook, type PlaybookAnswer, type PlaybookExport, type PlaybookSummary, type ProjectSettings, type Provider, type ProxyCreate, type ProxyInfo, type RecoverOptions, Run, type RunData, type RunInfo, type RunResult, type SandboxRuntime, type Signup, type SignupOptions, type SiteCredentials, type StartOptions, type StartResult, type StopResult, type SubmitOptions, Oya as default, file };

package/dist/index.js

@@ -478,9 +478,8 @@ var Browser = class {
   /**
    * 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.
+   * `autoHeal` is on (the default), the agent finishes the task and its fix
+   * replaces the broken steps in the playbook (`healed`); off, the step's error is thrown.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
     const path = `/api/browsers/${this.id}/playbooks/${segment(name, "name")}/play`;
@@ -706,7 +705,24 @@ var playbookApi = (http) => ({
     await http().request("DELETE", playbook(name));
   },
   /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {})
+  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {}),
+  ...transferApi(http)
+});
+var transferApi = (http) => ({
+  /** The playbook as one JSON document, to move it to another environment with `import()`. Secrets travel by name only. */
+  export: async (name) => http().request("GET", `${playbook(name)}/export`),
+  /**
+   * Save an exported playbook here, as `name` or the name it was exported with. A name
+   * already taken is refused unless `overwrite` is true.
+   */
+  import: async (doc, options = {}) => http().request("POST", "/api/playbooks/import", { playbook: doc, ...options })
+});
+var llmApi = (http) => ({
+  /**
+   * The text for one free-text field, written by this key's model: what an exported
+   * playbook calls as `oya.llm.answer(question, vars)` for a comment or a question's answer.
+   */
+  answer: async (question, values = {}, task) => (await http().request("POST", "/api/playbooks/answer", { question, values, task })).answer
 });
 
 // src/api/proxies.ts
@@ -1010,6 +1026,8 @@ var Oya = class {
   control = controlApi(() => this.http);
   /** Playbooks saved with `browser.toPlaybook()`. */
   playbooks = playbookApi(() => this.http);
+  /** This key's model for one-off text: `oya.llm.answer(question, vars)` fills a playbook's free-text field. */
+  llm = llmApi(() => this.http);
   /**
    * Proxy exits for your personas. A persona takes one at first connect (by its
    * geo hint) or by `personas.pinProxy`, and keeps it.

package/package.json

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