wolli 0.0.1 → 0.0.3

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

@@ -0,0 +1,192 @@
+/**
+ * Discord transport — holds the bot token, emits a `message` event per inbound message;
+ * the paired `discord-chat.ts` extension maps those onto sessions. Transport is the
+ * gateway WebSocket (discord.js `Client`); snowflake ids stay `string`. MESSAGE CONTENT
+ * is a privileged intent — enable it in the Developer Portal or `m.content` is empty.
+ * See README.md for setup.
+ */
+
+import type { IntegrationOnboardContext, IntegrationsAPI } from "@opsyhq/wolli";
+import { Client, Events, GatewayIntentBits, Partials, REST, Routes } from "discord.js";
+import { Type } from "typebox";
+
+/** Discord caps a single message at 2000 UTF-16 code units. */
+const DISCORD_MAX_LENGTH = 2000;
+
+const ONBOARD_GUIDE = [
+	"## Connect Discord",
+	"",
+	"1. Open the [Discord Developer Portal](https://discord.com/developers/applications)",
+	"   and create a **New Application**.",
+	"2. Go to **Bot**, then enable the **MESSAGE CONTENT INTENT** toggle (privileged —",
+	"   without it the bot receives empty message text).",
+	"3. On the **Bot** page, **Reset Token** and copy the token.",
+	"4. Go to **OAuth2 → URL Generator**, select the `bot` scope, copy the generated URL,",
+	"   open it, and invite the bot to your server.",
+	"5. Paste the token on the next screen.",
+	"",
+	"Wolli verifies the token and stores it for this agent.",
+].join("\n");
+
+interface DiscordAccount {
+	botToken: string;
+	allowedChannelIds?: string[];
+}
+
+/** One cached `REST` client per token for the request/response actions. */
+const rests = new Map<string, REST>();
+function getRest(token: string): REST {
+	let rest = rests.get(token);
+	if (!rest) {
+		rest = new REST({ version: "10" }).setToken(token);
+		rests.set(token, rest);
+	}
+	return rest;
+}
+
+/** Split into ≤2000-code-unit chunks without cutting a surrogate pair. */
+function chunkText(text: string, max = DISCORD_MAX_LENGTH): string[] {
+	if (text.length <= max) return [text];
+	const chunks: string[] = [];
+	let i = 0;
+	while (i < text.length) {
+		let end = Math.min(i + max, text.length);
+		if (end < text.length) {
+			const code = text.charCodeAt(end - 1);
+			if (code >= 0xd800 && code <= 0xdbff) end -= 1;
+		}
+		chunks.push(text.slice(i, end));
+		i = end;
+	}
+	return chunks;
+}
+
+/** Guided setup: collect the bot token, verify it via `GET /users/@me`, return it to store. */
+async function onboard(ctx: IntegrationOnboardContext): Promise<{ botToken: string } | undefined> {
+	ctx.ui.notify(ONBOARD_GUIDE, "info");
+
+	const entered = await ctx.ui.input("Paste the bot token from the Discord Developer Portal");
+	if (entered === undefined) return undefined; // cancelled
+	const token = entered.trim();
+	if (!token) {
+		ctx.ui.notify("No token entered.", "error");
+		return undefined;
+	}
+
+	try {
+		const me = (await new REST({ version: "10" }).setToken(token).get(Routes.user())) as { username: string };
+		ctx.ui.notify(`Verified bot ${me.username}.`, "info");
+	} catch (err) {
+		ctx.ui.notify(`Could not verify the token: ${err instanceof Error ? err.message : String(err)}`, "error");
+		return undefined;
+	}
+
+	return { botToken: token };
+}
+
+export default function (wolli: IntegrationsAPI) {
+	wolli.registerIntegration({
+		name: "discord",
+		account: Type.Object({
+			botToken: Type.String(),
+			/** Empty/absent = allow all (logged as a warning). */
+			allowedChannelIds: Type.Optional(Type.Array(Type.String())),
+		}),
+		events: {
+			message: Type.Object({
+				channelId: Type.String(),
+				messageId: Type.String(),
+				text: Type.String(),
+				author: Type.Object({
+					id: Type.String(),
+					name: Type.Optional(Type.String()),
+				}),
+			}),
+		},
+		onboard,
+		actions: {
+			sendMessage: {
+				description: "Send a text message to a channel (chunked at 2000; Discord renders markdown natively).",
+				parameters: Type.Object({
+					channelId: Type.String(),
+					text: Type.String(),
+				}),
+				execute: async (params, ctx) => {
+					const { channelId, text } = params as { channelId: string; text: string };
+					const account = ctx.account as DiscordAccount;
+					const rest = getRest(account.botToken);
+
+					const messageIds: string[] = [];
+					for (const content of chunkText(text)) {
+						const sent = (await rest.post(Routes.channelMessages(channelId), { body: { content } })) as {
+							id: string;
+						};
+						messageIds.push(sent.id);
+					}
+					return { messageIds };
+				},
+			},
+			sendTyping: {
+				description: "Show the 'typing…' indicator in a channel (lasts ~10s).",
+				parameters: Type.Object({
+					channelId: Type.String(),
+				}),
+				execute: async (params, ctx) => {
+					const { channelId } = params as { channelId: string };
+					const account = ctx.account as DiscordAccount;
+					const rest = getRest(account.botToken);
+					await rest.post(Routes.channelTyping(channelId));
+					return { ok: true };
+				},
+			},
+		},
+		run(ctx) {
+			const account = ctx.account as DiscordAccount;
+			const { botToken, allowedChannelIds } = account;
+			const allowAll = !allowedChannelIds || allowedChannelIds.length === 0;
+			if (allowAll) {
+				console.warn("[discord] no allowedChannelIds configured — accepting messages from ANY channel.");
+			}
+
+			const client = new Client({
+				intents: [
+					GatewayIntentBits.Guilds,
+					GatewayIntentBits.GuildMessages,
+					GatewayIntentBits.MessageContent,
+					GatewayIntentBits.DirectMessages,
+				],
+				partials: [Partials.Channel], // required to receive DMs
+			});
+
+			client.on(Events.MessageCreate, (m) => {
+				if (m.author.id === client.user?.id) return; // skip self
+				if (m.author.bot) return; // skip other bots (loop prevention)
+				if (!allowAll && !allowedChannelIds?.includes(m.channelId)) return;
+				const text = m.content;
+				if (!text) return; // empty without the MESSAGE CONTENT intent, or media-only
+
+				ctx.emit("message", {
+					channelId: m.channelId,
+					messageId: m.id,
+					text,
+					author: { id: m.author.id, name: m.author.username },
+				});
+			});
+
+			client.on(Events.Error, (err) => {
+				console.error("[discord] client error:", err.message);
+			});
+
+			// Fire-and-forget: login never settles into a state we await.
+			if (!ctx.signal.aborted) {
+				void client.login(botToken).catch((err) => {
+					console.error("[discord] failed to log in:", err instanceof Error ? err.message : err);
+				});
+			}
+
+			const dispose = () => void client.destroy();
+			ctx.signal.addEventListener("abort", dispose);
+			return dispose;
+		},
+	});
+}

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

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

package/built-in/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/built-in/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/built-in/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" });
+	});
+}