@tea-agent/loop-agent 0.3.0 → 0.5.0

package/dist/worker/runner/run-ready.js

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { deriveFailureRoute } from "../pool/failure-routing.js";
+import { findRunByWorkerRunId, getTaskPoolRoot, readAllTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
+import { runTaskSpec, } from "../run-task/run-task.js";
+import { formatDuration, noopProgressReporter } from "../progress-reporter.js";
+import { computeReadyQueue } from "../task-graph/ready-queue.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+export async function runReadyTasks(options) {
+    const now = options.now ?? new Date();
+    const startedAt = now.toISOString();
+    const batchRunId = options.batchRunId ?? buildBatchRunId(now);
+    const graph = await loadTaskGraph(options.featureDir);
+    const states = await readAllTaskPoolStates(options.repoRoot);
+    const readyTaskIds = computeReadyQueue(graph, toGraphState(states)).filter((taskId) => isPoolReady(states[taskId]));
+    const limitedTaskIds = readyTaskIds.slice(0, options.limit ?? readyTaskIds.length);
+    const tasks = [];
+    const runner = options.runTask ?? runTaskSpec;
+    const progress = options.progress ?? noopProgressReporter;
+    const total = limitedTaskIds.length;
+    let index = 0;
+    const batchStartedAt = Date.now();
+    progress.batch(`batch ${batchRunId}: feature=${graph.feature_id}, ${total} task${total === 1 ? "" : "s"} ready → starting`);
+    for (const taskId of limitedTaskIds) {
+        index += 1;
+        const node = graph.nodes.find((candidate) => candidate.id === taskId);
+        const taskSpecPath = path.join(options.featureDir, "tasks", node?.task ?? `${taskId}.yaml`);
+        const taskSpec = await loadTaskSpec(taskSpecPath);
+        const workerRunId = options.workerRunIdForTask?.(taskId, taskSpec) ??
+            buildStableWorkerRunId(taskId, taskSpec, now);
+        if (workerRunId) {
+            const existing = await findRunByWorkerRunId(options.repoRoot, workerRunId);
+            if (existing) {
+                progress.task(`task ${index}/${total} ${taskId}: reuse existing run ${workerRunId}`);
+                tasks.push({
+                    taskId,
+                    workerRunId,
+                    status: "reused",
+                    runRecordPath: existing.runRecordPath,
+                });
+                continue;
+            }
+        }
+        const taskStartedAt = Date.now();
+        progress.task(`task ${index}/${total} ${taskId} "${taskSpec.title}" (${workerRunId})`);
+        progress.step(`preflight → materialize → dag-run-task → validate → run-dag → report`);
+        let result;
+        try {
+            await writeTaskPoolState(options.repoRoot, {
+                taskId,
+                status: "Running",
+                updatedAt: new Date().toISOString(),
+                workerRunId,
+            });
+            result = await runner({
+                repoRoot: options.repoRoot,
+                taskSpec,
+                taskSpecPath,
+                client: options.client,
+                now,
+                workerRunId,
+                preflight: {
+                    runCheckRepo: options.runCheckRepo,
+                    ...(options.checkRepoCommand ? { checkRepoCommand: options.checkRepoCommand } : {}),
+                },
+                progress,
+                ...(options.piModel ? { piModel: options.piModel } : {}),
+            });
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            progress.note(`task ${taskId}: ERROR ${message}`);
+            try {
+                await recordTaskPoolRun({
+                    repoRoot: options.repoRoot,
+                    run: {
+                        schemaVersion: 1,
+                        batchRunId,
+                        workerRunId,
+                        taskId,
+                        featureId: taskSpec.feature_id,
+                        status: "run-error",
+                        recordedAt: new Date().toISOString(),
+                        error: message,
+                    },
+                });
+            }
+            catch (recordError) {
+                tasks.push({
+                    taskId,
+                    workerRunId,
+                    status: "record-error",
+                    error: errorMessage(recordError),
+                });
+                continue;
+            }
+            tasks.push({
+                taskId,
+                workerRunId,
+                status: "run-error",
+                error: message,
+            });
+            continue;
+        }
+        const failure = deriveFailureRoute(result);
+        if (result.status === "succeeded") {
+            progress.step(`✓ ${taskId} succeeded in ${formatDuration(Date.now() - taskStartedAt)} (promoted + closed out)`);
+        }
+        else {
+            progress.step(`✗ ${taskId} failed in ${formatDuration(Date.now() - taskStartedAt)} — see failure artifacts`);
+        }
+        const run = {
+            schemaVersion: 1,
+            batchRunId,
+            workerRunId: result.workerRunId,
+            taskId: result.businessId,
+            featureId: taskSpec.feature_id,
+            status: result.status,
+            harnessTaskId: result.harnessTaskId,
+            runRecordPath: result.runRecordPath,
+            dagPath: result.dagPath,
+            recordedAt: new Date().toISOString(),
+            ...(failure ? { failure } : {}),
+            ...(result.failureArtifacts ? { failureArtifacts: result.failureArtifacts } : {}),
+        };
+        try {
+            await recordTaskPoolRun({ repoRoot: options.repoRoot, run });
+            tasks.push({
+                taskId,
+                workerRunId: result.workerRunId,
+                status: result.status,
+                runRecordPath: result.runRecordPath,
+            });
+        }
+        catch (error) {
+            tasks.push({
+                taskId,
+                workerRunId: result.workerRunId,
+                status: "record-error",
+                error: errorMessage(error),
+                runRecordPath: result.runRecordPath,
+            });
+        }
+    }
+    const summary = summarize(tasks);
+    const batchRunPath = path.join(getTaskPoolRoot(options.repoRoot), "runs", `${batchRunId}.json`);
+    const output = {
+        schemaVersion: 1,
+        status: summary.recordErrors > 0 || summary.runErrors > 0 ? "failed" : "completed",
+        batchRunId,
+        featureId: graph.feature_id,
+        startedAt,
+        summary,
+        tasks,
+        batchRunPath,
+    };
+    await mkdir(path.dirname(batchRunPath), { recursive: true });
+    await writeFile(batchRunPath, `${JSON.stringify(output, null, 2)}\n`, "utf-8");
+    progress.batch(`batch ${batchRunId} ${output.status}: ${summary.succeeded} succeeded, ${summary.failed} failed, ${summary.reused} reused in ${formatDuration(Date.now() - batchStartedAt)} → ${batchRunPath}`);
+    return output;
+}
+export function buildBatchRunId(now) {
+    return `batch-${now.toISOString().replace(/[-:.]/g, "").slice(0, 15)}`;
+}
+export function buildStableWorkerRunId(taskId, taskSpec, now) {
+    const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+    const slug = taskId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const hash = createHash("sha256")
+        .update(`${taskSpec.feature_id}:${taskSpec.id}:${taskSpec.title}`)
+        .digest("hex")
+        .slice(0, 10);
+    return `wr-${date}-${slug}-${hash}`;
+}
+async function loadTaskGraph(featureDir) {
+    const graphPath = path.join(featureDir, "tasks", "task-graph.yaml");
+    return taskGraphSpecSchema.parse(YAML.parse(await readFile(graphPath, "utf-8")));
+}
+async function loadTaskSpec(taskSpecPath) {
+    return taskSpecSchema.parse(YAML.parse(await readFile(taskSpecPath, "utf-8")));
+}
+function toGraphState(states) {
+    const graphState = {};
+    for (const [taskId, state] of Object.entries(states)) {
+        if (state.status === "Done")
+            graphState[taskId] = "completed";
+        if (state.status === "Running" || state.status === "Queued")
+            graphState[taskId] = "running";
+        if (state.status === "Failed")
+            graphState[taskId] = "failed";
+        if (state.status === "Blocked")
+            graphState[taskId] = "blocked";
+    }
+    return graphState;
+}
+function isPoolReady(state) {
+    return !state || state.status === "Ready";
+}
+function summarize(tasks) {
+    return {
+        total: tasks.length,
+        succeeded: tasks.filter((task) => task.status === "succeeded").length,
+        failed: tasks.filter((task) => task.status === "failed").length,
+        reused: tasks.filter((task) => task.status === "reused").length,
+        recordErrors: tasks.filter((task) => task.status === "record-error").length,
+        runErrors: tasks.filter((task) => task.status === "run-error").length,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/worker/task-graph/acceptance-schema.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export const acceptanceItemSchema = z
+    .object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    priority: z.enum(["must", "should", "could", "wont"]).optional().default("must"),
+    type: z.string().min(1),
+    given: z.string().min(1),
+    when: z.string().min(1),
+    then: z.string().min(1),
+    verification: z
+        .object({
+        expected_task_refs: z.array(z.string().min(1)).min(1),
+        suggested_tests: z.array(z.string().min(1)).optional().default([]),
+    })
+        .strict(),
+})
+    .strict();
+export const acceptanceSpecSchema = z
+    .object({
+    schema_version: z.literal(1),
+    feature_id: z.string().min(1),
+    acceptance: z.array(acceptanceItemSchema).min(1),
+})
+    .strict();

