@moxxy/plugin-channel-slack 0.27.0

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@moxxy/plugin-channel-slack",
+  "version": "0.27.0",
+  "description": "Slack bot channel for moxxy. Ingests Slack Events API over the proxy relay, drives the Session, and streams threaded replies. Autonomous allow-list permission model (no human in the loop).",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "channel",
+    "slack",
+    "bot"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-channel-slack"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "cli"
+    },
+    "requirements": [
+      {
+        "kind": "plugin",
+        "name": "@moxxy/plugin-vault",
+        "hint": "slack resolves the vault from the service registry for its bot token + signing secret + pairing; @moxxy/plugin-vault must load first"
+      }
+    ],
+    "setup": {
+      "title": "Slack bot",
+      "description": "Create an app at https://api.slack.com/apps → install it to your workspace and copy the Bot User OAuth Token (xoxb-…) plus the Signing Secret (Basic Information). Events arrive over an HTTP ingest URL — after setup, `moxxy slack pair` prints the Request URL to paste into Event Subscriptions; pairing is trust-on-first-@mention.",
+      "fields": [
+        {
+          "key": "botToken",
+          "label": "Bot User OAuth Token (xoxb-…)",
+          "kind": "secret",
+          "vaultKey": "slack_bot_token",
+          "required": true,
+          "placeholder": "xoxb-…"
+        },
+        {
+          "key": "signingSecret",
+          "label": "Signing Secret",
+          "kind": "secret",
+          "vaultKey": "slack_signing_secret",
+          "required": true
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "zod": "^3.24.0",
+    "@moxxy/channel-kit": "0.27.0",
+    "@moxxy/core": "0.27.0",
+    "@moxxy/plugin-tunnel-proxy": "0.27.0",
+    "@moxxy/config": "0.27.0",
+    "@moxxy/plugin-vault": "0.27.0",
+    "@moxxy/sdk": "0.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/testing": "0.0.45",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/channel/slack-client.ts

@@ -0,0 +1,123 @@
+/**
+ * Minimal hand-rolled Slack Web API client. The repo norm is hand-rolled
+ * `fetch` over a vendor SDK (only Telegram pulls in grammy), so there is NO
+ * `@slack/web-api` dependency: each method POSTs JSON to
+ * `https://slack.com/api/<method>` with `Authorization: Bearer <token>` and
+ * throws on a non-`ok` Slack response.
+ */
+
+const SLACK_API_BASE = 'https://slack.com/api';
+
+export interface SlackClientOptions {
+  readonly token: string;
+  /** Override the API base (tests). */
+  readonly baseUrl?: string;
+  /** Injectable fetch (tests). Defaults to the global `fetch`. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+export interface AuthTestResult {
+  /** The bot's own user id — used to drop the bot's own messages. */
+  readonly botUserId: string;
+  readonly teamId?: string;
+  readonly team?: string;
+  readonly url?: string;
+}
+
+export interface PostMessageResult {
+  readonly channel: string;
+  /** The new message ts — used as the edit target for streaming. */
+  readonly ts: string;
+}
+
+/** Shape of every Slack API JSON response: a boolean `ok` plus method fields. */
+interface SlackApiResponse {
+  readonly ok: boolean;
+  readonly error?: string;
+  readonly [k: string]: unknown;
+}
+
+export class SlackClient {
+  private readonly token: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: SlackClientOptions) {
+    this.token = opts.token;
+    this.baseUrl = (opts.baseUrl ?? SLACK_API_BASE).replace(/\/+$/, '');
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  private async call(method: string, body: Record<string, unknown>): Promise<SlackApiResponse> {
+    const res = await this.fetchImpl(`${this.baseUrl}/${method}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+        authorization: `Bearer ${this.token}`,
+      },
+      body: JSON.stringify(body),
+    });
+    // Slack always returns 200 with `{ ok: false, error }` for app-level errors;
+    // a non-2xx is a transport/auth problem worth surfacing distinctly.
+    if (!res.ok) {
+      throw new Error(`Slack ${method} HTTP ${res.status}`);
+    }
+    const json = (await res.json()) as SlackApiResponse;
+    if (!json.ok) {
+      throw new Error(`Slack ${method} failed: ${json.error ?? 'unknown_error'}`);
+    }
+    return json;
+  }
+
+  /** Validate the token and capture the bot's own user id. */
+  async authTest(): Promise<AuthTestResult> {
+    const json = await this.call('auth.test', {});
+    const botUserId = typeof json['user_id'] === 'string' ? json['user_id'] : '';
+    if (!botUserId) throw new Error('Slack auth.test returned no user_id');
+    return {
+      botUserId,
+      ...(typeof json['team_id'] === 'string' ? { teamId: json['team_id'] } : {}),
+      ...(typeof json['team'] === 'string' ? { team: json['team'] } : {}),
+      ...(typeof json['url'] === 'string' ? { url: json['url'] } : {}),
+    };
+  }
+
+  /** Post a message into a channel/thread. Returns the channel + new ts. */
+  async postMessage(args: {
+    channel: string;
+    text: string;
+    threadTs?: string;
+  }): Promise<PostMessageResult> {
+    const json = await this.call('chat.postMessage', {
+      channel: args.channel,
+      text: args.text,
+      ...(args.threadTs ? { thread_ts: args.threadTs } : {}),
+    });
+    const channel = typeof json['channel'] === 'string' ? json['channel'] : args.channel;
+    const ts = typeof json['ts'] === 'string' ? json['ts'] : '';
+    if (!ts) throw new Error('Slack chat.postMessage returned no ts');
+    return { channel, ts };
+  }
+
+  /** Edit an existing message (the streaming-update path). */
+  async updateMessage(args: { channel: string; ts: string; text: string }): Promise<void> {
+    await this.call('chat.update', {
+      channel: args.channel,
+      ts: args.ts,
+      text: args.text,
+    });
+  }
+
+  /** Optional: read a thread's replies (unused by v1 streaming, exposed for tools). */
+  async conversationsReplies(args: {
+    channel: string;
+    ts: string;
+  }): Promise<ReadonlyArray<Record<string, unknown>>> {
+    const json = await this.call('conversations.replies', {
+      channel: args.channel,
+      ts: args.ts,
+    });
+    const messages = json['messages'];
+    return Array.isArray(messages) ? (messages as Array<Record<string, unknown>>) : [];
+  }
+}

package/src/channel/turn-runner.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { MoxxyEvent } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { runSlackTurn } from './turn-runner.js';
+import type { SlackClient } from './slack-client.js';
+
+/** A fake event log that fans out to subscribers, like the real session.log. */
+class FakeLog {
+  private readonly subs = new Set<(e: MoxxyEvent) => void>();
+  subscribe(fn: (e: MoxxyEvent) => void): () => void {
+    this.subs.add(fn);
+    return () => this.subs.delete(fn);
+  }
+  emit(e: MoxxyEvent): void {
+    for (const s of this.subs) s(e);
+  }
+}
+
+function chunk(turnId: string, delta: string): MoxxyEvent {
+  return {
+    id: `e_${Math.random()}`,
+    seq: 0,
+    ts: 0,
+    sessionId: 's1',
+    turnId,
+    source: 'model',
+    type: 'assistant_chunk',
+    delta,
+  } as MoxxyEvent;
+}
+
+function message(turnId: string, content: string): MoxxyEvent {
+  return {
+    id: `e_${Math.random()}`,
+    seq: 0,
+    ts: 0,
+    sessionId: 's1',
+    turnId,
+    source: 'model',
+    type: 'assistant_message',
+    content,
+    stopReason: 'end_turn',
+  } as MoxxyEvent;
+}
+
+/** Records every chat.postMessage / chat.update so the test can assert on Slack output. */
+function fakeClient(): {
+  client: SlackClient;
+  posts: Array<{ channel: string; text: string; threadTs?: string }>;
+  edits: Array<{ channel: string; ts: string; text: string }>;
+} {
+  const posts: Array<{ channel: string; text: string; threadTs?: string }> = [];
+  const edits: Array<{ channel: string; ts: string; text: string }> = [];
+  let n = 0;
+  const client = {
+    async postMessage(args: { channel: string; text: string; threadTs?: string }) {
+      posts.push(args);
+      return { channel: args.channel, ts: `ts_${++n}` };
+    },
+    async updateMessage(args: { channel: string; ts: string; text: string }) {
+      edits.push(args);
+    },
+  } as unknown as SlackClient;
+  return { client, posts, edits };
+}
+
+describe('runSlackTurn (turnId-filtered streaming)', () => {
+  it('streams only the matching turnId into the thread', async () => {
+    vi.useFakeTimers();
+    const log = new FakeLog();
+    const { client, posts, edits } = fakeClient();
+
+    // runTurn emits onto the shared log: our turn's chunks PLUS a foreign turn's
+    // chunk that must never reach Slack. Resolves after emitting.
+    const session = {
+      log,
+      runTurn(_prompt: string, opts: { turnId: string }) {
+        const ownTurn = opts.turnId;
+        return (async function* () {
+          log.emit(chunk('foreign-turn', 'SHOULD NOT APPEAR'));
+          log.emit(chunk(ownTurn, 'Hello'));
+          log.emit(chunk(ownTurn, ', world'));
+          log.emit(message(ownTurn, 'Hello, world!'));
+          log.emit(chunk('foreign-turn', 'ALSO NOT THIS'));
+          yield message(ownTurn, 'Hello, world!');
+        })();
+      },
+    } as unknown as Session;
+
+    const controller = new AbortController();
+    const promise = runSlackTurn(
+      { session, client, editFrameMs: 1000 },
+      {
+        channel: 'C1',
+        threadTs: '111.222',
+        text: '<@UBOT> hi',
+        controller,
+        turnId: 'own-turn',
+      },
+    );
+    // Drain timers (the debounced flush) and the turn.
+    await vi.runAllTimersAsync();
+    await promise;
+    vi.useRealTimers();
+
+    // Exactly one message posted into the right thread, carrying the final text.
+    expect(posts).toHaveLength(1);
+    expect(posts[0]).toMatchObject({ channel: 'C1', threadTs: '111.222' });
+    // The final flush carries the complete assistant_message content.
+    const finalText = edits.length > 0 ? edits[edits.length - 1]?.text : posts[0]?.text;
+    expect(finalText).toBe('Hello, world!');
+
+    // No foreign-turn text ever reached Slack.
+    const allText = [...posts.map((p) => p.text), ...edits.map((e) => e.text)].join('\n');
+    expect(allText).not.toContain('SHOULD NOT APPEAR');
+    expect(allText).not.toContain('ALSO NOT THIS');
+  });
+
+  it('posts a "(no output)" placeholder when a turn produces nothing', async () => {
+    vi.useFakeTimers();
+    const log = new FakeLog();
+    const { client, posts } = fakeClient();
+    const session = {
+      log,
+      runTurn() {
+        return (async function* () {
+          // no events
+        })();
+      },
+    } as unknown as Session;
+
+    const promise = runSlackTurn(
+      { session, client, editFrameMs: 1000 },
+      { channel: 'C1', threadTs: '1.2', text: 'hi', controller: new AbortController(), turnId: 't' },
+    );
+    await vi.runAllTimersAsync();
+    await promise;
+    vi.useRealTimers();
+
+    expect(posts).toHaveLength(1);
+    expect(posts[0]?.text).toContain('no output');
+  });
+});

package/src/channel/turn-runner.ts

@@ -0,0 +1,107 @@
+import type { newTurnId } from '@moxxy/core';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { FramePump, PlainTurnRenderer, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import type { SlackClient } from './slack-client.js';
+
+export interface TurnRunnerLogger {
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface RunSlackTurnDeps {
+  readonly session: Session;
+  readonly client: SlackClient;
+  readonly editFrameMs: number;
+  readonly logger?: TurnRunnerLogger;
+}
+
+export interface RunSlackTurnOptions {
+  /** Channel the triggering event arrived in. */
+  readonly channel: string;
+  /** Thread root for the reply: `event.thread_ts ?? event.ts`. */
+  readonly threadTs: string;
+  readonly text: string;
+  readonly model?: string;
+  readonly controller: AbortController;
+  /** Pre-minted turn id; the channel records it as an own-turn id. */
+  readonly turnId: ReturnType<typeof newTurnId>;
+}
+
+/**
+ * Drive a single Slack turn end-to-end: subscribe the frame pump to THIS turn's
+ * events (filtered by turnId — `session.log` fans out to every listener, so a
+ * concurrent turn on the same Session would otherwise stream into this thread,
+ * AGENTS.md invariant #8), run the turn through `runTurn`, flush the final
+ * frame, and unwind in `finally`.
+ *
+ * The streaming loop is `@moxxy/channel-kit`'s {@link FramePump} ("post once
+ * via `chat.postMessage`, then edit THAT message via `chat.update`, throttled
+ * to `editFrameMs`") over a {@link PlainTurnRenderer} snapshot; only the Slack
+ * Web-API calls live here. The turnId is minted by the caller so the channel
+ * can also record it as an own-turn id (it filters foreign-turn mirroring on
+ * those).
+ */
+export async function runSlackTurn(
+  deps: RunSlackTurnDeps,
+  opts: RunSlackTurnOptions,
+): Promise<void> {
+  const { session, client, editFrameMs, logger } = deps;
+  const { channel, threadTs, text, model, controller, turnId } = opts;
+
+  const renderer = new PlainTurnRenderer();
+  const pump = new FramePump<string>({
+    editFrameMs,
+    frame: () => renderer.snapshot(),
+    // Guarantee at least one message even when the turn produced no text.
+    emptyFinalText: '_(no output)_',
+    sink: {
+      send: async (t) => {
+        try {
+          const res = await client.postMessage({ channel, text: t, threadTs });
+          return res.ts;
+        } catch (err) {
+          logger?.warn?.('slack chat.postMessage failed', { err: String(err) });
+          return null;
+        }
+      },
+      edit: async (ts, t) => {
+        try {
+          await client.updateMessage({ channel, ts, text: t });
+        } catch (err) {
+          logger?.warn?.('slack chat.update failed', { err: String(err) });
+        }
+      },
+    },
+  });
+
+  const unsubscribe = subscribeTurn(session, turnId, (event) => {
+    if (renderer.accept(event)) pump.scheduleEdit();
+  });
+
+  try {
+    await driveTurn(session, {
+      turnId,
+      prompt: text,
+      ...(model ? { model } : {}),
+      signal: controller.signal,
+    });
+    await pump.flush(true);
+  } catch (err) {
+    logger?.warn?.('slack turn failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    // Surface the failure into the thread rather than leaving a dangling
+    // placeholder. Errors from this send are swallowed (best-effort).
+    try {
+      await client.postMessage({
+        channel,
+        threadTs,
+        text: `Turn failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    } catch {
+      /* ignore */
+    }
+  } finally {
+    unsubscribe();
+    pump.dispose();
+  }
+}