libretto 0.6.16 → 0.6.17

package/src/cli/commands/execution.ts

@@ -810,7 +810,7 @@ export const runInput = SimpleCLI.input({
       help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)",
     }),
     provider: SimpleCLI.option(z.string().optional(), {
-      help: "Browser provider (local, kernel, browserbase)",
+      help: "Browser provider (local, kernel, browserbase, steel)",
       aliases: ["-p"],
     }),
   },

package/src/cli/commands/search.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { DaemonClient } from "../core/daemon/ipc.js";
+import { resolveExperiments } from "../core/experiments.js";
+import {
+  formatHtmlForSearch,
+  searchFormattedHtml,
+} from "../../shared/html-search/search-html.js";
+import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
+import { SimpleCLI } from "affordance";
+
+export const searchInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("pattern", z.string().optional(), {
+      help: "JavaScript regex pattern to search for in the formatted HTML snapshot",
+    }),
+  ],
+  named: {
+    session: sessionOption(),
+    page: pageOption(),
+  },
+}).refine(
+  (input) => input.pattern !== undefined,
+  "Usage: libretto search <regex> --session <name> [--page <id>]",
+);
+
+export const searchCommand = SimpleCLI.command({
+  description: "Search the current page HTML snapshot",
+})
+  .input(searchInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    if (!resolveExperiments().search) {
+      throw new Error(
+        [
+          'The "search" experiment is disabled.',
+          "Enable it with: libretto experiments enable search",
+        ].join("\n"),
+      );
+    }
+
+    if (!ctx.sessionState.daemonSocketPath) {
+      throw new Error(
+        `Session "${ctx.session}" has no daemon socket. Close and reopen it with: libretto open <url> --session ${ctx.session}`,
+      );
+    }
+
+    const client = await DaemonClient.connect(ctx.sessionState.daemonSocketPath);
+    try {
+      const response = await client.readonlyExec({
+        code: "return await page.content()",
+        pageId: input.page,
+      });
+      if (!response.ok) {
+        throw new Error(response.message);
+      }
+      if (typeof response.data.result !== "string") {
+        throw new Error("Expected page.content() to return an HTML string.");
+      }
+
+      const formattedHtml = formatHtmlForSearch(response.data.result);
+      const matches = searchFormattedHtml(formattedHtml, input.pattern!);
+      if (matches.length === 0) {
+        console.log(`No matches for /${input.pattern}/.`);
+        return;
+      }
+
+      for (const [index, match] of matches.entries()) {
+        if (index > 0) console.log("--");
+        console.log(match.lines.join("\n"));
+      }
+    } finally {
+      client.destroy();
+    }
+  });

package/src/cli/commands/update.ts

