wolli 0.0.2 → 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

@@ -0,0 +1,240 @@
+/**
+ * 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 `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`
+ * account record 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 { defineIntegration, type IntegrationOnboardContext, type KeyValueStore } from "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 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()),
+		}),
+	},
+	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 → 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

@@ -0,0 +1,153 @@
+# Telegram
+
+Connect a wolli agent to Telegram. The bot runs over Telegram's long-polling API,
+gives each chat its own wolli session, and replies in place. Setup is one message to
+[@BotFather](https://t.me/BotFather) plus a single token prompt — no public URL or
+TLS is required.
+
+## How the bot behaves
+
+Before setup, here's the part most people want to know: this bot answers **every
+text message it receives**. There is no `@mention` gate.
+
+| Context | Behavior |
+|---------|----------|
+| **Private chats** | Responds to every text message. |
+| **Group chats** | Responds to every text message it can see in any chat. No `@mention` required. Scope where it listens with `allowedChatIds`. |
+| **Its own messages** | Ignored. The bot skips messages it sent itself, so it can't loop. |
+| **Non-text messages** | Skipped. Photos, stickers, voice, and other media are not handled — only text messages reach the agent. |
+| **Slash commands** | `/new`, `/status`, `/help` are handled locally and never sent to the model (see [Commands](#commands)). |
+
+While a turn runs, the bot shows Telegram's **typing…** indicator and re-sends it
+every ~4 seconds (Telegram clears the state on its own) until the reply lands.
+
+Replies are chunked at **4096 characters** (Telegram's per-message limit) and each
+chunk is sent with the configured **parse mode** (`MarkdownV2` by default). Telegram,
+unlike Discord, needs a parse mode to render formatting — and if it rejects a chunk's
+formatting, that chunk is **re-sent as plain text**, so a stray markdown character
+never silently drops the reply.
+
+If a new message arrives while the agent is mid-reply, it is **queued as a follow-up**
+and answered after the current turn finishes — it does not interrupt the in-flight
+response.
+
+## Commands
+
+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 its current model. |
+| `/help` | List the available commands. |
+
+Any other `/command` returns `Unknown command: /<name>. Try /help.`
+
+## Session model
+
+Each chat gets its **own wolli session**, bound by a `telegram:chat` tag:
+
+- **Inbound** — an incoming message is routed to the session tagged for its chat. If
+  none exists yet, one is created and tagged on the spot. Histories never bleed across
+  chats, and two chats can run in parallel.
+- **Outbound** — the reply rides the producing session's tag, so the answer always
+  returns to the chat that started the turn — not to whoever messaged most recently.
+
+`/new` creates a fresh session tagged for the chat; because it becomes the newest
+match for that tag, subsequent messages route to it.
+
+## Setup
+
+### 1. Create a bot with BotFather
+
+Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Pick a name
+and a username; BotFather replies with a **bot token** like `123456:ABC-DEF...`. Copy
+it — you'll paste it in the next step. Keep it secret.
+
+### 2. Install and onboard in wolli
+
+```bash
+wolli <agent> plugins install ./built-in/plugins/telegram
+```
+
+In an interactive terminal this runs onboarding immediately: it prints the BotFather
+walkthrough, then prompts you to **paste the bot token**. Paste the token from step 1.
+Wolli verifies it with a live `getMe()` call and stores it. That single token is the
+only value you enter.
+
+If you installed non-interactively, onboard later with:
+
+```bash
+wolli <agent> plugins configure telegram
+```
+
+### 3. Restart the agent
+
+```bash
+wolli restart <agent>
+```
+
+This starts the long-poll producer that connects to Telegram. After onboarding a
+fresh integration its producer starts only on the next daemon start, so restart the
+agent once for the bot to come online and begin responding.
+
+## Configuration reference
+
+Configuration lives per agent in `~/.wolli/agents/<name>/integrations.json` under
+`telegram.default`:
+
+```json
+{
+  "telegram": {
+    "default": {
+      "botToken": "123456:ABC-DEF...",
+      "allowedChatIds": [123456789],
+      "parseMode": "MarkdownV2"
+    }
+  }
+}
+```
+
+| Field | Required | Default | Purpose |
+|-------|----------|---------|---------|
+| `botToken` | Yes | — | The BotFather token. Onboarding stores it raw; a `$ENV` / `!cmd` reference placed here by hand also resolves on read. |
+| `allowedChatIds` | No | *(any chat)* | Allowlist of chat IDs the bot will respond in. Empty or absent accepts **any** chat (logged as a warning at startup). |
+| `parseMode` | No | `MarkdownV2` | Outbound formatting: `"MarkdownV2"`, `"HTML"`, or `"plain"` (disables parse mode). |
+
+Telegram chat IDs are **numbers** — keep them unquoted in JSON, unlike Discord's
+quoted snowflakes.
+
+`allowedChatIds` and `parseMode` are not asked during onboarding — edit
+`integrations.json` to set them.
+
+## Not supported
+
+The bot is deliberately focused on text chat. It does not provide:
+
+- A durable cursor — on start it calls `deleteWebhook({ drop_pending_updates: true })`,
+  so a restart never replays a backlog but also drops messages sent while the bot was
+  offline.
+- Inbound media or images — only text messages are handled.
+- Webhook mode — the transport is long polling only.
+- Callback queries or inline keyboards.
+- Outbound rate-limit throttling.
+- Mention-gating, or per-user / per-role allowlists — chat-level `allowedChatIds` is
+  the only scope control.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| No reply right after the first install/onboard | Restart the agent (`wolli restart <agent>`) so the long-poll producer starts. |
+| Bot ignores messages sent while it was offline | Expected — `deleteWebhook({ drop_pending_updates: true })` clears the backlog on start. The bot only sees messages that arrive while it is running. |
+| Formatting looks broken, or a message seems to drop | A chunk that fails parse-mode parsing is re-sent as plain text. Set `parseMode: "plain"` to disable formatting entirely. |
+
+## Security
+
+- `allowedChatIds` is the only access gate. With it empty, **any** chat is accepted —
+  set it to lock the bot to known chats.
+- There is no per-user gate beyond that. Anyone who can post in an allowed chat can
+  drive the agent, so keep the bot in trusted chats.
+- The bot token grants full control of the bot account — never commit it or share it.
+  Wolli writes `integrations.json` with mode `0600`.