@algolia/wizard 0.65.0 → 0.67.0

package/dist/main.js

@@ -1490,7 +1490,106 @@ async function clearWorkflowState(workflowId) {
   await rm(stateFile(workflowId), { force: true });
 }
 
+// src/lib/modelProfiles.ts
+var TOKENS_PER_MILLION = 1e6;
+var INITIAL_MODEL_ATTEMPT = 1;
+var NO_TOKENS = 0;
+var QUICK_MAX_OUTPUT_TOKENS = 8192;
+var QUICK_MAX_STEPS = 16;
+var ANALYSIS_MAX_OUTPUT_TOKENS = 8192;
+var ANALYSIS_MAX_STEPS = 24;
+var IMPLEMENTATION_MAX_OUTPUT_TOKENS = 65536;
+var IMPLEMENTATION_MAX_STEPS = 48;
+var VALIDATION_MAX_OUTPUT_TOKENS = 8192;
+var VALIDATION_MAX_STEPS = 24;
+var HAIKU_4_5_PRICES = {
+  input: 1,
+  output: 5,
+  cacheRead: 0.1,
+  cacheWrite: 1.25
+};
+var SONNET_5_PRICES = {
+  input: 2,
+  output: 10,
+  cacheRead: 0.2,
+  cacheWrite: 2.5
+};
+var MODEL_PROFILES = {
+  quick: {
+    model: "claude-haiku-4-5",
+    thinking: "disabled",
+    maxOutputTokens: QUICK_MAX_OUTPUT_TOKENS,
+    maxSteps: QUICK_MAX_STEPS,
+    prices: HAIKU_4_5_PRICES
+  },
+  analysis: {
+    model: "claude-sonnet-5",
+    thinking: "adaptive",
+    effort: "low",
+    maxOutputTokens: ANALYSIS_MAX_OUTPUT_TOKENS,
+    maxSteps: ANALYSIS_MAX_STEPS,
+    prices: SONNET_5_PRICES
+  },
+  implementation: {
+    model: "claude-sonnet-5",
+    thinking: "adaptive",
+    effort: "medium",
+    maxOutputTokens: IMPLEMENTATION_MAX_OUTPUT_TOKENS,
+    maxSteps: IMPLEMENTATION_MAX_STEPS,
+    prices: SONNET_5_PRICES
+  },
+  implementationRetry: {
+    model: "claude-sonnet-5",
+    thinking: "adaptive",
+    effort: "high",
+    maxOutputTokens: IMPLEMENTATION_MAX_OUTPUT_TOKENS,
+    maxSteps: IMPLEMENTATION_MAX_STEPS,
+    prices: SONNET_5_PRICES
+  },
+  validation: {
+    model: "claude-sonnet-5",
+    thinking: "adaptive",
+    effort: "low",
+    maxOutputTokens: VALIDATION_MAX_OUTPUT_TOKENS,
+    maxSteps: VALIDATION_MAX_STEPS,
+    prices: SONNET_5_PRICES
+  }
+};
+function getModelProfile(profileName) {
+  return MODEL_PROFILES[profileName];
+}
+function providerOptionsForProfile(profileName) {
+  const profile = getModelProfile(profileName);
+  return {
+    thinking: { type: profile.thinking },
+    ...profile.effort !== void 0 && { effort: profile.effort }
+  };
+}
+function tokenCount(value = NO_TOKENS) {
+  return value;
+}
+function estimateModelCost(profileName, usage) {
+  const { prices } = getModelProfile(profileName);
+  const inputDetails = Object.assign({}, usage.inputTokenDetails);
+  const cacheRead = tokenCount(inputDetails.cacheReadTokens);
+  const cacheWrite = tokenCount(inputDetails.cacheWriteTokens);
+  const input = Math.max(
+    NO_TOKENS,
+    tokenCount(usage.inputTokens) - cacheRead - cacheWrite
+  );
+  const output = tokenCount(usage.outputTokens);
+  return (input * prices.input + cacheRead * prices.cacheRead + cacheWrite * prices.cacheWrite + output * prices.output) / TOKENS_PER_MILLION;
+}
+
 // src/lib/telemetry.ts
+var COUNT_METRIC = 1;
+var GAUGE_METRIC = 3;
+var FIRST_ATTEMPT = 1;
+var NO_TOKENS2 = 0;
+var AGENT_TELEMETRY_CONTEXT = {
+  appId: void 0,
+  workflowId: void 0
+};
 function isTelemetryOptedOut() {
   return process.env.WIZARD_TELEMETRY === "false";
 }
