scai 0.1.178 → 1.0.0

package/dist/agent/runtime/runAgentPlanOnly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runAgentPlanOnly.js","sourceRoot":"","sources":["../../../src/agent/runtime/runAgentPlanOnly.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runs explicit plan-only mode for the new simple agent runtime.\n *\n * Why this file exists:\n * - `scai plan` and `/plan` should use the new runtime without entering the full answer loop\n * - plan-only runs should reuse the same understand, plan action, and step logging pieces\n * - this stage keeps planning in memory only and does not try to persist or resume plan state\n */\nimport type { AgentUI } from \"../../types.js\";\nimport {\n  emitAgentStepStateMessage,\n  emitAgentTaskStateMessage,\n  emitConsoleMessage,\n  shouldShowConsoleTiming,\n} from \"../../utils/consolePresentation.js\";\nimport { buildActions } from \"../actions/index.js\";\nimport {\n  getErrorMessage,\n  getErrorTrace,\n  logAgentError,\n  logAgentStepInput,\n  recordAgentArtifact,\n  recordAgentEvent,\n} from \"../logging/index.js\";\nimport {\n  formatStepMilestone,\n  formatStepProgress,\n  formatUnderstandMilestone,\n  formatUnderstandProgress,\n} from \"./progress.js\";\nimport { createRuntimeStep, finalizeTask, finishStep, startStep } from \"../state/index.js\";\nimport { buildTools } from \"../tools/index.js\";\nimport { runUnderstand } from \"./understand.js\";\nimport { AgentRuntimeError, type AgentMemory, type AgentPlanArtifact, type AgentStep } from \"../types.js\";\nimport {\n  applyUnderstandResult,\n  recordStepCreated,\n  recordStepFailure,\n  recordStepFinished,\n  recordStepStarted,\n  recordTaskFinalized,\n} from \"./lifecycle.js\";\n\nfunction emitMilestone(ui: AgentUI, message: string): void {\n  if (!shouldShowConsoleTiming()) {\n    emitConsoleMessage(ui, message);\n  }\n}\n\nfunction emitStepState(ui: AgentUI, step: AgentStep, from: string, to: string): void {\n  emitAgentStepStateMessage(ui, {\n    stepId: step.id,\n    action: step.action,\n    from,\n    to,\n  });\n}\n\nfunction renderPlanOnlyAnswer(plan: AgentPlanArtifact): string {\n  const lines = [\n    `Plan goal: ${plan.goal}`,\n    \"\",\n    `Why: ${plan.why}`,\n    \"\",\n    \"Steps:\",\n  ];\n\n  for (const [index, step] of plan.steps.entries()) {\n    lines.push(`${index + 1}. ${step.purpose} (${step.action})`);\n  }\n\n  return lines.join(\"\\n\");\n}\n\nexport async function runAgentPlanOnly(memory: AgentMemory, ui: AgentUI): Promise<void> {\n  const tools = buildTools();\n  const actions = buildActions(tools, ui);\n  let activeStep: AgentStep | undefined;\n\n  try {\n    ui.update(formatUnderstandProgress(memory.task));\n    emitMilestone(ui, formatUnderstandMilestone());\n    const understand = await runUnderstand(memory, ui);\n    applyUnderstandResult(memory, understand);\n\n    activeStep = createRuntimeStep(\n      memory,\n      \"plan\",\n      \"Create a short implementation plan without entering execution.\",\n      {},\n      [\"ordered plan steps\"]\n    );\n    recordAgentEvent(memory, \"step-created\", {\n      action: activeStep.action,\n      args: activeStep.args,\n      purpose: activeStep.purpose,\n    }, activeStep.id);\n    emitStepState(ui, activeStep, \"created\", activeStep.status);\n    ui.update(formatStepProgress(activeStep, memory.task));\n    emitMilestone(ui, formatStepMilestone(activeStep));\n    logAgentStepInput(memory, activeStep);\n\n    const fromStatus = activeStep.status;\n    startStep(memory, activeStep);\n    emitStepState(ui, activeStep, fromStatus, activeStep.status);\n    recordStepStarted(memory, activeStep);\n\n    const result = await actions.plan.run(memory, {});\n    finishStep(memory, activeStep, result.ok ? \"done\" : \"failed\", result.summary);\n    emitStepState(ui, activeStep, \"running\", activeStep.status);\n    recordStepFinished(memory, activeStep, result.summary, {\n      action: activeStep.action,\n      result: {\n        ok: result.ok,\n        summary: result.summary,\n        output: result.output ?? null,\n      },\n    });\n\n    const latestPlan = memory.artifacts.plans[memory.artifacts.plans.length - 1];\n    if (!latestPlan) {\n      throw new AgentRuntimeError({\n        stage: \"plan-only\",\n        message: \"Plan-only run finished without a plan artifact.\",\n        stepId: activeStep.id,\n        action: \"plan\",\n      });\n    }\n\n    const answer = renderPlanOnlyAnswer(latestPlan);\n    memory.artifacts.finalAnswer = answer;\n    recordAgentArtifact(memory.artifacts, \"final-answer\", answer);\n\n    finalizeTask(memory, \"done\", \"plan-only-completed\");\n    emitAgentTaskStateMessage(ui, {\n      from: \"active\",\n      to: \"done\",\n      reason: \"plan-only-completed\",\n    });\n    recordTaskFinalized(memory);\n  } catch (error) {\n    const details = error instanceof AgentRuntimeError\n      ? error.details\n      : {\n          stage: \"plan-only\",\n          message: getErrorMessage(error),\n          stepId: activeStep?.id,\n          action: activeStep?.action,\n        };\n\n    if (activeStep?.status === \"running\") {\n      finishStep(memory, activeStep, \"failed\", details.message);\n      emitStepState(ui, activeStep, \"running\", activeStep.status);\n      recordStepFailure(memory, activeStep, details.message, details.stage);\n    }\n\n    finalizeTask(memory, \"failed\", details.stage);\n    emitAgentTaskStateMessage(ui, {\n      from: \"active\",\n      to: \"failed\",\n      reason: details.stage,\n    });\n    recordAgentEvent(memory, \"task-failed\", {\n      stage: details.stage,\n      message: details.message,\n      action: details.action ?? null,\n      stepId: details.stepId ?? null,\n      status: \"failed\",\n      mode: memory.task.mode,\n    }, details.stepId);\n    logAgentError(memory, details, {\n      currentStepId: memory.task.currentStepId ?? null,\n      turnCount: memory.task.turnCount,\n      trace: getErrorTrace(error) ?? null,\n    });\n    recordTaskFinalized(memory);\n    throw (error instanceof AgentRuntimeError ? error : new AgentRuntimeError(details, error));\n  }\n}\n"]}

