@tea-agent/loop-agent 0.1.0

package/dist/workflows/dynamic/compile.js

@@ -0,0 +1,360 @@
+import path from "node:path";
+import { parseDagSpec } from "../dag/types.js";
+import { assertValidWorkflowSpec } from "./validate.js";
+import { workflowNodeSchema, } from "./spec.js";
+const READ_ONLY_FORBIDDEN_PATHS = ["artifacts/**", ".harness/**"];
+export function defaultCompileManifestPath(outputPath) {
+    const parsed = path.parse(outputPath);
+    const base = parsed.base.endsWith(".dag.json")
+        ? parsed.base.slice(0, -".dag.json".length)
+        : parsed.name;
+    return path.join(parsed.dir, `${base}.compile-manifest.json`);
+}
+function stringifyOutputSchema(outputSchema) {
+    if (outputSchema === undefined)
+        return undefined;
+    return `Workflow outputSchema:\n${JSON.stringify(outputSchema, null, 2)}`;
+}
+function compileTemplate(value, inputs) {
+    return value.replace(/\{\{\s*inputs\.([A-Za-z0-9_-]+)\s*\}\}/g, (_match, key) => {
+        const replacement = inputs[key];
+        if (typeof replacement === "string" ||
+            typeof replacement === "number" ||
+            typeof replacement === "boolean") {
+            return String(replacement);
+        }
+        return "";
+    });
+}
+function dagRoleForNode(node) {
+    if (node.type === "reduce_agent")
+        return "closeout";
+    if (node.type === "verify_agent")
+        return "verifier";
+    if (node.type === "human_gate")
+        return "supervisor";
+    if (node.type === "agent" || node.type === "map_agent")
+        return "reviewer";
+    return undefined;
+}
+function executorForAgentLikeNode(node) {
+    return node.executor ?? "pi";
+}
+function dagWriteFields(spec, node) {
+    if (node?.writePolicy === "none") {
+        return {
+            writePolicy: "none",
+            allowedPaths: [],
+            forbiddenPaths: [],
+        };
+    }
+    if (node?.writePolicy === "read-only") {
+        return {
+            writePolicy: "read-only",
+            allowedPaths: [],
+            forbiddenPaths: READ_ONLY_FORBIDDEN_PATHS,
+        };
+    }
+    if (spec.permissions.edits === "deny") {
+        return {
+            writePolicy: "read-only",
+            allowedPaths: [],
+            forbiddenPaths: READ_ONLY_FORBIDDEN_PATHS,
+        };
+    }
+    return {
+        writePolicy: "exclusive",
+        allowedPaths: spec.permissions.allowedPaths ?? [],
+        forbiddenPaths: spec.permissions.forbiddenPaths ?? [],
+        writeSet: spec.permissions.writeSet ?? [],
+    };
+}
+function buildAgentPrompt(node) {
+    const role = node.role ? `Workflow role: ${node.role}\n` : "";
+    const prompt = node.prompt ?? `Execute workflow node ${node.id}.`;
+    return [
+        `Workflow node: ${node.id}`,
+        `Workflow primitive: ${node.type}`,
+        role.trim(),
+        prompt,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}
+function compileCommandNode(spec, node) {
+    const command = node.command ?? "";
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "LOW",
+        subtask_prompt: `Run workflow command node ${node.id}.`,
+        executor: "shell",
+        writePolicy: "none",
+        allowedPaths: [],
+        forbiddenPaths: [],
+        shell: {
+            commands: [compileTemplate(command, spec.inputs)],
+        },
+        outputContract: stringifyOutputSchema(node.outputSchema),
+    };
+}
+function compileHumanGateNode(spec, node) {
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "LOW",
+        subtask_prompt: [
+            `Workflow human gate: ${node.id}`,
+            node.reason ?? "Review upstream workflow outputs and decide whether execution may continue.",
+            "Return a decision envelope. Set requiresHuman=true when explicit approval is needed.",
+        ].join("\n\n"),
+        executor: "pi",
+        role: "supervisor",
+        ...dagWriteFields(spec, node),
+        decisionGate: { enabled: true, mode: "pause-on-human" },
+        outputContract: node.approvalSchema
+            ? `Workflow approvalSchema:\n${JSON.stringify(node.approvalSchema, null, 2)}`
+            : undefined,
+    };
+}
+function compileArtifactTransformNode(node) {
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "LOW",
+        subtask_prompt: `Apply deterministic artifact transform ${node.id}.`,
+        executor: "static",
+        writePolicy: "none",
+        allowedPaths: [],
+        forbiddenPaths: [],
+        static: {
+            resultMarkdown: node.transform?.template ?? "artifact transform completed",
+        },
+        outputContract: stringifyOutputSchema(node.outputSchema),
+    };
+}
+function compileConditionNode(node) {
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "LOW",
+        subtask_prompt: `Evaluate workflow condition ${node.id}.`,
+        executor: "static",
+        writePolicy: "none",
+        allowedPaths: [],
+        forbiddenPaths: [],
+        static: {
+            resultMarkdown: `Dynamic condition barrier for ${node.id}.`,
+        },
+        outputContract: stringifyOutputSchema(node.outputSchema),
+        dynamicCondition: {
+            workflowNodeId: node.id,
+            cases: node.cases ?? [],
+            default: node.default,
+        },
+    };
+}
+function stopWhenAnyExpressions(stopWhen) {
+    if (typeof stopWhen === "string")
+        return [stopWhen];
+    if (stopWhen && typeof stopWhen === "object") {
+        const any = stopWhen.any;
+        if (Array.isArray(any)) {
+            return any.filter((entry) => typeof entry === "string");
+        }
+    }
+    return [];
+}
+function compileLoopBodyTask(spec, node) {
+    const executor = executorForAgentLikeNode(node);
+    return {
+        id: node.id,
+        dependsOn: node.dependsOn,
+        executor,
+        role: dagRoleForNode(node),
+        complexity: node.type === "reduce_agent" ? "MED" : "LOW",
+        subtaskPromptTemplate: buildAgentPrompt(node),
+        staticResultTemplate: node.staticResultTemplate ?? node.transform?.template ?? undefined,
+        outputContract: stringifyOutputSchema(node.outputSchema),
+        ...dagWriteFields(spec, node),
+    };
+}
+function compileLoopUntilNode(spec, node) {
+    const bodyTasks = (node.body ?? []).map((entry) => compileLoopBodyTask(spec, workflowNodeSchema.parse(entry)));
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "MED",
+        subtask_prompt: buildAgentPrompt(node),
+        executor: "static",
+        role: dagRoleForNode(node),
+        ...dagWriteFields(spec, node),
+        static: {
+            resultMarkdown: `Dynamic loop_until barrier for ${node.id}.`,
+        },
+        outputContract: stringifyOutputSchema(node.outputSchema),
+        dynamicLoopUntil: {
+            workflowNodeId: node.id,
+            maxIterations: node.maxIterations ?? spec.limits.maxIterations,
+            stopWhenAny: stopWhenAnyExpressions(node.stopWhen),
+            bodyTasks,
+        },
+    };
+}
+function compileAgentLikeNode(spec, node) {
+    const executor = executorForAgentLikeNode(node);
+    if (executor === "static") {
+        return {
+            id: node.id,
+            depends_on: node.dependsOn,
+            complexity: node.type === "reduce_agent" ? "MED" : "LOW",
+            subtask_prompt: buildAgentPrompt(node),
+            executor: "static",
+            role: dagRoleForNode(node),
+            ...dagWriteFields(spec, node),
+            static: {
+                resultMarkdown: node.staticResultTemplate ?? `Workflow node ${node.id} completed.`,
+            },
+            outputContract: stringifyOutputSchema(node.outputSchema),
+        };
+    }
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: node.type === "reduce_agent" ? "MED" : "LOW",
+        subtask_prompt: buildAgentPrompt(node),
+        executor: "pi",
+        role: dagRoleForNode(node),
+        ...dagWriteFields(spec, node),
+        outputContract: stringifyOutputSchema(node.outputSchema),
+    };
+}
+function compileNode(spec, node) {
+    if (node.type === "command")
+        return compileCommandNode(spec, node);
+    if (node.type === "human_gate")
+        return compileHumanGateNode(spec, node);
+    if (node.type === "artifact_transform")
+        return compileArtifactTransformNode(node);
+    if (node.type === "condition")
+        return compileConditionNode(node);
+    if (node.type === "loop_until")
+        return compileLoopUntilNode(spec, node);
+    if (node.type === "map_agent" || node.type === "verify_agent") {
+        return compileDynamicExpansionNode(spec, node);
+    }
+    if (node.type === "reduce_agent" && node.reducer) {
+        return compileDynamicReductionNode(spec, node);
+    }
+    return compileAgentLikeNode(spec, node);
+}
+function compileDynamicExpansionNode(spec, node) {
+    if (node.type !== "map_agent" && node.type !== "verify_agent") {
+        throw new Error(`unsupported dynamic expansion node type: ${node.type}`);
+    }
+    const expansionType = node.type;
+    const childExecutor = executorForAgentLikeNode(node);
+    const childPrompt = buildAgentPrompt(node);
+    const childTask = {
+        executor: childExecutor,
+        role: dagRoleForNode(node),
+        complexity: "LOW",
+        subtaskPromptTemplate: childPrompt,
+        staticResultTemplate: node.staticResultTemplate,
+        outputContract: stringifyOutputSchema(node.outputSchema),
+        ...dagWriteFields(spec, node),
+    };
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "LOW",
+        subtask_prompt: `Expand workflow map_agent node ${node.id}.`,
+        executor: "static",
+        writePolicy: "none",
+        allowedPaths: [],
+        forbiddenPaths: [],
+        static: {
+            resultMarkdown: `Dynamic ${node.type} expansion barrier for ${node.id}.`,
+        },
+        outputContract: stringifyOutputSchema(node.outputSchema),
+        dynamicExpansion: {
+            type: expansionType,
+            workflowNodeId: node.id,
+            itemsFrom: node.itemsFrom ?? "",
+            itemName: node.itemName ?? "item",
+            maxItems: node.maxItems ?? spec.limits.maxExpandedNodes,
+            maxExpandedNodes: spec.limits.maxExpandedNodes,
+            workspaceTemplate: node.workspaceTemplate,
+            childIdPrefix: node.id,
+            childTask,
+        },
+    };
+}
+function compileDynamicReductionNode(spec, node) {
+    return {
+        id: node.id,
+        depends_on: node.dependsOn,
+        complexity: "MED",
+        subtask_prompt: buildAgentPrompt(node),
+        executor: "static",
+        role: dagRoleForNode(node),
+        ...dagWriteFields(spec, node),
+        static: {
+            resultMarkdown: `Dynamic reducer ${node.reducer?.type ?? "unknown"} for ${node.id}.`,
+        },
+        outputContract: stringifyOutputSchema(node.outputSchema),
+        dynamicReduction: node.reducer
+            ? {
+                type: node.reducer.type,
+                workflowNodeId: node.id,
+                findingsFrom: node.reducer.findingsFrom,
+                verificationsFrom: node.reducer.verificationsFrom,
+                refutedFindingsArtifactName: "refuted-findings.json",
+            }
+            : undefined,
+    };
+}
+export function compileWorkflowToDag(spec, options = {}) {
+    assertValidWorkflowSpec(spec);
+    const tasks = spec.nodes.map((node) => compileNode(spec, node));
+    const dag = parseDagSpec({
+        version: 2,
+        title: `Workflow: ${spec.meta.name}`,
+        objective: spec.meta.description,
+        successCriteria: [`Workflow final node completed: ${spec.final.from}`],
+        globalConstraints: [
+            "Compiled from Dynamic Workflow DAG Engine WorkflowSpec.",
+            "Workflow origin is recorded in the sidecar compile manifest.",
+        ],
+        tasks,
+    });
+    const manifest = {
+        version: 1,
+        workflow: {
+            name: spec.meta.name,
+            version: spec.version,
+            kind: spec.kind,
+            sourcePath: options.sourcePath,
+            final: spec.final.from,
+        },
+        limits: spec.limits,
+        permissions: spec.permissions,
+        nodes: Object.fromEntries(spec.nodes.map((node) => [
+            node.id,
+            {
+                workflowNodeId: node.id,
+                workflowNodeType: node.type,
+                dagTaskIds: [node.id],
+                commandAllowlist: node.type === "command" ? spec.permissions.shell.commands : undefined,
+                outputSchema: node.outputSchema,
+                dynamic: node.type === "map_agent" ||
+                    node.type === "verify_agent" ||
+                    node.type === "condition" ||
+                    node.type === "loop_until"
+                    ? true
+                    : undefined,
+            },
+        ])),
+    };
+    return { dag, manifest };
+}

