@aaroncql/pim-agent 0.0.1

package/src/telegram/TaskScheduler.test.ts

@@ -0,0 +1,278 @@
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import type { SessionId } from "./Session";
+import { TaskScheduler } from "./TaskScheduler";
+import type { ScheduledTask } from "./TaskSchema";
+import { TaskStore } from "./TaskStore";
+
+let tmp: string;
+const sessionId: SessionId = { chatId: 42, threadId: undefined };
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), "pim-scheduler-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true });
+});
+
+function makeScheduler(opts: {
+  readonly now: () => number;
+  readonly onFire?: (task: ScheduledTask) => Promise<void>;
+}): { readonly scheduler: TaskScheduler; readonly fired: ScheduledTask[] } {
+  const fired: ScheduledTask[] = [];
+  const scheduler = new TaskScheduler({
+    configDir: tmp,
+    runTask: async (task) => {
+      fired.push(task);
+      await opts.onFire?.(task);
+    },
+    now: opts.now,
+  });
+  return { scheduler, fired };
+}
+
+async function listTaskFiles(): Promise<string[]> {
+  try {
+    return await readdir(join(tmp, "tasks"));
+  } catch {
+    return [];
+  }
+}
+
+describe("TaskScheduler.parseDuration", () => {
+  test("parses simple units", () => {
+    expect(TaskScheduler.parseDuration("30s")).toBe(30_000);
+    expect(TaskScheduler.parseDuration("5m")).toBe(300_000);
+    expect(TaskScheduler.parseDuration("2h")).toBe(7_200_000);
+    expect(TaskScheduler.parseDuration("1d")).toBe(86_400_000);
+  });
+
+  test("parses compound durations", () => {
+    expect(TaskScheduler.parseDuration("1h30m")).toBe(5_400_000);
+    expect(TaskScheduler.parseDuration("2h15m30s")).toBe(8_130_000);
+  });
+
+  test("rejects garbage", () => {
+    expect(() => TaskScheduler.parseDuration("")).toThrow();
+    expect(() => TaskScheduler.parseDuration("forever")).toThrow();
+    expect(() => TaskScheduler.parseDuration("10")).toThrow();
+  });
+});
+
+describe("TaskScheduler.tick", () => {
+  test("fires due active task and reschedules interval", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler, fired } = makeScheduler({ now: () => t0 });
+    const task = await scheduler.create(sessionId, {
+      prompt: "test",
+      schedule: { type: "interval", every: "30m" },
+    });
+    expect(task.nextRun).toBe(new Date(t0 + 30 * 60_000).toISOString());
+
+    // Not yet due
+    await scheduler.tick();
+    expect(fired).toHaveLength(0);
+
+    // 30 min later, due
+    const t1 = t0 + 30 * 60_000 + 5_000;
+    const later = makeScheduler({ now: () => t1 });
+    await later.scheduler.tick();
+    expect(later.fired).toHaveLength(1);
+    expect(later.fired[0]!.id).toBe(task.id);
+
+    const reloaded = (await TaskStore.loadAll(tmp))[0]!;
+    expect(reloaded.nextRun).toBe(new Date(t1 + 30 * 60_000).toISOString());
+  });
+
+  test("skips paused tasks", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    const task = await scheduler.create(sessionId, {
+      prompt: "test",
+      schedule: { type: "interval", every: "5m" },
+    });
+    await scheduler.setStatus(sessionId, task.id, "paused");
+
+    const t1 = t0 + 6 * 60_000;
+    const { scheduler: s2, fired } = makeScheduler({ now: () => t1 });
+    await s2.tick();
+    expect(fired).toHaveLength(0);
+
+    // File still exists
+    expect(await listTaskFiles()).toHaveLength(1);
+  });
+
+  test("once task is deleted after firing", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    const at = new Date(t0 + 60_000).toISOString();
+    await scheduler.create(sessionId, {
+      prompt: "test",
+      schedule: { type: "once", at },
+    });
+
+    const t1 = t0 + 90_000;
+    const { scheduler: s2, fired } = makeScheduler({ now: () => t1 });
+    await s2.tick();
+    expect(fired).toHaveLength(1);
+    expect(await listTaskFiles()).toHaveLength(0);
+  });
+
+  test("missed >24h is advanced silently without firing", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    // Manually write a task whose nextRun is 26h in the past
+    const stale: ScheduledTask = {
+      id: "stale-task",
+      prompt: "test",
+      chatId: sessionId.chatId,
+      threadId: sessionId.threadId,
+      schedule: { type: "interval", every: "1h" },
+      status: "active",
+      nextRun: new Date(t0 - 26 * 3600_000).toISOString(),
+      expires: null,
+      isolatedSession: false,
+      createdAt: new Date(t0 - 30 * 3600_000).toISOString(),
+    };
+    await TaskStore.save(tmp, stale);
+
+    const { scheduler, fired } = makeScheduler({ now: () => t0 });
+    await scheduler.tick();
+    expect(fired).toHaveLength(0);
+
+    const reloaded = (await TaskStore.loadAll(tmp))[0]!;
+    expect(Date.parse(reloaded.nextRun)).toBeGreaterThan(t0);
+  });
+
+  test("missed <24h fires once", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const stale: ScheduledTask = {
+      id: "recent-miss",
+      prompt: "test",
+      chatId: sessionId.chatId,
+      threadId: sessionId.threadId,
+      schedule: { type: "interval", every: "1h" },
+      status: "active",
+      nextRun: new Date(t0 - 2 * 3600_000).toISOString(),
+      expires: null,
+      isolatedSession: false,
+      createdAt: new Date(t0 - 5 * 3600_000).toISOString(),
+    };
+    await TaskStore.save(tmp, stale);
+
+    const { scheduler, fired } = makeScheduler({ now: () => t0 });
+    await scheduler.tick();
+    expect(fired).toHaveLength(1);
+  });
+
+  test("expired task is deleted without firing", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const expired: ScheduledTask = {
+      id: "expired",
+      prompt: "test",
+      chatId: sessionId.chatId,
+      threadId: sessionId.threadId,
+      schedule: { type: "interval", every: "1h" },
+      status: "active",
+      nextRun: new Date(t0 - 60_000).toISOString(),
+      expires: new Date(t0 - 30_000).toISOString(),
+      isolatedSession: false,
+      createdAt: new Date(t0 - 2 * 3600_000).toISOString(),
+    };
+    await TaskStore.save(tmp, expired);
+
+    const { scheduler, fired } = makeScheduler({ now: () => t0 });
+    await scheduler.tick();
+    expect(fired).toHaveLength(0);
+    expect(await listTaskFiles()).toHaveLength(0);
+  });
+
+  test("cron task next-run advances via Bun.cron.parse", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    const task = await scheduler.create(sessionId, {
+      prompt: "test",
+      schedule: { type: "cron", expr: "0 * * * *" },
+    });
+    expect(task.nextRun).toBe(new Date(t0 + 3600_000).toISOString());
+
+    // Fire it
+    const fireTime = t0 + 3600_000 + 30_000;
+    const { scheduler: s2, fired } = makeScheduler({ now: () => fireTime });
+    await s2.tick();
+    expect(fired).toHaveLength(1);
+
+    const reloaded = (await TaskStore.loadAll(tmp))[0]!;
+    // Should advance to next top-of-hour after firing
+    expect(Date.parse(reloaded.nextRun)).toBeGreaterThan(fireTime);
+  });
+});
+
+describe("TaskScheduler.create validation", () => {
+  test("rejects 'once' with past timestamp", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    await expect(
+      scheduler.create(sessionId, {
+        prompt: "test",
+        schedule: { type: "once", at: new Date(t0 - 1000).toISOString() },
+      })
+    ).rejects.toThrow();
+  });
+
+  test("rejects sub-minute interval", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    await expect(
+      scheduler.create(sessionId, {
+        prompt: "test",
+        schedule: { type: "interval", every: "30s" },
+      })
+    ).rejects.toThrow();
+  });
+
+  test("rejects expires before first nextRun", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    await expect(
+      scheduler.create(sessionId, {
+        prompt: "test",
+        schedule: { type: "interval", every: "1h" },
+        expires: new Date(t0 + 5 * 60_000).toISOString(),
+      })
+    ).rejects.toThrow();
+  });
+});
+
+describe("TaskScheduler.list", () => {
+  test("filters by chat/thread", async () => {
+    const t0 = Date.parse("2026-05-14T12:00:00Z");
+    const { scheduler } = makeScheduler({ now: () => t0 });
+    await scheduler.create(
+      { chatId: 1, threadId: undefined },
+      { prompt: "a", schedule: { type: "interval", every: "1h" } }
+    );
+    await scheduler.create(
+      { chatId: 1, threadId: 99 },
+      { prompt: "b", schedule: { type: "interval", every: "1h" } }
+    );
+    await scheduler.create(
+      { chatId: 2, threadId: undefined },
+      { prompt: "c", schedule: { type: "interval", every: "1h" } }
+    );
+
+    const main = await scheduler.list({
+      chatId: 1,
+      threadId: undefined,
+    });
+    expect(main).toHaveLength(1);
+    expect(main[0]!.prompt).toBe("a");
+
+    const threaded = await scheduler.list({ chatId: 1, threadId: 99 });
+    expect(threaded).toHaveLength(1);
+    expect(threaded[0]!.prompt).toBe("b");
+  });
+});

