libretto 0.5.5 → 0.5.6

package/src/cli/core/{snapshot-api-config.ts → ai-model.ts}

@@ -1,29 +1,56 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { type AiConfig, readAiConfig } from "./ai-config.js";
+import { type AiConfig, readAiConfig } from "./config.js";
 import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
 import {
   hasProviderCredentials,
   parseModel,
   type Provider,
-} from "../../shared/llm/client.js";
+} from "./resolve-model.js";
 
-const DEFAULT_SNAPSHOT_MODELS = {
+// ── Default models ──────────────────────────────────────────────────────────
+
+export const DEFAULT_SNAPSHOT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
   google: "google/gemini-3-flash-preview",
-  vertex: "vertex/gemini-2.5-pro",
+  vertex: "vertex/gemini-2.5-flash",
 } as const satisfies Record<Provider, string>;
 
+// ── Source detection ────────────────────────────────────────────────────────
+
+/**
+ * Detect which specific env var provides credentials for a provider.
+ * Returns the env var name (e.g. "OPENAI_API_KEY", "GEMINI_API_KEY"),
+ * or null if no credential is found.
+ */
+function detectProviderEnvVar(
+  provider: Provider,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  switch (provider) {
+    case "openai":
+      return env.OPENAI_API_KEY?.trim() ? "OPENAI_API_KEY" : null;
+    case "anthropic":
+      return env.ANTHROPIC_API_KEY?.trim() ? "ANTHROPIC_API_KEY" : null;
+    case "google":
+      if (env.GEMINI_API_KEY?.trim()) return "GEMINI_API_KEY";
+      if (env.GOOGLE_GENERATIVE_AI_API_KEY?.trim())
+        return "GOOGLE_GENERATIVE_AI_API_KEY";
+      return null;
+    case "vertex":
+      if (env.GOOGLE_CLOUD_PROJECT?.trim()) return "GOOGLE_CLOUD_PROJECT";
+      if (env.GCLOUD_PROJECT?.trim()) return "GCLOUD_PROJECT";
+      return null;
+  }
+}
+
+// ── Snapshot model resolution ───────────────────────────────────────────────
+
 export type SnapshotApiModelSelection = {
   model: string;
   provider: Provider;
-  source:
-    | "config"
-    | "env:auto-openai"
-    | "env:auto-anthropic"
-    | "env:auto-google"
-    | "env:auto-vertex";
+  source: "config" | `env:${string}`;
 };
 
 export class SnapshotApiUnavailableError extends Error {
@@ -67,7 +94,7 @@ function noSnapshotApiConfiguredMessage(): string {
   return [
     "Failed to analyze snapshot because no snapshot analyzer is configured.",
     `Add OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT to .env or as a shell environment variable, or choose a default model with \`${defaultModelCommandLine()}\`.`,
-    "For more info, run `npx libretto init`.",
+    "For more info, run `npx libretto setup`.",
   ].join(" ");
 }
 
@@ -81,10 +108,12 @@ function missingProviderSnapshotMessage(
   return [
     `Failed to analyze snapshot because ${selection.provider} is configured${configuredSource}, but ${providerMissingCredentialSummary(selection.provider)}.`,
     providerSetupSentence(selection.provider),
-    "For more info, run `npx libretto init`.",
+    "For more info, run `npx libretto setup`.",
   ].join(" ");
 }
 
+// ── Dotenv loading ──────────────────────────────────────────────────────────
+
 function readWorktreeEnvPath(): string | null {
   const gitPath = join(REPO_ROOT, ".git");
   if (!existsSync(gitPath)) return null;
@@ -165,6 +194,8 @@ export function parseDotEnvAssignment(
   return { key, value };
 }
 
+// ── Model resolution ────────────────────────────────────────────────────────
+
 function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
   const providersInPriorityOrder: Provider[] = [
     "openai",
@@ -174,11 +205,12 @@ function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
   ];
 
   for (const provider of providersInPriorityOrder) {
-    if (!hasProviderCredentials(provider)) continue;
+    const envVar = detectProviderEnvVar(provider);
+    if (!envVar) continue;
     return {
       model: DEFAULT_SNAPSHOT_MODELS[provider],
       provider,
-      source: `env:auto-${provider}` as SnapshotApiModelSelection["source"],
+      source: `env:${envVar}`,
     };
   }
 
@@ -229,3 +261,111 @@ export function resolveSnapshotApiModelOrThrow(
 export function isSnapshotApiUnavailableError(error: unknown): boolean {
   return error instanceof SnapshotApiUnavailableError;
 }
+
+// ── AI setup status ─────────────────────────────────────────────────────────
+
+/**
+ * Workspace AI setup health states.
+ *
+ * - `ready`: a usable model was resolved and the matching provider has credentials.
+ * - `configured-missing-credentials`: config pins a provider whose credentials are absent.
+ * - `invalid-config`: `.libretto/config.json` exists but fails schema validation.
+ * - `unconfigured`: no config and no env credentials detected.
+ */
+export type AiSetupStatus =
+  | {
+      kind: "ready";
+      model: string;
+      provider: Provider;
+      source: "config" | `env:${string}`;
+    }
+  | {
+      kind: "configured-missing-credentials";
+      model: string;
+      provider: Provider;
+    }
+  | { kind: "invalid-config"; message: string }
+  | { kind: "unconfigured" };
+
+/**
+ * Read AI config without throwing on invalid files.
+ * Returns the config or an error message.
+ */
+function readAiConfigSafely(
+  configPath: string,
+): { ok: true; config: AiConfig | null } | { ok: false; message: string } {
+  try {
+    return { ok: true, config: readAiConfig(configPath) };
+  } catch (err) {
+    return {
+      ok: false,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Resolve the workspace's current AI setup health.
+ *
+ * Uses the existing config reader and snapshot model resolver, but wraps
+ * them to distinguish broken states (invalid config, missing credentials)
+ * that the throwing APIs collapse into errors.
+ *
+ * 1. If config read throws → `invalid-config`.
+ * 2. If config has an `ai` block → check credentials for that provider.
+ * 3. If no config or no `ai` block → auto-detect from env via existing resolver.
+ */
+export function resolveAiSetupStatus(
+  configPath: string = LIBRETTO_CONFIG_PATH,
+): AiSetupStatus {
+  loadSnapshotEnv();
+
+  const configResult = readAiConfigSafely(configPath);
+
+  if (!configResult.ok) {
+    return { kind: "invalid-config", message: configResult.message };
+  }
+
+  // Config exists with an ai block — use it directly to check credentials
+  if (configResult.config) {
+    let selection: SnapshotApiModelSelection | null;
+    try {
+      selection = resolveSnapshotApiModel(configResult.config);
+    } catch (err) {
+      return {
+        kind: "invalid-config",
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+    if (!selection) {
+      // Should not happen when config has a model, but handle gracefully
+      return { kind: "unconfigured" };
+    }
+    if (hasProviderCredentials(selection.provider)) {
+      return {
+        kind: "ready",
+        model: selection.model,
+        provider: selection.provider,
+        source: selection.source,
+      };
+    }
+    return {
+      kind: "configured-missing-credentials",
+      model: selection.model,
+      provider: selection.provider,
+    };
+  }
+
+  // No ai config — fall back to env auto-detect via existing resolver
+  const envSelection = resolveSnapshotApiModel(null);
+  if (envSelection && hasProviderCredentials(envSelection.provider)) {
+    return {
+      kind: "ready",
+      model: envSelection.model,
+      provider: envSelection.provider,
+      source: envSelection.source,
+    };
+  }
+
+  return { kind: "unconfigured" };
+}

package/src/cli/core/api-snapshot-analyzer.ts

@@ -8,7 +8,8 @@
 
 import { readFileSync } from "node:fs";
 import type { LoggerApi } from "../../shared/logger/index.js";
-import { createLLMClient } from "../../shared/llm/client.js";
+import { generateObject } from "ai";
+import { resolveModel } from "./resolve-model.js";
 import {
   InterpretResultSchema,
   buildInlinePromptSelection,
@@ -17,8 +18,8 @@ import {
   type InterpretResult,
   type InterpretArgs,
 } from "./snapshot-analyzer.js";
-import { readAiConfig, type AiConfig } from "./ai-config.js";
-import { resolveSnapshotApiModelOrThrow } from "./snapshot-api-config.js";
+import { readAiConfig, type AiConfig } from "./config.js";
+import { resolveSnapshotApiModelOrThrow } from "./ai-model.js";
 
 export async function runApiInterpret(
   args: InterpretArgs,
@@ -64,9 +65,10 @@ export async function runApiInterpret(
   const imageMimeType = getMimeType(args.pngPath);
   const imageBytes = Buffer.from(imageBase64, "base64");
 
-  const client = createLLMClient(selection.model);
+  const model = await resolveModel(selection.model);
 
-  const result = await client.generateObjectFromMessages({
+  const { object: result } = await generateObject({
+    model,
     schema: InterpretResultSchema,
     messages: [
       {

package/src/cli/core/browser.ts

@@ -12,6 +12,7 @@ import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { spawn } from "node:child_process";
 import type { LoggerApi } from "../../shared/logger/index.js";
+import type { SessionAccessMode } from "../../shared/state/index.js";
 import {
   filterSemanticClasses,
   INTERACTIVE_ROLE_NAMES,
@@ -25,10 +26,11 @@ import {
   getSessionNetworkLogPath,
   PROFILES_DIR,
 } from "./context.js";
-import { readLibrettoConfig } from "./ai-config.js";
+import { readLibrettoConfig } from "./config.js";
 import {
   assertSessionAvailableForStart,
   clearSessionState,
+  isPidRunning,
   listSessionsWithStateFile,
   readSessionStateOrThrow,
   logFileForSession,
@@ -398,13 +400,24 @@ export async function runOpen(
   headed: boolean,
   session: string,
   logger: LoggerApi,
-  options?: { viewport?: { width: number; height: number } },
+  options?: {
+    viewport?: { width: number; height: number };
+    accessMode?: SessionAccessMode;
+  },
 ): Promise<void> {
   const parsedUrl = normalizeUrl(rawUrl);
   const url = parsedUrl.href;
   const viewport = resolveViewport(options?.viewport, logger);
+  const accessMode = options?.accessMode ?? "write-access";
   const windowPosition = headed ? resolveWindowPosition(logger) : undefined;
-  logger.info("open-start", { url, headed, session, viewport, windowPosition });
+  logger.info("open-start", {
+    url,
+    headed,
+    session,
+    viewport,
+    windowPosition,
+    accessMode,
+  });
   assertSessionAvailableForStart(session, logger);
 
   const port = await pickFreePort();
@@ -674,6 +687,7 @@ await new Promise(() => {});
           session,
           startedAt: new Date().toISOString(),
           status: "active",
+          mode: accessMode,
           viewport,
         },
         logger,
@@ -819,15 +833,6 @@ function waitForCloseSignalWindow(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
-function isPidRunning(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function sendSignalToProcessGroupOrPid(
   pid: number,
   signal: NodeJS.Signals,
@@ -993,8 +998,9 @@ export async function runConnect(
   cdpUrl: string,
   session: string,
   logger: LoggerApi,
+  accessMode: SessionAccessMode = "write-access",
 ): Promise<void> {
-  logger.info("connect-start", { cdpUrl, session });
+  logger.info("connect-start", { cdpUrl, session, accessMode });
   assertSessionAvailableForStart(session, logger);
 
   let parsedUrl: URL;
@@ -1005,18 +1011,22 @@ export async function runConnect(
       [
         `Invalid CDP URL: ${cdpUrl}`,
         ``,
-        `Expected an HTTP URL pointing to a Chrome DevTools Protocol endpoint, for example:`,
+        `Expected an HTTP or WebSocket URL pointing to a Chrome DevTools Protocol endpoint, for example:`,
         `  libretto connect http://127.0.0.1:9222`,
         `  libretto connect http://remote-host:9222`,
         `  libretto connect http://remote-host:9222/devtools/browser/<id>`,
+        `  libretto connect ws://remote-host:9222/devtools/browser/<id>`,
+        `  libretto connect wss://remote-host/cdp-endpoint`,
       ].join("\n"),
     );
   }
 
   const endpoint = parsedUrl.href;
+  const isWebSocket =
+    parsedUrl.protocol === "ws:" || parsedUrl.protocol === "wss:";
   const port = parsedUrl.port
     ? Number(parsedUrl.port)
-    : parsedUrl.protocol === "https:"
+    : parsedUrl.protocol === "https:" || parsedUrl.protocol === "wss:"
       ? 443
       : 80;
 
@@ -1024,17 +1034,25 @@ export async function runConnect(
     `Connecting to CDP endpoint at ${endpoint} (session: ${session})...`,
   );
 
-  // Verify the CDP endpoint is reachable
-  const versionUrl = `${parsedUrl.protocol}//${parsedUrl.host}/json/version`;
-  try {
-    const resp = await fetch(versionUrl);
-    const versionInfo = await resp.json();
-    logger.info("connect-version-ok", { versionUrl, versionInfo });
-  } catch (err) {
-    logger.error("connect-version-failed", { versionUrl, error: err });
-    throw new Error(
-      `Cannot reach CDP endpoint at ${versionUrl}. Make sure the target is running and accessible at ${parsedUrl.host}.`,
-    );
+  // Verify the CDP endpoint is reachable (HTTP only — WebSocket
+  // endpoints are validated by the Playwright connect call below).
+  if (!isWebSocket) {
+    const versionUrl = `${parsedUrl.protocol}//${parsedUrl.host}/json/version`;
+    try {
+      const resp = await fetch(versionUrl);
+      const versionInfo = await resp.json();
+      logger.info("connect-version-ok", { versionUrl, versionInfo });
+    } catch (err) {
+      logger.error("connect-version-failed", { versionUrl, error: err });
+      throw new Error(
+        `Cannot reach CDP endpoint at ${versionUrl}. Make sure the target is running and accessible at ${parsedUrl.host}.`,
+      );
+    }
+  } else {
+    logger.info("connect-skip-version-check", {
+      reason: "WebSocket-only endpoint, skipping HTTP version check",
+      endpoint,
+    });
   }
 
   // Connect via CDP using the full endpoint URL
@@ -1061,6 +1079,7 @@ export async function runConnect(
       session,
       startedAt: new Date().toISOString(),
       status: "active",
+      mode: accessMode,
     },
     logger,
   );

package/src/cli/core/{ai-config.ts → config.ts}

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 import { LIBRETTO_CONFIG_PATH } from "./context.js";
 
 export const CURRENT_CONFIG_VERSION = 1;
@@ -41,34 +42,11 @@ export const LibrettoConfigSchema = z
     ai: AiConfigSchema.optional(),
     viewport: ViewportConfigSchema.optional(),
     windowPosition: WindowPositionConfigSchema.optional(),
+    sessionMode: SessionAccessModeSchema.optional(),
   })
   .passthrough();
 export type LibrettoConfig = z.infer<typeof LibrettoConfigSchema>;
 
-/** Default models for each provider shorthand accepted by `ai configure`. */
-const DEFAULT_MODELS: Record<string, string> = {
-  openai: "openai/gpt-5.4",
-  anthropic: "anthropic/claude-sonnet-4-6",
-  gemini: "google/gemini-3-flash-preview",
-  vertex: "vertex/gemini-2.5-pro",
-};
-
-const PROVIDER_ALIASES: Record<string, string> = {
-  claude: DEFAULT_MODELS.anthropic,
-  google: DEFAULT_MODELS.gemini,
-};
-
-const CONFIGURE_PROVIDERS = [
-  "openai",
-  "anthropic",
-  "gemini",
-  "vertex",
-] as const;
-
-function formatConfigureProviders(separator = " | "): string {
-  return CONFIGURE_PROVIDERS.join(separator);
-}
-
 function formatConfigIssues(error: z.ZodError): string {
   return error.issues
     .map((issue) => `  - ${issue.path.join(".") || "root"}: ${issue.message}`)
@@ -91,6 +69,7 @@ function formatExpectedConfigExample(): string {
         x: 1600,
         y: 120,
       },
+      sessionMode: "write-access",
     },
     null,
     2,
@@ -105,10 +84,10 @@ function invalidConfigError(configPath: string, detail?: string): Error {
       "Expected config example:",
       formatExpectedConfigExample(),
       "Notes:",
-      '  - "ai", "viewport", and "windowPosition" are optional.',
+      '  - "ai", "viewport", "windowPosition", and "sessionMode" are optional.',
       '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
       "Fix the file to match this shape, or delete it and rerun:",
-      `  npx libretto ai configure ${formatConfigureProviders()}`,
+      `  npx libretto ai configure openai | anthropic | gemini | vertex`,
     ]
       .filter(Boolean)
       .join("\n"),
@@ -162,7 +141,14 @@ export function writeAiConfig(
   model: string,
   configPath: string = LIBRETTO_CONFIG_PATH,
 ): AiConfig {
-  const librettoConfig = readLibrettoConfig(configPath);
+  let librettoConfig: LibrettoConfig;
+  try {
+    librettoConfig = readLibrettoConfig(configPath);
+  } catch {
+    // Existing config is malformed — start fresh so repair flows can
+    // overwrite a broken file instead of throwing.
+    librettoConfig = { version: CURRENT_CONFIG_VERSION };
+  }
   const ai = AiConfigSchema.parse({
     model,
     updatedAt: new Date().toISOString(),
@@ -192,84 +178,3 @@ export function clearAiConfig(
   );
   return true;
 }
-
-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_MODELS[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);
-}

package/src/cli/core/context.ts

@@ -1,6 +1,4 @@
 import { Logger, createFileLogSink } from "../../shared/logger/index.js";
-import type { LLMClient } from "../../shared/llm/index.js";
-import type { LoggerApi } from "../../shared/logger/index.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveLibrettoRepoRoot } from "../../shared/paths/repo-root.js";
@@ -72,13 +70,6 @@ export function createLoggerForSession(session: string): Logger {
   );
 }
 
-export async function closeLogger(
-  logger: Logger | null | undefined,
-): Promise<void> {
-  if (!logger) return;
-  await logger.close();
-}
-
 export async function withSessionLogger<T>(
   session: string,
   run: (logger: Logger) => Promise<T>,
@@ -87,41 +78,6 @@ export async function withSessionLogger<T>(
   try {
     return await run(logger);
   } finally {
-    await closeLogger(logger);
+    await logger.close();
   }
 }
-
-let llmClientFactory:
-  | ((logger: LoggerApi, model: string) => Promise<LLMClient>)
-  | null = null;
-
-export function setLLMClientFactory(
-  factory: (logger: LoggerApi, model: string) => Promise<LLMClient>,
-): void {
-  llmClientFactory = factory;
-}
-
-export function getLLMClientFactory():
-  | ((logger: LoggerApi, model: string) => Promise<LLMClient>)
-  | null {
-  return llmClientFactory;
-}
-
-export function maybeConfigureLLMClientFactoryFromEnv(): void {
-  if (llmClientFactory) return;
-
-  const hasAnyCreds =
-    process.env.GOOGLE_CLOUD_PROJECT ||
-    process.env.GCLOUD_PROJECT ||
-    process.env.ANTHROPIC_API_KEY ||
-    process.env.OPENAI_API_KEY ||
-    process.env.GEMINI_API_KEY ||
-    process.env.GOOGLE_GENERATIVE_AI_API_KEY;
-
-  if (!hasAnyCreds) return;
-
-  setLLMClientFactory(async (_logger, model) => {
-    const { createLLMClient } = await import("../../shared/llm/index.js");
-    return createLLMClient(model);
-  });
-}