schedules for background agents

apps/x/packages/core/src/agent-schedule/repo.ts

@@ -0,0 +1,43 @@
+import { WorkDir } from "../config/config.js";
+import { AgentScheduleConfig, AgentScheduleEntry } from "@x/shared/dist/agent-schedule.js";
+import fs from "fs/promises";
+import path from "path";
+import z from "zod";
+
+const DEFAULT_AGENT_SCHEDULES: z.infer<typeof AgentScheduleConfig>["agents"] = {};
+
+export interface IAgentScheduleRepo {
+    ensureConfig(): Promise<void>;
+    getConfig(): Promise<z.infer<typeof AgentScheduleConfig>>;
+    upsert(agentName: string, entry: z.infer<typeof AgentScheduleEntry>): Promise<void>;
+    delete(agentName: string): Promise<void>;
+}
+
+export class FSAgentScheduleRepo implements IAgentScheduleRepo {
+    private readonly configPath = path.join(WorkDir, "config", "agent-schedule.json");
+
+    async ensureConfig(): Promise<void> {
+        try {
+            await fs.access(this.configPath);
+        } catch {
+            await fs.writeFile(this.configPath, JSON.stringify({ agents: DEFAULT_AGENT_SCHEDULES }, null, 2));
+        }
+    }
+
+    async getConfig(): Promise<z.infer<typeof AgentScheduleConfig>> {
+        const config = await fs.readFile(this.configPath, "utf8");
+        return AgentScheduleConfig.parse(JSON.parse(config));
+    }
+
+    async upsert(agentName: string, entry: z.infer<typeof AgentScheduleEntry>): Promise<void> {
+        const conf = await this.getConfig();
+        conf.agents[agentName] = entry;
+        await fs.writeFile(this.configPath, JSON.stringify(conf, null, 2));
+    }
+
+    async delete(agentName: string): Promise<void> {
+        const conf = await this.getConfig();
+        delete conf.agents[agentName];
+        await fs.writeFile(this.configPath, JSON.stringify(conf, null, 2));
+    }
+}

apps/x/packages/core/src/agent-schedule/state-repo.ts

@@ -0,0 +1,63 @@
+import { WorkDir } from "../config/config.js";
+import { AgentScheduleState, AgentScheduleStateEntry } from "@x/shared/dist/agent-schedule-state.js";
+import fs from "fs/promises";
+import path from "path";
+import z from "zod";
+
+const DEFAULT_AGENT_SCHEDULE_STATE: z.infer<typeof AgentScheduleState>["agents"] = {};
+
+export interface IAgentScheduleStateRepo {
+    ensureState(): Promise<void>;
+    getState(): Promise<z.infer<typeof AgentScheduleState>>;
+    getAgentState(agentName: string): Promise<z.infer<typeof AgentScheduleStateEntry> | null>;
+    updateAgentState(agentName: string, entry: Partial<z.infer<typeof AgentScheduleStateEntry>>): Promise<void>;
+    setAgentState(agentName: string, entry: z.infer<typeof AgentScheduleStateEntry>): Promise<void>;
+    deleteAgentState(agentName: string): Promise<void>;
+}
+
+export class FSAgentScheduleStateRepo implements IAgentScheduleStateRepo {
+    private readonly statePath = path.join(WorkDir, "config", "agent-schedule-state.json");
+
+    async ensureState(): Promise<void> {
+        try {
+            await fs.access(this.statePath);
+        } catch {
+            await fs.writeFile(this.statePath, JSON.stringify({ agents: DEFAULT_AGENT_SCHEDULE_STATE }, null, 2));
+        }
+    }
+
+    async getState(): Promise<z.infer<typeof AgentScheduleState>> {
+        const state = await fs.readFile(this.statePath, "utf8");
+        return AgentScheduleState.parse(JSON.parse(state));
+    }
+
+    async getAgentState(agentName: string): Promise<z.infer<typeof AgentScheduleStateEntry> | null> {
+        const state = await this.getState();
+        return state.agents[agentName] ?? null;
+    }
+
+    async updateAgentState(agentName: string, entry: Partial<z.infer<typeof AgentScheduleStateEntry>>): Promise<void> {
+        const state = await this.getState();
+        const existing = state.agents[agentName] ?? {
+            status: "scheduled" as const,
+            lastRunAt: null,
+            nextRunAt: null,
+            lastError: null,
+            runCount: 0,
+        };
+        state.agents[agentName] = { ...existing, ...entry };
+        await fs.writeFile(this.statePath, JSON.stringify(state, null, 2));
+    }
+
+    async setAgentState(agentName: string, entry: z.infer<typeof AgentScheduleStateEntry>): Promise<void> {
+        const state = await this.getState();
+        state.agents[agentName] = entry;
+        await fs.writeFile(this.statePath, JSON.stringify(state, null, 2));
+    }
+
+    async deleteAgentState(agentName: string): Promise<void> {
+        const state = await this.getState();
+        delete state.agents[agentName];
+        await fs.writeFile(this.statePath, JSON.stringify(state, null, 2));
+    }
+}

apps/x/packages/core/src/config/initConfigs.ts

@@ -1,6 +1,8 @@
 import container from "../di/container.js";
 import type { IModelConfigRepo } from "../models/repo.js";
 import type { IMcpConfigRepo } from "../mcp/repo.js";
