libretto 0.5.5 → 0.5.6

package/src/cli/core/session.ts

@@ -14,9 +14,11 @@ import {
   LIBRETTO_SESSIONS_DIR,
 } from "./context.js";
 import {
+  SessionAccessModeSchema,
   SESSION_STATE_VERSION,
   parseSessionStateContent,
   serializeSessionState,
+  type SessionAccessMode,
   type SessionStatus,
   type SessionState,
 } from "../../shared/state/index.js";
@@ -35,7 +37,13 @@ export function generateSessionName(): string {
   return `ses-${id}`;
 }
 export { SESSION_STATE_VERSION };
-export type { SessionStatus, SessionState };
+export type { SessionAccessMode, SessionStatus, SessionState };
+
+export function resolveSessionAccessMode(
+  state: Pick<SessionState, "mode"> | null | undefined,
+): SessionAccessMode {
+  return SessionAccessModeSchema.parse(state?.mode);
+}
 
 export function logFileForSession(session: string): string {
   validateSessionName(session);
@@ -111,6 +119,22 @@ function listActiveSessions(): string[] {
   return listSessionsWithStateFile();
 }
 
+/**
+ * List sessions whose state file exists and whose pid is still running.
+ * Returns session states (not just names) so callers can access port, status, etc.
+ */
+export function listRunningSessions(): SessionState[] {
+  const sessions = listSessionsWithStateFile();
+  const running: SessionState[] = [];
+  for (const name of sessions) {
+    const state = readSessionState(name);
+    if (!state) continue;
+    if (state.pid == null || !isPidRunning(state.pid)) continue;
+    running.push(state);
+  }
+  return running;
+}
+
 function throwSessionNotFoundError(session: string): never {
   const active = listActiveSessions();
   const lines = [`No session "${session}" found.`];
@@ -165,11 +189,47 @@ export function writeSessionState(
   logger?.info("session-state-write", {
     session: state.session,
     stateFile,
+    mode: state.mode,
     port: state.port,
     pid: state.pid,
   });
 }
 
+export function setSessionMode(
+  session: string,
+  mode: SessionAccessMode,
+  logger?: LoggerApi,
+): SessionState {
+  const state = readSessionStateOrThrow(session);
+  const normalizedMode = SessionAccessModeSchema.parse(mode);
+  if (state.mode === normalizedMode) {
+    return state;
+  }
+
+  const nextState = {
+    ...state,
+    mode: normalizedMode,
+  };
+  writeSessionState(nextState, logger);
+  return nextState;
+}
+
+export function assertSessionAllowsCommand(
+  state: SessionState,
+  commandName: string,
+  allowedModes: readonly SessionAccessMode[],
+): void {
+  const mode = resolveSessionAccessMode(state);
+  if (allowedModes.includes(mode)) {
+    return;
+  }
+
+  const supportedModes = [...allowedModes].join(", ");
+  throw new Error(
+    `Command "${commandName}" is blocked for session "${state.session}" because it is in ${mode} mode. Allowed modes for this command: ${supportedModes}. Run \`libretto session-mode write-access --session ${state.session}\` to unlock the session.`,
+  );
+}
+
 export function clearSessionState(session: string, logger?: LoggerApi): void {
   const stateFile = getStateFilePath(session);
   if (!existsSync(stateFile)) {
@@ -180,7 +240,7 @@ export function clearSessionState(session: string, logger?: LoggerApi): void {
   logger?.info("session-state-cleared", { session, stateFile });
 }
 
-function isPidRunning(pid: number): boolean {
+export function isPidRunning(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;

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

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { REPO_ROOT } from "./context.js";
+
+type PackageManifest = {
+  version?: string;
+};
+
+const INSTALLED_SKILL_PATHS = [
+  [".agents", "skills", "libretto", "SKILL.md"],
+  [".claude", "skills", "libretto", "SKILL.md"],
+] as const;
+
+let cachedCliVersion: string | null = null;
+
+function readCurrentCliVersion(): string {
+  if (cachedCliVersion) {
+    return cachedCliVersion;
+  }
+
+  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}.`,
+    );
+  }
+
+  cachedCliVersion = manifest.version;
+  return cachedCliVersion;
+}
+
+function readInstalledSkillVersion(skillPath: string): string | null {
+  if (!existsSync(skillPath)) {
+    return null;
+  }
+
+  const contents = readFileSync(skillPath, "utf8");
+  const frontmatterMatch = contents.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch) {
+    return null;
+  }
+
+  const metadataBlock = frontmatterMatch[1].match(
+    /^metadata:\s*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m,
+  )?.[1];
+  if (!metadataBlock) {
+    return null;
+  }
+
+  const versionMatch = metadataBlock.match(
+    /^[ \t]+version:\s*["']?([^"'\r\n]+)["']?\s*$/m,
+  );
+  return versionMatch?.[1]?.trim() ?? null;
+}
+
+function findInstalledSkillVersionMismatch(): {
+  installedVersion: string;
+  cliVersion: string;
+} | null {
+  const cliVersion = readCurrentCliVersion();
+
+  for (const relativePathParts of INSTALLED_SKILL_PATHS) {
+    const skillPath = join(REPO_ROOT, ...relativePathParts);
+    const installedVersion = readInstalledSkillVersion(skillPath);
+    if (installedVersion && installedVersion !== cliVersion) {
+      return { installedVersion, cliVersion };
+    }
+  }
+
+  return null;
+}
+
+export function warnIfInstalledSkillOutOfDate(): void {
+  try {
+    const mismatch = findInstalledSkillVersionMismatch();
+    if (!mismatch) {
+      return;
+    }
+
+    console.error(
+      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`npx libretto setup\` to update your skills to the correct version.`,
+    );
+  } catch {
+    // Never block command execution on a best-effort skill version check.
+  }
+}

package/src/cli/core/telemetry.ts

@@ -2,7 +2,6 @@ import {
   appendFileSync,
   existsSync,
   readFileSync,
-  writeFileSync,
 } from "node:fs";
 import type { Page } from "playwright";
 import {
@@ -65,31 +64,6 @@ export function readNetworkLog(
   return entries;
 }
 
-export function formatNetworkEntry(e: NetworkLogEntry): string {
-  const time = e.ts.replace(/.*T/, "").replace(/\.\d+Z$/, "");
-  const duration = e.durationMs != null ? `${e.durationMs}ms` : "?ms";
-  const size = e.size != null ? `${e.size}B` : "";
-  const parts = [
-    `[${time}]`,
-    `${e.status}`,
-    `${e.method.padEnd(6)}`,
-    e.url,
-    duration,
-    size,
-  ].filter(Boolean);
-  let line = parts.join(" ");
-  if (e.postData) {
-    line += `\n         body: ${e.postData.substring(0, 120)}${e.postData.length > 120 ? "..." : ""}`;
-  }
-  return line;
-}
-
-export function clearNetworkLog(session: string): void {
-  assertSessionStateExistsOrThrow(session);
-  const logPath = getSessionNetworkLogPath(session);
-  writeFileSync(logPath, "");
-}
-
 export type ActionLogEntry = {
   ts: string;
   pageId?: string;
@@ -182,32 +156,6 @@ export function readActionLog(
   return entries;
 }
 
-export function formatActionEntry(e: ActionLogEntry): string {
-  const time = e.ts.replace(/.*T/, "").replace(/\.\d+Z$/, "");
-  const src = e.source.toUpperCase().padEnd(5);
-  const displaySelector = e.bestSemanticSelector || e.selector;
-  const parts = [`[${time}]`, `[${src}]`, e.action];
-  if (displaySelector) parts.push(displaySelector);
-  if (e.targetSelector && e.targetSelector !== displaySelector) {
-    parts.push(`target=${e.targetSelector}`);
-  }
-  if (e.nearbyText) parts.push(`text="${e.nearbyText}"`);
-  if (e.coordinates) {
-    parts.push(`@(${e.coordinates.x},${e.coordinates.y})`);
-  }
-  if (e.value) parts.push(`"${e.value}"`);
-  if (e.url) parts.push(e.url);
-  if (e.duration != null) parts.push(`${e.duration}ms`);
-  if (!e.success) parts.push(`ERROR: ${e.error || "unknown"}`);
-  return parts.join(" ");
-}
-
-export function clearActionLog(session: string): void {
-  assertSessionStateExistsOrThrow(session);
-  const logPath = getSessionActionsLogPath(session);
-  writeFileSync(logPath, "");
-}
-
 const LOCATOR_ACTION_METHODS = [
   "click",
   "dblclick",

package/src/cli/index.ts

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
 import { runLibrettoCLI } from "./cli.js";
-import {
-  maybeConfigureLLMClientFactoryFromEnv,
-  setLLMClientFactory,
-} from "./core/context.js";
 
-export { setLLMClientFactory };
 export { runClose } from "./commands/browser.js";
 export { runLibrettoCLI };
 
-maybeConfigureLLMClientFactoryFromEnv();
 void runLibrettoCLI();

package/src/cli/router.ts

@@ -2,8 +2,8 @@ import { aiCommands } from "./commands/ai.js";
 import { browserCommands } from "./commands/browser.js";
 import { deployCommand } from "./commands/deploy.js";
 import { executionCommands } from "./commands/execution.js";
-import { initCommand } from "./commands/init.js";
-import { logCommands } from "./commands/logs.js";
+import { setupCommand } from "./commands/setup.js";
+import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
 import { SimpleCLI } from "./framework/simple-cli.js";
 
@@ -11,9 +11,9 @@ export const cliRoutes = {
   ...browserCommands,
   deploy: deployCommand,
   ...executionCommands,
-  ...logCommands,
   ai: aiCommands,
-  init: initCommand,
+  setup: setupCommand,
+  status: statusCommand,
   snapshot: snapshotCommand,
 };
 

package/src/cli/workers/run-integration-runtime.ts

@@ -5,7 +5,7 @@ import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
-  getWorkflowFromModuleExports,
+  getDefaultWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
   instrumentContext,
   launchBrowser,
@@ -138,9 +138,8 @@ function getAbsoluteIntegrationPath(integrationPath: string): string {
   return absolutePath;
 }
 
-async function loadWorkflowByName(
+async function loadDefaultWorkflow(
   absolutePath: string,
-  workflowName: string,
 ): Promise<LoadedLibrettoWorkflow> {
   let loadedModule: Record<string, unknown>;
   try {
@@ -156,22 +155,23 @@ async function loadWorkflowByName(
     );
   }
 
-  const workflow = getWorkflowFromModuleExports(loadedModule, workflowName);
-  if (workflow) {
-    return workflow as LoadedLibrettoWorkflow;
+  const defaultWorkflow = getDefaultWorkflowFromModuleExports(loadedModule);
+  if (defaultWorkflow) {
+    return defaultWorkflow as LoadedLibrettoWorkflow;
   }
 
-  const availableWorkflows = getWorkflowsFromModuleExports(loadedModule).map(
+  const availableWorkflowNames = getWorkflowsFromModuleExports(loadedModule).map(
     (candidate) => candidate.name,
   );
 
-  const detail =
-    availableWorkflows.length > 0
-      ? ` Available workflows: ${availableWorkflows.join(", ")}`
-      : ' No workflows found in this file. Export a workflow() instance from "libretto" directly or via `export const workflows = { ... }`.';
+  if (availableWorkflowNames.length === 0) {
+    throw new Error(
+      `No default-exported workflow found in ${absolutePath}. Export the workflow with \`export default workflow("name", handler)\`.`,
+    );
+  }
 
   throw new Error(
-    `Workflow "${workflowName}" not found in ${absolutePath}.${detail}`,
+    `No default-exported workflow found in ${absolutePath}. libretto run only uses the file's default export. Available named workflows: ${availableWorkflowNames.join(", ")}`,
   );
 }
 
@@ -194,7 +194,7 @@ async function runIntegrationInternal(
 ): Promise<RunIntegrationOutcome> {
   const { logger } = options;
   const absolutePath = getAbsoluteIntegrationPath(args.integrationPath);
-  const workflow = await loadWorkflowByName(absolutePath, args.workflowName);
+  const workflow = await loadDefaultWorkflow(absolutePath);
   const signalPaths = getPauseSignalPaths(args.session);
   await removeSignalIfExists(signalPaths.pausedSignalPath);
   await removeSignalIfExists(signalPaths.resumeSignalPath);
@@ -203,12 +203,12 @@ async function runIntegrationInternal(
   const restoreStdout = mirrorStdoutToFile(signalPaths.outputSignalPath);
 
   console.log(
-    `Running workflow "${args.workflowName}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
+    `Running workflow "${workflow.name}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
   );
 
   const integrationLogger = logger.withScope("integration-run", {
     integrationPath: absolutePath,
-    workflowName: args.workflowName,
+    workflowName: workflow.name,
     session: args.session,
   });
 
@@ -238,6 +238,7 @@ async function runIntegrationInternal(
     headless: args.headless,
     storageStatePath,
     viewport: args.viewport,
+    accessMode: args.accessMode,
   });
   if (!args.headless && args.visualize !== false) {
     await installHeadedWorkflowVisualization({
@@ -295,7 +296,6 @@ async function runIntegrationInternal(
       JSON.stringify({ completedAt: new Date().toISOString() }, null, 2),
       "utf8",
     );
-    console.log("Integration completed.");
     return { status: "completed" };
   } finally {
     restoreStdout();

package/src/cli/workers/run-integration-worker-protocol.ts

@@ -1,14 +1,15 @@
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 
 export const RunIntegrationWorkerRequestSchema = z.object({
   integrationPath: z.string().min(1),
-  workflowName: z.string().min(1),
   session: z.string().min(1),
   params: z.unknown(),
   headless: z.boolean(),
   visualize: z.boolean().default(true),
   authProfileDomain: z.string().optional(),
   viewport: z.object({ width: z.number(), height: z.number() }).optional(),
+  accessMode: SessionAccessModeSchema.default("write-access"),
 });
 
 export type RunIntegrationWorkerRequest = z.infer<

package/src/index.ts

@@ -16,13 +16,6 @@ export {
   jsonlConsoleSink,
 } from "./shared/logger/sinks.js";
 
-// LLM client interface
-export type {
-  LLMClient,
-  Message,
-  MessageContentPart,
-} from "./shared/llm/types.js";
-export { createLLMClientFromModel } from "./shared/llm/ai-sdk-adapter.js";
 export {
   SESSION_STATE_VERSION,
   SessionStatusSchema,
@@ -102,6 +95,7 @@ export {
 
 // Workflow helpers
 export {
+  getDefaultWorkflowFromModuleExports,
   getWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
   isLibrettoWorkflow,

package/src/runtime/extract/extract.ts

@@ -4,13 +4,13 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import { generateObject, type LanguageModel } from "ai";
 
 export type ExtractOptions<T extends z.ZodType> = {
   page: Page;
   instruction: string;
   schema: T;
-  llmClient: LLMClient;
+  model: LanguageModel;
   logger?: MinimalLogger;
   /** Optional CSS selector to scope extraction to a specific element. */
   selector?: string;
@@ -31,7 +31,7 @@ export async function extractFromPage<T extends z.ZodType>(
     schema,
     selector,
     logger = defaultLogger,
-    llmClient,
+    model,
   } = options;
 
   let screenshot: string;
@@ -79,7 +79,8 @@ ${domContent ? `Here is the HTML content for additional context:\n<html>\n${domC
 
 Extract the requested information from the screenshot and return it in the specified format. Be precise and only extract what is visible.`;
 
-  const result = await llmClient.generateObjectFromMessages({
+  const { object: result } = await generateObject({
+    model,
     schema,
     messages: [
       {
@@ -98,5 +99,5 @@ Extract the requested information from the screenshot and return it in the speci
     instruction: instruction.slice(0, 100),
   });
 
-  return result;
+  return result as z.infer<T>;
 }

package/src/runtime/recovery/agent.ts

@@ -3,7 +3,7 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import { generateObject, type LanguageModel } from "ai";
 
 type BrowserAction =
   | { type: "click"; x: number; y: number; button?: string }
@@ -183,9 +183,9 @@ export async function executeRecoveryAgent(
   page: Page,
   instruction: string,
   logger?: MinimalLogger,
-  llmClient?: LLMClient,
+  model?: LanguageModel,
 ): Promise<void> {
-  if (!llmClient) {
+  if (!model) {
     return;
   }
   const log = logger ?? defaultLogger;
@@ -213,7 +213,8 @@ export async function executeRecoveryAgent(
 
   const maxSteps = 3;
   for (let step = 1; step <= maxSteps; step++) {
-    const result = await llmClient.generateObjectFromMessages({
+    const { object: result } = await generateObject({
+      model,
       schema: recoveryActionSchema,
       messages: [
         {

package/src/runtime/recovery/errors.ts

@@ -3,7 +3,7 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import { generateObject, type LanguageModel } from "ai";
 import { z } from "zod";
 
 /**
@@ -47,7 +47,7 @@ export async function detectSubmissionError(
   page: Page,
   error: unknown,
   logContext: string,
-  llmClient: LLMClient,
+  model: LanguageModel,
   knownErrors: KnownSubmissionError[] = [],
   logger?: MinimalLogger,
 ): Promise<DetectedSubmissionError> {
@@ -109,7 +109,8 @@ IMPORTANT:
 
 ${domSnapshot ? `<dom_snapshot>\n${domSnapshot}\n</dom_snapshot>` : ""}`;
 
-  const result = await llmClient.generateObjectFromMessages({
+  const { object: result } = await generateObject({
+    model,
     schema: detectSubmissionErrorSchema,
     messages: [
       {

package/src/runtime/recovery/recovery.ts

@@ -3,7 +3,7 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import type { LanguageModel } from "ai";
 import { executeRecoveryAgent } from "./agent.js";
 
 /**
@@ -14,7 +14,7 @@ export async function attemptWithRecovery<T>(
   page: Page,
   fn: () => Promise<T>,
   logger?: MinimalLogger,
-  llmClient?: LLMClient,
+  model?: LanguageModel,
 ): Promise<T> {
   const log = logger ?? defaultLogger;
   try {
@@ -33,7 +33,7 @@ export async function attemptWithRecovery<T>(
       throw error;
     }
 
-    if (!llmClient) {
+    if (!model) {
       throw error;
     }
 
@@ -45,7 +45,7 @@ export async function attemptWithRecovery<T>(
       page,
       "Look at the page to see if there is a popup blocking the screen. If so, close the popup.",
       log,
-      llmClient,
+      model,
     );
 
     return await fn();

package/src/shared/debug/pause.ts

@@ -5,35 +5,16 @@ import {
   getPauseSignalPaths,
   removeSignalIfExists,
 } from "../../cli/core/pause-signals.js";
-import {
-  listSessionsWithStateFile,
-  readSessionState,
-} from "../../cli/core/session.js";
-
-function isPidRunning(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function getRunningSessions(): string[] {
-  return listSessionsWithStateFile().filter((candidate) => {
-    const state = readSessionState(candidate);
-    return state !== null && state.pid != null && isPidRunning(state.pid);
-  });
-}
+import { listRunningSessions } from "../../cli/core/session.js";
 
 function throwMissingSessionError(): never {
-  const runningSessions = getRunningSessions();
+  const runningSessions = listRunningSessions();
   const lines = ["pause(session) requires a non-empty session ID."];
 
   if (runningSessions.length > 0) {
     lines.push("", "Running sessions:");
-    for (const runningSession of runningSessions) {
-      lines.push(`  ${runningSession}`);
+    for (const s of runningSessions) {
+      lines.push(`  ${s.session}`);
     }
   }
 

package/src/shared/run/browser.ts

@@ -9,9 +9,10 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { ensureLibrettoSessionStatePath } from "../paths/paths.js";
 import {
   SESSION_STATE_VERSION,
+  type SessionAccessMode,
   SessionStateFileSchema,
 } from "../state/session-state.js";
-import { readLibrettoConfig } from "../../cli/core/ai-config.js";
+import { readLibrettoConfig } from "../../cli/core/config.js";
 
 async function pickFreePort(): Promise<number> {
   return await new Promise((resolve, reject) => {
@@ -34,6 +35,7 @@ export type LaunchBrowserArgs = {
   headless?: boolean;
   viewport?: { width: number; height: number };
   storageStatePath?: string;
+  accessMode?: SessionAccessMode;
 };
 
 export type BrowserSession = {
@@ -97,6 +99,7 @@ export async function launchBrowser({
   headless = false,
   viewport = { width: 1366, height: 768 },
   storageStatePath,
+  accessMode = "write-access",
 }: LaunchBrowserArgs): Promise<BrowserSession> {
   const debugPort = await pickFreePort();
   const windowPosition = headless ? undefined : resolveWindowPosition();
@@ -141,6 +144,7 @@ export async function launchBrowser({
         pid: process.pid,
         startedAt: new Date().toISOString(),
         status: "active",
+        mode: accessMode,
       },
       null,
       2,

package/src/shared/state/index.ts

@@ -1,10 +1,12 @@
 export {
+  SessionAccessModeSchema,
   SESSION_STATE_VERSION,
   SessionStatusSchema,
   SessionStateFileSchema,
   parseSessionStateData,
   parseSessionStateContent,
   serializeSessionState,
+  type SessionAccessMode,
   type SessionStatus,
   type SessionState,
   type SessionStateFile,