@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.10

package/dist/workflows/dag/retry-policy.js

@@ -1,61 +1,14 @@
-import { z } from "zod";
+import { projectProtocolFailureReason, } from "./frontend-recovery-capsule.js";
+import { TYPED_EVENT_FACT_KINDS } from "./frontend-typed-event-store.js";
 /**
- * Failure categories that are safe to auto-retry for read-only Pi nodes.
- *
- * These are failures with no repository write side-effects: model connection
- * interruption, provider rate-limiting, temporary provider unavailability,
- * request timeout, or a settled read-only turn with no assistant text.
- *
- * `quota` is intentionally NOT included: a quota exhaustion is an account
- * billing/plan state, not a transient rate limit, and retrying immediately
- * will not help and may waste budget.
- */
-export const DEFAULT_DAG_RETRY_CATEGORIES = [
-    "timeout",
-    "network",
-    "rate-limit",
-    "unavailable",
-    "empty-output",
-];
-export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
-export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
-/** Recoverable model artifact/schema formatting failure on read-only structured nodes. */
-export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
-/** Provider stopReason=length truncated the response before the JSON contract completed. */
-export const STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY = "structured-output-truncated";
-/** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
-export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
-/** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
-export const INCOMPLETE_WRITE_SET_RETRY_CATEGORY = "incomplete-write-set";
-/**
- * Provider/transport stall or absolute timeout on a Pi exclusive writer that
- * left zero attributed workspace writes and zero write-tool calls. Safe to
- * retry once because the attempt was a pure provider flake (no side effects).
- * Partial writes keep the original `timeout` category and do NOT retry.
+ * Failure-category constants, the zod retry-policy schema, and the
+ * target-template transient retry profile live in the leaf module
+ * `dag-retry-schema.ts` (see its header for the cycle rationale). Everything
+ * is re-exported here unchanged so retry-policy stays the single import
+ * surface for retry policies and helpers.
  */
-export const WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY = "writer-clean-timeout";
-export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
-    ...DEFAULT_DAG_RETRY_CATEGORIES,
-    STRUCTURED_OUTPUT_RETRY_CATEGORY,
-    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
-    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
-];
-/** Categories allowed on nodes that declare a machine-readable outputProtocol. */
-export const PROTOCOL_AWARE_DAG_RETRY_CATEGORIES = [
-    ...DEFAULT_DAG_RETRY_CATEGORIES,
-    PROTOCOL_INVALID_RETRY_CATEGORY,
-    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
-];
-export const ALL_DAG_RETRY_CATEGORIES = [
-    ...DEFAULT_DAG_RETRY_CATEGORIES,
-    STRUCTURED_OUTPUT_RETRY_CATEGORY,
-    PROTOCOL_INVALID_RETRY_CATEGORY,
-    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
-    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
-    WRITER_EMPTY_DIFF_RETRY_CATEGORY,
-    INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
-    WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
-];
+export { ALL_DAG_RETRY_CATEGORIES, CONTEXT_OVERFLOW_RETRY_CATEGORY, DEFAULT_DAG_RETRY_CATEGORIES, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, PROTOCOL_AWARE_DAG_RETRY_CATEGORIES, PROTOCOL_INVALID_RETRY_CATEGORY, READ_BURST_RETRY_CATEGORY, REVIEW_TERMINAL_MISSING_RETRY_CATEGORY, STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY, STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, dagRetryBackoffSchema, dagRetryCategorySchema, dagRetryPolicySchema, } from "./dag-retry-schema.js";
+import { CONTEXT_OVERFLOW_RETRY_CATEGORY, DEFAULT_DAG_RETRY_CATEGORIES, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, PROTOCOL_AWARE_DAG_RETRY_CATEGORIES, READ_BURST_RETRY_CATEGORY, REVIEW_TERMINAL_MISSING_RETRY_CATEGORY, STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "./dag-retry-schema.js";
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
     "scout",
@@ -64,53 +17,38 @@ const RETRY_SAFE_PI_ROLES = new Set([
     "supervisor",
     "closeout",
 ]);
-export const dagRetryCategorySchema = z.enum(ALL_DAG_RETRY_CATEGORIES);
-export const dagRetryBackoffSchema = z.enum(["exponential"]);
-/**
- * Opt-in retry policy for a DagTask. Generated for safe read-only Pi nodes,
- * except the single validation-gated writer-empty-diff policy. Validation
- * rejects all other writers, dynamic, shell, static, and decision-gate nodes.
- */
-export const dagRetryPolicySchema = z
-    .object({
-    /**
-     * Total number of attempts (including the first try). Must be 1..5.
-     * A value of 1 disables retry (one attempt, no retry).
-     */
-    maxAttempts: z.number().int().positive().max(5),
-    backoff: dagRetryBackoffSchema.default("exponential"),
-    /** Initial delay before the second attempt, in milliseconds. */
-    initialDelayMs: z.number().int().nonnegative().default(2000),
-    /** Upper bound on a single backoff delay, in milliseconds. */
-    maxDelayMs: z.number().int().nonnegative().default(30000),
-    /**
-     * Explicit set of failure categories eligible for retry. Defaults to
-     * {@link DEFAULT_DAG_RETRY_CATEGORIES}. `quota` and other categories
-     * are never retried.
-     */
-    retryCategories: z
-        .array(dagRetryCategorySchema)
-        .default([...DEFAULT_DAG_RETRY_CATEGORIES]),
-})
-    .superRefine((policy, ctx) => {
-    if (policy.maxDelayMs < policy.initialDelayMs) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "retryPolicy.maxDelayMs must be >= retryPolicy.initialDelayMs",
-            path: ["maxDelayMs"],
-        });
-    }
-});
 /**
  * The default retry policy applied to safe generated read-only Pi nodes.
  * Total attempts: 3, exponential backoff with cap.
+ *
+ * Includes `context-overflow`: a read-only node that blew the context window
+ * (400 request too large, e.g. a review node accumulating too many reads) is a
+ * transient, safe-to-retry failure — the retry re-runs the node with a
+ * compact-context instruction instead of failing the whole run. Previously
+ * only writer transport policies had context-overflow; contract/scout/
+ * design-review/review fell straight to ERROR without a retry attempt.
  */
 export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
     maxAttempts: 3,
     backoff: "exponential",
     initialDelayMs: 2000,
     maxDelayMs: 30000,