@@ -1537,6 +1636,110 @@ function sendMetric(name, value, type, tags = []) {
 function metricTags(workflowId, actionId) {
   return actionId ? [`workflow:${workflowId}`, `action:${actionId}`] : [`workflow:${workflowId}`];
 }
+function agentMetricTags(event, workflowId) {
+  const profile = getModelProfile(event.profile);
+  return [
+    ...workflowId ? [`workflow:${workflowId}`] : [],
+    `operation:${event.operation}`,
+    `profile:${event.profile}`,
+    `model:${profile.model}`,
+    `effort:${profile.effort ?? "none"}`,
+    `thinking:${profile.thinking}`
+  ];
+}
+function agentRunValues(event) {
+  const usage = Object.assign({}, event.usage);
+  const inputTokenDetails = Object.assign({}, usage.inputTokenDetails);
+  return {
+    inputTokens: usage.inputTokens ?? NO_TOKENS2,
+    outputTokens: usage.outputTokens ?? NO_TOKENS2,
+    cacheReadTokens: inputTokenDetails.cacheReadTokens ?? NO_TOKENS2,
+    cacheWriteTokens: inputTokenDetails.cacheWriteTokens ?? NO_TOKENS2,
+    estimatedCostUsd: estimateModelCost(event.profile, usage)
+  };
+}
+function agentRunMetrics(event, values, tags) {
+  const runTags = [...tags];
+  return [
+    {
+      name: "wizard.agent.duration_ms",
+      value: event.durationMs,
+      type: GAUGE_METRIC,
+      tags: runTags
+    },
+    {
+      name: "wizard.agent.input_tokens",
+      value: values.inputTokens,
+      type: COUNT_METRIC,
+      tags: runTags
+    },
+    {
+      name: "wizard.agent.output_tokens",
+      value: values.outputTokens,
+      type: COUNT_METRIC,
+      tags: runTags
+    },
+    {
+      name: "wizard.agent.cache_read_tokens",
+      value: values.cacheReadTokens,
+      type: COUNT_METRIC,
+      tags: runTags
+    },
+    {
+      name: "wizard.agent.cache_write_tokens",
+      value: values.cacheWriteTokens,
+      type: COUNT_METRIC,
+      tags: runTags
+    },
+    {
+      name: "wizard.agent.estimated_cost_usd",
+      value: values.estimatedCostUsd,
+      type: COUNT_METRIC,
+      tags: runTags
+    },
+    {
+      name: "wizard.agent.retry",
+      value: Number(event.attempt > FIRST_ATTEMPT),
+      type: COUNT_METRIC,
+      tags: runTags
+    }
+  ];
+}
+function trackAgentRun(event) {
+  const profile = getModelProfile(event.profile);
+  const values = agentRunValues(event);
+  const tagsForMetrics = agentMetricTags(
+    event,
+    AGENT_TELEMETRY_CONTEXT.workflowId
+  );
+  const tags = [
+    ...tagsForMetrics,
+    ...AGENT_TELEMETRY_CONTEXT.appId ? [`app_id:${AGENT_TELEMETRY_CONTEXT.appId}`] : []
+  ];
+  sendTelemetry({
+    logs: [
+      {
+        status: "info",
+        message: "wizard agent completed",
+        attributes: {
+          event: "wizard.agent.complete",
+          operation: event.operation,
+          profile: event.profile,
+          model: profile.model,
+          effort: profile.effort ?? "none",
+          thinking: profile.thinking,
+          attempt: event.attempt,
+          durationMs: event.durationMs,
+          workflow_id: AGENT_TELEMETRY_CONTEXT.workflowId,
+          app_id: AGENT_TELEMETRY_CONTEXT.appId,
+          ...values
+        },
+        tags
+      }
+    ],
+    metrics: agentRunMetrics(event, values, tagsForMetrics)
+  });
+}
 function logTags(workflowId, actionId, appId) {
   return [
     ...metricTags(workflowId, actionId),
@@ -1552,6 +1755,8 @@ function emitTelemetryLog(level, message, attributes, tags) {
   sendLog(level, message, attributes, tags);
 }
 function trackWorkflowStart(ctx) {
+  AGENT_TELEMETRY_CONTEXT.appId = ctx.appId;
+  AGENT_TELEMETRY_CONTEXT.workflowId = ctx.workflowId;
   const attributes = {
     event: "wizard.workflow.start",
     workflow_id: ctx.workflowId,
@@ -1677,6 +1882,8 @@ function trackWizardComplete(event) {
     attributes,
     logTags(event.workflowId, void 0, event.appId)
   );
+  AGENT_TELEMETRY_CONTEXT.appId = void 0;
+  AGENT_TELEMETRY_CONTEXT.workflowId = void 0;
 }
 function trackWorkflowError(ctx) {
   const attributes = {
@@ -1693,6 +1900,8 @@ function trackWorkflowError(ctx) {
     attributes,
     logTags(ctx.workflowId, ctx.actionId, ctx.appId)
   );
+  AGENT_TELEMETRY_CONTEXT.appId = void 0;
+  AGENT_TELEMETRY_CONTEXT.workflowId = void 0;
 }
 
 // src/lib/events.ts
@@ -1760,7 +1969,7 @@ function identify(traits) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.65.0",
+  version: "0.67.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -2306,7 +2515,8 @@ import {
   hasToolCall,
   Output as Output3,
   APICallError,
-  NoOutputGeneratedError
+  NoOutputGeneratedError,
+  stepCountIs
 } from "ai";
 import { createAnthropic as createAnthropic3 } from "@ai-sdk/anthropic";
 import "zod";
@@ -3297,6 +3507,7 @@ function runShell(command, opts) {
 }
 
 // src/lib/tools/runShell.ts
+var CLASSIFIER_MAX_OUTPUT_TOKENS = 512;
 function storeApproval(root) {
   return async (req) => {
     const store = useWizard.getState();
@@ -3510,7 +3721,6 @@ function fastPathSafety(command) {
   if (results.every((r) => r === true)) return true;
   return void 0;
 }
-var CLASSIFIER_MODEL = "claude-haiku-4-5";
 var commandSafetySchema = z16.object({
   safe: z16.boolean(),
   reason: z16.string().describe("One short sentence explaining the verdict.")
@@ -3535,9 +3745,21 @@ function approvedCommandHistory(approvedCommands) {
 async function classifyCommandSafety(createModel, command, cwd, explanation, approvedHistory) {
   try {
     const anthropic = createModel();
-    const { output } = await generateText({
-      model: anthropic(CLASSIFIER_MODEL),
+    const profile = getModelProfile("quick" /* quick */);
+    const modelOptions = providerOptionsForProfile("quick" /* quick */);
+    const startedAt = Date.now();
+    const { output, usage } = await generateText({
+      model: anthropic(profile.model),
+      maxOutputTokens: CLASSIFIER_MAX_OUTPUT_TOKENS,
       temperature: 0,
+      providerOptions: {
+        anthropic: {
+          thinking: modelOptions.thinking,
+          ...modelOptions.effort !== void 0 && {
+            effort: modelOptions.effort
+          }
+        }
+      },
       output: Output.object({ schema: commandSafetySchema }),
       prompt: [
         "A coding agent wants to run this shell command in a user's project without asking for approval first. The command may be in any programming language or ecosystem.",
@@ -3558,6 +3780,13 @@ async function classifyCommandSafety(createModel, command, cwd, explanation, app
         `Stated purpose: ${explanation}`
       ].join("\n")
     });
+    trackAgentRun({
+      operation: "shell-safety-classifier",
+      profile: "quick" /* quick */,
+      attempt: INITIAL_MODEL_ATTEMPT,
+      durationMs: Date.now() - startedAt,
+      usage
+    });
     if (!output.safe) {
       logger.info(
         { command, reason: output.reason },
@@ -3702,7 +3931,6 @@ import { createAnthropic as createAnthropic2 } from "@ai-sdk/anthropic";
 import { nanoid as nanoid2 } from "nanoid";
 import z17 from "zod";
 var DATA_DIR = ".algolia-wizard/data";
-var RECORD_MODEL = "claude-haiku-4-5";
 var MAX_RECORDS = 100;
 var BATCH_SIZE = 10;
 var MAX_BATCH_ATTEMPTS = 3;
@@ -3737,9 +3965,21 @@ function generateRecordTool(ctx, createModel = defaultCreateModel2) {
         const generateBatch = async (batchCount) => {
           let lastError;
           for (let attempt = 1; attempt <= MAX_BATCH_ATTEMPTS; attempt++) {
+            const profile = getModelProfile("quick" /* quick */);
+            const modelOptions = providerOptionsForProfile("quick" /* quick */);
+            const startedAt = Date.now();
             try {
-              const { output } = await generateText2({
-                model: anthropic(RECORD_MODEL),
+              const { output, usage } = await generateText2({
+                model: anthropic(profile.model),
+                maxOutputTokens: profile.maxOutputTokens,
+                providerOptions: {
+                  anthropic: {
+                    thinking: modelOptions.thinking,
+                    ...modelOptions.effort !== void 0 && {
+                      effort: modelOptions.effort
+                    }
+                  }
+                },
                 output: Output2.object({
                   schema: z17.object({
                     records: z17.array(recordSchema2).length(batchCount)
@@ -3751,9 +3991,23 @@ function generateRecordTool(ctx, createModel = defaultCreateModel2) {
                   `Variety seed: ${nanoid2()}. Use it to diversify values.`
                 ].filter(Boolean).join("\n")
               });
+              trackAgentRun({
+                operation: "sample-record-generation",
+                profile: "quick" /* quick */,
+                attempt,
+                durationMs: Date.now() - startedAt,
+                usage
+              });
               return output.records;
             } catch (err) {
               if (!NoObjectGeneratedError.isInstance(err)) throw err;
+              trackAgentRun({
+                operation: "sample-record-generation",
+                profile: "quick" /* quick */,
+                attempt,
+                durationMs: Date.now() - startedAt,
+                usage: err.usage
+              });
               lastError = err;
               logger.warn(
                 { entityName, batchCount, attempt, err },
@@ -3867,14 +4121,10 @@ var FS_READ_TOOLS = [
 ];
 
 // src/lib/agent.ts
-var MODEL_BY_SIZE = {
-  small: "claude-haiku-4-5",
-  medium: "claude-sonnet-4-6",
-  large: "claude-opus-4-8"
-};
 var MISSING_REPORT_STATUS_ERROR_MESSAGE = "Agent finished without calling reportStatus";
 var MISSING_REPORT_USER_MESSAGE = "This step ran into a problem finishing. Run the wizard again to retry it.";
 var REPORT_STATUS_RETRIES = 2;
+var ATTEMPT_NUMBER_OFFSET = 1;
 var PROVIDER_ERROR_USER_MESSAGE = "The AI service had trouble responding. Run the wizard again to retry this step.";
 function retryKind(err) {
   if (err instanceof Error && err.message === MISSING_REPORT_STATUS_ERROR_MESSAGE) {
@@ -3907,7 +4157,20 @@ async function runAgent(req) {
 }
 async function runAgentAttempt(req, attempt) {
   const start = Date.now();
-  logger.info({ startedAt: new Date(start).toISOString() }, "runAgent started");
+  const profileName = req.modelProfile ?? "implementation" /* implementation */;
+  const profile = getModelProfile(profileName);
+  const modelOptions = providerOptionsForProfile(profileName);
+  logger.info(
+    {
+      startedAt: new Date(start).toISOString(),
+      operation: req.operation,
+      profile: profileName,
+      model: profile.model,
+      effort: profile.effort,
+      thinking: profile.thinking
+    },
+    "runAgent started"
+  );
   const token = getAuthToken();
   if (!token) {
     throw new Error("Not authenticated: no user token available");
@@ -3934,7 +4197,16 @@ async function runAgentAttempt(req, attempt) {
     ] : []
   ];
   const agent = new ToolLoopAgent({
-    model: anthropic(MODEL_BY_SIZE[req.modelSize ?? "medium"]),
+    model: anthropic(profile.model),
+    maxOutputTokens: profile.maxOutputTokens,
+    providerOptions: {
+      anthropic: {
+        thinking: modelOptions.thinking,
+        ...modelOptions.effort !== void 0 && {
+          effort: modelOptions.effort
+        }
+      }
+    },
     // Cache tools + system on the last system block. Tools render before
     // system, so one breakpoint here caches both, reused on every loop turn
     // after the first.
@@ -3955,7 +4227,10 @@ async function runAgentAttempt(req, attempt) {
       tools: req.tools
     }),
     toolChoice: "required",
-    stopWhen: [hasToolCall("reportStatus")]
+    stopWhen: [
+      hasToolCall("reportStatus"),
+      stepCountIs(profile.maxSteps)
+    ]
   });
   const stream = await agent.stream({
     prompt: "Follow system instructions"
@@ -3986,13 +4261,20 @@ async function runAgentAttempt(req, attempt) {
   }
   const end = Date.now();
   const usage = await stream.totalUsage;
+  trackAgentRun({
+    operation: req.operation,
+    profile: profileName,
+    attempt: attempt + ATTEMPT_NUMBER_OFFSET,
+    durationMs: end - start,
+    usage
+  });
   logger.info(
     {
       finishedAt: new Date(end).toISOString(),
       durationMs: end - start,
-      // cachedInputTokens > 0 confirms prompt caching engaged. If it stays 0
-      // across turns, the tools+system prefix is under the model's min
-      // cacheable size (2048 tokens for sonnet-4-6) and caching is a no-op.
+      operation: req.operation,
+      profile: profileName,
+      model: profile.model,
       usage
     },
     "runAgent finished"
@@ -4073,6 +4355,7 @@ function prioritizeFrontendFrameworks(result) {
 }
 var detectLanguage = async () => {
   const result = await runAgent({
+    operation: "language-detection",
     instructions: [
       "Analyze the codebase and determine the programming languages and frameworks used",
       "If a superset language is found, exclude the subset language (e.g. TypeScript over JavaScript).",
@@ -4088,7 +4371,7 @@ var detectLanguage = async () => {
     ],
     tools: ["listFiles", "changeDirectory", "readFile", "searchFiles"],
     outputSchema: detectLanguageSchema,
-    modelSize: "small"
+    modelProfile: "quick" /* quick */
   });
   return prioritizeFrontendFrameworks(result);
 };
@@ -4164,9 +4447,11 @@ var MODE_CONFIG = {
 function runMode(mode, extraInstructions = []) {
   const { instructions, outputSchema } = MODE_CONFIG[mode];
   return runAgent({
+    operation: `code-analysis-${mode}`,
     instructions: [...instructions, ...extraInstructions],
     tools: READONLY_TOOLS,
-    outputSchema
+    outputSchema,
+    modelProfile: "analysis" /* analysis */
   });
 }
 async function runAnalysis(mode, extraInstructions = []) {
@@ -4544,6 +4829,7 @@ ${JSON.stringify(s.output, null, 2)}`
 }
 var reviewStep = async (ctx, options) => {
   const result = await runAgent({
+    operation: "workflow-review",
     instructions: [
       "Summarize what was accomplished in the workflow, leaving out verbose details.",
       "Base your summary only on the step outputs provided \u2014 do not read the repository.",
@@ -4558,7 +4844,7 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
     ],
     tools: [],
     outputSchema: reviewSchema,
-    modelSize: "small"
+    modelProfile: "quick" /* quick */
   });
   ctx.clearNotices();
   useWizard.getState().setReview(result);
@@ -4567,7 +4853,7 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
 
 // src/actions/implement.ts
 import z28 from "zod";
-import { mkdir as mkdir5, readFile as readFile8 } from "node:fs/promises";
+import { access, mkdir as mkdir5, readFile as readFile8 } from "node:fs/promises";
 import { join as join10, relative as relative6 } from "node:path";
 
 // src/lib/git.ts
@@ -4732,12 +5018,14 @@ var implementationOutputSchema = z28.object({
   // won't end up gitignored (it's public, meant to be committed).
   searchConfigFile: z28.string().optional()
 });
-var verificationOutputSchema = z28.object({
+var validationOutputSchema = z28.object({
   summary: z28.string(),
   sufficient: z28.boolean(),
-  additionalInstructions: z28.string().optional()
+  additionalInstructions: z28.string().optional(),
+  unrelatedFailure: z28.string().optional()
 });
-var MAX_IMPLEMENT_VERIFICATION_ATTEMPTS = 3;
+var MAX_IMPLEMENT_VALIDATION_ATTEMPTS = 3;
+var FIRST_IMPLEMENTATION_ATTEMPT = 1;
 var DEFAULT_IMPLEMENT_USE_CASES = ["ingestion", "search"];
 var INGEST_DIR = ".algolia-wizard";
 var INGESTION_SOURCE_PROMPT = "What data do you want to index?";
@@ -4746,6 +5034,9 @@ var INGESTION_SOURCE = {
   fileUpload: "Import a data file (CSV, JSON, TSV)",
   generated: "Generate sample data"
 };
+var BUILD_CHECK_PROMPT = "Run type-check and lint now? This can take several minutes on a large repository.";
+var MISSING_DEPENDENCIES_PROMPT = "Dependencies are not installed. Install them and run type-check and lint now?";
+var UNRELATED_FAILURE_PROMPT = "These checks are still failing and appear unrelated to the changes. Continue the investigation?";
 var FILE_UPLOAD_PATH_PROMPT = "Enter the path to your JSON, CSV, or TSV file (relative to the project root, or absolute):";
 var JS_LANGUAGES = ["javascript", "typescript", "jsx", "tsx", "node"];
 function lower(entries) {
@@ -4870,19 +5161,19 @@ function searchInstructions(input) {
     "The summary should be extremely concise; do not mention manual testing steps."
   ];
 }
-function verificationInstructions(input) {
+function validationInstructions(input) {
   return [
-    "Verify the Algolia implementation changes.",
-    `Verification tools found in the codebase: ${JSON.stringify(input.findings.verification ?? [])}.`,
-    "Run the project's own checks (lint, type check, tests) via runShell, using the project's commands \u2014 its task runner, manifest scripts, etc. Run every check that applies, not just the first.",
-    "If a check fails because packages or modules are missing, install the dependencies via runShell and re-run it rather than changing the code.",
-    "For issues caused by the implementation, make minimal fixes with writeFile and re-run the checks.",
-    "Do not make speculative fixes when no checks exist, a check cannot run, or failures are unrelated to these changes \u2014 note the limitation in your summary.",
-    "Do not add new Algolia functionality here; only validate and make minimal correctness fixes.",
-    `Do not modify "${input.ingestDir}/" unless a check reports an actionable issue in its files.`,
-    "Always call reportStatus with status=success once verification has run, even when sufficient=false.",
-    "Set sufficient=true only when the implementation is complete and checks pass (or fail for a clearly unrelated reason).",
-    "Set sufficient=false when the implementation is incomplete or has implementation-caused failures; include concrete additionalInstructions for the next pass."
+    "Validate the Algolia search implementation by inspecting the project source.",
+    "Confirm that the application renders exactly one search bar. Check for an old search bar and duplicate mounts.",
+    `Confirm that the search bar is mounted in ${input.searchLocation ? `"${input.searchLocation}"` : "the best always-rendered shared layout location"}.`,
+    "Confirm that the search component is reachable across the application and fits the surrounding layout.",
+    "Do not run the test suite or any test command.",
+    "Do not modify files. Report each implementation issue as a concrete instruction for the next implementation pass.",
+    `Available type-check and lint tools: ${JSON.stringify(input.findings.verification ?? [])}.`,
+    "Always call reportStatus with status=success after validation, even when sufficient=false.",
+    "Set sufficient=true only when the search bar is unique, correctly placed, and structurally complete.",
+    "Set sufficient=false for an implementation issue. Include concrete additionalInstructions for the next pass.",
+    "If a check fails only in untouched code, set unrelatedFailure to a concise failure description."
   ];
 }
 var IMPLEMENT_CONFIG = {
@@ -4894,9 +5185,9 @@ var IMPLEMENT_CONFIG = {
     title: "Algolia search",
     buildInstructions: searchInstructions
   },
-  verification: {
-    title: "Algolia verification",
-    buildInstructions: verificationInstructions
+  validation: {
+    title: "Algolia validation",
+    buildInstructions: validationInstructions
   }
 };
 var useCaseToolMap = {
@@ -4909,7 +5200,7 @@ var useCaseToolMap = {
     "notifyUser"
   ],
   search: [...FS_READ_TOOLS, "writeFile", "runShell", "notifyUser"],
-  verification: [...FS_READ_TOOLS, "writeFile", "runShell", "notifyUser"]
+  validation: [...FS_READ_TOOLS, "runShell", "notifyUser"]
 };
 function toolsForUseCase(useCase, ingestionSource) {
   const tools = useCaseToolMap[useCase];
@@ -4929,7 +5220,7 @@ function buildAgentInstructions(useCase, input, extraInstructions = []) {
   ];
 }
 function formatSummary(useCase, summary) {
-  const label = useCase === "ingestion" ? "Ingestion" : useCase === "search" ? "Search" : "Verification";
+  const label = useCase === "ingestion" ? "Ingestion" : useCase === "search" ? "Search" : "Validation";
   return `${label}: ${summary}`;
 }
 function parseIngestRecordCount(output) {
@@ -5021,9 +5312,62 @@ function makeToolContext(root, env = async () => ({})) {
     createShellContext({ env, approve: storeApproval(root) })
   );
 }
-function verificationRetryInstructions(verification) {
+function validationRetryInstructions(validation) {
+  return [
+    `Implementation insufficient. Address these findings before reporting completion: ${validation.additionalInstructions ?? validation.summary}`
+  ];
+}
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveBuildCheckPlan(ctx, repoRoot, input) {
+  if (!input.findings.verification?.length) {
+    return { run: false, installDependencies: false };
+  }
+  const installDependencies = isJsProject(input.language) && !await pathExists(join10(repoRoot, "node_modules"));
+  const accepted = Boolean(
+    await ctx.requestUserInput({
+      prompt: installDependencies ? MISSING_DEPENDENCIES_PROMPT : BUILD_CHECK_PROMPT,
+      promptType: "acceptReject",
+      options: ["Yes", "No"],
+      messages: []
+    })
+  );
+  return {
+    run: accepted,
+    installDependencies: accepted && installDependencies
+  };
+}
+function installCheckInstructions(plan, attempt) {
+  if (!plan.installDependencies) {
+    return [];
+  }
+  if (attempt === 1) {
+    return [
+      "Install dependencies once with the project's declared package manager before any check.",
+      "Do not try alternate install commands. If installation fails, stop the checks and report the limitation."
+    ];
+  }
+  return ["Dependencies were already installed. Do not install them again."];
+}
+function validationRunInstructions(plan, changedFiles, attempt) {
+  if (!plan.run) {
+    return [
+      "The developer chose to skip build checks. Do not install dependencies or run shell checks."
+    ];
+  }
   return [
-    `Implementation insufficient. Address these findings before reporting completion: ${verification.additionalInstructions ?? verification.summary}`
+    "The developer approved the optional build checks.",
+    ...installCheckInstructions(plan, attempt),
+    "Do not use npx, dlx, or another package runner that can download an undeclared tool.",
+    "Run the type check once with the project's existing command, when one is available.",
+    `Lint only these changed files: ${JSON.stringify(changedFiles)}. Do not run a full-project lint. If this list is empty, do not run lint.`,
+    "Do not use an autofix option during validation."
   ];
 }
 async function resolveIngestionSource(ctx, repoRoot) {
@@ -5178,10 +5522,11 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
     [INDEX_NAME_VAR]: targetIndex
   })) : void 0;
   const searchTools = makeToolContext(repoRoot);
-  async function runImplementationUseCase(currentUseCase, extraInstructions = []) {
+  async function runImplementationUseCase(currentUseCase, extraInstructions = [], isRetry = false) {
     if (agentRuns > 0) ctx.recordStepExecution();
     agentRuns += 1;
     return runAgent({
+      operation: `${currentUseCase}-implementation`,
       instructions: buildAgentInstructions(
         currentUseCase,
         input,
@@ -5189,16 +5534,23 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
       ),
       tools: toolsForUseCase(currentUseCase, input.ingestionSource),
       outputSchema: implementationOutputSchema,
+      modelProfile: isRetry ? "implementationRetry" /* implementationRetry */ : "implementation" /* implementation */,
       toolContext: currentUseCase === "ingestion" ? ingestionTools ?? searchTools : searchTools
     });
   }
-  async function runVerificationUseCase() {
+  async function runValidationUseCase(extraInstructions) {
     if (agentRuns > 0) ctx.recordStepExecution();
     agentRuns += 1;
     return runAgent({
-      instructions: buildAgentInstructions("verification", input),
-      tools: toolsForUseCase("verification"),
-      outputSchema: verificationOutputSchema,
+      operation: "search-validation",
+      instructions: buildAgentInstructions(
+        "validation",
+        input,
+        extraInstructions
+      ),
+      tools: toolsForUseCase("validation"),
+      outputSchema: validationOutputSchema,
+      modelProfile: "validation" /* validation */,
       toolContext: searchTools
     });
   }
@@ -5307,6 +5659,7 @@ ${detail}` : ""}`
   let searchConfigFile;
   if (useCases.includes("search")) {
     let extraInstructions = [];
+    let buildCheckPlan;
     const confirmedFrameworks = language.frameworks ?? [];
     const detectedFrameworks = scan.frameworks ?? [];
     const framework = confirmedFrameworks[0]?.name ?? "unknown";
@@ -5331,40 +5684,75 @@ ${detail}` : ""}`
       });
     };
     useWizard.getState().clearWrittenFiles();
-    for (let attempt = 1; attempt <= MAX_IMPLEMENT_VERIFICATION_ATTEMPTS; attempt++) {
-      if (attempt > 1) {
+    for (let attempt = FIRST_IMPLEMENTATION_ATTEMPT; attempt <= MAX_IMPLEMENT_VALIDATION_ATTEMPTS; attempt++) {
+      if (attempt > FIRST_IMPLEMENTATION_ATTEMPT) {
         logger.info(
           {
             attempt,
-            maxAttempts: MAX_IMPLEMENT_VERIFICATION_ATTEMPTS,
+            maxAttempts: MAX_IMPLEMENT_VALIDATION_ATTEMPTS,
             extraInstructions
           },
-          "implement: retrying search implementation after failed verification"
+          "implement: retrying search implementation after failed validation"
         );
       }
       const searchResult = await runImplementationUseCase(
         "search",
-        extraInstructions
+        extraInstructions,
+        attempt > FIRST_IMPLEMENTATION_ATTEMPT
       );
       summaries.push(formatSummary("search", searchResult.summary));
       if (searchResult.searchConfigFile) {
         searchConfigFile = searchResult.searchConfigFile;
       }
-      const verification = await runVerificationUseCase();
-      summaries.push(formatSummary("verification", verification.summary));
-      if (verification.sufficient) {
+      buildCheckPlan ??= await resolveBuildCheckPlan(ctx, repoRoot, input);
+      const searchFilesChanged = [
+        ...new Set(useWizard.getState().writtenFiles)
+      ].map((file) => relative6(repoRoot, file));
+      const validation = await runValidationUseCase(
+        validationRunInstructions(buildCheckPlan, searchFilesChanged, attempt)
+      );
+      summaries.push(formatSummary("validation", validation.summary));
+      const finalAttempt = attempt === MAX_IMPLEMENT_VALIDATION_ATTEMPTS;
+      let investigateUnrelated = false;
+      if (validation.unrelatedFailure && !finalAttempt) {
+        investigateUnrelated = Boolean(
+          await ctx.requestUserInput({
+            prompt: UNRELATED_FAILURE_PROMPT,
+            promptType: "acceptReject",
+            options: ["Yes", "No"],
+            messages: [validation.unrelatedFailure]
+          })
+        );
+        if (!investigateUnrelated) {
+          summaries.push("Validation: Skipped unrelated check failures.");
+          if (validation.sufficient) {
+            ctx.setUserInput("implementation", "success");
+            trackComponentGenerated(true, attempt);
+            break;
+          }
+        }
+      }
+      if (validation.sufficient && (!validation.unrelatedFailure || finalAttempt)) {
+        if (validation.unrelatedFailure) {
+          summaries.push("Validation: Unrelated check failures remain.");
+        }
         ctx.setUserInput("implementation", "success");
         trackComponentGenerated(true, attempt);
         break;
       }
-      if (attempt === MAX_IMPLEMENT_VERIFICATION_ATTEMPTS) {
+      if (finalAttempt) {
         ctx.setUserInput("implementation", "fail");
         trackComponentGenerated(false, attempt);
         throw new Error(
-          `Implementation verification failed after ${MAX_IMPLEMENT_VERIFICATION_ATTEMPTS} attempts: ${verification.additionalInstructions ?? verification.summary}`
+          `Unable to validate the implementation after ${MAX_IMPLEMENT_VALIDATION_ATTEMPTS} attempts: ${validation.additionalInstructions ?? validation.unrelatedFailure ?? validation.summary}`
+        );
+      }
+      extraInstructions = validation.sufficient ? [] : validationRetryInstructions(validation);
+      if (validation.unrelatedFailure && investigateUnrelated) {
+        extraInstructions.push(
+          `The developer asked you to investigate this check failure: ${validation.unrelatedFailure}`
         );
       }
-      extraInstructions = verificationRetryInstructions(verification);
     }
     if (searchConfigFile) {
       const ignoreStatus = await gitIgnoreStatus(
@@ -7074,7 +7462,7 @@ function delay(ms) {
 // package.json with { type: 'json' }
 var package_default2 = {
   name: "@algolia/wizard",
-  version: "0.65.0",
+  version: "0.67.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {