wolli 0.0.1 → 0.0.2

package/plugins/scheduler/index.ts

@@ -0,0 +1,244 @@
+/**
+ * Scheduler integration — the timer half (self-contained package).
+ *
+ * This integration owns the jobs and the wake loop: it persists jobs in `ctx.store`
+ * (one file at `~/.wolli/agents/<name>/store/scheduler.json`), ticks a coarse timer,
+ * and emits a `due` event when a job's time arrives. It does not touch sessions or the
+ * agent; the paired extension (`scheduler-chat.ts`) registers the agent-facing `cron`
+ * tool and, on `due`, wakes a session. See `INTEGRATION.md` for the producer-vs-mapping
+ * split.
+ *
+ * Jobs are scheduled by the agent through the `cron` tool, which calls the CRUD actions
+ * below. The scheduler has no secret — onboarding just writes an empty `scheduler.default`
+ * account so `run()` starts.
+ *
+ * ## Guarantees
+ *  - At-most-once: a tick advances a job's `nextRunAt` (or disables a one-shot) and
+ *    persists that BEFORE emitting `due`, so a crash/reload right after an emit never
+ *    double-fires.
+ *  - Missed runs while down: the catch-up tick on start fires each overdue job once
+ *    (recompute-from-now), not one replay per missed interval.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { IntegrationOnboardContext, IntegrationsAPI, KeyValueStore } from "@opsyhq/wolli";
+import { Cron } from "croner";
+import { type Static, Type } from "typebox";
+
+/** Default wake interval — coarse by design (a fixed tick is trivially idempotent across reloads). */
+const DEFAULT_TICK_MS = 60_000;
+
+const Schedule = Type.Union([
+	/** One-shot at an absolute epoch-ms instant. */
+	Type.Object({ kind: Type.Literal("at"), at: Type.Number() }),
+	/** Fixed interval; the first run is one interval after creation. */
+	Type.Object({ kind: Type.Literal("every"), everyMs: Type.Number() }),
+	/** Cron expression; `tz` omitted = host local time. */
+	Type.Object({ kind: Type.Literal("cron"), expr: Type.String(), tz: Type.Optional(Type.String()) }),
+]);
+type Schedule = Static<typeof Schedule>;
+
+interface Job {
+	id: string;
+	name?: string;
+	prompt: string;
+	schedule: Schedule;
+	enabled: boolean;
+	/** Tags of the session that scheduled the job; the fired result is delivered to the newest session matching these. */
+	originTags?: Record<string, string>;
+	/** Epoch ms; advanced before firing. */
+	nextRunAt: number;
+	lastRunAt?: number;
+}
+
+interface SchedulerAccount {
+	tickMs?: number;
+}
+
+/** Jobs live under the single store key `"jobs"`, keyed by id. */
+function loadJobs(store: KeyValueStore): Record<string, Job> {
+	return (store.get("jobs") as Record<string, Job> | undefined) ?? {};
+}
+function saveJobs(store: KeyValueStore, jobs: Record<string, Job>): void {
+	store.set("jobs", jobs);
+}
+
+/** Next run for a schedule relative to `fromMs`; null when there is no future run. */
+function computeNextRunAt(schedule: Schedule, fromMs: number): number | null {
+	switch (schedule.kind) {
+		case "at":
+			return schedule.at;
+		case "every":
+			return fromMs + schedule.everyMs;
+		case "cron":
+			return new Cron(schedule.expr, { timezone: schedule.tz }).nextRun(new Date(fromMs))?.getTime() ?? null;
+	}
+}
+
+async function onboard(ctx: IntegrationOnboardContext): Promise<Record<string, unknown>> {
+	ctx.ui.notify("Scheduler enabled.", "info");
+	return {};
+}
+
+export default function (wolli: IntegrationsAPI) {
+	wolli.registerIntegration({
+		name: "scheduler",
+		account: Type.Object({
+			/** Wake interval in ms; defaults to 60s. */
+			tickMs: Type.Optional(Type.Number()),
+		}),
+		events: {
+			due: Type.Object({
+				id: Type.String(),
+				prompt: Type.String(),
+				originTags: Type.Optional(Type.Record(Type.String(), Type.String())),
+				name: Type.Optional(Type.String()),
+			}),
+		},
+		onboard,
+		actions: {
+			addJob: {
+				description: "Schedule a new job from a prompt and a schedule (at / every / cron).",
+				parameters: Type.Object({
+					prompt: Type.String(),
+					name: Type.Optional(Type.String()),
+					schedule: Schedule,
+					originTags: Type.Optional(Type.Record(Type.String(), Type.String())),
+				}),
+				execute: async (params, ctx) => {
+					const p = params as {
+						prompt: string;
+						name?: string;
+						schedule: Schedule;
+						originTags?: Record<string, string>;
+					};
+					const now = Date.now();
+					const seeded = computeNextRunAt(p.schedule, now);
+					const job: Job = {
+						id: randomUUID(),
+						name: p.name,
+						prompt: p.prompt,
+						schedule: p.schedule,
+						enabled: seeded !== null,
+						originTags: p.originTags,
+						nextRunAt: seeded ?? 0,
+					};
+					const jobs = loadJobs(ctx.store);
+					jobs[job.id] = job;
+					saveJobs(ctx.store, jobs);
+					return { id: job.id, nextRunAt: job.nextRunAt };
+				},
+			},
+			listJobs: {
+				description: "List all scheduled jobs.",
+				parameters: Type.Object({}),
+				execute: async (_params, ctx) => {
+					return { jobs: Object.values(loadJobs(ctx.store)) };
+				},
+			},
+			updateJob: {
+				description: "Update a job by id; recomputes the next run when the schedule changes.",
+				parameters: Type.Object({
+					id: Type.String(),
+					prompt: Type.Optional(Type.String()),
+					name: Type.Optional(Type.String()),
+					schedule: Type.Optional(Schedule),
+					enabled: Type.Optional(Type.Boolean()),
+				}),
+				execute: async (params, ctx) => {
+					const p = params as {
+						id: string;
+						prompt?: string;
+						name?: string;
+						schedule?: Schedule;
+						enabled?: boolean;
+					};
+					const jobs = loadJobs(ctx.store);
+					const job = jobs[p.id];
+					if (!job) throw new Error(`unknown job '${p.id}'`);
+
+					if (p.prompt !== undefined) job.prompt = p.prompt;
+					if (p.name !== undefined) job.name = p.name;
+					if (p.enabled !== undefined) job.enabled = p.enabled;
+					if (p.schedule !== undefined) {
+						job.schedule = p.schedule;
+						const next = computeNextRunAt(p.schedule, Date.now());
+						job.nextRunAt = next ?? 0;
+						if (next === null) job.enabled = false;
+					}
+
+					saveJobs(ctx.store, jobs);
+					return { job };
+				},
+			},
+			removeJob: {
+				description: "Delete a job by id.",
+				parameters: Type.Object({ id: Type.String() }),
+				execute: async (params, ctx) => {
+					const { id } = params as { id: string };
+					const jobs = loadJobs(ctx.store);
+					const removed = id in jobs;
+					delete jobs[id];
+					saveJobs(ctx.store, jobs);
+					return { removed };
+				},
+			},
+			runJob: {
+				description: "Run a job on the next tick (sets it due immediately).",
+				parameters: Type.Object({ id: Type.String() }),
+				execute: async (params, ctx) => {
+					const { id } = params as { id: string };
+					const jobs = loadJobs(ctx.store);
+					const job = jobs[id];
+					if (!job) throw new Error(`unknown job '${id}'`);
+					job.enabled = true;
+					job.nextRunAt = 0;
+					saveJobs(ctx.store, jobs);
+					return { id, nextRunAt: job.nextRunAt };
+				},
+			},
+		},
+		run(ctx) {
+			const account = ctx.account as SchedulerAccount;
+			const tickMs = account.tickMs ?? DEFAULT_TICK_MS;
+
+			const tick = (): void => {
+				const now = Date.now();
+				const jobs = loadJobs(ctx.store);
+				const due: Job[] = [];
+				for (const job of Object.values(jobs)) {
+					if (!job.enabled || job.nextRunAt > now) continue;
+					job.lastRunAt = now;
+					if (job.schedule.kind === "at") {
+						job.enabled = false; // one-shot
+					} else {
+						const next = computeNextRunAt(job.schedule, now);
+						if (next === null) job.enabled = false;
+						else job.nextRunAt = next;
+					}
+					due.push(job);
+				}
+				if (due.length === 0) return;
+
+				// Persist the advanced state before emitting so a crash right after an emit never re-fires.
+				saveJobs(ctx.store, jobs);
+				for (const job of due) {
+					ctx.emit("due", {
+						id: job.id,
+						prompt: job.prompt,
+						originTags: job.originTags,
+						name: job.name,
+					});
+				}
+			};
+
+			// One catch-up tick on start: each overdue job fires once (recompute-from-now), not N replays.
+			tick();
+			const timer = setInterval(tick, tickMs);
+
+			const dispose = () => clearInterval(timer);
+			ctx.signal.addEventListener("abort", dispose);
+			return dispose;
+		},
+	});
+}