@@ -0,0 +1,149 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { SimpleCLI } from "affordance";
+
+const UPDATE_COMMAND = "curl -fsSL https://libretto.sh/install.sh | bash";
+
+type PackageManifest = {
+  version?: string;
+};
+
+function readCurrentCliVersion(): string {
+  const packageJsonPath = fileURLToPath(
+    new URL("../../../package.json", import.meta.url),
+  );
+  const manifest = JSON.parse(
+    readFileSync(packageJsonPath, "utf8"),
+  ) as PackageManifest;
+
+  if (!manifest.version) {
+    throw new Error(
+      `Unable to determine current libretto version from ${packageJsonPath}.`,
+    );
+  }
+
+  return manifest.version;
+}
+
+function readLatestNpmVersion(): string {
+  const result = spawnSync("npm", ["view", "libretto@latest", "version"], {
+    encoding: "utf8",
+  });
+
+  if (result.error) {
+    throw new Error(
+      [
+        "Error: failed to check the latest Libretto version on npm.",
+        `Known state: ${result.error.message}`,
+        "Try: npm view libretto@latest version",
+        "Help: libretto help update",
+      ].join("\n"),
+    );
+  }
+
+  if (result.status !== 0) {
+    const detail = result.stderr.trim();
+    throw new Error(
+      [
+        "Error: failed to check the latest Libretto version on npm.",
+        `Known state: npm exited with status ${result.status}.`,
+        ...(detail ? [`npm stderr: ${detail}`] : []),
+        "Try: npm view libretto@latest version",
+        "Help: libretto help update",
+      ].join("\n"),
+    );
+  }
+
+  const version = result.stdout.trim();
+  if (!version) {
+    throw new Error(
+      [
+        "Error: failed to check the latest Libretto version on npm.",
+        "Known state: npm did not print a version.",
+        "Try: npm view libretto@latest version",
+        "Help: libretto help update",
+      ].join("\n"),
+    );
+  }
+
+  return version;
+}
+
+export const updateInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    dryRun: SimpleCLI.flag({
+      name: "dry-run",
+      help: "Print the update command without running it",
+    }),
+  },
+});
+
+function formatUpdateFailure(
+  status: number | null,
+  signal: string | null,
+): string {
+  const knownState =
+    status === null
+      ? `installer was interrupted${signal ? ` by ${signal}` : ""}.`
+      : `installer exited with status ${status}.`;
+
+  return [
+    "Error: failed to update Libretto to the latest version.",
+    `Known state: ${knownState}`,
+    `Try: ${UPDATE_COMMAND}`,
+    "Help: libretto help update",
+  ].join("\n");
+}
+
+export const updateCommand = SimpleCLI.command({
+  description: "Update Libretto to the latest version",
+})
+  .input(updateInput)
+  .handle(async ({ input }) => {
+    if (input.dryRun) {
+      console.log("Update command:");
+      console.log(`  ${UPDATE_COMMAND}`);
+      console.log("No changes made.");
+      return;
+    }
+
+    const currentVersion = readCurrentCliVersion();
+    const latestVersion = readLatestNpmVersion();
+    console.log(`Current version: ${currentVersion}`);
+    console.log(`Latest version: ${latestVersion}`);
+
+    if (currentVersion === latestVersion) {
+      console.log(`Libretto is already up to date (${currentVersion}).`);
+      console.log("No further action required.");
+      return;
+    }
+
+    console.log("Updating Libretto to latest...");
+    const result = spawnSync("bash", ["-lc", UPDATE_COMMAND], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        LIBRETTO_VERSION: "latest",
+      },
+    });
+
+    if (result.error) {
+      throw new Error(
+        [
+          "Error: failed to start the Libretto installer.",
+          `Known state: ${result.error.message}`,
+          `Try: ${UPDATE_COMMAND}`,
+          "Help: libretto help update",
+        ].join("\n"),
+      );
+    }
+
+    if (result.status !== 0) {
+      throw new Error(formatUpdateFailure(result.status, result.signal));
+    }
+
+    console.log("Libretto updated to latest.");
+    console.log("No further action required.");
+  });

package/src/cli/core/context.ts

@@ -34,6 +34,10 @@ export function getSessionNetworkLogPath(session: string): string {
   return join(getSessionDir(session), "network.jsonl");
 }
 
+export function getSessionRawNetworkDir(session: string): string {
+  return join(getSessionDir(session), "raw-network");
+}
+
 export function getSessionActionsLogPath(session: string): string {
   return join(getSessionDir(session), "actions.jsonl");
 }

package/src/cli/core/daemon/daemon.ts

