libretto 0.3.2 → 0.4.0

package/dist/cli/core/snapshot-analyzer.js

@@ -8,13 +8,6 @@ import { extname, isAbsolute, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { z } from "zod";
-import {
-  formatCommandPrefix,
-  readAiConfig
-} from "./ai-config.js";
-import {
-  getLLMClientFactory
-} from "./context.js";
 const InterpretResultSchema = z.object({
   answer: z.string(),
   selectors: z.array(
@@ -23,8 +16,8 @@ const InterpretResultSchema = z.object({
       selector: z.string(),
       rationale: z.string()
     })
-  ).default([]),
-  notes: z.string().optional().default("")
+  ),
+  notes: z.string()
 });
 class UserCodingAgent {
   constructor(config) {
@@ -41,7 +34,7 @@ class UserCodingAgent {
     }
   }
   static readConfiguredConfig() {
-    return readAiConfig();
+    return null;
   }
   static getConfigured() {
     const config = this.readConfiguredConfig();
@@ -70,7 +63,7 @@ Use the screenshot alongside the HTML snapshot context above.`;
     const result = await runExternalCommand(this.command, args, logger, stdinText);
     if (result.exitCode !== 0) {
       throw new Error(
-        `Analyzer command failed (${formatCommandPrefix([this.command, ...args])}).
+        `Analyzer command failed (${[this.command, ...args].join(" ")}).
 ${stripAnsi(result.stderr).trim() || stripAnsi(result.stdout).trim() || "No error output."}`
       );
     }
@@ -427,37 +420,50 @@ function collectSelectorHints(html, limit = 120) {
   }
   return candidates;
 }
