@tea-agent/loop-agent 0.44.0-next.7 → 0.44.0-next.9

package/dist/executors/dag-pi/tools/review-terminal-tools.js

@@ -0,0 +1,166 @@
+/** DAG Pi review terminal 工具工厂：M5 committed typed review 终审工具，禁止反向依赖执行器入口。 */
+import { createFrontendReviewScopeProtocol } from "../../../workflows/dag/frontend-review-scopes.js";
+import { createDurableFrontendTools } from "../../../workflows/dag/frontend-durable-tools.js";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+/**
+ * M5: build the two committed typed review terminal tools (approve_review /
+ * request_review_changes). Each tool validates its parameters with the review
+ * fact zod schemas, stages + adopts a terminal fact into the typed event
+ * store, and returns a structured receipt. Terminal conflicts (a second
+ * terminal commit) are caught inside execute and returned as an error receipt
+ * rather than crashing the node.
+ */
+export async function createFrontendReviewTerminalTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { approveReviewFactSchema, readCommittedEvents, requestReviewChangesFactSchema, reviewFindingSchema, writeTypedEventStoreJsonl, } = await import("../../../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../../../workflows/dag/frontend-typed-event-transaction.js");
+    let store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.Enum({ Critical: "Critical", Important: "Important", Minor: "Minor", Info: "Info" }),
+        file: Type.Optional(Type.String({ minLength: 1 })),
+        line: Type.Optional(Type.Integer({ minimum: 1 })),
+        issue: Type.String({ minLength: 1 }),
+        requiredChange: Type.Optional(Type.String({ minLength: 1 })),
+        repairAssertions: Type.Optional(Type.Unknown()),
+    }, { additionalProperties: false });
+    const scopeProtocol = createFrontendReviewScopeProtocol({ phase: "review", inventory: input.inventory, getStore: () => store, attemptId });
+    const savedFindings = () => [...new Map(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "review-finding").map(r => [r.fact.id, r.fact.finding])).values()];
+    const allFindings = (direct) => [...new Map([...savedFindings(), ...(Array.isArray(direct) ? direct : [])].map(finding => [JSON.stringify(finding), finding])).values()];
+    const recordFindingTool = defineTool({
+        name: "record_review_finding", label: "record_review_finding",
+        description: "Save one finding with a stable id. Submit findings incrementally, then finalize without repeating the findings array. Saved blocking findings cannot be omitted from approval; correct a finding explicitly with replace:true.",
+        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema }, { additionalProperties: false }),
+        async execute(_callId, params) {
+            try {
+                const previous = readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "review-finding" && r.fact.id === params.id).at(-1);
+                const scopeIds = scopeProtocol.findingScopeIds(previous?.fact.scopeIds);
+                const fact = { kind: "review-finding", id: params.id, finding: reviewFindingSchema.parse(params.finding), ...(scopeIds ? { scopeIds } : {}) };
+                const requestId = `${attemptId}:finding:${randomUUID()}`;
+                const staged = stageTypedEventFact({ store, requestId, attemptId, fact });
+                const adopted = await adoptTypedEventFact({ store, requestId, attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
+                const details = { ok: true, eventId: adopted.eventId, revision: adopted.revision };
+                return { content: [{ type: "text", text: JSON.stringify(details) }], details };
+            }
+            catch (error) {
+                const code = error.code ?? "FRONTEND_INPUT_SCOPE_VIOLATION";
+                const details = { ok: false, code, error: error instanceof Error ? error.message : String(error) };
+                return { content: [{ type: "text", text: JSON.stringify(details) }], details };
+            }
+        },
+    });
+    const approveParameters = Type.Object({
+        findings: Type.Optional(Type.Array(findingSchema, {
+            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
+        })),
+    }, { additionalProperties: false });
+    const requestParameters = Type.Object({
+        issueCategory: Type.Enum({
+            "implementation-mismatch": "implementation-mismatch",
+            "approved-design-defect": "approved-design-defect",
+            "target-surface-defect": "target-surface-defect",
+            "contract-requirement-gap": "contract-requirement-gap",
+            "unknown": "unknown",
+        }, { description: "Typed issue category (five-value enum)" }),
+        evidenceRefs: Type.Array(Type.String({ minLength: 1 }), {
+            description: "Evidence refs (paths or artifact ids); at least one", minItems: 1,
+        }),
+        findings: Type.Optional(Type.Array(findingSchema, {
+            description: "At least one finding", minItems: 1,
+        })),
+    }, { additionalProperties: false });
+    async function adoptReviewFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            scopeProtocol.assertComplete();
+            const parsed = kind === "approve_review"
+                ? approveReviewFactSchema.parse(fact)
+                : requestReviewChangesFactSchema.parse(fact);
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+            });
+            const adopted = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: true,
+                            kind,
+                            eventId: adopted.eventId,
+                            revision: adopted.revision,
+                        }),
+                    },
+                ],
+                details: {
+                    ok: true,
+                    kind,
+                    eventId: adopted.eventId,
+                    revision: adopted.revision,
+                },
+            };
+        }
+        catch (error) {
+            const code = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, kind, code, error: message }),
+                    },
+                ],
+                details: { ok: false, kind, code, error: message },
+            };
+        }
+    }
+    const approveReviewTool = defineTool({
+        name: "approve_review",
+        label: "approve_review",
+        description: "Commit the authoritative approve_review terminal fact. Use only when the implementation passes review with no Critical/Important findings.",
+        promptSnippet: "Commit the authoritative approve_review terminal verdict (no Critical/Important findings).",
+        parameters: approveParameters,
+        async execute(_toolCallId, params) {
+            return adoptReviewFact("approve_review", {
+                kind: "approve_review",
+                verdict: "approve_review",
+                findings: allFindings(params?.findings),
+            });
+        },
+    });
+    const requestReviewChangesTool = defineTool({
+        name: "request_review_changes",
+        label: "request_review_changes",
+        description: "Commit the authoritative request_review_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+        promptSnippet: "Commit the authoritative request_review_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
+        parameters: requestParameters,
+        async execute(_toolCallId, params) {
+            return adoptReviewFact("request_review_changes", {
+                kind: "request_review_changes",
+                verdict: "request_review_changes",
+                issueCategory: params?.issueCategory,
+                evidenceRefs: params?.evidenceRefs,
+                findings: allFindings(params?.findings),
+            });
+        },
+    });
+    const durable = await createDurableFrontendTools({
+        file: path.join(input.runDir, input.nodeId, "review-typed-facts.jsonl"), attemptId, store: input.store,
+        binding: { inputDigest: input.inputDigest, scopeDigest: input.inventory?.digest }, setWorkingStore: next => { store = next; }, tools: [...scopeProtocol.customTools, recordFindingTool, approveReviewTool, requestReviewChangesTool], validateRestored: async () => { await input.inventory?.validate(); },
+    });
+    return { ...durable, scopeProtocol };
+}

