@clue-ai/cli 0.0.17 → 0.0.19

package/bin/clue-cli.mjs

@@ -20,6 +20,7 @@ import { runSemanticCi, runSemanticInventory } from "../src/semantic-ci.mjs";
 import { runSetupCheck } from "../src/setup-check.mjs";
 import { runSetupDetect } from "../src/setup-detect.mjs";
 import { runSetupDoctor } from "../src/setup-doctor.mjs";
+import { runSetupAgent } from "../src/setup-agent.mjs";
 import { buildAiSetupHelp } from "../src/setup-help.mjs";
 import { runSetupPrepare } from "../src/setup-prepare.mjs";
 import { installSetupSkills } from "../src/setup-tool.mjs";
@@ -850,6 +851,7 @@ const usage = () =>
     "Usage:",
     "  /clue-init",
     `  ${clueCliCommand("setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev --documents-url <url>")}`,
+    `  ${clueCliCommand("setup-agent --repo . [--ai-provider openai|anthropic --ai-provider-api-key <key> --ai-model <model>]")}`,
     `  ${clueCliCommand("setup-detect --repo .")}`,
     `  ${clueCliCommand("semantic-inventory --framework fastapi --backend-root-path backend --repo .")}`,
     `  ${clueCliCommand("semantic-agent-skills --output .clue/semantic-agent-skills.json")}`,
@@ -930,6 +932,19 @@ const main = async () => {
     return;
   }
 
