libretto 0.5.4 → 0.5.6

package/src/{shared/llm/client.ts → cli/core/resolve-model.ts}

@@ -1,6 +1,4 @@
-import { generateObject, type LanguageModel, type ModelMessage } from "ai";
-import type { ZodType, output as ZodOutput } from "zod";
-import type { LLMClient, Message, MessageContentPart } from "./types.js";
+import type { LanguageModel } from "ai";
 
 export type Provider = "google" | "vertex" | "anthropic" | "openai";
 
@@ -138,87 +136,7 @@ async function getProviderModel(
   }
 }
 
-function convertUserContentParts(parts: MessageContentPart[]) {
-  return parts.map((part) => {
-    if (part.type === "text") {
-      return { type: "text" as const, text: part.text };
-    }
-    return {
-      type: "image" as const,
-      image: part.image,
-      ...(part.mediaType ? { mediaType: part.mediaType } : {}),
-    };
-  });
-}
-
-function convertAssistantContentParts(parts: MessageContentPart[]) {
-  return parts
-    .filter(
-      (part): part is MessageContentPart & { type: "text" } =>
-        part.type === "text",
-    )
-    .map((part) => ({ type: "text" as const, text: part.text }));
-}
-
-function convertMessages(messages: Message[]): ModelMessage[] {
-  return messages.map((msg): ModelMessage => {
-    if (msg.role === "user") {
-      if (typeof msg.content === "string") {
-        return { role: "user", content: msg.content };
-      }
-      return {
-        role: "user",
-        content: convertUserContentParts(msg.content),
-      };
-    }
-    if (typeof msg.content === "string") {
-      return { role: "assistant", content: msg.content };
-    }
-    return {
-      role: "assistant",
-      content: convertAssistantContentParts(msg.content),
-    };
-  });
-}
-
-export function createLLMClient(model: string): LLMClient {
+export async function resolveModel(model: string): Promise<LanguageModel> {
   const { provider, modelId } = parseModel(model);
-  let modelPromise: Promise<LanguageModel> | null = null;
-
-  const getModel = () => {
-    modelPromise ??= getProviderModel(provider, modelId);
-    return modelPromise;
-  };
-
-  return {
-    async generateObject<T extends ZodType>(opts: {
-      prompt: string;
-      schema: T;
-      temperature?: number;
-    }): Promise<ZodOutput<T>> {
-      const aiModel = await getModel();
-      const result = await generateObject({
-        model: aiModel,
-        prompt: opts.prompt,
-        schema: opts.schema,
-        temperature: opts.temperature ?? 0,
-      });
-      return result.object as ZodOutput<T>;
-    },
-
-    async generateObjectFromMessages<T extends ZodType>(opts: {
-      messages: Message[];
-      schema: T;
-      temperature?: number;
-    }): Promise<ZodOutput<T>> {
-      const aiModel = await getModel();
-      const result = await generateObject({
-        model: aiModel,
-        messages: convertMessages(opts.messages),
-        schema: opts.schema,
-        temperature: opts.temperature ?? 0,
-      });
-      return result.object as ZodOutput<T>;
-    },
-  };
+  return getProviderModel(provider, modelId);
 }

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,
@@ -14,7 +14,11 @@ import {
 } from "../../index.js";
 import type { LoggerApi } from "../../shared/logger/index.js";
 import { parseSessionStateContent } from "../../shared/state/index.js";
-import { getProfilePath, normalizeDomain } from "../core/browser.js";
+import {
+  getProfilePath,
+  normalizeDomain,
+  normalizeUrl,
+} from "../core/browser.js";
 import {
   getSessionActionsLogPath,
   getSessionDir,
@@ -109,23 +113,18 @@ async function waitForFailureSessionRelease(args: {
   }
 }
 
-function resolveLocalAuthProfilePath(domain: string): string {
-  return getProfilePath(normalizeDomain(domain));
-}
-
 function getMissingLocalAuthProfileError(args: {
-  domain: string;
+  normalizedDomain: string;
   profilePath: string;
   session: string;
 }): string {
-  const normalizedDomain = normalizeDomain(args.domain);
   return [
-    `Local auth profile not found for domain "${normalizedDomain}".`,
+    `Local auth profile not found for domain "${args.normalizedDomain}".`,
     `Expected profile file: ${args.profilePath}`,
     "To create it:",
-    `  1. libretto open https://${normalizedDomain} --headed --session ${args.session}`,
+    `  1. libretto open https://${args.normalizedDomain} --headed --session ${args.session}`,
     "  2. Log in manually in the browser window.",
-    `  3. libretto save ${normalizedDomain} --session ${args.session}`,
+    `  3. libretto save ${args.normalizedDomain} --session ${args.session}`,
   ].join("\n");
 }
 
@@ -139,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 {
@@ -157,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(", ")}`,
   );
 }
 
@@ -195,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);
@@ -204,24 +203,31 @@ 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,
   });
 
   // Resolve auth profile from CLI flag (--auth-profile <domain>)
   const authProfileDomain = args.authProfileDomain;
-  const storageStatePath = authProfileDomain
-    ? resolveLocalAuthProfilePath(authProfileDomain)
+  const normalizedAuthProfileDomain = authProfileDomain
+    ? normalizeDomain(normalizeUrl(authProfileDomain))
+    : undefined;
+  const storageStatePath = normalizedAuthProfileDomain
+    ? getProfilePath(normalizedAuthProfileDomain)
     : undefined;
-  if (authProfileDomain && storageStatePath && !existsSync(storageStatePath)) {
+  if (
+    normalizedAuthProfileDomain &&
+    storageStatePath &&
+    !existsSync(storageStatePath)
+  ) {
     throw new Error(
       getMissingLocalAuthProfileError({
-        domain: authProfileDomain,
+        normalizedDomain: normalizedAuthProfileDomain,
         profilePath: storageStatePath,
         session: args.session,
       }),
@@ -232,6 +238,7 @@ async function runIntegrationInternal(
     headless: args.headless,
     storageStatePath,
     viewport: args.viewport,
+    accessMode: args.accessMode,
   });
   if (!args.headless && args.visualize !== false) {
     await installHeadedWorkflowVisualization({
@@ -255,7 +262,6 @@ async function runIntegrationInternal(
 
   const workflowContext: LibrettoWorkflowContext = {
     session: args.session,
-    logger: integrationLogger,
     page: browserSession.page,
   };
 
@@ -290,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: [
         {