package/dist/workflows/dynamic/compileTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/workflows/dynamic/errors.js

@@ -0,0 +1,5 @@
+export function formatWorkflowValidationIssues(issues) {
+    return issues
+        .map((issue) => `${issue.type} at ${issue.path}: ${issue.message}`)
+        .join("; ");
+}

package/dist/workflows/dynamic/index.js

@@ -0,0 +1,7 @@
+export * from "./spec.js";
+export * from "./errors.js";
+export * from "./validate.js";
+export * from "./compileTypes.js";
+export * from "./compile.js";
+export * from "./artifacts.js";
+export * from "./profiles.js";

package/dist/workflows/dynamic/profiles.js

@@ -0,0 +1,156 @@
+export const WORKFLOW_PLAN_PROFILES = [
+    "pr-review",
+];
+function buildDiscoverFilesOutput(files) {
+    return JSON.stringify({
+        files: files.map((file, index) => ({
+            path: file,
+            findingId: `finding-${index + 1}`,
+            expectedStatus: "verified",
+            expectedReason: `review finding for ${file} is present in the mapped artifact`,
+        })),
+    });
+}
+export function buildPrReviewWorkflowSpec(options) {
+    const base = options.base ?? "main";
+    const head = options.head ?? "HEAD";
+    const files = options.changedFiles && options.changedFiles.length > 0
+        ? options.changedFiles
+        : ["README.md"];
+    return {
+        version: "0.1",
+        kind: "dynamic-agent-workflow",
+        meta: {
+            name: "pr-review",
+            description: `Read-only PR review workflow for task ${options.taskId}.`,
+            riskLevel: "low",
+        },
+        inputs: {
+            taskId: options.taskId,
+            base,
+            head,
+        },
+        limits: {
+            maxConcurrency: 4,
+            maxAgentRuns: 50,
+            maxExpandedNodes: 50,
+            maxRetriesPerNode: 0,
+            maxIterations: 3,
+            maxWallClockMinutes: 15,
+        },
+        permissions: {
+            filesystem: "read_only",
+            shell: {
+                mode: "deny",
+                commands: [],
+            },
+            network: "deny",
+            edits: "deny",
+        },
+        nodes: [
+            {
+                id: "discover-changed-files",
+                type: "artifact_transform",
+                dependsOn: [],
+                transform: {
+                    type: "markdown_template",
+                    template: buildDiscoverFilesOutput(files),
+                },
+                outputSchema: {
+                    type: "object",
+                    required: ["files"],
+                    properties: {
+                        files: { type: "array" },
+                    },
+                },
+            },
+            {
+                id: "review-each-file",
+                type: "map_agent",
+                dependsOn: ["discover-changed-files"],
+                itemsFrom: "$.nodes['discover-changed-files'].output.files",
+                itemName: "file",
+                executor: "static",
+                role: "reviewer",
+                prompt: "Review {{file.path}} and emit one structured finding.",
+                staticResultTemplate: "{\"id\":\"{{file.findingId}}\",\"sourceNodeId\":\"review-each-file\",\"targetRef\":\"{{file.path}}\",\"title\":\"Review finding for {{file.path}}\",\"severity\":\"medium\",\"evidence\":[{\"path\":\"{{file.path}}\",\"summary\":\"deterministic profile finding\"}],\"recommendation\":\"Inspect {{file.path}} before merging\",\"expectedStatus\":\"{{file.expectedStatus}}\",\"expectedReason\":\"{{file.expectedReason}}\"}",
+                outputSchema: {
+                    type: "object",
+                    required: [
+                        "id",
+                        "sourceNodeId",
+                        "targetRef",
+                        "title",
+                        "severity",
+                        "evidence",
+                        "recommendation",
+                    ],
+                    properties: {
+                        id: { type: "string" },
+                        sourceNodeId: { type: "string" },
+                        targetRef: { type: "string" },
+                        title: { type: "string" },
+                        severity: { type: "string" },
+                        evidence: { type: "array" },
+                        recommendation: { type: "string" },
+                    },
+                },
+            },
+            {
+                id: "verify-findings",
+                type: "verify_agent",
+                dependsOn: ["review-each-file"],
+                producerNodeId: "review-each-file",
+                itemsFrom: "$.nodes['review-each-file'].output.children",
+                itemName: "finding",
+                executor: "static",
+                role: "adversarial-verifier",
+                prompt: "Independently verify {{finding.output.id}} using only the finding artifact.",
+                staticResultTemplate: "{\"findingId\":\"{{finding.output.id}}\",\"verifierNodeId\":\"verify-findings\",\"status\":\"{{finding.output.expectedStatus}}\",\"reason\":\"{{finding.output.expectedReason}}\",\"evidence\":[{\"path\":\"{{finding.output.targetRef}}\",\"summary\":\"independent verifier checked mapped finding\"}]}",
+                outputSchema: {
+                    type: "object",
+                    required: ["findingId", "verifierNodeId", "status", "reason", "evidence"],
+                    properties: {
+                        findingId: { type: "string" },
+                        verifierNodeId: { type: "string" },
+                        status: { type: "string" },
+                        reason: { type: "string" },
+                        evidence: { type: "array" },
+                    },
+                },
+            },
+            {
+                id: "final-ranked-summary",
+                type: "reduce_agent",
+                dependsOn: ["verify-findings"],
+                role: "closeout",
+                prompt: "Create a verified-first PR review report.",
+                reducer: {
+                    type: "verified_findings_report",
+                    findingsFrom: "$.nodes['review-each-file'].output.children",
+                    verificationsFrom: "$.nodes['verify-findings'].output.children",
+                },
+                outputSchema: {
+                    type: "object",
+                    required: ["summary", "verifiedFindings", "uncertainFindings", "evidenceRefs"],
+                    properties: {
+                        summary: { type: "string" },
+                        verifiedFindings: { type: "array" },
+                        uncertainFindings: { type: "array" },
+                        refutedFindingsRef: { type: "string" },
+                        evidenceRefs: { type: "array" },
+                    },
+                },
+            },
+        ],
+        final: {
+            from: "final-ranked-summary",
+        },
+    };
+}
+export function buildWorkflowSpecForProfile(input) {
+    if (input.profile === "pr-review") {
+        return buildPrReviewWorkflowSpec(input);
+    }
+    throw new Error(`unsupported workflow profile: ${input.profile}`);
+}

