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

package/dist/worker/scheduler/trigger.js

@@ -0,0 +1,258 @@
+/**
+ * Pure time helpers for once schedules, allowedHours windows, and misfire policy.
+ * No I/O. Display timezone is IANA; executeAt is always frozen as UTC ISO.
+ */
+const HHMM = /^(\d{2}):(\d{2})$/;
+const LOCAL_AT = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?$/;
+/**
+ * Parse a local wall-clock time in an IANA timezone into a unique UTC instant.
+ * Fail-closed on ambiguous/invalid inputs rather than guessing.
+ */
+export function parseOnceLocalToUtc(input) {
+    const timezone = input.timezone.trim();
+    if (!timezone) {
+        throw new Error("timezone is required");
+    }
+    assertValidTimezone(timezone);
+    const match = LOCAL_AT.exec(input.localAt.trim());
+    if (!match) {
+        throw new Error(`invalid localAt (expected YYYY-MM-DD HH:mm): ${JSON.stringify(input.localAt)}`);
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6] ?? "0");
+    const utcMs = zonedLocalToUtcMs({
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        timezone,
+    });
+    if (utcMs === null) {
+        throw new Error(`cannot resolve localAt ${JSON.stringify(input.localAt)} in timezone ${timezone}`);
+    }
+    const executeAtUtc = new Date(utcMs).toISOString();
+    const misfirePolicy = input.misfirePolicy ?? "wait-next-window";
+    const result = {
+        type: "once",
+        executeAtUtc,
+        displayTimezone: timezone,
+        misfirePolicy,
+    };
+    if (input.latestStartAtUtc) {
+        const latest = Date.parse(input.latestStartAtUtc);
+        if (!Number.isFinite(latest)) {
+            throw new Error(`invalid latestStartAtUtc: ${JSON.stringify(input.latestStartAtUtc)}`);
+        }
+        if (latest < utcMs) {
+            throw new Error("latestStartAtUtc must be >= executeAtUtc");
+        }
+        result.latestStartAtUtc = new Date(latest).toISOString();
+    }
+    return result;
+}
+export function isWithinAllowedHours(nowUtc, timezone, allowedHours) {
+    if (allowedHours.length === 0)
+        return true;
+    const minutes = localMinutesSinceMidnight(nowUtc, timezone);
+    return allowedHours.some((window) => minutesInWindow(minutes, window));
+}
+export function nextAllowedWindowStartUtc(nowUtc, timezone, allowedHours) {
+    if (allowedHours.length === 0)
+        return nowUtc.toISOString();
+    const windows = allowedHours
+        .map(parseWindow)
+        .sort((a, b) => a.start - b.start);
+    // Search the next 48 hours in 1-minute steps (deterministic, no DST edge guessing beyond Intl).
+    for (let offsetMin = 0; offsetMin < 60 * 48; offsetMin += 1) {
+        const candidate = new Date(nowUtc.getTime() + offsetMin * 60_000);
+        const minutes = localMinutesSinceMidnight(candidate, timezone);
+        if (windows.some((window) => minutesInParsedWindow(minutes, window))) {
+            return candidate.toISOString();
+        }
+    }
+    return null;
+}
+export function evaluateOnceDue(input) {
+    const executeAt = Date.parse(input.executeAtUtc);
+    if (!Number.isFinite(executeAt)) {
+        return {
+            kind: "human_required",
+            reason: `invalid executeAtUtc: ${input.executeAtUtc}`,
+        };
+    }
+    const nowMs = input.nowUtc.getTime();
+    if (nowMs < executeAt) {
+        return {
+            kind: "waiting",
+            reason: "not-due",
+            nextAttemptAt: input.executeAtUtc,
+        };
+    }
+    if (input.latestStartAtUtc) {
+        const latest = Date.parse(input.latestStartAtUtc);
+        if (Number.isFinite(latest) && nowMs > latest) {
+            return {
+                kind: "human_required",
+                reason: "past-latest-start",
+            };
+        }
+    }
+    const inWindow = isWithinAllowedHours(input.nowUtc, input.timezone, input.allowedHours);
+    if (inWindow) {
+        return { kind: "eligible" };
+    }
+    if (input.misfirePolicy === "run-immediately") {
+        // Still respect allowedHours when policy says wait/human; run-immediately
+        // only bypasses window if we are not past latestStart.
+        return { kind: "eligible" };
+    }
+    if (input.misfirePolicy === "human-required") {
+        return {
+            kind: "human_required",
+            reason: "outside-allowed-hours",
+        };
+    }
+    const next = nextAllowedWindowStartUtc(input.nowUtc, input.timezone, input.allowedHours);
+    if (!next) {
+        return {
+            kind: "human_required",
+            reason: "no-next-allowed-window",
+        };
+    }
+    return {
+        kind: "waiting",
+        reason: "outside-allowed-hours",
+        nextAttemptAt: next,
+    };
+}
+export function stableDueSortKey(schedule) {
+    return `${schedule.executeAtUtc}\0${schedule.scheduleId}`;
+}
+export function compareDueSchedules(a, b) {
+    return stableDueSortKey(a).localeCompare(stableDueSortKey(b));
+}
+function assertValidTimezone(timezone) {
+    try {
+        // Throws RangeError for invalid IANA ids in modern Node.
+        new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format(0);
+    }
+    catch {
+        throw new Error(`invalid timezone: ${JSON.stringify(timezone)}`);
+    }
+}
+function localMinutesSinceMidnight(date, timezone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    }).formatToParts(date);
+    const hour = Number(parts.find((part) => part.type === "hour")?.value ?? "0");
+    const minute = Number(parts.find((part) => part.type === "minute")?.value ?? "0");
+    return hour * 60 + minute;
+}
+function parseWindow(window) {
+    const [startRaw, endRaw] = window.split("-");
+    if (!startRaw || !endRaw) {
+        throw new Error(`invalid allowedHours window: ${JSON.stringify(window)}`);
+    }
+    return {
+        start: parseHhMm(startRaw),
+        end: parseHhMm(endRaw),
+    };
+}
+function parseHhMm(value) {
+    const match = HHMM.exec(value);
+    if (!match) {
+        throw new Error(`invalid HH:MM: ${JSON.stringify(value)}`);
+    }
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    if (hour > 23 || minute > 59) {
+        throw new Error(`invalid HH:MM: ${JSON.stringify(value)}`);
+    }
+    return hour * 60 + minute;
+}
+function minutesInWindow(minutes, window) {
+    return minutesInParsedWindow(minutes, parseWindow(window));
+}
+function minutesInParsedWindow(minutes, window) {
+    if (window.start === window.end)
+        return true;
+    if (window.start < window.end) {
+        return minutes >= window.start && minutes < window.end;
+    }
+    // Cross midnight, e.g. 22:00-06:00
+    return minutes >= window.start || minutes < window.end;
+}
+/**
+ * Convert a local civil time in `timezone` to UTC ms using iterative offset
+ * resolution (handles DST without external deps).
+ */
+function zonedLocalToUtcMs(input) {
+    const utcGuess = Date.UTC(input.year, input.month - 1, input.day, input.hour, input.minute, input.second);
+    for (let i = 0; i < 3; i += 1) {
+        const offset = timezoneOffsetMs(new Date(utcGuess), input.timezone);
+        const candidate = utcGuess - offset;
+        const roundTrip = timezoneOffsetMs(new Date(candidate), input.timezone);
+        if (roundTrip === offset) {
+            // Verify the local components match.
+            const parts = getZonedParts(new Date(candidate), input.timezone);
+            if (parts.year === input.year &&
+                parts.month === input.month &&
+                parts.day === input.day &&
+                parts.hour === input.hour &&
+                parts.minute === input.minute &&
+                parts.second === input.second) {
+                return candidate;
+            }
+        }
+    }
+    // Fallback: try neighboring hour for DST folds.
+    for (const delta of [-3600_000, 3600_000, -7200_000, 7200_000]) {
+        const candidate = utcGuess + delta;
+        const parts = getZonedParts(new Date(candidate), input.timezone);
+        if (parts.year === input.year &&
+            parts.month === input.month &&
+            parts.day === input.day &&
+            parts.hour === input.hour &&
+            parts.minute === input.minute &&
+            parts.second === input.second) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function timezoneOffsetMs(date, timezone) {
+    const parts = getZonedParts(date, timezone);
+    const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+    return asUtc - date.getTime();
+}
+function getZonedParts(date, timezone) {
+    const dtf = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+    });
+    const parts = dtf.formatToParts(date);
+    const read = (type) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+    return {
+        year: read("year"),
+        month: read("month"),
+        day: read("day"),
+        hour: read("hour"),
+        minute: read("minute"),
+        second: read("second"),
+    };
+}

