@tea-agent/loop-agent 0.44.0-next.6 → 0.44.0-next.8

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

@@ -0,0 +1,156 @@
+/** DAG Pi design terminal 工具工厂：M8 committed typed design 终审工具，禁止反向依赖执行器入口。 */
+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";
+/**
+ * M8: build the two committed typed design terminal tools (approve_design /
+ * request_design_changes). Each tool validates its parameters with the design
+ * fact zod schemas, stages + adopts a terminal fact into the typed event
+ * store, and returns a structured receipt. Terminal conflicts are caught
+ * inside execute and returned as an error receipt rather than crashing the
+ * node.
+ */
+export async function createFrontendDesignTerminalTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { approveDesignFactSchema, readCommittedEvents, requestDesignChangesFactSchema, 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 })),
+    }, { additionalProperties: false });
+    const scopeProtocol = createFrontendReviewScopeProtocol({ phase: "design", inventory: input.inventory, getStore: () => store, attemptId });
+    const savedFindings = () => [...new Map(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "design-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_design_finding", label: "record_design_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) {
+            const fact = { kind: "design-finding", id: params.id, finding: params.finding };
+            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 };
+        },
+    });
+    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 adoptDesignFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            scopeProtocol.assertComplete();
+            const parsed = kind === "approve_design"
+                ? approveDesignFactSchema.parse(fact)
+                : requestDesignChangesFactSchema.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 approveDesignTool = defineTool({
+        name: "approve_design",
+        label: "approve_design",
+        description: "Commit the authoritative approve_design terminal fact. Use only when the plan passes design review with no Critical/Important findings.",
+        promptSnippet: "Commit the authoritative approve_design terminal verdict (no Critical/Important findings).",
+        parameters: approveParameters,
+        async execute(_toolCallId, params) {
+            return adoptDesignFact("approve_design", {
+                kind: "approve_design",
+                verdict: "approve_design",
+                findings: allFindings(params?.findings),
+            });
+        },
+    });
+    const requestDesignChangesTool = defineTool({
+        name: "request_design_changes",
+        label: "request_design_changes",
+        description: "Commit the authoritative request_design_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+        promptSnippet: "Commit the authoritative request_design_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
+        parameters: requestParameters,
+        async execute(_toolCallId, params) {
+            return adoptDesignFact("request_design_changes", {
+                kind: "request_design_changes",
+                verdict: "request_design_changes",
+                issueCategory: params?.issueCategory,
+                evidenceRefs: params?.evidenceRefs,
+                findings: allFindings(params?.findings),
+            });
+        },
+    });
+    const durable = await createDurableFrontendTools({
+        file: path.join(input.runDir, input.nodeId, "design-typed-facts.jsonl"), attemptId, store: input.store,
+        binding: { inputDigest: input.inputDigest, scopeDigest: input.inventory?.digest }, setWorkingStore: next => { store = next; }, tools: [...scopeProtocol.customTools, recordFindingTool, approveDesignTool, requestDesignChangesTool], validateRestored: async () => { await input.inventory?.validate(); },
+    });
+    return { ...durable, scopeProtocol };
+}