+  if (command === "setup-agent") {
+    const report = await runSetupAgent({
+      env: process.env,
+      flags,
+      repoRoot,
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (report.status === "blocked") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (command === "setup") {
     const report = await installSetupSkills({
       repoRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clue-ai/cli",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "bin": {
     "clue-ai": "bin/clue-cli.mjs"

package/src/ai-provider.mjs

@@ -25,8 +25,7 @@ const providerBaseUrl = ({ provider, env = {}, request = {} }) => {
 };
 
 const providerModel = ({ env = {}, request = {} }) => {
-  const configuredModel =
-    env.CLUE_INIT_AI_MODEL || env.CLUE_AI_MODEL || request.ai_model;
+  const configuredModel = env.CLUE_AI_MODEL || request.ai_model;
   const model = String(configuredModel || "").trim();
   if (!model) {
     throw new Error("CLUE_AI_MODEL is required");
@@ -59,6 +58,27 @@ const parseOpenAiJson = async ({ response, emptyMessage }) => {
   return JSON.parse(content);
 };
 
+const parseOpenAiStrictToolJson = async ({ response, toolName, emptyMessage }) => {
+  const body = await response.json();
+  const output = Array.isArray(body?.output) ? body.output : [];
+  const functionCalls = output.flatMap((entry) => {
+    if (entry?.type === "function_call") return [entry];
+    if (Array.isArray(entry?.content)) {
+      return entry.content.filter((item) => item?.type === "function_call");
+    }
+    return [];
+  });
+  const toolCall = functionCalls.find((entry) => entry?.name === toolName);
+  const rawArguments = toolCall?.arguments ?? toolCall?.input;
+  if (typeof rawArguments === "string" && rawArguments.trim()) {
+    return JSON.parse(rawArguments);
+  }
+  if (rawArguments && typeof rawArguments === "object") {
+    return rawArguments;
+  }
+  throw new Error(emptyMessage);
+};
+
 const parseAnthropicJson = async ({ response, toolName, emptyMessage }) => {
   const body = await response.json();
   const toolUse = Array.isArray(body?.content)
@@ -84,6 +104,76 @@ const parseAnthropicJson = async ({ response, toolName, emptyMessage }) => {
   return JSON.parse(text);
 };
 
+export const callStrictToolAiProvider = async ({
+  config,
+  system,
+  user,
+  toolName,
+  toolDescription,
+  parameters,
+  failureMessage = "AI provider failed",
+  emptyMessage = "AI provider returned empty tool call",
+}) => {
+  const response =
+    config.provider === "anthropic"
+      ? await fetch(`${config.baseUrl}/messages`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": config.apiKey,
+            "anthropic-version": "2023-06-01",
+          },
+          body: JSON.stringify({
+            model: config.model,
+            max_tokens: 4096,
+            temperature: 0,
+            system,
+            messages: [{ role: "user", content: user }],
+            tools: [
+              {
+                name: toolName,
+                description: toolDescription,
+                input_schema: parameters,
+              },
+            ],
+            tool_choice: { type: "tool", name: toolName },
+          }),
+        })
+      : await fetch(`${config.baseUrl}/responses`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${config.apiKey}`,
+          },
+          body: JSON.stringify({
+            model: config.model,
+            input: [
+              { role: "system", content: system },
+              { role: "user", content: user },
+            ],
+            tools: [
+              {
+                type: "function",
+                name: toolName,
+                description: toolDescription,
+                strict: true,
+                parameters,
+              },
+            ],
+            tool_choice: { type: "function", name: toolName },
+            parallel_tool_calls: false,
+            temperature: 0,
+          }),
+        });
+
+  if (!response.ok) {
+    throw new Error(`${failureMessage}: ${response.status}`);
+  }
+  return config.provider === "anthropic"
+    ? parseAnthropicJson({ response, toolName, emptyMessage })
+    : parseOpenAiStrictToolJson({ response, toolName, emptyMessage });
+};
+
 export const callJsonAiProvider = async ({
   config,
   system,

package/src/fastapi-analyzer.mjs

@@ -11,6 +11,7 @@ const ROUTE_DECORATOR = new RegExp(
 const API_ROUTE_DECORATOR = /@(?<router>[A-Za-z_][A-Za-z0-9_]*)\.api_route\(\s*["'](?<path>[^"']+)["'][\s\S]*?methods\s*=\s*\[(?<methods>[^\]]+)\]/gi;
 const FUNCTION_PATTERN = /(?:async\s+def|def)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
 const ROUTER_ASSIGNMENT = /\b(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*APIRouter\s*\(/g;
+const ROUTER_ALIAS_ASSIGNMENT = /^\s*(?<alias>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?<owner>[A-Za-z_][A-Za-z0-9_]*)\.(?<routerName>[A-Za-z_][A-Za-z0-9_]*)\s*$/gm;
 const INCLUDE_ROUTER_CALL = /\b(?<owner>[A-Za-z_][A-Za-z0-9_]*)\.include_router\s*\(/g;
 const FROM_IMPORT = /^\s*from\s+(?<module>[A-Za-z0-9_.]+|\.+[A-Za-z0-9_.]*)\s+import\s+(?<names>[A-Za-z0-9_,\s]+)$/gm;
 const IMPORT_MODULE = /^\s*import\s+(?<modules>[A-Za-z0-9_.,\s]+)$/gm;
@@ -214,9 +215,35 @@ const parseImports = ({ source, currentRelativePath, filesByRelativePath }) => {
 
 const routerKey = (file, routerName) => `${file}::${routerName}`;
 
-const resolveRouterTarget = ({ target, relativePath, imports }) => {
+const parseRouterAliases = ({ source, relativePath, imports }) => {
+  const aliases = new Map();
+  for (const match of source.matchAll(ROUTER_ALIAS_ASSIGNMENT)) {
+    const importedOwner = imports.get(match.groups.owner);
+    if (importedOwner?.file && !importedOwner.name) {
+      aliases.set(match.groups.alias, {
+        file: importedOwner.file,
+        name: match.groups.routerName,
+      });
+      continue;
+    }
+    aliases.set(match.groups.alias, {
+      file: relativePath,
+      name: match.groups.routerName,
+    });
+  }
+  return aliases;
+};
+
+const resolveRouterTarget = ({ target, relativePath, imports, routerAliases }) => {
   const parts = target.split(".");
   if (parts.length === 1) {
+    const aliased = routerAliases.get(target);
+    if (aliased) {
+      return {
+        file: aliased.file,
+        routerName: aliased.name,
+      };
+    }
     const imported = imports.get(target);
     return {
       file: imported?.file ?? relativePath,
@@ -236,7 +263,7 @@ const resolveRouterTarget = ({ target, relativePath, imports }) => {
   };
 };
 
-const parseIncludeRouters = ({ source, relativePath, imports }) => {
+const parseIncludeRouters = ({ source, relativePath, imports, routerAliases }) => {
   const includes = [];
   for (const match of source.matchAll(INCLUDE_ROUTER_CALL)) {
     const openParenIndex = match.index + match[0].length - 1;
@@ -249,6 +276,7 @@ const parseIncludeRouters = ({ source, relativePath, imports }) => {
       target: routerMatch.groups.router,
       relativePath,
       imports,
+      routerAliases,
     });
     includes.push({
       ownerName: match.groups.owner,
@@ -359,6 +387,11 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
       currentRelativePath: record.relativePath,
       filesByRelativePath,
     });
+    record.routerAliases = parseRouterAliases({
+      source: record.source,
+      relativePath: record.relativePath,
+      imports: record.imports,
+    });
   }
 
   const routerPrefixesByKey = new Map();
@@ -375,6 +408,7 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
       source: record.source,
       relativePath: record.relativePath,
       imports: record.imports,
+      routerAliases: record.routerAliases,
     })) {
       const parentKey = record.routerPrefixes.has(include.ownerName)
         ? routerKey(record.relativePath, include.ownerName)

package/src/lifecycle-init.mjs

@@ -1,6 +1,10 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { callJsonAiProvider, resolveAiProviderConfig } from "./ai-provider.mjs";
+import {
+  callJsonAiProvider,
+  callStrictToolAiProvider,
+  resolveAiProviderConfig,
+} from "./ai-provider.mjs";
 import {
   extractExecutableModuleStatements,
   findLifecycleCallApiNames,
@@ -22,6 +26,13 @@ const API_NAMES = new Set([
 ]);
 
 const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const DEPENDENCY_CONTEXT_FILE_CANDIDATES = [
+  "package.json",
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+];
 const MAX_CONTEXT_FILES = 180;
 const MAX_FILE_CHARS = 12_000;
 const MAX_TOTAL_CHARS = 360_000;
@@ -29,6 +40,71 @@ const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
 const WRONG_FRONTEND_SDK_PACKAGES = ["clue-js-sdk", "@clue/browser-sdk"];
 const CLUE_SETUP_ADDITION_PATTERN =
   /\b(?:ClueInit|ClueIdentify|ClueSetAccount|ClueLogout|clue_init_fastapi|clue_init_django|clue-fastapi-sdk|clue-django-sdk|CLUE_[A-Z0-9_]+|browserTokenProvider|clue[-_])|@clue-ai\/browser-sdk/i;
+const LIFECYCLE_PLAN_TOOL_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["ready", "blocked"] },
+    edits: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file_path: { type: "string" },
+          find: { type: "string" },
+          replace: { type: "string" },
+        },
+        required: ["file_path", "find", "replace"],
+        additionalProperties: false,
+      },
+    },
+    lifecycle_insertions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          api_name: {
+            type: "string",
+            enum: [
+              "ClueInit",
+              "ClueIdentify",
+              "ClueSetAccount",
+              "ClueLogout",
+            ],
+          },
+          file_path: { type: "string" },
+          confidence: { type: "number" },
+          reason: { type: "string" },
+        },
+        required: ["api_name", "file_path", "confidence", "reason"],
+        additionalProperties: false,
+      },
+    },
+    blockers: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          reason: { type: "string" },
+          evidence: { type: ["string", "null"] },
+        },
+        required: ["reason", "evidence"],
+        additionalProperties: false,
+      },
+    },
+    warnings: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+  required: [
+    "status",
+    "edits",
+    "lifecycle_insertions",
+    "blockers",
+    "warnings",
+  ],
+  additionalProperties: false,
+};
 
 const nonEmpty = (value, field) => {
   if (typeof value !== "string" || value.trim() === "") {
@@ -47,6 +123,33 @@ const safeRelativePath = (repoRoot, filePath) => {
   return { absolutePath, relativePath };
 };
 
+const startsWithAllowedPath = (filePath, allowedPath) => {
+  const normalizedFilePath = filePath.replace(/\\/g, "/").replace(/^\/+/, "");
+  const normalizedAllowedPath = String(allowedPath ?? "")
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+  return (
+    normalizedAllowedPath !== "" &&
+    (normalizedFilePath === normalizedAllowedPath ||
+      normalizedFilePath.startsWith(`${normalizedAllowedPath}/`))
+  );
+};
+
+const assertAllowedWritePath = ({ allowedWritePaths, filePath }) => {
+  if (!Array.isArray(allowedWritePaths) || allowedWritePaths.length === 0) {
+    return;
+  }
+  if (
+    allowedWritePaths.some((allowedPath) =>
+      startsWithAllowedPath(filePath, allowedPath),
+    )
+  ) {
+    return;
+  }
+  throw new Error(`setup-agent cannot edit outside allowed setup paths: ${filePath}`);
+};
+
 const assertApiName = (apiName) => {
   if (!API_NAMES.has(apiName)) {
     throw new Error(`unsupported lifecycle API: ${apiName}`);
@@ -458,7 +561,11 @@ const buildLifecycleEvidenceSourceMap = async ({
   return sourceByPath;
 };
 
-export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
+export const applyLifecyclePlan = async ({
+  repoRoot,
+  plan: rawPlan,
+  allowedWritePaths,
+}) => {
   const plan = normalizePlan(rawPlan);
   if (plan.status === "blocked") {
     throw new Error(
@@ -478,6 +585,7 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
       repoRoot,
       edit.file_path,
     );
+    assertAllowedWritePath({ allowedWritePaths, filePath: relativePath });
     assertNoForbiddenInstrumentation(edit.replace);
     const current =
       sourceByPath.get(relativePath)?.text ??
@@ -499,6 +607,10 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
   }
   await buildLifecycleEvidenceSourceMap({ repoRoot, plan, sourceByPath });
   for (const insertion of plan.lifecycleInsertions) {
+    assertAllowedWritePath({
+      allowedWritePaths,
+      filePath: insertion.file_path,
+    });
     const source = sourceByPath.get(insertion.file_path);
     if (!source) {
       throw new Error(
@@ -520,6 +632,42 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
   };
 };
 
+const dependencyContextCandidatePaths = (allowedSourcePaths) => [
+  ...DEPENDENCY_CONTEXT_FILE_CANDIDATES,
+  ...allowedSourcePaths.flatMap((root) => {
+    const normalized = root.replace(/\/+$/, "");
+    const roots =
+      normalized.endsWith("/src") || normalized.endsWith("/app")
+        ? [normalized, dirname(normalized)]
+        : [normalized];
+    return roots.flatMap((candidateRoot) =>
+      DEPENDENCY_CONTEXT_FILE_CANDIDATES.map((file) =>
+        join(candidateRoot, file),
+      ),
+    );
+  }),
+];
+
+const addContextFile = async ({
+  absolutePath,
+  context,
+  repoRoot,
+  totalChars,
+}) => {
+  const text = await readFile(absolutePath, "utf8");
+  const snippet = text.slice(0, MAX_FILE_CHARS);
+  const nextTotalChars = totalChars + snippet.length;
+  if (nextTotalChars > MAX_TOTAL_CHARS) {
+    return { totalChars, added: false };
+  }
+  context.push({
+    file_path: relative(resolve(repoRoot), absolutePath),
+    source: snippet,
+    truncated: text.length > snippet.length,
+  });
+  return { totalChars: nextTotalChars, added: true };
+};
+
 const readContextFiles = async ({ repoRoot, request }) => {
   const files = await listAllowedSourceFiles({
     repoRoot,
@@ -530,17 +678,38 @@ const readContextFiles = async ({ repoRoot, request }) => {
   const context = [];
   let totalChars = 0;
   for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
-    const text = await readFile(absolutePath, "utf8");
-    const snippet = text.slice(0, MAX_FILE_CHARS);
-    totalChars += snippet.length;
-    if (totalChars > MAX_TOTAL_CHARS) {
+    const result = await addContextFile({
+      absolutePath,
+      context,
+      repoRoot,
+      totalChars,
+    });
+    totalChars = result.totalChars;
+    if (!result.added) {
       break;
     }
-    context.push({
-      file_path: relative(resolve(repoRoot), absolutePath),
-      source: snippet,
-      truncated: text.length > snippet.length,
-    });
+  }
+  const seen = new Set(context.map((entry) => entry.file_path));
+  for (const candidatePath of dependencyContextCandidatePaths(
+    request.allowed_source_paths,
+  )) {
+    const { absolutePath, relativePath } = safeRelativePath(
+      repoRoot,
+      candidatePath,
+    );
+    if (seen.has(relativePath)) continue;
+    try {
+      const result = await addContextFile({
+        absolutePath,
+        context,
+        repoRoot,
+        totalChars,
+      });
+      totalChars = result.totalChars;
+      if (result.added) seen.add(relativePath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
   }
   return context;
 };
@@ -567,8 +736,8 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Find all clear account, workspace, organization, or tenant resolution paths and add ClueSetAccount to every one of them.",
       "Find all clear logout or session reset paths and add ClueLogout to every one of them.",
       "Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
-      "For frontend code, add or use the real @clue-ai/browser-sdk dependency. Do not invent clue-js-sdk, @clue/browser-sdk, local SDK modules, global window.Clue APIs, or dynamic imports that hide a missing SDK.",
-      "For FastAPI backends, add the clue-fastapi-sdk dependency when missing, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
+      "For frontend code, add or use the real @clue-ai/browser-sdk dependency through the latest channel (@clue-ai/browser-sdk@latest). Do not invent clue-js-sdk, @clue/browser-sdk, local SDK modules, global window.Clue APIs, or dynamic imports that hide a missing SDK.",
+      "For FastAPI backends, add the unpinned clue-fastapi-sdk dependency when missing so pip resolves the latest release, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
       "For Django backends, use clue-django-sdk only after dependency or registry verification confirms it is installable. If it cannot be verified, report a blocker instead of adding guessed imports or dependencies.",
       "For other backend frameworks, treat SDK existence as unverified unless present in dependency files or verified through package-manager/official documentation. If no backend SDK exists or verification is impossible, report a blocker instead of silently frontend-only setup.",
       "Do not add broad ClueTrack instrumentation.",
@@ -580,20 +749,25 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Use environment variable names for Clue configuration values.",
       "For Python/FastAPI code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_API_KEY, and CLUE_INGEST_ENDPOINT from the backend env block.",
       "CLUE_API_BASE_URL is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
-      "For Next.js browser/client code, read NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, NEXT_PUBLIC_CLUE_SERVICE_KEY, and NEXT_PUBLIC_CLUE_INGEST_ENDPOINT from the frontend .env.local block.",
+      "For Next.js browser/client code, read NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, NEXT_PUBLIC_CLUE_SERVICE_KEY, NEXT_PUBLIC_CLUE_INGEST_ENDPOINT, and NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT from the frontend .env.local block.",
       "Do not read process.env.CLUE_PROJECT_KEY, process.env.CLUE_ENVIRONMENT, process.env.CLUE_SERVICE_KEY, or process.env.CLUE_INGEST_ENDPOINT in Next.js browser/client code, and do not add non-public CLUE_* fallbacks there.",
+      "Frontend SDK adapter code is contract-owned Clue setup wiring. The AI may choose the existing import/mount point, but must not invent token URL, env, or initialization semantics.",
+      "For Next.js frontend adapters, read the full customer-backend browser-token proxy URL from NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT. Do not derive it from NEXT_PUBLIC_API_URL, generic app API env names, detected backend ports, or relative frontend-origin paths.",
+      "Do not mix stale browser-token paths such as /api/clue/browser-token, /clue/browser-tokens, or /browser-tokens with the canonical /api/v1/clue/browser-tokens path.",
+      "Do not call ClueInit with empty-string fallbacks for required NEXT_PUBLIC_CLUE_* values. If required Clue env is absent, skip initialization and report the missing env names.",
+      "If a singleton guard is used, do not set initialized = true before ClueInit has actually been called with required config present.",
       "For non-Next.js browser code, use the exact frontend env names written in .env.clue for that service instead of inventing a framework-specific prefix.",
       "Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
       "Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
       "Keep the four setup API hops distinct: customer frontend -> customer backend /api/v1/clue/browser-tokens, customer backend -> Clue /api/v1/ingest/browser-tokens, customer frontend -> Clue /api/v1/ingest/browser, and customer backend -> Clue /api/v1/ingest/backend.",
       "The local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as /api/v1/clue/browser-tokens; do not use a generic path such as /browser-tokens that could be confused with product behavior. It must call Clue server-side at /api/v1/ingest/browser-tokens.",
-      "The frontend browserTokenProvider must send the same service key used by ClueInit to the customer backend token endpoint. For Next.js this value comes from NEXT_PUBLIC_CLUE_SERVICE_KEY.",
+      "The frontend browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT and send the same service key used by ClueInit to the customer backend token endpoint. For Next.js this value comes from NEXT_PUBLIC_CLUE_SERVICE_KEY.",
       "The browser token request must include the frontend service key used by ClueInit. Project key and environment may be included only as public consistency hints; the backend must use server configuration or validate them against server configuration before calling Clue.",
       "The backend browser token proxy must derive request origin from trusted request headers or server request metadata. Do not trust origin, projectKey, or environment from JSON/body payload fields when calling Clue with server CLUE_API_KEY.",
       "For browser token proxy code, the service key sent to Clue must be the frontend ClueInit serviceKey from the browser request, not the backend service's CLUE_SERVICE_KEY.",
       "If a backend-owned browser token endpoint is implemented, read CLUE_API_BASE_URL from the backend env block and normalize it so values with or without a trailing /api/v1 do not produce duplicate paths.",
-      "Do not add @clue-ai/browser-sdk or backend SDK dependencies with * or latest; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
+      "Install Clue SDK dependencies through the latest channel. Frontend package managers must use @clue-ai/browser-sdk@latest; Python backend dependency declarations must not pin clue-fastapi-sdk or clue-django-sdk to a fixed version.",
       "Prefer minimal edits that engineers can review in one PR.",
       "Do not run broad formatters, import sorters, cleanup tools, or style-only edits. Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring.",
       "If a lifecycle point is unclear, skip that edit and include a warning.",
@@ -614,6 +788,8 @@ const buildLifecyclePrompt = ({ request, files }) =>
       browser_ingest_endpoint_env: "framework_specific",
       nextjs_browser_ingest_endpoint_env: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
       client_backend_browser_token_proxy_path: "/api/v1/clue/browser-tokens",
+      nextjs_browser_token_endpoint_env:
+        "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
       clue_backend_browser_token_issue_path: "/api/v1/ingest/browser-tokens",
       nextjs_browser_service_key_env: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
       service_key: request.service_key,
@@ -660,3 +836,45 @@ export const planLifecycleInsertions = async ({ repoRoot, request, env }) => {
     emptyMessage: "AI provider returned empty lifecycle plan",
   });
 };
+
+export const planLifecycleInsertionsStrict = async ({
+  repoRoot,
+  request,
+  env,
+  failureContext = null,
+}) => {
+  const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "CLUE_AI_PROVIDER_API_KEY is required for setup-agent lifecycle planning",
+    );
+  }
+  const setupAgentEnv = {
+    ...env,
+    CLUE_AI_PROVIDER_BASE_URL: undefined,
+  };
+  const files = await readContextFiles({ repoRoot, request });
+  const prompt = JSON.parse(buildLifecyclePrompt({ request, files }));
+  const user = JSON.stringify({
+    ...prompt,
+    setup_agent_mode: {
+      execution_owner: "clue_cli",
+      model_role: "lifecycle_plan_only",
+      direct_file_writes_allowed: false,
+      setup_watch_allowed: false,
+      retry_failure_context: failureContext,
+    },
+  });
+  return callStrictToolAiProvider({
+    config: resolveAiProviderConfig({ env: setupAgentEnv, apiKey }),
+    system:
+      "You are a safe code-edit planner for Clue SDK setup. Call the provided function with a schema-valid lifecycle plan only.",
+    user,
+    toolName: "propose_clue_lifecycle_plan",
+    toolDescription:
+      "Return the exact Clue SDK lifecycle insertion plan for the local CLI to validate and apply.",
+    parameters: LIFECYCLE_PLAN_TOOL_SCHEMA,
+    failureMessage: "AI provider failed during setup-agent lifecycle planning",
+    emptyMessage: "AI provider returned empty setup-agent lifecycle plan",
+  });
+};

package/src/public-schema.cjs

@@ -185,6 +185,7 @@ const semanticSnapshotPurposeChangeStateValues = [
 const semanticSnapshotActiveSemanticSourceValues = [
     "previous_reused",
     "new_confirmed",
+    "new_unconfirmed",
     "previous_kept_pending_review",
 ];
 const targetObjectKeySchema = nonEmptyStringSchema.regex(snakeSegmentPattern, {