package/dist/worker/scheduler/types.js

@@ -0,0 +1,369 @@
+import { z } from "zod";
+export const SCHEDULE_SCHEMA_VERSION = 1;
+export const ADMISSION_SCHEMA_VERSION = 1;
+export const EXECUTION_SCHEMA_VERSION = 1;
+export const LEDGER_SCHEMA_VERSION = 1;
+export const TRANSACTION_SCHEMA_VERSION = 1;
+export const scheduleStatusSchema = z.enum([
+    "submitted",
+    "validating",
+    "rejected",
+    "validated",
+    "scheduled",
+    "waiting",
+    "dispatching",
+    "running",
+    "cancel_requested",
+    "succeeded",
+    "failed",
+    "human_required",
+    "cancelled",
+]);
+export const TERMINAL_SCHEDULE_STATUSES = new Set([
+    "rejected",
+    "succeeded",
+    "failed",
+    "human_required",
+    "cancelled",
+]);
+export const ACTIVE_SCHEDULE_STATUSES = new Set(scheduleStatusSchema.options.filter((status) => !TERMINAL_SCHEDULE_STATUSES.has(status)));
+export const scheduleLedgerEventNameSchema = z.enum([
+    "plan_submitted",
+    "validation_started",
+    "validation_passed",
+    "validation_rejected",
+    "task_reserved",
+    "schedule_created",
+    "schedule_cancelled",
+    "became_due",
+    "waiting",
+    "execution_claimed",
+    "dispatch_started",
+    "worker_run_associated",
+    "execution_finished",
+    "evidence_archived",
+    "closing_commit_created",
+    "merge_skipped",
+    "merge_completed",
+    "worktree_discarded",
+    "cancel_requested",
+    "human_required",
+    "doctor_finding",
+    "transition_recovered",
+    "lease_recovered",
+    "auto_retry_queued",
+    "auto_followup_enqueued",
+]);
+export const scheduleTriggerSchema = z.object({
+    type: z.literal("once"),
+    executeAtUtc: z.string().datetime(),
+    displayTimezone: z.string().min(1),
+    latestStartAtUtc: z.string().datetime().optional(),
+    misfirePolicy: z
+        .enum(["run-immediately", "wait-next-window", "human-required"])
+        .optional(),
+});
+export const schedulePolicySnapshotSchema = z.object({
+    allowedHours: z.array(z.string().min(1)).default(["00:00-08:00"]),
+    maxConcurrency: z.number().int().positive().default(1),
+    maxAutoAttempts: z.number().int().positive().default(1),
+    keepFailedWorktree: z.boolean().default(true),
+    mergePolicy: z
+        .enum(["manual-on-success", "auto-on-success"])
+        .default("manual-on-success"),
+    misfirePolicy: z
+        .enum(["run-immediately", "wait-next-window", "human-required"])
+        .default("wait-next-window"),
+    timezone: z.string().min(1).default("Asia/Shanghai"),
+    /** ADR 0010: frozen at admission; default false. */
+    autoFollowUpEnabled: z.boolean().default(false),
+    autoFollowUpMode: z.enum(["draft-only"]).default("draft-only"),
+});
+export const scheduleIsolationSchema = z.object({
+    mode: z.literal("git-worktree").default("git-worktree"),
+    required: z.boolean().default(true),
+    baseBranch: z.string().min(1).optional(),
+    baseCommit: z.string().min(1).optional(),
+    worktreePath: z.string().min(1).optional(),
+    branch: z.string().min(1).optional(),
+    mergePolicy: z
+        .enum(["manual-on-success", "auto-on-success"])
+        .default("manual-on-success"),
+    mergeState: z
+        .enum([
+        "not-applicable",
+        "pending-execution",
+        "pending-harvest",
+        "merged",
+        "discarded",
+        "not-merged",
+    ])
+        .default("not-applicable"),
+});
+export const scheduleTraceabilitySchema = z.object({
+    kind: z.literal("task-card").default("task-card"),
+    label: z.string().min(1).default("Task Card"),
+    workItemRef: z.string().min(1).optional(),
+    pattern: z.string().min(1).optional(),
+    commitMessageTemplate: z.string().min(1).optional(),
+    requiredOnCreate: z.boolean().default(true),
+    requiredOnEveryPushableCommit: z.boolean().default(true),
+});
+export const scheduleTimestampsSchema = z.object({
+    submittedAt: z.string().datetime(),
+    validatedAt: z.string().datetime().nullable().optional(),
+    scheduledAt: z.string().datetime().nullable().optional(),
+    startedAt: z.string().datetime().nullable().optional(),
+    finishedAt: z.string().datetime().nullable().optional(),
+});
+export const scheduleRecordSchema = z.object({
+    schemaVersion: z.literal(SCHEDULE_SCHEMA_VERSION),
+    id: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    featureId: z.string().min(1),
+    taskId: z.string().min(1),
+    featureDir: z.string().min(1).optional(),
+    status: scheduleStatusSchema,
+    dispatch: z
+        .object({
+        mode: z.literal("single-task").default("single-task"),
+    })
+        .default({ mode: "single-task" }),
+    trigger: scheduleTriggerSchema.optional(),
+    policySnapshot: schedulePolicySnapshotSchema.optional(),
+    admissionRef: z.string().min(1).optional(),
+    reservation: z
+        .object({
+        taskPoolStatus: z.literal("Queued"),
+        reservedAt: z.string().datetime(),
+    })
+        .optional(),
+    isolation: scheduleIsolationSchema.optional(),
+    traceability: scheduleTraceabilitySchema.optional(),
+    timestamps: scheduleTimestampsSchema,
+    currentExecutionId: z.string().min(1).nullable().optional(),
+    lastTransitionId: z.string().min(1).optional(),
+    lastLedgerEventId: z.string().min(1).optional(),
+    waitingReason: z.string().nullable().optional(),
+    nextAttemptAt: z.string().datetime().nullable().optional(),
+    cancelReason: z.string().nullable().optional(),
+    rejectReason: z.string().nullable().optional(),
+});
+export const taskAdmissionSchema = z.object({
+    schemaVersion: z.literal(ADMISSION_SCHEMA_VERSION),
+    scheduleId: z.string().min(1),
+    featureId: z.string().min(1),
+    taskId: z.string().min(1),
+    featureDir: z.string().min(1),
+    taskSpec: z
+        .object({
+        path: z.string().min(1),
+        sha256: z.string().min(1),
+    })
+        .optional(),
+    taskGraph: z
+        .object({
+        path: z.string().min(1),
+        sha256: z.string().min(1),
+    })
+        .optional(),
+    harnessTaskId: z.string().min(1).optional(),
+    workspace: z
+        .object({
+        path: z.string().min(1),
+        branch: z.string().min(1),
+        baseBranch: z.string().min(1),
+        baseCommit: z.string().min(1),
+        ownershipToken: z.string().min(1),
+        taskDir: z.string().min(1).optional(),
+    })
+        .optional(),
+    controllerIdentity: z.record(z.string(), z.unknown()).optional(),
+    dag: z
+        .object({
+        path: z.string().min(1),
+        sha256: z.string().min(1),
+        nodeCount: z.number().int().nonnegative().optional(),
+        strictValidated: z.boolean().optional(),
+        writeSet: z.array(z.string()).optional(),
+    })
+        .optional(),
+    gateApproval: z
+        .object({
+        id: z.string().min(1),
+        token: z.string().min(1),
+        digest: z.string().min(1),
+        bound: z.record(z.string(), z.unknown()).optional(),
+        approvedAt: z.string().datetime().optional(),
+        approvedBy: z.string().min(1).optional(),
+    })
+        .optional(),
+    verification: z
+        .object({
+        commands: z.array(z.object({
+            label: z.string().min(1),
+            command: z.string().min(1),
+        })),
+    })
+        .optional(),
+    estimate: z
+        .object({
+        minutes: z.number().nonnegative().optional(),
+        confidence: z.string().optional(),
+    })
+        .optional(),
+    risk: z.string().optional(),
+    createdAt: z.string().datetime(),
+});
+export const executionRecordSchema = z.object({
+    schemaVersion: z.literal(EXECUTION_SCHEMA_VERSION),
+    executionId: z.string().min(1),
+    scheduleId: z.string().min(1),
+    attempt: z.number().int().positive(),
+    status: z.enum([
+        "claimed",
+        "running",
+        "succeeded",
+        "failed",
+        "human_required",
+        "cancelled",
+    ]),
+    claimedAt: z.string().datetime(),
+    startedAt: z.string().datetime().nullable().optional(),
+    finishedAt: z.string().datetime().nullable().optional(),
+    lease: z
+        .object({
+        ownerPid: z.number().int().positive(),
+        hostname: z.string().min(1),
+        token: z.string().min(1),
+        heartbeatAt: z.string().datetime(),
+    })
+        .optional(),
+    workerRunId: z.string().min(1).optional(),
+    dagRunId: z.string().min(1).optional(),
+    workspacePath: z.string().min(1).optional(),
+    evidenceArchivePath: z.string().min(1).optional(),
+    failure: z
+        .object({
+        code: z.string().optional(),
+        message: z.string().optional(),
+    })
+        .nullable()
+        .optional(),
+});
+export const ledgerEventSchema = z.object({
+    schemaVersion: z.literal(LEDGER_SCHEMA_VERSION),
+    eventId: z.string().min(1),
+    transitionId: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    at: z.string().datetime(),
+    scheduleId: z.string().min(1),
+    featureId: z.string().min(1),
+    taskId: z.string().min(1),
+    fromStatus: scheduleStatusSchema.nullable(),
+    toStatus: scheduleStatusSchema,
+    event: scheduleLedgerEventNameSchema,
+    plannedExecuteAtUtc: z.string().datetime().optional(),
+    reasonCode: z.string().nullable().optional(),
+    reason: z.string().nullable().optional(),
+    executionId: z.string().min(1).nullable().optional(),
+    worktreePath: z.string().min(1).nullable().optional(),
+    evidencePaths: z.array(z.string()).optional(),
+});
+export const transitionJournalSchema = z.object({
+    schemaVersion: z.literal(TRANSACTION_SCHEMA_VERSION),
+    transitionId: z.string().min(1),
+    scheduleId: z.string().min(1),
+    status: z.enum(["pending", "committed"]),
+    createdAt: z.string().datetime(),
+    committedAt: z.string().datetime().optional(),
+    /** Prior schedule revision; null means create (no prior snapshot). */
+    expectedRevision: z.number().int().nonnegative().nullable(),
+    fromStatus: scheduleStatusSchema.nullable(),
+    toStatus: scheduleStatusSchema,
+    event: scheduleLedgerEventNameSchema,
+    patch: z.record(z.string(), z.unknown()).default({}),
+    ledgerEvent: ledgerEventSchema,
+    scheduleSnapshot: scheduleRecordSchema,
+});
+export const SCHEDULER_ERROR_CODES = {
+    NOT_FOUND: "scheduler-not-found",
+    INVALID_TRANSITION: "scheduler-invalid-transition",
+    REVISION_CONFLICT: "scheduler-revision-conflict",
+    DUPLICATE_ACTIVE: "scheduler-duplicate-active",
+    INVALID_RECORD: "scheduler-invalid-record",
+    LOCK_HELD: "scheduler-lock-held",
+    UNSAFE_ID: "scheduler-unsafe-id",
+    JOURNAL_PENDING: "scheduler-journal-pending",
+    TERMINAL: "scheduler-terminal",
+};
+export class SchedulerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SchedulerError";
+        this.code = code;
+    }
+}
+/** Legal from → to edges for Phase 1 lifecycle. */
+export const SCHEDULE_TRANSITIONS = {
+    submitted: ["validating", "rejected", "cancelled"],
+    validating: ["validated", "rejected", "cancelled"],
+    rejected: [],
+    validated: ["scheduled", "rejected", "cancelled"],
+    scheduled: ["waiting", "dispatching", "cancelled", "human_required"],
+    waiting: ["dispatching", "cancelled", "human_required", "waiting"],
+    dispatching: ["running", "waiting", "failed", "human_required", "cancelled"],
+    running: [
+        "succeeded",
+        "failed",
+        "human_required",
+        "cancel_requested",
+        "cancelled",
+    ],
+    cancel_requested: ["cancelled", "failed", "human_required"],
+    succeeded: [],
+    // failed is normally terminal; Phase 4 allows failed → waiting only for
+    // bounded EnvFailure auto-retry (never expands writeSet / never re-admits).
+    failed: ["waiting"],
+    human_required: [],
+    cancelled: [],
+};
+export function isTerminalScheduleStatus(status) {
+    return TERMINAL_SCHEDULE_STATUSES.has(status);
+}
+export function canTransitionSchedule(from, to) {
+    if (from === null) {
+        return to === "submitted";
+    }
+    return (SCHEDULE_TRANSITIONS[from] ?? []).includes(to);
+}
+export function defaultEventForTransition(from, to) {
+    if (from === null && to === "submitted")
+        return "plan_submitted";
+    if (to === "validating")
+        return "validation_started";
+    if (to === "validated")
+        return "validation_passed";
+    if (to === "rejected")
+        return "validation_rejected";
+    if (to === "scheduled")
+        return "schedule_created";
+    if (from === "failed" && to === "waiting")
+        return "auto_retry_queued";
+    if (to === "waiting")
+        return "waiting";
+    if (to === "dispatching")
+        return "execution_claimed";
+    if (to === "running")
+        return "worker_run_associated";
+    if (to === "succeeded" || to === "failed")
+        return "execution_finished";
+    if (to === "human_required")
+        return "human_required";
+    if (to === "cancel_requested")
+        return "cancel_requested";
+    if (to === "cancelled")
+        return "schedule_cancelled";
+    return "doctor_finding";
+}