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

package/dist/workflows/dag/observer-compose.js

@@ -0,0 +1,52 @@
+function reportError(context, observerIndex, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[dag-observer-compose] observer#${observerIndex} ${context} failed: ${message}\n`);
+}
+const HOOK_NAMES = [
+    "onRunStart",
+    "onNodeStart",
+    "onNodeOutput",
+    "onNodeFinish",
+    "onRunFinish",
+];
+/**
+ * Compose multiple `DagRunObserver`s into one. Each hook is invoked in order.
+ * A throw in a single observer's hook is reported to stderr and does not stop
+ * subsequent observers — observers are derived views and must not affect
+ * canonical DAG execution. Returns `undefined` when no observers are provided.
+ */
+export function composeDagRunObservers(observers) {
+    const active = observers.filter((observer) => Boolean(observer));
+    if (active.length === 0)
+        return undefined;
+    const observer = {
+        onRunStart: async (state) => {
+            await runHook("onRunStart", active, (obs) => obs.onRunStart?.(state));
+        },
+        onNodeStart: async (nodeId, state) => {
+            await runHook("onNodeStart", active, (obs) => obs.onNodeStart?.(nodeId, state));
+        },
+        onNodeOutput: async (nodeId, chunk, state) => {
+            await runHook("onNodeOutput", active, (obs) => obs.onNodeOutput?.(nodeId, chunk, state));
+        },
+        onNodeFinish: async (nodeId, state) => {
+            await runHook("onNodeFinish", active, (obs) => obs.onNodeFinish?.(nodeId, state));
+        },
+        onRunFinish: async (state) => {
+            await runHook("onRunFinish", active, (obs) => obs.onRunFinish?.(state));
+        },
+    };
+    return observer;
+}
+async function runHook(hookName, active, invoke) {
+    for (let i = 0; i < active.length; i += 1) {
+        try {
+            await invoke(active[i]);
+        }
+        catch (error) {
+            reportError(hookName, i, error);
+        }
+    }
+}
+// Re-exported for tests/inspection of hook coverage.
+export const COMPOSED_HOOK_NAMES = HOOK_NAMES;

package/dist/workflows/dag/output-protocol.js

