libretto 0.5.5 → 0.6.0

package/src/cli/core/providers/libretto-cloud.ts

@@ -0,0 +1,61 @@
+import type { ProviderApi } from "./types.js";
+
+export function createLibrettoCloudProvider(): ProviderApi {
+  const apiKey = process.env.LIBRETTO_API_KEY;
+  if (!apiKey)
+    throw new Error(
+      "LIBRETTO_API_KEY is required for the Libretto Cloud provider.",
+    );
+  const apiUrl = process.env.LIBRETTO_API_URL;
+  if (!apiUrl)
+    throw new Error(
+      "LIBRETTO_API_URL is required for the Libretto Cloud provider.",
+    );
+  const endpoint = apiUrl.replace(/\/$/, "");
+
+  return {
+    async createSession() {
+      const timeoutSeconds = Number(
+        process.env.LIBRETTO_TIMEOUT_SECONDS ?? 7200,
+      );
+      const resp = await fetch(`${endpoint}/v1/sessions/create`, {
+        method: "POST",
+        headers: {
+          "x-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ timeout_seconds: timeoutSeconds }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Libretto Cloud API error (${resp.status}): ${body}`,
+        );
+      }
+      const json = (await resp.json()) as {
+        session_id: string;
+        cdp_url: string;
+      };
+      return {
+        sessionId: json.session_id,
+        cdpEndpoint: json.cdp_url,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/v1/sessions/close`, {
+        method: "POST",
+        headers: {
+          "x-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ session_id: sessionId }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+    },
+  };
+}

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

@@ -0,0 +1,9 @@
+export type ProviderSession = {
+  sessionId: string; // remote session id for cleanup
+  cdpEndpoint: string; // CDP WebSocket URL
+};
+
+export type ProviderApi = {
+  createSession(): Promise<ProviderSession>;
+  closeSession(sessionId: string): Promise<void>;
+};

package/src/cli/core/readonly-exec.ts

@@ -0,0 +1,284 @@
+import type { Locator, Page } from "playwright";
+
+const PAGE_READ_METHODS = new Set([
+  "url",
+  "title",
+  "content",
+  "pageErrors",
+  "viewportSize",
+  "waitForLoadState",
+  "waitForRequest",
+  "waitForResponse",
+  "waitForURL",
+]);
+const PAGE_LOCATOR_FACTORY_METHODS = new Set([
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+]);
+
+const PAGE_ALLOWED_PROPERTIES = new Set<string>([]);
+
+const LOCATOR_READ_METHODS = new Set([
+  "textContent",
+  "innerText",
+  "allTextContents",
+  "allInnerTexts",
+  "ariaSnapshot",
+  "boundingBox",
+  "count",
+  "getAttribute",
+  "inputValue",
+  "isChecked",
+  "isDisabled",
+  "isEditable",
+  "isEnabled",
+  "isVisible",
+  "isHidden",
+  "waitFor",
+]);
+
+const LOCATOR_FACTORY_METHODS = new Set([
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "filter",
+  "and",
+  "or",
+  "first",
+  "last",
+  "nth",
+]);
+
+const LOCATOR_COLLECTION_FACTORY_METHODS = new Set(["all"]);
+
+const LOCATOR_SCROLL_METHODS = new Set(["scrollIntoViewIfNeeded"]);
+
+const LOCATOR_ALLOWED_PROPERTIES = new Set<string>([]);
+
+type ReadonlyExecOptions = {
+  onActivity?: () => void;
+};
+
+const readonlyPageCache = new WeakMap<Page, Page>();
+const readonlyLocatorCache = new WeakMap<Locator, Locator>();
+
+function markActivity(onActivity?: () => void): void {
+  onActivity?.();
+}
+
+export class ReadonlyExecDeniedError extends Error {
+  constructor(message: string) {
+    super(`ReadonlyExecDenied: ${message}`);
+    this.name = "ReadonlyExecDenied";
+  }
+}
+
+function denyOperation(targetName: "page" | "locator", method: string): never {
+  throw new ReadonlyExecDeniedError(
+    `${targetName}.${method} is blocked in readonly-exec`,
+  );
+}
+
+export function wrapLocatorForReadonlyExec(
+  locator: Locator,
+  options: ReadonlyExecOptions = {},
+): Locator {
+  const cached = readonlyLocatorCache.get(locator);
+  if (cached) return cached;
+
+  const proxy = new Proxy(locator, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
+      }
+
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") {
+        if (LOCATOR_ALLOWED_PROPERTIES.has(prop)) {
+          return value;
+        }
+        return denyOperation("locator", prop);
+      }
+
+      if (LOCATOR_READ_METHODS.has(prop)) {
+        return (...args: unknown[]) => {
+          const result = value.apply(target, args);
+          markActivity(options.onActivity);
+          return result;
+        };
+      }
+
+      if (LOCATOR_FACTORY_METHODS.has(prop)) {
+        return (...args: unknown[]) => {
+          const nextLocator = value.apply(target, args) as Locator;
+          markActivity(options.onActivity);
+          return wrapLocatorForReadonlyExec(nextLocator, options);
+        };
+      }
+
+      if (LOCATOR_COLLECTION_FACTORY_METHODS.has(prop)) {
+        return async (...args: unknown[]) => {
+          const locators = (await value.apply(target, args)) as Locator[];
+          markActivity(options.onActivity);
+          return locators.map((locator) =>
+            wrapLocatorForReadonlyExec(locator, options),
+          );
+        };
+      }
+
+      if (LOCATOR_SCROLL_METHODS.has(prop)) {
+        return async (...args: unknown[]) => {
+          await value.apply(target, args);
+          markActivity(options.onActivity);
+        };
+      }
+
+      return (..._args: unknown[]) => denyOperation("locator", prop);
+    },
+  });
+
+  readonlyLocatorCache.set(locator, proxy as Locator);
+  return proxy as Locator;
+}
+
+export function wrapPageForReadonlyExec(
+  page: Page,
+  options: ReadonlyExecOptions = {},
+): Page {
+  const cached = readonlyPageCache.get(page);
+  if (cached) return cached;
+
+  const proxy = new Proxy(page, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
+      }
+
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") {
+        if (PAGE_ALLOWED_PROPERTIES.has(prop)) {
+          return value;
+        }
+        return denyOperation("page", prop);
+      }
+
+      if (PAGE_READ_METHODS.has(prop)) {
+        return (...args: unknown[]) => {
+          const result = value.apply(target, args);
+          markActivity(options.onActivity);
+          return result;
+        };
+      }
+
+      if (PAGE_LOCATOR_FACTORY_METHODS.has(prop)) {
+        return (...args: unknown[]) => {
+          const locator = value.apply(target, args) as Locator;
+          markActivity(options.onActivity);
+          return wrapLocatorForReadonlyExec(locator, options);
+        };
+      }
+
+      return (..._args: unknown[]) => denyOperation("page", prop);
+    },
+  });
+
+  readonlyPageCache.set(page, proxy as Page);
+  return proxy as Page;
+}
+
+function resolveRequestMethod(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): string {
+  const requestMethod =
+    typeof Request !== "undefined" && input instanceof Request
+      ? input.method
+      : undefined;
+  return (init?.method ?? requestMethod ?? "GET").toUpperCase();
+}
+
+function assertReadonlyRequestBodyAllowed(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): void {
+  if (init?.body !== undefined) {
+    throw new ReadonlyExecDeniedError(
+      "request bodies are blocked in readonly-exec",
+    );
+  }
+
+  if (
+    typeof Request !== "undefined" &&
+    input instanceof Request &&
+    input.body !== null
+  ) {
+    throw new ReadonlyExecDeniedError(
+      "request bodies are blocked in readonly-exec",
+    );
+  }
+}
+
+export function createReadonlyExecHelpers(
+  page: Page,
+  options: ReadonlyExecOptions = {},
+) {
+  const readonlyPage = wrapPageForReadonlyExec(page, options);
+  const execState: Record<string, unknown> = {};
+
+  return {
+    page: readonlyPage,
+    state: execState,
+    // Playwright has no native viewport scroll method — only locator.scrollIntoViewIfNeeded().
+    // Arbitrary scrolling requires page.evaluate(), which is blocked by the readonly proxy
+    // since it can run arbitrary code. This helper calls evaluate on the raw (unwrapped) page,
+    // scoped to just window.scrollBy.
+    scrollBy: async (deltaX: number, deltaY: number) => {
+      await page.evaluate(
+        ([x, y]) => {
+          window.scrollBy(x, y);
+        },
+        [deltaX, deltaY] as const,
+      );
+      markActivity(options.onActivity);
+    },
+    get: async (input: RequestInfo | URL, init?: RequestInit) => {
+      const method = resolveRequestMethod(input, init);
+      if (method !== "GET" && method !== "HEAD") {
+        throw new ReadonlyExecDeniedError(
+          `${method} requests are blocked in readonly-exec`,
+        );
+      }
+      assertReadonlyRequestBodyAllowed(input, init);
+      markActivity(options.onActivity);
+      return await fetch(input, {
+        ...init,
+        method,
+      });
+    },
+    // Shadows the global Node.js fetch to prevent unrestricted HTTP access.
+    // Without this, agent code would fall through to the global fetch (POST, PUT, DELETE, etc.).
+    fetch: () => {
+      throw new ReadonlyExecDeniedError(
+        "fetch is blocked in readonly-exec; use get() instead",
+      );
+    },
+    console,
+    setTimeout,
+    setInterval,
+    clearTimeout,
+    clearInterval,
+    URL,
+    Buffer,
+  };
+}

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,26 @@ 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.provider) {
+      running.push(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 +193,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 +244,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;
@@ -212,6 +276,15 @@ export function assertSessionAvailableForStart(
 ): void {
   const existingState = readSessionState(session, logger);
   if (!existingState) return;
+
+  // Cloud provider sessions have no local PID — treat them as active
+  // if they have a provider field with a cdpEndpoint.
+  if (existingState.provider && existingState.cdpEndpoint) {
+    throw new Error(
+      `Session "${session}" is already open via ${existingState.provider.name} provider. Close it first with: libretto close --session ${session}`,
+    );
+  }
+
   if (existingState.pid == null || !isPidRunning(existingState.pid)) {
     setSessionStatus(session, "exited", logger);
     return;

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.
+  }
+}