package/src/telegram/TaskScheduler.ts

@@ -0,0 +1,293 @@
+import type { SessionId } from "./Session";
+import type { ScheduleSpec, ScheduledTask } from "./TaskSchema";
+import { TaskStore } from "./TaskStore";
+
+export type RunTaskFn = (task: ScheduledTask) => Promise<void>;
+
+export type TaskSchedulerOptions = {
+  readonly configDir: string;
+  readonly runTask: RunTaskFn;
+  readonly pollIntervalMs?: number;
+  readonly now?: () => number;
+};
+
+const MISSED_TASK_WINDOW_MS = 24 * 3600_000;
+const MIN_INTERVAL_MS = 60_000;
+
+export class TaskScheduler {
+  private readonly configDir: string;
+  private readonly runTask: RunTaskFn;
+  private readonly pollIntervalMs: number;
+  private readonly now: () => number;
+  private timer: Timer | undefined;
+  private inflight: Promise<void> | undefined;
+
+  public constructor(opts: TaskSchedulerOptions) {
+    this.configDir = opts.configDir;
+    this.runTask = opts.runTask;
+    this.pollIntervalMs = opts.pollIntervalMs ?? 10_000;
+    this.now = opts.now ?? ((): number => Date.now());
+  }
+
+  public async start(): Promise<void> {
+    if (this.timer) {
+      return;
+    }
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, this.pollIntervalMs);
+    await this.tick();
+  }
+
+  public async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    if (this.inflight) {
+      await this.inflight;
+    }
+  }
+
+  public async tick(): Promise<void> {
+    if (this.inflight) {
+      await this.inflight;
+      return;
+    }
+    const run = this.runTick().finally(() => {
+      this.inflight = undefined;
+    });
+    this.inflight = run;
+    await run;
+  }
+
+  public async list(
+    sessionId: SessionId
+  ): Promise<ReadonlyArray<ScheduledTask>> {
+    const all = await TaskStore.loadAll(this.configDir);
+    return all
+      .filter(
+        (t) =>
+          t.chatId === sessionId.chatId && t.threadId === sessionId.threadId
+      )
+      .sort((a, b) => a.nextRun.localeCompare(b.nextRun));
+  }
+
+  public async create(
+    sessionId: SessionId,
+    input: {
+      readonly prompt: string;
+      readonly schedule: ScheduleSpec;
+      readonly expires?: string;
+      readonly isolatedSession?: boolean;
+    }
+  ): Promise<ScheduledTask> {
+    const nextRun = this.computeFirstRun(input.schedule);
+    if (input.expires !== undefined) {
+      const expMs = Date.parse(input.expires);
+      if (!Number.isFinite(expMs)) {
+        throw new Error(`invalid expires timestamp: ${input.expires}`);
+      }
+      if (expMs <= Date.parse(nextRun)) {
+        throw new Error(
+          `expires must be strictly after first nextRun (${nextRun})`
+        );
+      }
+    }
+    const task: ScheduledTask = {
+      id: TaskStore.makeId(input.prompt),
+      prompt: input.prompt,
+      chatId: sessionId.chatId,
+      threadId: sessionId.threadId,
+      schedule: input.schedule,
+      status: "active",
+      nextRun,
+      expires: input.expires ?? null,
+      isolatedSession: input.isolatedSession ?? false,
+      createdAt: new Date(this.now()).toISOString(),
+    };
+    await TaskStore.save(this.configDir, task);
+    return task;
+  }
+
+  public async delete(sessionId: SessionId, id: string): Promise<boolean> {
+    const t = await this.find(sessionId, id);
+    if (!t) {
+      return false;
+    }
+    await TaskStore.delete(this.configDir, id);
+    return true;
+  }
+
+  public async setStatus(
+    sessionId: SessionId,
+    id: string,
+    status: "active" | "paused"
+  ): Promise<ScheduledTask | undefined> {
+    const t = await this.find(sessionId, id);
+    if (!t) {
+      return undefined;
+    }
+    if (t.status === status) {
+      return t;
+    }
+    const updated: ScheduledTask = { ...t, status };
+    await TaskStore.save(this.configDir, updated);
+    return updated;
+  }
+
+  public async updatePrompt(
+    sessionId: SessionId,
+    id: string,
+    prompt: string
+  ): Promise<ScheduledTask | undefined> {
+    const t = await this.find(sessionId, id);
+    if (!t) {
+      return undefined;
+    }
+    if (t.prompt === prompt) {
+      return t;
+    }
+    const updated: ScheduledTask = { ...t, prompt };
+    await TaskStore.save(this.configDir, updated);
+    return updated;
+  }
+
+  private async find(
+    sessionId: SessionId,
+    id: string
+  ): Promise<ScheduledTask | undefined> {
+    const all = await this.list(sessionId);
+    return all.find((t) => t.id === id);
+  }
+
+  private async runTick(): Promise<void> {
+    const all = await TaskStore.loadAll(this.configDir);
+    const now = this.now();
+    const fires: Promise<void>[] = [];
+
+    for (const task of all) {
+      if (task.status !== "active") {
+        continue;
+      }
+      const nextMs = Date.parse(task.nextRun);
+      if (!Number.isFinite(nextMs) || nextMs > now) {
+        continue;
+      }
+
+      if (task.expires) {
+        const expMs = Date.parse(task.expires);
+        if (Number.isFinite(expMs) && now > expMs) {
+          await TaskStore.delete(this.configDir, task.id);
+          continue;
+        }
+      }
+
+      if (now - nextMs > MISSED_TASK_WINDOW_MS) {
+        const advanced = TaskScheduler.advanceNextRun(task, now);
+        if (advanced) {
+          await TaskStore.save(this.configDir, advanced);
+        } else {
+          await TaskStore.delete(this.configDir, task.id);
+        }
+        console.warn(
+          `[scheduler] task ${task.id} missed by >24h, advanced silently`
+        );
+        continue;
+      }
+
+      fires.push(this.fireAndReschedule(task, now));
+    }
+
+    await Promise.allSettled(fires);
+  }
+
+  private async fireAndReschedule(
+    task: ScheduledTask,
+    firedAt: number
+  ): Promise<void> {
+    try {
+      await this.runTask(task);
+    } catch (err) {
+      console.error(`[scheduler] task ${task.id} runTask failed:`, err);
+    }
+    const next = TaskScheduler.advanceNextRun(task, firedAt);
+    if (next) {
+      await TaskStore.save(this.configDir, next);
+    } else {
+      await TaskStore.delete(this.configDir, task.id);
+    }
+  }
+
+  private computeFirstRun(schedule: ScheduleSpec): string {
+    const now = this.now();
+    if (schedule.type === "once") {
+      const at = Date.parse(schedule.at);
+      if (!Number.isFinite(at)) {
+        throw new Error(`invalid 'at' timestamp: ${schedule.at}`);
+      }
+      if (at <= now) {
+        throw new Error(`'at' must be strictly in the future`);
+      }
+      return new Date(at).toISOString();
+    }
+    if (schedule.type === "interval") {
+      const ms = TaskScheduler.parseDuration(schedule.every);
+      if (ms < MIN_INTERVAL_MS) {
+        throw new Error(`interval must be at least 1 minute`);
+      }
+      return new Date(now + ms).toISOString();
+    }
+    const next = Bun.cron.parse(schedule.expr, new Date(now));
+    if (!next) {
+      throw new Error(`cron expression has no future match: ${schedule.expr}`);
+    }
+    return next.toISOString();
+  }
+
+  private static advanceNextRun(
+    task: ScheduledTask,
+    fromMs: number
+  ): ScheduledTask | undefined {
+    const schedule = task.schedule;
+    if (schedule.type === "once") {
+      return undefined;
+    }
+    if (schedule.type === "interval") {
+      const ms = TaskScheduler.parseDuration(schedule.every);
+      return { ...task, nextRun: new Date(fromMs + ms).toISOString() };
+    }
+    const next = Bun.cron.parse(schedule.expr, new Date(fromMs));
+    if (!next) {
+      return undefined;
+    }
+    return { ...task, nextRun: next.toISOString() };
+  }
+
+  public static parseDuration(input: string): number {
+    const s = input.trim();
+    if (!s) {
+      throw new Error("empty duration");
+    }
+    let remaining = s;
+    let total = 0;
+    while (remaining.length > 0) {
+      const m = remaining.match(/^(\d+)([smhd])/);
+      if (!m) {
+        throw new Error(`bad duration: ${input}`);
+      }
+      const n = Number(m[1]);
+      const mult = DURATION_UNITS[m[2]!]!;
+      total += n * mult;
+      remaining = remaining.slice(m[0].length);
+    }
+    return total;
+  }
+}
+
+const DURATION_UNITS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};

