libretto 0.2.5 → 0.2.7

package/README.md

@@ -9,17 +9,21 @@ pnpm add libretto playwright zod
 npx libretto init
 ```
 
-> **pnpm users:** add `onlyBuiltDependencies` to your `package.json` to allow
-> Playwright's postinstall script to run:
+> **pnpm users:** if your workspace uses `onlyBuiltDependencies`, add both
+> `libretto` and `playwright` to allow their postinstall scripts to run
+> (libretto's postinstall copies skill files and installs Playwright Chromium):
 >
 > ```jsonc
 > // package.json
 > {
 >   "pnpm": {
->     "onlyBuiltDependencies": ["playwright"]
+>     "onlyBuiltDependencies": ["libretto", "playwright"]
 >   }
 > }
 > ```
+>
+> If the postinstall was skipped (e.g., `libretto` wasn't in the allowlist),
+> run `npx libretto init` manually after install to complete setup.
 
 ## Quick Start
 
@@ -119,6 +123,33 @@ Run `npx libretto help` for the full list.
 | `libretto/run`             | `launchBrowser`                                               |
 | `libretto/state`           | Session state serialization and parsing                       |
 
+## Using Recovery Helpers
+
+The recovery module (`libretto/recovery`) provides `detectSubmissionError` and
+`executeRecoveryAgent` for handling form submission errors. Both accept an
+`LLMClient` — create one with `createLLMClientFromModel` and pass it directly:
+
+```typescript
+import { detectSubmissionError, executeRecoveryAgent } from "libretto/recovery";
+import { createLLMClientFromModel } from "libretto/llm";
+import { openai } from "@ai-sdk/openai";
+
+const llmClient = createLLMClientFromModel(openai("gpt-4o"));
+
+// Detect if a submission produced an error
+const error = await detectSubmissionError(
+  page, submissionError, "eligibility check failed", llmClient, knownErrors, logger,
+);
+
+// Or run the full recovery agent to retry with corrections
+const result = await executeRecoveryAgent(
+  page, error, llmClient, recoveryOptions, logger,
+);
+```
+
+No need to write custom wrappers — `createLLMClientFromModel` bridges any
+Vercel AI SDK provider into the `LLMClient` interface that recovery helpers expect.
+
 ## Links
 
 - [GitHub](https://github.com/saffron-health/libretto)

package/dist/shared/logger/logger.cjs

@@ -168,8 +168,27 @@ class Logger {
       options
     });
   }
-  info(event, data, options) {
-    this.entry({ level: "info", event, data, options });
+  info(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "info",
+      event,
+      data,
+      options
+    });
   }
   withScope(scope, context = {}) {
     return new Logger([...this.scopes, scope], this.sinks, {

package/dist/shared/logger/logger.d.cts

@@ -7,7 +7,7 @@ type LogOptions = {
  * implement withScope, withContext, flush, etc.
  */
 type MinimalLogger = {
-    info: (event: string, data?: Record<string, any>) => void;
+    info: (event: string, data?: any) => void;
     warn: (event: string, data?: any) => void;
     error: (event: string, data?: any) => any;
 };
@@ -26,7 +26,9 @@ type LoggerApi = {
     warn: (event: string, data?: Error | ({
         error: Error;
     } & Record<string, any>) | unknown, options?: LogOptions) => void;
-    info: (event: string, data?: Record<string, any>, options?: LogOptions) => void;
+    info: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => void;
     /**
      * Context passed in will be attached to all entries in this scope.
      */
@@ -71,7 +73,9 @@ declare class Logger implements LoggerApi {
     warn(event: string, dataOrError?: Error | ({
         error: Error;
     } & Record<string, any>) | unknown, options?: LogOptions): void;
-    info(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    info(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
     withScope(scope: string, context?: Record<string, any>): LoggerApi;
     withContext(context: Record<string, any>): LoggerApi;
     withSink(sink: LoggerSink): Logger;

package/dist/shared/logger/logger.d.ts

@@ -7,7 +7,7 @@ type LogOptions = {
  * implement withScope, withContext, flush, etc.
  */
 type MinimalLogger = {
-    info: (event: string, data?: Record<string, any>) => void;
+    info: (event: string, data?: any) => void;
     warn: (event: string, data?: any) => void;
     error: (event: string, data?: any) => any;
 };
@@ -26,7 +26,9 @@ type LoggerApi = {
     warn: (event: string, data?: Error | ({
         error: Error;
     } & Record<string, any>) | unknown, options?: LogOptions) => void;
-    info: (event: string, data?: Record<string, any>, options?: LogOptions) => void;
+    info: (event: string, data?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions) => void;
     /**
      * Context passed in will be attached to all entries in this scope.
      */
@@ -71,7 +73,9 @@ declare class Logger implements LoggerApi {
     warn(event: string, dataOrError?: Error | ({
         error: Error;
     } & Record<string, any>) | unknown, options?: LogOptions): void;
-    info(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    info(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
     withScope(scope: string, context?: Record<string, any>): LoggerApi;
     withContext(context: Record<string, any>): LoggerApi;
     withSink(sink: LoggerSink): Logger;

package/dist/shared/logger/logger.js

@@ -144,8 +144,27 @@ class Logger {
       options
     });
   }
-  info(event, data, options) {
-    this.entry({ level: "info", event, data, options });
+  info(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "info",
+      event,
+      data,
+      options
+    });
   }
   withScope(scope, context = {}) {
     return new Logger([...this.scopes, scope], this.sinks, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {

package/skill/code-generation-rules.md

@@ -43,6 +43,42 @@ export const myWorkflow = workflow<Input, Output>(
 - Use `await pause()` (imported from `"libretto"`) to pause the workflow for debugging. It is a no-op in production.
 - The browser is launched and closed automatically by the CLI — do not launch or close it in the handler
 
+## Passing Application Dependencies via Services
+
+Use the third generic on `workflow<Input, Output, Services>` to inject
+dependencies that exist in your application but not in libretto's runtime
+(DB transactions, API clients, caches, etc.):
+
+```typescript
+import { type Transaction } from "./db";
+
+type MyServices = { tx?: Transaction };
+
+export const myWorkflow = workflow<Input, Output, MyServices>(
+  {},
+  async (ctx, input) => {
+    if (ctx.services.tx) {
+      await ctx.services.tx.insert(/* ... */);
+    } else {
+      ctx.logger.info("No DB transaction — skipping write");
+    }
+    // ... browser automation ...
+  },
+);
+```
+
+In production, the caller passes services when invoking `.run()`:
+
+```typescript
+await myWorkflow.run(
+  { page, logger, services: { tx } },
+  input,
+);
+```
+
+When running standalone via `npx libretto run`, services defaults to `{}`,
+so mark fields optional for anything unavailable in that context.
+
 ## Playwright Locators for DOM Interaction
 
 Generated code must use Playwright locator APIs for all DOM interactions. Do not use `page.evaluate()` with `document.querySelector`, `querySelectorAll`, `textContent`, `click()`, or other DOM APIs when a Playwright locator can do the same thing.