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

package/dist/commands/task-advance.js

@@ -0,0 +1,366 @@
+import { advanceTaskLifecycle, } from "../application/task-lifecycle/index.js";
+import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
+import { createRunDagProgressObserver, validateRunDagProgressIntervalMs, } from "./run-dag-progress.js";
+const COMMAND = "task advance";
+const USAGE = `usage:
+  task advance <task-id> [title]
+    [--prd <path>]...
+    [--role <role>]...
+    [--from-text <string>]
+    [--from-draft <TaskContractDraftV1.json>]
+    [--task-kind <kind>]
+    [--feature-id <id>]
+    [--allowed-path <glob>]...
+    [--forbidden-path <glob>]...
+    [--verify <label:command>]...
+    [--verify-timeout <label:timeoutMs>]...
+    [--accept-recommendations <digest>]
+    [--approve-gate <gate-id:digest>]
+    [--reject-gate <gate-id:digest> --reason <text>]
+    [--profile auto|minimal|standard|reviewed|supervised]
+    [--max-concurrent <n>]
+    [--run-id <id>]
+    [--events-jsonl <path>]
+    [--worker-association <json>]
+    [--dag-output <path>]
+    [--skip-finalize]
+    [--no-strict-models]
+    [--quiet]
+    [--progress-interval-ms <ms>]
+    [--dry-run]
+    [--json]`;
+function pushList(target, value) {
+    const list = target ?? [];
+    list.push(value);
+    return list;
+}
+function parseVerify(flag) {
+    const idx = flag.indexOf(":");
+    if (idx <= 0 || idx === flag.length - 1) {
+        throw new Error(`invalid --verify ${flag}; expected label:command`);
+    }
+    return { label: flag.slice(0, idx), command: flag.slice(idx + 1) };
+}
+function parseVerifyTimeout(flag) {
+    const idx = flag.indexOf(":");
+    if (idx <= 0 || idx === flag.length - 1) {
+        throw new Error(`invalid --verify-timeout ${flag}; expected label:timeoutMs`);
+    }
+    const timeoutMs = Number(flag.slice(idx + 1));
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error(`invalid --verify-timeout ${flag}; timeoutMs must be > 0`);
+    }
+    return { label: flag.slice(0, idx), timeoutMs };
+}
+export function parseTaskAdvanceArgs(args) {
+    const options = {};
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        const next = () => {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                throw new Error(`missing value for ${token}\n${USAGE}`);
+            }
+            i += 1;
+            return value;
+        };
+        if (token === "--json") {
+            options.json = true;
+            continue;
+        }
+        if (token === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (token === "--prd") {
+            options.prdPaths = pushList(options.prdPaths, next());
+            continue;
+        }
+        if (token === "--role") {
+            options.roles = pushList(options.roles, next());
+            continue;
+        }
+        if (token === "--from-text") {
+            options.fromText = next();
+            continue;
+        }
+        if (token === "--from-draft") {
+            options.fromDraft = next();
+            continue;
+        }
+        if (token === "--task-kind") {
+            options.taskKind = next();
+            continue;
+        }
+        if (token === "--feature-id") {
+            options.featureId = next();
+            continue;
+        }
+        if (token === "--allowed-path") {
+            options.allowedPaths = pushList(options.allowedPaths, next());
+            continue;
+        }
+        if (token === "--forbidden-path") {
+            options.forbiddenPaths = pushList(options.forbiddenPaths, next());
+            continue;
+        }
+        if (token === "--verify") {
+            options.verify = pushList(options.verify, next());
+            continue;
+        }
+        if (token === "--verify-timeout") {
+            options.verifyTimeout = pushList(options.verifyTimeout, next());
+            continue;
+        }
+        if (token === "--accept-recommendations") {
+            options.acceptRecommendations = next();
+            continue;
+        }
+        if (token === "--approve-gate") {
+            options.approveGate = next();
+            continue;
+        }
+        if (token === "--reject-gate") {
+            options.rejectGate = next();
+            continue;
+        }
+        if (token === "--reason") {
+            options.reason = next();
+            continue;
+        }
+        if (token === "--profile") {
+            const value = next();
+            if (value !== "auto" &&
+                value !== "minimal" &&
+                value !== "standard" &&
+                value !== "reviewed" &&
+                value !== "supervised") {
+                throw new Error(`--profile must be auto|minimal|standard|reviewed|supervised\n${USAGE}`);
+            }
+            options.profile = value;
+            continue;
+        }
+        if (token === "--max-concurrent") {
+            const value = Number(next());
+            if (!Number.isFinite(value) || value <= 0) {
+                throw new Error(`--max-concurrent must be a positive number\n${USAGE}`);
+            }
+            options.maxConcurrent = value;
+            continue;
+        }
+        if (token === "--run-id") {
+            options.runId = next();
+            continue;
+        }
+        if (token === "--events-jsonl") {
+            options.eventsJsonlPath = next();
+            continue;
+        }
+        if (token === "--worker-association") {
+            options.workerAssociation = next();
+            continue;
+        }
+        if (token === "--dag-output") {
+            options.dagOutputPath = next();
+            continue;
+        }
+        if (token === "--skip-finalize") {
+            options.skipFinalize = true;
+            continue;
+        }
+        if (token === "--no-strict-models") {
+            options.strictModels = false;
+            continue;
+        }
+        if (token === "--quiet") {
+            options.quiet = true;
+            continue;
+        }
+        if (token === "--progress-interval-ms") {
+            const raw = next();
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed)) {
+                throw new Error(`progress-interval-ms must be an integer >= 1000\n${USAGE}`);
+            }
+            options.progressIntervalMs = validateRunDagProgressIntervalMs(parsed);
+            continue;
+        }
+        if (token === "--help" || token === "-h") {
+            throw new Error(USAGE);
+        }
+        if (token.startsWith("-")) {
+            throw new Error(`unknown flag ${token}\n${USAGE}`);
+        }
+        positional.push(token);
+    }
+    const taskId = positional[0];
+    if (!taskId)
+        throw new Error(USAGE);
+    if (positional.length > 1) {
+        options.title = positional.slice(1).join(" ");
+    }
+    return { taskId, options };
+}
+function mapOutcome(result) {
+    if (result.blockers.length > 0) {
+        const code = result.blockers[0]?.code ?? "";
+        if (code === "STALE_GATE" || code.includes("CONFLICT"))
+            return "conflict";
+        if (code === "INTAKE_REQUIRED" || code === "INVALID_DRAFT")
+            return "invalid";
+        if (code === "NOT_FOUND" || code === "TASK_NOT_FOUND")
+            return "not-found";
+        return "blocked";
+    }
+    if (result.lifecycleState === "awaiting-write-set-approval") {
+        // Shared operator outcomes do not include awaiting-approval; use blocked
+        // with result.gate so machine clients can branch on lifecycleState/gate.
+        return "blocked";
+    }
+    if (result.lifecycleState === "needs-attention")
+        return "needs-reconcile";
+    if (result.lifecycleState === "run-failed")
+        return "blocked";
+    return "succeeded";
+}
+export function toUseCaseInput(repoRoot, taskId, options, observer) {
+    const timeouts = new Map((options.verifyTimeout ?? []).map((entry) => {
+        const parsed = parseVerifyTimeout(entry);
+        return [parsed.label, parsed.timeoutMs];
+    }));
+    const verifyCommands = (options.verify ?? []).map((entry) => {
+        const parsed = parseVerify(entry);
+        const timeoutMs = timeouts.get(parsed.label);
+        return timeoutMs
+            ? { ...parsed, timeoutMs }
+            : { label: parsed.label, command: parsed.command };
+    });
+    const roles = options.roles ?? [];
+    const prdPaths = (options.prdPaths ?? []).map((filePath, index) => ({
+        filePath,
+        role: roles[index],
+    }));
+    let workerAssociation;
+    if (options.workerAssociation) {
+        let parsed;
+        try {
+            parsed = JSON.parse(options.workerAssociation);
+        }
+        catch {
+            throw new Error("--worker-association must be valid JSON {schemaVersion:1,workerRunId,featureId,taskId}");
+        }
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.schemaVersion !== 1 ||
+            typeof parsed.workerRunId !== "string" ||
+            typeof parsed.featureId !== "string" ||
+            typeof parsed.taskId !== "string") {
+            throw new Error("--worker-association must be JSON {schemaVersion:1,workerRunId,featureId,taskId}");
+        }
+        workerAssociation = parsed;
+    }
+    return {
+        repoRoot,
+        taskId,
+        title: options.title,
+        prdPaths: prdPaths.length > 0 ? prdPaths : undefined,
+        fromText: options.fromText,
+        fromDraftPath: options.fromDraft,
+        taskKind: options.taskKind,
+        taskKindExplicit: Boolean(options.taskKind?.trim()),
+        featureId: options.featureId,
+        allowedPaths: options.allowedPaths,
+        forbiddenPaths: options.forbiddenPaths,
+        verifyCommands: verifyCommands.length > 0 ? verifyCommands : undefined,
+        approveGateToken: options.approveGate,
+        rejectGateToken: options.rejectGate,
+        rejectReason: options.reason,
+        acceptRecommendationsDigest: options.acceptRecommendations,
+        dryRun: options.dryRun,
+        profile: options.profile,
+        profileExplicit: Boolean(options.profile),
+        maxConcurrent: options.maxConcurrent,
+        runId: options.runId,
+        eventsJsonlPath: options.eventsJsonlPath,
+        workerAssociation,
+        dagOutputPath: options.dagOutputPath,
+        skipFinalize: options.skipFinalize,
+        strictModels: options.strictModels,
+        ...(observer ? { observer } : {}),
+        onProgress: options.quiet
+            ? undefined
+            : (message) => {
+                process.stderr.write(`[task advance] ${message}\n`);
+            },
+    };
+}
+export async function runTaskAdvance(repoRoot, args) {
+    let taskId;
+    let options;
+    try {
+        ({ taskId, options } = parseTaskAdvanceArgs(args));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const envelope = operatorFailed({
+            command: COMMAND,
+            outcome: "invalid",
+            code: "INVALID_INPUT",
+            message,
+        });
+        writeOperatorJson(envelope);
+        process.exitCode = processExitCodeForOutcome(envelope.outcome);
+        return;
+    }
+    let progress;
+    try {
+        // AC-006/AC-007: periodic DAG progress goes to stderr only (stdout stays
+        // the single final OperatorCommandResultV1 JSON). The observer is created
+        // ONLY for the approve-gate execution path and disposed on every exit;
+        // its timer starts only after onRunStart (double guard, no stray timer).
+        if (options.approveGate && !options.dryRun && !options.quiet) {
+            progress = createRunDagProgressObserver({
+                intervalMs: options.progressIntervalMs,
+            });
+        }
+        const result = await advanceTaskLifecycle(toUseCaseInput(repoRoot, taskId, options, progress?.observer));
+        const outcome = mapOutcome(result);
+        const gateStop = result.lifecycleState === "awaiting-write-set-approval" &&
+            result.blockers.length === 0;
+        const createOnlyStop = result.lifecycleState === "intake-incomplete" &&
+            result.blockers.length === 0 &&
+            (result.completedTransitions.includes("task-created") ||
+                result.completedTransitions.includes("prd-imported"));
+        const ok = outcome === "succeeded" || gateStop || createOnlyStop;
+        const envelope = buildOperatorResult({
+            command: COMMAND,
+            ok,
+            // awaiting write-set approval is a successful stop condition for
+            // the first advance call; keep outcome blocked for machine branch
+            // but ok=true when no blockers.
+            outcome: gateStop ? "blocked" : createOnlyStop ? "succeeded" : outcome,
+            result,
+            warnings: result.warnings,
+        });
+        writeOperatorJson(envelope);
+        process.exitCode =
+            envelope.ok && envelope.outcome === "blocked"
+                ? 0
+                : processExitCodeForOutcome(envelope.outcome);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const envelope = operatorFailed({
+            command: COMMAND,
+            outcome: "blocked",
+            code: "INTERNAL_ERROR",
+            message,
+        });
+        writeOperatorJson(envelope);
+        process.exitCode = processExitCodeForOutcome(envelope.outcome);
+    }
+    finally {
+        progress?.dispose();
+    }
+}

