libretto 0.2.5 → 0.2.6

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -105,9 +105,15 @@
     "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "@ai-sdk/anthropic": { "optional": true },
-    "@ai-sdk/google-vertex": { "optional": true },
-    "@ai-sdk/openai": { "optional": true }
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google-vertex": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.53",

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.