@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/pool/failure-routing.js

@@ -0,0 +1,182 @@
+import { defaultRetryabilityForCategory, recommendedActionForRetryability, } from "./recovery-decision.js";
+const PRODUCT_CATEGORIES = new Set([
+    "SpecUnclear",
+    "ContractMismatch",
+    "ProductBug",
+    "TestBug",
+    "EnvFailure",
+    "FlakyTest",
+    "RiskyChange",
+    "DependencyFailure",
+    "NeedsHuman",
+    "Unknown",
+]);
+const FOLLOW_UP_BY_CATEGORY = {
+    SpecUnclear: "spec-clarification",
+    ContractMismatch: "architecture-contract-fix",
+    ProductBug: "dev-fix",
+    TestBug: "qa-fix-test",
+    EnvFailure: "env-fix",
+    FlakyTest: "flaky-test-analysis",
+    RiskyChange: "human-review",
+    DependencyFailure: "unblock-dependency",
+    NeedsHuman: "human-review",
+    Unknown: "human-triage",
+};
+const FOLLOW_UP_PREFIX_BY_CATEGORY = {
+    SpecUnclear: "SPEC",
+    ContractMismatch: "CONTRACT",
+    ProductBug: "FIX",
+    TestBug: "QA-FIX",
+    EnvFailure: "ENV",
+    FlakyTest: "FLAKY",
+    RiskyChange: "REVIEW",
+    DependencyFailure: "UNBLOCK",
+    NeedsHuman: "REVIEW",
+    Unknown: "TRIAGE",
+};
+const DAG_TO_PRODUCT_CATEGORY = {
+    validation: "SpecUnclear",
+    executor: "EnvFailure",
+    "write-guard": "RiskyChange",
+    timeout: "EnvFailure",
+    auth: "EnvFailure",
+    "human-required": "NeedsHuman",
+    "human-rejected": "NeedsHuman",
+    "shell-command": "ProductBug",
+    "static-error": "SpecUnclear",
+    "decision-envelope": "NeedsHuman",
+    skipped: "DependencyFailure",
+    unknown: "Unknown",
+};
+export function deriveFailureRoute(result) {
+    if (result.status === "succeeded")
+        return undefined;
+    const primaryFailure = readObject(result.reportDecision.primaryFailure);
+    const category = looksLikeExecutorConfigurationFailure(primaryFailure)
+        ? "EnvFailure"
+        : readProductCategory(primaryFailure, "productLineFailureCategory") ??
+            readProductCategory(primaryFailure, "productLineCategory") ??
+            readProductCategory(primaryFailure, "product_line_failure_category") ??
+            mapDagCategory(readString(primaryFailure, "failureCategory")) ??
+            mapDagCategory(readString(primaryFailure, "normalizedFailureCategory")) ??
+            categoryFromDecisionReason(result.reportDecision.reason);
+    const recommendedFollowUpKind = readString(primaryFailure, "recommendedFollowUpKind") ??
+        readString(primaryFailure, "recommendedFollowUp") ??
+        FOLLOW_UP_BY_CATEGORY[category];
+    return {
+        category,
+        recommendedFollowUpKind,
+        derivedFollowUpTaskId: `${FOLLOW_UP_PREFIX_BY_CATEGORY[category]}-${result.businessId}`,
+        source: primaryFailure ? "report-primary-failure" : "fallback",
+    };
+}
+/** Route a failure raised before a DAG report can be produced. */
+export function deriveFailureRouteFromError(message, businessId) {
+    const category = looksLikeExecutorConfigurationText(message)
+        ? "EnvFailure"
+        : "Unknown";
+    return {
+        category,
+        recommendedFollowUpKind: FOLLOW_UP_BY_CATEGORY[category],
+        derivedFollowUpTaskId: `${FOLLOW_UP_PREFIX_BY_CATEGORY[category]}-${businessId}`,
+        source: "runner-error",
+    };
+}
+/**
+ * Phase-aware V2 failure for new writers. V1 FailureRoute remains available.
+ */
+export function deriveFailureRouteV2(result, phase = "execute") {
+    const base = deriveFailureRoute(result);
+    if (!base)
+        return undefined;
+    const retryability = defaultRetryabilityForCategory(base.category, phase);
+    return {
+        ...base,
+        schemaVersion: 2,
+        phase,
+        retryability,
+        recommendedAction: recommendedActionForRetryability(retryability),
+        message: result.reportDecision.reason,
+        evidence: [
+            result.runRecordPath,
+            result.dagPath,
+            ...(result.failureArtifacts
+                ? Object.values(result.failureArtifacts).filter((value) => typeof value === "string")
+                : []),
+        ],
+    };
+}
+export function deriveFailureRouteV2FromError(message, businessId, phase = "prepare") {
+    const base = deriveFailureRouteFromError(message, businessId);
+    const retryability = defaultRetryabilityForCategory(base.category, phase);
+    return {
+        ...base,
+        schemaVersion: 2,
+        phase,
+        retryability,
+        recommendedAction: recommendedActionForRetryability(retryability),
+        message,
+        evidence: [],
+    };
+}
+export function toWorkerAttemptFailureV2(route) {
+    return {
+        schemaVersion: 2,
+        phase: route.phase,
+        category: route.category,
+        message: route.message ?? route.recommendedFollowUpKind,
+        retryability: route.retryability,
+        recommendedAction: route.recommendedAction,
+        evidence: route.evidence ?? [],
+    };
+}
+function readProductCategory(value, key) {
+    const candidate = readString(value, key);
+    return candidate && PRODUCT_CATEGORIES.has(candidate)
+        ? candidate
+        : undefined;
+}
+function mapDagCategory(value) {
+    if (!value || value === "success")
+        return undefined;
+    return DAG_TO_PRODUCT_CATEGORY[value] ?? "Unknown";
+}
+function categoryFromDecisionReason(reason) {
+    if (reason === "report-json-unavailable" || reason === "report-run-missing") {
+        return "Unknown";
+    }
+    return "Unknown";
+}
+function looksLikeExecutorConfigurationFailure(value) {
+    if (!value)
+        return false;
+    return looksLikeExecutorConfigurationText([
+        "failureCategory",
+        "normalizedFailureCategory",
+        "message",
+        "error",
+        "stderr",
+        "detail",
+    ]
+        .map((key) => readString(value, key))
+        .filter((candidate) => Boolean(candidate))
+        .join("\n"));
+}
+function looksLikeExecutorConfigurationText(message) {
+    const value = message.toLowerCase();
+    const executorTerms = /provider|model|executor|api[ _-]?key|credential|thinking level/;
+    const configurationTerms = /unknown|invalid|unsupported|missing|not configured|configuration|unavailable/;
+    return executorTerms.test(value) && configurationTerms.test(value);
+}
+function readObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function readString(value, key) {
+    if (!value)
+        return undefined;
+    const child = value[key];
+    return typeof child === "string" ? child : undefined;
+}

