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

package/dist/worker/scheduler/scheduler-loop.js

@@ -0,0 +1,272 @@
+import { randomBytes } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { readTaskPoolState } from "../pool/run-store.js";
+import { dispatchClaimedExecution, } from "./dispatcher.js";
+import { acquireExecutionLease, countActiveLeases, readExecutionLease, } from "./lease.js";
+import { withSchedulerMutationLock } from "./lock.js";
+import { transitionSchedule } from "./lifecycle.js";
+import { getLeasesDir } from "./paths.js";
+import { recoverStaleSchedulerState } from "./recovery.js";
+import { listExecutionsForSchedule, listSchedules, readAdmission, recoverAllPendingJournals, writeExecution, } from "./store.js";
+import { compareDueSchedules, evaluateOnceDue } from "./trigger.js";
+import { SCHEDULER_ERROR_CODES, SchedulerError, } from "./types.js";
+/**
+ * One OS-driven tick: recover journals, claim due schedules under short lock,
+ * then dispatch outside the lock.
+ */
+export async function schedulerTick(options) {
+    const now = options.now ?? new Date();
+    const maxClaims = options.maxClaims ?? 1;
+    if (!Number.isInteger(maxClaims) || maxClaims < 1) {
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `maxClaims must be a positive integer, got ${maxClaims}`);
+    }
+    const waiting = [];
+    const skipped = [];
+    const recovery = [];
+    const claimedMeta = [];
+    await recoverAllPendingJournals(options.controlRepoRoot);
+    if (options.recoverStale !== false) {
+        const recovered = await recoverStaleSchedulerState({
+            controlRepoRoot: options.controlRepoRoot,
+            now,
+            hostname: options.hostname,
+        });
+        for (const item of recovered) {
+            recovery.push({
+                scheduleId: item.scheduleId,
+                action: item.action,
+                detail: item.detail,
+            });
+        }
+    }
+    await withSchedulerMutationLock({
+        controlRepoRoot: options.controlRepoRoot,
+        hostname: options.hostname,
+        now: () => now,
+    }, async () => {
+        const schedules = await listSchedules(options.controlRepoRoot);
+        const candidates = schedules
+            .filter((schedule) => schedule.status === "scheduled" || schedule.status === "waiting")
+            .filter((schedule) => schedule.trigger?.type === "once")
+            .map((schedule) => ({
+            schedule,
+            executeAtUtc: schedule.trigger.executeAtUtc,
+            scheduleId: schedule.id,
+        }))
+            .sort((a, b) => compareDueSchedules({ executeAtUtc: a.executeAtUtc, scheduleId: a.scheduleId }, { executeAtUtc: b.executeAtUtc, scheduleId: b.scheduleId }));
+        const activeLeaseCount = await countCurrentActiveLeases(options.controlRepoRoot, now);
+        const concurrencyLimits = candidates.map((item) => item.schedule.policySnapshot?.maxConcurrency ?? 1);
+        const maxConcurrency = concurrencyLimits.length > 0
+            ? Math.max(1, Math.min(...concurrencyLimits))
+            : 1;
+        let remainingCapacity = Math.max(0, maxConcurrency - activeLeaseCount);
+        remainingCapacity = Math.min(remainingCapacity, maxClaims);
+        for (const item of candidates) {
+            if (remainingCapacity <= 0) {
+                skipped.push({
+                    scheduleId: item.scheduleId,
+                    reason: "max-concurrency",
+                });
+                continue;
+            }
+            const decision = evaluateDue(item.schedule, now);
+            if (decision.kind === "waiting") {
+                if (item.schedule.status === "scheduled" ||
+                    item.schedule.waitingReason !== decision.reason) {
+                    await transitionSchedule({
+                        controlRepoRoot: options.controlRepoRoot,
+                        scheduleId: item.scheduleId,
+                        toStatus: "waiting",
+                        event: "waiting",
+                        reason: decision.reason,
+                        reasonCode: decision.reason,
+                        patch: {
+                            waitingReason: decision.reason,
+                            nextAttemptAt: decision.nextAttemptAt,
+                        },
+                        alreadyLocked: true,
+                        now,
+                    });
+                }
+                waiting.push({
+                    scheduleId: item.scheduleId,
+                    reason: decision.reason,
+                    ...(decision.nextAttemptAt
+                        ? { nextAttemptAt: decision.nextAttemptAt }
+                        : {}),
+                });
+                continue;
+            }
+            if (decision.kind === "human_required") {
+                await transitionSchedule({
+                    controlRepoRoot: options.controlRepoRoot,
+                    scheduleId: item.scheduleId,
+                    toStatus: "human_required",
+                    event: "human_required",
+                    reason: decision.reason,
+                    reasonCode: decision.reason,
+                    alreadyLocked: true,
+                    now,
+                });
+                skipped.push({
+                    scheduleId: item.scheduleId,
+                    reason: decision.reason,
+                });
+                continue;
+            }
+            // eligible
+            const existingLease = await readExecutionLease(options.controlRepoRoot, item.scheduleId);
+            if (existingLease) {
+                skipped.push({
+                    scheduleId: item.scheduleId,
+                    reason: "lease-held",
+                });
+                continue;
+            }
+            const admission = await readAdmission(options.controlRepoRoot, item.scheduleId);
+            if (!admission?.workspace ||
+                !admission.gateApproval?.token ||
+                !admission.gateApproval.approvedAt) {
+                await transitionSchedule({
+                    controlRepoRoot: options.controlRepoRoot,
+                    scheduleId: item.scheduleId,
+                    toStatus: "human_required",
+                    event: "human_required",
+                    reason: "approved admission incomplete at claim",
+                    reasonCode: "admission-incomplete",
+                    alreadyLocked: true,
+                    now,
+                });
+                skipped.push({
+                    scheduleId: item.scheduleId,
+                    reason: "admission-incomplete",
+                });
+                continue;
+            }
+            const poolState = await readTaskPoolState(options.controlRepoRoot, {
+                featureId: item.schedule.featureId,
+                taskId: item.schedule.taskId,
+            });
+            if (poolState?.status !== "Queued" ||
+                poolState.nightScheduleId !== item.scheduleId) {
+                await transitionSchedule({
+                    controlRepoRoot: options.controlRepoRoot,
+                    scheduleId: item.scheduleId,
+                    toStatus: "human_required",
+                    event: "human_required",
+                    reason: "Task Pool reservation is missing or owned by another run",
+                    reasonCode: "reservation-mismatch",
+                    alreadyLocked: true,
+                    now,
+                });
+                skipped.push({
+                    scheduleId: item.scheduleId,
+                    reason: "reservation-mismatch",
+                });
+                continue;
+            }
+            const priorExecutions = await listExecutionsForSchedule(options.controlRepoRoot, item.scheduleId);
+            const attemptNumber = priorExecutions.length + 1;
+            const executionId = `exec-${item.scheduleId}-${randomBytes(2).toString("hex")}`;
+            await transitionSchedule({
+                controlRepoRoot: options.controlRepoRoot,
+                scheduleId: item.scheduleId,
+                toStatus: "dispatching",
+                event: "execution_claimed",
+                patch: {
+                    currentExecutionId: executionId,
+                    waitingReason: null,
+                    nextAttemptAt: null,
+                },
+                alreadyLocked: true,
+                now,
+            });
+            const lease = await acquireExecutionLease({
+                controlRepoRoot: options.controlRepoRoot,
+                scheduleId: item.scheduleId,
+                executionId,
+                hostname: options.hostname,
+                workspacePath: admission.workspace.path,
+                now,
+            });
+            await writeExecution(options.controlRepoRoot, {
+                schemaVersion: 1,
+                executionId,
+                scheduleId: item.scheduleId,
+                attempt: attemptNumber,
+                status: "claimed",
+                claimedAt: now.toISOString(),
+                startedAt: null,
+                finishedAt: null,
+                lease: {
+                    ownerPid: lease.ownerPid,
+                    hostname: lease.hostname,
+                    token: lease.token,
+                    heartbeatAt: lease.heartbeatAt,
+                },
+                workspacePath: admission.workspace.path,
+                failure: null,
+            });
+            claimedMeta.push({
+                scheduleId: item.scheduleId,
+                executionId,
+                lease,
+            });
+            remainingCapacity -= 1;
+        }
+    });
+    const dispatch = options.dispatch ?? dispatchClaimedExecution;
+    const dispatched = await Promise.all(claimedMeta.map((claim) => dispatch({
+        controlRepoRoot: options.controlRepoRoot,
+        scheduleId: claim.scheduleId,
+        executionId: claim.executionId,
+        lease: claim.lease,
+        client: options.client,
+        now: new Date(),
+    })));
+    return {
+        schemaVersion: 1,
+        at: now.toISOString(),
+        claimed: claimedMeta.map((item) => item.scheduleId),
+        dispatched,
+        waiting,
+        skipped,
+        recovery,
+    };
+}
+function evaluateDue(schedule, now) {
+    const trigger = schedule.trigger;
+    if (!trigger || trigger.type !== "once") {
+        return { kind: "human_required", reason: "missing-once-trigger" };
+    }
+    const policy = schedule.policySnapshot;
+    return evaluateOnceDue({
+        nowUtc: now,
+        executeAtUtc: trigger.executeAtUtc,
+        ...(trigger.latestStartAtUtc
+            ? { latestStartAtUtc: trigger.latestStartAtUtc }
+            : {}),
+        timezone: trigger.displayTimezone ?? policy?.timezone ?? "Asia/Shanghai",
+        allowedHours: policy?.allowedHours ?? ["00:00-08:00"],
+        misfirePolicy: trigger.misfirePolicy ?? policy?.misfirePolicy ?? "wait-next-window",
+    });
+}
+async function countCurrentActiveLeases(controlRepoRoot, now) {
+    const leases = [];
+    try {
+        const dir = getLeasesDir(controlRepoRoot);
+        const names = await readdir(dir);
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const scheduleId = name.slice(0, -5);
+            const lease = await readExecutionLease(controlRepoRoot, scheduleId);
+            if (lease)
+                leases.push(lease);
+        }
+    }
+    catch {
+        return 0;
+    }
+    return countActiveLeases(leases, now);
+}

