wolli 0.0.3 → 0.0.4

package/built-in/plugins/scheduler/cron.ts

@@ -0,0 +1,131 @@
+/**
+ * Cron tool — lets the agent schedule its own prompts (add / list / update / remove / run)
+ * by driving the scheduler integration's CRUD actions. `add` snapshots the calling
+ * session's tags onto the job (`originTags`), so when the job fires, `scheduler-due.ts`
+ * wakes the session that surface belongs to and its reply returns there with no
+ * scheduler-side special-casing.
+ */
+
+import { defineTool } from "wolli";
+import { Type } from "typebox";
+import scheduler from "./index.ts";
+
+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 tool 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 defineTool({
+	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) {
+		const sched = ctx.integration(scheduler);
+		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.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.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.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.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.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 });
+		}
+	},
+});

package/built-in/plugins/scheduler/index.ts

@@ -4,13 +4,12 @@
  * 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.
+ * agent; the `cron` tool (`cron.ts`) drives the CRUD actions and the `scheduler-due.ts`
+ * workflow, on `due`, wakes the session the job was scheduled from.
  *
  * 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.
+ * below. The scheduler has no secret — onboarding just writes an empty `scheduler`
+ * account record so `run()` starts.
  *
  * ## Guarantees
  *  - At-most-once: a tick advances a job's `nextRunAt` (or disables a one-shot) and
@@ -21,7 +20,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import type { IntegrationOnboardContext, IntegrationsAPI, KeyValueStore } from "@opsyhq/wolli";
+import { defineIntegration, type IntegrationOnboardContext, type KeyValueStore } from "wolli";
 import { Cron } from "croner";
 import { type Static, Type } from "typebox";
 
@@ -80,165 +79,162 @@ async function onboard(ctx: IntegrationOnboardContext): Promise<Record<string, u
 	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()),
+export default defineIntegration({
+	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()),
 		}),
-		events: {
-			due: Type.Object({
-				id: 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(),
-				originTags: Type.Optional(Type.Record(Type.String(), Type.String())),
 				name: Type.Optional(Type.String()),
+				schedule: Schedule,
+				originTags: Type.Optional(Type.Record(Type.String(), 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 };
-				},
+			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)) };
-				},
+		},
+		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}'`);
+		},
+		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;
-					}
+				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 };
-				},
+				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 };
-				},
+		},
+		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 };
-				},
+		},
+		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;
+	},
+	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);
+		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;
 				}
-				if (due.length === 0) return;
+				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,
-					});
-				}
-			};
+			// 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);
+		// 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;
-		},
-	});
-}
+		const dispose = () => clearInterval(timer);
+		ctx.signal.addEventListener("abort", dispose);
+		return dispose;
+	},
+});

package/built-in/plugins/scheduler/package.json

@@ -5,12 +5,13 @@
 	"type": "module",
 	"wolli": {
 		"integrations": ["./index.ts"],
-		"extensions": ["./scheduler-chat.ts"]
+		"workflows": ["./scheduler-due.ts"],
+		"tools": ["./cron.ts"]
 	},
 	"dependencies": {
 		"croner": "10.0.1"
 	},
 	"peerDependencies": {
-		"@opsyhq/wolli": "*"
+		"wolli": "*"
 	}
 }

package/built-in/plugins/scheduler/scheduler-due.ts

@@ -0,0 +1,22 @@
+/**
+ * Scheduler due routing — on a `due` event, runs the job's prompt as a turn in the session
+ * it was scheduled from (the newest match for the job's origin tags). A telegram-tagged
+ * origin means telegram's own `agent_end` ships the reply back to that chat; no
+ * scheduler-side channel handling. If no session matches (the origin was pruned), a fresh
+ * one is created carrying the SAME origin tags so it stays bound to that surface — never
+ * an untagged session, which would deliver nowhere.
+ */
+
+import scheduler from "./index.ts";
+
+export const due = scheduler.on("due", async (job, ctx) => {
+	const originTags = job.originTags ?? {};
+	const [match] = await ctx.agent.findSessions(originTags);
+	const session = match
+		? await ctx.agent.openSession(match.id)
+		: await ctx.agent.createSession({
+				setup: (s) => s.appendTags(originTags),
+			});
+	// followUp queues cleanly if a turn is in flight.
+	await session.sendUserMessage(job.prompt, { deliverAs: "followUp" });
+});

package/built-in/plugins/telegram/README.md

@@ -33,13 +33,13 @@ response.
 
 ## Commands
 
-These commands are registered as the bot's command menu via BotFather on startup and
-are handled by the integration directly, not forwarded to the model:
+These commands are registered as the bot's command menu at producer startup and are
+handled locally by the inbound routing workflow, not forwarded to the model:
 
 | Command | Action |
 |---------|--------|
 | `/new` | Start a fresh session for this chat. The new session becomes the active one; the previous session stays addressable but new messages route to the new one. |
-| `/status` | Show the current session name and the model used in the last reply. |
+| `/status` | Show the current session name and its current model. |
 | `/help` | List the available commands. |
 
 Any other `/command` returns `Unknown command: /<name>. Try /help.`