package/dist/worker/task-graph/ready-queue.js

@@ -0,0 +1,23 @@
+const TERMINAL_OR_ACTIVE = new Set([
+    "running",
+    "completed",
+    "failed",
+    "blocked",
+]);
+export function computeReadyQueue(graph, state) {
+    return graph.nodes
+        .filter((node) => {
+        const ownStatus = getStatus(state[node.id]);
+        if (ownStatus && TERMINAL_OR_ACTIVE.has(ownStatus))
+            return false;
+        return node.depends_on.every((dependencyId) => getStatus(state[dependencyId]) === "completed");
+    })
+        .map((node) => node.id);
+}
+function getStatus(value) {
+    if (!value)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    return value.status;
+}

package/dist/worker/task-graph/task-graph-schema.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { taskSpecTypeSchema } from "../task-spec/schema.js";
+export const taskGraphNodeSchema = z
+    .object({
+    id: z.string().min(1),
+    task: z.string().min(1),
+    type: taskSpecTypeSchema,
+    depends_on: z.array(z.string().min(1)).optional().default([]),
+})
+    .strict();
+export const taskGraphSpecSchema = z
+    .object({
+    schema_version: z.literal(1),
+    feature_id: z.string().min(1),
+    nodes: z.array(taskGraphNodeSchema).min(1),
+    parallel_policy: z
+        .object({
+        max_parallel_tasks: z.number().int().positive().optional().default(1),
+        disallow_same_file_parallel_writes: z.boolean().optional().default(true),
+    })
+        .strict()
+        .optional()
+        .default({
+        max_parallel_tasks: 1,
+        disallow_same_file_parallel_writes: true,
+    }),
+})
+    .strict();