+import type { IAgentScheduleRepo } from "../agent-schedule/repo.js";
+import type { IAgentScheduleStateRepo } from "../agent-schedule/state-repo.js";
 import { ensureSecurityConfig } from "./security.js";
 
 /**
@@ -11,10 +13,14 @@ export async function initConfigs(): Promise<void> {
     // Resolve repos and explicitly call their ensureConfig methods
     const modelConfigRepo = container.resolve<IModelConfigRepo>("modelConfigRepo");
     const mcpConfigRepo = container.resolve<IMcpConfigRepo>("mcpConfigRepo");
+    const agentScheduleRepo = container.resolve<IAgentScheduleRepo>("agentScheduleRepo");
+    const agentScheduleStateRepo = container.resolve<IAgentScheduleStateRepo>("agentScheduleStateRepo");
 
     await Promise.all([
         modelConfigRepo.ensureConfig(),
         mcpConfigRepo.ensureConfig(),
+        agentScheduleRepo.ensureConfig(),
+        agentScheduleStateRepo.ensureState(),
         ensureSecurityConfig(),
     ]);
 }

apps/x/packages/core/src/di/container.ts

@@ -12,6 +12,8 @@ import { FSOAuthRepo, IOAuthRepo } from "../auth/repo.js";
 import { FSClientRegistrationRepo, IClientRegistrationRepo } from "../auth/client-repo.js";
 import { FSGranolaConfigRepo, IGranolaConfigRepo } from "../knowledge/granola/repo.js";
 import { IAbortRegistry, InMemoryAbortRegistry } from "../runs/abort-registry.js";
+import { FSAgentScheduleRepo, IAgentScheduleRepo } from "../agent-schedule/repo.js";
+import { FSAgentScheduleStateRepo, IAgentScheduleStateRepo } from "../agent-schedule/state-repo.js";
 
 const container = createContainer({
     injectionMode: InjectionMode.PROXY,
@@ -33,6 +35,8 @@ container.register({
     oauthRepo: asClass<IOAuthRepo>(FSOAuthRepo).singleton(),
     clientRegistrationRepo: asClass<IClientRegistrationRepo>(FSClientRegistrationRepo).singleton(),
     granolaConfigRepo: asClass<IGranolaConfigRepo>(FSGranolaConfigRepo).singleton(),
+    agentScheduleRepo: asClass<IAgentScheduleRepo>(FSAgentScheduleRepo).singleton(),
+    agentScheduleStateRepo: asClass<IAgentScheduleStateRepo>(FSAgentScheduleStateRepo).singleton(),
 });
 
 export default container;

apps/x/packages/shared/src/agent-schedule-state.ts

@@ -0,0 +1,16 @@
+import z from "zod";
+
+// "triggered" is terminal state for once-schedules (will not run again)
+export const AgentScheduleStatus = z.enum(["scheduled", "running", "finished", "failed", "triggered"]);
+
+export const AgentScheduleStateEntry = z.object({
+    status: AgentScheduleStatus,
+    lastRunAt: z.string().datetime().nullable(),
+    nextRunAt: z.string().datetime().nullable(),
+    lastError: z.string().nullable(),
+    runCount: z.number().default(0),
+});
+
+export const AgentScheduleState = z.object({
+    agents: z.record(z.string(), AgentScheduleStateEntry),
+});

apps/x/packages/shared/src/agent-schedule.ts

@@ -0,0 +1,42 @@
+import z from "zod";
+
+// Cron schedule - runs at exact times defined by cron expression.
+// Examples:
+//   - Every 5 minutes: "*/5 * * * *"
+//   - Everyday at 8am: "0 8 * * *"
+//   - Every Monday at 9am: "0 9 * * 1"
+export const CronSchedule = z.object({
+    type: z.literal("cron"),
+    expression: z.string(),
+});
+
+// Window schedule - runs once during a time window.
+// The agent will run once at a random time within the specified window.
+// Examples:
+//   - Daily between 8am and 10am: cron="0 0 * * *", startTime="08:00", endTime="10:00"
+//   - Weekly on Monday between 9am-12pm: cron="0 0 * * 1", startTime="09:00", endTime="12:00"
+export const WindowSchedule = z.object({
+    type: z.literal("window"),
+    cron: z.string(), // Base frequency cron expression
+    startTime: z.string(), // "HH:MM" format
+    endTime: z.string(), // "HH:MM" format
+});
+
+// Once schedule - runs exactly once at a specific time, then never again.
+// Examples:
+//   - Run once at specific datetime: runAt="2024-02-05T10:30:00Z"
+export const OnceSchedule = z.object({
+    type: z.literal("once"),
+    runAt: z.string().datetime(), // ISO 8601 datetime
+});
+
+export const ScheduleDefinition = z.union([CronSchedule, WindowSchedule, OnceSchedule]);
+
+export const AgentScheduleEntry = z.object({
+    schedule: ScheduleDefinition,
+    enabled: z.boolean().optional().default(true),
+});
+
+export const AgentScheduleConfig = z.object({
+    agents: z.record(z.string(), AgentScheduleEntry),
+});

apps/x/packages/shared/src/index.ts

@@ -4,4 +4,6 @@ export * as ipc from './ipc.js';
 export * as models from './models.js';
 export * as workspace from './workspace.js';
 export * as mcp from './mcp.js';
+export * as agentSchedule from './agent-schedule.js';
+export * as agentScheduleState from './agent-schedule-state.js';
 export { PrefixLogger };