package/dist/workflows/dynamic/spec.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+export const WORKFLOW_NODE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export const workflowVersionSchema = z.literal("0.1");
+export const workflowKindSchema = z.literal("dynamic-agent-workflow");
+export const workflowRiskLevelSchema = z.enum(["low", "medium", "high", "critical"]);
+export const workflowNodeTypeSchema = z.enum([
+    "agent",
+    "map_agent",
+    "verify_agent",
+    "reduce_agent",
+    "command",
+    "condition",
+    "loop_until",
+    "human_gate",
+    "artifact_transform",
+]);
+export const workflowLimitsSchema = z
+    .object({
+    maxConcurrency: z.number().int().positive().max(32).default(8),
+    maxAgentRuns: z.number().int().positive().max(500).default(100),
+    maxExpandedNodes: z.number().int().positive().max(1000).default(200),
+    maxRetriesPerNode: z.number().int().nonnegative().max(5).default(1),
+    maxIterations: z.number().int().positive().max(20).default(3),
+    maxWallClockMinutes: z.number().int().positive().max(24 * 60).default(30),
+})
+    .default({});
+export const workflowPermissionsSchema = z
+    .object({
+    filesystem: z.enum(["read_only", "workspace"]).default("read_only"),
+    shell: z
+        .object({
+        mode: z.enum(["deny", "allowlist"]).default("deny"),
+        commands: z.array(z.string().min(1)).default([]),
+    })
+        .default({}),
+    network: z.enum(["deny", "allow"]).default("deny"),
+    edits: z.enum(["deny", "allow"]).default("deny"),
+    allowedPaths: z.array(z.string().min(1)).optional(),
+    forbiddenPaths: z.array(z.string().min(1)).optional(),
+    writeSet: z.array(z.string().min(1)).optional(),
+})
+    .default({});
+export const workflowNodeSchema = z.object({
+    id: z.string().regex(WORKFLOW_NODE_ID_PATTERN, "node id must be kebab-case"),
+    type: workflowNodeTypeSchema,
+    dependsOn: z.array(z.string()).default([]),
+    executor: z.enum(["pi", "static"]).optional(),
+    role: z.string().optional(),
+    prompt: z.string().optional(),
+    staticResultTemplate: z.string().optional(),
+    writePolicy: z.enum(["none", "read-only", "exclusive"]).optional(),
+    outputSchema: z.unknown().optional(),
+    command: z.string().optional(),
+    itemsFrom: z.string().optional(),
+    items: z.array(z.unknown()).optional(),
+    itemName: z.string().optional(),
+    producerNodeId: z.string().optional(),
+    maxItems: z.number().int().positive().optional(),
+    concurrency: z.number().int().positive().optional(),
+    workspaceTemplate: z.string().min(1).optional(),
+    reason: z.string().optional(),
+    approvalSchema: z.unknown().optional(),
+    cases: z
+        .array(z.object({
+        when: z.string().min(1),
+        then: z.string().min(1),
+    }))
+        .optional(),
+    default: z.string().optional(),
+    maxIterations: z.number().int().positive().optional(),
+    stopWhen: z.unknown().optional(),
+    body: z.array(z.unknown()).optional(),
+    transform: z
+        .object({
+        type: z.literal("markdown_template"),
+        template: z.string().min(1),
+    })
+        .optional(),
+    reducer: z
+        .object({
+        type: z.literal("verified_findings_report"),
+        findingsFrom: z.string().min(1),
+        verificationsFrom: z.string().min(1),
+    })
+        .optional(),
+});
+export const workflowSpecSchema = z.object({
+    version: workflowVersionSchema,
+    kind: workflowKindSchema,
+    meta: z
+        .object({
+        name: z.string().min(1),
+        description: z.string().optional(),
+        riskLevel: workflowRiskLevelSchema.optional().default("low"),
+    })
+        .default({ name: "unnamed-workflow", riskLevel: "low" }),
+    inputs: z.record(z.string(), z.unknown()).default({}),
+    limits: workflowLimitsSchema,
+    permissions: workflowPermissionsSchema,
+    nodes: z.array(workflowNodeSchema).min(1),
+    final: z.object({
+        from: z.string().min(1),
+    }),
+});
+export const AGENT_LIKE_WORKFLOW_NODE_TYPES = new Set([
+    "agent",
+    "map_agent",
+    "verify_agent",
+    "reduce_agent",
+]);
+export const ITEM_SELECTOR_WORKFLOW_NODE_TYPES = new Set([
+    "map_agent",
+    "verify_agent",
+]);