libretto 0.4.4 → 0.5.1

package/dist/shared/config/config.d.ts

@@ -1,10 +1,2 @@
-/**
- * Runtime configuration for libretto.
- *
- * Values are derived from environment variables only.
- */
-declare function isDebugMode(): boolean;
-declare function isDryRun(): boolean;
-declare function shouldPauseBeforeMutation(): boolean;
 
-export { isDebugMode, isDryRun, shouldPauseBeforeMutation };
+export {  }

package/dist/shared/config/config.js

@@ -1,18 +0,0 @@
-function isDebugMode() {
-  return process.env.LIBRETTO_DEBUG === "true";
-}
-function isDryRun() {
-  const explicit = process.env.LIBRETTO_DRY_RUN;
-  if (explicit !== void 0) {
-    return explicit === "true";
-  }
-  return process.env.NODE_ENV === "development";
-}
-function shouldPauseBeforeMutation() {
-  return isDryRun() && isDebugMode();
-}
-export {
-  isDebugMode,
-  isDryRun,
-  shouldPauseBeforeMutation
-};

package/dist/shared/config/index.d.ts

@@ -1 +1,2 @@
-export { isDebugMode, isDryRun, shouldPauseBeforeMutation } from './config.js';
+
+export {  }

package/dist/shared/config/index.js

@@ -1,10 +0,0 @@
-import {
-  isDebugMode,
-  isDryRun,
-  shouldPauseBeforeMutation
-} from "./config.js";
-export {
-  isDebugMode,
-  isDryRun,
-  shouldPauseBeforeMutation
-};

package/dist/shared/debug/pause.js