package/dist/worker/scheduler/store.js

@@ -0,0 +1,275 @@
+import { randomBytes } from "node:crypto";
+import { appendFile, mkdir, readdir, readFile, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { getAdmissionPath, getAdmissionsDir, getExecutionPath, getExecutionsDir, getLedgerPath, getSchedulePath, getSchedulesDir, getSchedulerRoot, getTransactionPath, getTransactionsDir, relativeSchedulerPath, } from "./paths.js";
+import { ACTIVE_SCHEDULE_STATUSES, executionRecordSchema, ledgerEventSchema, scheduleRecordSchema, SCHEDULER_ERROR_CODES, SchedulerError, taskAdmissionSchema, transitionJournalSchema, } from "./types.js";
+export async function ensureSchedulerDirs(controlRepoRoot) {
+    const root = getSchedulerRoot(controlRepoRoot);
+    await mkdir(root, { recursive: true });
+    await Promise.all([
+        getSchedulesDir(controlRepoRoot),
+        getAdmissionsDir(controlRepoRoot),
+        getExecutionsDir(controlRepoRoot),
+        getTransactionsDir(controlRepoRoot),
+        path.join(root, "leases"),
+        path.join(root, "evidence"),
+        path.join(root, "reports"),
+    ].map((dir) => mkdir(dir, { recursive: true })));
+}
+export function createScheduleId(now = new Date()) {
+    const stamp = now
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}Z$/, "Z");
+    // sched-20260806T180000Z-7f3a
+    const compact = stamp.replace("Z", "").slice(0, 15);
+    const suffix = randomBytes(2).toString("hex");
+    return `sched-${compact}-${suffix}`;
+}
+export function createTransitionId(now = new Date()) {
+    return `tr-${now.getTime().toString(36)}-${randomBytes(3).toString("hex")}`;
+}
+export function createEventId(now = new Date()) {
+    return `evt-${now.getTime().toString(36)}-${randomBytes(3).toString("hex")}`;
+}
+export async function readSchedule(controlRepoRoot, scheduleId) {
+    const filePath = getSchedulePath(controlRepoRoot, scheduleId);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return scheduleRecordSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        if (error instanceof SchedulerError)
+            throw error;
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `invalid schedule snapshot ${scheduleId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function writeScheduleSnapshot(controlRepoRoot, schedule) {
+    const parsed = scheduleRecordSchema.parse(schedule);
+    await ensureSchedulerDirs(controlRepoRoot);
+    await writeJsonAtomic(getSchedulePath(controlRepoRoot, parsed.id), parsed, {
+        repoRoot: controlRepoRoot,
+    });
+}
+export async function listSchedules(controlRepoRoot) {
+    const dir = getSchedulesDir(controlRepoRoot);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const id = name.slice(0, -5);
+        const record = await readSchedule(controlRepoRoot, id);
+        if (record)
+            records.push(record);
+    }
+    return records.sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function listActiveSchedulesForTask(controlRepoRoot, featureId, taskId) {
+    const all = await listSchedules(controlRepoRoot);
+    return all.filter((schedule) => schedule.featureId === featureId &&
+        schedule.taskId === taskId &&
+        ACTIVE_SCHEDULE_STATUSES.has(schedule.status));
+}
+export async function readAdmission(controlRepoRoot, scheduleId) {
+    const filePath = getAdmissionPath(controlRepoRoot, scheduleId);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return taskAdmissionSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `invalid admission ${scheduleId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function writeAdmission(controlRepoRoot, admission) {
+    const parsed = taskAdmissionSchema.parse(admission);
+    await ensureSchedulerDirs(controlRepoRoot);
+    const absolute = getAdmissionPath(controlRepoRoot, parsed.scheduleId);
+    await writeJsonAtomic(absolute, parsed, { repoRoot: controlRepoRoot });
+    return relativeSchedulerPath(controlRepoRoot, absolute);
+}
+export async function readExecution(controlRepoRoot, executionId) {
+    const filePath = getExecutionPath(controlRepoRoot, executionId);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return executionRecordSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `invalid execution ${executionId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function writeExecution(controlRepoRoot, execution) {
+    const parsed = executionRecordSchema.parse(execution);
+    await ensureSchedulerDirs(controlRepoRoot);
+    await writeJsonAtomic(getExecutionPath(controlRepoRoot, parsed.executionId), parsed, { repoRoot: controlRepoRoot });
+}
+export async function listExecutions(controlRepoRoot) {
+    const dir = getExecutionsDir(controlRepoRoot);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const id = name.slice(0, -5);
+        const record = await readExecution(controlRepoRoot, id);
+        if (record)
+            records.push(record);
+    }
+    return records.sort((a, b) => a.executionId.localeCompare(b.executionId));
+}
+export async function listExecutionsForSchedule(controlRepoRoot, scheduleId) {
+    const all = await listExecutions(controlRepoRoot);
+    return all.filter((item) => item.scheduleId === scheduleId);
+}
+export async function appendLedgerEvent(controlRepoRoot, event) {
+    const parsed = ledgerEventSchema.parse(event);
+    await ensureSchedulerDirs(controlRepoRoot);
+    const ledgerPath = getLedgerPath(controlRepoRoot);
+    // Idempotent by eventId: skip if already present.
+    const existing = await readLedgerEvents(controlRepoRoot);
+    if (existing.some((item) => item.eventId === parsed.eventId)) {
+        return;
+    }
+    await appendFile(ledgerPath, `${JSON.stringify(parsed)}\n`, "utf-8");
+}
+export async function readLedgerEvents(controlRepoRoot, filter) {
+    const ledgerPath = getLedgerPath(controlRepoRoot);
+    let raw;
+    try {
+        raw = await readFile(ledgerPath, "utf-8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+    const events = [];
+    for (const [index, line] of raw.split(/\r?\n/).filter(Boolean).entries()) {
+        try {
+            const parsed = ledgerEventSchema.safeParse(JSON.parse(line));
+            if (!parsed.success)
+                continue;
+            if (filter?.scheduleId && parsed.data.scheduleId !== filter.scheduleId) {
+                continue;
+            }
+            if (filter?.toStatus && parsed.data.toStatus !== filter.toStatus) {
+                continue;
+            }
+            events.push(parsed.data);
+        }
+        catch {
+            // skip corrupt line; doctor reports separately
+            void index;
+        }
+    }
+    return events;
+}
+export async function writeTransitionJournal(controlRepoRoot, journal) {
+    const parsed = transitionJournalSchema.parse(journal);
+    await ensureSchedulerDirs(controlRepoRoot);
+    await writeJsonAtomic(getTransactionPath(controlRepoRoot, parsed.transitionId), parsed, { repoRoot: controlRepoRoot });
+}
+export async function readTransitionJournal(controlRepoRoot, transitionId) {
+    const filePath = getTransactionPath(controlRepoRoot, transitionId);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return transitionJournalSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw new SchedulerError(SCHEDULER_ERROR_CODES.INVALID_RECORD, `invalid transition journal ${transitionId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function listPendingJournals(controlRepoRoot) {
+    const dir = getTransactionsDir(controlRepoRoot);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+    const journals = [];
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const id = name.slice(0, -5);
+        const journal = await readTransitionJournal(controlRepoRoot, id);
+        if (journal && journal.status === "pending") {
+            journals.push(journal);
+        }
+    }
+    return journals;
+}
+export async function deleteTransitionJournal(controlRepoRoot, transitionId) {
+    const filePath = getTransactionPath(controlRepoRoot, transitionId);
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+}
+/**
+ * Recover a pending journal: rewrite schedule snapshot + append ledger (idempotent),
+ * then mark committed and delete journal.
+ */
+export async function recoverTransitionJournal(controlRepoRoot, journal) {
+    const parsed = transitionJournalSchema.parse(journal);
+    await writeScheduleSnapshot(controlRepoRoot, parsed.scheduleSnapshot);
+    await appendLedgerEvent(controlRepoRoot, parsed.ledgerEvent);
+    const committed = {
+        ...parsed,
+        status: "committed",
+        committedAt: new Date().toISOString(),
+    };
+    await writeTransitionJournal(controlRepoRoot, committed);
+    await deleteTransitionJournal(controlRepoRoot, parsed.transitionId);
+    return parsed.scheduleSnapshot;
+}
+export async function recoverAllPendingJournals(controlRepoRoot) {
+    const pending = await listPendingJournals(controlRepoRoot);
+    const recovered = [];
+    for (const journal of pending) {
+        recovered.push(await recoverTransitionJournal(controlRepoRoot, journal));
+    }
+    return recovered;
+}
+/** Low-level helper for tests that need to simulate partial crash mid-write. */
+export async function writeRawFile(filePath, content) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, "utf-8");
+}
+function isNotFound(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/worker/scheduler/traceability.js

@@ -0,0 +1,54 @@
+/**
+ * Validate a task-card / work item ref against tracked policy.
+ * Public package keeps generic workItemRef; company repos set required=true.
+ */
+export function validateTaskCard(workItemRef, policy) {
+    const required = policy?.required ?? false;
+    const label = policy?.label ?? "Task Card";
+    const patternSource = policy?.pattern ?? "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$";
+    const template = policy?.commitMessageTemplate ?? "{summary}\n\n{workItemRef}";
+    if (!template.includes("{workItemRef}")) {
+        return {
+            ok: false,
+            reason: "traceability.commitMessageTemplate must include {workItemRef}",
+        };
+    }
+    if (!workItemRef || workItemRef.trim().length === 0) {
+        if (required) {
+            return {
+                ok: false,
+                reason: `${label} is required (--task-card)`,
+            };
+        }
+        return { ok: true, workItemRef: "" };
+    }
+    let re;
+    try {
+        re = new RegExp(patternSource);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: `invalid traceability.pattern: ${patternSource}`,
+        };
+    }
+    if (!re.test(workItemRef.trim())) {
+        return {
+            ok: false,
+            reason: `${label} does not match pattern ${patternSource}: ${workItemRef}`,
+        };
+    }
+    return { ok: true, workItemRef: workItemRef.trim() };
+}
+export function formatCommitMessage(input) {
+    const template = input.template ?? "{summary}\n\n{workItemRef}";
+    const summary = input.summary.replace(/\r?\n/g, " ").trim().slice(0, 72);
+    let body = template
+        .replaceAll("{summary}", summary)
+        .replaceAll("{workItemRef}", input.workItemRef);
+    if (input.trailers) {
+        const lines = Object.entries(input.trailers).map(([key, value]) => `${key}: ${value}`);
+        body = `${body.trimEnd()}\n${lines.join("\n")}`;
+    }
+    return `${body.trimEnd()}\n`;
+}