-async function runInterpret(args, logger) {
-  logger.info("interpret-start", {
-    objective: args.objective,
-    pngPath: args.pngPath,
-    htmlPath: args.htmlPath
-  });
-  process.env.NODE_ENV = "development";
-  const pngPath = resolvePath(args.pngPath);
-  const htmlPath = resolvePath(args.htmlPath);
-  if (!existsSync(pngPath)) {
-    throw new Error(`PNG file not found: ${pngPath}`);
+function estimateTokensFromChars(chars) {
+  return Math.ceil(chars / 4);
+}
+function inferContextWindowTokens(model) {
+  const normalized = model.trim().toLowerCase();
+  if (normalized.includes("claude")) {
+    return { contextWindowTokens: 2e5, source: "model:claude" };
   }
-  if (!existsSync(htmlPath)) {
-    throw new Error(`HTML file not found: ${htmlPath}`);
+  if (normalized.includes("gpt-5") || normalized.includes("o3") || normalized.includes("o4")) {
+    return { contextWindowTokens: 2e5, source: "model:openai" };
+  }
+  if (normalized.includes("gemini")) {
+    return { contextWindowTokens: 1e6, source: "model:gemini" };
   }
-  const htmlContent = readFileSync(htmlPath, "utf-8");
-  const htmlCharLimit = 5e5;
-  const { text: trimmedHtml, truncated } = truncateText(
-    htmlContent,
-    htmlCharLimit
+  if (normalized.startsWith("openai/") || normalized.startsWith("codex/")) {
+    return { contextWindowTokens: 2e5, source: "provider:openai" };
+  }
+  if (normalized.startsWith("anthropic/")) {
+    return { contextWindowTokens: 2e5, source: "provider:anthropic" };
+  }
+  if (normalized.startsWith("google/") || normalized.startsWith("vertex/")) {
+    return { contextWindowTokens: 1e6, source: "provider:google" };
+  }
+  return { contextWindowTokens: 128e3, source: "default" };
+}
+function buildSnapshotBudget(model) {
+  const { contextWindowTokens, source } = inferContextWindowTokens(model);
+  const outputReserveTokens = Math.min(
+    32e3,
+    Math.max(8e3, Math.floor(contextWindowTokens * 0.1))
   );
-  const selectorHints = collectSelectorHints(htmlContent, 120);
-  let prompt = `# Objective
-${args.objective}
-
-`;
-  prompt += `# Context
-${args.context}
-
-`;
-  prompt += `# Instructions
+  const promptBudgetTokens = Math.max(
+    8e3,
+    contextWindowTokens - outputReserveTokens - 2e3
+  );
+  return {
+    contextWindowTokens,
+    outputReserveTokens,
+    promptBudgetTokens,
+    source
+  };
+}
+function buildInterpretInstructions() {
+  let prompt = `# Instructions
 `;
   prompt += `You are analyzing a screenshot and HTML snapshot of the same web page on behalf of an automation agent.
 `;
@@ -483,66 +489,135 @@ ${args.context}
   prompt += `Selectors should prefer robust attributes: data-testid, data-test, aria-label, name, id, role. Avoid fragile class-based or positional selectors.
 `;
   prompt += `Only include selectors that exist in the HTML snapshot.
+`;
+  return prompt;
+}
+function buildInlineHtmlPrompt(args, options) {
+  const selectorHints = collectSelectorHints(options.htmlContent, 120);
+  let prompt = `# Objective
+${args.objective}
+
+`;
+  prompt += `# Context
+${args.context}
 
 `;
+  prompt += `# Snapshot Selection
+`;
+  prompt += `- Selected HTML snapshot: ${options.domLabel}
+`;
+  prompt += `- Selection reason: ${options.selectionReason}
+
+`;
+  prompt += buildInterpretInstructions();
   if (selectorHints.length > 0) {
-    prompt += `Selector hints from HTML attributes (use if relevant):
+    prompt += `
+Selector hints from HTML attributes (use if relevant):
 `;
     prompt += selectorHints.map((hint) => `- ${hint}`).join("\n");
-    prompt += "\n\n";
+    prompt += "\n";
   }
-  if (truncated) {
-    prompt += `HTML content is truncated to fit token limits.
-
+  if (options.truncated) {
+    prompt += `
+HTML content is truncated to fit token limits.
 `;
   }
-  prompt += `HTML snapshot:
+  prompt += `
+HTML snapshot (${options.domLabel}):
 
-${trimmedHtml}`;
+${options.htmlContent}`;
   prompt += "\n\nReturn only a JSON object. Do not include markdown code fences or extra commentary.";
-  let parsed;
-  const configuredAgent = UserCodingAgent.getConfigured();
-  if (configuredAgent) {
-    const configuredAnalyzer = configuredAgent.snapshotAnalyzerConfig;
-    logger.info("interpret-analyzer-config", {
-      preset: configuredAnalyzer.preset,
-      commandPrefix: configuredAnalyzer.commandPrefix
+  return prompt;
+}
+function buildInlinePromptSelection(args, fullHtmlContent, condensedHtmlContent, model) {
+  const budget = buildSnapshotBudget(model);
+  const stats = {
+    fullDomChars: fullHtmlContent.length,
+    fullDomEstimatedTokens: estimateTokensFromChars(fullHtmlContent.length),
+    condensedDomChars: condensedHtmlContent.length,
+    condensedDomEstimatedTokens: estimateTokensFromChars(condensedHtmlContent.length),
+    configuredModel: model
+  };
+  const buildCandidate = (domSource, htmlContent, selectionReason, truncated) => {
+    const domLabel = domSource === "full" ? "full DOM" : "condensed DOM";
+    const prompt = buildInlineHtmlPrompt(args, {
+      htmlContent,
+      domLabel,
+      truncated,
+      selectionReason,
+      budget,
+      stats
     });
-    parsed = await configuredAgent.analyzeSnapshot(prompt, pngPath, logger);
-  } else {
-    const llmClientFactory = getLLMClientFactory();
-    if (!llmClientFactory) {
-      throw new Error(
-        "No AI config set. Run 'libretto-cli ai configure codex' (or claude/gemini). Library integrations can still set a factory via setLLMClientFactory()."
-      );
-    }
-    logger.info("interpret-analyzer-factory-fallback", {});
-    const imageBase64 = readFileAsBase64(pngPath);
-    const client = await llmClientFactory(logger, "google/gemini-3-flash-preview");
-    const result = await client.generateObjectFromMessages({
-      schema: InterpretResultSchema,
-      messages: [
-        {
-          role: "user",
-          content: [
-            { type: "text", text: prompt },
-            {
-              type: "image",
-              image: `data:${getMimeType(pngPath)};base64,${imageBase64}`
-            }
-          ]
-        }
-      ],
-      temperature: 0.1
+    return {
+      prompt,
+      domSource,
+      domLabel,
+      htmlChars: htmlContent.length,
+      htmlEstimatedTokens: estimateTokensFromChars(htmlContent.length),
+      promptEstimatedTokens: estimateTokensFromChars(prompt.length),
+      truncated,
+      selectionReason,
+      budget,
+      stats
+    };
+  };
+  const fullCandidate = buildCandidate(
+    "full",
+    fullHtmlContent,
+    "placeholder",
+    false
+  );
+  if (fullCandidate.promptEstimatedTokens <= budget.promptBudgetTokens) {
+    const selectionReason = `Full DOM fits within the estimated prompt budget (~${fullCandidate.promptEstimatedTokens.toLocaleString()} <= ${budget.promptBudgetTokens.toLocaleString()} tokens), so the analyzer receives the uncondensed page HTML.`;
+    const prompt = buildInlineHtmlPrompt(args, {
+      htmlContent: fullHtmlContent,
+      domLabel: "full DOM",
+      truncated: false,
+      selectionReason,
+      budget,
+      stats
     });
-    parsed = InterpretResultSchema.parse(result);
+    return {
+      ...fullCandidate,
+      selectionReason,
+      prompt,
+      promptEstimatedTokens: estimateTokensFromChars(prompt.length)
+    };
+  }
+  const condensedReason = `Full DOM would exceed the estimated prompt budget (~${fullCandidate.promptEstimatedTokens.toLocaleString()} > ${budget.promptBudgetTokens.toLocaleString()} tokens), so the analyzer receives the condensed DOM instead.`;
+  const condensedCandidate = buildCandidate(
+    "condensed",
+    condensedHtmlContent,
+    condensedReason,
+    false
+  );
+  if (condensedCandidate.promptEstimatedTokens <= budget.promptBudgetTokens) {
+    return condensedCandidate;
   }
-  logger.info("interpret-success", {
-    selectorCount: parsed.selectors.length,
-    answer: parsed.answer.slice(0, 200)
+  const truncateReason = `Both full and condensed DOM snapshots exceed the estimated prompt budget (full ~${fullCandidate.promptEstimatedTokens.toLocaleString()}, condensed ~${condensedCandidate.promptEstimatedTokens.toLocaleString()}, budget ${budget.promptBudgetTokens.toLocaleString()} tokens), so the condensed DOM is truncated to fit.`;
+  const basePrompt = buildInlineHtmlPrompt(args, {
+    htmlContent: "",
+    domLabel: "condensed DOM",
+    truncated: true,
+    selectionReason: truncateReason,
+    budget,
+    stats
   });
+  const availableHtmlTokens = Math.max(
+    2e3,
+    budget.promptBudgetTokens - estimateTokensFromChars(basePrompt.length)
+  );
+  const truncatedHtml = truncateText(condensedHtmlContent, availableHtmlTokens * 4);
+  return buildCandidate(
+    "condensed",
+    truncatedHtml.text,
+    truncateReason,
+    truncatedHtml.truncated
+  );
+}
+function formatInterpretationOutput(parsed, header = "Interpretation:") {
   const outputLines = [];
-  outputLines.push("Interpretation:");
+  outputLines.push(header);
   outputLines.push(`Answer: ${parsed.answer}`);
   outputLines.push("");
   if (parsed.selectors.length === 0) {
@@ -555,16 +630,54 @@ ${trimmedHtml}`;
       outputLines.push(`     rationale: ${selector.rationale}`);
     });
   }
-  if (parsed.notes.trim()) {
+  if (parsed.notes && parsed.notes.trim()) {
     outputLines.push("");
     outputLines.push(`Notes: ${parsed.notes.trim()}`);
   }
-  console.log(outputLines.join("\n"));
+  return outputLines.join("\n");
+}
+async function runInterpret(args, logger) {
+  logger.info("interpret-start", {
+    objective: args.objective,
+    pngPath: args.pngPath,
+    htmlPath: args.htmlPath,
+    condensedHtmlPath: args.condensedHtmlPath
+  });
+  process.env.NODE_ENV = "development";
+  const pngPath = resolvePath(args.pngPath);
+  const htmlPath = resolvePath(args.htmlPath);
+  const condensedHtmlPath = resolvePath(args.condensedHtmlPath);
+  if (!existsSync(pngPath)) {
+    throw new Error(`PNG file not found: ${pngPath}`);
+  }
+  if (!existsSync(htmlPath)) {
+    throw new Error(`HTML file not found: ${htmlPath}`);
+  }
+  if (!existsSync(condensedHtmlPath)) {
+    throw new Error(`Condensed HTML file not found: ${condensedHtmlPath}`);
+  }
+  const fullHtmlContent = readFileSync(htmlPath, "utf-8");
+  const condensedHtmlContent = readFileSync(condensedHtmlPath, "utf-8");
+  const configuredAgent = UserCodingAgent.getConfigured();
+  if (!configuredAgent) {
+    throw new Error(
+      "No AI config set. Run 'npx libretto ai configure codex' (or claude/gemini), or set API credentials in your .env file for direct API analysis."
+    );
+  }
+  const configuredAnalyzer = configuredAgent.snapshotAnalyzerConfig;
+  throw new Error(
+    "The CLI-agent snapshot analysis path is not active. Update your config to the current format with `npx libretto ai configure <provider>`, or set API credentials in .env for direct API analysis."
+  );
 }
 function canAnalyzeSnapshots() {
-  return UserCodingAgent.getConfigured() !== null || getLLMClientFactory() !== null;
+  return UserCodingAgent.getConfigured() !== null;
 }
 export {
+  InterpretResultSchema,
+  buildInlinePromptSelection,
   canAnalyzeSnapshots,
+  formatInterpretationOutput,
+  getMimeType,
+  readFileAsBase64,
   runInterpret
 };

package/dist/cli/core/snapshot-api-config.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  readAiConfig
+} from "./ai-config.js";
+import { REPO_ROOT } from "./context.js";
+import {
+  hasProviderCredentials,
+  missingProviderCredentialsMessage,
+  parseModel
+} from "../../shared/llm/client.js";
+const DEFAULT_SNAPSHOT_MODELS = {
+  openai: "openai/gpt-5.4",
+  anthropic: "anthropic/claude-sonnet-4-6",
+  google: "google/gemini-2.5-flash",
+  vertex: "vertex/gemini-2.5-pro"
+};
+class SnapshotApiUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SnapshotApiUnavailableError";
+  }
+}
+function readWorktreeEnvPath() {
+  const gitPath = join(REPO_ROOT, ".git");
+  if (!existsSync(gitPath)) return null;
+  try {
+    const gitPointer = readFileSync(gitPath, "utf-8").trim();
+    const match = gitPointer.match(/^gitdir:\s*(.+)$/i);
+    if (!match?.[1]) return null;
+    const worktreeGitDir = resolve(REPO_ROOT, match[1].trim());
+    const commonGitDir = resolve(worktreeGitDir, "..", "..");
+    return join(dirname(commonGitDir), ".env");
+  } catch {
+    return null;
+  }
+}
+function loadSnapshotEnv() {
+  if (process.env.LIBRETTO_DISABLE_DOTENV?.trim() === "1") return;
+  const envPathCandidates = [
+    join(REPO_ROOT, ".env"),
+    readWorktreeEnvPath()
+  ].filter((value) => Boolean(value));
+  const envPath = envPathCandidates.find((candidate) => existsSync(candidate));
+  if (!envPath) return;
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const parsed = parseDotEnvAssignment(line);
+    if (!parsed) continue;
+    if (!(parsed.key in process.env)) {
+      process.env[parsed.key] = parsed.value;
+    }
+  }
+}
+function parseDotEnvAssignment(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+  const withoutExport = trimmed.startsWith("export ") ? trimmed.slice("export ".length).trimStart() : trimmed;
+  const eqIdx = withoutExport.indexOf("=");
+  if (eqIdx < 1) return null;
+  const key = withoutExport.slice(0, eqIdx).trim();
+  if (!key) return null;
+  const rawValue = withoutExport.slice(eqIdx + 1).trimStart();
+  if (!rawValue) {
+    return { key, value: "" };
+  }
+  if (rawValue.startsWith('"')) {
+    const closeIdx = rawValue.indexOf('"', 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
+    }
+    return { key, value: rawValue.slice(1) };
+  }
+  if (rawValue.startsWith("'")) {
+    const closeIdx = rawValue.indexOf("'", 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
+    }
+    return { key, value: rawValue.slice(1) };
+  }
+  const inlineCommentIndex = rawValue.search(/\s#/);
+  const value = inlineCommentIndex >= 0 ? rawValue.slice(0, inlineCommentIndex).trimEnd() : rawValue.trim();
+  return { key, value };
+}
+function inferAutoSnapshotModel() {
+  const providersInPriorityOrder = [
+    "openai",
+    "anthropic",
+    "google",
+    "vertex"
+  ];
+  for (const provider of providersInPriorityOrder) {
+    if (!hasProviderCredentials(provider)) continue;
+    return {
+      model: DEFAULT_SNAPSHOT_MODELS[provider],
+      provider,
+      source: `env:auto-${provider}`
+    };
+  }
+  return null;
+}
+function resolveSnapshotApiModel(config = readAiConfig()) {
+  loadSnapshotEnv();
+  if (config?.model) {
+    const { provider } = parseModel(config.model);
+    return {
+      model: config.model,
+      provider,
+      source: "config"
+    };
+  }
+  return inferAutoSnapshotModel();
+}
+function resolveSnapshotApiModelOrThrow(config = readAiConfig()) {
+  const selection = resolveSnapshotApiModel(config);
+  if (!selection) {
+    throw new SnapshotApiUnavailableError(
+      "No API snapshot analyzer is available. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY/GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT, or run `npx libretto ai configure <provider>` to set a default model."
+    );
+  }
+  if (!hasProviderCredentials(selection.provider)) {
+    throw new SnapshotApiUnavailableError(
+      missingProviderCredentialsMessage(selection.provider)
+    );
+  }
+  return selection;
+}
+function isSnapshotApiUnavailableError(error) {
+  return error instanceof SnapshotApiUnavailableError;
+}
+export {
+  SnapshotApiUnavailableError,
+  isSnapshotApiUnavailableError,
+  loadSnapshotEnv,
+  parseDotEnvAssignment,
+  resolveSnapshotApiModel,
+  resolveSnapshotApiModelOrThrow
+};