package/plugins/scheduler/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "wolli-integration-scheduler",
+	"private": true,
+	"version": "1.0.0",
+	"type": "module",
+	"wolli": {
+		"integrations": ["./index.ts"],
+		"extensions": ["./scheduler-chat.ts"]
+	},
+	"dependencies": {
+		"croner": "10.0.1"
+	},
+	"peerDependencies": {
+		"@opsyhq/wolli": "*"
+	}
+}

package/plugins/scheduler/scheduler-chat.ts

@@ -0,0 +1,164 @@
+/**
+ * Scheduler chat extension — the mapping half (paired with `index.ts`).
+ *
+ * The integration (`index.ts`) is the producer (jobs, wake timer, `due` events); this
+ * extension maps that onto the agent:
+ *
+ *   - tool:   registers the `cron` tool so the agent schedules its own jobs
+ *             (add / list / update / remove / run) via the integration's CRUD actions.
+ *   - inbound: `scheduler.on("due")` runs the job's prompt in the session it was scheduled from.
+ *
+ * Delivery via tags: `add` snapshots the scheduling session's tags onto the job (`originTags`).
+ * When the job fires, the prompt runs as a turn in the newest session matching those tags, so
+ * whatever extension owns that surface delivers the answer onward with no scheduler-side
+ * special-casing — a telegram-tagged origin means telegram's own `agent_end` ships the reply
+ * back to that chat. An untagged origin falls back to the newest session.
+ *
+ * This file is declared under the package's `wolli.extensions` and is resolved in place by the
+ * package manager when the integration is onboarded.
+ */
+
+import type { ExtensionAPI } from "@opsyhq/wolli";
+import { Type } from "typebox";
+
+const CronParams = Type.Object({
+	action: Type.Union([
+		Type.Literal("add"),
+		Type.Literal("list"),
+		Type.Literal("update"),
+		Type.Literal("remove"),
+		Type.Literal("run"),
+	]),
+	prompt: Type.Optional(Type.String({ description: "What to run (the woken session's first message)." })),
+	name: Type.Optional(Type.String({ description: "Human label for the job." })),
+	at: Type.Optional(Type.Number({ description: "One-shot run time, epoch ms." })),
+	everyMs: Type.Optional(Type.Number({ description: "Fixed interval in ms." })),
+	cron: Type.Optional(Type.String({ description: "Cron expression (5/6-field)." })),
+	tz: Type.Optional(Type.String({ description: "Timezone for the cron expression (host local if omitted)." })),
+	id: Type.Optional(Type.String({ description: "Job id, for update / remove / run." })),
+	enabled: Type.Optional(Type.Boolean({ description: "Enable or disable the job (update)." })),
+});
+
+/** The fields of a job this extension reads back from `listJobs` (the integration owns the full shape). */
+interface Job {
+	id: string;
+	name?: string;
+	schedule: { kind: "at"; at: number } | { kind: "every"; everyMs: number } | { kind: "cron"; expr: string; tz?: string };
+	enabled: boolean;
+	nextRunAt: number;
+}
+
+/** Map the tool's flat `at`/`everyMs`/`cron` fields onto the integration's `Schedule` union. */
+function buildSchedule(p: { at?: number; everyMs?: number; cron?: string; tz?: string }): Job["schedule"] | undefined {
+	if (p.at !== undefined) return { kind: "at", at: p.at };
+	if (p.everyMs !== undefined) return { kind: "every", everyMs: p.everyMs };
+	if (p.cron !== undefined) return { kind: "cron", expr: p.cron, tz: p.tz };
+	return undefined;
+}
+
+function describeSchedule(schedule: Job["schedule"]): string {
+	switch (schedule.kind) {
+		case "at":
+			return `at ${new Date(schedule.at).toISOString()}`;
+		case "every":
+			return `every ${schedule.everyMs}ms`;
+		case "cron":
+			return `cron "${schedule.expr}"${schedule.tz ? ` (${schedule.tz})` : ""}`;
+	}
+}
+
+function text(message: string, details: unknown) {
+	return { content: [{ type: "text" as const, text: message }], details };
+}
+
+export default function (wolli: ExtensionAPI) {
+	const sched = wolli.getIntegration("scheduler", "default");
+
+	wolli.registerTool({
+		name: "cron",
+		label: "Cron",
+		description:
+			"Schedule prompts to run later. Actions: add (prompt + at/everyMs/cron), list, update (id), remove (id), run (id).",
+		parameters: CronParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				switch (params.action) {
+					case "add": {
+						if (!params.prompt) return text("Error: prompt is required to add a job.", { error: "prompt required" });
+						const schedule = buildSchedule(params);
+						if (!schedule) {
+							return text("Error: provide one of at, everyMs, or cron.", { error: "schedule required" });
+						}
+						// Snapshot the scheduling session's tags so the fired result returns to this surface.
+						const result = (await sched.call("addJob", {
+							prompt: params.prompt,
+							name: params.name,
+							schedule,
+							originTags: ctx.session.getTags(),
+						})) as { id: string; nextRunAt: number };
+						return text(
+							`Scheduled job ${result.id} — ${describeSchedule(schedule)} — next ${new Date(result.nextRunAt).toISOString()}.`,
+							result,
+						);
+					}
+					case "list": {
+						const result = (await sched.call("listJobs")) as { jobs: Job[] };
+						const body = result.jobs.length
+							? result.jobs
+									.map((j) => {
+										const label = j.name ? `${j.name} ` : "";
+										const state = j.enabled ? `next ${new Date(j.nextRunAt).toISOString()}` : "disabled";
+										return `${j.id} ${label}— ${describeSchedule(j.schedule)} — ${state}`;
+									})
+									.join("\n")
+							: "No scheduled jobs.";
+						return text(body, result);
+					}
+					case "update": {
+						if (!params.id) return text("Error: id is required to update a job.", { error: "id required" });
+						const result = await sched.call("updateJob", {
+							id: params.id,
+							prompt: params.prompt,
+							name: params.name,
+							schedule: buildSchedule(params),
+							enabled: params.enabled,
+						});
+						return text(`Updated job ${params.id}.`, result);
+					}
+					case "remove": {
+						if (!params.id) return text("Error: id is required to remove a job.", { error: "id required" });
+						const result = (await sched.call("removeJob", { id: params.id })) as { removed: boolean };
+						return text(result.removed ? `Removed job ${params.id}.` : `No job ${params.id}.`, result);
+					}
+					case "run": {
+						if (!params.id) return text("Error: id is required to run a job.", { error: "id required" });
+						const result = await sched.call("runJob", { id: params.id });
+						return text(`Job ${params.id} will run on the next tick.`, result);
+					}
+				}
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return text(`Error: ${message}`, { error: message });
+			}
+		},
+	});
+
+	sched.on("due", async (data) => {
+		const job = data as { id: string; prompt: string; originTags?: Record<string, string> };
+
+		// Run the prompt as a turn in the session the job was scheduled from (newest match for its
+		// origin tags). A telegram-tagged origin → telegram's own agent_end ships the reply to that
+		// chat; no scheduler-side channel handling. followUp queues cleanly if a turn is in flight.
+		// If no session matches (e.g. the origin was pruned), create one carrying the SAME origin tags
+		// so it stays bound to that surface — never an untagged session, which would deliver nowhere.
+		const [match] = await wolli.findSessions(job.originTags ?? {});
+		const session = match
+			? await wolli.openSession(match.id)
+			: await wolli.createSession({
+					setup: async (sessionManager) => {
+						await sessionManager.appendTags(job.originTags ?? {});
+					},
+				});
+		await session.sendUserMessage(job.prompt, { deliverAs: "followUp" });
+	});
+}