minimal-agent 0.10.0 → 0.12.0

package/plugins/cron-runner/src/runs.ts

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type { CronMissedRecord, CronRunRecord } from './types.js';
+
+export async function appendRun(runsDir: string, record: CronRunRecord): Promise<void> {
+  await mkdir(runsDir, { recursive: true });
+  await appendFile(join(runsDir, `${record.taskId}.jsonl`), `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+export async function recentRuns(
+  runsDir: string,
+  taskId: string,
+  limit = 5,
+): Promise<CronRunRecord[]> {
+  const file = join(runsDir, `${taskId}.jsonl`);
+  if (!existsSync(file)) return [];
+  try {
+    const raw = await readFile(file, 'utf8');
+    const byId = new Map<string, CronRunRecord>();
+    for (const line of raw.trim().split('\n').filter(Boolean)) {
+      const record = JSON.parse(line) as CronRunRecord;
+      byId.set(record.id, { ...(byId.get(record.id) ?? {}), ...record });
+    }
+    return Array.from(byId.values())
+      .sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt))
+      .slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
+export async function markRunsRead(
+  runsDir: string,
+  taskId?: string,
+): Promise<void> {
+  if (!existsSync(runsDir)) return;
+  const now = new Date().toISOString();
+  const taskIds = taskId ? [taskId] : await listRunTaskIds(runsDir);
+  for (const id of taskIds) {
+    for (const run of await recentRuns(runsDir, id, Number.MAX_SAFE_INTEGER)) {
+      if (!run.readAt) await appendRun(runsDir, { ...run, readAt: now });
+    }
+  }
+}
+
+async function listRunTaskIds(runsDir: string): Promise<string[]> {
+  const { readdir } = await import('node:fs/promises');
+  try {
+    return (await readdir(runsDir))
+      .filter((name) => name.endsWith('.jsonl'))
+      .map((name) => name.slice(0, -6));
+  } catch {
+    return [];
+  }
+}
+
+export async function appendMissed(file: string, record: CronMissedRecord): Promise<void> {
+  await mkdir(dirname(file), { recursive: true });
+  await appendFile(file, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+export async function listMissed(file: string, limit = 20): Promise<CronMissedRecord[]> {
+  if (!existsSync(file)) return [];
+  try {
+    const raw = await readFile(file, 'utf8');
+    const bySlot = new Map<string, CronMissedRecord>();
+    for (const line of raw.trim().split('\n').filter(Boolean)) {
+      const parsed = JSON.parse(line) as Partial<CronMissedRecord> & Pick<CronMissedRecord, 'taskId' | 'scheduledFor'>;
+      const record: CronMissedRecord = {
+        ...(parsed as CronMissedRecord),
+        reason:
+          parsed.reason === 'overlap' || parsed.reason === 'binding_unavailable'
+            ? parsed.reason
+            : 'offline',
+        missedCount:
+          typeof parsed.missedCount === 'number' && parsed.missedCount > 0
+            ? parsed.missedCount
+            : 1,
+      };
+      bySlot.set(`${record.taskId}:${record.scheduledFor}`, record);
+    }
+    return Array.from(bySlot.values())
+      .sort((a, b) => Date.parse(b.detectedAt) - Date.parse(a.detectedAt))
+      .slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
+export async function markMissedRead(file: string, taskId?: string): Promise<void> {
+  const records = await listMissed(file, Number.MAX_SAFE_INTEGER);
+  const now = new Date().toISOString();
+  for (const record of records) {
+    if (!record.readAt && (!taskId || record.taskId === taskId)) {
+      await appendMissed(file, { ...record, readAt: now });
+    }
+  }
+}

package/plugins/cron-runner/src/scheduleEngine.ts

@@ -0,0 +1,76 @@
+import { cronFieldsMatchDate, nextCronRunMs, parseCronExpression } from './cronTime.js';
+import type { CronSchedule } from './types.js';
+
+export const MIN_INTERVAL_MS = 60_000;
+
+export function intervalToHuman(intervalMs: number): string {
+  const units = [
+    { ms: 7 * 24 * 60 * 60_000, label: '周' },
+    { ms: 24 * 60 * 60_000, label: '天' },
+    { ms: 60 * 60_000, label: '小时' },
+    { ms: 60_000, label: '分钟' },
+  ];
+  for (const unit of units) {
+    if (intervalMs % unit.ms === 0) return `每 ${intervalMs / unit.ms} ${unit.label}`;
+  }
+  return `每 ${Math.round(intervalMs / 60_000)} 分钟`;
+}
+
+/** Return the first wall-clock slot strictly after `fromMs`. */
+export function nextScheduleRunMs(schedule: CronSchedule, fromMs: number): number | null {
+  if (schedule.type === 'cron') return nextCronRunMs(schedule.cron, fromMs);
+  const anchor = Date.parse(schedule.anchorAt);
+  if (!Number.isFinite(anchor) || schedule.intervalMs < MIN_INTERVAL_MS) return null;
+  if (fromMs < anchor) return anchor;
+  return anchor + (Math.floor((fromMs - anchor) / schedule.intervalMs) + 1) * schedule.intervalMs;
+}
+
+/** Return the latest slot at or before `atMs`. */
+export function latestScheduleRunMs(schedule: CronSchedule, atMs: number): number | null {
+  if (schedule.type === 'interval') {
+    const anchor = Date.parse(schedule.anchorAt);
+    if (!Number.isFinite(anchor) || atMs < anchor || schedule.intervalMs < MIN_INTERVAL_MS) {
+      return null;
+    }
+    return anchor + Math.floor((atMs - anchor) / schedule.intervalMs) * schedule.intervalMs;
+  }
+
+  const fields = parseCronExpression(schedule.cron);
+  if (!fields) return null;
+  const cursor = new Date(atMs);
+  cursor.setSeconds(0, 0);
+  for (let i = 0; i < 366 * 24 * 60; i++) {
+    if (cronFieldsMatchDate(fields, cursor)) return cursor.getTime();
+    cursor.setMinutes(cursor.getMinutes() - 1);
+  }
+  return null;
+}
+
+export function countScheduleSlots(
+  schedule: CronSchedule,
+  afterExclusiveMs: number,
+  throughInclusiveMs: number,
+): number {
+  if (throughInclusiveMs <= afterExclusiveMs) return 0;
+  if (schedule.type === 'interval') {
+    const first = nextScheduleRunMs(schedule, afterExclusiveMs);
+    if (!first || first > throughInclusiveMs) return 0;
+    return Math.floor((throughInclusiveMs - first) / schedule.intervalMs) + 1;
+  }
+
+  let count = 0;
+  let cursor = afterExclusiveMs;
+  while (count < 10_000) {
+    const next = nextScheduleRunMs(schedule, cursor);
+    if (!next || next > throughInclusiveMs) break;
+    count++;
+    cursor = next;
+  }
+  return count;
+}
+
+export function scheduleAnchorMs(schedule: CronSchedule, createdAt: string): number {
+  const value = schedule.type === 'interval' ? schedule.anchorAt : createdAt;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}

package/plugins/cron-runner/src/scheduler.ts

@@ -0,0 +1,376 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import type { PluginRuntimeContext } from '../../../src/plugin-sdk.js';
+import { resolveSessionFile } from '../../../src/plugin-sdk.js';
+import { releaseSchedulerLock, tryAcquireSchedulerLock } from './lock.js';
+import {
+  countScheduleSlots,
+  latestScheduleRunMs,
+  nextScheduleRunMs,
+} from './scheduleEngine.js';
+import {
+  appendMissed,
+  appendRun,
+  cronLockFile,
+  getTask,
+  listTasks,
+  subscribeTaskChanges,
+  updateTask,
+} from './store.js';
+import type { CronRunRecord, CronTask } from './types.js';
+
+const RECONCILE_MS = 30_000;
+
+export class Scheduler {
+  private dueTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconcileTimer: ReturnType<typeof setInterval> | null = null;
+  private unsubscribeStore: (() => void) | null = null;
+  private readonly executions = new Map<string, Promise<void>>();
+  private readonly executionController = new AbortController();
+  private readonly owner = `cron-runner-${process.pid}-${randomUUID()}`;
+  private ownsLock = false;
+  private started = false;
+  private stopping = false;
+  private reconciling = false;
+  private initializing = false;
+  private stopPromise: Promise<void> | null = null;
+
+  constructor(private readonly ctx: PluginRuntimeContext) {}
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.stopping = false;
+    this.unsubscribeStore = subscribeTaskChanges(() => this.wake());
+    void this.startAsync();
+  }
+
+  async stop(): Promise<void> {
+    if (this.stopPromise) return await this.stopPromise;
+    if (!this.started && !this.ownsLock && this.executions.size === 0) return;
+    this.started = false;
+    this.stopping = true;
+    this.executionController.abort('cron scheduler stopped');
+    this.clearTimers();
+    this.unsubscribeStore?.();
+    this.unsubscribeStore = null;
+    this.stopPromise = (async () => {
+      await Promise.allSettled([...this.executions.values()]);
+      if (!this.ownsLock) return;
+      this.ownsLock = false;
+      await releaseSchedulerLock(cronLockFile(), this.owner);
+    })();
+    await this.stopPromise;
+  }
+
+  async runTaskNow(id: string): Promise<void> {
+    if (this.stopping || this.executions.has(id)) return;
+    const task = await getTask(id);
+    if (!task) return;
+    await this.launchTask(task);
+  }
+
+  async isActiveScheduler(): Promise<boolean> {
+    return this.ownsLock;
+  }
+
+  wake(): void {
+    if (!this.ownsLock || this.stopping || this.initializing) return;
+    if (this.dueTimer) clearTimeout(this.dueTimer);
+    this.dueTimer = setTimeout(() => void this.reconcile(), 0);
+    this.dueTimer.unref?.();
+  }
+
+  private async startAsync(): Promise<void> {
+    this.initializing = true;
+    this.ownsLock = await tryAcquireSchedulerLock(cronLockFile(), this.owner);
+    if (!this.ownsLock) {
+      this.initializing = false;
+      return;
+    }
+    if (this.stopping) {
+      this.ownsLock = false;
+      await releaseSchedulerLock(cronLockFile(), this.owner);
+      this.initializing = false;
+      return;
+    }
+    await this.recordMissedTasks();
+    this.initializing = false;
+    this.reconcileTimer = setInterval(() => void this.reconcile(), RECONCILE_MS);
+    this.reconcileTimer.unref?.();
+    await this.reconcile();
+  }
+
+  private clearTimers(): void {
+    if (this.dueTimer) clearTimeout(this.dueTimer);
+    if (this.reconcileTimer) clearInterval(this.reconcileTimer);
+    this.dueTimer = null;
+    this.reconcileTimer = null;
+  }
+
+  private async reconcile(): Promise<void> {
+    if (!this.ownsLock || this.stopping || this.reconciling) return;
+    this.reconciling = true;
+    try {
+      const now = Date.now();
+      const tasks = await listTasks();
+      for (const task of tasks) await this.processDueTask(task, now);
+      await this.armNextTimer();
+    } finally {
+      this.reconciling = false;
+    }
+  }
+
+  private async processDueTask(task: CronTask, now: number): Promise<void> {
+    if (task.status !== 'active') return;
+    if (task.runtime.bindingStatus !== 'bound') return;
+    if (this.isExpired(task, now)) {
+      await updateTask(task.id, (latest) => ({ ...latest, status: 'completed' }));
+      return;
+    }
+
+    const baseMs = this.lastProcessedMs(task);
+    const jitterMs = task.schedule.jitterMs ?? 0;
+    const latestDue = latestScheduleRunMs(task.schedule, now - jitterMs);
+    if (!latestDue || latestDue <= baseMs) return;
+    const dueCount = countScheduleSlots(task.schedule, baseMs, latestDue);
+    if (dueCount === 0) return;
+
+    if (this.executions.has(task.id)) {
+      await this.markMissed(task, latestDue, dueCount, 'overlap');
+      return;
+    }
+
+    // If the event loop was delayed across several slots, run only the latest
+    // and record all older slots. This keeps skip semantics deterministic.
+    if (dueCount > 1) await this.appendMissed(task, latestDue, dueCount - 1, 'offline');
+    const claimed = await updateTask(task.id, (latest) => ({
+      ...latest,
+      schedule: {
+        ...latest.schedule,
+        lastScheduledFor: new Date(latestDue).toISOString(),
+        lastFiredAt: new Date().toISOString(),
+      },
+      stats: {
+        ...latest.stats,
+        skippedCount: latest.stats.skippedCount + Math.max(0, dueCount - 1),
+      },
+    }));
+    if (claimed && !this.stopping) void this.launchTask(claimed, new Date(latestDue).toISOString());
+  }
+
+  private async recordMissedTasks(): Promise<void> {
+    const now = Date.now();
+    for (const task of await listTasks()) {
+      if (task.status !== 'active') continue;
+      const baseMs = this.lastProcessedMs(task);
+      const latestDue = latestScheduleRunMs(task.schedule, now - (task.schedule.jitterMs ?? 0));
+      if (!latestDue || latestDue <= baseMs) continue;
+      const missedCount = countScheduleSlots(task.schedule, baseMs, latestDue);
+      if (missedCount > 0) await this.markMissed(task, latestDue, missedCount, 'offline');
+    }
+  }
+
+  private async markMissed(
+    task: CronTask,
+    latestDue: number,
+    missedCount: number,
+    reason: 'offline' | 'overlap',
+  ): Promise<void> {
+    await this.appendMissed(task, latestDue, missedCount, reason);
+    await updateTask(task.id, (latest) => ({
+      ...latest,
+      ...(latest.kind === 'once' ? { status: 'paused' as const } : {}),
+      schedule: {
+        ...latest.schedule,
+        lastScheduledFor: new Date(latestDue).toISOString(),
+      },
+      stats: {
+        ...latest.stats,
+        skippedCount: latest.stats.skippedCount + missedCount,
+      },
+    }));
+  }
+
+  private async appendMissed(
+    task: CronTask,
+    latestDue: number,
+    missedCount: number,
+    reason: 'offline' | 'overlap',
+  ): Promise<void> {
+    await appendMissed({
+      id: `missed-${randomUUID().slice(0, 8)}`,
+      taskId: task.id,
+      taskName: task.name,
+      scheduledFor: new Date(latestDue).toISOString(),
+      detectedAt: new Date().toISOString(),
+      actionPreview: actionPreview(task),
+      reason,
+      missedCount,
+    });
+  }
+
+  private async armNextTimer(): Promise<void> {
+    if (!this.ownsLock || this.stopping) return;
+    if (this.dueTimer) clearTimeout(this.dueTimer);
+    let earliest = Number.POSITIVE_INFINITY;
+    for (const task of await listTasks()) {
+      if (task.status !== 'active' || this.isExpired(task, Date.now())) continue;
+      const next = nextScheduleRunMs(task.schedule, this.lastProcessedMs(task));
+      if (next) earliest = Math.min(earliest, next + (task.schedule.jitterMs ?? 0));
+    }
+    if (!Number.isFinite(earliest)) {
+      this.dueTimer = null;
+      return;
+    }
+    const delay = Math.max(0, earliest - Date.now());
+    this.dueTimer = setTimeout(() => void this.reconcile(), delay);
+    this.dueTimer.unref?.();
+  }
+
+  private lastProcessedMs(task: CronTask): number {
+    const raw = task.schedule.lastScheduledFor ?? task.createdAt;
+    const parsed = Date.parse(raw);
+    return Number.isFinite(parsed) ? parsed : Date.now();
+  }
+
+  private isExpired(task: CronTask, now: number): boolean {
+    return Boolean(task.expiresAt && !task.permanent && Date.parse(task.expiresAt) <= now);
+  }
+
+  private launchTask(task: CronTask, scheduledFor?: string): Promise<void> {
+    if (this.executions.has(task.id)) return this.executions.get(task.id)!;
+    const execution = this.runTask(task, scheduledFor).finally(() => {
+      this.executions.delete(task.id);
+      this.wake();
+    });
+    this.executions.set(task.id, execution);
+    return execution;
+  }
+
+  private async runTask(task: CronTask, scheduledFor?: string): Promise<void> {
+    const started = Date.now();
+
+    // Session 绑定失效表示本次根本没有执行。它属于 missed/needs_binding，而不是一次
+    // Agent failure；否则会消耗 maxRuns，并让用户误以为模型真正跑过。
+    if (task.runtime.sessionMode !== 'fresh' && !existsSync(await resolveSessionFile(task.runtime.cwd, task.runtime.sessionId))) {
+      const detectedAt = new Date().toISOString();
+      await updateTask(task.id, (latest) => ({
+        ...latest,
+        runtime: { ...latest.runtime, bindingStatus: 'needs_binding' },
+        ...(latest.status === 'active' ? { status: 'paused' as const } : {}),
+        stats: {
+          ...latest.stats,
+          skippedCount: latest.stats.skippedCount + (scheduledFor ? 1 : 0),
+        },
+      }));
+      await appendMissed({
+        id: `missed-${randomUUID().slice(0, 8)}`,
+        taskId: task.id,
+        taskName: task.name,
+        scheduledFor: scheduledFor ?? detectedAt,
+        detectedAt,
+        actionPreview: actionPreview(task),
+        reason: 'binding_unavailable',
+        missedCount: 1,
+      });
+      return;
+    }
+
+    const run: CronRunRecord = {
+      id: `run-${randomUUID().slice(0, 8)}`,
+      taskId: task.id,
+      taskName: task.name,
+      ...(scheduledFor ? { scheduledFor } : {}),
+      startedAt: new Date(started).toISOString(),
+      status: 'running',
+      cwd: task.runtime.cwd,
+      sessionId: task.runtime.sessionId,
+      ...(task.runtime.model ? { model: task.runtime.model } : {}),
+    };
+    await appendRun(run);
+
+    try {
+      const input = task.action.type === 'workflow'
+        ? `/workflow ${task.action.command}`
+        : task.action.prompt;
+      const sessionId = task.runtime.sessionId;
+      const result = await this.ctx.runAgentTurn({
+        input,
+        provider: this.ctx.provider,
+        cwd: task.runtime.cwd,
+        sessionId,
+        maxTurns: task.runtime.maxTurns,
+        model: task.runtime.model,
+        signal: combineSignals(this.ctx.signal, this.executionController.signal),
+      });
+      const executionOk = result.ok && !this.executionController.signal.aborted;
+      const executionError = this.executionController.signal.aborted
+        ? 'cron scheduler stopped during execution'
+        : result.error;
+      const finishedAt = new Date().toISOString();
+      await updateTask(task.id, (latest) => ({
+        ...latest,
+        ...(reachedRunLimit(latest, latest.stats.runCount + 1)
+          ? { status: 'completed' as const }
+          : {}),
+        stats: {
+          ...latest.stats,
+          runCount: latest.stats.runCount + 1,
+          successCount: latest.stats.successCount + (executionOk ? 1 : 0),
+          failureCount: latest.stats.failureCount + (executionOk ? 0 : 1),
+          lastRunAt: finishedAt,
+          ...(executionOk ? { lastSuccessAt: finishedAt } : { lastFailureAt: finishedAt }),
+        },
+      }));
+      await appendRun({
+        ...run,
+        finishedAt,
+        status: executionOk ? 'success' : 'failure',
+        durationMs: Date.now() - started,
+        resultPreview: result.result.slice(0, 1000),
+        ...(!executionOk ? { attentionReason: 'failure' as const } : {}),
+        ...(executionError ? { error: executionError } : {}),
+      });
+    } catch (err) {
+      const finishedAt = new Date().toISOString();
+      await updateTask(task.id, (latest) => ({
+        ...latest,
+        ...(reachedRunLimit(latest, latest.stats.runCount + 1)
+          ? { status: 'completed' as const }
+          : {}),
+        stats: {
+          ...latest.stats,
+          runCount: latest.stats.runCount + 1,
+          failureCount: latest.stats.failureCount + 1,
+          lastRunAt: finishedAt,
+          lastFailureAt: finishedAt,
+        },
+      }));
+      await appendRun({
+        ...run,
+        finishedAt,
+        status: 'failure',
+        durationMs: Date.now() - started,
+        attentionReason: 'failure',
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+function reachedRunLimit(task: CronTask, nextRunCount: number): boolean {
+  if (task.kind === 'once') return true;
+  return typeof task.maxRuns === 'number' && task.maxRuns > 0 && nextRunCount >= task.maxRuns;
+}
+
+function actionPreview(task: CronTask): string {
+  const text = task.action.type === 'workflow'
+    ? `/workflow ${task.action.command}`
+    : task.action.prompt;
+  return text.length > 160 ? `${text.slice(0, 157)}...` : text;
+}
+
+function combineSignals(parent: AbortSignal | undefined, local: AbortSignal): AbortSignal {
+  return parent ? AbortSignal.any([parent, local]) : local;
+}

package/plugins/cron-runner/src/schema.ts

@@ -0,0 +1,139 @@
+import type { CronTask } from './types.js';
+import { cronToHuman, nextCronRunMs, parseCronExpression } from './cronTime.js';
+import { intervalToHuman, MIN_INTERVAL_MS } from './scheduleEngine.js';
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; error: string };
+
+export function validateCron(cron: string): ValidationResult {
+  const parsed = parseCronExpression(cron);
+  if (!parsed) return { ok: false, error: 'cron 必须是合法的 5 字段表达式。' };
+  if (nextCronRunMs(cron) === null) {
+    return { ok: false, error: 'cron 在未来一年内没有可运行时间。' };
+  }
+  return { ok: true };
+}
+
+export function validateIsoDate(value: string, field: string): ValidationResult {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) return { ok: false, error: `${field} 必须是 ISO 时间。` };
+  return { ok: true };
+}
+
+export function normalizeTask(raw: unknown): CronTask | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const task = raw as Partial<CronTask> & Record<string, unknown>;
+  if (typeof task.id !== 'string' || !task.id) return null;
+  if (typeof task.name !== 'string' || !task.name) return null;
+  if (task.status !== 'active' && task.status !== 'paused' && task.status !== 'completed') return null;
+  if (!task.schedule || typeof task.schedule !== 'object') return null;
+  const schedule = task.schedule as unknown as Record<string, unknown>;
+  const scheduleType = schedule.type === 'interval' ? 'interval' : 'cron';
+  if (scheduleType === 'cron') {
+    if (typeof schedule.cron !== 'string' || !parseCronExpression(schedule.cron)) return null;
+  } else if (
+    typeof schedule.intervalMs !== 'number' ||
+    schedule.intervalMs < MIN_INTERVAL_MS ||
+    typeof schedule.anchorAt !== 'string' ||
+    !Number.isFinite(Date.parse(schedule.anchorAt))
+  ) {
+    return null;
+  }
+  if (!task.action || typeof task.action !== 'object') return null;
+  const action = task.action as CronTask['action'];
+  if (action.type === 'prompt') {
+    if (typeof action.prompt !== 'string' || !action.prompt) return null;
+  } else if (action.type === 'workflow') {
+    if (typeof action.command !== 'string' || !action.command) return null;
+  } else {
+    return null;
+  }
+  if (!task.runtime || typeof task.runtime !== 'object') return null;
+  const runtime = task.runtime as Partial<CronTask['runtime']>;
+  if (typeof runtime.cwd !== 'string' || !runtime.cwd) return null;
+  if (runtime.environment && runtime.environment !== 'project') return null;
+
+  const now = new Date().toISOString();
+  const kind = task.kind === 'once' ? 'once' : 'recurring';
+  const timezone =
+    typeof schedule.timezone === 'string' && schedule.timezone
+      ? schedule.timezone
+      : Intl.DateTimeFormat().resolvedOptions().timeZone || 'local';
+  const stats: Partial<CronTask['stats']> = task.stats ?? {
+    runCount: 0,
+    successCount: 0,
+    failureCount: 0,
+  };
+
+  const legacyNeedsBinding =
+    runtime.sessionMode === 'fresh' ||
+    typeof runtime.sessionId !== 'string' ||
+    !runtime.sessionId ||
+    runtime.sessionId.startsWith('cron-');
+  const bindingStatus = runtime.bindingStatus === 'needs_binding' || legacyNeedsBinding
+    ? 'needs_binding'
+    : 'bound';
+
+  return {
+    id: task.id,
+    name: task.name,
+    ...(typeof task.description === 'string' && task.description
+      ? { description: task.description }
+      : {}),
+    status: bindingStatus === 'needs_binding' && task.status === 'active' ? 'paused' : task.status,
+    kind,
+    ...(task.permanent ? { permanent: true } : {}),
+    ...(typeof task.expiresAt === 'string' ? { expiresAt: task.expiresAt } : {}),
+    ...(typeof task.maxRuns === 'number' && task.maxRuns > 0 ? { maxRuns: task.maxRuns } : {}),
+    schedule: scheduleType === 'interval' ? {
+      type: 'interval',
+      intervalMs: schedule.intervalMs as number,
+      anchorAt: schedule.anchorAt as string,
+      human: intervalToHuman(schedule.intervalMs as number),
+      ...(typeof schedule.nextRunAt === 'string' ? { nextRunAt: schedule.nextRunAt } : {}),
+      ...(typeof schedule.lastFiredAt === 'string' ? { lastFiredAt: schedule.lastFiredAt } : {}),
+      ...(typeof schedule.lastScheduledFor === 'string'
+        ? { lastScheduledFor: schedule.lastScheduledFor }
+        : {}),
+      ...(typeof schedule.jitterMs === 'number' ? { jitterMs: schedule.jitterMs } : {}),
+    } : {
+      type: 'cron',
+      cron: schedule.cron as string,
+      timezone,
+      human: cronToHuman(schedule.cron as string),
+      ...(typeof schedule.nextRunAt === 'string' ? { nextRunAt: schedule.nextRunAt } : {}),
+      ...(typeof schedule.lastFiredAt === 'string' ? { lastFiredAt: schedule.lastFiredAt } : {}),
+      ...(typeof schedule.lastScheduledFor === 'string'
+        ? { lastScheduledFor: schedule.lastScheduledFor }
+        : {}),
+      ...(typeof schedule.jitterMs === 'number' ? { jitterMs: schedule.jitterMs } : {}),
+    },
+    action,
+    runtime: {
+      cwd: runtime.cwd,
+      environment: 'project',
+      sessionId:
+        typeof runtime.sessionId === 'string' && runtime.sessionId
+          ? runtime.sessionId
+          : `cron-${task.id}`,
+      sessionMode: bindingStatus === 'bound' ? 'persistent' : (runtime.sessionMode === 'fresh' ? 'fresh' : 'persistent'),
+      bindingStatus,
+      ...(typeof runtime.model === 'string' && runtime.model ? { model: runtime.model } : {}),
+      ...(typeof runtime.maxTurns === 'number' && runtime.maxTurns > 0
+        ? { maxTurns: runtime.maxTurns }
+        : {}),
+    },
+    stats: {
+      runCount: typeof stats.runCount === 'number' ? stats.runCount : 0,
+      successCount: typeof stats.successCount === 'number' ? stats.successCount : 0,
+      failureCount: typeof stats.failureCount === 'number' ? stats.failureCount : 0,
+      skippedCount: typeof stats.skippedCount === 'number' ? stats.skippedCount : 0,
+      ...(typeof stats.lastRunAt === 'string' ? { lastRunAt: stats.lastRunAt } : {}),
+      ...(typeof stats.lastSuccessAt === 'string' ? { lastSuccessAt: stats.lastSuccessAt } : {}),
+      ...(typeof stats.lastFailureAt === 'string' ? { lastFailureAt: stats.lastFailureAt } : {}),
+    },
+    createdAt: typeof task.createdAt === 'string' ? task.createdAt : now,
+    updatedAt: typeof task.updatedAt === 'string' ? task.updatedAt : now,
+  };
+}