libretto 0.5.4 → 0.5.6

package/src/cli/commands/ai.ts

@@ -1,7 +1,117 @@
 import { z } from "zod";
-import { runAiConfigure } from "../core/ai-config.js";
+import {
+  CURRENT_CONFIG_VERSION,
+  readAiConfig,
+  writeAiConfig,
+  clearAiConfig,
+  type AiConfig,
+} from "../core/config.js";
+import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
+import { DEFAULT_SNAPSHOT_MODELS } from "../core/ai-model.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 
+const PROVIDER_ALIASES: Record<string, string> = {
+  claude: DEFAULT_SNAPSHOT_MODELS.anthropic,
+  gemini: DEFAULT_SNAPSHOT_MODELS.google,
+  google: DEFAULT_SNAPSHOT_MODELS.google,
+};
+
+const CONFIGURE_PROVIDERS = [
+  "openai",
+  "anthropic",
+  "gemini",
+  "vertex",
+] as const;
+
+function formatConfigureProviders(separator = " | "): string {
+  return CONFIGURE_PROVIDERS.join(separator);
+}
+
+function printAiConfig(config: AiConfig, configPath: string): void {
+  console.log(`Model: ${config.model}`);
+  console.log(`Config file: ${configPath}`);
+  console.log(`Updated at: ${config.updatedAt}`);
+}
+
+/**
+ * Resolve the model string from a `ai configure` argument.
+ * Accepts a provider shorthand ("openai", "anthropic", "gemini", "vertex")
+ * or a full provider/model-id string ("openai/gpt-4o", "anthropic/claude-sonnet-4-6").
+ */
+function resolveModelFromInput(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  // Full model string (contains a slash)
+  if (trimmed.includes("/")) return trimmed;
+
+  // Provider shorthand
+  const normalized = trimmed.toLowerCase();
+  return (
+    (DEFAULT_SNAPSHOT_MODELS as Record<string, string>)[normalized] ??
+    PROVIDER_ALIASES[normalized] ??
+    null
+  );
+}
+
+export function runAiConfigure(
+  input: {
+    preset?: string;
+    clear?: boolean;
+  },
+  options: {
+    configureCommandName?: string;
+    configPath?: string;
+  } = {},
+): void {
+  const configureCommandName =
+    options.configureCommandName ?? "npx libretto ai configure";
+  const configPath = options.configPath ?? LIBRETTO_CONFIG_PATH;
+
+  const presetArg = input.preset?.trim();
+
+  if (!presetArg && !input.clear) {
+    const config = readAiConfig(configPath);
+    if (!config) {
+      console.log(
+        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`,
+      );
+      console.log(
+        "Provider credentials still come from your shell or .env file.",
+      );
+      return;
+    }
+    printAiConfig(config, configPath);
+    return;
+  }
+
+  if (input.clear) {
+    const removed = clearAiConfig(configPath);
+    if (removed) {
+      console.log(`Cleared AI config: ${configPath}`);
+    } else {
+      console.log("No AI config was set.");
+    }
+    return;
+  }
+
+  const model = resolveModelFromInput(presetArg!);
+  if (!model) {
+    console.log(
+      `Usage: ${configureCommandName} <${CONFIGURE_PROVIDERS.join("|")}|provider/model-id>\n` +
+        `       ${configureCommandName}\n` +
+        `       ${configureCommandName} --clear`,
+    );
+    throw new Error(
+      `Invalid provider or model. Use one of: ${formatConfigureProviders()}, or a full model string like "openai/gpt-4o".`,
+    );
+  }
+
+  const config = writeAiConfig(model, configPath);
+  console.log("AI config saved.");
+  printAiConfig(config, configPath);
+}
+
 export const aiConfigureInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("preset", z.string().optional(), {

package/src/cli/commands/browser.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 import {
   runClose as runCloseWithLogger,
   runCloseAll as runCloseAllWithLogger,
@@ -7,11 +8,15 @@ import {
   runPages,
   runSave,
 } from "../core/browser.js";
+import { readLibrettoConfig } from "../core/config.js";
 import { createLoggerForSession, withSessionLogger } from "../core/context.js";
 import {
+  type SessionAccessMode,
   assertSessionAvailableForStart,
+  setSessionMode,
   validateSessionName,
 } from "../core/session.js";
+import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   sessionOption,
@@ -42,6 +47,13 @@ export function parseViewportArg(
   return { width, height };
 }
 
+function resolveRequestedSessionMode(readOnly: boolean | undefined, writeAccess: boolean | undefined): SessionAccessMode {
+  if (readOnly) return "read-only";
+  if (writeAccess) return "write-access";
+  const config = readLibrettoConfig();
+  return config.sessionMode ?? "write-access";
+}
+
 export const openInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("url", z.string().optional(), {
@@ -52,6 +64,14 @@ export const openInput = SimpleCLI.input({
     session: sessionOption(),
     headed: SimpleCLI.flag({ help: "Run browser in headed mode" }),
     headless: SimpleCLI.flag({ help: "Run browser in headless mode" }),
+    readOnly: SimpleCLI.flag({
+      name: "read-only",
+      help: "Create the session in read-only mode",
+    }),
+    writeAccess: SimpleCLI.flag({
+      name: "write-access",
+      help: "Create the session in write-access mode (overrides config default)",
+    }),
     viewport: SimpleCLI.option(z.string().optional(), {
       help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)",
     }),
@@ -59,11 +79,15 @@ export const openInput = SimpleCLI.input({
 })
   .refine(
     (input) => Boolean(input.url),
-    `Usage: libretto open <url> [--headless] [--viewport WxH] [--session <name>]`,
+    `Usage: libretto open <url> [--headless] [--read-only|--write-access] [--viewport WxH] [--session <name>]`,
   )
   .refine(
     (input) => !(input.headed && input.headless),
     "Cannot pass both --headed and --headless.",
+  )
+  .refine(
+    (input) => !(input.readOnly && input.writeAccess),
+    "Cannot pass both --read-only and --write-access.",
   );
 
 export const openCommand = SimpleCLI.command({
@@ -72,10 +96,14 @@ export const openCommand = SimpleCLI.command({
   .input(openInput)
   .use(withAutoSession())
   .handle(async ({ input, ctx }) => {
+    warnIfInstalledSkillOutOfDate();
     assertSessionAvailableForStart(ctx.session, ctx.logger);
     const headed = input.headed || !input.headless;
     const viewport = parseViewportArg(input.viewport);
-    await runOpen(input.url!, headed, ctx.session, ctx.logger, { viewport });
+    await runOpen(input.url!, headed, ctx.session, ctx.logger, {
+      viewport,
+      accessMode: resolveRequestedSessionMode(input.readOnly, input.writeAccess),
+    });
   });
 
 export const connectInput = SimpleCLI.input({
@@ -86,11 +114,24 @@ export const connectInput = SimpleCLI.input({
   ],
   named: {
     session: sessionOption(),
+    readOnly: SimpleCLI.flag({
+      name: "read-only",
+      help: "Create the session in read-only mode",
+    }),
+    writeAccess: SimpleCLI.flag({
+      name: "write-access",
+      help: "Create the session in write-access mode (overrides config default)",
+    }),
   },
-}).refine(
-  (input) => Boolean(input.cdpUrl),
-  `Usage: libretto connect <cdp-url> --session <name>`,
-);
+})
+  .refine(
+    (input) => Boolean(input.cdpUrl),
+    `Usage: libretto connect <cdp-url> [--read-only|--write-access] --session <name>`,
+  )
+  .refine(
+    (input) => !(input.readOnly && input.writeAccess),
+    "Cannot pass both --read-only and --write-access.",
+  );
 
 export const connectCommand = SimpleCLI.command({
   description: "Connect to an existing Chrome DevTools Protocol (CDP) endpoint",
@@ -98,7 +139,13 @@ export const connectCommand = SimpleCLI.command({
   .input(connectInput)
   .use(withAutoSession())
   .handle(async ({ input, ctx }) => {
-    await runConnectWithLogger(input.cdpUrl!, ctx.session, ctx.logger);
+    warnIfInstalledSkillOutOfDate();
+    await runConnectWithLogger(
+      input.cdpUrl!,
+      ctx.session,
+      ctx.logger,
+      resolveRequestedSessionMode(input.readOnly, input.writeAccess),
+    );
   });
 
 export const saveInput = SimpleCLI.input({
@@ -140,6 +187,32 @@ export const pagesCommand = SimpleCLI.command({
     await runPages(ctx.session, ctx.logger);
   });
 
+export const sessionModeInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("mode", SessionAccessModeSchema.optional(), {
+      help: "Session mode to set",
+    }),
+  ],
+  named: {
+    session: sessionOption(),
+  },
+});
+
+export const sessionModeCommand = SimpleCLI.command({
+  description: "View or set the session access mode",
+})
+  .input(sessionModeInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    if (!input.mode) {
+      console.log(`Session "${ctx.session}" mode: ${ctx.sessionState.mode}`);
+      return;
+    }
+
+    const nextState = setSessionMode(ctx.session, input.mode, ctx.logger);
+    console.log(`Session "${ctx.session}" mode set to ${nextState.mode}.`);
+  });
+
 export const closeInput = SimpleCLI.input({
   positionals: [],
   named: {
@@ -179,6 +252,7 @@ export const browserCommands = {
   connect: connectCommand,
   save: saveCommand,
   pages: pagesCommand,
+  "session-mode": sessionModeCommand,
   close: closeCommand,
 };
 

package/src/cli/commands/execution.ts

@@ -14,16 +14,20 @@ import { parseViewportArg } from "./browser.js";
 import { getPauseSignalPaths } from "../core/pause-signals.js";
 import {
   assertSessionAvailableForStart,
+  assertSessionAllowsCommand,
   clearSessionState,
   readSessionState,
   setSessionStatus,
   type SessionState,
 } from "../core/session.js";
+import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
 import {
   readActionLog,
   readNetworkLog,
   wrapPageForActionLogging,
 } from "../core/telemetry.js";
+import { readLibrettoConfig } from "../core/config.js";
+import { createReadonlyExecHelpers } from "../core/readonly-exec.js";
 import type { RunIntegrationWorkerRequest } from "../workers/run-integration-worker-protocol.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
@@ -37,6 +41,7 @@ type ExecFunction = (...args: unknown[]) => Promise<unknown>;
 type RunIntegrationCommandRequest = RunIntegrationWorkerRequest & {
   tsconfigPath?: string;
 };
+type ExecMode = "exec" | "readonly-exec";
 
 type StripTypeScriptTypesFn = (
   code: string,
@@ -202,14 +207,20 @@ async function runExec(
   code: string,
   session: string,
   logger: LoggerApi,
-  visualize = false,
-  pageId?: string,
+  options: {
+    visualize?: boolean;
+    pageId?: string;
+    mode?: ExecMode;
+  } = {},
 ): Promise<void> {
+  const visualize = options.visualize ?? false;
+  const pageId = options.pageId;
+  const mode = options.mode ?? "exec";
   const { cleaned: cleanedCode, strippedCount } = stripEmptyCatchHandlers(code);
   if (strippedCount > 0) {
     console.log("(Stripped `.catch(() => {})` — letting errors bubble up)");
   }
-  logger.info("exec-start", {
+  logger.info(`${mode}-start`, {
     session,
     codeLength: cleanedCode.length,
     codePreview: cleanedCode.slice(0, 200),
@@ -235,20 +246,20 @@ async function runExec(
   const stallInterval = setInterval(() => {
     const silenceMs = Date.now() - lastActivityTs;
     if (silenceMs >= STALL_THRESHOLD_MS) {
-      logger.warn("exec-stall-warning", {
+      logger.warn(`${mode}-stall-warning`, {
         session,
         silenceMs,
         codePreview: cleanedCode.slice(0, 200),
       });
       console.warn(
-        `[stall-warning] No Playwright activity for ${Math.round(silenceMs / 1000)}s — exec may be hung (code: ${cleanedCode.slice(0, 100)}...)`,
+        `[stall-warning] No Playwright activity for ${Math.round(silenceMs / 1000)}s — ${mode} may be hung (code: ${cleanedCode.slice(0, 100)}...)`,
       );
     }
   }, STALL_THRESHOLD_MS);
 
   const execStartTs = Date.now();
   const sigintHandler = () => {
-    logger.info("exec-interrupted", {
+    logger.info(`${mode}-interrupted`, {
       session,
       duration: Date.now() - execStartTs,
       codePreview: cleanedCode.slice(0, 200),
@@ -256,60 +267,67 @@ async function runExec(
   };
   process.on("SIGINT", sigintHandler);
 
-  wrapPageForActionLogging(page, session, resolvedPageId, onActivity);
+  if (mode === "exec") {
+    wrapPageForActionLogging(page, session, resolvedPageId, onActivity);
+  }
 
-  if (visualize) {
+  if (visualize && mode === "exec") {
     await installInstrumentation(page, { visualize: true, logger });
   }
 
   try {
-    const execState: Record<string, unknown> = {};
-
-    const networkLog = (
-      opts: {
-        last?: number;
-        filter?: string;
-        method?: string;
-        pageId?: string;
-      } = {},
-    ) => {
-      return readNetworkLog(session, opts);
-    };
-
-    const actionLog = (
-      opts: {
-        last?: number;
-        filter?: string;
-        action?: string;
-        source?: string;
-        pageId?: string;
-      } = {},
-    ) => {
-      return readActionLog(session, opts);
-    };
-
-    const helpers = {
-      page,
-      context,
-      state: execState,
-      browser,
-      networkLog,
-      actionLog,
-      console,
-      setTimeout,
-      setInterval,
-      clearTimeout,
-      clearInterval,
-      fetch,
-      URL,
-      Buffer,
-    };
+    const helpers =
+      mode === "readonly-exec"
+        ? createReadonlyExecHelpers(page, { onActivity })
+        : (() => {
+            const execState: Record<string, unknown> = {};
+
+            const networkLog = (
+              opts: {
+                last?: number;
+                filter?: string;
+                method?: string;
+                pageId?: string;
+              } = {},
+            ) => {
+              return readNetworkLog(session, opts);
+            };
+
+            const actionLog = (
+              opts: {
+                last?: number;
+                filter?: string;
+                action?: string;
+                source?: string;
+                pageId?: string;
+              } = {},
+            ) => {
+              return readActionLog(session, opts);
+            };
+
+            return {
+              page,
+              context,
+              state: execState,
+              browser,
+              networkLog,
+              actionLog,
+              console,
+              setTimeout,
+              setInterval,
+              clearTimeout,
+              clearInterval,
+              fetch,
+              URL,
+              Buffer,
+            };
+          })();
 
     const helperNames = Object.keys(helpers);
     const fn = compileExecFunction(cleanedCode, helperNames);
 
     const result = await fn(...Object.values(helpers));
-    logger.info("exec-success", { session, hasResult: result !== undefined });
+    logger.info(`${mode}-success`, { session, hasResult: result !== undefined });
     if (result !== undefined) {
       console.log(
         typeof result === "string" ? result : JSON.stringify(result, null, 2),
@@ -318,7 +336,7 @@ async function runExec(
       console.log("Executed successfully");
     }
   } catch (err) {
-    logger.error("exec-error", {
+    logger.error(`${mode}-error`, {
       error: err,
       session,
       codePreview: cleanedCode.slice(0, 200),
@@ -605,13 +623,13 @@ async function runIntegrationFromFile(
   );
   const payload = JSON.stringify({
     integrationPath: args.integrationPath,
-    workflowName: args.workflowName,
     session: args.session,
     params: args.params,
     headless: args.headless,
     visualize: args.visualize,
     authProfileDomain: args.authProfileDomain,
     viewport: args.viewport,
+    accessMode: args.accessMode,
   } satisfies RunIntegrationWorkerRequest);
   const worker = spawn(
     process.execPath,
@@ -690,6 +708,7 @@ export const execCommand = SimpleCLI.command({
   .input(execInput)
   .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
+    assertSessionAllowsCommand(ctx.sessionState, "exec", ["write-access"]);
     const code = input.code!;
     const codeFromArgsOrStdin = code === "-" ? readStdinSync() : code;
     if (codeFromArgsOrStdin === null) {
@@ -701,21 +720,55 @@ export const execCommand = SimpleCLI.command({
       codeFromArgsOrStdin,
       ctx.session,
       ctx.logger,
-      input.visualize,
-      input.page,
+      {
+        visualize: input.visualize,
+        pageId: input.page,
+        mode: "exec",
+      },
     );
   });
 
-const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
+export const readonlyExecInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("code", z.string().optional(), {
+      help: "Read-only Playwright TypeScript code to execute",
+    }),
+  ],
+  named: {
+    session: sessionOption(),
+    page: pageOption(),
+  },
+}).refine(
+  (input) => input.code !== undefined,
+  `Usage: libretto readonly-exec <code|-> [--session <name>] [--page <id>]\n       echo '<code>' | libretto readonly-exec - [--session <name>] [--page <id>]`,
+);
+
+export const readonlyExecCommand = SimpleCLI.command({
+  description: "Execute read-only Playwright inspection code",
+})
+  .input(readonlyExecInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    const code = input.code!;
+    const codeFromArgsOrStdin = code === "-" ? readStdinSync() : code;
+    if (codeFromArgsOrStdin === null) {
+      throw new Error(
+        "Missing stdin input for `readonly-exec -`. Pipe inspection code into stdin.",
+      );
+    }
+    await runExec(codeFromArgsOrStdin, ctx.session, ctx.logger, {
+      pageId: input.page,
+      mode: "readonly-exec",
+    });
+  });
+
+const runUsage = `Usage: libretto run <integrationFile> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--read-only|--write-access] [--no-visualize] [--viewport WxH]`;
 
 export const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {
       help: "Path to the integration file",
     }),
-    SimpleCLI.positional("workflowName", z.string().optional(), {
-      help: "Workflow name to run (from workflow(name, handler))",
-    }),
   ],
   named: {
     session: sessionOption(),
@@ -731,6 +784,14 @@ export const runInput = SimpleCLI.input({
     }),
     headed: SimpleCLI.flag({ help: "Run in headed mode" }),
     headless: SimpleCLI.flag({ help: "Run in headless mode" }),
+    readOnly: SimpleCLI.flag({
+      name: "read-only",
+      help: "Create the session in read-only mode",
+    }),
+    writeAccess: SimpleCLI.flag({
+      name: "write-access",
+      help: "Create the session in write-access mode (overrides config default)",
+    }),
     noVisualize: SimpleCLI.flag({
       name: "no-visualize",
       help: "Disable ghost cursor + highlight visualization in headed mode",
@@ -745,7 +806,7 @@ export const runInput = SimpleCLI.input({
   },
 })
   .refine(
-    (input) => Boolean(input.integrationFile && input.workflowName),
+    (input) => Boolean(input.integrationFile),
     runUsage,
   )
   .refine(
@@ -755,6 +816,10 @@ export const runInput = SimpleCLI.input({
   .refine(
     (input) => !(input.headed && input.headless),
     "Cannot pass both --headed and --headless.",
+  )
+  .refine(
+    (input) => !(input.readOnly && input.writeAccess),
+    "Cannot pass both --read-only and --write-access.",
   );
 
 function resolveRunParams(
@@ -779,11 +844,12 @@ function resolveRunParams(
 }
 
 export const runCommand = SimpleCLI.command({
-  description: "Run an exported Libretto workflow from a file",
+  description: "Run the default-exported Libretto workflow from a file",
 })
   .input(runInput)
   .use(withAutoSession())
   .handle(async ({ input, ctx }) => {
+    warnIfInstalledSkillOutOfDate();
     await stopExistingFailedRunSession(ctx.session, ctx.logger);
     assertSessionAvailableForStart(ctx.session, ctx.logger);
 
@@ -802,7 +868,6 @@ export const runCommand = SimpleCLI.command({
     await runIntegrationFromFile(
       {
         integrationPath: input.integrationFile!,
-        workflowName: input.workflowName!,
         session: ctx.session,
         params,
         tsconfigPath: input.tsconfig,
@@ -810,6 +875,7 @@ export const runCommand = SimpleCLI.command({
         visualize,
         authProfileDomain: input.authProfile,
         viewport,
+        accessMode: input.readOnly ? "read-only" : input.writeAccess ? "write-access" : (readLibrettoConfig().sessionMode ?? "write-access"),
       },
       ctx.logger,
     );
@@ -833,6 +899,7 @@ export const resumeCommand = SimpleCLI.command({
 
 export const executionCommands = {
   exec: execCommand,
+  "readonly-exec": readonlyExecCommand,
   run: runCommand,
   resume: resumeCommand,
 };