package/dist/commands/task-contract.js

@@ -0,0 +1,269 @@
+import { ContractMutationError, adoptTaskContract, applyTaskContract, diffTaskContract, doctorTaskContract, loadDraftFromPath, observeTaskContractState, recoverTaskContract, validateDraftForTask, } from "../task/contract/index.js";
+import { operatorFailed, operatorSucceeded, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
+const USAGE = `usage:
+  task contract validate --task <id> --input <path> [--json]
+  task contract diff --task <id> --input <path> [--json]
+
+Advanced-only public leaves. Managed apply/show/adopt/doctor/recover are internal services
+reached via task advance / task status (or application APIs), not public CLI subcommands.`;
+export function parseTaskContractArgs(args) {
+    const options = {};
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--json") {
+            options.json = true;
+            continue;
+        }
+        if (token === "--task") {
+            options.task = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token === "--input") {
+            options.input = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token === "--expected-revision") {
+            const raw = args[i + 1];
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n < 0) {
+                throw new Error(`invalid --expected-revision: ${raw}`);
+            }
+            options.expectedRevision = n;
+            i += 1;
+            continue;
+        }
+        if (token === "--expected-observed-hash") {
+            options.expectedObservedHash = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token === "--request-id") {
+            options.requestId = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token === "--request-payload-sha256") {
+            options.requestPayloadSha256 = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token === "--tx-id") {
+            options.txId = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw new Error(`unknown flag ${token}\n${USAGE}`);
+        }
+        positional.push(token);
+    }
+    const subcommand = positional[0];
+    if (!subcommand) {
+        throw new Error(USAGE);
+    }
+    // show takes positional taskId; others prefer --task
+    let taskId = options.task;
+    if (subcommand === "show") {
+        taskId = positional[1] ?? options.task;
+    }
+    return { subcommand, taskId, options };
+}
+function mutationOutcome(code) {
+    switch (code) {
+        case "REVISION_CONFLICT":
+        case "OBSERVED_HASH_CONFLICT":
+        case "REQUEST_ID_REUSE_CONFLICT":
+        case "LEASE_HELD":
+            return "conflict";
+        case "NOT_FOUND":
+            return "not-found";
+        case "TRANSACTION_INCOMPLETE":
+        case "OPERATION_NEEDS_RECONCILE":
+            return "needs-reconcile";
+        case "EXTERNALLY_MODIFIED":
+        case "NOT_MANAGED":
+        case "BINDING_DRIFT":
+            return "blocked";
+        case "INVALID_INPUT":
+        case "PATH_OUTSIDE_REPO":
+        case "UNSUPPORTED_SCHEMA_VERSION":
+            return "invalid";
+        default:
+            return "rejected";
+    }
+}
+function emit(result, json) {
+    // Machine envelope is the default for task contract when --json is set;
+    // without --json still print the same document for dogfood consistency.
+    writeOperatorJson(result);
+    if (!json) {
+        // already wrote JSON; human path same for Phase 0.5
+    }
+    process.exitCode = processExitCodeForOutcome(result.outcome);
+}
+export async function runTaskContract(repoRoot, args) {
+    let subcommand;
+    let taskId;
+    let options;
+    try {
+        ({ subcommand, taskId, options } = parseTaskContractArgs(args));
+    }
+    catch (error) {
+        const result = operatorFailed({
+            command: "task contract",
+            outcome: "invalid",
+            code: "INVALID_INPUT",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        emit(result, true);
+        return;
+    }
+    const command = `task contract ${subcommand}`;
+    try {
+        switch (subcommand) {
+            case "show": {
+                if (!taskId) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract show requires <taskId>");
+                }
+                const state = await observeTaskContractState(repoRoot, taskId);
+                const result = operatorSucceeded(command, { taskId, state });
+                emit(result, options.json);
+                return;
+            }
+            case "validate": {
+                if (!taskId || !options.input) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract validate requires --task and --input");
+                }
+                const { draft } = await loadDraftFromPath(options.input, repoRoot);
+                const validation = await validateDraftForTask({
+                    repoRoot,
+                    taskId,
+                    draft,
+                });
+                if (!validation.ok) {
+                    const result = operatorFailed({
+                        command,
+                        outcome: "invalid",
+                        code: "INVALID_INPUT",
+                        message: validation.errors.join("; "),
+                        details: { errors: validation.errors },
+                    });
+                    emit(result, options.json);
+                    return;
+                }
+                const result = operatorSucceeded(command, {
+                    taskId,
+                    valid: true,
+                    warnings: validation.warnings,
+                });
+                emit(result, options.json);
+                return;
+            }
+            case "diff": {
+                if (!taskId || !options.input) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract diff requires --task and --input");
+                }
+                const { draft } = await loadDraftFromPath(options.input, repoRoot);
+                const diff = await diffTaskContract({ repoRoot, taskId, draft });
+                const result = operatorSucceeded(command, diff);
+                emit(result, options.json);
+                return;
+            }
+            case "apply": {
+                if (!taskId ||
+                    !options.input ||
+                    options.expectedRevision === undefined ||
+                    !options.expectedObservedHash ||
+                    !options.requestId ||
+                    !options.requestPayloadSha256) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract apply requires --task --input --expected-revision --expected-observed-hash --request-id --request-payload-sha256");
+                }
+                const loaded = await loadDraftFromPath(options.input, repoRoot);
+                // Client-supplied payload hash must match file bytes
+                if (loaded.payloadSha256 !== options.requestPayloadSha256) {
+                    throw new ContractMutationError("INVALID_INPUT", `request-payload-sha256 does not match input file hash (expected ${loaded.payloadSha256})`);
+                }
+                const applyResult = await applyTaskContract({
+                    repoRoot,
+                    taskId,
+                    draft: loaded.draft,
+                    expectedRevision: options.expectedRevision,
+                    expectedObservedHash: options.expectedObservedHash,
+                    requestId: options.requestId,
+                    requestPayloadSha256: options.requestPayloadSha256,
+                    rawDraftText: loaded.rawText,
+                });
+                const result = operatorSucceeded(command, applyResult);
+                emit(result, options.json);
+                return;
+            }
+            case "adopt": {
+                if (!taskId ||
+                    options.expectedRevision === undefined ||
+                    !options.expectedObservedHash ||
+                    !options.requestId ||
+                    !options.requestPayloadSha256) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract adopt requires --task --expected-revision --expected-observed-hash --request-id --request-payload-sha256");
+                }
+                const adoptResult = await adoptTaskContract({
+                    repoRoot,
+                    taskId,
+                    expectedRevision: options.expectedRevision,
+                    expectedObservedHash: options.expectedObservedHash,
+                    requestId: options.requestId,
+                    requestPayloadSha256: options.requestPayloadSha256,
+                });
+                const result = operatorSucceeded(command, adoptResult);
+                emit(result, options.json);
+                return;
+            }
+            case "doctor": {
+                if (!taskId) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract doctor requires --task");
+                }
+                const doctor = await doctorTaskContract({ repoRoot, taskId });
+                const result = operatorSucceeded(command, doctor);
+                emit(result, options.json);
+                return;
+            }
+            case "recover": {
+                if (!taskId) {
+                    throw new ContractMutationError("INVALID_INPUT", "task contract recover requires --task");
+                }
+                const recover = await recoverTaskContract({
+                    repoRoot,
+                    taskId,
+                    txId: options.txId,
+                });
+                const result = operatorSucceeded(command, recover);
+                emit(result, options.json);
+                return;
+            }
+            default:
+                throw new ContractMutationError("INVALID_INPUT", `unknown task contract subcommand: ${subcommand}\n${USAGE}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof ContractMutationError) {
+            const result = operatorFailed({
+                command,
+                outcome: mutationOutcome(error.code),
+                code: error.code,
+                message: error.message,
+                details: error.details,
+            });
+            emit(result, options.json);
+            return;
+        }
+        const result = operatorFailed({
+            command,
+            outcome: "rejected",
+            code: "INTERNAL_ERROR",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        emit(result, options.json);
+    }
+}