@tea-agent/loop-agent 0.28.2-beta.1 → 0.28.3

package/dist/worker/scheduler/cli.js

@@ -0,0 +1,539 @@
+import path from "node:path";
+import { LoopAgentClient } from "../loop-agent/loop-agent-client.js";
+import { addSchedule, cancelScheduledReservation, prepareAdmission, } from "./admission.js";
+import { getScheduleStatus, listScheduleSnapshots, submitSchedule, transitionSchedule, } from "./lifecycle.js";
+import { diagnoseScheduler, formatSchedulerDoctorHuman } from "./doctor.js";
+import { readAdmission, readLedgerEvents, recoverAllPendingJournals, } from "./store.js";
+import { discardNightSchedule, harvestNightSchedule } from "./night-harvest.js";
+import { schedulerTick } from "./scheduler-loop.js";
+import { scheduleStatusSchema, SchedulerError, } from "./types.js";
+import { parseOnceLocalToUtc } from "./trigger.js";
+/**
+ * Register `agent-worker scheduler` + `admission` commands.
+ * Phase 2: prepare + add + cancel reservation. Live tick lands in Phase 3.
+ */
+export function registerSchedulerCommands(program) {
+    const admission = program
+        .command("admission")
+        .description("Night Scheduler admission prepare / inspect (daytime planning)");
+    admission
+        .command("prepare")
+        .description("Create schedule worktree, materialize/validate DAG to writeSet gate, freeze admission")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .requiredOption("--feature-dir <path>", "Feature directory")
+        .requiredOption("--task-id <task-id>", "TaskSpec id")
+        .requiredOption("--at <local-time>", 'Local execute time "YYYY-MM-DD HH:mm"')
+        .option("--tz <timezone>", "IANA timezone for --at", "Asia/Shanghai")
+        .option("--task-card <ref>", "Task card / work item ref")
+        .option("--loop-agent-bin <path>", "Published loop-agent binary")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const controlRepoRoot = path.resolve(options.repo);
+            const client = new LoopAgentClient({
+                loopAgentBin: options.loopAgentBin ?? "loop-agent",
+                artifactRoot: path.join(controlRepoRoot, ".harness", "task-pool", "scheduler", "client-artifacts"),
+                resolveIdentity: true,
+            });
+            const result = await prepareAdmission({
+                controlRepoRoot,
+                featureDir: options.featureDir,
+                taskId: options.taskId,
+                at: options.at,
+                timezone: options.tz,
+                ...(options.taskCard ? { taskCard: options.taskCard } : {}),
+                client,
+            });
+            emit(options.json, result, () => formatReviewPacketHuman(result.reviewPacket));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    admission
+        .command("show")
+        .description("Show frozen admission for a schedule")
+        .argument("<schedule-id>", "Schedule id")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const admission = await readAdmission(path.resolve(options.repo), scheduleId);
+            if (!admission) {
+                throw new SchedulerError("scheduler-not-found", `admission not found: ${scheduleId}`);
+            }
+            emit(options.json, admission, () => `${JSON.stringify(admission, null, 2)}\n`);
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    const scheduler = program
+        .command("scheduler")
+        .description("Night Scheduler facts, lifecycle, admission commit, and doctor");
+    scheduler
+        .command("add")
+        .description("Approve frozen gate receipt and reserve Task Pool Queued (no DAG execute)")
+        .argument("<schedule-id>", "Schedule id from admission prepare")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .requiredOption("--approve-gate <token>", "Gate token from admission review packet")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const result = await addSchedule({
+                controlRepoRoot: path.resolve(options.repo),
+                scheduleId,
+                approveGate: options.approveGate,
+            });
+            emit(options.json, result, () => formatScheduleHuman(result.schedule));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("submit")
+        .description("Create a submitted schedule fact (planning intent; no admission yet)")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .requiredOption("--feature-id <feature-id>", "Feature id")
+        .requiredOption("--task-id <task-id>", "Task id")
+        .option("--feature-dir <path>", "Feature directory relative to repo")
+        .option("--task-card <ref>", "Task card / work item ref (e.g. UCP-LOOP#11)")
+        .option("--at <local-time>", 'Local execute time "YYYY-MM-DD HH:mm"')
+        .option("--tz <timezone>", "IANA timezone for --at", "Asia/Shanghai")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const controlRepoRoot = path.resolve(options.repo);
+            const trigger = options.at
+                ? parseOnceLocalToUtc({
+                    localAt: options.at,
+                    timezone: options.tz ?? "Asia/Shanghai",
+                })
+                : undefined;
+            const result = await submitSchedule({
+                controlRepoRoot,
+                featureId: options.featureId,
+                taskId: options.taskId,
+                ...(options.featureDir ? { featureDir: options.featureDir } : {}),
+                ...(options.taskCard ? { workItemRef: options.taskCard } : {}),
+                ...(trigger
+                    ? {
+                        trigger: {
+                            type: "once",
+                            executeAtUtc: trigger.executeAtUtc,
+                            displayTimezone: trigger.displayTimezone,
+                            ...(trigger.latestStartAtUtc
+                                ? { latestStartAtUtc: trigger.latestStartAtUtc }
+                                : {}),
+                            misfirePolicy: trigger.misfirePolicy,
+                        },
+                    }
+                    : {}),
+            });
+            emit(options.json, result.schedule, () => formatScheduleHuman(result.schedule));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("list")
+        .description("List current schedule snapshots")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--status <status>", "Filter by current status (comma-separated allowed)")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const controlRepoRoot = path.resolve(options.repo);
+            const statusFilter = parseStatusFilter(options.status);
+            const schedules = await listScheduleSnapshots({
+                controlRepoRoot,
+                ...(statusFilter ? { status: statusFilter } : {}),
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({ schemaVersion: 1, schedules }, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(formatScheduleListHuman(schedules));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("status")
+        .description("Show one schedule current snapshot")
+        .argument("<schedule-id>", "Schedule id")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const schedule = await getScheduleStatus({
+                controlRepoRoot: path.resolve(options.repo),
+                scheduleId,
+            });
+            emit(options.json, schedule, () => formatScheduleHuman(schedule));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("ledger")
+        .description("Query append-only schedule lifecycle ledger")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--schedule-id <id>", "Filter by schedule id")
+        .option("--to-status <status>", "Filter by toStatus")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const events = await readLedgerEvents(path.resolve(options.repo), {
+                ...(options.scheduleId ? { scheduleId: options.scheduleId } : {}),
+                ...(options.toStatus ? { toStatus: options.toStatus } : {}),
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({ schemaVersion: 1, events }, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(formatLedgerHuman(events));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("cancel")
+        .description("Cancel a non-running schedule and release Queued reservation when bound")
+        .argument("<schedule-id>", "Schedule id")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .requiredOption("--reason <reason>", "Cancel reason")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const schedule = await cancelScheduledReservation({
+                controlRepoRoot: path.resolve(options.repo),
+                scheduleId,
+                reason: options.reason,
+            });
+            emit(options.json, schedule, () => formatScheduleHuman(schedule));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("transition")
+        .description("Internal/test helper: apply a legal lifecycle transition (no dispatch)")
+        .argument("<schedule-id>", "Schedule id")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .requiredOption("--to <status>", "Target status")
+        .option("--reason <reason>", "Reason text")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const toStatus = scheduleStatusSchema.parse(options.to);
+            const result = await transitionSchedule({
+                controlRepoRoot: path.resolve(options.repo),
+                scheduleId,
+                toStatus,
+                ...(options.reason ? { reason: options.reason } : {}),
+            });
+            emit(options.json, result.schedule, () => formatScheduleHuman(result.schedule));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("tick")
+        .description("Claim due once schedules and dispatch prepared execution (OS cron entry)")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--loop-agent-bin <path>", "Published loop-agent binary")
+        .option("--max-claims <n>", "Max schedules to claim this tick", "1")
+        .option("--json", "Emit JSON")
+        .action(async (options) => {
+        try {
+            const controlRepoRoot = path.resolve(options.repo);
+            const client = new LoopAgentClient({
+                loopAgentBin: options.loopAgentBin ?? "loop-agent",
+                artifactRoot: path.join(controlRepoRoot, ".harness", "task-pool", "scheduler", "client-artifacts"),
+                resolveIdentity: true,
+            });
+            const maxClaims = Number(options.maxClaims ?? "1");
+            const result = await schedulerTick({
+                controlRepoRoot,
+                client,
+                maxClaims: Number.isFinite(maxClaims) ? maxClaims : 1,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(formatTickHuman(result));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("harvest")
+        .description("Exact-base fast-forward night branch into base (succeeded + pending-harvest only)")
+        .argument("<schedule-id>", "Schedule id")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--keep-worktree", "Keep night worktree/branch after harvest")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const result = await harvestNightSchedule({
+                controlRepoRoot: path.resolve(options.repo),
+                scheduleId,
+                keepWorktree: options.keepWorktree === true,
+            });
+            if (!result.ok) {
+                if (options.json) {
+                    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                }
+                else {
+                    process.stderr.write(`harvest blocked (${result.code}): ${result.message}\nnext: ${result.nextAction}\n`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            emit(options.json, result, () => [
+                `HARVESTED ${result.scheduleId}`,
+                `  base:     ${result.baseBranch}@${result.mergedCommit.slice(0, 12)}`,
+                `  night:    ${result.nightBranch}`,
+                `  ff:       yes`,
+                `  worktree: ${result.worktreeRemoved ? "removed" : "kept"}`,
+                `  branch:   ${result.branchDeleted ? "deleted" : "kept"}`,
+                "",
+            ].join("\n"));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("discard")
+        .description("Discard night worktree/branch after evidence retained (failed needs --force)")
+        .argument("<schedule-id>", "Schedule id")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .requiredOption("--reason <reason>", "Why this schedule is discarded")
+        .option("--force", "Required for failed/human_required schedules")
+        .option("--json", "Emit JSON")
+        .action(async (scheduleId, options) => {
+        try {
+            const result = await discardNightSchedule({
+                controlRepoRoot: path.resolve(options.repo),
+                scheduleId,
+                reason: options.reason,
+                force: options.force === true,
+            });
+            if (!result.ok) {
+                if (options.json) {
+                    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                }
+                else {
+                    process.stderr.write(`discard blocked (${result.code}): ${result.message}\nnext: ${result.nextAction}\n`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            emit(options.json, result, () => [
+                `DISCARDED ${result.scheduleId}`,
+                `  reason:   ${result.reason}`,
+                `  worktree: ${result.worktreeRemoved ? "removed" : "kept/missing"}`,
+                `  branch:   ${result.branchDeleted ? "deleted" : "kept/missing"}`,
+                "",
+            ].join("\n"));
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+    scheduler
+        .command("doctor")
+        .description("Read-only Night Scheduler consistency diagnosis")
+        .requiredOption("--repo <repo-root>", "Control repo root")
+        .option("--json", "Emit JSON")
+        .option("--recover-journals", "Replay pending transition journals before diagnosis")
+        .action(async (options) => {
+        try {
+            const controlRepoRoot = path.resolve(options.repo);
+            if (options.recoverJournals) {
+                await recoverAllPendingJournals(controlRepoRoot);
+            }
+            const report = await diagnoseScheduler(controlRepoRoot);
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(formatSchedulerDoctorHuman(report));
+            if (!report.ok)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            handleSchedulerCliError(error, options.json === true);
+        }
+    });
+}
+function parseStatusFilter(raw) {
+    if (!raw)
+        return undefined;
+    const parts = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const parsed = parts.map((part) => scheduleStatusSchema.parse(part));
+    if (parsed.length === 0)
+        return undefined;
+    if (parsed.length === 1)
+        return parsed[0];
+    return parsed;
+}
+function emit(json, value, human) {
+    if (json) {
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(human());
+}
+function formatTickHuman(result) {
+    const lines = [
+        `Night Scheduler tick @ ${result.at}`,
+        `  claimed:    ${result.claimed.length ? result.claimed.join(", ") : "(none)"}`,
+        `  dispatched: ${result.dispatched.length}`,
+    ];
+    for (const item of result.dispatched) {
+        lines.push(`    - ${item.schedule.id} → ${item.schedule.status}`);
+    }
+    if (result.recovery?.length) {
+        lines.push("  recovery:");
+        for (const item of result.recovery) {
+            lines.push(`    - ${item.scheduleId}: ${item.action} (${item.detail})`);
+        }
+    }
+    if (result.waiting.length) {
+        lines.push("  waiting:");
+        for (const item of result.waiting) {
+            lines.push(`    - ${item.scheduleId}: ${item.reason}`);
+        }
+    }
+    if (result.skipped.length) {
+        lines.push("  skipped:");
+        for (const item of result.skipped) {
+            lines.push(`    - ${item.scheduleId}: ${item.reason}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function formatReviewPacketHuman(packet) {
+    const lines = [
+        "ADMISSION REVIEW PACKET",
+        `  schedule:  ${packet.scheduleId}`,
+        `  task:      ${packet.featureId}/${packet.taskId}`,
+        `  executeAt: ${packet.executeAtUtc}`,
+        `  worktree:  ${packet.worktreePath}`,
+        `  branch:    ${packet.branch}`,
+        `  base:      ${packet.baseBranch}@${packet.baseCommit.slice(0, 12)}`,
+        `  gate:      ${packet.gateToken}`,
+        `  admission: ${packet.admissionPath}`,
+    ];
+    if (packet.harnessTaskId)
+        lines.push(`  harness:   ${packet.harnessTaskId}`);
+    if (packet.taskCard)
+        lines.push(`  card:      ${packet.taskCard}`);
+    if (packet.writeSet?.length) {
+        lines.push("  writeSet:");
+        for (const entry of packet.writeSet)
+            lines.push(`    - ${entry}`);
+    }
+    lines.push("", "Next: review writeSet, then:", `  agent-worker scheduler add ${packet.scheduleId} --approve-gate ${JSON.stringify(packet.gateToken)} --repo .`, "");
+    return lines.join("\n");
+}
+function formatScheduleHuman(schedule) {
+    const lines = [
+        `SCHEDULE ${schedule.id}`,
+        `  task:     ${schedule.featureId}/${schedule.taskId}`,
+        `  status:   ${schedule.status} (rev ${schedule.revision})`,
+    ];
+    if (schedule.trigger?.executeAtUtc) {
+        lines.push(`  plan:     ${schedule.trigger.executeAtUtc}${schedule.trigger.displayTimezone ? ` (${schedule.trigger.displayTimezone})` : ""}`);
+    }
+    if (schedule.traceability?.workItemRef) {
+        lines.push(`  card:     ${schedule.traceability.workItemRef}`);
+    }
+    if (schedule.isolation?.worktreePath) {
+        lines.push(`  worktree: ${schedule.isolation.worktreePath}`);
+    }
+    if (schedule.isolation?.mergeState) {
+        lines.push(`  merge:    ${schedule.isolation.mergeState}`);
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+function formatScheduleListHuman(schedules) {
+    if (schedules.length === 0) {
+        return "No schedules.\n";
+    }
+    const header = "SCHEDULE                         TASK                      PLAN TIME                 STATUS           MERGE";
+    const lines = [header, "-".repeat(header.length)];
+    for (const schedule of schedules) {
+        const plan = schedule.trigger?.executeAtUtc ?? "-";
+        const merge = schedule.isolation?.mergeState ?? "-";
+        const task = `${schedule.featureId}/${schedule.taskId}`;
+        lines.push([
+            pad(schedule.id, 32),
+            pad(task, 25),
+            pad(plan, 24),
+            pad(schedule.status, 16),
+            merge,
+        ].join(" "));
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+function formatLedgerHuman(events) {
+    if (events.length === 0)
+        return "No ledger events.\n";
+    const lines = [
+        "AT                        SCHEDULE                      TRANSITION              EVENT",
+    ];
+    for (const event of events) {
+        const transition = `${event.fromStatus ?? "∅"}→${event.toStatus}`;
+        lines.push([
+            pad(event.at, 25),
+            pad(event.scheduleId, 29),
+            pad(transition, 23),
+            event.event,
+        ].join(" "));
+        if (event.reason) {
+            lines.push(`  reason: ${event.reason}`);
+        }
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+function pad(value, width) {
+    if (value.length >= width)
+        return value.slice(0, width);
+    return value + " ".repeat(width - value.length);
+}
+function handleSchedulerCliError(error, json) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof SchedulerError ? error.code : "scheduler-cli-error";
+    if (json) {
+        process.stdout.write(`${JSON.stringify({
+            schemaVersion: 1,
+            ok: false,
+            code,
+            message,
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`${message}\n`);
+    }
+    process.exitCode = 1;
+}