@tea-agent/loop-agent 0.26.5-beta.2 → 0.27.0

package/dist/commands/task-advance.js

@@ -0,0 +1,335 @@
+import { advanceTaskLifecycle, } from "../application/task-lifecycle/index.js";
+import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.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]
+    [--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 === "--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";
+}
+function toUseCaseInput(repoRoot, taskId, options) {
+    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,
+        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,
+        onProgress: options.json
+            ? 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;
+    }
+    try {
+        const result = await advanceTaskLifecycle(toUseCaseInput(repoRoot, taskId, options));
+        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);
+    }
+}

package/dist/commands/task-contract.js

@@ -1,13 +1,11 @@
 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 show <taskId> [--json]
   task contract validate --task <id> --input <path> [--json]
   task contract diff --task <id> --input <path> [--json]
-  task contract apply --task <id> --input <path> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> [--json]
-  task contract adopt --task <id> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> [--json]
-  task contract doctor --task <id> [--json]
-  task contract recover --task <id> [--tx-id <id>] [--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 = [];

package/dist/commands/task-source-prepare.js

@@ -205,13 +205,13 @@ function validateOptionCombinations(options) {
         throw new Error(`need at least one intent source: --use-imported-prd, --from-text/--from-file/--from-stdin, --from-draft, or sufficient flags (title/objective + --ac + --allowed-path)\n${USAGE}`);
     }
 }
-async function readStdinText() {
-    if (stdinStream.isTTY) {
+export async function readTaskSourcePrepareStdin(stream = stdinStream) {
+    if (stream.isTTY) {
         throw new Error("--from-stdin refused on TTY; pipe input or use --from-file/--from-text");
     }
     const chunks = [];
     let total = 0;
-    for await (const chunk of stdinStream) {
+    for await (const chunk of stream) {
         const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
         total += buf.byteLength;
         if (total > PREPARE_MAX_FILE_BYTES) {
@@ -239,7 +239,7 @@ async function loadTextInput(repoRoot, options) {
         return { text: raw.toString("utf-8"), label: options.fromFile };
     }
     if (options.fromStdin) {
-        const text = await readStdinText();
+        const text = await readTaskSourcePrepareStdin();
         return { text, label: "stdin" };
     }
     return {};
@@ -386,6 +386,11 @@ function printHuman(result) {
     console.log(lines.join("\n"));
 }
 export async function runTaskSourcePrepare(repoRoot, args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        process.exitCode = 0;
+        return;
+    }
     let taskId;
     let options = {};
     try {

package/dist/commands/task-status.js

@@ -0,0 +1,133 @@
+import { observeTaskLifecycle } from "../application/task-lifecycle/index.js";
+import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
+const COMMAND = "task status";
+const USAGE = `usage:
+  task status <task-id> [--json|--markdown] [--details]`;
+export function parseTaskStatusArgs(args) {
+    const options = {};
+    const positional = [];
+    for (const token of args) {
+        if (token === "--json") {
+            options.json = true;
+            continue;
+        }
+        if (token === "--markdown") {
+            options.markdown = true;
+            continue;
+        }
+        if (token === "--details") {
+            options.details = true;
+            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 || positional.length > 1)
+        throw new Error(USAGE);
+    return { taskId, options };
+}
+function formatMarkdown(snapshot, details) {
+    const lines = [
+        `# Task ${snapshot.taskId}`,
+        "",
+        `- lifecycleState: \`${snapshot.lifecycleState}\``,
+        `- exists: ${snapshot.exists}`,
+    ];
+    if (snapshot.title)
+        lines.push(`- title: ${snapshot.title}`);
+    if (snapshot.contract) {
+        lines.push(`- contract: ${snapshot.contract.effectiveStatus} rev=${snapshot.contract.revision ?? "n/a"}`);
+    }
+    if (snapshot.dagDraft) {
+        lines.push(`- dagDraft: exists=${snapshot.dagDraft.exists} strictValidated=${snapshot.dagDraft.strictValidated}`);
+        if (details && snapshot.dagDraft.writeSet.length > 0) {
+            lines.push(`- writeSet: ${snapshot.dagDraft.writeSet.join(", ")}`);
+        }
+    }
+    if (snapshot.gate) {
+        lines.push(`- gate: ${snapshot.gate.id} digest=${snapshot.gate.digest}`);
+        lines.push(`- approve: \`${snapshot.gate.approveCommand}\``);
+    }
+    if (snapshot.activeRun) {
+        lines.push(`- activeRun: ${snapshot.activeRun.runId} (${snapshot.activeRun.lifecycle}/${snapshot.activeRun.status ?? "?"})`);
+    }
+    if (snapshot.latestRun) {
+        lines.push(`- latestRun: ${snapshot.latestRun.runId} (${snapshot.latestRun.lifecycle}/${snapshot.latestRun.status ?? "?"})`);
+    }
+    if (snapshot.next.kind === "none") {
+        lines.push("- next: none");
+    }
+    else if (snapshot.next.kind === "external-action") {
+        lines.push(`- next: ${snapshot.next.description}`);
+    }
+    else {
+        lines.push(`- next: \`${snapshot.next.command}\``);
+    }
+    if (details && snapshot.completedTransitions.length > 0) {
+        lines.push("", "## completedTransitions", "");
+        for (const transition of snapshot.completedTransitions) {
+            lines.push(`- ${transition}`);
+        }
+    }
+    if (snapshot.blockers.length > 0) {
+        lines.push("", "## blockers", "");
+        for (const blocker of snapshot.blockers) {
+            lines.push(`- ${blocker.code}: ${blocker.message}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function runTaskStatus(repoRoot, args) {
+    let taskId;
+    let options;
+    try {
+        ({ taskId, options } = parseTaskStatusArgs(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;
+    }
+    try {
+        const snapshot = await observeTaskLifecycle(repoRoot, taskId);
+        if (options.markdown && !options.json) {
+            process.stdout.write(formatMarkdown(snapshot, Boolean(options.details)));
+            process.exitCode = snapshot.exists ? 0 : 2;
+            return;
+        }
+        const envelope = buildOperatorResult({
+            command: COMMAND,
+            ok: true,
+            outcome: snapshot.exists ? "succeeded" : "not-found",
+            result: snapshot,
+        });
+        // status is read-only; missing task is still a valid observation.
+        envelope.ok = true;
+        writeOperatorJson(envelope);
+        process.exitCode = snapshot.exists ? 0 : 2;
+    }
+    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);
+    }
+}

package/dist/governance/manifest-types.js

@@ -90,9 +90,9 @@ export const workflowPolicySchema = z
             .optional()
             .default("zh-CN"),
         defaultEntry: z
-            .enum(["dag run-task", "run-dag"])
+            .enum(["task advance", "dag execute"])
             .optional()
-            .default("dag run-task"),
+            .default("task advance"),
         profileRouting: z
             .object({
             minimal: workflowPolicyDagTemplateSchema