@tea-agent/loop-agent 0.41.0-next.3 → 0.41.1-beta.0

package/dist/workflows/dag/frontend-writer-admission.js

@@ -0,0 +1,285 @@
+import { deterministicSha256, frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
+import { expandFrontendGlobPaths } from "./frontend-worktree-diff.js";
+import { z } from "zod";
+/** Runtime writer admission evidence. This is the sole production authorization type. */
+export const frontendWriterAdmissionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    writerNodeId: z.literal("frontend-implement-pi"),
+    decision: z.enum(["authorized", "denied"]),
+    sourceArtifact: z.string().min(1),
+    artifactHash: z.string().regex(/^[a-f0-9]{64}$/),
+    checkedAt: z.string().min(1),
+    reason: z.string().nullable(),
+})
+    .strict();
+/** A+B (AC-006): four-state writer admission classification. `accepted` is the
+ * only authorized state; `requires-human-approval` is the High-topology
+ * high-admission-receipt gate; `blocked` is deterministic denial; `stale` is
+ * digest drift (source refresh / re-contract). */
+export const frontendWriterAdmissionClassificationSchema = z.enum([
+    "accepted",
+    "requires-human-approval",
+    "blocked",
+    "stale",
+    // Legacy fixture alias: writeSet-external test helpers still emit `admitted`.
+    // Canonical producers always emit one of the four values above.
+    "admitted",
+]);
+/** A+B (AC-006): Micro topology uses `requirement-to-target-and-evidence`
+ * coverage; Small/Standard/High use `requirement-to-decision`. The two schemas
+ * are deliberately separated so a Micro evidence coverage can never be read as
+ * a decision coverage. */
+export const frontendAdmissionCoverageSchema = z.discriminatedUnion("coverageId", [
+    z
+        .object({
+        coverageId: z.literal("requirement-to-target-and-evidence"),
+        requirementId: z.string().min(1),
+        targetPaths: z.array(z.string().min(1)),
+        evidenceRefs: z.array(z.string().min(1)),
+    })
+        .strict(),
+    z
+        .object({
+        coverageId: z.literal("requirement-to-decision"),
+        requirementId: z.string().min(1),
+        decisionRefs: z.array(z.string().min(1)),
+    })
+        .strict(),
+]);
+/** Failure-source values shared with frontend recovery planning (M8). */
+export const frontendAdmissionFailureSourceSchema = z.enum([
+    "frontend-plan-pi",
+    "frontend-design-policy-shell",
+    "frontend-writer-admission-shell",
+    "frontend-implement-pi",
+    "frontend-verify-shell",
+]);
+/**
+ * Deterministic artifact schema for `contracts/frontend-writer-admission-result.json`.
+ * Scheduler admission gate and frontend recovery planning read this artifact
+ * (fail-closed); it replaces the legacy frontend-prewrite-result-v1 as the
+ * write authorization source.
+ */
+export const frontendWriterAdmissionResultV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal("frontend-writer-admission-shell-v1"),
+    classification: frontendWriterAdmissionClassificationSchema,
+    writeSet: z.array(z.string().min(1)),
+    writeSetDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    baselineDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    admissionDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    baselineDebtPolicy: z.string().min(1).optional(),
+    findings: z.array(z
+        .object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+        path: z.string().optional(),
+    })
+        .strict()),
+    // r12 policy change: a request_design_changes verdict no longer blocks
+    // writer admission. The verdict and its findings ride along as
+    // advisory context for the implement node; blocking is owned by the
+    // deterministic gates (prewrite, write guard) and the final code
+    // review.
+    designReviewAdvisory: z
+        .object({
+        verdict: z.enum(["approve_design", "request_design_changes"]),
+        restartPhase: z.string().min(1).optional(),
+        findingCount: z.number().int().nonnegative(),
+    })
+        .strict()
+        .optional(),
+    failureSource: frontendAdmissionFailureSourceSchema.optional(),
+})
+    .strict();
+/** Artifact relative path written by the frontend-writer-admission-shell. */
+export const FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT = "contracts/frontend-writer-admission-result.json";
+function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        if (a.code !== b.code)
+            return a.code < b.code ? -1 : 1;
+        if (a.message !== b.message)
+            return a.message < b.message ? -1 : 1;
+        const pathA = a.path ?? "";
+        const pathB = b.path ?? "";
+        if (pathA !== pathB)
+            return pathA < pathB ? -1 : 1;
+        return 0;
+    });
+}
+/** Reject non-concrete writeSet entries: absolute paths, traversal, globstar,
+ * repo-root, and empty/duplicate-slash segments. */
+export function isConcreteWriteSetPath(value) {
+    const path = value.trim();
+    if (path === "" || path === "." || path === "./")
+        return false;
+    if (path.startsWith("/") || path.includes("\\"))
+        return false;
+    const segments = path.split("/");
+    if (segments.some((segment) => segment === ".." || segment === "**" || segment === "")) {
+        return false;
+    }
+    return true;
+}
+/** Derive the concrete writeSet from implementation targets ∪ non-static
+ * verification target files. Entries are de-duplicated and lexicographically
+ * sorted (frozen). */
+export function deriveWriteSet(contract, options) {
+    const findings = [];
+    const candidates = [
+        ...contract.targets.files,
+        ...contract.verificationTargets
+            .filter((target) => target.type !== "static")
+            .map((target) => target.file),
+    ];
+    // Expand glob entries (e.g. `src/**` inherited from the skeleton) against
+    // the enumerated workspace files so the derived writeSet contains only
+    // concrete paths. Without a file list, globs are treated as concrete and
+    // rejected by isConcreteWriteSetPath below (fail-closed).
+    const expanded = options?.workspaceFiles
+        ? expandFrontendGlobPaths({
+            candidates,
+            workspaceFiles: options.workspaceFiles,
+        })
+        : candidates;
+    const writeSet = new Set();
+    for (const candidate of expanded) {
+        if (!isConcreteWriteSetPath(candidate)) {
+            findings.push({
+                code: "write-set-path-not-concrete",
+                message: `writeSet entry is not a concrete path: ${candidate}`,
+                path: candidate,
+            });
+            continue;
+        }
+        writeSet.add(candidate);
+    }
+    return { writeSet: [...writeSet].sort(), findings };
+}
+/** Sort and freeze the injected baseline; duplicate paths and empty baselines
+ * are blocking (collection itself is production wiring, not this shell). */
+export function freezeBaseline(baseline) {
+    const findings = [];
+    if (baseline.length === 0) {
+        findings.push({
+            code: "baseline-empty",
+            message: "writer admission baseline is empty",
+        });
+    }
+    const seen = new Set();
+    for (const entry of baseline) {
+        if (seen.has(entry.path)) {
+            findings.push({
+                code: "baseline-duplicate-path",
+                message: `baseline contains duplicate path: ${entry.path}`,
+                path: entry.path,
+            });
+        }
+        seen.add(entry.path);
+    }
+    const sorted = [...baseline].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return { baselineDigest: deterministicSha256(sorted), findings };
+}
+/** Combine mock strategy, allowed strategies digest, frozen command digest,
+ * production-default-off flag and real-integration expectation into one
+ * deterministic admission digest. */
+export function deriveAdmissionDigest(contract, allowedMockStrategies, frozenCommandLabels, baselineDebtPolicy) {
+    return deterministicSha256({
+        mockApiStrategy: contract.mockApi.strategy,
+        allowedMockStrategiesDigest: deterministicSha256([...allowedMockStrategies].sort()),
+        frozenCommandLabelsDigest: deterministicSha256([...frozenCommandLabels].sort()),
+        productionDefaultOff: contract.mockApi.productionDefaultOff === true,
+        hasRealIntegrationGap: Boolean(contract.realIntegrationGap),
+        baselineDebtPolicy: baselineDebtPolicy ?? "",
+    });
+}
+/** Shape-aware deterministic admission: re-validate the typed contract, honor
+ * the design-policy result, derive/freeze the writeSet, digest the baseline,
+ * and assemble the admission digest. */
+export function deriveFrontendWriterAdmissionShell(input) {
+    const findings = [];
+    const shape = frontendImplementationContractSchema.safeParse(input.contract);
+    if (!shape.success) {
+        findings.push({
+            code: "contract-shape-invalid",
+            message: `contract fails strict shape validation: ${shape.error.issues[0]?.message ?? "unknown issue"}`,
+            path: shape.error.issues[0]?.path.join(".") || undefined,
+        });
+    }
+    if (input.designPolicyResult.classification === "blocked") {
+        findings.push({
+            code: "design-policy-blocked",
+            message: `design policy is blocked with ${input.designPolicyResult.findings.length} finding(s)`,
+        });
+    }
+    const derived = deriveWriteSet(input.contract, {
+        workspaceFiles: input.workspaceFiles,
+    });
+    findings.push(...derived.findings);
+    const baseline = freezeBaseline(input.baseline);
+    findings.push(...baseline.findings);
+    const sortedFindings = sortFindings(findings);
+    // Deterministic admission: any finding blocks. High-risk contracts keep the
+    // full policy/writeSet/baseline gates but do NOT stop for a human approval
+    // step — the DAG runs unattended, so `requires-human-approval` would strand
+    // every high-risk writer. The receipt is still materialized for audit; the
+    // scheduler authorizes `accepted` directly.
+    const classification = sortedFindings.length > 0 ? "blocked" : "accepted";
+    const result = {
+        schemaId: "frontend-writer-admission-shell-v1",
+        classification,
+        writeSet: derived.writeSet,
+        writeSetDigest: deterministicSha256(derived.writeSet),
+        baselineDigest: baseline.baselineDigest,
+        admissionDigest: deriveAdmissionDigest(input.contract, input.allowedMockStrategies, input.frozenCommandLabels, input.baselineDebtPolicy),
+        ...(input.baselineDebtPolicy !== undefined
+            ? { baselineDebtPolicy: input.baselineDebtPolicy }
+            : {}),
+        findings: sortedFindings,
+    };
+    return result;
+}
+function normalizeNewVerdict(classification) {
+    return classification === "accepted" ||
+        classification === "requires-human-approval" ||
+        classification === "admitted"
+        ? "accepted"
+        : "blocked";
+}
+function normalizeLegacyVerdict(classification) {
+    return classification === "accepted" || classification === "accepted-normalized"
+        ? "accepted"
+        : "blocked";
+}
+export function compareAdmissionToLegacyGate(input) {
+    const newVerdict = normalizeNewVerdict(input.newClassification);
+    const legacyVerdict = normalizeLegacyVerdict(input.legacyClassification);
+    return {
+        newClassification: input.newClassification,
+        legacyClassification: input.legacyClassification,
+        newVerdict,
+        legacyVerdict,
+        match: newVerdict === legacyVerdict,
+    };
+}
+/** Render a stable, deterministically ordered mismatch list for the evaluation
+ * set. Input order is irrelevant: rows are sorted by a canonical key. */
+export function renderAdmissionShadowDiff(results) {
+    const indexed = results.map((result, index) => ({ ...result, index }));
+    const sorted = indexed.sort((a, b) => {
+        const keyA = `${a.legacyClassification}|${a.newClassification}`;
+        const keyB = `${b.legacyClassification}|${b.newClassification}`;
+        if (keyA !== keyB)
+            return keyA < keyB ? -1 : 1;
+        return a.index - b.index;
+    });
+    const mismatches = sorted.filter((row) => !row.match);
+    const lines = [
+        "## Admission Shadow Diff",
+        `${sorted.length} comparisons, ${mismatches.length} mismatches`,
+        ...sorted.map((row) => `- ${row.legacyClassification} -> ${row.newClassification}: legacy=${row.legacyVerdict} new=${row.newVerdict}${row.match ? " match" : " MISMATCH"}`),
+    ];
+    return lines.join("\n");
+}