@@ -39,6 +39,7 @@ import {
 import {
   createLoggerForSession,
   getSessionDir,
+  getSessionRawNetworkDir,
   getSessionNetworkLogPath,
   getSessionActionsLogPath,
   getSessionProviderClosePath,
@@ -255,6 +256,7 @@ class BrowserDaemon {
     // Telemetry — may fail on connect-mode reconnections where
     // exposeFunction bindings already exist; log and continue.
     const networkLogFile = getSessionNetworkLogPath(session);
+    const rawNetworkDir = getSessionRawNetworkDir(session);
     const actionsLogFile = getSessionActionsLogPath(session);
     const logger = createLoggerForSession(session);
 
@@ -263,6 +265,7 @@ class BrowserDaemon {
         context,
         initialPage: page,
         includeUserDomActions: true,
+        rawNetworkDir,
         logAction: (entry: TelemetryEntry) => {
           appendFileSync(actionsLogFile, JSON.stringify(entry) + "\n");
         },

package/src/cli/core/experiments.ts

@@ -11,7 +11,21 @@ export type ExperimentMetadata = {
   defaultValue: boolean;
 };
 
-export const EXPERIMENTS: Readonly<Record<string, ExperimentMetadata>> = {};
+export const EXPERIMENTS: Readonly<Record<string, ExperimentMetadata>> = {
+  search: {
+    title: "HTML Search",
+    oneSentenceDescription:
+      "Adds a search command that greps the current page's formatted HTML snapshot.",
+    docs: [
+      "Adds a search command for inspecting the current page's HTML snapshot with a JavaScript regex.",
+      "",
+      "Usage: libretto search <regex> --session <name> [--page <id>]",
+      "",
+      "The command captures page HTML through read-only execution, condenses and formats it, then prints matching regions with up to four lines of surrounding context.",
+    ].join("\n"),
+    defaultValue: false,
+  },
+};
 
 export type ExperimentName = string;
 export type Experiments = Record<ExperimentName, boolean>;

package/src/cli/core/providers/index.ts

@@ -2,12 +2,14 @@ import { readLibrettoConfig } from "../config.js";
 import { createBrowserbaseProvider } from "./browserbase.js";
 import { createKernelProvider } from "./kernel.js";
 import { createLibrettoCloudProvider } from "./libretto-cloud.js";
+import { createSteelProvider } from "./steel.js";
 import type { ProviderApi } from "./types.js";
 
 const VALID_PROVIDERS = new Set([
   "local",
   "kernel",
   "browserbase",
+  "steel",
   "libretto-cloud",
 ] as const);
 export type ProviderName =
@@ -56,12 +58,14 @@ export function getCloudProviderApi(name: string): ProviderApi {
       return createKernelProvider();
     case "browserbase":
       return createBrowserbaseProvider();
+    case "steel":
+      return createSteelProvider();
     case "libretto-cloud":
       console.warn("Note: The libretto-cloud provider is in alpha.");
       return createLibrettoCloudProvider();
     default:
       throw new Error(
-        `Unknown provider "${name}". Valid cloud providers: kernel, browserbase`,
+        `Unknown provider "${name}". Valid cloud providers: kernel, browserbase, steel`,
       );
   }
 }

package/src/cli/core/providers/steel.ts

@@ -0,0 +1,75 @@
+import type { ProviderApi } from "./types.js";
+
+const DEFAULT_STEEL_API_ENDPOINT = "https://api.steel.dev";
+const DEFAULT_STEEL_CONNECT_ENDPOINT = "wss://connect.steel.dev";
+
+type SteelSessionResponse = {
+  id: string;
+  sessionViewerUrl?: string;
+};
+
+export type SteelProviderOptions = {
+  apiKey?: string;
+};
+
+export function createSteelProvider(
+  options: SteelProviderOptions = {},
+): ProviderApi {
+  const apiKey = options.apiKey ?? process.env.STEEL_API_KEY;
+  if (!apiKey) throw new Error("STEEL_API_KEY is required for Steel provider.");
+
+  const endpoint = process.env.STEEL_BASE_URL ?? DEFAULT_STEEL_API_ENDPOINT;
+  const connectEndpoint =
+    process.env.STEEL_CONNECT_URL ?? DEFAULT_STEEL_CONNECT_ENDPOINT;
+
+  return {
+    async createSession() {
+      const resp = await fetch(`${endpoint}/v1/sessions`, {
+        method: "POST",
+        headers: {
+          "steel-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({}),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Steel API error (${resp.status}): ${body}`);
+      }
+      const json = (await resp.json()) as SteelSessionResponse;
+      return {
+        sessionId: json.id,
+        cdpEndpoint: buildSteelCdpEndpoint(connectEndpoint, apiKey, json.id),
+        liveViewUrl: json.sessionViewerUrl,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/v1/sessions/${sessionId}/release`, {
+        method: "POST",
+        headers: {
+          "steel-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({}),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Steel API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+      return {};
+    },
+  };
+}
+
+function buildSteelCdpEndpoint(
+  connectEndpoint: string,
+  apiKey: string,
+  sessionId: string,
+): string {
+  const endpoint = new URL(connectEndpoint);
+  endpoint.searchParams.set("apiKey", apiKey);
+  endpoint.searchParams.set("sessionId", sessionId);
+  return endpoint.toString();
+}

package/src/cli/core/session-telemetry.ts

@@ -1,4 +1,7 @@
 import type { BrowserContext, Page } from "playwright";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
 import {
   filterSemanticClasses,
   INTERACTIVE_ROLE_NAMES,
@@ -16,18 +19,69 @@ type InstallSessionTelemetryOptions = {
   logAction: (entry: TelemetryEntry) => void;
   logNetwork: (entry: TelemetryEntry) => void;
   includeUserDomActions?: boolean;
+  rawNetworkDir?: string;
 };
 
+const BODY_PREVIEW_CHARS = 4096;
+const MAX_SAVED_BODY_BYTES = 10 * 1024 * 1024;
+const LOG_RESOURCE_TYPES = new Set(["document", "xhr", "fetch"]);
+const SKIP_RESOURCE_TYPES = new Set(["image", "font", "media", "stylesheet"]);
+const NOISE_URL_RE =
+  /(google-analytics|googletagmanager|googleadservices|googlesyndication|doubleclick|facebook\.com\/tr|pinterest|criteo|snapchat|2mdn\.net|adtrafficquality|safeframe|recaptcha|analytics|beacon|pixel|\/ads?\/|\/collect|\/event|\/pagead\/|\/gmp\/conversion|\/ccm\/|\/rmkt\/|favicon|\.map(?:\?|$))/i;
+const TEXT_CONTENT_TYPE_RE =
+  /json|html|text|xml|graphql|javascript|x-www-form-urlencoded/i;
+
+function shouldLogNetworkEntry(
+  method: string,
+  url: string,
+  resourceType: string,
+): boolean {
+  if (url.startsWith("chrome-extension://")) return false;
+  if (NOISE_URL_RE.test(url)) return false;
+  if (resourceType === "ping") return false;
+  if (LOG_RESOURCE_TYPES.has(resourceType)) return true;
+  if (["POST", "PUT", "PATCH", "DELETE"].includes(method)) return true;
+  if (SKIP_RESOURCE_TYPES.has(resourceType)) return false;
+  return false;
+}
+
+function isTextLikeContentType(contentType: string | null): boolean {
+  return contentType !== null && TEXT_CONTENT_TYPE_RE.test(contentType);
+}
+
+function bodyPreview(value: string): string {
+  return value.slice(0, BODY_PREVIEW_CHARS);
+}
+
+function saveBodySidecar(
+  rawNetworkDir: string | undefined,
+  id: number,
+  kind: "request" | "response",
+  contentType: string | null,
+  body: string,
+): string | null {
+  if (!rawNetworkDir) return null;
+  mkdirSync(rawNetworkDir, { recursive: true });
+  const ext = contentType?.includes("json")
+    ? "json"
+    : contentType?.includes("html")
+      ? "html"
+      : "txt";
+  const filename = `${String(id).padStart(6, "0")}.${kind}.${ext}.gz`;
+  writeFileSync(join(rawNetworkDir, filename), gzipSync(body));
+  return `raw-network/${filename}`;
+}
+
 export async function installSessionTelemetry(
   options: InstallSessionTelemetryOptions,
 ): Promise<void> {
-  const STATIC_EXT_RE =
-    /\.(css|js|png|jpg|jpeg|gif|woff|woff2|ttf|ico|svg)(\?|$)/i;
-  const { context, initialPage, logAction, logNetwork } = options;
+  const { context, initialPage, logAction, logNetwork, rawNetworkDir } =
+    options;
   const includeUserDomActions = options.includeUserDomActions ?? false;
   const pageIdCache = new WeakMap<Page, string>();
   const wrappedPages = new WeakSet<Page>();
   const exposedPages = new WeakSet<Page>();
+  let networkId = 0;
 
   const resolvePageId = async (page: Page): Promise<string> => {
     if (pageIdCache.has(page)) return pageIdCache.get(page)!;
@@ -748,20 +802,129 @@ export async function installSessionTelemetry(
     page.on("response", async (response) => {
       const request = response.request();
       const url = request.url();
-      if (STATIC_EXT_RE.test(url) || url.startsWith("chrome-extension://"))
-        return;
+      const method = request.method();
+      const resourceType = request.resourceType();
+      if (!shouldLogNetworkEntry(method, url, resourceType)) return;
+
+      const id = ++networkId;
+      const requestHeaders = request.headers();
+      const responseHeaders = response.headers();
+      const contentType = responseHeaders["content-type"] ?? null;
+      const requestContentType = requestHeaders["content-type"] ?? null;
+      const requestBody = request.postData();
+      const requestBodyBytes =
+        requestBody === null ? null : Buffer.byteLength(requestBody);
+      let requestBodyPath: string | null = null;
+      let requestBodyOmittedReason: string | null = null;
+      let responseBodyPreview: string | null = null;
+      let responseBodyPath: string | null = null;
+      let responseBodyBytes: number | null = null;
+      let responseBodyTruncated = false;
+      let responseBodyOmittedReason: string | null = null;
+      let errorText: string | null = null;
+
+      if (requestBody === null) {
+        requestBodyOmittedReason = "no-request-body";
+      } else if (!isTextLikeContentType(requestContentType)) {
+        requestBodyOmittedReason = "binary-content-type";
+      } else if (requestBodyBytes !== null && requestBodyBytes > MAX_SAVED_BODY_BYTES) {
+        requestBodyOmittedReason = "body-too-large";
+      } else {
+        requestBodyPath = saveBodySidecar(
+          rawNetworkDir,
+          id,
+          "request",
+          requestContentType,
+          requestBody,
+        );
+      }
+
+      if (!isTextLikeContentType(contentType) || !LOG_RESOURCE_TYPES.has(resourceType)) {
+        responseBodyOmittedReason = "binary-content-type";
+      } else {
+        try {
+          const responseBody = await response.text();
+          responseBodyBytes = Buffer.byteLength(responseBody);
+          responseBodyPreview = bodyPreview(responseBody);
+          if (responseBodyBytes > MAX_SAVED_BODY_BYTES) {
+            responseBodyTruncated = true;
+            responseBodyOmittedReason = "body-too-large";
+          } else {
+            responseBodyPath = saveBodySidecar(
+              rawNetworkDir,
+              id,
+              "response",
+              contentType,
+              responseBody,
+            );
+          }
+        } catch (error: any) {
+          responseBodyOmittedReason = "read-error";
+          errorText = error?.message ?? String(error);
+        }
+      }
+
       emitNetwork({
+        id,
         pageId,
-        method: request.method(),
+        method,
         url,
+        resourceType,
         status: response.status(),
-        contentType: response.headers()["content-type"] ?? null,
-        postData:
-          request.method() === "POST" ||
-          request.method() === "PUT" ||
-          request.method() === "PATCH"
-            ? (request.postData() ?? "").substring(0, 2000)
-            : undefined,
+        statusText: response.statusText(),
+        contentType,
+        requestHeaders,
+        responseHeaders,
+        requestBodyPreview: requestBody ? bodyPreview(requestBody) : null,
+        requestBodyPath,
+        requestBodyBytes,
+        requestBodyTruncated:
+          requestBody !== null &&
+          requestBodyBytes !== null &&
+          requestBodyBytes > MAX_SAVED_BODY_BYTES,
+        requestBodyOmittedReason,
+        responseBodyPreview,
+        responseBodyPath,
+        responseBodyBytes,
+        responseBodyTruncated,
+        responseBodyOmittedReason,
+        errorText,
+        postData: requestBody ? bodyPreview(requestBody) : undefined,
+        responseBody: null,
+        size: null,
+        durationMs: null,
+      });
+    });
+
+    page.on("requestfailed", async (request) => {
+      const url = request.url();
+      const method = request.method();
+      const resourceType = request.resourceType();
+      if (!shouldLogNetworkEntry(method, url, resourceType)) return;
+
+      const id = ++networkId;
+      emitNetwork({
+        id,
+        pageId,
+        method,
+        url,
+        resourceType,
+        status: null,
+        statusText: null,
+        contentType: null,
+        requestHeaders: request.headers(),
+        responseHeaders: null,
+        requestBodyPreview: null,
+        requestBodyPath: null,
+        requestBodyBytes: null,
+        requestBodyTruncated: false,
+        requestBodyOmittedReason: null,
+        responseBodyPreview: null,
+        responseBodyPath: null,
+        responseBodyBytes: null,
+        responseBodyTruncated: false,
+        responseBodyOmittedReason: "request-failed",
+        errorText: request.failure()?.errorText ?? null,
         responseBody: null,
         size: null,
         durationMs: null,

package/src/cli/core/skill-version.ts

@@ -14,7 +14,7 @@ const INSTALLED_SKILL_PATHS = [
 
 let cachedCliVersion: string | null = null;
 
-function readCurrentCliVersion(): string {
+export function readCurrentCliVersion(): string {
   if (cachedCliVersion) {
     return cachedCliVersion;
   }

package/src/cli/core/telemetry.ts

@@ -11,16 +11,32 @@ import {
 import { assertSessionStateExistsOrThrow } from "./session.js";
 
 export type NetworkLogEntry = {
+  id?: number;
   ts: string;
   pageId?: string;
   method: string;
   url: string;
-  status: number;
+  resourceType?: string;
+  status: number | null;
+  statusText?: string | null;
   contentType: string | null;
+  requestHeaders?: Record<string, string> | null;
+  responseHeaders?: Record<string, string> | null;
+  requestBodyPreview?: string | null;
+  requestBodyPath?: string | null;
+  requestBodyBytes?: number | null;
+  requestBodyTruncated?: boolean;
+  requestBodyOmittedReason?: string | null;
+  responseBodyPreview?: string | null;
+  responseBodyPath?: string | null;
+  responseBodyBytes?: number | null;
+  responseBodyTruncated?: boolean;
+  responseBodyOmittedReason?: string | null;
+  errorText?: string | null;
   postData?: string;
   responseBody?: string | null;
-  size: number | null;
-  durationMs: number | null;
+  size?: number | null;
+  durationMs?: number | null;
 };
 
 export function readNetworkLog(