package/dist/worker/pool/migrate-state.js

@@ -0,0 +1,303 @@
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, readFile, rename, rm, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { diagnoseTaskPoolStates, loadOperatorMapping, } from "./doctor.js";
+import { getEventsJsonlPath, getLegacyTaskStatePath, getRunsJsonlPath, getTaskPoolRoot, getTaskStatePath, pathExists, sha256File, sha256Text, } from "./run-store.js";
+import { TASK_POOL_STATE_ERROR_CODES, TaskPoolStateError, } from "./types.js";
+/**
+ * Migrate legacy flat Task Pool states to feature-scoped v2.
+ * Defaults to dry-run (zero writes). Apply requires --owner and --reason.
+ */
+export async function migrateTaskPoolStates(input) {
+    const apply = input.apply === true;
+    const migrationId = input.migrationId ??
+        `migration-${(input.now ?? new Date()).toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+    const mapping = input.mapping ?? (await loadOperatorMapping(input.mappingPath));
+    const doctor = await diagnoseTaskPoolStates(input.repoRoot, { mapping });
+    const planned = [];
+    const skipped = [];
+    for (const item of doctor.legacy) {
+        if (item.resolution === "ambiguous") {
+            skipped.push({
+                taskId: item.taskId,
+                reason: item.detail ?? "identity ambiguous",
+                code: TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS,
+            });
+            continue;
+        }
+        if (item.resolution === "unresolved" || !item.featureId) {
+            skipped.push({
+                taskId: item.taskId,
+                reason: item.detail ?? "no unique identity evidence",
+                code: TASK_POOL_STATE_ERROR_CODES.MIGRATION_REQUIRED,
+            });
+            continue;
+        }
+        const ref = {
+            featureId: item.featureId,
+            taskId: item.taskId,
+        };
+        const v2Path = getTaskStatePath(input.repoRoot, ref);
+        const alreadyMigrated = await pathExists(v2Path);
+        if (alreadyMigrated) {
+            // Idempotent: if v2 already exists with matching identity, skip write.
+            planned.push({
+                taskId: item.taskId,
+                legacyPath: item.legacyPath,
+                legacySha256: item.sha256,
+                featureId: item.featureId,
+                v2Path,
+                resolution: item.resolution,
+                alreadyMigrated: true,
+            });
+            continue;
+        }
+        // Conflict: v2 path occupied by different content is handled at apply time.
+        planned.push({
+            taskId: item.taskId,
+            legacyPath: item.legacyPath,
+            legacySha256: item.sha256,
+            featureId: item.featureId,
+            v2Path,
+            resolution: item.resolution,
+            alreadyMigrated: false,
+        });
+    }
+    const runsPath = getRunsJsonlPath(input.repoRoot);
+    const eventsPath = getEventsJsonlPath(input.repoRoot);
+    const runsHashBefore = (await pathExists(runsPath))
+        ? await sha256File(runsPath)
+        : null;
+    const eventsHashBefore = (await pathExists(eventsPath))
+        ? await sha256File(eventsPath)
+        : null;
+    if (!apply) {
+        return {
+            schemaVersion: 1,
+            mode: "dry-run",
+            status: planned.length === 0 && skipped.length === 0 ? "noop" : "planned",
+            migrationId,
+            planned,
+            skipped,
+            jsonlUnchanged: { runs: true, events: true },
+            doctor,
+        };
+    }
+    if (!input.owner?.trim()) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, "pool migrate-state --apply requires a non-empty --owner");
+    }
+    if (!input.reason?.trim()) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, "pool migrate-state --apply requires a non-empty --reason");
+    }
+    if (skipped.some((item) => item.code === TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS)) {
+        return {
+            schemaVersion: 1,
+            mode: "apply",
+            status: "failed",
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            planned,
+            skipped,
+            jsonlUnchanged: { runs: true, events: true },
+            doctor,
+            error: {
+                code: TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS,
+                message: "refusing apply while any legacy identity is ambiguous",
+            },
+        };
+    }
+    const actionable = planned.filter((item) => !item.alreadyMigrated);
+    if (actionable.length === 0 && planned.every((item) => item.alreadyMigrated)) {
+        // Idempotent re-run: move any remaining legacy files that match already-migrated v2.
+        // If legacy still present with alreadyMigrated, still archive them.
+    }
+    const artifactDir = path.join(getTaskPoolRoot(input.repoRoot), "artifacts", "migrations", migrationId);
+    const beforeDir = path.join(artifactDir, "before");
+    const stagingDir = path.join(artifactDir, "staging");
+    const writtenV2 = [];
+    const movedLegacy = [];
+    try {
+        await mkdir(beforeDir, { recursive: true });
+        await mkdir(stagingDir, { recursive: true });
+        // Stage all v2 payloads first.
+        const staged = [];
+        for (const item of planned) {
+            const legacyBytes = await readFile(item.legacyPath);
+            const legacyText = legacyBytes.toString("utf-8");
+            const hash = await sha256Text(legacyText);
+            if (hash !== item.legacySha256) {
+                throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `legacy state changed during migration: ${item.taskId}`);
+            }
+            const parsed = JSON.parse(legacyText);
+            const payload = {
+                ...parsed,
+                schemaVersion: 2,
+                featureId: item.featureId,
+                taskId: item.taskId,
+            };
+            const stagedPath = path.join(stagingDir, `${item.featureId}__${item.taskId}.json`);
+            await writeFile(stagedPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+            staged.push({ item, stagedPath, payload, legacyBytes });
+        }
+        // Conflict checks against existing v2 targets.
+        for (const entry of staged) {
+            if (await pathExists(entry.item.v2Path)) {
+                const existing = JSON.parse(await readFile(entry.item.v2Path, "utf-8"));
+                if (existing.featureId === entry.item.featureId &&
+                    existing.taskId === entry.item.taskId) {
+                    // already migrated — ok, will only archive legacy
+                    continue;
+                }
+                throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `v2 target already exists with different identity: ${entry.item.v2Path}`);
+            }
+        }
+        // Atomic rename of staged v2 files.
+        for (const entry of staged) {
+            if (await pathExists(entry.item.v2Path)) {
+                // already migrated
+                continue;
+            }
+            await mkdir(path.dirname(entry.item.v2Path), { recursive: true });
+            const tempPath = `${entry.item.v2Path}.${randomUUID()}.tmp`;
+            try {
+                await copyFile(entry.stagedPath, tempPath);
+                await input.faultInjector?.("before-v2-rename", entry.item.taskId);
+                await rename(tempPath, entry.item.v2Path);
+                writtenV2.push(entry.item.v2Path);
+            }
+            finally {
+                await unlink(tempPath).catch(() => { });
+            }
+        }
+        await input.faultInjector?.("after-partial-v2");
+        // Move legacy into artifact before/.
+        for (const entry of staged) {
+            const dest = path.join(beforeDir, path.basename(entry.item.legacyPath));
+            await input.faultInjector?.("before-legacy-move", entry.item.taskId);
+            if (await pathExists(entry.item.legacyPath)) {
+                // Preserve exact bytes
+                await writeFile(dest, entry.legacyBytes);
+                await unlink(entry.item.legacyPath);
+                movedLegacy.push({
+                    from: entry.item.legacyPath,
+                    to: dest,
+                    originalBytes: entry.legacyBytes,
+                });
+            }
+        }
+        const mappingDoc = {
+            schemaVersion: 1,
+            migrationId,
+            items: planned.map((item) => ({
+                taskId: item.taskId,
+                featureId: item.featureId,
+                resolution: item.resolution,
+                legacySha256: item.legacySha256,
+                v2Path: item.v2Path,
+                alreadyMigrated: item.alreadyMigrated,
+            })),
+            skipped,
+        };
+        const manifest = {
+            schemaVersion: 1,
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            appliedAt: (input.now ?? new Date()).toISOString(),
+            plannedCount: planned.length,
+            skippedCount: skipped.length,
+        };
+        const resultDoc = {
+            schemaVersion: 1,
+            status: "applied",
+            migrationId,
+            writtenV2,
+            archivedLegacy: movedLegacy.map((item) => item.to),
+        };
+        await writeFile(path.join(artifactDir, "mapping.json"), `${JSON.stringify(mappingDoc, null, 2)}\n`, "utf-8");
+        await writeFile(path.join(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+        await writeFile(path.join(artifactDir, "result.json"), `${JSON.stringify(resultDoc, null, 2)}\n`, "utf-8");
+        // Clean staging
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        const runsHashAfter = (await pathExists(runsPath))
+            ? await sha256File(runsPath)
+            : null;
+        const eventsHashAfter = (await pathExists(eventsPath))
+            ? await sha256File(eventsPath)
+            : null;
+        return {
+            schemaVersion: 1,
+            mode: "apply",
+            status: "applied",
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            planned,
+            skipped,
+            artifactDir,
+            jsonlUnchanged: {
+                runs: runsHashBefore === runsHashAfter,
+                events: eventsHashBefore === eventsHashAfter,
+            },
+            doctor,
+        };
+    }
+    catch (error) {
+        // Full rollback: restore legacy, remove half-written v2.
+        for (const v2Path of writtenV2) {
+            await unlink(v2Path).catch(() => { });
+        }
+        for (const moved of movedLegacy) {
+            await writeFile(moved.from, moved.originalBytes).catch(() => { });
+            await unlink(moved.to).catch(() => { });
+        }
+        // Also restore any legacy that was deleted without movedLegacy tracking
+        // (should not happen with current flow).
+        for (const item of planned) {
+            if (!(await pathExists(item.legacyPath))) {
+                // try recover from beforeDir if present
+                const dest = path.join(beforeDir, path.basename(item.legacyPath));
+                if (await pathExists(dest)) {
+                    await copyFile(dest, item.legacyPath).catch(() => { });
+                }
+            }
+            if (!item.alreadyMigrated &&
+                (await pathExists(item.v2Path)) &&
+                writtenV2.includes(item.v2Path)) {
+                await unlink(item.v2Path).catch(() => { });
+            }
+        }
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = error instanceof TaskPoolStateError
+            ? error.code
+            : TASK_POOL_STATE_ERROR_CODES.CONFLICT;
+        return {
+            schemaVersion: 1,
+            mode: "apply",
+            status: "failed",
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            planned,
+            skipped,
+            artifactDir,
+            jsonlUnchanged: { runs: true, events: true },
+            doctor,
+            error: { code, message: detail },
+        };
+    }
+}
+/** Helper for tests: write a legacy flat state file without going through writeTaskPoolState. */
+export async function writeLegacyTaskPoolState(repoRoot, state) {
+    const statePath = getLegacyTaskStatePath(repoRoot, state.taskId);
+    await mkdir(path.dirname(statePath), { recursive: true });
+    const payload = {
+        schemaVersion: 1,
+        ...state,
+    };
+    delete payload.featureId;
+    await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+    return statePath;
+}