wolli 0.0.4 → 0.0.6

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

@@ -0,0 +1,14 @@
+{
+	"name": "wolli-integration-github",
+	"private": true,
+	"version": "1.0.0",
+	"type": "module",
+	"wolli": {
+		"integrations": ["./index.ts"],
+		"workflows": ["./github-chat.ts"],
+		"tools": ["./github-review.ts"]
+	},
+	"peerDependencies": {
+		"wolli": "*"
+	}
+}

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

@@ -0,0 +1,144 @@
+# Slack
+
+Connect a wolli agent to Slack over **Socket Mode** — an outbound WebSocket, so no
+public URL, TLS certificate, or webhook signing is needed (the app's signing secret
+is never used or stored). Setup is a few clicks at api.slack.com plus two token
+prompts.
+
+## How the bot behaves
+
+The bot is **mention-gated**: it answers when @-mentioned, then holds a conversation
+in the mention's thread.
+
+| Context | Behavior |
+|---------|----------|
+| **@-mention in a channel** | Starts (or continues) a session bound to that thread and replies in-thread. A mention outside a thread makes that message the thread root. |
+| **Replies inside a tracked thread** | Routed to the thread's session as follow-ups — no further mention needed. |
+| **Channel chatter outside threads** | Ignored. No mention, no routing. |
+| **DMs** | Not routed in v1. |
+| **Other bots / itself** | Ignored (loop prevention). |
+
+## Session model
+
+Each mention thread gets its **own wolli session**, bound by a `slack:thread` tag
+holding `channelId:threadTs`:
+
+- **Inbound** — a mention or tracked-thread reply routes to the session tagged for its
+  thread; a mention in an untracked thread creates and tags one on the spot.
+- **Outbound** — the reply rides the producing session's tag, so answers always land
+  in the thread that started the turn.
+
+## Events and actions
+
+| Surface | Shape |
+|---------|-------|
+| `message` event | A plain user message the bot can see: `{ channelId, ts, threadTs?, text, user: { id }, channelType }`. Edits, deletes, joins, bot posts (including the bot's own), and messages that @-mention the bot are dropped. |
+| `app_mention` event | The bot was @-mentioned: `{ channelId, ts, threadTs?, text, user: { id } }`. Mentions arrive **only** as this event, never as `message`, so the two are disjoint. |
+| `sendMessage` action | `{ channelId, text, threadTs? }` → `chat.postMessage`, chunked at 40,000 characters, returns `{ ts: string[] }`. Pass `threadTs` to reply in a thread; Slack renders `mrkdwn`, not standard markdown. |
+
+`ts` is Slack's message id and doubles as the key for threading: reply to a message
+by passing its `ts` (or its `threadTs` if it was already in a thread) as `threadTs`.
+
+## Setup
+
+### 1. Create a Slack app
+
+Open [api.slack.com/apps](https://api.slack.com/apps), **Create New App → From
+scratch**, pick a name and workspace.
+
+### 2. Enable Socket Mode
+
+Open **Socket Mode** in the sidebar and enable it. Slack prompts you to create an
+**app-level token** with the `connections:write` scope — copy the `xapp-...` token.
+
+### 3. Add bot token scopes
+
+Under **OAuth & Permissions → Scopes → Bot Token Scopes** add:
+
+- `chat:write` — send messages
+- `app_mentions:read` — receive @-mentions
+- `channels:history`, `groups:history`, `im:history`, `mpim:history` — receive
+  messages in public channels, private channels, DMs, and group DMs
+
+### 4. Subscribe to events
+
+Under **Event Subscriptions**, toggle **Enable Events** and add the bot events
+`app_mention`, `message.channels`, `message.groups`, `message.im`, `message.mpim`.
+(With Socket Mode on, no Request URL is asked for.)
+
+### 5. Install and copy the bot token
+
+Under **OAuth & Permissions**, click **Install to Workspace** and authorize. Copy the
+**Bot User OAuth Token** (`xoxb-...`).
+
+### 6. Install and onboard in wolli
+
+```bash
+wolli <agent> plugins install ./built-in/plugins/slack
+```
+
+Onboarding prompts for the bot token, then the app-level token, verifies them with
+live `auth.test` and `apps.connections.open` calls, and stores them. If you installed
+non-interactively, onboard later with `wolli <agent> plugins configure slack`.
+
+### 7. Invite the bot and restart
+
+The bot only receives channel messages where it is a member — run `/invite @yourbot`
+in the channels it should hear. Then:
+
+```bash
+wolli restart <agent>
+```
+
+## Configuration reference
+
+Configuration lives per agent in `~/.wolli/agents/<name>/integrations.json`:
+
+```json
+{
+  "slack": {
+    "botToken": "xoxb-...",
+    "appToken": "xapp-...",
+    "allowedChannelIds": ["C0123456789"]
+  }
+}
+```
+
+| Field | Required | Default | Purpose |
+|-------|----------|---------|---------|
+| `botToken` | Yes | — | Bot token for all Web API calls. Onboarding stores it raw; a `$ENV` / `!cmd` reference placed here by hand also resolves on read. |
+| `appToken` | Yes | — | App-level token, used only to open the Socket Mode connection. |
+| `allowedChannelIds` | No | *(any channel)* | Allowlist of channel ids the integration emits events for. Empty or absent accepts **any** channel the bot can see (logged as a warning at startup). |
+
+`allowedChannelIds` is not asked during onboarding — edit `integrations.json` to set
+it. Channel ids look like `C0123456789`; grab one from a channel's **View channel
+details → About** panel.
+
+## Not supported
+
+- DM routing — DM `message` events are emitted by the integration (with the `im`
+  scopes and event subscriptions) but the chat workflow does not route them.
+- Inbound media, file uploads, edits, deletions, or reactions.
+- Slash commands and interactive payloads (buttons, modals) — their envelopes are
+  acked and dropped.
+- Durable event dedupe: envelopes are acked on receipt, so a Slack retry after a
+  crash can re-emit an event.
+- HTTP Events API mode — Socket Mode only.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Connects but no `message` events | Subscribe to the `message.*` bot events (step 4) and reinstall the app; then check the bot is a member of the channel (`/invite @yourbot`). |
+| `invalid_auth` / `not_authed` | Wrong token in the wrong field — `botToken` is `xoxb-...`, `appToken` is `xapp-...`. |
+| `not_in_channel` on sendMessage | Invite the bot to the channel first. |
+| Bot never answers a mention | Check the `app_mention` bot event is subscribed (step 4) and the agent was restarted after install. |
+
+## Security
+
+- `allowedChannelIds` is the only access gate today. With it empty, **any** channel
+  the bot can see is accepted — set it to lock the integration to known channels.
+- There is no per-user gate. Anyone who can post where the bot listens can drive the
+  agent, so keep the bot in trusted channels.
+- The tokens grant control of the bot — never commit them. Wolli writes
+  `integrations.json` with mode `0600`.

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

@@ -0,0 +1,360 @@
+/**
+ * Slack transport — the integration half only (no routing workflows yet).
+ *
+ * Faces Slack over Socket Mode: `apps.connections.open` (app-level `xapp-` token)
+ * returns a one-time WebSocket URL, envelopes arrive over that socket and are
+ * acked immediately, and normalized `message` / `app_mention` events are emitted.
+ * Outbound goes through the Web API (`chat.postMessage`, bot `xoxb-` token). No
+ * public URL, TLS, or webhook signing is involved — Socket Mode has no inbound
+ * HTTP surface, so the app's signing secret is NOT needed or stored.
+ *
+ * Zero dependencies: plain `fetch` plus Node's global `WebSocket` (Node >= 22).
+ *
+ * ## Slack app requirements
+ *  - Socket Mode enabled (this is what mints the `xapp-` token, scope `connections:write`).
+ *  - Bot token scopes: `chat:write`, `app_mentions:read`, plus the history scope for
+ *    each surface it should hear (`channels:history`, `groups:history`, `im:history`,
+ *    `mpim:history`).
+ *  - Event Subscriptions enabled with the matching bot events (`app_mention`,
+ *    `message.channels`, `message.groups`, `message.im`, `message.mpim`).
+ *  - The bot only receives channel messages where it is a member (`/invite @bot`).
+ *
+ * ## Config (`~/.wolli/agents/<name>/integrations.json`)
+ *
+ *   { "slack": { "botToken": "xoxb-...", "appToken": "xapp-..." } }
+ *
+ * Both tokens resolve `$ENV` / `!cmd` references on read. `allowedChannelIds` is an
+ * allowlist — empty/absent means "allow any channel" (logged as a warning).
+ *
+ * ## Known v1 limitations
+ *  - Slack sends a bot mention as BOTH `app_mention` and `message`; this transport
+ *    emits only `app_mention` for it, keeping the two events disjoint. The suppression
+ *    needs the bot's user id from `auth.test`, so a mention landing in the first
+ *    moments after connect can still emit both.
+ *  - Envelopes are acked on receipt with no durable event-id dedupe, so a Slack
+ *    retry after a crash can re-emit an event.
+ *  - On a Slack-requested refresh the socket is closed and reopened, so events in
+ *    that gap are seen only if Slack retries them.
+ *  - Text only: no media, edits, deletions, reactions, slash commands, or interactive
+ *    payloads (non-`events_api` envelopes are acked and dropped).
+ */
+
+// The integration surface is host-provided via the loader's VIRTUAL_MODULES / aliases, so
+// wolli is a peerDependency, not a dependency.
+import { defineIntegration, type IntegrationOnboardContext } from "wolli";
+import { Type } from "typebox";
+
+/** Slack cuts off a single chat.postMessage at 40,000 characters. */
+const SLACK_MAX_LENGTH = 40000;
+
+const ONBOARD_GUIDE = [
+	"## Connect Slack",
+	"",
+	"1. Open [api.slack.com/apps](https://api.slack.com/apps) and **Create New App**",
+	"   (from scratch).",
+	"2. Under **Socket Mode**, enable it — this creates an **app-level token**",
+	"   (`xapp-...`) with the `connections:write` scope. Copy it.",
+	"3. Under **OAuth & Permissions → Bot Token Scopes**, add `chat:write`,",
+	"   `app_mentions:read`, `channels:history`, `groups:history`, `im:history`,",
+	"   `mpim:history`.",
+	"4. Under **Event Subscriptions**, enable events and subscribe to the bot events",
+	"   `app_mention`, `message.channels`, `message.groups`, `message.im`,",
+	"   `message.mpim`.",
+	"5. **Install to Workspace** (OAuth & Permissions) and copy the **bot token**",
+	"   (`xoxb-...`).",
+	"6. Invite the bot to a channel with `/invite @yourbot`, then paste both tokens",
+	"   on the next screens. The signing secret is not needed — Socket Mode has no",
+	"   inbound webhook to verify.",
+].join("\n");
+
+interface SlackAccount {
+	botToken: string;
+	appToken: string;
+	allowedChannelIds?: string[];
+}
+
+/** Successful envelope of every Web API response; `ok: false` carries `error`. */
+interface SlackApiOk {
+	ok: boolean;
+	error?: string;
+}
+
+/** One inbound Socket Mode frame. Only `events_api` envelopes carry an event. */
+interface SocketEnvelope {
+	type: string;
+	envelope_id?: string;
+	payload?: { event?: SlackEvent };
+}
+
+/** The subset of Slack event fields this transport reads. */
+interface SlackEvent {
+	type: string;
+	subtype?: string;
+	user?: string;
+	bot_id?: string;
+	channel?: string;
+	channel_type?: string;
+	text?: string;
+	ts?: string;
+	thread_ts?: string;
+}
+
+/** Call a Slack Web API method; throws on transport errors and `ok: false`. */
+async function slackApi<T>(token: string, method: string, body?: Record<string, unknown>): Promise<T & SlackApiOk> {
+	const res = await fetch(`https://slack.com/api/${method}`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			...(body ? { "content-type": "application/json; charset=utf-8" } : {}),
+		},
+		body: body ? JSON.stringify(body) : undefined,
+	});
+	const data = (await res.json()) as T & SlackApiOk;
+	if (!data.ok) throw new Error(`Slack ${method} failed: ${data.error ?? `HTTP ${res.status}`}`);
+	return data;
+}
+
+/** Split into ≤40,000-code-unit chunks without cutting a surrogate pair. */
+function chunkText(text: string, max = SLACK_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 both tokens, verify the bot token with `auth.test` and the
+ * app token with `apps.connections.open`, return them to store.
+ */
+async function onboard(ctx: IntegrationOnboardContext): Promise<{ botToken: string; appToken: string } | undefined> {
+	ctx.ui.notify(ONBOARD_GUIDE, "info");
+
+	const botEntered = await ctx.ui.input("Paste the bot token (xoxb-...)");
+	if (botEntered === undefined) return undefined; // cancelled
+	const botToken = botEntered.trim();
+	if (!botToken) {
+		ctx.ui.notify("No bot token entered.", "error");
+		return undefined;
+	}
+
+	const appEntered = await ctx.ui.input("Paste the app-level token (xapp-...)");
+	if (appEntered === undefined) return undefined; // cancelled
+	const appToken = appEntered.trim();
+	if (!appToken) {
+		ctx.ui.notify("No app-level token entered.", "error");
+		return undefined;
+	}
+
+	try {
+		const me = await slackApi<{ user: string; team: string }>(botToken, "auth.test");
+		await slackApi<{ url: string }>(appToken, "apps.connections.open");
+		ctx.ui.notify(`Verified bot @${me.user} in workspace ${me.team}.`, "info");
+	} catch (err) {
+		ctx.ui.notify(`Could not verify the tokens: ${err instanceof Error ? err.message : String(err)}`, "error");
+		return undefined;
+	}
+
+	return { botToken, appToken };
+}
+
+export default defineIntegration({
+	account: Type.Object({
+		/** Bot token (`xoxb-...`), used for all Web API calls. */
+		botToken: Type.String(),
+		/** App-level token (`xapp-...`, scope `connections:write`), used only to open the socket. */
+		appToken: Type.String(),
+		/** Allowlist of channel ids. Empty/absent = allow all (logged as a warning). */
+		allowedChannelIds: Type.Optional(Type.Array(Type.String())),
+	}),
+	events: {
+		/**
+		 * A plain user message the bot can see (no subtype — edits, joins, bot posts are
+		 * dropped). Messages that @-mention the bot arrive only as `app_mention`.
+		 */
+		message: Type.Object({
+			channelId: Type.String(),
+			/** Message timestamp — Slack's message id AND the key for replying in-thread. */
+			ts: Type.String(),
+			/** Present when the message is inside a thread. */
+			threadTs: Type.Optional(Type.String()),
+			text: Type.String(),
+			user: Type.Object({ id: Type.String() }),
+			/** "channel" | "group" | "im" | "mpim". */
+			channelType: Type.String(),
+		}),
+		/** The bot was @-mentioned. Mentions are NOT also emitted as `message`. */
+		app_mention: Type.Object({
+			channelId: Type.String(),
+			ts: Type.String(),
+			threadTs: Type.Optional(Type.String()),
+			text: Type.String(),
+			user: Type.Object({ id: Type.String() }),
+		}),
+	},
+	onboard,
+	actions: {
+		sendMessage: {
+			description:
+				"Send a text message to a channel via chat.postMessage (chunked at 40000; Slack renders mrkdwn). Pass threadTs to reply in a thread.",
+			parameters: Type.Object({
+				channelId: Type.String(),
+				text: Type.String(),
+				threadTs: Type.Optional(Type.String()),
+			}),
+			execute: async (params, ctx) => {
+				const { channelId, text, threadTs } = params as {
+					channelId: string;
+					text: string;
+					threadTs?: string;
+				};
+				const account = ctx.account as SlackAccount;
+
+				const ts: string[] = [];
+				for (const chunk of chunkText(text)) {
+					const sent = await slackApi<{ ts: string }>(account.botToken, "chat.postMessage", {
+						channel: channelId,
+						text: chunk,
+						...(threadTs ? { thread_ts: threadTs } : {}),
+					});
+					ts.push(sent.ts);
+				}
+				return { ts };
+			},
+		},
+	},
+	run(ctx) {
+		const account = ctx.account as SlackAccount;
+		const { botToken, appToken, allowedChannelIds } = account;
+		const allowAll = !allowedChannelIds || allowedChannelIds.length === 0;
+		if (allowAll) {
+			console.warn("[slack] no allowedChannelIds configured — accepting messages from ANY channel.");
+		}
+
+		let ws: WebSocket | undefined;
+		let stopped = false;
+		let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+		let attempt = 0;
+
+		// Self-filter id. Bot posts always carry bot_id, which is filtered regardless;
+		// this covers the bot's non-bot-authored surfaces while auth.test is in flight.
+		let botUserId: string | undefined;
+		void slackApi<{ user_id: string }>(botToken, "auth.test")
+			.then((r) => {
+				botUserId = r.user_id;
+			})
+			.catch((err) => {
+				console.error("[slack] auth.test failed:", err instanceof Error ? err.message : err);
+			});
+
+		const handleEvent = (event: SlackEvent) => {
+			const channelId = event.channel;
+			if (!channelId || !event.ts) return;
+			if (!allowAll && !allowedChannelIds?.includes(channelId)) return;
+			if (event.bot_id) return; // skip our own posts and other bots (loop prevention)
+			if (!event.user || botUserId === event.user) return;
+			const text = event.text;
+			if (!text) return; // media-only or empty
+
+			if (event.type === "message") {
+				if (event.subtype) return; // edits, deletes, joins, bot_message, ...
+				// Slack sends a bot mention as both `message` and `app_mention` — emit only the
+				// latter so the events stay disjoint and consumers never double-handle a mention.
+				if (botUserId && text.includes(`<@${botUserId}>`)) return;
+				ctx.emit("message", {
+					channelId,
+					ts: event.ts,
+					threadTs: event.thread_ts,
+					text,
+					user: { id: event.user },
+					channelType: event.channel_type ?? "channel",
+				});
+			} else if (event.type === "app_mention") {
+				ctx.emit("app_mention", {
+					channelId,
+					ts: event.ts,
+					threadTs: event.thread_ts,
+					text,
+					user: { id: event.user },
+				});
+			}
+		};
+
+		const scheduleReconnect = () => {
+			if (stopped || reconnectTimer) return;
+			attempt += 1;
+			const delay = Math.min(30_000, 1000 * 2 ** attempt);
+			reconnectTimer = setTimeout(() => {
+				reconnectTimer = undefined;
+				void connect().catch((err) => {
+					console.error("[slack] reconnect failed:", err instanceof Error ? err.message : err);
+					scheduleReconnect();
+				});
+			}, delay);
+		};
+
+		const handleFrame = (socket: WebSocket, raw: string) => {
+			let envelope: SocketEnvelope;
+			try {
+				envelope = JSON.parse(raw) as SocketEnvelope;
+			} catch {
+				return;
+			}
+			// Slack refreshes connections periodically; close and let the reconnect loop
+			// fetch a fresh one-time URL.
+			if (envelope.type === "disconnect") {
+				socket.close();
+				return;
+			}
+			// Ack within 3s or Slack redelivers. Ack everything (non-events_api envelopes
+			// like slash_commands are acked and dropped).
+			if (envelope.envelope_id) {
+				socket.send(JSON.stringify({ envelope_id: envelope.envelope_id }));
+			}
+			if (envelope.type === "events_api" && envelope.payload?.event) {
+				handleEvent(envelope.payload.event);
+			}
+		};
+
+		const connect = async () => {
+			if (stopped) return;
+			const { url } = await slackApi<{ url: string }>(appToken, "apps.connections.open");
+			if (stopped) return;
+			const socket = new WebSocket(url);
+			ws = socket;
+			socket.addEventListener("open", () => {
+				attempt = 0;
+			});
+			socket.addEventListener("message", (e) => {
+				if (typeof e.data === "string") handleFrame(socket, e.data);
+			});
+			socket.addEventListener("error", () => {
+				// A close event always follows; reconnect is scheduled there.
+			});
+			socket.addEventListener("close", () => {
+				if (ws === socket) scheduleReconnect();
+			});
+		};
+
+		void connect().catch((err) => {
+			console.error("[slack] failed to connect:", err instanceof Error ? err.message : err);
+			scheduleReconnect();
+		});
+
+		const dispose = () => {
+			stopped = true;
+			if (reconnectTimer) clearTimeout(reconnectTimer);
+			ws?.close();
+		};
+		ctx.signal.addEventListener("abort", dispose);
+		return dispose;
+	},
+});

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * Slack chat routing, as one workflows file:
+ *  - `mention` binds each mention thread to its own session by a `slack:thread` tag and
+ *    delivers the mention text as a followUp. A mention posted outside a thread makes its
+ *    own `ts` the thread root, so the reply opens the thread the session lives in.
+ *  - `thread` continues tracked threads: replies inside a thread whose session exists are
+ *    delivered as followUps without needing another mention. Untracked threads and
+ *    non-thread channel chatter never route — the bot is mention-gated.
+ *  - `reply` ships the turn's final assistant text back on `agent_end`, riding the
+ *    producing session's `slack:thread` tag, threaded under the originating message.
+ * Slack has no typing indicator for classic bots, so there is no typing workflow.
+ */
+
+import { wolli } from "wolli";
+import slack from "./index.ts";
+
+/** Tag value `${channelId}:${threadTs}` — channel ids never contain ":". */
+function threadTag(channelId: string, threadTs: string): Record<string, string> {
+	return { "slack:thread": `${channelId}:${threadTs}` };
+}
+
+// m is typed from the event schema
+export const mention = slack.on("app_mention", async (m, ctx) => {
+	// The mention is the thread root unless it was posted inside an existing thread.
+	const tag = threadTag(m.channelId, m.threadTs ?? m.ts);
+	const [match] = await ctx.agent.findSessions(tag);
+	const session = match
+		? await ctx.agent.openSession(match.id)
+		: await ctx.agent.createSession({
+				setup: (s) => s.appendTags(tag),
+			});
+	// followUp queues behind a running turn instead of interrupting it.
+	await session.sendUserMessage(m.text, { deliverAs: "followUp" });
+});
+
+export const thread = slack.on("message", async (m, ctx) => {
+	if (!m.threadTs) return; // channel chatter outside threads never routes (mention-gated)
+	const [match] = await ctx.agent.findSessions(threadTag(m.channelId, m.threadTs));
+	if (!match) return; // untracked thread
+	const session = await ctx.agent.openSession(match.id);
+	await session.sendUserMessage(m.text, { deliverAs: "followUp" });
+});
+
+export const reply = wolli.on("agent_end", async (evt, ctx) => {
+	const bound = ctx.session.getTags()["slack:thread"];
+	if (!bound) return; // not a slack-bound session
+	const sep = bound.indexOf(":");
+	const channelId = bound.slice(0, sep);
+	const threadTs = bound.slice(sep + 1);
+	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(slack).sendMessage({ channelId, text, threadTs });
+});