package/src/telegram/TaskSchema.ts

@@ -0,0 +1,88 @@
+import { type Static, Type } from "typebox";
+
+export type ScheduleSpec =
+  | { readonly type: "once"; readonly at: string }
+  | { readonly type: "interval"; readonly every: string }
+  | { readonly type: "cron"; readonly expr: string };
+
+export type ScheduledTask = {
+  readonly id: string;
+  readonly prompt: string;
+  readonly chatId: number;
+  readonly threadId: number | undefined;
+  readonly schedule: ScheduleSpec;
+  readonly status: "active" | "paused";
+  readonly nextRun: string;
+  readonly expires: string | null;
+  readonly isolatedSession: boolean;
+  readonly createdAt: string;
+};
+
+const scheduleSchema = Type.Union([
+  Type.Object({
+    type: Type.Literal("once"),
+    at: Type.String({
+      description:
+        "RFC3339 timestamp in the future, UTC. Example: '2026-05-14T15:30:00Z'.",
+    }),
+  }),
+  Type.Object({
+    type: Type.Literal("interval"),
+    every: Type.String({
+      description:
+        "Duration like '30m', '2h', '1h30m'. Units: s, m, h, d. Minimum 1 minute.",
+    }),
+  }),
+  Type.Object({
+    type: Type.Literal("cron"),
+    expr: Type.String({
+      description:
+        "Standard 5-field cron expression in UTC. Macros @hourly, @daily, @weekly, @monthly, @yearly supported.",
+    }),
+  }),
+]);
+
+export const taskToolSchema = Type.Object({
+  action: Type.Union(
+    [
+      Type.Literal("create"),
+      Type.Literal("list"),
+      Type.Literal("delete"),
+      Type.Literal("pause"),
+      Type.Literal("resume"),
+      Type.Literal("update_prompt"),
+    ],
+    {
+      description:
+        "create: schedule a new task. list: see this thread's tasks. delete/pause/resume: by id. update_prompt: change a task's prompt.",
+    }
+  ),
+  prompt: Type.Optional(
+    Type.String({
+      description:
+        "Required for 'create' and 'update_prompt'. The instruction the agent will receive when the task fires.",
+      minLength: 1,
+    })
+  ),
+  schedule: Type.Optional(scheduleSchema),
+  expires: Type.Optional(
+    Type.String({
+      description:
+        "Optional RFC3339 timestamp after which the task auto-deletes without firing again.",
+    })
+  ),
+  isolatedSession: Type.Optional(
+    Type.Boolean({
+      description:
+        "If true, run in a fresh/isolated session with no chat history. Default false.",
+    })
+  ),
+  id: Type.Optional(
+    Type.String({
+      description:
+        "Task id. Required for delete, pause, resume, update_prompt.",
+    })
+  ),
+});
+
+export type TaskToolInput = Static<typeof taskToolSchema>;