package/dist/worker/task-graph/types.js

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

package/dist/worker/task-graph/validate.js

@@ -0,0 +1,188 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { acceptanceSpecSchema } from "./acceptance-schema.js";
+import { computeReadyQueue } from "./ready-queue.js";
+import { taskGraphSpecSchema } from "./task-graph-schema.js";
+export async function validateFeatureTaskGraph(featureDir, options = {}) {
+    const errors = [];
+    const acceptance = await loadAcceptanceSpec(featureDir, options, errors);
+    const graph = await loadTaskGraphSpec(featureDir, options, errors);
+    if (!acceptance || !graph) {
+        return result("", acceptance, graph, errors);
+    }
+    checkDuplicateNodeIds(graph, errors);
+    checkAcceptanceTaskRefs(acceptance, graph, errors);
+    checkUnknownDependencies(graph, errors);
+    checkCycles(graph, errors);
+    await checkTaskFiles(featureDir, graph, errors);
+    return result(graph.feature_id, acceptance, graph, errors);
+}
+async function loadAcceptanceSpec(featureDir, options, errors) {
+    const raw = options.acceptanceOverride ??
+        YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8"));
+    const parsed = acceptanceSpecSchema.safeParse(raw);
+    if (!parsed.success) {
+        errors.push({
+            code: "acceptance-schema-invalid",
+            message: parsed.error.issues.map((issue) => issue.message).join("; "),
+            path: "acceptance.yaml",
+        });
+        return undefined;
+    }
+    return parsed.data;
+}
+async function loadTaskGraphSpec(featureDir, options, errors) {
+    const raw = options.graphOverride ??
+        YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8"));
+    const parsed = taskGraphSpecSchema.safeParse(raw);
+    if (!parsed.success) {
+        errors.push({
+            code: "task-graph-schema-invalid",
+            message: parsed.error.issues.map((issue) => issue.message).join("; "),
+            path: "tasks/task-graph.yaml",
+        });
+        return undefined;
+    }
+    return parsed.data;
+}
+function checkDuplicateNodeIds(graph, errors) {
+    const seen = new Set();
+    for (const node of graph.nodes) {
+        if (seen.has(node.id)) {
+            errors.push({
+                code: "duplicate-node-id",
+                message: `duplicate task graph node id: ${node.id}`,
+                path: `nodes.${node.id}`,
+            });
+        }
+        seen.add(node.id);
+    }
+}
+function checkAcceptanceTaskRefs(acceptance, graph, errors) {
+    const nodeIds = new Set(graph.nodes.map((node) => node.id));
+    for (const item of acceptance.acceptance) {
+        for (const taskRef of item.verification.expected_task_refs) {
+            if (!nodeIds.has(taskRef)) {
+                errors.push({
+                    code: "acceptance-task-ref-missing",
+                    message: `acceptance ${item.id} references missing task ${taskRef}`,
+                    path: `acceptance.${item.id}.verification.expected_task_refs`,
+                });
+            }
+        }
+    }
+}
+function checkUnknownDependencies(graph, errors) {
+    const nodeIds = new Set(graph.nodes.map((node) => node.id));
+    for (const node of graph.nodes) {
+        for (const dependency of node.depends_on) {
+            if (!nodeIds.has(dependency)) {
+                errors.push({
+                    code: "unknown-dependency",
+                    message: `${node.id} depends on unknown task ${dependency}`,
+                    path: `nodes.${node.id}.depends_on`,
+                });
+            }
+        }
+    }
+}
+function checkCycles(graph, errors) {
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (nodeId, trail) => {
+        if (visiting.has(nodeId)) {
+            errors.push({
+                code: "cycle-detected",
+                message: `cycle detected: ${[...trail, nodeId].join(" -> ")}`,
+                path: `nodes.${nodeId}.depends_on`,
+            });
+            return;
+        }
+        if (visited.has(nodeId))
+            return;
+        const node = nodes.get(nodeId);
+        if (!node)
+            return;
+        visiting.add(nodeId);
+        for (const dependency of node.depends_on)
+            visit(dependency, [...trail, nodeId]);
+        visiting.delete(nodeId);
+        visited.add(nodeId);
+    };
+    for (const node of graph.nodes)
+        visit(node.id, []);
+}
+async function checkTaskFiles(featureDir, graph, errors) {
+    for (const node of graph.nodes) {
+        const taskPath = path.join(featureDir, "tasks", node.task);
+        if (!(await exists(taskPath))) {
+            errors.push({
+                code: "task-file-missing",
+                message: `task file does not exist: ${node.task}`,
+                path: `nodes.${node.id}.task`,
+            });
+            continue;
+        }
+        const parsedTask = taskSpecSchema.safeParse(YAML.parse(await readFile(taskPath, "utf-8")));
+        if (!parsedTask.success) {
+            errors.push({
+                code: "task-spec-schema-invalid",
+                message: `task file is not a valid TaskSpec: ${node.task}`,
+                path: `nodes.${node.id}.task`,
+            });
+            continue;
+        }
+        const taskSpec = parsedTask.data;
+        if (taskSpec.id !== node.id) {
+            errors.push({
+                code: "task-id-mismatch",
+                message: `graph node ${node.id} points at TaskSpec ${taskSpec.id}`,
+                path: `nodes.${node.id}.id`,
+            });
+        }
+        if (taskSpec.type !== node.type) {
+            errors.push({
+                code: "task-type-mismatch",
+                message: `graph node ${node.id} type ${node.type} differs from TaskSpec ${taskSpec.type}`,
+                path: `nodes.${node.id}.type`,
+            });
+        }
+        if (!sameStringSet(taskSpec.depends_on, node.depends_on)) {
+            errors.push({
+                code: "task-depends-on-mismatch",
+                message: `graph node ${node.id} depends_on differs from TaskSpec`,
+                path: `nodes.${node.id}.depends_on`,
+            });
+        }
+    }
+}
+function result(featureId, acceptance, graph, errors) {
+    return {
+        ok: errors.length === 0,
+        featureId,
+        summary: {
+            acceptanceCount: acceptance?.acceptance.length ?? 0,
+            nodeCount: graph?.nodes.length ?? 0,
+            readyWithoutState: graph ? computeReadyQueue(graph, {}) : [],
+        },
+        errors,
+    };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sameStringSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const rightSet = new Set(right);
+    return left.every((value) => rightSet.has(value));
+}

