libretto 0.5.5 → 0.6.0

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,16 +26,19 @@ 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,
   readSessionState,
   writeSessionState,
 } from "./session.js";
+import type { ProviderApi } from "./providers/types.js";
+import { getCloudProviderApi } from "./providers/index.js";
 import { installSessionTelemetry } from "./session-telemetry.js";
 
 const CLOSE_WAIT_MS = 1_500;
@@ -256,6 +260,16 @@ export async function connect(
       endpoint,
       pid: state.pid,
     });
+    // Provider sessions have no local PID to check liveness.
+    // Don't destroy the remote session on a transient failure —
+    // let the user retry or explicitly close.
+    if (state.provider) {
+      throw new Error(
+        `Could not connect to ${state.provider.name} session for "${session}" at ${endpoint}. ` +
+          `The remote session may still be active. Try again, or close with: libretto close --session ${session}`,
+      );
+    }
+
     if (state.pid == null || !isPidRunning(state.pid)) {
       clearSessionState(session, logger);
       throw new Error(
@@ -398,13 +412,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 +699,7 @@ await new Promise(() => {});
           session,
           startedAt: new Date().toISOString(),
           status: "active",
+          mode: accessMode,
           viewport,
         },
         logger,
@@ -703,6 +729,106 @@ await new Promise(() => {});
   );
 }
 
+export async function runOpenWithProvider(
+  rawUrl: string,
+  providerName: string,
+  provider: ProviderApi,
+  session: string,
+  logger: LoggerApi,
+  accessMode: SessionAccessMode = "write-access",
+): Promise<void> {
+  const parsedUrl = normalizeUrl(rawUrl);
+  const url = parsedUrl.href;
+  logger.info("open-provider-start", { url, provider: providerName, session });
+
+  console.log(
+    `Creating ${providerName} browser session (session: ${session})...`,
+  );
+
+  const providerSession = await provider.createSession();
+  logger.info("open-provider-session-created", {
+    provider: providerName,
+    sessionId: providerSession.sessionId,
+    cdpEndpoint: providerSession.cdpEndpoint,
+  });
+
+  console.log(`Connecting to ${providerName} browser...`);
+
+  let browser: Browser | null = null;
+  try {
+    browser = await tryConnectToCDP(
+      providerSession.cdpEndpoint,
+      logger,
+      30_000,
+    );
+    if (!browser) {
+      throw new Error(
+        `Could not connect to ${providerName} browser at ${providerSession.cdpEndpoint}. The remote session was created but CDP connection failed.`,
+      );
+    }
+
+    const contexts = browser.contexts();
+    let page: Page;
+    if (contexts.length > 0 && contexts[0].pages().length > 0) {
+      page = contexts[0].pages()[0];
+    } else {
+      const context =
+        contexts.length > 0 ? contexts[0] : await browser.newContext();
+      page = await context.newPage();
+    }
+
+    await page.goto(url);
+    logger.info("open-provider-navigated", { url, session });
+
+    // Cloud sessions have no local port. Reconnection uses cdpEndpoint directly.
+    writeSessionState(
+      {
+        port: 0,
+        cdpEndpoint: providerSession.cdpEndpoint,
+        session,
+        startedAt: new Date().toISOString(),
+        status: "active",
+        mode: accessMode,
+        provider: {
+          name: providerName,
+          sessionId: providerSession.sessionId,
+        },
+      },
+      logger,
+    );
+
+    disconnectBrowser(browser, logger, session);
+  } catch (err) {
+    if (browser) {
+      disconnectBrowser(browser, logger, session);
+    }
+    // Clean up the remote session so it doesn't leak
+    logger.warn("open-provider-cleanup-after-error", {
+      provider: providerName,
+      sessionId: providerSession.sessionId,
+      error: err,
+    });
+    try {
+      await provider.closeSession(providerSession.sessionId);
+    } catch (cleanupErr) {
+      logger.warn("open-provider-cleanup-failed", {
+        provider: providerName,
+        sessionId: providerSession.sessionId,
+        error: cleanupErr,
+      });
+    }
+    throw err;
+  }
+
+  logger.info("open-provider-success", {
+    url,
+    provider: providerName,
+    session,
+    sessionId: providerSession.sessionId,
+  });
+  console.log(`Browser open (${providerName}): ${url}`);
+}
+
 export async function runSave(
   urlOrDomain: string,
   session: string,
@@ -797,11 +923,37 @@ export async function runClose(
     return;
   }
 
-  logger.info("close-killing", { session, pid: state.pid, port: state.port });
-
-  if (state.pid != null) {
-    sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
-    await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+  if (state.provider) {
+    // Cloud provider session — close via provider API, no local pid to kill
+    logger.info("close-provider", {
+      session,
+      provider: state.provider.name,
+      sessionId: state.provider.sessionId,
+    });
+    try {
+      const provider = getCloudProviderApi(state.provider.name);
+      await provider.closeSession(state.provider.sessionId);
+    } catch (err) {
+      logger.warn("close-provider-error", {
+        session,
+        provider: state.provider.name,
+        sessionId: state.provider.sessionId,
+        error: err,
+      });
+      // Preserve state with cleanup-failed status so the user can retry.
+      // The provider.sessionId is retained for manual or future cleanup.
+      writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+      throw new Error(
+        `Failed to close remote ${state.provider.name} session "${state.provider.sessionId}" for session "${session}". ` +
+          `State preserved with status "cleanup-failed". Retry with: libretto close --session ${session}`,
+      );
+    }
+  } else {
+    logger.info("close-killing", { session, pid: state.pid, port: state.port });
+    if (state.pid != null) {
+      sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
+      await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+    }
   }
 
   clearSessionState(session, logger);
@@ -813,21 +965,13 @@ type ClosableSession = {
   session: string;
   pid?: number;
   port: number;
+  provider?: { name: string; sessionId: string };
 };
 
 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,
@@ -874,6 +1018,7 @@ function resolveClosableSessions(logger: LoggerApi): {
       session,
       pid: state.pid,
       port: state.port,
+      provider: state.provider,
     });
   }
 
