feat(tasks): support markdown scheduled-task loops in .agents/loops

Adds markdown-based scheduled-task definitions ("loops") discovered from .agents/loops/*.md (project scope, ancestor directories up to the worktree root) and ~/.agents/loops/*.md (user scope), mirroring the skills discovery pattern. File format: YAML frontmatter (name, schedule cron, enabled, model as provider/model, optional agent/timezone) plus the markdown body as the execution prompt. Discovery and parsing live in scheduled-tasks/loops.js; project-config gains reconcileLoopTasks which runs inside the project write lock on every syncProject: - identity by task name; a loop takes over a matching task, preserving its id and runtime state (markdown wins on conflict with JSON) - tasks whose loopFile is gone are unscheduled; JSON tasks are never removed - new loops are created under deterministic loop:<scope>:<name> ids - project scope shadows user scope on name collisions - malformed files are skipped with a warning and never block valid ones Runtime state stays in the project config/state store; it is never written to the markdown files. Module documentation updated with the file format and reconciliation rules. Fixes #2583
2026-08-05 14:11:28 +03:00
parent 34c221b07f
commit 2fcfe511a5
6 changed files with 861 additions and 3 deletions
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import os from 'os';
 import path from 'path';
 import { mkdtemp, rm, readFile, writeFile } from 'fs/promises';
@@ -173,3 +173,160 @@ describe('project-config runtime', () => {
    }
  });
 });
+
+describe('project-config loop reconciliation', () => {
+  const loop = (name, overrides = {}) => ({
+    scope: 'project',
+    filePath: `/repo/.agents/loops/${name}.md`,
+    definition: {
+      name,
+      enabled: true,
+      schedule: { kind: 'cron', cron: '0 9 * * *', timezone: 'UTC' },
+      execution: {
+        prompt: `Loop prompt for ${name}`,
+        providerID: 'openai',
+        modelID: 'gpt-4.1',
+      },
+      ...overrides,
+    },
+  });
+
+  it('creates tasks for discovered loops with deterministic ids', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const tasks = await runtime.reconcileLoopTasks('project-test', [
+        loop('daily-digest'),
+        loop('weekly-report'),
+      ]);
+
+      expect(tasks).toHaveLength(2);
+      const digest = tasks.find((task) => task.name === 'daily-digest');
+      expect(digest.id).toBe('loop:project:daily-digest');
+      expect(digest.schedule.cron).toBe('0 9 * * *');
+      expect(digest.execution.providerID).toBe('openai');
+      expect(digest.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+
+      const reloaded = await runtime.listScheduledTasks('project-test');
+      expect(reloaded).toHaveLength(2);
+      expect(reloaded[0].state.createdAt).toBeGreaterThan(0);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('adopts an existing task by name, preserving id and state, and persists state across reconciles', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'daily-digest',
+        enabled: true,
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: { prompt: 'JSON prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      const first = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const adopted = first.find((task) => task.id === created.task.id);
+      expect(adopted).toBeDefined();
+      expect(adopted.id).toBe(created.task.id);
+      expect(adopted.name).toBe('daily-digest');
+      expect(adopted.schedule.kind).toBe('cron');
+      expect(adopted.schedule.cron).toBe('0 9 * * *');
+      expect(adopted.execution.prompt).toBe('Loop prompt for daily-digest');
+      expect(adopted.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+
+      const state = adopted.state;
+      await runtime.updateScheduledTaskState('project-test', adopted.id, {
+        nextRunAt: 123456,
+        lastRunAt: 111,
+        lastStatus: 'success',
+      });
+
+      const second = await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const again = second.find((task) => task.id === created.task.id);
+      expect(again.id).toBe(created.task.id);
+      expect(again.state.nextRunAt).toBe(123456);
+      expect(again.state.lastRunAt).toBe(111);
+      expect(again.state.lastStatus).toBe('success');
+      expect(again.loopFile).toBe('/repo/.agents/loops/daily-digest.md');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('unschedules a loop-sourced task when its file is removed', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      const tasks = await runtime.reconcileLoopTasks('project-test', []);
+
+      expect(tasks).toHaveLength(0);
+      expect(await runtime.listScheduledTasks('project-test')).toHaveLength(0);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('leaves JSON-configured tasks untouched when no loop matches', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'json-only',
+        enabled: true,
+        schedule: { kind: 'daily', time: '08:00', timezone: 'UTC' },
+        execution: { prompt: 'JSON prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      const tasks = await runtime.reconcileLoopTasks('project-test', [loop('loop-only')]);
+
+      expect(tasks).toHaveLength(2);
+      expect(tasks.find((task) => task.id === created.task.id)).toBeDefined();
+      expect(tasks.find((task) => task.name === 'loop-only')).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('does not remove a JSON task that merely shares a loop name after the loop is gone... keeps it when never adopted', async () => {
+    // A JSON task that was never driven by a loop file (no loopFile marker)
+    // must survive reconciles even when a loop with the same name existed
+    // only in a previous reconcile round — but once a loop adopted it, the
+    // file is authoritative and removing the file unschedules the task.
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const created = await runtime.upsertScheduledTask('project-test', {
+        name: 'daily-digest',
+        enabled: true,
+        schedule: { kind: 'daily', time: '09:30', timezone: 'UTC' },
+        execution: { prompt: 'JSON prompt', providerID: 'openai', modelID: 'gpt-4.1' },
+      });
+
+      // First reconcile adopts the task (loopFile marker set).
+      await runtime.reconcileLoopTasks('project-test', [loop('daily-digest')]);
+      // Loop file removed -> task unscheduled.
+      const afterRemoval = await runtime.reconcileLoopTasks('project-test', []);
+      expect(afterRemoval.find((task) => task.id === created.task.id)).toBeUndefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('skips invalid loop definitions without blocking valid ones', async () => {
+    const { runtime, cleanup } = await createRuntime();
+    try {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      try {
+        const tasks = await runtime.reconcileLoopTasks('project-test', [
+          loop('bad-loop', { schedule: { kind: 'cron', cron: 'not a cron', timezone: 'UTC' } }),
+          loop('good-loop'),
+        ]);
+
+        expect(tasks.map((task) => task.name)).toEqual(['good-loop']);
+        expect(warn).toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+});