package/dist/worker/task-spec/complexity-mapping.js

@@ -0,0 +1,8 @@
+const RISK_TO_COMPLEXITY = {
+    low: "small",
+    medium: "medium",
+    high: "large",
+};
+export function mapRiskLevelToComplexity(riskLevel) {
+    return RISK_TO_COMPLEXITY[riskLevel];
+}

package/dist/worker/task-spec/schema.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { verifyModeSchema, verifyPresetSchema, verifyQuotaSchema, } from "../../task/config-types.js";
+export const taskSpecTypeSchema = z.enum([
+    "architecture",
+    "backend-feature",
+    "frontend-feature",
+    "bugfix",
+    "ci-fix",
+    "doc-update",
+    "qa-analysis",
+    "qa-casegen",
+    "qa-testcode",
+    "qa-execute",
+    "qa-failure-analysis",
+    "reviewer-gate",
+    "fix-from-failure",
+]);
+export const taskSpecRiskLevelSchema = z.enum(["low", "medium", "high"]);
+const verifyCommandSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    command: z.string().min(1),
+    required: z.boolean().optional().default(true),
+    timeout_ms: z.number().int().positive().optional(),
+})
+    .strict();
+export const taskSpecSchema = z
+    .object({
+    schema_version: z.literal(1),
+    id: z.string().min(1),
+    feature_id: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().optional().default(""),
+    repo: z
+        .object({
+        name: z.string().min(1),
+        path_ref: z.string().min(1),
+        default_branch: z.string().min(1).optional(),
+    })
+        .strict(),
+    type: taskSpecTypeSchema,
+    priority: z.enum(["P0", "P1", "P2", "P3"]).optional().default("P2"),
+    risk_level: taskSpecRiskLevelSchema,
+    depends_on: z.array(z.string().min(1)).optional().default([]),
+    source_docs: z
+        .object({
+        requirement: z.string().min(1),
+        acceptance: z.string().min(1),
+        design: z.string().min(1).optional(),
+        test_plan: z.string().min(1).optional(),
+        test_cases: z.string().min(1).optional(),
+    })
+        .strict(),
+    acceptance_refs: z.array(z.string().min(1)).min(1),
+    scope: z
+        .object({
+        goals: z.array(z.string().min(1)).min(1),
+        non_goals: z.array(z.string().min(1)).optional().default([]),
+        assumptions: z.array(z.string().min(1)).optional().default([]),
+        open_questions: z.array(z.string().min(1)).optional().default([]),
+    })
+        .strict(),
+    constraints: z
+        .object({
+        allowed_paths: z.array(z.string().min(1)).optional().default([]),
+        forbidden_paths: z.array(z.string().min(1)).optional().default([]),
+        hard_constraints: z.array(z.string().min(1)).optional().default([]),
+    })
+        .strict(),
+    verify: z
+        .object({
+        preset: verifyPresetSchema,
+        mode: verifyModeSchema,
+        quota: verifyQuotaSchema.optional().default("full"),
+        commands: z.array(verifyCommandSchema).optional().default([]),
+    })
+        .strict(),
+    worker: z
+        .object({
+        execution_mode: z.enum([
+            "dry-run",
+            "generate-only",
+            "generate-validate",
+            "generate-validate-run",
+        ]),
+        max_attempts: z.number().int().positive().optional().default(1),
+        timeout_ms: z.number().int().positive().optional(),
+        require_clean_worktree: z.boolean().optional().default(true),
+        require_human_review: z.boolean().optional().default(true),
+        create_worktree: z.boolean().optional().default(false),
+    })
+        .strict(),
+    loop_agent: z
+        .object({
+        profile_policy: z.literal("mapped"),
+        strict_models: z.boolean().optional().default(true),
+        strict_governance: z.boolean().optional().default(true),
+        no_cursor: z.boolean().optional().default(false),
+        max_concurrent: z.number().int().positive().optional().default(1),
+    })
+        .strict(),
+    outputs: z
+        .object({
+        required: z.array(z.string().min(1)).min(1),
+    })
+        .strict(),
+    failure_policy: z
+        .object({
+        failed_run_promote: z.boolean().optional().default(false),
+        generate_closeout_draft: z.boolean().optional().default(true),
+        create_followup_task: z.boolean().optional().default(true),
+    })
+        .strict(),
+})
+    .strict();

package/dist/worker/task-spec/types.js

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