package/dist/agent/runtime/understand.js

@@ -0,0 +1,336 @@
+/**
+ * Runs the narrow understand phase for the new simple agent runtime.
+ *
+ * Why this file exists:
+ * - understand should stay outside the main loop
+ * - query normalization should stay small and factual
+ * - alternative interpretations should stay bounded and explicit
+ * - prompt and parsing ownership should stay outside this runtime wiring
+ */
+import { generate } from "../../lib/generate.js";
+import { extractFileReferences } from "../../utils/extractFileReferences.js";
+import { emitAgentLlmTimingMessage } from "../../utils/consolePresentation.js";
+import { getErrorMessage, getErrorTrace, logAgentLlmFailure, logAgentLlmInput, logAgentLlmOutput, recordAgentEvent, } from "../logging/index.js";
+import { renderUnderstandPrompt } from "../prompting/index.js";
+import { renderResumeCheckpointForPrompt } from "../resume/checkpoint.js";
+import { parseStructuredJson } from "../structuredOutput/index.js";
+import { uniqueStrings } from "../evidence/index.js";
+import { AgentRuntimeError, } from "../types.js";
+import { nowLocalIso } from "../../utils/time.js";
+const VALID_QUERY_SCOPES = new Set([
+    "targeted",
+    "multi-file",
+    "broad-repo",
+    "general",
+]);
+const NON_TARGET_EXPLICIT_TOKENS = new Set([
+    "this",
+    "that",
+    "these",
+    "those",
+    "it",
+    "also",
+    "repo",
+    "repository",
+    "codebase",
+    "project",
+]);
+const MAX_SEARCH_TERM_GROUPS = 4;
+const MAX_TERMS_PER_GROUP = 6;
+const MAX_TERM_WORDS = 4;
+const MAX_TERM_LENGTH = 40;
+const GENERIC_SEARCH_TERMS = new Set([
+    "agent",
+    "code",
+    "command",
+    "commands",
+    "config",
+    "configuration",
+    "entry",
+    "entrypoint",
+    "entrypoints",
+    "execute",
+    "file",
+    "files",
+    "path",
+    "paths",
+    "point",
+    "points",
+    "repo",
+    "repository",
+    "run",
+    "runner",
+    "script",
+    "scripts",
+    "source",
+    "sources",
+    "test",
+    "tests",
+]);
+/**
+ * Detects broad tool or concept questions that do not point at this repo.
+ * Example: "how do I use git bash to save a diff?" should stay general.
+ * Example: "what is recursion?" should stay general.
+ */
+function looksLikeGeneralKnowledgeQuestion(query, primaryIntent) {
+    const text = `${String(query ?? "")} ${String(primaryIntent ?? "")}`;
+    const lowered = text.toLowerCase();
+    if (/\b(this repo|the repo|repo|repository|codebase|project)\b/.test(lowered)) {
+        return false;
+    }
+    if (/[a-z][A-Z]/.test(text) || /[A-Z]{2,}[a-z]/.test(text) || text.includes("_")) {
+        return false;
+    }
+    if (/(?:^|[\s"'`])(?:\.{0,2}\/)?[A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+(?:$|[\s"'`])/m.test(text) ||
+        /(?:^|[\s"'`])[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,10}(?:$|[\s"'`!?.,:;])/m.test(text) ||
+        /["'`][^"'`\n]{4,}["'`]/.test(text)) {
+        return false;
+    }
+    if (/\b(where|which|find|locate|identify)\b/.test(lowered) &&
+        /\b(set|configured|configuration|entry|entrypoint|owner|limit|count|max)\b/.test(lowered)) {
+        return false;
+    }
+    return /\b(what is|what does|how do i|how can i|how to|how should i|why does|when should i)\b/.test(lowered);
+}
+function shouldKeepExplicitTarget(target) {
+    const trimmed = String(target ?? "").trim();
+    if (!trimmed) {
+        return false;
+    }
+    const lowered = trimmed.toLowerCase();
+    if (NON_TARGET_EXPLICIT_TOKENS.has(lowered)) {
+        return false;
+    }
+    if (/^(this|the)\s+(repo|repository|codebase|project)$/i.test(trimmed)) {
+        return false;
+    }
+    return true;
+}
+function validateQueryScope(rawScope, explicitTargets, query, primaryIntent) {
+    const meaningfulExplicitTargets = explicitTargets
+        .map((target) => String(target ?? "").trim())
+        .filter(Boolean);
+    const normalizedScope = VALID_QUERY_SCOPES.has(rawScope)
+        ? rawScope
+        : "general";
+    if (meaningfulExplicitTargets.length > 1) {
+        return "multi-file";
+    }
+    if (meaningfulExplicitTargets.length === 1 && normalizedScope === "general") {
+        return "targeted";
+    }
+    if (meaningfulExplicitTargets.length === 0 &&
+        normalizedScope === "targeted" &&
+        looksLikeGeneralKnowledgeQuestion(query, primaryIntent)) {
+        return "general";
+    }
+    return normalizedScope;
+}
+function looksLikeSearchAnchor(term) {
+    const value = String(term ?? "").trim();
+    if (!value) {
+        return false;
+    }
+    if (value.startsWith("/")) {
+        return true;
+    }
+    if (/[A-Z]/.test(value) && /[a-z]/.test(value)) {
+        return true;
+    }
+    if (/[._/-]/.test(value)) {
+        return true;
+    }
+    if (/[0-9]/.test(value)) {
+        return true;
+    }
+    return false;
+}
+function isGenericSearchTerm(term) {
+    return GENERIC_SEARCH_TERMS.has(String(term ?? "").trim().toLowerCase());
+}
+function looksLikeCommandPathTerm(term) {
+    const value = String(term ?? "").trim();
+    if (!value) {
+        return false;
+    }
+    return value.startsWith("/") || /[./-]/.test(value);
+}
+function requiresRepoAnchorGroup(query, primaryIntent) {
+    const lowered = `${String(query ?? "")} ${String(primaryIntent ?? "")}`.toLowerCase();
+    return /\b(where|which|what|find|locate|identify)\b/.test(lowered)
+        && /\b(set|setting|configured|configuration|register|registered|entry|entrypoint|command|commands|limit|count|max|owner)\b/.test(lowered);
+}
+function isValidSearchTermGroupKind(value) {
+    return value === "repo-anchor" || value === "command-path" || value === "generic";
+}
+function normalizeSearchTermGroups(rawGroups, query, primaryIntent) {
+    if (!Array.isArray(rawGroups)) {
+        return [];
+    }
+    const seenGroupKeys = new Set();
+    const seenGenericTerms = new Set();
+    const seenAnchors = new Set();
+    const seenNonGenericTerms = new Set();
+    const normalizedGroups = [];
+    const repoAnchorRequired = requiresRepoAnchorGroup(query, primaryIntent);
+    for (const rawGroup of rawGroups) {
+        if (!rawGroup || typeof rawGroup !== "object" || Array.isArray(rawGroup)) {
+            continue;
+        }
+        const kind = isValidSearchTermGroupKind(rawGroup.kind)
+            ? rawGroup.kind
+            : null;
+        const rawTerms = rawGroup.terms;
+        if (!kind || !Array.isArray(rawTerms)) {
+            continue;
+        }
+        const seenTerms = new Set();
+        const group = [];
+        for (const rawTerm of rawTerms) {
+            const term = String(rawTerm ?? "").trim();
+            if (!term || term.length > MAX_TERM_LENGTH) {
+                continue;
+            }
+            if ((term.match(/\s+/g)?.length ?? 0) + 1 > MAX_TERM_WORDS) {
+                continue;
+            }
+            const normalizedKey = term.toLowerCase();
+            if (seenTerms.has(normalizedKey)) {
+                continue;
+            }
+            seenTerms.add(normalizedKey);
+            group.push(term);
+            if (group.length >= MAX_TERMS_PER_GROUP) {
+                break;
+            }
+        }
+        if (group.length === 0) {
+            continue;
+        }
+        const groupAnchors = group.filter(looksLikeSearchAnchor);
+        const hasNewAnchor = groupAnchors.some((term) => !seenAnchors.has(term.toLowerCase()));
+        const hasPathLikeTerm = group.some(looksLikeCommandPathTerm);
+        const filteredGroup = group.filter((term) => {
+            const normalizedKey = term.toLowerCase();
+            if (looksLikeSearchAnchor(term)) {
+                return true;
+            }
+            if (!isGenericSearchTerm(term)) {
+                return true;
+            }
+            return hasNewAnchor || !seenGenericTerms.has(normalizedKey);
+        });
+        if (filteredGroup.length === 0) {
+            continue;
+        }
+        if (kind === "repo-anchor" && !filteredGroup.some(looksLikeSearchAnchor)) {
+            continue;
+        }
+        if (kind === "command-path" && !hasPathLikeTerm) {
+            continue;
+        }
+        if (kind === "generic" && !filteredGroup.some(looksLikeSearchAnchor) && filteredGroup.every(isGenericSearchTerm)) {
+            continue;
+        }
+        const hasNewNonGenericTerm = filteredGroup.some((term) => {
+            const normalizedKey = term.toLowerCase();
+            return !isGenericSearchTerm(term) && !looksLikeSearchAnchor(term) && !seenNonGenericTerms.has(normalizedKey);
+        });
+        if (kind === "generic" && !hasNewAnchor && !hasNewNonGenericTerm) {
+            continue;
+        }
+        for (const term of filteredGroup) {
+            const normalizedKey = term.toLowerCase();
+            if (looksLikeSearchAnchor(term)) {
+                seenAnchors.add(normalizedKey);
+            }
+            if (isGenericSearchTerm(term)) {
+                seenGenericTerms.add(normalizedKey);
+            }
+            else {
+                seenNonGenericTerms.add(normalizedKey);
+            }
+        }
+        const groupKey = `${kind}:${filteredGroup.map((term) => term.toLowerCase()).sort().join("|")}`;
+        if (seenGroupKeys.has(groupKey)) {
+            continue;
+        }
+        seenGroupKeys.add(groupKey);
+        normalizedGroups.push({ kind, terms: filteredGroup });
+        if (normalizedGroups.length >= MAX_SEARCH_TERM_GROUPS) {
+            break;
+        }
+    }
+    if (repoAnchorRequired && !normalizedGroups.some((group) => group.kind === "repo-anchor")) {
+        return [];
+    }
+    return normalizedGroups;
+}
+export function normalizeUnderstandResult(query, parsed) {
+    const explicitTargets = uniqueStrings([
+        ...(Array.isArray(parsed.explicitTargets) ? parsed.explicitTargets : []),
+        ...extractFileReferences(query),
+    ])
+        .map((target) => String(target ?? "").trim())
+        .filter(shouldKeepExplicitTarget)
+        .slice(0, 5);
+    const normalizedQuery = String(parsed.normalizedQuery ?? query).trim() || query;
+    const primaryIntent = String(parsed.primaryIntent ?? "Understand and answer the user's request.").trim();
+    return {
+        normalizedQuery,
+        queryScope: validateQueryScope(parsed.queryScope, explicitTargets, normalizedQuery, primaryIntent),
+        explicitTargets,
+        constraints: uniqueStrings(Array.isArray(parsed.constraints) ? parsed.constraints : []).slice(0, 5),
+        primaryIntent,
+        alternativeIntents: uniqueStrings(Array.isArray(parsed.alternativeIntents) ? parsed.alternativeIntents : []).slice(0, 3),
+        searchTermGroups: normalizeSearchTermGroups(parsed.searchTermGroups, normalizedQuery, primaryIntent),
+        ambiguityFlags: uniqueStrings(Array.isArray(parsed.ambiguityFlags) ? parsed.ambiguityFlags : []).slice(0, 3),
+    };
+}
+export async function runUnderstand(memory, ui) {
+    const resumedContext = renderResumeCheckpointForPrompt(memory.resumeCheckpoint);
+    const packet = {
+        query: memory.task.initialQuery,
+        repoRootPath: memory.session.repoRootPath,
+        resumedContext,
+    };
+    recordAgentEvent(memory, "understand-started", {
+        query: memory.task.initialQuery,
+    });
+    logAgentLlmInput(memory, "agent.understand", packet, undefined, nowLocalIso());
+    try {
+        const response = await generate({ query: memory.task.initialQuery, content: renderUnderstandPrompt(memory.task.initialQuery, resumedContext) }, {
+            caller: "agent.understand",
+            inputContext: packet,
+        });
+        const parsed = parseStructuredJson(String(response.data ?? ""), {
+            fallback: {
+                normalizedQuery: memory.task.initialQuery,
+                queryScope: "general",
+                explicitTargets: [],
+                constraints: [],
+                primaryIntent: "Understand and answer the user's request.",
+                alternativeIntents: [],
+                searchTermGroups: [],
+                ambiguityFlags: [],
+            },
+        });
+        const result = normalizeUnderstandResult(memory.task.initialQuery, parsed);
+        logAgentLlmOutput(memory, "agent.understand", {
+            parsed: result,
+        }, undefined, response.trace);
+        if (ui) {
+            emitAgentLlmTimingMessage(ui, "agent.understand", response.trace);
+        }
+        return result;
+    }
+    catch (error) {
+        const details = {
+            stage: "understand",
+            message: getErrorMessage(error),
+        };
+        logAgentLlmFailure(memory, "agent.understand", details, getErrorTrace(error));
+        throw new AgentRuntimeError(details, error);
+    }
+}
+//# sourceMappingURL=understand.js.map

package/dist/agent/runtime/understand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"understand.js","sourceRoot":"","sources":["../../../src/agent/runtime/understand.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runs the narrow understand phase for the new simple agent runtime.\n *\n * Why this file exists:\n * - understand should stay outside the main loop\n * - query normalization should stay small and factual\n * - alternative interpretations should stay bounded and explicit\n * - prompt and parsing ownership should stay outside this runtime wiring\n */\nimport { generate } from \"../../lib/generate.js\";\nimport { extractFileReferences } from \"../../utils/extractFileReferences.js\";\nimport { emitAgentLlmTimingMessage } from \"../../utils/consolePresentation.js\";\nimport {\n  getErrorMessage,\n  getErrorTrace,\n  logAgentLlmFailure,\n  logAgentLlmInput,\n  logAgentLlmOutput,\n  recordAgentEvent,\n} from \"../logging/index.js\";\nimport { renderUnderstandPrompt } from \"../prompting/index.js\";\nimport { renderResumeCheckpointForPrompt } from \"../resume/checkpoint.js\";\nimport { parseStructuredJson } from \"../structuredOutput/index.js\";\nimport { uniqueStrings } from \"../evidence/index.js\";\nimport {\n  AgentRuntimeError,\n  type AgentMemory,\n  type AgentQueryScope,\n  type AgentSearchTermGroup,\n  type AgentSearchTermGroupKind,\n  type UnderstandResult,\n} from \"../types.js\";\nimport { nowLocalIso } from \"../../utils/time.js\";\n\nconst VALID_QUERY_SCOPES = new Set<AgentQueryScope>([\n  \"targeted\",\n  \"multi-file\",\n  \"broad-repo\",\n  \"general\",\n]);\nconst NON_TARGET_EXPLICIT_TOKENS = new Set([\n  \"this\",\n  \"that\",\n  \"these\",\n  \"those\",\n  \"it\",\n  \"also\",\n  \"repo\",\n  \"repository\",\n  \"codebase\",\n  \"project\",\n]);\nconst MAX_SEARCH_TERM_GROUPS = 4;\nconst MAX_TERMS_PER_GROUP = 6;\nconst MAX_TERM_WORDS = 4;\nconst MAX_TERM_LENGTH = 40;\nconst GENERIC_SEARCH_TERMS = new Set([\n  \"agent\",\n  \"code\",\n  \"command\",\n  \"commands\",\n  \"config\",\n  \"configuration\",\n  \"entry\",\n  \"entrypoint\",\n  \"entrypoints\",\n  \"execute\",\n  \"file\",\n  \"files\",\n  \"path\",\n  \"paths\",\n  \"point\",\n  \"points\",\n  \"repo\",\n  \"repository\",\n  \"run\",\n  \"runner\",\n  \"script\",\n  \"scripts\",\n  \"source\",\n  \"sources\",\n  \"test\",\n  \"tests\",\n]);\n\n/**\n * Detects broad tool or concept questions that do not point at this repo.\n * Example: \"how do I use git bash to save a diff?\" should stay general.\n * Example: \"what is recursion?\" should stay general.\n */\nfunction looksLikeGeneralKnowledgeQuestion(query: string, primaryIntent: string): boolean {\n  const text = `${String(query ?? \"\")} ${String(primaryIntent ?? \"\")}`;\n  const lowered = text.toLowerCase();\n  if (/\\b(this repo|the repo|repo|repository|codebase|project)\\b/.test(lowered)) {\n    return false;\n  }\n  if (/[a-z][A-Z]/.test(text) || /[A-Z]{2,}[a-z]/.test(text) || text.includes(\"_\")) {\n    return false;\n  }\n  if (\n    /(?:^|[\\s\"'`])(?:\\.{0,2}\\/)?[A-Za-z0-9_.-]+\\/[A-Za-z0-9_./-]+(?:$|[\\s\"'`])/m.test(text) ||\n    /(?:^|[\\s\"'`])[A-Za-z0-9_.-]+\\.[A-Za-z0-9]{1,10}(?:$|[\\s\"'`!?.,:;])/m.test(text) ||\n    /[\"'`][^\"'`\\n]{4,}[\"'`]/.test(text)\n  ) {\n    return false;\n  }\n  if (\n    /\\b(where|which|find|locate|identify)\\b/.test(lowered) &&\n    /\\b(set|configured|configuration|entry|entrypoint|owner|limit|count|max)\\b/.test(lowered)\n  ) {\n    return false;\n  }\n  return /\\b(what is|what does|how do i|how can i|how to|how should i|why does|when should i)\\b/.test(lowered);\n}\n\nfunction shouldKeepExplicitTarget(target: string): boolean {\n  const trimmed = String(target ?? \"\").trim();\n  if (!trimmed) {\n    return false;\n  }\n  const lowered = trimmed.toLowerCase();\n  if (NON_TARGET_EXPLICIT_TOKENS.has(lowered)) {\n    return false;\n  }\n  if (/^(this|the)\\s+(repo|repository|codebase|project)$/i.test(trimmed)) {\n    return false;\n  }\n  return true;\n}\n\nfunction validateQueryScope(\n  rawScope: unknown,\n  explicitTargets: string[],\n  query: string,\n  primaryIntent: string\n): AgentQueryScope {\n  const meaningfulExplicitTargets = explicitTargets\n    .map((target) => String(target ?? \"\").trim())\n    .filter(Boolean);\n  const normalizedScope = VALID_QUERY_SCOPES.has(rawScope as AgentQueryScope)\n    ? rawScope as AgentQueryScope\n    : \"general\";\n\n  if (meaningfulExplicitTargets.length > 1) {\n    return \"multi-file\";\n  }\n\n  if (meaningfulExplicitTargets.length === 1 && normalizedScope === \"general\") {\n    return \"targeted\";\n  }\n\n  if (\n    meaningfulExplicitTargets.length === 0 &&\n    normalizedScope === \"targeted\" &&\n    looksLikeGeneralKnowledgeQuestion(query, primaryIntent)\n  ) {\n    return \"general\";\n  }\n\n  return normalizedScope;\n}\n\nfunction looksLikeSearchAnchor(term: string): boolean {\n  const value = String(term ?? \"\").trim();\n  if (!value) {\n    return false;\n  }\n  if (value.startsWith(\"/\")) {\n    return true;\n  }\n  if (/[A-Z]/.test(value) && /[a-z]/.test(value)) {\n    return true;\n  }\n  if (/[._/-]/.test(value)) {\n    return true;\n  }\n  if (/[0-9]/.test(value)) {\n    return true;\n  }\n  return false;\n}\n\nfunction isGenericSearchTerm(term: string): boolean {\n  return GENERIC_SEARCH_TERMS.has(String(term ?? \"\").trim().toLowerCase());\n}\n\nfunction looksLikeCommandPathTerm(term: string): boolean {\n  const value = String(term ?? \"\").trim();\n  if (!value) {\n    return false;\n  }\n  return value.startsWith(\"/\") || /[./-]/.test(value);\n}\n\nfunction requiresRepoAnchorGroup(query: string, primaryIntent: string): boolean {\n  const lowered = `${String(query ?? \"\")} ${String(primaryIntent ?? \"\")}`.toLowerCase();\n  return /\\b(where|which|what|find|locate|identify)\\b/.test(lowered)\n    && /\\b(set|setting|configured|configuration|register|registered|entry|entrypoint|command|commands|limit|count|max|owner)\\b/.test(lowered);\n}\n\nfunction isValidSearchTermGroupKind(value: unknown): value is AgentSearchTermGroupKind {\n  return value === \"repo-anchor\" || value === \"command-path\" || value === \"generic\";\n}\n\nfunction normalizeSearchTermGroups(\n  rawGroups: unknown,\n  query: string,\n  primaryIntent: string\n): AgentSearchTermGroup[] {\n  if (!Array.isArray(rawGroups)) {\n    return [];\n  }\n\n  const seenGroupKeys = new Set<string>();\n  const seenGenericTerms = new Set<string>();\n  const seenAnchors = new Set<string>();\n  const seenNonGenericTerms = new Set<string>();\n  const normalizedGroups: AgentSearchTermGroup[] = [];\n  const repoAnchorRequired = requiresRepoAnchorGroup(query, primaryIntent);\n  for (const rawGroup of rawGroups) {\n    if (!rawGroup || typeof rawGroup !== \"object\" || Array.isArray(rawGroup)) {\n      continue;\n    }\n    const kind = isValidSearchTermGroupKind((rawGroup as { kind?: unknown }).kind)\n      ? (rawGroup as { kind: AgentSearchTermGroupKind }).kind\n      : null;\n    const rawTerms = (rawGroup as { terms?: unknown }).terms;\n    if (!kind || !Array.isArray(rawTerms)) {\n      continue;\n    }\n\n    const seenTerms = new Set<string>();\n    const group: string[] = [];\n    for (const rawTerm of rawTerms) {\n      const term = String(rawTerm ?? \"\").trim();\n      if (!term || term.length > MAX_TERM_LENGTH) {\n        continue;\n      }\n      if ((term.match(/\\s+/g)?.length ?? 0) + 1 > MAX_TERM_WORDS) {\n        continue;\n      }\n      const normalizedKey = term.toLowerCase();\n      if (seenTerms.has(normalizedKey)) {\n        continue;\n      }\n      seenTerms.add(normalizedKey);\n      group.push(term);\n      if (group.length >= MAX_TERMS_PER_GROUP) {\n        break;\n      }\n    }\n\n    if (group.length === 0) {\n      continue;\n    }\n\n    const groupAnchors = group.filter(looksLikeSearchAnchor);\n    const hasNewAnchor = groupAnchors.some((term) => !seenAnchors.has(term.toLowerCase()));\n    const hasPathLikeTerm = group.some(looksLikeCommandPathTerm);\n    const filteredGroup = group.filter((term) => {\n      const normalizedKey = term.toLowerCase();\n      if (looksLikeSearchAnchor(term)) {\n        return true;\n      }\n      if (!isGenericSearchTerm(term)) {\n        return true;\n      }\n      return hasNewAnchor || !seenGenericTerms.has(normalizedKey);\n    });\n\n    if (filteredGroup.length === 0) {\n      continue;\n    }\n    if (kind === \"repo-anchor\" && !filteredGroup.some(looksLikeSearchAnchor)) {\n      continue;\n    }\n    if (kind === \"command-path\" && !hasPathLikeTerm) {\n      continue;\n    }\n    if (kind === \"generic\" && !filteredGroup.some(looksLikeSearchAnchor) && filteredGroup.every(isGenericSearchTerm)) {\n      continue;\n    }\n    const hasNewNonGenericTerm = filteredGroup.some((term) => {\n      const normalizedKey = term.toLowerCase();\n      return !isGenericSearchTerm(term) && !looksLikeSearchAnchor(term) && !seenNonGenericTerms.has(normalizedKey);\n    });\n    if (kind === \"generic\" && !hasNewAnchor && !hasNewNonGenericTerm) {\n      continue;\n    }\n\n    for (const term of filteredGroup) {\n      const normalizedKey = term.toLowerCase();\n      if (looksLikeSearchAnchor(term)) {\n        seenAnchors.add(normalizedKey);\n      }\n      if (isGenericSearchTerm(term)) {\n        seenGenericTerms.add(normalizedKey);\n      } else {\n        seenNonGenericTerms.add(normalizedKey);\n      }\n    }\n\n    const groupKey = `${kind}:${filteredGroup.map((term) => term.toLowerCase()).sort().join(\"|\")}`;\n    if (seenGroupKeys.has(groupKey)) {\n      continue;\n    }\n    seenGroupKeys.add(groupKey);\n    normalizedGroups.push({ kind, terms: filteredGroup });\n    if (normalizedGroups.length >= MAX_SEARCH_TERM_GROUPS) {\n      break;\n    }\n  }\n\n  if (repoAnchorRequired && !normalizedGroups.some((group) => group.kind === \"repo-anchor\")) {\n    return [];\n  }\n\n  return normalizedGroups;\n}\n\nexport function normalizeUnderstandResult(query: string, parsed: Partial<UnderstandResult>): UnderstandResult {\n  const explicitTargets = uniqueStrings([\n    ...(Array.isArray(parsed.explicitTargets) ? parsed.explicitTargets : []),\n    ...extractFileReferences(query),\n  ])\n    .map((target) => String(target ?? \"\").trim())\n    .filter(shouldKeepExplicitTarget)\n    .slice(0, 5);\n  const normalizedQuery = String(parsed.normalizedQuery ?? query).trim() || query;\n  const primaryIntent = String(parsed.primaryIntent ?? \"Understand and answer the user's request.\").trim();\n\n  return {\n    normalizedQuery,\n    queryScope: validateQueryScope(parsed.queryScope, explicitTargets, normalizedQuery, primaryIntent),\n    explicitTargets,\n    constraints: uniqueStrings(Array.isArray(parsed.constraints) ? parsed.constraints : []).slice(0, 5),\n    primaryIntent,\n    alternativeIntents: uniqueStrings(Array.isArray(parsed.alternativeIntents) ? parsed.alternativeIntents : []).slice(0, 3),\n    searchTermGroups: normalizeSearchTermGroups(\n      parsed.searchTermGroups,\n      normalizedQuery,\n      primaryIntent\n    ),\n    ambiguityFlags: uniqueStrings(Array.isArray(parsed.ambiguityFlags) ? parsed.ambiguityFlags : []).slice(0, 3),\n  };\n}\n\nexport async function runUnderstand(memory: AgentMemory, ui?: { message(text: string): void }): Promise<UnderstandResult> {\n  const resumedContext = renderResumeCheckpointForPrompt(memory.resumeCheckpoint);\n  const packet = {\n    query: memory.task.initialQuery,\n    repoRootPath: memory.session.repoRootPath,\n    resumedContext,\n  };\n  recordAgentEvent(memory, \"understand-started\", {\n    query: memory.task.initialQuery,\n  });\n  logAgentLlmInput(memory, \"agent.understand\", packet, undefined, nowLocalIso());\n  try {\n    const response = await generate({ query: memory.task.initialQuery, content: renderUnderstandPrompt(memory.task.initialQuery, resumedContext) }, {\n      caller: \"agent.understand\",\n      inputContext: packet,\n    });\n    const parsed = parseStructuredJson<Partial<UnderstandResult>>(String(response.data ?? \"\"), {\n      fallback: {\n        normalizedQuery: memory.task.initialQuery,\n        queryScope: \"general\",\n        explicitTargets: [],\n        constraints: [],\n        primaryIntent: \"Understand and answer the user's request.\",\n        alternativeIntents: [],\n        searchTermGroups: [],\n        ambiguityFlags: [],\n      },\n    });\n    const result = normalizeUnderstandResult(memory.task.initialQuery, parsed);\n    logAgentLlmOutput(memory, \"agent.understand\", {\n      parsed: result,\n    }, undefined, response.trace);\n    if (ui) {\n      emitAgentLlmTimingMessage(ui, \"agent.understand\", response.trace);\n    }\n    return result;\n  } catch (error) {\n    const details = {\n      stage: \"understand\",\n      message: getErrorMessage(error),\n    };\n    logAgentLlmFailure(memory, \"agent.understand\", details, getErrorTrace(error));\n    throw new AgentRuntimeError(details, error);\n  }\n}\n"]}