package/dist/workflows/dag/frontend-writer-status.js

@@ -0,0 +1,256 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+/**
+ * M4: fact-derived frontend writer status + bounded in-node micro-loop.
+ *
+ * `frontend-implement-pi` derives its implementation status from mechanical
+ * facts (write-tool events, run delta, cumulative diff, write guard, requirement
+ * coverage, focused-check failures) instead of parsing the
+ * `IMPLEMENTATION_OUTCOME:` first line. The legacy `implementation-outcome-v1`
+ * protocol (backend/README/module writers + `frontend-repair-pi`) is untouched.
+ *
+ * Everything here is either a pure function (deterministically testable) or an
+ * IO collector that is only reached through a dynamic import from the Pi
+ * executor, avoiding an executor↔workflows static cycle.
+ */
+/**
+ * Write/edit-style tool names emitted by DAG writer customTools. Kept in sync
+ * with the `SDK_WRITE_TOOL_NAMES` set in pi-sdk-executor.ts so the persisted
+ * session-event count and the in-memory writeToolCallCount agree.
+ */
+export const FRONTEND_WRITE_TOOL_NAMES = new Set([
+    "edit",
+    "write",
+    "str_replace_editor",
+]);
+/**
+ * AC-001/AC-003: derive the writer status from mechanical facts only. The
+ * first-line text is never consulted. Ordering:
+ *  1. write-guard violation → blocked
+ *  2. focused-check failure → needs-repair (including trace preflight gaps)
+ *  3. non-empty diff → changed (diff is the mechanical fact source)
+ *  4. empty diff + runtime already-satisfied evidence → already-satisfied
+ *  5. empty diff, zero writes, zero diff → blocked (no progress)
+ *  6. otherwise → empty-diff (fail-closed)
+ */
+export function deriveFrontendWriterStatus(facts) {
+    if (!facts.writeGuardOk) {
+        return {
+            status: "blocked",
+            reason: `write guard violations: ${facts.writeGuardViolations.join(", ") || "unknown"}`,
+        };
+    }
+    if (facts.focusedCheckFailures.length > 0) {
+        const failures = facts.focusedCheckFailures
+            .map((failure) => failure.targetId
+            ? `${failure.targetId}: ${failure.detail}`
+            : failure.detail)
+            .join("; ");
+        return {
+            status: "needs-repair",
+            reason: `focused checks require repair: ${failures}`,
+        };
+    }
+    if (facts.changedFiles.length > 0) {
+        return {
+            status: "changed",
+            reason: `non-empty run-attributed diff (${facts.changedFiles.length} file${facts.changedFiles.length === 1 ? "" : "s"})`,
+        };
+    }
+    if (facts.alreadySatisfiedEvidence) {
+        return {
+            status: "already-satisfied",
+            reason: `empty diff with runtime already-satisfied evidence (${facts.alreadySatisfiedEvidence.requirementTargets.length} target${facts.alreadySatisfiedEvidence.requirementTargets.length === 1 ? "" : "s"})`,
+        };
+    }
+    if (facts.writeToolEvents === 0 && facts.changedFiles.length === 0) {
+        return {
+            status: "blocked",
+            reason: "zero write-tool events and zero diff: no implementation progress",
+        };
+    }
+    return {
+        status: "empty-diff",
+        reason: "empty diff without runtime already-satisfied evidence (fail-closed)",
+    };
+}
+/**
+ * Deterministic failure fingerprint over the normalized failure signature:
+ * category + focused-check failures (target + detail) + guard status. Used for
+ * repeated-failure deduplication inside the bounded micro-loop.
+ */
+export function computeFailureFingerprint(facts) {
+    const signature = normalizeFailureSignature(facts);
+    return createHash("sha256").update(signature).digest("hex");
+}
+function normalizeFailureSignature(facts) {
+    const parts = [];
+    if (!facts.writeGuardOk) {
+        parts.push("write-guard");
+    }
+    for (const failure of facts.focusedCheckFailures) {
+        parts.push(`${failure.category}:${failure.targetId ?? ""}:${failure.detail}`);
+    }
+    if (facts.changedFiles.length === 0 && facts.writeToolEvents === 0) {
+        parts.push("no-progress");
+    }
+    return parts.sort().join("\n");
+}
+export const DEFAULT_FRONTEND_MICRO_LOOP_BUDGET = {
+    maxFocusedCheckRounds: 3,
+    maxWriteAttempts: 5,
+    maxWallTimeMs: 15 * 60 * 1000,
+    maxTokens: 200_000,
+    maxRepeatedFingerprints: 2,
+};
+/**
+ * Pure micro-loop continuation gate. Deterministic: same budget + history +
+ * timestamps always yield the same decision. The caller (executor) drives the
+ * loop by re-checking this function after each focused-check round.
+ */
+export function evaluateMicroLoopContinuation(budget, history, startWallTimeMs, nowWallTimeMs) {
+    const rounds = history.length;
+    const last = history[rounds - 1];
+    if (last) {
+        const resolved = (last.status === "changed" &&
+            last.writeGuardOk &&
+            last.focusedCheckFailures.length === 0) ||
+            last.status === "already-satisfied" ||
+            last.status === "blocked";
+        if (resolved) {
+            return { continue: false, reason: "status-resolved" };
+        }
+        if (last.writeAttempts >= budget.maxWriteAttempts) {
+            return { continue: false, reason: "budget-write-attempts" };
+        }
+        if (last.tokensUsed >= budget.maxTokens) {
+            return { continue: false, reason: "budget-tokens" };
+        }
+        if (nowWallTimeMs - startWallTimeMs >= budget.maxWallTimeMs) {
+            return { continue: false, reason: "budget-wall-time" };
+        }
+        const repeatCount = history.filter((round) => round.fingerprint === last.fingerprint).length;
+        if (repeatCount >= budget.maxRepeatedFingerprints) {
+            return { continue: false, reason: "budget-repeated-fingerprint" };
+        }
+    }
+    if (rounds >= budget.maxFocusedCheckRounds) {
+        return { continue: false, reason: "budget-focused-check-rounds" };
+    }
+    return { continue: true };
+}
+/**
+ * Build a deterministic per-round checkpoint payload. Persistence stays with the
+ * caller (executor writes `runDir/<nodeId>/` only, never root `artifacts/**`).
+ */
+export function buildFrontendMicroLoopCheckpoint(input) {
+    return {
+        schemaVersion: 1,
+        nodeId: input.nodeId,
+        round: input.round,
+        status: deriveFrontendWriterStatus(input.facts).status,
+        fingerprint: computeFailureFingerprint(input.facts),
+        changedFiles: [...input.facts.changedFiles].sort(),
+        focusedCheckFailures: input.facts.focusedCheckFailures.map((failure) => ({
+            ...failure,
+        })),
+        writeGuardOk: input.facts.writeGuardOk,
+        recordedAt: input.recordedAt,
+        wallTimeMs: input.facts.wallTimeMs,
+        tokensUsed: input.facts.tokensUsed,
+        writeAttempts: input.facts.writeAttempts,
+    };
+}
+/**
+ * Shadow comparison between the fact-derived status and the legacy
+ * `IMPLEMENTATION_OUTCOME:` first-line parse. Never used to decide ok/fail —
+ * only persisted for the M4 shadow evaluation.
+ */
+export function compareFactStatusToLegacyOutcome(factStatus, legacyOutcome) {
+    const factVerdict = factStatus === "changed" || factStatus === "already-satisfied"
+        ? "ok"
+        : "fail";
+    const legacyVerdict = legacyOutcome === "changed" || legacyOutcome === "already-satisfied"
+        ? "ok"
+        : "fail";
+    return {
+        factStatus,
+        legacyOutcome,
+        factVerdict,
+        legacyVerdict,
+        match: factVerdict === legacyVerdict,
+    };
+}
+/**
+ * Pure session-event scanner: count write-tool events from the persisted
+ * session-events.jsonl content. Fail-closed: an unparseable line never counts
+ * as a write, so a corrupt/empty log cannot inflate progress.
+ */
+export function countWriteToolEventsFromSessionEvents(content) {
+    let count = 0;
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_WRITE_TOOL_NAMES.has(event.toolName)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * IO collector for frontend facts. Reads only the persisted session-events
+ * file; every other fact is passed in by the executor so this stays narrow and
+ * deterministic under test (tests inject session content by writing to a temp
+ * path or call the pure scanner directly).
+ */
+export async function collectFrontendWriterFacts(input) {
+    let writeToolEvents = 0;
+    try {
+        const content = await readFile(input.sessionEventsPath, "utf8");
+        writeToolEvents = countWriteToolEventsFromSessionEvents(content);
+    }
+    catch {
+        // Missing/unreadable session log → fail-closed at zero, never fail-open.
+        writeToolEvents = 0;
+    }
+    return {
+        changedFiles: [...input.changedFiles].sort(),
+        writeToolEvents,
+        writeGuardOk: input.writeGuard.ok,
+        writeGuardViolations: [...input.writeGuard.violations],
+        requirementTargets: [...new Set(input.requirementTargets)].sort(),
+        coveredRequirementIds: [...new Set(input.coveredRequirementIds)].sort(),
+        focusedCheckFailures: input.focusedCheckFailures.map((failure) => ({
+            ...failure,
+        })),
+        ...(input.alreadySatisfiedEvidence
+            ? {
+                alreadySatisfiedEvidence: {
+                    requirementTargets: [
+                        ...input.alreadySatisfiedEvidence.requirementTargets,
+                    ].sort(),
+                    proofSha256: input.alreadySatisfiedEvidence.proofSha256,
+                },
+            }
+            : {}),
+        tokensUsed: input.tokensUsed ?? 0,
+        wallTimeMs: input.wallTimeMs ?? 0,
+        rounds: input.rounds ?? 1,
+        writeAttempts: input.writeAttempts ?? 1,
+        ...(input.firstLineText !== undefined
+            ? { firstLineText: input.firstLineText }
+            : {}),
+    };
+}