scai 0.1.178 → 1.0.0

package/dist/agent/policy/index.js

@@ -0,0 +1,344 @@
+import { resolveReadCoverageState } from "./coveragePolicy.js";
+import { resolveEndDecision } from "./endDecisionPolicy.js";
+import { extractQuotedFragments } from "../search/searchContext.js";
+import { buildLoopReviewPacket } from "./loopReview.js";
+import { hasPendingStep, isDirectGeneralAnswerRoute, isTransformIntent, isSuccessfulDirectoryListing, looksLikeRegexQuery, resolveAllowedActions, resolveNextFolderListingTarget, } from "./readinessPolicy.js";
+const GENERAL_ROUTE_REASON = "The query is general and does not need grounded repo evidence before answering.";
+function hasConcreteQueryAnchor(query) {
+    return /[\/_.-]/.test(query) || /[a-z][A-Z]/.test(query);
+}
+function hasQuotedFragmentSearchGuidance(memory) {
+    return extractQuotedFragments(memory.task.initialQuery).length > 0;
+}
+function hasActionableSearchMatches(memory) {
+    return memory.evidence.searches.some((search) => (search.matches?.length ?? 0) > 0);
+}
+function looksLikeBroadRepoReadOnlyAsk(memory) {
+    if (isTransformIntent(memory)) {
+        return false;
+    }
+    if (memory.task.explicitTargets.length > 0 || memory.task.hardFileTargets.length > 0) {
+        return false;
+    }
+    const query = `${memory.task.normalizedQuery} ${memory.task.primaryIntent}`.toLowerCase();
+    const hasRepoScope = /\b(this repo|the repo|repo|repository|codebase|project)\b/.test(query);
+    const hasBroadCodeQuestion = /\b(how|where|which|entrypoints?|tests?|test runner|architecture|flow|configured|configuration)\b/.test(query);
+    return hasRepoScope && hasBroadCodeQuestion;
+}
+/**
+ * Allows one discovery search before we ask the user for a narrower hint.
+ *
+ * Why this helper exists:
+ * - weak-signal questions should get one small search chance before we stop
+ * - the bootstrap rule should stay owned by policy instead of leaking into search
+ * - this must stay one-shot so repeated weak searches still fall back to clarification
+ */
+function shouldBootstrapDiscoverySearch(memory, coverage, args) {
+    if (memory.task.mode !== "ask" || isTransformIntent(memory)) {
+        return false;
+    }
+    if (memory.evidence.searches.length > 0 || args.hasGroundedEvidence || args.hasUsefulEvidence) {
+        return false;
+    }
+    if (coverage.ambiguousTargets.length > 0 || coverage.unreadHardFileTargets.length > 0) {
+        return false;
+    }
+    if (memory.task.explicitTargets.length > 0 || coverage.hardFileTargets.length > 0 || coverage.folderTargets.length > 0) {
+        return false;
+    }
+    if (hasQuotedFragmentSearchGuidance(memory) || looksLikeRegexQuery(memory.task.normalizedQuery)) {
+        return false;
+    }
+    if (resolveNextFolderListingTarget(memory, coverage)) {
+        return false;
+    }
+    return true;
+}
+function buildReadDecision(allowedActions, reason, target) {
+    return {
+        allowedActions,
+        nextAction: "read-file",
+        args: { target },
+        reason,
+    };
+}
+function describePolicyReason(memory, hasUsefulEvidence, shouldAskUser, shouldReplan, coverage) {
+    if (isDirectGeneralAnswerRoute(memory, coverage)) {
+        return GENERAL_ROUTE_REASON;
+    }
+    if (hasUsefulEvidence) {
+        return coverage.evidenceCoverage.reason;
+    }
+    if (isTransformIntent(memory) && coverage.unreadHardFileTargets.length === 0 && coverage.hardFileTargets.length > 0) {
+        return "The requested file has a grounded full read and is ready for transform.";
+    }
+    if (shouldAskUser) {
+        return "The request still needs one concrete user hint.";
+    }
+    if (shouldReplan) {
+        return "There is no pending work and evidence is still weak.";
+    }
+    if (coverage.ambiguousTargets.length > 0) {
+        const ambiguous = coverage.ambiguousTargets[0];
+        return `Need the user to choose the exact in-repo path for ${ambiguous.target}.`;
+    }
+    if (coverage.hasUnresolvedHardFileRequirement) {
+        return coverage.folderTargets.length > 0
+            ? "A required explicit file or folder target did not resolve inside the repo."
+            : "A required hard file target did not resolve inside the repo.";
+    }
+    if (coverage.unreadHardFileTargets.length > 0) {
+        return coverage.folderTargets.length > 0
+            ? "Need grounded reads for the remaining explicit file or folder targets."
+            : "Need grounded reads for the remaining hard file targets.";
+    }
+    if (coverage.unreadTriageTargets.length > 0 || coverage.unreadFullReadTargets.length > 0) {
+        return coverage.needsBroadTriage
+            ? "Need another triage or full read from the ranked candidate set before answering."
+            : "Need another ranked candidate read before answering.";
+    }
+    return "Need another small evidence-gathering action.";
+}
+export function resolveNextReadTarget(memory) {
+    const coverage = resolveReadCoverageState(memory);
+    const loopReview = buildLoopReviewPacket(memory, coverage);
+    return resolveNextStructuredStep(memory, coverage, loopReview).nextReadTarget;
+}
+export function resolveNextTriageTarget(memory) {
+    const coverage = resolveReadCoverageState(memory);
+    const loopReview = buildLoopReviewPacket(memory, coverage);
+    return resolveNextStructuredStep(memory, coverage, loopReview).nextTriageTarget;
+}
+export function resolvePreferredReadAction(memory) {
+    const coverage = resolveReadCoverageState(memory);
+    const loopReview = buildLoopReviewPacket(memory, coverage);
+    const reviewTarget = loopReview.expansionAssessment.bestCandidatePath;
+    if (loopReview.expansionAssessment.shouldExpand && reviewTarget) {
+        if (coverage.unreadTriageTargets.includes(reviewTarget) && !coverage.unreadFullReadTargets.includes(reviewTarget)) {
+            return "triage-file";
+        }
+        return "read-file";
+    }
+    if (coverage.unreadHardFileTargets.length > 0 || coverage.unreadFullReadTargets.length > 0) {
+        return "read-file";
+    }
+    if (coverage.unreadTriageTargets.length > 0) {
+        return "triage-file";
+    }
+    return undefined;
+}
+function resolvePreferredSearchQuery(memory) {
+    return hasQuotedFragmentSearchGuidance(memory)
+        ? memory.task.initialQuery
+        : memory.task.normalizedQuery;
+}
+function resolveNextStructuredStep(memory, coverage, loopReview) {
+    const reviewTarget = loopReview.expansionAssessment.bestCandidatePath;
+    const nextReadTarget = loopReview.expansionAssessment.shouldExpand && reviewTarget
+        ? reviewTarget
+        : coverage.unreadFullReadTargets[0];
+    const nextTriageTarget = loopReview.expansionAssessment.shouldExpand && reviewTarget && coverage.unreadTriageTargets.includes(reviewTarget)
+        ? reviewTarget
+        : coverage.unreadTriageTargets[0];
+    return {
+        nextFolderListingTarget: resolveNextFolderListingTarget(memory, coverage),
+        nextReadTarget,
+        nextTriageTarget,
+        nextTransformTarget: memory.task.hardFileTargets[0],
+        nextSearchQuery: resolvePreferredSearchQuery(memory),
+    };
+}
+function resolvePolicyActionArgs(memory, coverage, loopReview, action) {
+    const nextStep = resolveNextStructuredStep(memory, coverage, loopReview);
+    switch (action) {
+        case "search-list-directory":
+            return nextStep.nextFolderListingTarget
+                ? { folderPath: nextStep.nextFolderListingTarget }
+                : undefined;
+        case "read-file":
+            return nextStep.nextReadTarget
+                ? { target: nextStep.nextReadTarget }
+                : undefined;
+        case "triage-file":
+            return nextStep.nextTriageTarget
+                ? { target: nextStep.nextTriageTarget }
+                : undefined;
+        case "codeTransform":
+            return nextStep.nextTransformTarget
+                ? { target: nextStep.nextTransformTarget }
+                : undefined;
+        case "search-db":
+            return { query: nextStep.nextSearchQuery };
+        default:
+            return undefined;
+    }
+}
+function resolvePolicyDecision(memory, coverage, loopReview, allowedActions, shouldAskUser, forcedEnd) {
+    const nextStep = resolveNextStructuredStep(memory, coverage, loopReview);
+    if (isDirectGeneralAnswerRoute(memory, coverage) && allowedActions.includes("final-answer")) {
+        return {
+            allowedActions,
+            stop: "final-answer",
+            reason: GENERAL_ROUTE_REASON,
+        };
+    }
+    if (loopReview.stopAssessment.canStop && allowedActions.includes("final-answer")) {
+        return {
+            allowedActions,
+            stop: "final-answer",
+            reason: loopReview.stopAssessment.reason,
+        };
+    }
+    if (shouldAskUser && allowedActions.includes("request-user-input")) {
+        return {
+            allowedActions,
+            stop: "request-user-input",
+            reason: coverage.ambiguousTargets[0]
+                ? `Need the user to choose the exact in-repo path for ${coverage.ambiguousTargets[0].target}.`
+                : "The request still needs one concrete user hint.",
+        };
+    }
+    if (allowedActions.includes("codeTransform") && memory.task.hardFileTargets[0]) {
+        return {
+            allowedActions,
+            nextAction: "codeTransform",
+            args: resolvePolicyActionArgs(memory, coverage, loopReview, "codeTransform"),
+            reason: "The grounded target file is ready for transform.",
+        };
+    }
+    if (nextStep.nextFolderListingTarget && allowedActions.includes("search-list-directory")) {
+        return {
+            allowedActions,
+            nextAction: "search-list-directory",
+            args: resolvePolicyActionArgs(memory, coverage, loopReview, "search-list-directory"),
+            reason: "List the resolved folder target before reading files inside it.",
+        };
+    }
+    if (coverage.unreadHardFileTargets.length > 0 && nextStep.nextReadTarget && allowedActions.includes("read-file")) {
+        return buildReadDecision(allowedActions, coverage.evidenceCoverage.kind === "needs-read"
+            ? coverage.evidenceCoverage.reason
+            : "Read the next grounded target before answering.", nextStep.nextReadTarget);
+    }
+    if (loopReview.referenceFollowupNeeded && nextStep.nextReadTarget && allowedActions.includes("read-file")) {
+        return buildReadDecision(allowedActions, loopReview.expansionAssessment.reason, nextStep.nextReadTarget);
+    }
+    if (coverage.unreadTriageTargets.length > 0 && nextStep.nextTriageTarget && allowedActions.includes("triage-file")) {
+        return {
+            allowedActions,
+            nextAction: "triage-file",
+            args: resolvePolicyActionArgs(memory, coverage, loopReview, "triage-file"),
+            reason: loopReview.referenceFollowupNeeded
+                ? loopReview.expansionAssessment.reason
+                : "Triage the next ranked candidate before a full read.",
+        };
+    }
+    if (loopReview.driftAssessment.blocksExpansion &&
+        !loopReview.stopAssessment.canStop &&
+        allowedActions.includes("plan")) {
+        return {
+            allowedActions,
+            nextAction: "plan",
+            args: resolvePolicyActionArgs(memory, coverage, loopReview, "plan"),
+            reason: loopReview.driftAssessment.reason,
+        };
+    }
+    if (coverage.unreadFullReadTargets.length > 0 && nextStep.nextReadTarget && allowedActions.includes("read-file")) {
+        return buildReadDecision(allowedActions, coverage.evidenceCoverage.kind === "needs-read"
+            ? coverage.evidenceCoverage.reason
+            : "Read the next ranked candidate before answering.", nextStep.nextReadTarget);
+    }
+    if (coverage.evidenceCoverage.kind === "needs-search" && allowedActions.includes("search-db")) {
+        const nextAction = looksLikeRegexQuery(memory.task.normalizedQuery) && allowedActions.includes("search-regex")
+            ? "search-regex"
+            : "search-db";
+        return {
+            allowedActions,
+            nextAction,
+            args: resolvePolicyActionArgs(memory, coverage, loopReview, nextAction),
+            reason: coverage.evidenceCoverage.reason,
+        };
+    }
+    if (forcedEnd) {
+        return {
+            allowedActions,
+            stop: "cannot-answer",
+            reason: "The gathered evidence is still too weak to answer reliably.",
+        };
+    }
+    return {
+        allowedActions,
+        nextAction: allowedActions[0],
+        args: resolvePolicyActionArgs(memory, coverage, loopReview, allowedActions[0]),
+        reason: "Take the next legal action.",
+    };
+}
+export function resolvePolicyState(memory, options = {}) {
+    const fileReads = Object.values(memory.evidence.fileReads);
+    const hasReadEvidence = fileReads.length > 0;
+    const hasDirectoryListing = memory.evidence.searches.some(isSuccessfulDirectoryListing);
+    const hasGroundedEvidence = hasReadEvidence || hasDirectoryListing;
+    const coverage = resolveReadCoverageState(memory);
+    const loopReview = buildLoopReviewPacket(memory, coverage);
+    const hasSearchGuidance = coverage.softHints.length > 0 ||
+        looksLikeRegexQuery(memory.task.normalizedQuery) ||
+        hasConcreteQueryAnchor(memory.task.normalizedQuery) ||
+        hasQuotedFragmentSearchGuidance(memory);
+    const broadRepoReadOnlyAsk = looksLikeBroadRepoReadOnlyAsk(memory);
+    const hasReviewReadTarget = loopReview.expansionAssessment.shouldExpand && typeof loopReview.expansionAssessment.bestCandidatePath === "string";
+    const directGeneralAnswer = isDirectGeneralAnswerRoute(memory, coverage);
+    const primaryAmbiguousTarget = coverage.ambiguousTargets[0]
+        ? {
+            target: coverage.ambiguousTargets[0].target,
+            candidates: coverage.ambiguousTargets[0].candidates,
+            reason: coverage.ambiguousTargets[0].reason,
+        }
+        : undefined;
+    const hasUsefulEvidence = directGeneralAnswer ||
+        hasDirectoryListing ||
+        coverage.evidenceCoverage.kind === "enough" ||
+        hasActionableSearchMatches(memory) ||
+        (loopReview.stopAssessment.canStop &&
+            !coverage.hasStructuredTargetRequirement &&
+            !coverage.hasUnresolvedHardFileRequirement &&
+            coverage.unreadHardFileTargets.length === 0);
+    const shouldBootstrapSearch = shouldBootstrapDiscoverySearch(memory, coverage, {
+        hasGroundedEvidence,
+        hasUsefulEvidence,
+    });
+    const shouldAskUser = coverage.ambiguousTargets.length > 0 ||
+        (!hasUsefulEvidence &&
+            !hasReadEvidence &&
+            !shouldBootstrapSearch &&
+            !coverage.hasStructuredTargetRequirement &&
+            !hasSearchGuidance &&
+            !broadRepoReadOnlyAsk);
+    const shouldReplan = !hasPendingStep(memory) &&
+        !directGeneralAnswer &&
+        !hasUsefulEvidence &&
+        memory.evidence.candidateFiles.length === 0 &&
+        !coverage.hasStructuredTargetRequirement &&
+        coverage.ambiguousTargets.length === 0 &&
+        coverage.softHints.length === 0;
+    const allowFinalAnswer = directGeneralAnswer || (hasUsefulEvidence &&
+        loopReview.stopAssessment.canStop &&
+        !coverage.hasUnresolvedHardFileRequirement &&
+        coverage.unreadHardFileTargets.length === 0);
+    const allowedActions = resolveAllowedActions(memory, allowFinalAnswer, coverage, { forceReadFile: hasReviewReadTarget });
+    if (shouldAskUser && !allowedActions.includes("request-user-input")) {
+        allowedActions.unshift("request-user-input");
+    }
+    const decision = resolvePolicyDecision(memory, coverage, loopReview, allowedActions, shouldAskUser, options.forcedEnd ?? false);
+    return {
+        allowedActions,
+        decision,
+        hasGroundedEvidence,
+        hasUsefulEvidence,
+        loopReview,
+        shouldReplan,
+        shouldAskUser,
+        primaryAmbiguousTarget,
+        endDecision: options.forcedEnd ? resolveEndDecision(decision) : null,
+        reason: describePolicyReason(memory, hasUsefulEvidence, shouldAskUser, shouldReplan, coverage),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/agent/policy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/policy/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,iBAAiB,EACjB,4BAA4B,EAC5B,mBAAmB,EACnB,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AA+B9B,MAAM,oBAAoB,GAAG,iFAAiF,CAAC;AAE/G,SAAS,sBAAsB,CAAC,KAAa;IAC3C,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,+BAA+B,CAAC,MAAmB;IAC1D,OAAO,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,0BAA0B,CAAC,MAAmB;IACrD,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,6BAA6B,CAAC,MAAmB;IACxD,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1F,MAAM,YAAY,GAAG,2DAA2D,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7F,MAAM,oBAAoB,GAAG,kGAAkG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5I,OAAO,YAAY,IAAI,oBAAoB,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,8BAA8B,CACrC,MAAmB,EACnB,QAAqD,EACrD,IAGC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC9F,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,QAAQ,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,+BAA+B,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;QAChG,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,8BAA8B,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,iBAAiB,CACxB,cAAiC,EACjC,MAAc,EACd,MAAc;IAEd,OAAO;QACL,cAAc;QACd,UAAU,EAAE,WAAW;QACvB,IAAI,EAAE,EAAE,MAAM,EAAE;QAChB,MAAM;KACP,CAAC;AACJ,CAAC;AAUD,SAAS,oBAAoB,CAC3B,MAAmB,EACnB,iBAA0B,EAC1B,aAAsB,EACtB,YAAqB,EACrB,QAAqD;IAErD,IAAI,0BAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QACjD,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC,gBAAgB,CAAC,MAAM,CAAC;IAC1C,CAAC;IACD,IAAI,iBAAiB,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpH,OAAO,yEAAyE,CAAC;IACnF,CAAC;IACD,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,iDAAiD,CAAC;IAC3D,CAAC;IACD,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,sDAAsD,CAAC;IAChE,CAAC;IACD,IAAI,QAAQ,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,sDAAsD,SAAS,CAAC,MAAM,GAAG,CAAC;IACnF,CAAC;IACD,IAAI,QAAQ,CAAC,gCAAgC,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;YACtC,CAAC,CAAC,4EAA4E;YAC9E,CAAC,CAAC,8DAA8D,CAAC;IACrE,CAAC;IACD,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;YACtC,CAAC,CAAC,wEAAwE;YAC1E,CAAC,CAAC,0DAA0D,CAAC;IACjE,CAAC;IACD,IAAI,QAAQ,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzF,OAAO,QAAQ,CAAC,gBAAgB;YAC9B,CAAC,CAAC,kFAAkF;YACpF,CAAC,CAAC,sDAAsD,CAAC;IAC7D,CAAC;IACD,OAAO,+CAA+C,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACvD,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,OAAO,yBAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,cAAc,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAmB;IACzD,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,OAAO,yBAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,gBAAgB,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAmB;IAC5D,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,UAAU,CAAC,mBAAmB,CAAC,iBAAiB,CAAC;IACtE,IAAI,UAAU,CAAC,mBAAmB,CAAC,YAAY,IAAI,YAAY,EAAE,CAAC;QAChE,IAAI,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAClH,OAAO,aAAa,CAAC;QACvB,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3F,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,QAAQ,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,2BAA2B,CAAC,MAAmB;IACtD,OAAO,+BAA+B,CAAC,MAAM,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY;QAC1B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;AAClC,CAAC;AAED,SAAS,yBAAyB,CAChC,MAAmB,EACnB,QAAqD,EACrD,UAAiC;IAEjC,MAAM,YAAY,GAAG,UAAU,CAAC,mBAAmB,CAAC,iBAAiB,CAAC;IACtE,MAAM,cAAc,GAAG,UAAU,CAAC,mBAAmB,CAAC,YAAY,IAAI,YAAY;QAChF,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,gBAAgB,GAAG,UAAU,CAAC,mBAAmB,CAAC,YAAY,IAAI,YAAY,IAAI,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,YAAY,CAAC;QACzI,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACpC,OAAO;QACL,uBAAuB,EAAE,8BAA8B,CAAC,MAAM,EAAE,QAAQ,CAAC;QACzE,cAAc;QACd,gBAAgB;QAChB,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;QACnD,eAAe,EAAE,2BAA2B,CAAC,MAAM,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAS,uBAAuB,CAC9B,MAAmB,EACnB,QAAqD,EACrD,UAAiC,EACjC,MAAuB;IAEvB,MAAM,QAAQ,GAAG,yBAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACzE,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,uBAAuB;YAC1B,OAAO,QAAQ,CAAC,uBAAuB;gBACrC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,uBAAuB,EAAE;gBAClD,CAAC,CAAC,SAAS,CAAC;QAChB,KAAK,WAAW;YACd,OAAO,QAAQ,CAAC,cAAc;gBAC5B,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,cAAc,EAAE;gBACrC,CAAC,CAAC,SAAS,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,QAAQ,CAAC,gBAAgB;gBAC9B,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,gBAAgB,EAAE;gBACvC,CAAC,CAAC,SAAS,CAAC;QAChB,KAAK,eAAe;YAClB,OAAO,QAAQ,CAAC,mBAAmB;gBACjC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,mBAAmB,EAAE;gBAC1C,CAAC,CAAC,SAAS,CAAC;QAChB,KAAK,WAAW;YACd,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC7C;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAC5B,MAAmB,EACnB,QAAqD,EACrD,UAAiC,EACjC,cAAiC,EACjC,aAAsB,EACtB,SAAkB;IAElB,MAAM,QAAQ,GAAG,yBAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAEzE,IAAI,0BAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC5F,OAAO;YACL,cAAc;YACd,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,oBAAoB;SAC7B,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,cAAc,CAAC,OAAO,IAAI,cAAc,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACjF,OAAO;YACL,cAAc;YACd,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,MAAM;SACzC,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,IAAI,cAAc,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACnE,OAAO;YACL,cAAc;YACd,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;gBAClC,CAAC,CAAC,sDAAsD,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG;gBAC9F,CAAC,CAAC,iDAAiD;SACtD,CAAC;IACJ,CAAC;IAED,IAAI,cAAc,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,OAAO;YACL,cAAc;YACd,UAAU,EAAE,eAAe;YAC3B,IAAI,EAAE,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,CAAC;YAC5E,MAAM,EAAE,kDAAkD;SAC3D,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,uBAAuB,IAAI,cAAc,CAAC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC;QACzF,OAAO;YACL,cAAc;YACd,UAAU,EAAE,uBAAuB;YACnC,IAAI,EAAE,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,uBAAuB,CAAC;YACpF,MAAM,EAAE,iEAAiE;SAC1E,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,cAAc,IAAI,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACjH,OAAO,iBAAiB,CACtB,cAAc,EACd,QAAQ,CAAC,gBAAgB,CAAC,IAAI,KAAK,YAAY;YAC7C,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,MAAM;YAClC,CAAC,CAAC,iDAAiD,EACrD,QAAQ,CAAC,cAAc,CACxB,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,uBAAuB,IAAI,QAAQ,CAAC,cAAc,IAAI,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC1G,OAAO,iBAAiB,CACtB,cAAc,EACd,UAAU,CAAC,mBAAmB,CAAC,MAAM,EACrC,QAAQ,CAAC,cAAc,CACxB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,gBAAgB,IAAI,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACnH,OAAO;YACL,cAAc;YACd,UAAU,EAAE,aAAa;YACzB,IAAI,EAAE,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,CAAC;YAC1E,MAAM,EAAE,UAAU,CAAC,uBAAuB;gBACxC,CAAC,CAAC,UAAU,CAAC,mBAAmB,CAAC,MAAM;gBACvC,CAAC,CAAC,sDAAsD;SAC3D,CAAC;IACJ,CAAC;IAED,IACE,UAAU,CAAC,eAAe,CAAC,eAAe;QAC1C,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO;QAClC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,EAC/B,CAAC;QACD,OAAO;YACL,cAAc;YACd,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC;YACnE,MAAM,EAAE,UAAU,CAAC,eAAe,CAAC,MAAM;SAC1C,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,cAAc,IAAI,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACjH,OAAO,iBAAiB,CACtB,cAAc,EACd,QAAQ,CAAC,gBAAgB,CAAC,IAAI,KAAK,YAAY;YAC7C,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,MAAM;YAClC,CAAC,CAAC,kDAAkD,EACtD,QAAQ,CAAC,cAAc,CACxB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,gBAAgB,CAAC,IAAI,KAAK,cAAc,IAAI,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9F,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,cAAc,CAAC;YAC5G,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,WAAW,CAAC;QAChB,OAAO;YACL,cAAc;YACd,UAAU;YACV,IAAI,EAAE,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,CAAC;YACvE,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,MAAM;SACzC,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,OAAO;YACL,cAAc;YACd,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,6DAA6D;SACtE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,cAAc;QACd,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;QAC7B,IAAI,EAAE,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,EAAE,6BAA6B;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,MAAmB,EACnB,UAAqC,EAAE;IAEvC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC3D,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAC7C,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACxF,MAAM,mBAAmB,GAAG,eAAe,IAAI,mBAAmB,CAAC;IACnE,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;QACrD,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;QAChD,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;QACnD,+BAA+B,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,oBAAoB,GAAG,6BAA6B,CAAC,MAAM,CAAC,CAAC;IACnE,MAAM,mBAAmB,GAAG,UAAU,CAAC,mBAAmB,CAAC,YAAY,IAAI,OAAO,UAAU,CAAC,mBAAmB,CAAC,iBAAiB,KAAK,QAAQ,CAAC;IAChJ,MAAM,mBAAmB,GAAG,0BAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzE,MAAM,sBAAsB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACzD,CAAC,CAAC;YACE,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM;YAC3C,UAAU,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,UAAU;YACnD,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM;SAC5C;QACH,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,iBAAiB,GAAG,mBAAmB;QAC3C,mBAAmB;QACnB,QAAQ,CAAC,gBAAgB,CAAC,IAAI,KAAK,QAAQ;QAC3C,0BAA0B,CAAC,MAAM,CAAC;QAClC,CACE,UAAU,CAAC,cAAc,CAAC,OAAO;YACjC,CAAC,QAAQ,CAAC,8BAA8B;YACxC,CAAC,QAAQ,CAAC,gCAAgC;YAC1C,QAAQ,CAAC,qBAAqB,CAAC,MAAM,KAAK,CAAC,CAC5C,CAAC;IACJ,MAAM,qBAAqB,GAAG,8BAA8B,CAAC,MAAM,EAAE,QAAQ,EAAE;QAC7E,mBAAmB;QACnB,iBAAiB;KAClB,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,QAAQ,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;QACxD,CAAC,CAAC,iBAAiB;YACjB,CAAC,eAAe;YAChB,CAAC,qBAAqB;YACtB,CAAC,QAAQ,CAAC,8BAA8B;YACxC,CAAC,iBAAiB;YAClB,CAAC,oBAAoB,CAAC,CAAC;IAC3B,MAAM,YAAY,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC;QAC1C,CAAC,mBAAmB;QACpB,CAAC,iBAAiB;QAClB,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC;QAC3C,CAAC,QAAQ,CAAC,8BAA8B;QACxC,QAAQ,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC;QACtC,QAAQ,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC;IAClC,MAAM,gBAAgB,GAAG,mBAAmB,IAAI,CAC9C,iBAAiB;QACjB,UAAU,CAAC,cAAc,CAAC,OAAO;QACjC,CAAC,QAAQ,CAAC,gCAAgC;QAC1C,QAAQ,CAAC,qBAAqB,CAAC,MAAM,KAAK,CAAC,CAC5C,CAAC;IACF,MAAM,cAAc,GAAG,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC,CAAC;IACzH,IAAI,aAAa,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACpE,cAAc,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC;IAEhI,OAAO;QACL,cAAc;QACd,QAAQ;QACR,mBAAmB;QACnB,iBAAiB;QACjB,UAAU;QACV,YAAY;QACZ,aAAa;QACb,sBAAsB;QACtB,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACpE,MAAM,EAAE,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,CAAC;KAC/F,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Resolves one read-only policy snapshot for the modular agent runtime.\n *\n * Why this file exists:\n * - runtime loop policy should stay in one small derivation-only area\n * - coverage, readiness, and forced-end logic should stay separate from loop execution\n * - policy should consume resolution and coverage facts, not re-infer them in the loop\n */\nimport type { AgentActionName, AgentLoopReviewPacket, AgentMemory } from \"../types.js\";\nimport type { PolicyActionArgs, PolicyDecision } from \"./contracts.js\";\nimport { resolveReadCoverageState } from \"./coveragePolicy.js\";\nimport { resolveEndDecision } from \"./endDecisionPolicy.js\";\nimport { extractQuotedFragments } from \"../search/searchContext.js\";\nimport { buildLoopReviewPacket } from \"./loopReview.js\";\nimport {\n  hasPendingStep,\n  isDirectGeneralAnswerRoute,\n  isTransformIntent,\n  isSuccessfulDirectoryListing,\n  looksLikeRegexQuery,\n  resolveAllowedActions,\n  resolveNextFolderListingTarget,\n} from \"./readinessPolicy.js\";\n\nexport interface AgentPolicyEndDecision {\n  action: \"final-answer\" | \"cannot-answer\" | \"request-user-input\";\n  taskStatus: \"done\" | \"blocked\" | \"waiting\";\n  stopReason: string;\n  purpose: string;\n  expectedEvidence: string[];\n}\n\nexport interface AgentPolicyState {\n  allowedActions: AgentActionName[];\n  decision: PolicyDecision;\n  hasGroundedEvidence: boolean;\n  hasUsefulEvidence: boolean;\n  loopReview: AgentLoopReviewPacket;\n  shouldReplan: boolean;\n  shouldAskUser: boolean;\n  primaryAmbiguousTarget?: {\n    target: string;\n    candidates: string[];\n    reason: string;\n  };\n  endDecision: AgentPolicyEndDecision | null;\n  reason: string;\n}\n\ninterface ResolvePolicyStateOptions {\n  forcedEnd?: boolean;\n}\n\nconst GENERAL_ROUTE_REASON = \"The query is general and does not need grounded repo evidence before answering.\";\n\nfunction hasConcreteQueryAnchor(query: string): boolean {\n  return /[\\/_.-]/.test(query) || /[a-z][A-Z]/.test(query);\n}\n\nfunction hasQuotedFragmentSearchGuidance(memory: AgentMemory): boolean {\n  return extractQuotedFragments(memory.task.initialQuery).length > 0;\n}\n\nfunction hasActionableSearchMatches(memory: AgentMemory): boolean {\n  return memory.evidence.searches.some((search) => (search.matches?.length ?? 0) > 0);\n}\n\nfunction looksLikeBroadRepoReadOnlyAsk(memory: AgentMemory): boolean {\n  if (isTransformIntent(memory)) {\n    return false;\n  }\n\n  if (memory.task.explicitTargets.length > 0 || memory.task.hardFileTargets.length > 0) {\n    return false;\n  }\n\n  const query = `${memory.task.normalizedQuery} ${memory.task.primaryIntent}`.toLowerCase();\n  const hasRepoScope = /\\b(this repo|the repo|repo|repository|codebase|project)\\b/.test(query);\n  const hasBroadCodeQuestion = /\\b(how|where|which|entrypoints?|tests?|test runner|architecture|flow|configured|configuration)\\b/.test(query);\n  return hasRepoScope && hasBroadCodeQuestion;\n}\n\n/**\n * Allows one discovery search before we ask the user for a narrower hint.\n *\n * Why this helper exists:\n * - weak-signal questions should get one small search chance before we stop\n * - the bootstrap rule should stay owned by policy instead of leaking into search\n * - this must stay one-shot so repeated weak searches still fall back to clarification\n */\nfunction shouldBootstrapDiscoverySearch(\n  memory: AgentMemory,\n  coverage: ReturnType<typeof resolveReadCoverageState>,\n  args: {\n    hasGroundedEvidence: boolean;\n    hasUsefulEvidence: boolean;\n  }\n): boolean {\n  if (memory.task.mode !== \"ask\" || isTransformIntent(memory)) {\n    return false;\n  }\n\n  if (memory.evidence.searches.length > 0 || args.hasGroundedEvidence || args.hasUsefulEvidence) {\n    return false;\n  }\n\n  if (coverage.ambiguousTargets.length > 0 || coverage.unreadHardFileTargets.length > 0) {\n    return false;\n  }\n\n  if (memory.task.explicitTargets.length > 0 || coverage.hardFileTargets.length > 0 || coverage.folderTargets.length > 0) {\n    return false;\n  }\n\n  if (hasQuotedFragmentSearchGuidance(memory) || looksLikeRegexQuery(memory.task.normalizedQuery)) {\n    return false;\n  }\n\n  if (resolveNextFolderListingTarget(memory, coverage)) {\n    return false;\n  }\n\n  return true;\n}\n\nfunction buildReadDecision(\n  allowedActions: AgentActionName[],\n  reason: string,\n  target: string\n): PolicyDecision {\n  return {\n    allowedActions,\n    nextAction: \"read-file\",\n    args: { target },\n    reason,\n  };\n}\n\ntype NextStructuredStep = {\n  nextFolderListingTarget?: string;\n  nextReadTarget?: string;\n  nextTriageTarget?: string;\n  nextTransformTarget?: string;\n  nextSearchQuery: string;\n};\n\nfunction describePolicyReason(\n  memory: AgentMemory,\n  hasUsefulEvidence: boolean,\n  shouldAskUser: boolean,\n  shouldReplan: boolean,\n  coverage: ReturnType<typeof resolveReadCoverageState>\n): string {\n  if (isDirectGeneralAnswerRoute(memory, coverage)) {\n    return GENERAL_ROUTE_REASON;\n  }\n  if (hasUsefulEvidence) {\n    return coverage.evidenceCoverage.reason;\n  }\n  if (isTransformIntent(memory) && coverage.unreadHardFileTargets.length === 0 && coverage.hardFileTargets.length > 0) {\n    return \"The requested file has a grounded full read and is ready for transform.\";\n  }\n  if (shouldAskUser) {\n    return \"The request still needs one concrete user hint.\";\n  }\n  if (shouldReplan) {\n    return \"There is no pending work and evidence is still weak.\";\n  }\n  if (coverage.ambiguousTargets.length > 0) {\n    const ambiguous = coverage.ambiguousTargets[0];\n    return `Need the user to choose the exact in-repo path for ${ambiguous.target}.`;\n  }\n  if (coverage.hasUnresolvedHardFileRequirement) {\n    return coverage.folderTargets.length > 0\n      ? \"A required explicit file or folder target did not resolve inside the repo.\"\n      : \"A required hard file target did not resolve inside the repo.\";\n  }\n  if (coverage.unreadHardFileTargets.length > 0) {\n    return coverage.folderTargets.length > 0\n      ? \"Need grounded reads for the remaining explicit file or folder targets.\"\n      : \"Need grounded reads for the remaining hard file targets.\";\n  }\n  if (coverage.unreadTriageTargets.length > 0 || coverage.unreadFullReadTargets.length > 0) {\n    return coverage.needsBroadTriage\n      ? \"Need another triage or full read from the ranked candidate set before answering.\"\n      : \"Need another ranked candidate read before answering.\";\n  }\n  return \"Need another small evidence-gathering action.\";\n}\n\nexport function resolveNextReadTarget(memory: AgentMemory): string | undefined {\n  const coverage = resolveReadCoverageState(memory);\n  const loopReview = buildLoopReviewPacket(memory, coverage);\n  return resolveNextStructuredStep(memory, coverage, loopReview).nextReadTarget;\n}\n\nexport function resolveNextTriageTarget(memory: AgentMemory): string | undefined {\n  const coverage = resolveReadCoverageState(memory);\n  const loopReview = buildLoopReviewPacket(memory, coverage);\n  return resolveNextStructuredStep(memory, coverage, loopReview).nextTriageTarget;\n}\n\nexport function resolvePreferredReadAction(memory: AgentMemory): \"triage-file\" | \"read-file\" | undefined {\n  const coverage = resolveReadCoverageState(memory);\n  const loopReview = buildLoopReviewPacket(memory, coverage);\n  const reviewTarget = loopReview.expansionAssessment.bestCandidatePath;\n  if (loopReview.expansionAssessment.shouldExpand && reviewTarget) {\n    if (coverage.unreadTriageTargets.includes(reviewTarget) && !coverage.unreadFullReadTargets.includes(reviewTarget)) {\n      return \"triage-file\";\n    }\n    return \"read-file\";\n  }\n  if (coverage.unreadHardFileTargets.length > 0 || coverage.unreadFullReadTargets.length > 0) {\n    return \"read-file\";\n  }\n  if (coverage.unreadTriageTargets.length > 0) {\n    return \"triage-file\";\n  }\n  return undefined;\n}\n\nfunction resolvePreferredSearchQuery(memory: AgentMemory): string {\n  return hasQuotedFragmentSearchGuidance(memory)\n    ? memory.task.initialQuery\n    : memory.task.normalizedQuery;\n}\n\nfunction resolveNextStructuredStep(\n  memory: AgentMemory,\n  coverage: ReturnType<typeof resolveReadCoverageState>,\n  loopReview: AgentLoopReviewPacket\n): NextStructuredStep {\n  const reviewTarget = loopReview.expansionAssessment.bestCandidatePath;\n  const nextReadTarget = loopReview.expansionAssessment.shouldExpand && reviewTarget\n    ? reviewTarget\n    : coverage.unreadFullReadTargets[0];\n  const nextTriageTarget = loopReview.expansionAssessment.shouldExpand && reviewTarget && coverage.unreadTriageTargets.includes(reviewTarget)\n    ? reviewTarget\n    : coverage.unreadTriageTargets[0];\n  return {\n    nextFolderListingTarget: resolveNextFolderListingTarget(memory, coverage),\n    nextReadTarget,\n    nextTriageTarget,\n    nextTransformTarget: memory.task.hardFileTargets[0],\n    nextSearchQuery: resolvePreferredSearchQuery(memory),\n  };\n}\n\nfunction resolvePolicyActionArgs(\n  memory: AgentMemory,\n  coverage: ReturnType<typeof resolveReadCoverageState>,\n  loopReview: AgentLoopReviewPacket,\n  action: AgentActionName\n): PolicyActionArgs | undefined {\n  const nextStep = resolveNextStructuredStep(memory, coverage, loopReview);\n  switch (action) {\n    case \"search-list-directory\":\n      return nextStep.nextFolderListingTarget\n        ? { folderPath: nextStep.nextFolderListingTarget }\n        : undefined;\n    case \"read-file\":\n      return nextStep.nextReadTarget\n        ? { target: nextStep.nextReadTarget }\n        : undefined;\n    case \"triage-file\":\n      return nextStep.nextTriageTarget\n        ? { target: nextStep.nextTriageTarget }\n        : undefined;\n    case \"codeTransform\":\n      return nextStep.nextTransformTarget\n        ? { target: nextStep.nextTransformTarget }\n        : undefined;\n    case \"search-db\":\n      return { query: nextStep.nextSearchQuery };\n    default:\n      return undefined;\n  }\n}\n\nfunction resolvePolicyDecision(\n  memory: AgentMemory,\n  coverage: ReturnType<typeof resolveReadCoverageState>,\n  loopReview: AgentLoopReviewPacket,\n  allowedActions: AgentActionName[],\n  shouldAskUser: boolean,\n  forcedEnd: boolean\n): PolicyDecision {\n  const nextStep = resolveNextStructuredStep(memory, coverage, loopReview);\n\n  if (isDirectGeneralAnswerRoute(memory, coverage) && allowedActions.includes(\"final-answer\")) {\n    return {\n      allowedActions,\n      stop: \"final-answer\",\n      reason: GENERAL_ROUTE_REASON,\n    };\n  }\n\n  if (loopReview.stopAssessment.canStop && allowedActions.includes(\"final-answer\")) {\n    return {\n      allowedActions,\n      stop: \"final-answer\",\n      reason: loopReview.stopAssessment.reason,\n    };\n  }\n\n  if (shouldAskUser && allowedActions.includes(\"request-user-input\")) {\n    return {\n      allowedActions,\n      stop: \"request-user-input\",\n      reason: coverage.ambiguousTargets[0]\n        ? `Need the user to choose the exact in-repo path for ${coverage.ambiguousTargets[0].target}.`\n        : \"The request still needs one concrete user hint.\",\n    };\n  }\n\n  if (allowedActions.includes(\"codeTransform\") && memory.task.hardFileTargets[0]) {\n    return {\n      allowedActions,\n      nextAction: \"codeTransform\",\n      args: resolvePolicyActionArgs(memory, coverage, loopReview, \"codeTransform\"),\n      reason: \"The grounded target file is ready for transform.\",\n    };\n  }\n\n  if (nextStep.nextFolderListingTarget && allowedActions.includes(\"search-list-directory\")) {\n    return {\n      allowedActions,\n      nextAction: \"search-list-directory\",\n      args: resolvePolicyActionArgs(memory, coverage, loopReview, \"search-list-directory\"),\n      reason: \"List the resolved folder target before reading files inside it.\",\n    };\n  }\n\n  if (coverage.unreadHardFileTargets.length > 0 && nextStep.nextReadTarget && allowedActions.includes(\"read-file\")) {\n    return buildReadDecision(\n      allowedActions,\n      coverage.evidenceCoverage.kind === \"needs-read\"\n        ? coverage.evidenceCoverage.reason\n        : \"Read the next grounded target before answering.\",\n      nextStep.nextReadTarget\n    );\n  }\n\n  if (loopReview.referenceFollowupNeeded && nextStep.nextReadTarget && allowedActions.includes(\"read-file\")) {\n    return buildReadDecision(\n      allowedActions,\n      loopReview.expansionAssessment.reason,\n      nextStep.nextReadTarget\n    );\n  }\n\n  if (coverage.unreadTriageTargets.length > 0 && nextStep.nextTriageTarget && allowedActions.includes(\"triage-file\")) {\n    return {\n      allowedActions,\n      nextAction: \"triage-file\",\n      args: resolvePolicyActionArgs(memory, coverage, loopReview, \"triage-file\"),\n      reason: loopReview.referenceFollowupNeeded\n        ? loopReview.expansionAssessment.reason\n        : \"Triage the next ranked candidate before a full read.\",\n    };\n  }\n\n  if (\n    loopReview.driftAssessment.blocksExpansion &&\n    !loopReview.stopAssessment.canStop &&\n    allowedActions.includes(\"plan\")\n  ) {\n    return {\n      allowedActions,\n      nextAction: \"plan\",\n      args: resolvePolicyActionArgs(memory, coverage, loopReview, \"plan\"),\n      reason: loopReview.driftAssessment.reason,\n    };\n  }\n\n  if (coverage.unreadFullReadTargets.length > 0 && nextStep.nextReadTarget && allowedActions.includes(\"read-file\")) {\n    return buildReadDecision(\n      allowedActions,\n      coverage.evidenceCoverage.kind === \"needs-read\"\n        ? coverage.evidenceCoverage.reason\n        : \"Read the next ranked candidate before answering.\",\n      nextStep.nextReadTarget\n    );\n  }\n\n  if (coverage.evidenceCoverage.kind === \"needs-search\" && allowedActions.includes(\"search-db\")) {\n    const nextAction = looksLikeRegexQuery(memory.task.normalizedQuery) && allowedActions.includes(\"search-regex\")\n      ? \"search-regex\"\n      : \"search-db\";\n    return {\n      allowedActions,\n      nextAction,\n      args: resolvePolicyActionArgs(memory, coverage, loopReview, nextAction),\n      reason: coverage.evidenceCoverage.reason,\n    };\n  }\n\n  if (forcedEnd) {\n    return {\n      allowedActions,\n      stop: \"cannot-answer\",\n      reason: \"The gathered evidence is still too weak to answer reliably.\",\n    };\n  }\n\n  return {\n    allowedActions,\n    nextAction: allowedActions[0],\n    args: resolvePolicyActionArgs(memory, coverage, loopReview, allowedActions[0]),\n    reason: \"Take the next legal action.\",\n  };\n}\n\nexport function resolvePolicyState(\n  memory: AgentMemory,\n  options: ResolvePolicyStateOptions = {}\n): AgentPolicyState {\n  const fileReads = Object.values(memory.evidence.fileReads);\n  const hasReadEvidence = fileReads.length > 0;\n  const hasDirectoryListing = memory.evidence.searches.some(isSuccessfulDirectoryListing);\n  const hasGroundedEvidence = hasReadEvidence || hasDirectoryListing;\n  const coverage = resolveReadCoverageState(memory);\n  const loopReview = buildLoopReviewPacket(memory, coverage);\n  const hasSearchGuidance = coverage.softHints.length > 0 ||\n    looksLikeRegexQuery(memory.task.normalizedQuery) ||\n    hasConcreteQueryAnchor(memory.task.normalizedQuery) ||\n    hasQuotedFragmentSearchGuidance(memory);\n  const broadRepoReadOnlyAsk = looksLikeBroadRepoReadOnlyAsk(memory);\n  const hasReviewReadTarget = loopReview.expansionAssessment.shouldExpand && typeof loopReview.expansionAssessment.bestCandidatePath === \"string\";\n  const directGeneralAnswer = isDirectGeneralAnswerRoute(memory, coverage);\n  const primaryAmbiguousTarget = coverage.ambiguousTargets[0]\n    ? {\n        target: coverage.ambiguousTargets[0].target,\n        candidates: coverage.ambiguousTargets[0].candidates,\n        reason: coverage.ambiguousTargets[0].reason,\n      }\n    : undefined;\n  const hasUsefulEvidence = directGeneralAnswer ||\n    hasDirectoryListing ||\n    coverage.evidenceCoverage.kind === \"enough\" ||\n    hasActionableSearchMatches(memory) ||\n    (\n      loopReview.stopAssessment.canStop &&\n      !coverage.hasStructuredTargetRequirement &&\n      !coverage.hasUnresolvedHardFileRequirement &&\n      coverage.unreadHardFileTargets.length === 0\n    );\n  const shouldBootstrapSearch = shouldBootstrapDiscoverySearch(memory, coverage, {\n    hasGroundedEvidence,\n    hasUsefulEvidence,\n  });\n  const shouldAskUser = coverage.ambiguousTargets.length > 0 ||\n    (!hasUsefulEvidence &&\n      !hasReadEvidence &&\n      !shouldBootstrapSearch &&\n      !coverage.hasStructuredTargetRequirement &&\n      !hasSearchGuidance &&\n      !broadRepoReadOnlyAsk);\n  const shouldReplan = !hasPendingStep(memory) &&\n    !directGeneralAnswer &&\n    !hasUsefulEvidence &&\n    memory.evidence.candidateFiles.length === 0 &&\n    !coverage.hasStructuredTargetRequirement &&\n    coverage.ambiguousTargets.length === 0 &&\n    coverage.softHints.length === 0;\n  const allowFinalAnswer = directGeneralAnswer || (\n    hasUsefulEvidence &&\n    loopReview.stopAssessment.canStop &&\n    !coverage.hasUnresolvedHardFileRequirement &&\n    coverage.unreadHardFileTargets.length === 0\n  );\n  const allowedActions = resolveAllowedActions(memory, allowFinalAnswer, coverage, { forceReadFile: hasReviewReadTarget });\n  if (shouldAskUser && !allowedActions.includes(\"request-user-input\")) {\n    allowedActions.unshift(\"request-user-input\");\n  }\n  const decision = resolvePolicyDecision(memory, coverage, loopReview, allowedActions, shouldAskUser, options.forcedEnd ?? false);\n\n  return {\n    allowedActions,\n    decision,\n    hasGroundedEvidence,\n    hasUsefulEvidence,\n    loopReview,\n    shouldReplan,\n    shouldAskUser,\n    primaryAmbiguousTarget,\n    endDecision: options.forcedEnd ? resolveEndDecision(decision) : null,\n    reason: describePolicyReason(memory, hasUsefulEvidence, shouldAskUser, shouldReplan, coverage),\n  };\n}\n"]}