@@ -0,0 +1,356 @@
+import { z } from "zod";
+import { normalizeVerdictCandidateLine } from "./dynamic-runtime/shared.js";
+/**
+ * Machine-readable output protocol for safe read-only Pi nodes.
+ *
+ */
+const firstLineEnumOutputProtocolSchema = z
+    .object({
+    type: z.literal("first-line-enum"),
+    validLines: z.array(z.string().min(1)).min(1),
+    retryOnInvalid: z.boolean().default(true),
+})
+    .strict();
+const jsonReviewVerdictOutputProtocolSchema = z
+    .object({
+    type: z.literal("json-review-verdict"),
+    retryOnInvalid: z.boolean().default(true),
+})
+    .strict();
+export const dagOutputProtocolSchema = z.discriminatedUnion("type", [
+    firstLineEnumOutputProtocolSchema,
+    jsonReviewVerdictOutputProtocolSchema,
+]);
+/** Reviewer VERDICT protocol used by reviewed/supervised DAGs. */
+export const REVIEW_VERDICT_OUTPUT_PROTOCOL = {
+    type: "first-line-enum",
+    validLines: ["VERDICT: pass", "VERDICT: request-revision"],
+    retryOnInvalid: true,
+};
+/** Structured reviewer verdict protocol used when deterministic gates parse JSON. */
+export const REVIEW_JSON_VERDICT_OUTPUT_PROTOCOL = {
+    type: "json-review-verdict",
+    retryOnInvalid: true,
+};
+const reviewFindingSchema = z
+    .object({
+    severity: z.enum(["Critical", "Important", "Minor", "Info"]),
+    file: z.string().min(1).optional(),
+    line: z.number().int().positive().optional(),
+    issue: z.string().min(1),
+    requiredChange: z.string().min(1).optional(),
+})
+    .strict();
+const reviewJsonVerdictSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    verdict: z.enum(["pass", "request-revision"]),
+    findings: z.array(reviewFindingSchema),
+    verificationAssessment: z.string().min(1).optional(),
+    uxAssessment: z.string().min(1).optional(),
+    residualRisks: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+/**
+ * Extract the first non-empty line from assistant/stdout text.
+ */
+export function firstNonEmptyLine(text) {
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+function extractUniqueReviewJson(text) {
+    const source = String(text).trim();
+    const blocks = [...source.matchAll(/```(?:json|jsonc)?\s*([\s\S]*?)\s*```/gi)].map((match) => match[1].trim());
+    const candidates = blocks.length > 0 ? blocks : [source];
+    const parsed = [];
+    for (const candidate of candidates) {
+        let cursor = 0;
+        while (cursor < candidate.length) {
+            const start = candidate.indexOf("{", cursor);
+            if (start < 0)
+                break;
+            let depth = 0;
+            let inString = false;
+            let escaped = false;
+            let end = -1;
+            for (let index = start; index < candidate.length; index += 1) {
+                const character = candidate[index];
+                if (inString) {
+                    if (escaped)
+                        escaped = false;
+                    else if (character === "\\")
+                        escaped = true;
+                    else if (character === '"')
+                        inString = false;
+                    continue;
+                }
+                if (character === '"')
+                    inString = true;
+                else if (character === "{")
+                    depth += 1;
+                else if (character === "}" && --depth === 0) {
+                    try {
+                        const value = JSON.parse(candidate.slice(start, index + 1));
+                        if (value && typeof value === "object" && !Array.isArray(value))
+                            parsed.push(value);
+                    }
+                    catch {
+                        // Keep fail-closed behavior for malformed JSON.
+                    }
+                    end = index;
+                    break;
+                }
+            }
+            if (end < 0)
+                break;
+            cursor = end + 1;
+        }
+    }
+    if (parsed.length !== 1) {
+        throw new Error(parsed.length === 0
+            ? "output must contain one valid JSON review object"
+            : "output must contain exactly one JSON review object");
+    }
+    return parsed[0];
+}
+/** Parse a JSON review verdict after extracting one unambiguous JSON object.
+ * Prose and one Markdown fence are tolerated at this boundary; ambiguity and
+ * schema/semantic violations remain fail-closed. */
+export function parseJsonReviewVerdict(text) {
+    const trimmed = String(text).trim();
+    if (!trimmed)
+        return { ok: false, reason: "missing JSON output" };
+    let parsed;
+    try {
+        parsed = extractUniqueReviewJson(trimmed);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `output JSON extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: "output must be exactly one JSON object",
+        };
+    }
+    const checked = reviewJsonVerdictSchema.safeParse(parsed);
+    if (!checked.success) {
+        return {
+            ok: false,
+            reason: `JSON review verdict schema violation: ${checked.error.issues
+                .map((issue) => `${issue.path.join(".") || "<root>"} ${issue.message}`)
+                .join("; ")}`,
+        };
+    }
+    const blockingFindings = checked.data.findings.filter((finding) => finding.severity === "Critical" || finding.severity === "Important");
+    if (checked.data.verdict === "pass" && blockingFindings.length > 0) {
+        return {
+            ok: false,
+            reason: "JSON review verdict cannot be pass when Critical or Important findings are present",
+        };
+    }
+    if (checked.data.verdict === "request-revision" &&
+        checked.data.findings.length === 0) {
+        return {
+            ok: false,
+            reason: "JSON review verdict request-revision requires at least one finding",
+        };
+    }
+    return { ok: true, verdict: checked.data.verdict };
+}
+function validateJsonReviewVerdict(text) {
+    const parsed = parseJsonReviewVerdict(text);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: parsed.reason,
+            firstNonEmptyLine: firstNonEmptyLine(text),
+        };
+    }
+    return { ok: true, verdict: parsed.verdict };
+}
+/**
+ * Validate node output against an explicit outputProtocol.
+ * Pure function — does not mutate run facts.
+ */
+export function validateOutputProtocol(protocol, text) {
+    if (protocol.type === "json-review-verdict") {
+        return validateJsonReviewVerdict(text);
+    }
+    const validLines = "validLines" in protocol ? protocol.validLines : undefined;
+    if (!validLines) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `unsupported outputProtocol.type: ${protocol.type ?? "unknown"}`,
+        };
+    }
+    const first = firstNonEmptyLine(text);
+    if (!first) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `missing first non-empty line; expected one of: ${protocol.validLines.map((l) => JSON.stringify(l)).join(" or ")}`,
+        };
+    }
+    const isReviewVerdict = protocol.validLines.length === 2 && protocol.validLines.includes("VERDICT: pass") && protocol.validLines.includes("VERDICT: request-revision");
+    // Models frequently prepend a short explanation despite the protocol
+    // instruction. Recover only when there is exactly one unambiguous protocol
+    // line; conflicting or repeated verdicts remain fail-closed.
+    const candidates = isReviewVerdict ? text
+        .split("\n")
+        .map((line) => normalizeVerdictCandidateLine(line.trim()))
+        .filter((line) => protocol.validLines.includes(line)) : [];
+    const uniqueCandidates = [...new Set(candidates)];
+    if (uniqueCandidates.length > 1) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `conflicting protocol lines found: ${uniqueCandidates.map((line) => JSON.stringify(line)).join(" and ")}`,
+            firstNonEmptyLine: first,
+        };
+    }
+    if (protocol.validLines.includes(first)) {
+        return { ok: true, matchedLine: first };
+    }
+    if (uniqueCandidates.length === 1) {
+        return { ok: true, matchedLine: uniqueCandidates[0] };
+    }
+    if (!protocol.validLines.includes(first)) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `first non-empty line ${JSON.stringify(first)} is not a valid protocol line; expected one of: ${protocol.validLines.map((l) => JSON.stringify(l)).join(" or ")}`,
+            firstNonEmptyLine: first,
+        };
+    }
+    return { ok: true, matchedLine: first };
+}
+/**
+ * Correction instruction appended on protocol-invalid retry attempts.
+ */
+export function buildProtocolRetryInstruction(protocol, reason) {
+    if (protocol.type === "json-review-verdict") {
+        return [
+            "<retry_instruction>",
+            "Previous attempt violated the structured review output protocol:",
+            reason,
+            "Return ONLY a JSON object, with no Markdown fence and no surrounding prose.",
+            'Required schema: {"schemaVersion":1,"verdict":"pass|request-revision","findings":[{"severity":"Critical|Important|Minor|Info","file":"optional path","line":1,"issue":"required","requiredChange":"optional"}],"verificationAssessment":"optional","uxAssessment":"optional","residualRisks":["optional"]}.',
+            'Rules: verdict "request-revision" requires at least one finding; verdict "pass" is invalid if any finding severity is Critical or Important.',
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    const expected = protocol.validLines
+        .map((line) => JSON.stringify(line))
+        .join(" or ");
+    return [
+        "<retry_instruction>",
+        "Previous attempt violated the output protocol:",
+        reason,
+        `Return one valid protocol line before any explanation. Expected first non-empty line: ${expected}.`,
+        "</retry_instruction>",
+    ].join("\n");
+}
+/**
+ * AC2: deterministic review-verdict normalization applied ONLY after retries
+ * are exhausted on a review verdict protocol node.
+ *
+ * The canonical review verdict protocol accepts exactly one of
+ * {@link REVIEW_VERDICT_OUTPUT_PROTOCOL}.validLines. This helper scans the
+ * FULL output (assistantText + stdout style text) for verdict lines using the
+ * same whole-line Markdown-emphasis normalization the verdict gate uses.
+ *
+ * Normalization succeeds if and only if the full output contains exactly one
+ * supported, unambiguous verdict line. It produces a normalized output whose
+ * first non-empty line is that verdict, preserving the original evidence text
+ * afterwards. It never changes the verdict value.
+ *
+ * It fails (returns ok:false) for:
+ * - no verdict line anywhere;
+ * - multiple verdict lines, even if identical (duplicated protocol ambiguity);
+ * - conflicting verdict lines;
+ * - any unsupported/illegal verdict value (e.g. `VERDICT: approve`);
+ * - malformed lines that are not a supported verdict after normalization;
+ * - natural-language approval prose without a real verdict token.
+ *
+ * This helper only operates on the canonical review verdict protocol; any
+ * other protocol is left untouched (ok:false) so decision envelopes, shell
+ * output, and structured protocols are never loosely tolerated.
+ */
+export function normalizeReviewVerdictAfterRetries(protocol, text) {
+    if (protocol.type !== "first-line-enum") {
+        return {
+            ok: false,
+            reason: "deterministic verdict normalization only applies to the canonical review verdict protocol",
+        };
+    }
+    const validLines = protocol.validLines;
+    const isReviewVerdictProtocol = Array.from(validLines).every((line, index) => line === REVIEW_VERDICT_OUTPUT_PROTOCOL.validLines[index]) &&
+        validLines.length ===
+            REVIEW_VERDICT_OUTPUT_PROTOCOL.validLines.length;
+    if (!isReviewVerdictProtocol) {
+        return {
+            ok: false,
+            reason: "deterministic verdict normalization only applies to the canonical review verdict protocol",
+        };
+    }
+    const supported = new Set(REVIEW_VERDICT_OUTPUT_PROTOCOL.validLines);
+    const candidates = [];
+    let seenIllegalVerdictPrefixedLine = false;
+    for (const rawLine of String(text).split(/\r?\n/)) {
+        const normalized = normalizeVerdictCandidateLine(rawLine);
+        if (!normalized)
+            continue;
+        // Detect any line that looks like a verdict token (VERDICT: ...) but is
+        // not a supported value, so a single valid + single illegal line cannot
+        // be silently normalized to the valid one.
+        if (/^VERDICT:/.test(normalized) && !supported.has(normalized)) {
+            seenIllegalVerdictPrefixedLine = true;
+            continue;
+        }
+        if (supported.has(normalized)) {
+            candidates.push(normalized);
+        }
+    }
+    if (seenIllegalVerdictPrefixedLine) {
+        return {
+            ok: false,
+            reason: "output contains an illegal or unsupported VERDICT value; cannot normalize",
+        };
+    }
+    if (candidates.length === 0) {
+        return {
+            ok: false,
+            reason: "no supported verdict line found in full output; cannot normalize",
+        };
+    }
+    const unique = new Set(candidates);
+    if (unique.size !== 1 || candidates.length !== 1) {
+        return {
+            ok: false,
+            reason: "output contains multiple or conflicting verdict lines; normalization requires exactly one supported verdict",
+        };
+    }
+    const verdictLine = candidates[0];
+    const preservedEvidence = String(text)
+        .split(/\r?\n/)
+        .filter((line) => {
+        const normalized = normalizeVerdictCandidateLine(line);
+        return !normalized || !supported.has(normalized);
+    })
+        .join("\n")
+        .trim();
+    const normalizedOutput = preservedEvidence
+        ? `${verdictLine}\n${preservedEvidence}`
+        : verdictLine;
+    return { ok: true, verdictLine, normalizedOutput };
+}