package/dist/executors/dag-pi/tools/scout-evidence-tools.js

@@ -0,0 +1,270 @@
+/** DAG Pi scout evidence 工具工厂：origin=scout 增量证据工具，禁止反向依赖执行器入口。 */
+import { createDurableFrontendTools } from "../../../workflows/dag/frontend-durable-tools.js";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isRecordObject } from "../guards.js";
+/**
+ * A+B: `frontend-scout-pi` incremental evidence tools (origin=scout). Runtime
+ * enriches committed target-surface / design-evidence facts with hash/section/
+ * freshness from real read events; the tool itself never trusts model self-report.
+ */
+export async function createFrontendScoutEvidenceTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../../../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../../../workflows/dag/frontend-typed-event-transaction.js");
+    let store = input.store;
+    const attemptId = input.attemptId;
+    const stringArray = Type.Array(Type.String({}));
+    const optionalString = Type.Optional(Type.String({}));
+    const scoutCompleteness = Type.Union([
+        Type.Literal("complete"),
+        Type.Literal("blocked"),
+    ]);
+    const receipt = (details) => ({
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+    });
+    const sourceDeclaredPaths = (input.sourceDeclaredPaths ?? []).map((value) => value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, ""));
+    const hasSourceDeclarations = input.sourceDeclaredPaths !== undefined;
+    let activeScope;
+    const scopeIdentity = (ids) => createHash("sha256").update(JSON.stringify([...ids].sort())).digest("hex");
+    const latestScopes = () => {
+        const byRequirement = new Map();
+        for (const record of readCommittedEvents(store, attemptId))
+            if (record.fact.kind === "scout-scope" && Array.isArray(record.fact.requirementIds)) {
+                for (const id of record.fact.requirementIds)
+                    if (typeof id === "string")
+                        byRequirement.set(id, record.fact);
+            }
+        return byRequirement;
+    };
+    const isSourceDeclared = (candidate) => {
+        const normalized = candidate.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+        return sourceDeclaredPaths.some((declared) => declared === normalized || declared.startsWith(`${normalized}/`));
+    };
+    // A+B (AC-003): runtime enriches declared scout paths with hash/freshness
+    // from the real filesystem. The model's self-reported path list is never
+    // trusted for content identity; a missing file fails closed to fresh=false
+    // with a zero hash instead of inventing content.
+    const enrichScoutPathEvidence = async (paths) => {
+        if (!input.workspaceRoot)
+            return [];
+        const workspaceRoot = path.resolve(input.workspaceRoot);
+        const evidence = [];
+        for (const relative of new Set(paths)) {
+            const absolute = path.resolve(workspaceRoot, relative);
+            if (absolute !== workspaceRoot &&
+                !absolute.startsWith(`${workspaceRoot}${path.sep}`)) {
+                evidence.push({ path: relative, sha256: "0".repeat(64), fresh: false, sourceDeclared: isSourceDeclared(relative) });
+                continue;
+            }
+            try {
+                // Directories are legitimate named targets (greenfield smoke: the
+                // page directory exists while the files inside it are to be
+                // created). readFile on a directory throws EISDIR, which used to
+                // mark every directory path fresh=false and structurally fail the
+                // freshness gate for create-new surfaces. stat() first: a directory
+                // counts as fresh existence evidence; its content hash is a stable
+                // directory marker since there is no single file content to hash.
+                const info = await stat(absolute);
+                if (info.isDirectory()) {
+                    evidence.push({
+                        path: relative,
+                        sha256: createHash("sha256").update(`directory:${relative}`).digest("hex"),
+                        fresh: true,
+                        sourceDeclared: isSourceDeclared(relative),
+                    });
+                    continue;
+                }
+                const bytes = await readFile(absolute);
+                evidence.push({
+                    path: relative,
+                    sha256: createHash("sha256").update(bytes).digest("hex"),
+                    fresh: true,
+                    sourceDeclared: isSourceDeclared(relative),
+                });
+            }
+            catch {
+                evidence.push({ path: relative, sha256: "0".repeat(64), fresh: false, sourceDeclared: isSourceDeclared(relative) });
+            }
+        }
+        return evidence;
+    };
+    async function adoptScoutFact(kind, fact) {
+        try {
+            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+            });
+            const committed = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                ok: true,
+                kind,
+                eventId: committed.eventId,
+                revision: committed.revision,
+                error: "",
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                kind,
+                code: error?.code,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    const recordTargetSurfaceTool = defineTool({
+        name: "record_target_surface",
+        label: "record_target_surface",
+        description: "Commit an origin=scout target-surface fact with complete/blocked discovery status. A complete surface needs a proven target path and no unresolved paths; blocked surfaces name the unresolved paths instead of guessing. Example: {\"completeness\": \"complete\", \"entrypoint\": \"<file>\", \"implementationPaths\": [\"<dir or file>\"], \"testPaths\": [\"<file>\"], \"allowedPathConflicts\": [], \"unresolvedPaths\": []}",
+        promptSnippet: "Commit an origin=scout target-surface fact.",
+        parameters: Type.Object({
+            scopeId: Type.Optional(Type.String({ minLength: 1 })),
+            completeness: scoutCompleteness,
+            entrypoint: optionalString,
+            routeOrMount: optionalString,
+            implementationPaths: stringArray,
+            proposedPaths: Type.Optional(stringArray),
+            testPaths: stringArray,
+            dataSource: optionalString,
+            allowedPathConflicts: stringArray,
+            unresolvedPaths: stringArray,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            if (input.requirementIds && (!activeScope?.length || params.scopeId !== scopeIdentity(activeScope)))
+                return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "Use exactly the runtime Scout scopeId; discovery may complete only the supplied obligations" });
+            const implementationPaths = params?.implementationPaths ?? [];
+            const proposedPaths = params?.proposedPaths ?? [];
+            const testPaths = params?.testPaths ?? [];
+            const pathEvidence = await enrichScoutPathEvidence([
+                ...(params?.entrypoint ? [params.entrypoint] : []),
+                ...implementationPaths,
+                ...testPaths,
+            ]);
+            for (const proposedPath of proposedPaths) {
+                if (!pathEvidence.some((item) => item.path === proposedPath)) {
+                    pathEvidence.push({ path: proposedPath, sha256: "0".repeat(64), fresh: false, sourceDeclared: false, proposed: true });
+                }
+            }
+            const surface = {
+                kind: "target-surface",
+                origin: "scout",
+                completeness: params?.completeness ?? "blocked",
+                entrypoint: params?.entrypoint ?? "",
+                routeOrMount: params?.routeOrMount ?? "",
+                implementationPaths,
+                ...(proposedPaths.length > 0 ? { proposedPaths } : {}),
+                testPaths,
+                dataSource: params?.dataSource ?? "",
+                allowedPathConflicts: params?.allowedPathConflicts ?? [],
+                unresolvedPaths: params?.unresolvedPaths ?? [],
+                ...(hasSourceDeclarations ? { sourceDeclaredPaths } : {}),
+                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
+            };
+            if (activeScope) {
+                const { readCompleteScoutTargetSurface } = await import("../../../workflows/dag/frontend-committed-facts.js");
+                if (surface.completeness === "complete") {
+                    const check = readCompleteScoutTargetSurface([{ phase: "committed", fact: surface }]);
+                    if (!check.ok)
+                        return receipt({ ok: false, code: "SCOUT_SCOPE_INCOMPLETE", error: check.reason });
+                }
+                const saved = await adoptScoutFact("scout-scope", { kind: "scout-scope", origin: "scout", id: params.scopeId, requirementIds: activeScope, surface });
+                if (!saved.ok)
+                    return receipt(saved);
+                const current = latestScopes();
+                if (input.requirementIds?.every(id => current.get(id)?.surface?.completeness === "complete")) {
+                    const surfaces = [...new Set(input.requirementIds.map(id => current.get(id)))].map(f => f.surface);
+                    const union = (key) => [...new Set(surfaces.flatMap(s => Array.isArray(s[key]) ? s[key] : []))];
+                    const entries = [...new Set(surfaces.map(s => String(s.entrypoint ?? "")).filter(Boolean))];
+                    return receipt(await adoptScoutFact("target-surface", { kind: "target-surface", origin: "scout", completeness: "complete", entrypoint: entries[0] ?? "", implementationPaths: [...new Set([...entries, ...union("implementationPaths")])], proposedPaths: union("proposedPaths"), testPaths: union("testPaths"), allowedPathConflicts: union("allowedPathConflicts"), unresolvedPaths: union("unresolvedPaths"), routeOrMount: [...new Set(surfaces.map(s => s.routeOrMount).filter(Boolean))].join("\n"), dataSource: [...new Set(surfaces.map(s => s.dataSource).filter(Boolean))].join("\n"), pathEvidence: surfaces.flatMap(s => s.pathEvidence ?? []), ...(hasSourceDeclarations ? { sourceDeclaredPaths } : {}) }));
+                }
+                return receipt(saved);
+            }
+            const result = await adoptScoutFact("target-surface", surface);
+            return receipt(result);
+        },
+    });
+    const recordDesignEvidenceTool = defineTool({
+        name: "record_design_evidence",
+        label: "record_design_evidence",
+        description: "Commit an origin=scout design-evidence fact (source, paths, conflicts). Example: {\"source\": \"<source>\", \"paths\": [\"<file>\"], \"conflicts\": []}",
+        promptSnippet: "Commit an origin=scout design-evidence fact.",
+        parameters: Type.Object({ source: Type.String({}), paths: stringArray, conflicts: stringArray }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const paths = params?.paths ?? [];
+            const pathEvidence = await enrichScoutPathEvidence(paths);
+            const result = await adoptScoutFact("design-evidence", {
+                kind: "design-evidence",
+                origin: "scout",
+                source: params?.source ?? "",
+                paths,
+                conflicts: params?.conflicts ?? [],
+                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
+            });
+            return receipt(result);
+        },
+    });
+    const durable = await createDurableFrontendTools({
+        file: path.join(input.runDir, input.nodeId, "scout-typed-facts.jsonl"), attemptId, store: input.store,
+        setWorkingStore: next => { store = next; }, binding: { requirementIds: input.requirementIds, sourceDeclaredPaths: input.sourceDeclaredPaths, sourceDigest: input.sourceDigest, workspaceRoot: input.workspaceRoot },
+        tools: [recordTargetSurfaceTool, recordDesignEvidenceTool],
+        validateRestored: async (records) => {
+            if (!input.workspaceRoot)
+                return;
+            for (const record of records) {
+                const evidence = record.fact.kind === "scout-scope" ? record.fact.surface?.pathEvidence : record.fact.pathEvidence;
+                if (!Array.isArray(evidence))
+                    continue;
+                for (const previous of evidence) {
+                    if (!isRecordObject(previous) || typeof previous.path !== "string")
+                        throw Error("scout path evidence is malformed");
+                    const current = (await enrichScoutPathEvidence([previous.path]))[0];
+                    if (!current || current.sha256 !== previous.sha256 || current.fresh !== previous.fresh)
+                        throw Error(`scout evidence drift: ${previous.path}; refresh Scout before reusing facts`);
+                }
+            }
+        },
+    });
+    return {
+        ...durable,
+        adoptCommittedFacts: async (records) => durable.commitExternal(async () => {
+            for (const record of records) {
+                if (record.phase !== "committed")
+                    continue;
+                const fact = record.fact;
+                if (!fact || typeof fact !== "object" || Array.isArray(fact))
+                    continue;
+                const result = await adoptScoutFact(typeof fact.kind === "string"
+                    ? fact.kind
+                    : "scout-fact", fact);
+                if (!result.ok) {
+                    throw new Error(`frontend scout shard fact merge failed: ${result.error}`);
+                }
+            }
+        }),
+        setActiveScope: ids => {
+            if (!ids.length || ids.some(id => !input.requirementIds?.includes(id)))
+                throw Error("FRONTEND_INPUT_SCOPE_VIOLATION");
+            activeScope = [...new Set(ids)];
+            return scopeIdentity(activeScope);
+        },
+        completedRequirementIds: () => new Set([...latestScopes()].filter(([, fact]) => fact.surface?.completeness === "complete").map(([id]) => id)),
+        completedScopeFacts: () => [...new Set(latestScopes().values())].filter(f => f.surface?.completeness === "complete"),
+        committedFacts: () => readCommittedEvents(store, attemptId),
+    };
+}