@@ -1,8 +1,14 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { getSessionDir } from "../../cli/core/context.js";
-import { getPauseSignalPaths, removeSignalIfExists } from "../../cli/core/pause-signals.js";
-import { listSessionsWithStateFile, readSessionState } from "../../cli/core/session.js";
+import {
+  getPauseSignalPaths,
+  removeSignalIfExists
+} from "../../cli/core/pause-signals.js";
+import {
+  listSessionsWithStateFile,
+  readSessionState
+} from "../../cli/core/session.js";
 function isPidRunning(pid) {
   try {
     process.kill(pid, 0);
@@ -14,7 +20,7 @@ function isPidRunning(pid) {
 function getRunningSessions() {
   return listSessionsWithStateFile().filter((candidate) => {
     const state = readSessionState(candidate);
-    return state !== null && isPidRunning(state.pid);
+    return state !== null && state.pid != null && isPidRunning(state.pid);
   });
 }
 function throwMissingSessionError() {

package/dist/shared/instrumentation/instrument.js

@@ -25,6 +25,7 @@ const LOCATOR_ACTIONS = [
 ];
 const NAV_ACTIONS = ["goto", "reload", "goBack", "goForward"];
 const POINTER_ACTIONS = /* @__PURE__ */ new Set(["click", "dblclick", "hover"]);
+const instrumentedTargets = /* @__PURE__ */ new WeakSet();
 const pageQueues = /* @__PURE__ */ new WeakMap();
 function enqueue(page, fn) {
   const prev = pageQueues.get(page) ?? Promise.resolve();
@@ -96,11 +97,93 @@ function wrapLocatorActions(locator, page, opts) {
     };
   }
 }
+const LOCATOR_FACTORY_METHODS = [
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "filter",
+  "and",
+  "or",
+  "first",
+  "last",
+  "nth"
+];
+const FRAME_LOCATOR_FACTORY_METHODS = [
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "owner",
+  "first",
+  "last",
+  "nth"
+];
+function instrumentLocator(locator, page, opts) {
+  const target = locator;
+  if (instrumentedTargets.has(target)) {
+    return locator;
+  }
+  instrumentedTargets.add(target);
+  wrapLocatorActions(locator, page, opts);
+  for (const method of LOCATOR_FACTORY_METHODS) {
+    if (typeof locator[method] !== "function") continue;
+    const orig = locator[method].bind(locator);
+    locator[method] = (...args) => {
+      const nextLocator = orig(...args);
+      return instrumentLocator(nextLocator, page, opts);
+    };
+  }
+  if (typeof locator.contentFrame === "function") {
+    const origContentFrame = locator.contentFrame.bind(locator);
+    locator.contentFrame = (...args) => {
+      const frameLocator = origContentFrame(...args);
+      return instrumentFrameLocator(frameLocator, page, opts);
+    };
+  }
+  return locator;
+}
+function instrumentFrameLocator(frameLocator, page, opts) {
+  const target = frameLocator;
+  if (instrumentedTargets.has(target)) {
+    return frameLocator;
+  }
+  instrumentedTargets.add(target);
+  for (const method of FRAME_LOCATOR_FACTORY_METHODS) {
+    if (typeof frameLocator[method] !== "function") continue;
+    const orig = frameLocator[method].bind(frameLocator);
+    frameLocator[method] = (...args) => {
+      const result = orig(...args);
+      if (method === "first" || method === "last" || method === "nth") {
+        return instrumentFrameLocator(result, page, opts);
+      }
+      return instrumentLocator(result, page, opts);
+    };
+  }
+  if (typeof frameLocator.frameLocator === "function") {
+    const origFrameLocator = frameLocator.frameLocator.bind(
+      frameLocator
+    );
+    frameLocator.frameLocator = (...args) => {
+      const nestedFrameLocator = origFrameLocator(...args);
+      return instrumentFrameLocator(nestedFrameLocator, page, opts);
+    };
+  }
+  return frameLocator;
+}
 function isTimeoutError(err) {
   if (!err || typeof err.message !== "string") return false;
   return err.message.includes("Timeout") || err.message.includes("timeout") || err.name === "TimeoutError";
 }
-const LOCATOR_FACTORIES = [
+const PAGE_LOCATOR_FACTORIES = [
   "locator",
   "getByRole",
   "getByText",
@@ -110,6 +193,7 @@ const LOCATOR_FACTORIES = [
   "getByTitle",
   "getByTestId"
 ];
+const PAGE_FRAME_LOCATOR_FACTORIES = ["frameLocator"];
 async function installInstrumentation(page, options) {
   if (page.__librettoInstrumented) return;
   page.__librettoInstrumented = true;
@@ -129,7 +213,12 @@ async function installInstrumentation(page, options) {
           try {
             const loc = page.locator(args[0]);
             const box = await loc.boundingBox();
-            await visualizeBeforeAction(page, box, method, highlightBeforeActionMs);
+            await visualizeBeforeAction(
+              page,
+              box,
+              method,
+              highlightBeforeActionMs
+            );
           } catch {
           }
         });
@@ -161,13 +250,20 @@ async function installInstrumentation(page, options) {
       return orig(...args);
     };
   }
-  for (const factory of LOCATOR_FACTORIES) {
+  for (const factory of PAGE_LOCATOR_FACTORIES) {
     if (typeof page[factory] !== "function") continue;
     const origFactory = page[factory].bind(page);
     page[factory] = (...factoryArgs) => {
       const locator = origFactory(...factoryArgs);
-      wrapLocatorActions(locator, page, mergedOpts);
-      return locator;
+      return instrumentLocator(locator, page, mergedOpts);
+    };
+  }
+  for (const factory of PAGE_FRAME_LOCATOR_FACTORIES) {
+    if (typeof page[factory] !== "function") continue;
+    const origFactory = page[factory].bind(page);
+    page[factory] = (...factoryArgs) => {
+      const frameLocator = origFactory(...factoryArgs);
+      return instrumentFrameLocator(frameLocator, page, mergedOpts);
     };
   }
 }

package/dist/shared/llm/ai-sdk-adapter.js

@@ -18,7 +18,9 @@ function createLLMClientFromModel(model) {
         if (msg.role === "assistant") {
           return {
             role: "assistant",
-            content: msg.content.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }))
+            content: msg.content.filter(
+              (part) => part.type === "text"
+            ).map((part) => ({ type: "text", text: part.text }))
           };
         }
         return {

package/dist/shared/llm/client.js

@@ -121,7 +121,9 @@ function convertUserContentParts(parts) {
   });
 }
 function convertAssistantContentParts(parts) {
-  return parts.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }));
+  return parts.filter(
+    (part) => part.type === "text"
+  ).map((part) => ({ type: "text", text: part.text }));
 }
 function convertMessages(messages) {
   return messages.map((msg) => {

package/dist/shared/logger/index.js

@@ -1,4 +1,7 @@
-import { Logger, defaultLogger } from "./logger.js";
+import {
+  Logger,
+  defaultLogger
+} from "./logger.js";
 import {
   createFileLogSink,
   prettyConsoleSink,

package/dist/shared/paths/paths.js

@@ -1,5 +1,6 @@
 import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { resolveLibrettoRepoRoot } from "./repo-root.js";
 const LIBRETTO_DIRNAME = ".libretto";
 const LIBRETTO_SESSIONS_DIRNAME = "sessions";
 const SESSION_STATE_FILENAME = "state.json";
@@ -8,7 +9,7 @@ const RUNNER_LOG_FILENAME = "logs.jsonl";
 const PAUSED_SIGNAL_SUFFIX = "paused";
 const RESUME_SIGNAL_SUFFIX = "resume";
 function getLibrettoRoot(cwd = process.cwd()) {
-  return join(cwd, LIBRETTO_DIRNAME);
+  return join(resolveLibrettoRepoRoot(cwd), LIBRETTO_DIRNAME);
 }
 function getLibrettoSessionsDir(cwd = process.cwd()) {
   return join(getLibrettoRoot(cwd), LIBRETTO_SESSIONS_DIRNAME);

package/dist/shared/paths/repo-root.d.ts

@@ -0,0 +1,3 @@
+declare function resolveLibrettoRepoRoot(cwd?: string): string;
+
+export { resolveLibrettoRepoRoot };

package/dist/shared/paths/repo-root.js

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+const repoRootCache = /* @__PURE__ */ new Map();
+function resolveLibrettoRepoRoot(cwd = process.cwd()) {
+  const override = process.env.LIBRETTO_REPO_ROOT?.trim();
+  if (override) {
+    return resolve(override);
+  }
+  const normalizedCwd = resolve(cwd);
+  const cached = repoRootCache.get(normalizedCwd);
+  if (cached) {
+    return cached;
+  }
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: normalizedCwd,
+    encoding: "utf-8"
+  });
+  const repoRoot = result.status === 0 && result.stdout ? result.stdout.trim() : normalizedCwd;
+  repoRootCache.set(normalizedCwd, repoRoot);
+  return repoRoot;
+}
+export {
+  resolveLibrettoRepoRoot
+};

package/dist/shared/run/api.js

@@ -1,4 +1,6 @@
-import { launchBrowser } from "./browser.js";
+import {
+  launchBrowser
+} from "./browser.js";
 export {
   launchBrowser
 };

package/dist/shared/run/browser.js

@@ -1,8 +1,13 @@
-import { chromium } from "playwright";
+import {
+  chromium
+} from "playwright";
 import { createServer } from "node:net";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { ensureLibrettoSessionStatePath } from "../paths/paths.js";
-import { SESSION_STATE_VERSION, SessionStateFileSchema } from "../state/session-state.js";
+import {
+  SESSION_STATE_VERSION,
+  SessionStateFileSchema
+} from "../state/session-state.js";
 async function pickFreePort() {
   return await new Promise((resolve, reject) => {
     const server = createServer();

package/dist/shared/state/session-state.d.ts

@@ -15,7 +15,8 @@ declare const SessionViewportSchema: z.ZodObject<{
 declare const SessionStateFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     port: z.ZodNumber;
-    pid: z.ZodNumber;
+    pid: z.ZodOptional<z.ZodNumber>;
+    cdpEndpoint: z.ZodOptional<z.ZodString>;
     session: z.ZodString;
     startedAt: z.ZodString;
     status: z.ZodOptional<z.ZodEnum<{

package/dist/shared/state/session-state.js

@@ -14,7 +14,8 @@ const SessionViewportSchema = z.object({
 const SessionStateFileSchema = z.object({
   version: z.literal(SESSION_STATE_VERSION),
   port: z.number().int().min(0).max(65535),
-  pid: z.number().int(),
+  pid: z.number().int().optional(),
+  cdpEndpoint: z.string().url().optional(),
   session: z.string().min(1),
   startedAt: z.string().datetime({ offset: true }),
   status: SessionStatusSchema.optional(),
@@ -29,7 +30,9 @@ function formatIssues(error) {
 function parseSessionStateData(rawState, source) {
   const parsed = SessionStateFileSchema.safeParse(rawState);
   if (!parsed.success) {
-    throw new Error(`Session state at ${source} is invalid: ${formatIssues(parsed.error)}`);
+    throw new Error(
+      `Session state at ${source} is invalid: ${formatIssues(parsed.error)}`
+    );
   }
   const { version: _version, ...state } = parsed.data;
   return state;

package/dist/shared/visualization/ghost-cursor.js

@@ -64,7 +64,13 @@ async function moveGhostCursor(page, target) {
         el.style.transition = `transform ${duration}ms ${easing}`;
         el.style.transform = `translate3d(${x}px, ${y}px, 0)`;
       },
-      { id: CURSOR_ID, x: target.x, y: target.y, duration: durationMs, easing: opts.easing }
+      {
+        id: CURSOR_ID,
+        x: target.x,
+        y: target.y,
+        duration: durationMs,
+        easing: opts.easing
+      }
     );
     await page.waitForTimeout(durationMs);
   } catch {
@@ -122,15 +128,18 @@ async function hideGhostCursor(page) {
 }
 async function getGhostCursorPosition(page) {
   try {
-    return await page.evaluate(({ id }) => {
-      const el = document.getElementById(id);
-      if (!el) return null;
-      const match = el.style.transform.match(
-        /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/
-      );
-      if (!match) return null;
-      return { x: parseFloat(match[1]), y: parseFloat(match[2]) };
-    }, { id: CURSOR_ID });
+    return await page.evaluate(
+      ({ id }) => {
+        const el = document.getElementById(id);
+        if (!el) return null;
+        const match = el.style.transform.match(
+          /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/
+        );
+        if (!match) return null;
+        return { x: parseFloat(match[1]), y: parseFloat(match[2]) };
+      },
+      { id: CURSOR_ID }
+    );
   } catch {
     return null;
   }

package/dist/shared/visualization/highlight.js

@@ -92,12 +92,15 @@ async function showHighlight(page, params) {
 }
 async function clearHighlights(page) {
   try {
-    await page.evaluate(({ layerId }) => {
-      const layer = document.getElementById(layerId);
-      if (!layer) return;
-      const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
-      rects.forEach((r) => r.remove());
-    }, { layerId: LAYER_ID });
+    await page.evaluate(
+      ({ layerId }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+        const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
+        rects.forEach((r) => r.remove());
+      },
+      { layerId: LAYER_ID }
+    );
   } catch {
   }
 }

package/dist/shared/workflow/workflow.d.ts

@@ -2,8 +2,8 @@ import { Page } from 'playwright';
 import { MinimalLogger } from '../logger/logger.js';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
-type LibrettoWorkflowMetadata = {};
 type LibrettoWorkflowContext<S = {}> = {
+    session: string;
     page: Page;
     logger: MinimalLogger;
     services: S;
@@ -11,11 +11,10 @@ type LibrettoWorkflowContext<S = {}> = {
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown, S = {}> = (ctx: LibrettoWorkflowContext<S>, input: Input) => Promise<Output>;
 declare class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
     readonly [LIBRETTO_WORKFLOW_BRAND] = true;
-    readonly metadata: LibrettoWorkflowMetadata;
     private readonly handler;
-    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>);
+    constructor(handler: LibrettoWorkflowHandler<Input, Output, S>);
     run(ctx: LibrettoWorkflowContext<S>, input: Input): Promise<Output>;
 }
-declare function workflow<Input = unknown, Output = unknown, S = {}>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
+declare function workflow<Input = unknown, Output = unknown, S = {}>(handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
 
-export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, workflow };

package/dist/shared/workflow/workflow.js

@@ -1,18 +1,16 @@
 const LIBRETTO_WORKFLOW_BRAND = /* @__PURE__ */ Symbol.for("libretto.workflow");
 class LibrettoWorkflow {
   [LIBRETTO_WORKFLOW_BRAND] = true;
-  metadata;
   handler;
-  constructor(metadata, handler) {
-    this.metadata = metadata;
+  constructor(handler) {
     this.handler = handler;
   }
   async run(ctx, input) {
     return this.handler(ctx, input);
   }
 }
-function workflow(metadata, handler) {
-  return new LibrettoWorkflow(metadata, handler);
+function workflow(handler) {
+  return new LibrettoWorkflow(handler);
 }
 export {
   LIBRETTO_WORKFLOW_BRAND,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -14,31 +14,33 @@
   },
   "files": [
     "dist",
+    "src",
     "scripts",
     "skills/libretto"
   ],
+  "types": "./dist/index.d.ts",
   "bin": {
-    "libretto": "./dist/cli/index.js",
-    "libretto-cli": "./dist/cli/index.js"
+    "libretto": "./dist/cli/index.js"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "build": "pnpm run build:runtime && pnpm run build:cli",
-    "build:runtime": "tsup --config tsup.config.ts",
-    "build:cli": "tsup --config tsup.cli.config.ts",
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "check:skills": "node scripts/check-skills-sync.mjs",
+    "build": "tsup --config tsup.config.ts",
     "type-check": "tsc --noEmit",
     "test": "pnpm run build && vitest run",
     "eval": "pnpm run build && vitest run --config vitest.evals.config.ts",
     "benchmark": "pnpm run build && tsx benchmarks/run.ts",
     "test:watch": "vitest",
     "cli": "node dist/index.js",
+    "prepare-release": "bash ./scripts/prepare-release.sh",
     "prepack": "pnpm run build"
   },
   "peerDependencies": {
@@ -62,12 +64,13 @@
     }
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.75",
     "@ai-sdk/anthropic": "^3.0.58",
     "@ai-sdk/google": "^3.0.51",
     "@ai-sdk/google-vertex": "^4.0.80",
     "@ai-sdk/openai": "^3.0.41",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.75",
     "@types/node": "^25.5.0",
+    "glimpseui": "^0.5.1",
     "openai": "^6.29.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",

package/scripts/check-skills-sync.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareSkillDirs, SKILL_DIRS } from "./skills-libretto.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const result = compareSkillDirs(repoRoot);
+
+if (result.ok) {
+  console.log(
+    `libretto: verified identical skill mirrors across ${SKILL_DIRS.join(", ")}`,
+  );
+  process.exit(0);
+}
+
+console.error("libretto: skill directories must be identical:");
+for (const issue of result.issues) {
+  console.error(`- ${issue}`);
+}
+console.error("");
+console.error("Run `pnpm i` to resync the mirrors in this repository.");
+process.exit(1);

package/scripts/compare-eval-summary.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function usage() {
+  console.error(
+    "Usage: node scripts/compare-eval-summary.mjs <baseline-summary.json> <current-summary.json> [threshold-percent]",
+  );
+}
+
+const [, , baselineArg, currentArg, thresholdArg] = process.argv;
+
+if (!baselineArg || !currentArg) {
+  usage();
+  process.exit(1);
+}
+
+const baseline = JSON.parse(readFileSync(resolve(baselineArg), "utf8"));
+const current = JSON.parse(readFileSync(resolve(currentArg), "utf8"));
+const threshold = thresholdArg ? Number(thresholdArg) : 5;
+
+if (!Number.isFinite(threshold) || threshold < 0) {
+  console.error(`Invalid threshold percent: ${thresholdArg}`);
+  process.exit(1);
+}
+
+const delta = Number((current.percent - baseline.percent).toFixed(2));
+const withinThreshold = Math.abs(delta) <= threshold;
+
+const lines = [
+  "# Eval Baseline Comparison",
+  "",
+  `- Baseline score: \`${baseline.percent}%\``,
+  `- Current score: \`${current.percent}%\``,
+  `- Delta: \`${delta > 0 ? "+" : ""}${delta}%\``,
+  `- Allowed range: \`+/-${threshold}%\``,
+];
+
+process.stdout.write(`${lines.join("\n")}\n`);
+
+if (!withinThreshold) {
+  console.error(
+    `Eval score delta ${delta > 0 ? "+" : ""}${delta}% is outside the allowed +/-${threshold}% range.`,
+  );
+  process.exit(1);
+}