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

package/dist/workflows/dag/decision-envelope.js

@@ -0,0 +1,557 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { summarizeDecisionEnvelopeEvidenceCompleteness, } from "./decision-evidence.js";
+import { locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+export const DECISION_ENVELOPE_FENCE_INFO = "DECISION_ENVELOPE_JSON";
+const decisionGateTypeSchema = z.enum([
+    "plan-gate",
+    "side-effect-gate",
+    "acceptance-gate",
+    "closeout-gate",
+]);
+const decisionScopeSchema = z.enum([
+    "node",
+    "rank",
+    "dag-run",
+    "task",
+    "repo",
+]);
+const decisionValueSchema = z.enum([
+    "auto-approve",
+    "approve-with-constraints",
+    "request-revision",
+    "run-more-verification",
+    "split-followup",
+    "reject",
+    "escalate-to-human",
+    "pause-wait-external",
+]);
+const nextActionSchema = z.enum([
+    "continue",
+    "rerun-implement",
+    "rerun-verify",
+    "run-targeted-check",
+    "split-followup",
+    "pause-and-ask",
+    "abort",
+]);
+const riskLevelSchema = z.enum(["low", "medium", "high", "critical"]);
+const evidenceStatusSchema = z.enum([
+    "verified",
+    "partial",
+    "self-reported",
+    "conflicting",
+    "missing",
+]);
+const humanEscalationOptionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    risk: z.string().min(1),
+    reason: z.string().min(1),
+});
+const humanEscalationSchema = z.object({
+    question: z.string().min(1),
+    recommendedOption: z.string().min(1),
+    options: z.array(humanEscalationOptionSchema).min(1),
+});
+const evidenceItemSchema = z.object({
+    path: z.string().min(1),
+    kind: z.string().min(1),
+    status: evidenceStatusSchema,
+    summary: z.string().min(1),
+});
+export const decisionEnvelopeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    gateType: decisionGateTypeSchema,
+    decisionScope: decisionScopeSchema,
+    decision: decisionValueSchema,
+    confidence: z.number().min(0).max(1),
+    riskLevel: riskLevelSchema,
+    requiresHuman: z.boolean(),
+    nextAction: nextActionSchema,
+    policyVersion: z.string().min(1),
+    policyChecks: z.object({
+        mustEscalateFlags: z.array(z.string().min(1)),
+        evidenceComplete: z.boolean(),
+        allowedAutoApprove: z.boolean(),
+    }),
+    rationale: z.array(z.string().min(1)).min(1),
+    evidence: z.array(evidenceItemSchema).min(1),
+    blockingFindings: z.array(z.string().min(1)),
+    requiredRevisions: z.array(z.string().min(1)),
+    riskFlags: z.array(z.string().min(1)),
+    humanEscalation: humanEscalationSchema.nullable(),
+    audit: z
+        .object({
+        runId: z.string().min(1),
+        nodeId: z.string().min(1),
+        model: z.string().min(1),
+        sourceHash: z.string().optional(),
+    })
+        .passthrough(),
+})
+    .strict();
+/**
+ * Canonical schema-valid and semantic-valid payload embedded in supervised
+ * Decision Gate prompts. Keep this example minimal and verify it through the
+ * real parser so the prompt contract cannot silently drift from runtime rules.
+ */
+export const DECISION_ENVELOPE_CANONICAL_EXAMPLE = {
+    schemaVersion: 1,
+    gateType: "acceptance-gate",
+    decisionScope: "dag-run",
+    decision: "auto-approve",
+    confidence: 0.9,
+    riskLevel: "low",
+    requiresHuman: false,
+    nextAction: "continue",
+    policyVersion: "agent-dag-decision-gate-v1",
+    policyChecks: {
+        mustEscalateFlags: [],
+        evidenceComplete: true,
+        allowedAutoApprove: true,
+    },
+    rationale: ["Deterministic verification passed."],
+    evidence: [
+        {
+            path: "docs/templates/agent-dag-decision-envelope.schema.json",
+            kind: "schema",
+            status: "verified",
+            summary: "Schema and deterministic verification evidence were reviewed.",
+        },
+    ],
+    blockingFindings: [],
+    requiredRevisions: [],
+    riskFlags: [],
+    humanEscalation: null,
+    audit: {
+        runId: "<current-run-id>",
+        nodeId: "decision-pi",
+        model: "<current-node-model>",
+    },
+};
+/** Build the strict structured-output contract injected into decision-pi. */
+export function buildDecisionEnvelopePromptContract() {
+    return [
+        "Return exactly one Decision Envelope using the current strict schema.",
+        "Use only these decision values: auto-approve, approve-with-constraints, request-revision, run-more-verification, split-followup, reject, escalate-to-human, pause-wait-external.",
+        "Use only these nextAction values: continue, rerun-implement, rerun-verify, run-targeted-check, split-followup, pause-and-ask, abort.",
+        "When deterministic verification and review pass with no blocking findings, use decision=auto-approve, requiresHuman=false, nextAction=continue.",
+        "Replace audit.runId and audit.model placeholders with the current DAG run id and current node model. Keep audit.nodeId equal to the current Decision Gate node id.",
+        "Do not emit legacy root fields taskId, gate, verdict, summary, invariants, or findings. Do not use invented decision values such as proceed-to-closeout, accept, or proceed. Unknown fields and enum values fail validation.",
+        "The authoritative schema is docs/templates/agent-dag-decision-envelope.schema.json.",
+        "Output this exact fenced shape with a schema-valid payload:",
+        `\`\`\`${DECISION_ENVELOPE_FENCE_INFO}`,
+        JSON.stringify(DECISION_ENVELOPE_CANONICAL_EXAMPLE, null, 2),
+        "```",
+    ].join("\n");
+}
+const DECISION_ENVELOPE_FENCE_RE = /(?<!`)(`{3,})DECISION_ENVELOPE_JSON[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*(?=\r?\n|$)/g;
+export function extractDecisionEnvelopeFencedBlocks(text) {
+    const blocks = [];
+    if (!text)
+        return blocks;
+    const re = new RegExp(DECISION_ENVELOPE_FENCE_RE.source, DECISION_ENVELOPE_FENCE_RE.flags);
+    for (const match of text.matchAll(re)) {
+        const body = match[2]?.trim();
+        if (body)
+            blocks.push(body);
+    }
+    return blocks;
+}
+export function parseDecisionEnvelopeJson(rawJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [
+                `malformed JSON in ${DECISION_ENVELOPE_FENCE_INFO} block: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    const schemaResult = decisionEnvelopeSchema.safeParse(parsed);
+    if (!schemaResult.success) {
+        return {
+            ok: false,
+            errors: schemaResult.error.issues.map((issue) => `schema: ${issue.path.join(".") || "(root)"}: ${issue.message}`),
+        };
+    }
+    const semanticErrors = validateDecisionEnvelopeSemantics(schemaResult.data);
+    if (semanticErrors.length > 0) {
+        return { ok: false, errors: semanticErrors };
+    }
+    return { ok: true, envelope: schemaResult.data };
+}
+export function validateDecisionEnvelopeSemantics(envelope) {
+    const errors = [];
+    if ((envelope.decision === "auto-approve" ||
+        envelope.decision === "approve-with-constraints") &&
+        envelope.requiresHuman) {
+        errors.push(`${envelope.decision} must not set requiresHuman=true`);
+    }
+    if ((envelope.decision === "escalate-to-human" ||
+        envelope.decision === "pause-wait-external" ||
+        envelope.nextAction === "pause-and-ask") &&
+        (!envelope.requiresHuman || envelope.humanEscalation === null)) {
+        errors.push("escalate-to-human, pause-wait-external, or nextAction=pause-and-ask requires requiresHuman=true and humanEscalation object");
+    }
+    if (envelope.requiresHuman && envelope.nextAction !== "pause-and-ask") {
+        errors.push("requiresHuman=true requires nextAction=pause-and-ask");
+    }
+    if (!envelope.requiresHuman && envelope.humanEscalation !== null) {
+        errors.push("requiresHuman=false must not include a blocking humanEscalation question");
+    }
+    if (envelope.humanEscalation) {
+        const optionIds = new Set(envelope.humanEscalation.options.map((option) => option.id));
+        if (!optionIds.has(envelope.humanEscalation.recommendedOption)) {
+            errors.push("humanEscalation.recommendedOption must match one of options[].id");
+        }
+    }
+    if ((envelope.riskLevel === "high" || envelope.riskLevel === "critical") &&
+        envelope.decision === "auto-approve") {
+        const verifiedEvidence = envelope.evidence.filter((item) => item.status === "verified");
+        if (!envelope.policyChecks.allowedAutoApprove ||
+            verifiedEvidence.length === 0) {
+            errors.push("high/critical risk must not auto-approve unless policyChecks.allowedAutoApprove is true and verified evidence exists");
+        }
+    }
+    return errors;
+}
+export function parseDecisionEnvelopeFromText(text, source) {
+    const blocks = extractDecisionEnvelopeFencedBlocks(text);
+    if (blocks.length === 0) {
+        return {
+            ok: false,
+            errors: [`missing ${DECISION_ENVELOPE_FENCE_INFO} fenced block`],
+            source,
+        };
+    }
+    if (blocks.length > 1) {
+        return {
+            ok: false,
+            errors: [
+                `expected exactly one ${DECISION_ENVELOPE_FENCE_INFO} fenced block, found ${blocks.length}`,
+            ],
+            source,
+        };
+    }
+    const parsed = parseDecisionEnvelopeJson(blocks[0]);
+    if (!parsed.ok) {
+        return { ok: false, errors: parsed.errors, source };
+    }
+    return { ok: true, envelope: parsed.envelope, source };
+}
+export async function readOptionalTextFile(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function parseDecisionEnvelopeForNode(input) {
+    const primary = input.assistantText?.trim()
+        ? parseDecisionEnvelopeFromText(input.assistantText, "assistantText")
+        : undefined;
+    if (primary?.ok) {
+        return primary;
+    }
+    if (primary &&
+        primary.errors.some((error) => error.startsWith("expected exactly one"))) {
+        return primary;
+    }
+    if (input.resultSummaryMarkdown?.trim()) {
+        const fallback = parseDecisionEnvelopeFromText(input.resultSummaryMarkdown, "resultSummaryFallback");
+        if (fallback.ok) {
+            return fallback;
+        }
+    }
+    if (primary) {
+        return primary;
+    }
+    if (input.resultSummaryMarkdown?.trim()) {
+        return parseDecisionEnvelopeFromText(input.resultSummaryMarkdown, "resultSummaryFallback");
+    }
+    return {
+        ok: false,
+        errors: [`missing ${DECISION_ENVELOPE_FENCE_INFO} fenced block`],
+    };
+}
+export function toDecisionEnvelopeNodeRecord(result) {
+    if (!result.ok) {
+        return {
+            parseOk: false,
+            errors: result.errors,
+            source: result.source,
+        };
+    }
+    return {
+        parseOk: true,
+        decision: result.envelope.decision,
+        requiresHuman: result.envelope.requiresHuman,
+        nextAction: result.envelope.nextAction,
+        riskLevel: result.envelope.riskLevel,
+        source: result.source,
+    };
+}
+export async function writeDecisionEnvelopeArtifacts(nodeArtifactsDir, result) {
+    await mkdir(nodeArtifactsDir, { recursive: true });
+    if (result.ok) {
+        const envelopePath = path.join(nodeArtifactsDir, "decision.envelope.json");
+        await writeFile(envelopePath, `${JSON.stringify(result.envelope, null, 2)}\n`, "utf-8");
+        return { envelopePath };
+    }
+    const validationPath = path.join(nodeArtifactsDir, "decision.envelope.validation.json");
+    await writeFile(validationPath, `${JSON.stringify({
+        ok: false,
+        source: result.source ?? null,
+        errors: result.errors,
+    }, null, 2)}\n`, "utf-8");
+    return { validationPath };
+}
+export function isDecisionGateEnabled(task) {
+    return task.decisionGate?.enabled === true;
+}
+export function isPauseOnHumanDecisionGate(task) {
+    return (isDecisionGateEnabled(task) && task.decisionGate?.mode === "pause-on-human");
+}
+export function shouldPauseOnHumanEscalation(task, nodeRecord) {
+    return (isPauseOnHumanDecisionGate(task) &&
+        nodeRecord?.parseOk === true &&
+        nodeRecord.requiresHuman === true);
+}
+export async function writeHumanEscalationArtifacts(input) {
+    await mkdir(input.nodeArtifactsDir, { recursive: true });
+    const jsonPath = path.join(input.nodeArtifactsDir, "human-escalation.json");
+    const markdownPath = path.join(input.nodeArtifactsDir, "human-escalation.md");
+    const payload = {
+        schemaVersion: 1,
+        runId: input.runId,
+        nodeId: input.nodeId,
+        decision: input.envelope.decision,
+        requiresHuman: input.envelope.requiresHuman,
+        nextAction: input.envelope.nextAction,
+        riskLevel: input.envelope.riskLevel,
+        humanEscalation: input.envelope.humanEscalation,
+        pausedAt: input.pausedAt,
+    };
+    await writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+    const escalation = input.envelope.humanEscalation;
+    const markdownLines = [
+        "# Human escalation",
+        "",
+        `- **Run**: \`${input.runId}\``,
+        `- **Node**: \`${input.nodeId}\``,
+        `- **Decision**: \`${input.envelope.decision}\``,
+        `- **Risk**: \`${input.envelope.riskLevel}\``,
+        `- **Paused at**: ${input.pausedAt}`,
+        "",
+        escalation ? `## Question\n\n${escalation.question}` : "## Question\n\n(none)",
+    ];
+    if (escalation) {
+        markdownLines.push("", `Recommended option: \`${escalation.recommendedOption}\``, "", "## Options");
+        for (const option of escalation.options) {
+            markdownLines.push("", `### ${option.label} (\`${option.id}\`)`, `- Risk: ${option.risk}`, `- Reason: ${option.reason}`);
+        }
+    }
+    await writeFile(markdownPath, `${markdownLines.join("\n")}\n`, "utf-8");
+    return { jsonPath, markdownPath };
+}
+export async function recordDecisionEnvelopeForNode(input) {
+    if (!isDecisionGateEnabled(input.task)) {
+        return undefined;
+    }
+    const resultSummaryMarkdown = await readOptionalTextFile(path.join(input.runDir, input.nodeId, "result.summary.md"));
+    const parseResult = await parseDecisionEnvelopeForNode({
+        assistantText: input.assistantText,
+        resultSummaryMarkdown,
+    });
+    const nodeRecord = toDecisionEnvelopeNodeRecord(parseResult);
+    await writeDecisionEnvelopeArtifacts(path.join(input.runDir, input.nodeId), parseResult);
+    return {
+        nodeRecord,
+        envelope: parseResult.ok ? parseResult.envelope : undefined,
+    };
+}
+export function parseDagDecisionCommandArgs(mode, args) {
+    if (args.length === 0) {
+        throw new Error(`usage: dag decision ${mode} --run-id <id> [--node-id <node-id>]`);
+    }
+    let runId;
+    let nodeId;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--run-id") {
+            runId = args[++i];
+            continue;
+        }
+        if (arg.startsWith("--run-id=")) {
+            runId = arg.slice("--run-id=".length);
+            continue;
+        }
+        if (arg === "--node-id") {
+            nodeId = args[++i];
+            continue;
+        }
+        if (arg.startsWith("--node-id=")) {
+            nodeId = arg.slice("--node-id=".length);
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new Error(`unknown dag decision ${mode} flag: ${arg}`);
+        }
+        throw new Error(`unexpected positional argument: ${arg}`);
+    }
+    if (!runId) {
+        throw new Error(`usage: dag decision ${mode} --run-id <id> [--node-id <node-id>]`);
+    }
+    return { runId, nodeId };
+}
+function buildDecisionEnvelopeInspectNodeSummary(envelope) {
+    return {
+        decision: envelope.decision,
+        requiresHuman: envelope.requiresHuman,
+        nextAction: envelope.nextAction,
+        riskLevel: envelope.riskLevel,
+        gateType: envelope.gateType,
+        confidence: envelope.confidence,
+        blockingFindingsCount: envelope.blockingFindings.length,
+        requiredRevisionsCount: envelope.requiredRevisions.length,
+        riskFlags: envelope.riskFlags,
+        hasHumanEscalation: envelope.humanEscalation !== null,
+        evidence: summarizeDecisionEnvelopeEvidenceCompleteness(envelope),
+    };
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolvePersistedDecisionArtifact(nodeDir) {
+    if (await pathExists(path.join(nodeDir, "decision.envelope.json"))) {
+        return "decision.envelope.json";
+    }
+    if (await pathExists(path.join(nodeDir, "decision.envelope.validation.json"))) {
+        return "decision.envelope.validation.json";
+    }
+    return null;
+}
+async function listDecisionGateNodeIds(input) {
+    const ids = new Set();
+    for (const task of input.specTasks) {
+        if (isDecisionGateEnabled(task)) {
+            ids.add(task.id);
+        }
+    }
+    for (const [nodeId, node] of Object.entries(input.state.nodes)) {
+        if (node.decisionEnvelope !== undefined) {
+            ids.add(nodeId);
+        }
+        const nodeDir = path.join(input.runDir, nodeId);
+        if (await resolvePersistedDecisionArtifact(nodeDir)) {
+            ids.add(nodeId);
+        }
+    }
+    return [...ids].sort();
+}
+export async function inspectDecisionEnvelopeNode(input) {
+    const nodeDir = path.join(input.runDir, input.nodeId);
+    const assistantText = input.nodeRecord?.assistantText;
+    const resultSummaryMarkdown = await readOptionalTextFile(path.join(nodeDir, "result.summary.md"));
+    const parseResult = await parseDecisionEnvelopeForNode({
+        assistantText,
+        resultSummaryMarkdown,
+    });
+    const persistedArtifact = await resolvePersistedDecisionArtifact(nodeDir);
+    const summary = parseResult.ok
+        ? buildDecisionEnvelopeInspectNodeSummary(parseResult.envelope)
+        : {
+            decision: input.nodeRecord?.decisionEnvelope?.decision,
+            requiresHuman: input.nodeRecord?.decisionEnvelope?.requiresHuman,
+            nextAction: input.nodeRecord?.decisionEnvelope?.nextAction,
+            riskLevel: input.nodeRecord?.decisionEnvelope?.riskLevel,
+        };
+    return {
+        nodeId: input.nodeId,
+        parseOk: parseResult.ok,
+        source: parseResult.ok ? parseResult.source : parseResult.source,
+        persistedArtifact,
+        inputs: {
+            assistantText: Boolean(assistantText?.trim()),
+            resultSummaryMarkdown: Boolean(resultSummaryMarkdown?.trim()),
+        },
+        recordSummary: input.nodeRecord?.decisionEnvelope,
+        summary,
+        errors: parseResult.ok ? undefined : parseResult.errors,
+    };
+}
+export async function buildDecisionEnvelopeInspectReport(repoRoot, args, mode) {
+    const located = await locateDagRun(repoRoot, args.runId);
+    if (!located) {
+        throw new Error(`dag run not found: ${args.runId}`);
+    }
+    const { lifecycle, runDir } = located;
+    const state = await readDagRunState(runDir);
+    const spec = await readDagRunSpec(runDir);
+    let nodeIds = await listDecisionGateNodeIds({
+        runDir,
+        specTasks: spec.tasks,
+        state,
+    });
+    if (args.nodeId) {
+        if (!nodeIds.includes(args.nodeId)) {
+            const nodeDir = path.join(runDir, args.nodeId);
+            const hasArtifacts = Boolean(state.nodes[args.nodeId]) ||
+                (await resolvePersistedDecisionArtifact(nodeDir)) !== null;
+            if (!hasArtifacts) {
+                throw new Error(`decision gate node not found for run ${args.runId}: ${args.nodeId}`);
+            }
+            nodeIds = [args.nodeId];
+        }
+        else {
+            nodeIds = [args.nodeId];
+        }
+    }
+    if (nodeIds.length === 0) {
+        throw new Error(`no decision gate nodes found for run ${args.runId}`);
+    }
+    const nodes = [];
+    for (const nodeId of nodeIds) {
+        nodes.push(await inspectDecisionEnvelopeNode({
+            runDir,
+            nodeId,
+            nodeRecord: state.nodes[nodeId],
+        }));
+    }
+    return {
+        mode,
+        runId: args.runId,
+        lifecycle,
+        dryRun: true,
+        advisoryOnly: true,
+        valid: nodes.every((node) => node.parseOk),
+        nodes,
+    };
+}
+export async function runDagDecisionInspect(repoRoot, rawArgs) {
+    const parsed = parseDagDecisionCommandArgs("inspect", rawArgs);
+    const report = await buildDecisionEnvelopeInspectReport(repoRoot, parsed, "inspect");
+    console.log(JSON.stringify(report, null, 2));
+}
+export async function runDagDecisionValidate(repoRoot, rawArgs) {
+    const parsed = parseDagDecisionCommandArgs("validate", rawArgs);
+    const report = await buildDecisionEnvelopeInspectReport(repoRoot, parsed, "validate");
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.valid) {
+        process.exit(1);
+    }
+}