wolli 0.0.2 → 0.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 # Wolli
 
-**Build persistent, purposeful 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,16 +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`.
+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.
+
+ ↑/↓ 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, and extensions; 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
@@ -49,12 +57,12 @@ state live under `~/.wolli`.
 
   | 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. |
 
 - **Always on, locally.** A per-agent daemon supervised by launchd (macOS) or
-  systemd (linux) runs the agent on schedules and events while your machine is on.
+  systemd (Linux) runs the agent on schedules and events while your machine is on.
 - **Sandboxed.** The agent runs in a sandbox by default: `srt` (Apple Seatbelt /
   bubblewrap), or optional Docker. Reaching your real machine is an explicit,
   approval-gated escalation.
@@ -62,10 +70,10 @@ state live under `~/.wolli`.
 
 ## 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.
 
@@ -76,7 +84,10 @@ removes them with it:
 
 | Type | What it adds |
 | --- | --- |
-| **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. |
@@ -89,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 |
@@ -100,8 +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.
-The integration/extension split is covered in [INTEGRATION.md](INTEGRATION.md).
+workflows, integrations, tools, providers, hooks, skills, prompt templates, themes, plugins, and the SDK.
 
 ## Roadmap
 

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

@@ -0,0 +1,156 @@
+# Discord
+
+Connect a wolli agent to Discord. The bot runs over Discord's gateway WebSocket,
+gives each channel and DM its own wolli session, and replies in place. Setup is a
+few clicks in the Discord Developer Portal plus a single token prompt.
+
+## How the bot behaves
+
+Before setup, here's the part most people want to know: this bot answers
+**everything it can read**. There is no `@mention` gate.
+
+| Context | Behavior |
+|---------|----------|
+| **DMs** | Responds to every non-empty message. |
+| **Server channels** | Responds to every non-empty message in any channel it can read. No `@mention` required — unlike some Discord agents, the bot replies to plain messages. Scope where it listens with `allowedChannelIds`. |
+| **Other bots / itself** | Ignored. The bot skips its own messages and messages from any other bot, so it can't loop. |
+| **Empty / media-only messages** | Skipped (there is no inbound media handling). |
+
+While a turn runs, the bot shows Discord's **typing…** indicator in the channel and
+keeps it alive until the reply lands. Replies are chunked at **2000 characters**
+(Discord's per-message limit); Discord renders markdown natively, so formatting in
+the agent's output comes through as-is.
+
+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.
+
+## Session model
+
+Each channel and DM gets its **own wolli session**, bound by a `discord:channel`
+tag:
+
+- **Inbound** — an incoming message is routed to the session tagged for its channel.
+  If none exists yet, one is created and tagged on the spot. Histories never bleed
+  across channels, and two channels can run in parallel.
+- **Outbound** — the reply rides the producing session's tag, so the answer always
+  returns to the channel that started the turn — not to whoever messaged most
+  recently.
+
+## Setup
+
+### 1. Create a Discord application
+
+Open the [Discord Developer Portal](https://discord.com/developers/applications) and
+click **New Application**. Name it (e.g. "Wolli") and accept the terms.
+
+### 2. Enable the Message Content Intent
+
+This is the critical step. Open **Bot** in the sidebar, scroll to **Privileged
+Gateway Intents**, toggle **Message Content Intent** to **ON**, and **Save Changes**.
+
+Without it, the bot still receives message events but the message text arrives
+**empty**, so it can never reply. This is the single privileged intent the bot
+needs — you do **not** need Server Members or Presence.
+
+### 3. Reset and copy the bot token
+
+On the same **Bot** page, click **Reset Token**, complete 2FA if prompted, and copy
+the token. It is shown only once — if you lose it, reset and generate a new one. Keep
+it secret.
+
+### 4. Invite the bot
+
+Open **OAuth2 → URL Generator** and select:
+
+- **Scopes:** `bot`
+- **Bot Permissions:** **View Channels**, **Send Messages**, **Read Message History**
+
+Copy the generated URL at the bottom, open it, pick a server you administer, and
+authorize. Only the `bot` scope is required — the `applications.commands` scope is
+not needed.
+
+### 5. Install and onboard in wolli
+
+```bash
+wolli <agent> plugins install ./built-in/plugins/discord
+```
+
+In an interactive terminal this runs onboarding immediately: it prints the connect
+guide, then prompts you to **paste the bot token**. Paste the token from step 3.
+Wolli verifies it with a live `GET /users/@me` 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 discord
+```
+
+### 6. Restart the agent
+
+```bash
+wolli restart <agent>
+```
+
+This starts the gateway producer that connects to Discord. After onboarding a fresh
+integration, restart the agent once so the bot comes online and begins responding.
+
+## Configuration reference
+
+Configuration lives per agent in `~/.wolli/agents/<name>/integrations.json` under
+`discord.default`:
+
+```json
+{
+  "discord": {
+    "default": {
+      "botToken": "...",
+      "allowedChannelIds": ["123456789012345678"]
+    }
+  }
+}
+```
+
+| Field | Required | Default | Purpose |
+|-------|----------|---------|---------|
+| `botToken` | Yes | — | The bot token. Onboarding stores it raw; a `$ENV` / `!cmd` reference placed here by hand also resolves on read. |
+| `allowedChannelIds` | No | *(any channel)* | Allowlist of channel IDs the bot will respond in. Empty or absent accepts **any** channel the bot can read (logged as a warning at startup). |
+
+Discord IDs are snowflakes — keep them as **quoted strings** in JSON, never numbers,
+since a 64-bit snowflake exceeds JavaScript's safe-integer range. To grab a channel
+ID, enable **Developer Mode** in Discord (Settings → Advanced), then right-click a
+channel and **Copy Channel ID**.
+
+`allowedChannelIds` is not asked during onboarding — edit `integrations.json` to set
+it.
+
+## Not supported
+
+The bot is deliberately focused on text chat. It does not provide:
+
+- Mention-gating — it answers every readable message, not only `@mentions`.
+- User, role, or guild allowlists — channel-level `allowedChannelIds` is the only
+  scope control.
+- Threads or auto-threading.
+- Reactions.
+- Native Discord slash commands.
+- Inbound or outbound media, attachments, or voice.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Bot is online but never replies | Enable the **Message Content Intent** (step 2). Without it the message text arrives empty and there is nothing to answer. |
+| `Disallowed intents` on connect | Same cause: the Message Content Intent is not enabled in the Developer Portal. |
+| No reply right after the first install/onboard | Restart the agent (`wolli restart <agent>`) so the gateway producer starts. |
+| Silence in one specific channel | The bot is missing **View Channels** / **Send Messages** there, or the channel isn't in `allowedChannelIds`. Try a DM to isolate. |
+
+## Security
+
+- `allowedChannelIds` is the only access gate today. With it empty, **any** channel
+  the bot can read is accepted — set it to lock the bot to known channels.
+- There is no per-user or per-role gate. Anyone who can post in an allowed channel
+  can drive the agent, so keep the bot in trusted channels.
+- The bot token grants full control of the bot account — never commit it or share
+  it. Wolli writes `integrations.json` with mode `0600`.

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

@@ -0,0 +1,50 @@
+/**
+ * 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 { 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

@@ -0,0 +1,234 @@
+/**
+ * Discord transport — holds the bot token, emits a `message` event per inbound message;
+ * 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 { 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",
+	"",
+	"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 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()),
+			}),
+		}),
+	},
+	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 };
+			},
+		},
+		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
+		});
+
+		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 = () => {
+			// 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

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