wolli 0.0.3 → 0.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 # Wolli
 
-**Create purposeful, self-extending AI agents.**
+**Create agents that grow around a purpose.**
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/wolli.svg)](https://www.npmjs.com/package/wolli)
@@ -16,10 +16,7 @@
 
 > **What is my purpose?**
 
-Wolli lets you create purposeful agents. That purpose becomes the organizing
-principle of an agent's life: it remembers across sessions, runs on a schedule,
-acts on events, and extends itself to do its job better over time, writing its
-own skills, integrations, and extensions as the work demands.
+Wolli lets you create agents that grow around a purpose. Each agent remembers across sessions, runs on schedules, reacts to events, and extends itself over time by writing the skills, integrations, and workflows it needs to do its job better.
 
 ## Install
 
@@ -29,27 +26,27 @@ wolli
 ```
 
 The first run sets up your provider and creates your first agent. A new agent
-starts in a **forming** state: it interviews you to work out its purpose and
-records what it learns, and does not act unattended until you deploy it. Agents and
-state live under `~/.wolli`. `●` deployed and `○` forming.
+opens by interviewing you to work out its purpose, then writes its own
+`SOUL.md` — its first line becomes the agent's description everywhere. Agents
+and state live under `~/.wolli`.
 
 ```
  Agents
 
- → ● inbox    Triage my email each morning, draft replies to the routine ones, flag what needs me.
-   ● scout    Watch the repos and deps we ship; when a release or CVE needs action, open an issue and ping me.
-   ● ledger   Track project spend across providers, reconcile invoices weekly, warn me before a budget tips over.
-   ○ sprout   Still working out my purpose.
+ → inbox    Triage my email each morning, draft replies to the routine ones, flag what needs me.
+   scout    Watch the repos and deps we ship; when a release or CVE needs action, open an issue and ping me.
+   ledger   Track project spend across providers, reconcile invoices weekly, warn me before a budget tips over.
 
  ↑/↓ browse · enter chat · tab details · type to search commands · ctrl+c quit
 ```
 
 ## How it works
 
-- **Purpose-built.** You state the agent's purpose at birth. It decides what the
-  agent stores, when it speaks up, and what it does unattended.
+- **Purpose-built.** The agent works its purpose out with you in its first
+  conversation and records it as the first line of its `SOUL.md`. It decides what
+  the agent stores, when it speaks up, and what it does unattended.
 - **Self-extending.** The agent builds itself out for its purpose. It curates its
-  own memory and authors and installs its own skills, tools, extensions and integrations; they
+  own memory and authors and installs its own skills, tools, workflows, and integrations; they
   live in its home and load on reload. The agent grows more capable at its job
   instead of staying a fixed tool.
 - **Persistent.** Sessions are an append-only JSONL tree, the agent's lifetime
@@ -60,7 +57,7 @@ state live under `~/.wolli`. `●` deployed and `○` forming.
 
   | File | Holds |
   | --- | --- |
-  | `SOUL.md` | Identity, authored at deploy. |
+  | `SOUL.md` | Identity, authored by the agent; the first line is its purpose. |
   | `MEMORY.md` | Durable notes the agent keeps. |
   | `USER.md` | Facts about its human. |
 
@@ -73,10 +70,10 @@ state live under `~/.wolli`. `●` deployed and `○` forming.
 
 ## Lifecycle
 
-| State | What happens |
-| --- | --- |
-| **forming** | Interviews its human and records memory. Does not act unattended. |
-| **deployed** | The agent has authored its purpose and `SOUL.md`, and you confirmed `/deploy`, the single human-held latch. It now runs on schedules and events. |
+An agent is live from the moment it is created: its daemon is installed as an
+OS service at creation and runs on schedules and events from birth. While its
+`SOUL.md` is empty it interviews you to work out its purpose, then authors
+`SOUL.md` itself.
 
 `wolli delete <name>` removes an agent and its state.
 
@@ -87,8 +84,10 @@ removes them with it:
 
 | Type | What it adds |
 | --- | --- |
-| **Integrations** | TypeScript modules: tools, commands, events, UI. |
-| **Extensions** | TypeScript modules: tools, commands, events, UI. |
+| **Integrations** | Transports that connect external services and message channels. |
+| **Workflows** | Route events into sessions and automate the agent. |
+| **Tools** | Typed actions the model calls during a turn. |
+| **Providers** | Model providers beyond the built-in catalog. |
 | **Skills** | The Agent Skills standard. |
 | **Prompt templates** | `/name` slash commands. |
 | **Themes** | TUI appearance. |
@@ -101,7 +100,7 @@ Two integrations ship bundled: **Telegram** (bidirectional chat) and a
 | Command | Action |
 | --- | --- |
 | `wolli` | Set up on first run; otherwise pick an agent and open it |
-| `wolli new <name>` | Create and birth a new agent |
+| `wolli new <name>` | Create a new agent and start chatting with it |
 | `wolli <agent>` | Open a specific agent interactively |
 | `wolli <agent> "msg" --print` | One-shot, non-interactive reply |
 | `wolli list` | List agents |
@@ -112,7 +111,7 @@ Two integrations ship bundled: **Telegram** (bidirectional chat) and a
 ## Documentation
 
 Full documentation is in [`packages/wolli/docs`](packages/wolli/docs/index.md):
-extensions, skills, prompt templates, themes, integrations, plugins, and the SDK.
+workflows, integrations, tools, providers, hooks, skills, prompt templates, themes, plugins, and the SDK.
 
 ## Roadmap
 

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

@@ -1,87 +1,50 @@
 /**
- * Discord chat extension — maps the transport's `message` events onto wolli sessions:
- * each channel/DM gets its own session (bound by a `discord:channel` tag), inbound text
- * is queued as a followUp, and the final assistant text is sent back on `agent_end`.
- * Paired with `index.ts`.
+ * Discord chat routing, as one workflows file:
+ *  - `inbound` binds each channel/DM to its own session by a `discord:channel` tag and
+ *    delivers inbound text as a followUp. Discord has no channel commands, so every message
+ *    routes into a session.
+ *  - `typing` starts the "typing…" indicator on `agent_start`; the integration owns the
+ *    keep-alive timer.
+ *  - `reply` ships the turn's final assistant text back on `agent_end`, riding the
+ *    producing session's `discord:channel` tag; typing stops first so a pure tool-call turn
+ *    still clears the indicator.
  */
 
-import type { AgentMessage } from "@opsyhq/agent";
-import type { ExtensionAPI } from "@opsyhq/wolli";
-
-// Discord's typing state lasts ~10s; refresh a little ahead of that.
-const TYPING_INTERVAL_MS = 8000;
-
-interface DiscordMessage {
-	channelId: string;
-	messageId: string;
-	text: string;
-	author: { id: string; name?: string };
-}
-
-/** Text of the last assistant message; "" for a pure tool-call turn. */
-function finalAssistantText(messages: AgentMessage[]): string {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const m = messages[i];
-		if (m.role !== "assistant") continue;
-		return m.content
-			.filter((c): c is { type: "text"; text: string } => c.type === "text")
-			.map((c) => c.text)
-			.join("")
-			.trim();
-	}
-	return "";
-}
-
-export default function (wolli: ExtensionAPI) {
-	const discord = wolli.getIntegration("discord", "default");
-
-	let typingTimer: ReturnType<typeof setInterval> | undefined;
-
-	discord.on("message", async (data) => {
-		const m = data as DiscordMessage;
-
-		// Reuse this channel's session, or create + tag a fresh one.
-		const channelTag = { "discord:channel": m.channelId };
-		const [match] = await wolli.findSessions(channelTag);
-		const session = match
-			? await wolli.openSession(match.id)
-			: await wolli.createSession({
-					setup: async (sessionManager) => {
-						await sessionManager.appendTags(channelTag);
-					},
-				});
-
-		// followUp: a message arriving mid-turn queues instead of interrupting.
-		void session.sendUserMessage(m.text, { deliverAs: "followUp" });
-	});
-
-	const stopTyping = (): void => {
-		if (typingTimer) {
-			clearInterval(typingTimer);
-			typingTimer = undefined;
-		}
-	};
-
-	wolli.on("agent_start", async (_event, ctx) => {
-		const channelId = ctx.session.getTags()["discord:channel"];
-		if (!channelId) return; // not a discord-bound session
-		const sendTyping = () => {
-			void discord.call("sendTyping", { channelId }).catch(() => {});
-		};
-		sendTyping();
-		stopTyping();
-		typingTimer = setInterval(sendTyping, TYPING_INTERVAL_MS);
-	});
-
-	wolli.on("agent_end", async ({ messages }, ctx) => {
-		stopTyping();
-
-		// Reply goes to the channel that started this turn (the producing session's tag).
-		const channelId = ctx.session.getTags()["discord:channel"];
-		if (!channelId) return; // not a discord-bound session
-
-		const text = finalAssistantText(messages as AgentMessage[]);
-		if (!text) return; // pure tool-call turn — nothing to send
-		await discord.call("sendMessage", { channelId, text });
-	});
-}
+import { wolli } from "wolli";
+import discord from "./index.ts";
+
+// m is typed from the event schema
+export const inbound = discord.on("message", async (m, ctx) => {
+	const channelTag = { "discord:channel": m.channelId };
+	const [match] = await ctx.agent.findSessions(channelTag);
+	const session = match
+		? await ctx.agent.openSession(match.id)
+		: await ctx.agent.createSession({
+				setup: (s) => s.appendTags(channelTag),
+			});
+	// followUp queues behind a running turn instead of interrupting it.
+	await session.sendUserMessage(m.text, { deliverAs: "followUp" });
+});
+
+export const typing = wolli.on("agent_start", async (_evt, ctx) => {
+	const channelId = ctx.session.getTags()["discord:channel"];
+	if (!channelId) return; // not a discord-bound session
+	await ctx.integration(discord).startTyping({ channelId });
+});
+
+export const reply = wolli.on("agent_end", async (evt, ctx) => {
+	const channelId = ctx.session.getTags()["discord:channel"];
+	if (!channelId) return; // not a discord-bound session
+	// Stop the typing indicator before the empty-text early return, so a pure tool-call
+	// turn still clears it.
+	await ctx.integration(discord).stopTyping({ channelId });
+	const text = evt.messages
+		.filter((m) => m.role === "assistant")
+		.at(-1)
+		?.content.filter((c) => c.type === "text")
+		.map((c) => c.text)
+		.join("")
+		.trim();
+	if (!text) return; // a pure tool-call turn sends nothing
+	await ctx.integration(discord).sendMessage({ channelId, text });
+});

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

@@ -1,18 +1,43 @@
 /**
  * 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.
+ * the routing workflows (`discord-chat.ts`, declared under `wolli.workflows`) map 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. The
+ * "typing…" keep-alive timers live here, since workflow files hold no module state.
  * See README.md for setup.
  */
 
-import type { IntegrationOnboardContext, IntegrationsAPI } from "@opsyhq/wolli";
+import { defineIntegration, type IntegrationOnboardContext } from "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;
 
+/** Typing indicator refresh interval — Discord's typing state lasts ~10s, so refresh a little ahead. */
+const TYPING_INTERVAL_MS = 8000;
+
+/**
+ * Live "typing…" keep-alive timers, keyed by channelId. Per-channel so parallel channels
+ * never stomp each other; cleared by `stopTyping` and by the producer's disposer on reload,
+ * so a reload can never orphan an interval.
+ */
+const typingTimers = new Map<string, ReturnType<typeof setInterval>>();
+
+function stopTypingTimer(channelId: string): void {
+	const timer = typingTimers.get(channelId);
+	if (timer) {
+		clearInterval(timer);
+		typingTimers.delete(channelId);
+	}
+}
+
+function clearAllTypingTimers(): void {
+	for (const timer of typingTimers.values()) clearInterval(timer);
+	typingTimers.clear();
+}
+
 const ONBOARD_GUIDE = [
 	"## Connect Discord",
 	"",
@@ -84,109 +109,126 @@ async function onboard(ctx: IntegrationOnboardContext): Promise<{ botToken: stri
 	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())),
+export default defineIntegration({
+	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()),
+			}),
 		}),
-		events: {
-			message: Type.Object({
+	},
+	onboard,
+	actions: {
+		sendMessage: {
+			description: "Send a text message to a channel (chunked at 2000; Discord renders markdown natively).",
+			parameters: Type.Object({
 				channelId: Type.String(),
-				messageId: Type.String(),
 				text: Type.String(),
-				author: Type.Object({
-					id: Type.String(),
-					name: Type.Optional(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 };
+			},
 		},
-		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 };
-				},
+		startTyping: {
+			description: "Show the 'typing…' indicator in a channel and keep it alive on a timer until stopTyping.",
+			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);
+				const send = () => {
+					void rest.post(Routes.channelTyping(channelId)).catch(() => {});
+				};
+				send(); // immediate first tick; the indicator would otherwise lag by the interval
+				stopTypingTimer(channelId); // replace any existing timer for this channel
+				typingTimers.set(channelId, setInterval(send, TYPING_INTERVAL_MS));
+				return { ok: true };
 			},
-			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 };
-				},
+		},
+		stopTyping: {
+			description: "Stop the 'typing…' indicator in a channel.",
+			parameters: Type.Object({
+				channelId: Type.String(),
+			}),
+			execute: async (params) => {
+				const { channelId } = params as { channelId: string };
+				stopTypingTimer(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
-			});
+	},
+	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.");
+		}
 
-			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 },
-				});
+		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);
-			});
+		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);
-				});
-			}
+		// 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;
-		},
-	});
-}
+		const dispose = () => {
+			// Clear typing timers here so a reload can never orphan an interval.
+			clearAllTypingTimers();
+			void client.destroy();
+		};
+		ctx.signal.addEventListener("abort", dispose);
+		return dispose;
+	},
+});

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

@@ -5,12 +5,12 @@
 	"type": "module",
 	"wolli": {
 		"integrations": ["./index.ts"],
-		"extensions": ["./discord-chat.ts"]
+		"workflows": ["./discord-chat.ts"]
 	},
 	"dependencies": {
 		"discord.js": "14.26.4"
 	},
 	"peerDependencies": {
-		"@opsyhq/wolli": "*"
+		"wolli": "*"
 	}
 }