-    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES],
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
+};
+/** Scout is the discovery authority. A missing/incomplete typed target surface
+ * is safe to retry in-node, rather than making Plan rediscover the repository. */
+export const FRONTEND_SCOUT_COMPLETENESS_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Structured planner nodes may retry with a compact-output instruction
@@ -120,7 +58,11 @@ export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
  */
 export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
-    retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
+    retryCategories: [
+        ...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Planner read-only nodes (standard DAG contract-pi / plan-pi) may retry with
@@ -131,7 +73,12 @@ export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
  */
 export const PLANNER_OUTPUT_LIMIT_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
-    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES, STRUCTURED_OUTPUT_RETRY_CATEGORY],
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_OUTPUT_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Default retry for reviewer / recovery nodes that declare outputProtocol.
@@ -141,6 +88,22 @@ export const PROTOCOL_AWARE_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
     retryCategories: [...PROTOCOL_AWARE_DAG_RETRY_CATEGORIES],
 };
+/**
+ * frontend-review-pi retry policy. The review verdict must be committed
+ * through the typed terminal tools (approve_review / request_review_changes);
+ * a model that only echoes "VERDICT: pass" text fails as
+ * review-terminal-missing. That is read-only and safe to retry with a
+ * corrected instruction so a single model slip does not burn the whole run.
+ */
+export const FRONTEND_REVIEW_TERMINAL_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+        REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
+    ],
+};
 /**
  * The sole writer retry policy for requireChangedFiles writers. It is
  * intentionally not included in any read-only default: a writer may retry only
@@ -163,7 +126,10 @@ export const WRITER_TRANSPORT_RETRY_POLICY = {
     backoff: "exponential",
     initialDelayMs: 5000,
     maxDelayMs: 30000,
-    retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
+    retryCategories: [
+        WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Implicit runtime retry for canonical final verify shells. Not a DagRetryPolicy:
@@ -182,18 +148,23 @@ export const VERIFY_SHELL_RETRY_POLICY = {
     maxDelayMs: 30000,
     retryCategories: VERIFY_SHELL_RETRY_CATEGORIES,
 };
-export const TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE = "standard-reviewed-supervised-v1";
 /**
  * Target-template exclusive implement-pi transport retry. Same schema category
  * as frontend (`writer-clean-timeout`) so DagSpec validation stays unchanged;
- * only the delay cap is wider. Do not mutate {@link WRITER_TRANSPORT_RETRY_POLICY}.
+ * only the delay cap is wider. Context overflow is added so a writer whose
+ * session hit the context window (compact+retry inside the SDK) can retry once
+ * more at the DAG level with a fresh attempt. Do not mutate
+ * {@link WRITER_TRANSPORT_RETRY_POLICY}.
  */
 export const TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY = {
     maxAttempts: 2,
     backoff: "exponential",
     initialDelayMs: 5000,
     maxDelayMs: 60000,
-    retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
+    retryCategories: [
+        WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Backend-test generation writers: empty-diff once, plus bounded incomplete-write-set
@@ -209,6 +180,11 @@ export const BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY = {
         INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
     ],
 };
+/** Markdown shard writers use one full attempt plus at most one bounded binding repair. */
+export const BACKEND_TEST_MARKDOWN_BINDING_RETRY_POLICY = {
+    ...BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY,
+    maxAttempts: 2,
+};
 /**
  * Deterministic helper: is this raw failure category eligible for retry under
  * the given policy? Pure function; executor never decides retry eligibility.
@@ -259,13 +235,14 @@ export function isWriterEmptyDiffRetryCandidate(task) {
         task.writerOutcomePolicy?.requireChangedFiles === true);
 }
 /**
- * Standard exclusive implementers (implementation-outcome writers) may take a
- * single clean-timeout transport retry. Backend completeness writers already
- * have their own policy and are excluded here.
+ * Standard exclusive implementers (implementation-outcome and frontend-facts
+ * writers) may take a single clean-timeout transport retry. Backend
+ * completeness writers already have their own policy and are excluded here.
  */
 export function isWriterTransportRetryCandidate(task) {
     return (isExclusivePiImplementer(task) &&
-        task.writerOutcomePolicy?.type === "implementation-outcome-v1" &&
+        (task.writerOutcomePolicy?.type === "implementation-outcome-v1" ||
+            task.writerOutcomePolicy?.type === "frontend-facts-v1") &&
         task.writerOutcomePolicy.requireChangedFiles !== true);
 }
 /**
@@ -370,3 +347,141 @@ export function computeBackoffDelayMs(attemptNumber, policy) {
     const raw = policy.initialDelayMs * 2 ** exponent;
     return Math.min(raw, policy.maxDelayMs);
 }
+/**
+ * A+B (AC-001/AC-005): project raw executor signals to the canonical 7-value
+ * protocol failure reason. Specific signals win first, then the existing
+ * alias/enum passthrough; unknown signals fail closed to `undefined`.
+ */
+export function projectFrontendNodeProtocolFailureReason(input) {
+    // 1. length stop reason without a terminal → length-before-terminal.
+    if (input.stopReason === "length" && input.hasTerminalFact === false) {
+        return "length-before-terminal";
+    }
+    // 2. timeout with reasoning-side evidence → reasoning-timeout.
+    if (input.failureCategory === "timeout" &&
+        /(?:reasoning|thinking|thought)/i.test(input.assistantText ?? "")) {
+        return "reasoning-timeout";
+    }
+    // 3. empty output without a terminal → provider-ended-without-terminal.
+    if (input.failureCategory === "empty-output" &&
+        input.hasTerminalFact === false) {
+        return "provider-ended-without-terminal";
+    }
+    // 4. Alias/enum passthrough; unknown fails closed to undefined.
+    return projectProtocolFailureReason(input.failureCategory ?? "");
+}
+export const FRONTEND_PLAN_LADDER = [
+    "normal",
+    "compact-terminal-first",
+    "bounded-tool-only",
+    "backup-model",
+];
+/**
+ * Map a 7-value protocol failure reason to the closest provider capability
+ * fact kind for backup-model routing. `unsupported-tool-capability` is a
+ * protocol reason, not a provider capability kind, so it is deliberately NOT
+ * a valid route (fail-closed to `unsupported-provider-capability`).
+ */
+export function frontendPlanProtocolReasonToCapabilityKind(reason) {
+    switch (reason) {
+        case "length-before-terminal":
+            return "length-before-terminal";
+        case "reasoning-timeout":
+            return "reasoning-timeout";
+        case "provider-ended-without-terminal":
+            return "provider-ended-without-terminal";
+        case "terminal-event-missing":
+        case "terminal-conflict":
+            return "terminal-commit";
+        case "typed-fact-invalid":
+            return "read-only-fact-channel";
+        case "unsupported-tool-capability":
+            return "unsupported-tool-capability";
+        default:
+            return undefined;
+    }
+}
+/**
+ * A+B (AC-003): resolve a backup-model route against the frozen seven-kind
+ * provider capability catalog (the exact set `routeFrontendProviderCapability`
+ * consults). `unsupported-tool-capability` is a protocol reason, not a
+ * provider capability kind, so it (and any unmapped reason) fails closed to
+ * `unsupported-provider-capability` — never swapped for the 7-value reason.
+ */
+export function resolveFrontendPlanBackupRoute(reason) {
+    const factKind = frontendPlanProtocolReasonToCapabilityKind(reason);
+    if (!factKind) {
+        return { ok: false, reason: "unsupported-provider-capability" };
+    }
+    return TYPED_EVENT_FACT_KINDS.includes(factKind)
+        ? { ok: true, factKind }
+        : { ok: false, reason: "unsupported-provider-capability" };
+}
+/**
+ * A+B (AC-002): deterministic ladder resolution. Reason-mandated upgrades
+ * (length → compact-terminal-first; terminal/timeout/empty → bounded-tool-only)
+ * never regress below the current rung. A repeated failure fingerprint with no
+ * new committed fact escalates one rung instead of re-running the same step;
+ * at `backup-model` that becomes `non-converging`, and an unavailable backup
+ * provider route fails closed to `unsupported-provider-capability`.
+ */
+export function resolveFrontendPlanRetryStep(input) {
+    if (input.currentStep === "non-converging" ||
+        input.currentStep === "unsupported-provider-capability") {
+        return input.currentStep;
+    }
+    const currentIndex = FRONTEND_PLAN_LADDER.indexOf(input.currentStep);
+    const reasonStep = reasonMandatedFrontendPlanRetryStep(input.protocolFailureReason);
+    const reasonIndex = reasonStep
+        ? FRONTEND_PLAN_LADDER.indexOf(reasonStep)
+        : -1;
+    let nextIndex = Math.max(currentIndex, reasonIndex);
+    const repeated = input.priorFingerprints.includes(input.fingerprint);
+    if (repeated && !input.hasNewCommittedFact) {
+        nextIndex = Math.max(nextIndex, currentIndex + 1);
+    }
+    const nextStep = nextIndex >= FRONTEND_PLAN_LADDER.length
+        ? "non-converging"
+        : (FRONTEND_PLAN_LADDER[nextIndex] ?? "non-converging");
+    if (nextStep === "backup-model" && input.backupRouteAvailable === false) {
+        return "unsupported-provider-capability";
+    }
+    return nextStep;
+}
+function reasonMandatedFrontendPlanRetryStep(reason) {
+    switch (reason) {
+        case "length-before-terminal":
+            return "compact-terminal-first";
+        case "terminal-event-missing":
+        case "reasoning-timeout":
+        case "provider-ended-without-terminal":
+            return "bounded-tool-only";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Opt-in retry policy mounted on the frontend-plan-pi node. maxAttempts=3
+ * bounds plan retry cost: the four-rung ladder is only partially traversable
+ * before the run fails non-converging (rungs: normal → bounded-tool-only →
+ * compact-terminal-first → backup-model). `invalid-output` (typed-fact schema
+ * violations, e.g. verification targets referencing undeclared UI states)
+ * retries at the `normal` rung with the contractCheck reason injected via
+ * `<retry_instruction>` (§5.1 ladder).
+ */
+export const FRONTEND_PLAN_LADDER_RETRY_POLICY = {
+    // Extreme-environment (small output window) plan nodes submit dozens of
+    // incremental record_* calls; dense call bursts hit provider rate limits
+    // whose windows exceed the old 30s cap. Longer backoff gives the limit
+    // window time to expire before the next attempt.
+    maxAttempts: 3,
+    backoff: "exponential",
+    initialDelayMs: 5000,
+    maxDelayMs: 60000,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
+};