@@ -883,9 +1028,11 @@ function resolveClosableSessions(logger: LoggerApi): {
 function clearStoppedSessionStates(
   sessions: ReadonlyArray<ClosableSession>,
   logger: LoggerApi,
+  skip?: ReadonlySet<string>,
 ): number {
   let cleared = 0;
   for (const session of sessions) {
+    if (skip?.has(session.session)) continue;
     if (session.pid == null || !isPidRunning(session.pid)) {
       clearSessionState(session.session, logger);
       cleared += 1;
@@ -911,7 +1058,38 @@ export async function runCloseAll(
     return;
   }
 
+  // Close provider sessions via their APIs
+  const failedProviderSessions = new Set<string>();
+  for (const target of closable) {
+    if (target.provider) {
+      logger.info("close-all-provider", {
+        session: target.session,
+        provider: target.provider.name,
+        sessionId: target.provider.sessionId,
+      });
+      try {
+        const provider = getCloudProviderApi(target.provider.name);
+        await provider.closeSession(target.provider.sessionId);
+      } catch (err) {
+        logger.warn("close-all-provider-error", {
+          session: target.session,
+          provider: target.provider.name,
+          sessionId: target.provider.sessionId,
+          error: err,
+        });
+        failedProviderSessions.add(target.session);
+        // Mark as cleanup-failed, preserving provider.sessionId for retry
+        const state = readSessionState(target.session, logger);
+        if (state) {
+          writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+        }
+      }
+    }
+  }
+
+  // Send SIGTERM to local sessions
   for (const target of closable) {
+    if (target.provider) continue; // already handled above
     logger.info("close-all-sigterm", {
       session: target.session,
       pid: target.pid,
@@ -933,7 +1111,11 @@ export async function runCloseAll(
     (target) => target.pid != null && isPidRunning(target.pid),
   );
   if (survivors.length > 0 && !force) {
-    const closed = clearStoppedSessionStates(closable, logger);
+    const closed = clearStoppedSessionStates(
+      closable,
+      logger,
+      failedProviderSessions,
+    );
 
     throw new Error(
       [
@@ -966,7 +1148,11 @@ export async function runCloseAll(
       (target) => target.pid != null && isPidRunning(target.pid),
     );
     if (survivors.length > 0) {
-      const closed = clearStoppedSessionStates(closable, logger);
+      const closed = clearStoppedSessionStates(
+        closable,
+        logger,
+        failedProviderSessions,
+      );
       throw new Error(
         [
           `Failed to force-close ${survivors.length} session(s): ${formatSessionList(survivors)}.`,
@@ -976,14 +1162,21 @@ export async function runCloseAll(
     }
   }
 
-  clearStoppedSessionStates(closable, logger);
+  clearStoppedSessionStates(closable, logger, failedProviderSessions);
+
+  if (failedProviderSessions.size > 0) {
+    console.log(
+      `Warning: ${failedProviderSessions.size} provider session(s) failed remote cleanup and were preserved with status "cleanup-failed".`,
+    );
+  }
 
   if (clearedUnreadableStates > 0) {
     console.log(
       `Cleared ${clearedUnreadableStates} unreadable session state file(s).`,
     );
   }
-  console.log(`Closed ${closable.length} session(s).`);
+  const closedCount = closable.length - failedProviderSessions.size;
+  console.log(`Closed ${closedCount} session(s).`);
   if (forceKilled > 0) {
     console.log(`Force-killed ${forceKilled} session(s).`);
   }
@@ -993,8 +1186,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 +1199,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 +1222,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 +1267,7 @@ export async function runConnect(
       session,
       startedAt: new Date().toISOString(),
       status: "active",
+      mode: accessMode,
     },
     logger,
   );