@dreki-gg/pi-slack 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @dreki-gg/pi-slack
+
+Slack read tools for [pi](https://github.com/earendil-works/pi-coding-agent) — messages, threads, channels, search, and file/image downloads.
+
+Uses [Effect](https://effect.website) for the Slack client layer (typed errors, retries, rate limit handling).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `slack_list_channels` | List channels the bot has access to |
+| `slack_read_messages` | Read message history from a channel |
+| `slack_read_thread` | Read replies in a thread |
+| `slack_search` | Full-text search across workspace (requires user token) |
+| `slack_download_file` | Download a shared file/image to temp directory |
+
+## Setup
+
+### 1. Create a Slack App
+
+Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**. Give it a name (e.g. `pi-context`) and select your workspace.
+
+### 2. Add OAuth scopes
+
+In the left sidebar → **OAuth & Permissions** → scroll to **Scopes**.
+
+**Bot Token Scopes** (for `SLACK_BOT_TOKEN`):
+
+| Scope | Enables |
+|-------|---------|
+| `channels:read` | list public channels |
+| `channels:history` | read public channel messages |
+| `groups:read` | list private channels |
+| `groups:history` | read private channel messages |
+| `im:history` | read DMs |
+| `files:read` | file info + image/file downloads |
+
+**User Token Scopes** (for `SLACK_USER_TOKEN` — only needed for `slack_search`):
+
+| Scope | Enables |
+|-------|---------|
+| `search:read` | `slack_search` tool |
+
+> `search.messages` is only available with a **user** token — bots cannot search. Skip the user token entirely if you don't need search.
+
+### 3. Install to workspace
+
+Still on **OAuth & Permissions** → click **Install to Workspace** at the top → authorize. (If your workspace requires admin approval, an admin must approve it.)
+
+### 4. Copy the tokens
+
+After installing, the same page shows:
+
+- **Bot User OAuth Token** — starts with `xoxb-` → your `SLACK_BOT_TOKEN`
+- **User OAuth Token** — starts with `xoxp-` → your `SLACK_USER_TOKEN`
+
+```bash
+export SLACK_BOT_TOKEN=xoxb-...
+export SLACK_USER_TOKEN=xoxp-...  # Optional, needed for slack_search
+```
+
+### 5. Invite the bot to channels
+
+A bot token can only read channels the bot is **a member of**. In each Slack channel you want the agent to read, type:
+
+```
+/invite @your-app-name
+```
+
+Otherwise `slack_read_messages` returns `not_in_channel`.
+
+### 6. Optional project config
+
+Create `.pi/slack.json` in your project to set a default channel and message limit:
+
+```json
+{
+  "defaultChannel": "C0123ABC456",
+  "messageLimit": 50
+}
+```
+
+## Finding channel IDs
+
+Open a channel in Slack → click the channel name → scroll to the bottom of the popup; the ID (`C0123ABC456`) is shown there. Or run `slack_list_channels` once the bot is installed to list channels with their IDs.
+
+## Checking status
+
+Run `/slack` in pi to see token detection and project config status.
+
+## Install
+
+```bash
+pi install @dreki-gg/pi-slack
+```

package/extensions/slack/client/SlackClient.ts

@@ -0,0 +1,15 @@
+import { Layer } from 'effect';
+import type { SlackCredentials } from '../config.js';
+import { SlackConfig, SlackHttpLive } from './http.js';
+
+/**
+ * Builds the runtime layer that the Slack Effect programs require:
+ * the credentials (SlackConfig) plus the retrying HttpClient (SlackHttpLive).
+ *
+ * Used at the `Effect.runPromise` boundary in the tool execute handlers.
+ * The individual operations (listChannels, readMessages, searchMessages,
+ * downloadFile, …) are imported directly from their domain modules.
+ */
+export function makeRuntimeLayer(credentials: SlackCredentials) {
+  return Layer.merge(Layer.succeed(SlackConfig, credentials), SlackHttpLive);
+}

package/extensions/slack/client/channels.ts

@@ -0,0 +1,182 @@
+import { Effect } from 'effect';
+import { slackGet } from './http.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SlackChannel {
+  id: string;
+  name: string;
+  isPrivate: boolean;
+  isMember: boolean;
+  topic: string;
+  purpose: string;
+  numMembers: number;
+}
+
+export interface SlackMessage {
+  user: string;
+  text: string;
+  ts: string;
+  threadTs?: string;
+  replyCount?: number;
+  reactions?: Array<{ name: string; count: number }>;
+  files?: Array<{ id: string; name: string; mimetype: string; urlPrivate: string }>;
+}
+
+export interface ListChannelsResult {
+  channels: SlackChannel[];
+  cursor?: string;
+}
+
+export interface ReadMessagesResult {
+  messages: SlackMessage[];
+  hasMore: boolean;
+  cursor?: string;
+}
+
+// ---------------------------------------------------------------------------
+// API response shapes (raw from Slack)
+// ---------------------------------------------------------------------------
+
+interface RawChannel {
+  id: string;
+  name: string;
+  is_private: boolean;
+  is_member: boolean;
+  topic?: { value: string };
+  purpose?: { value: string };
+  num_members: number;
+}
+
+interface RawMessage {
+  user?: string;
+  text?: string;
+  ts: string;
+  thread_ts?: string;
+  reply_count?: number;
+  reactions?: Array<{ name: string; count: number }>;
+  files?: Array<{
+    id: string;
+    name: string;
+    mimetype: string;
+    url_private: string;
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// Normalizers
+// ---------------------------------------------------------------------------
+
+function normalizeChannel(raw: RawChannel): SlackChannel {
+  return {
+    id: raw.id,
+    name: raw.name,
+    isPrivate: raw.is_private,
+    isMember: raw.is_member,
+    topic: raw.topic?.value ?? '',
+    purpose: raw.purpose?.value ?? '',
+    numMembers: raw.num_members,
+  };
+}
+
+function normalizeMessage(raw: RawMessage): SlackMessage {
+  const msg: SlackMessage = {
+    user: raw.user ?? 'unknown',
+    text: raw.text ?? '',
+    ts: raw.ts,
+  };
+  if (raw.thread_ts) msg.threadTs = raw.thread_ts;
+  if (raw.reply_count) msg.replyCount = raw.reply_count;
+  if (raw.reactions) msg.reactions = raw.reactions;
+  if (raw.files) {
+    msg.files = raw.files.map((f) => ({
+      id: f.id,
+      name: f.name,
+      mimetype: f.mimetype,
+      urlPrivate: f.url_private,
+    }));
+  }
+  return msg;
+}
+
+// ---------------------------------------------------------------------------
+// Effects
+// ---------------------------------------------------------------------------
+
+export function listChannels(params: { limit?: number; cursor?: string; types?: string }) {
+  return Effect.gen(function* () {
+    const resp = yield* slackGet<{
+      ok: true;
+      channels: RawChannel[];
+      response_metadata?: { next_cursor?: string };
+    }>('conversations.list', {
+      limit: params.limit ?? 100,
+      cursor: params.cursor,
+      types: params.types ?? 'public_channel,private_channel',
+      exclude_archived: true,
+    });
+
+    return {
+      channels: resp.channels.map(normalizeChannel),
+      cursor: resp.response_metadata?.next_cursor || undefined,
+    } satisfies ListChannelsResult;
+  });
+}
+
+export function readMessages(params: {
+  channel: string;
+  limit?: number;
+  oldest?: string;
+  latest?: string;
+  cursor?: string;
+}) {
+  return Effect.gen(function* () {
+    const resp = yield* slackGet<{
+      ok: true;
+      messages: RawMessage[];
+      has_more: boolean;
+      response_metadata?: { next_cursor?: string };
+    }>('conversations.history', {
+      channel: params.channel,
+      limit: params.limit ?? 50,
+      oldest: params.oldest,
+      latest: params.latest,
+      cursor: params.cursor,
+    });
+
+    return {
+      messages: resp.messages.map(normalizeMessage),
+      hasMore: resp.has_more,
+      cursor: resp.response_metadata?.next_cursor || undefined,
+    } satisfies ReadMessagesResult;
+  });
+}
+
+export function readThread(params: {
+  channel: string;
+  threadTs: string;
+  limit?: number;
+  cursor?: string;
+}) {
+  return Effect.gen(function* () {
+    const resp = yield* slackGet<{
+      ok: true;
+      messages: RawMessage[];
+      has_more: boolean;
+      response_metadata?: { next_cursor?: string };
+    }>('conversations.replies', {
+      channel: params.channel,
+      ts: params.threadTs,
+      limit: params.limit ?? 100,
+      cursor: params.cursor,
+    });
+
+    return {
+      messages: resp.messages.map(normalizeMessage),
+      hasMore: resp.has_more,
+      cursor: resp.response_metadata?.next_cursor || undefined,
+    } satisfies ReadMessagesResult;
+  });
+}

package/extensions/slack/client/errors.ts

@@ -0,0 +1,44 @@
+import { Data } from 'effect';
+
+/** Slack API returned an error response (ok: false). */
+export class SlackApiError extends Data.TaggedError('SlackApiError')<{
+  readonly method: string;
+  readonly code: string;
+  readonly detail?: string;
+}> {
+  get message(): string {
+    return `Slack API error [${this.method}]: ${this.code}${this.detail ? ` — ${this.detail}` : ''}`;
+  }
+}
+
+/** Missing or invalid authentication token. */
+export class SlackAuthError extends Data.TaggedError('SlackAuthError')<{
+  readonly reason: string;
+}> {
+  get message(): string {
+    return `Slack auth error: ${this.reason}`;
+  }
+}
+
+/** Rate limited by Slack — includes retry-after seconds when available. */
+export class SlackRateLimitError extends Data.TaggedError('SlackRateLimitError')<{
+  readonly method: string;
+  readonly retryAfter?: number;
+}> {
+  get message(): string {
+    return `Slack rate limited [${this.method}]${this.retryAfter ? ` — retry after ${this.retryAfter}s` : ''}`;
+  }
+}
+
+/** File download or processing failed. */
+export class SlackFileError extends Data.TaggedError('SlackFileError')<{
+  readonly fileId: string;
+  readonly reason: string;
+}> {
+  get message(): string {
+    return `Slack file error [${this.fileId}]: ${this.reason}`;
+  }
+}
+
+/** Union of all Slack client errors. */
+export type SlackError = SlackApiError | SlackAuthError | SlackRateLimitError | SlackFileError;

package/extensions/slack/client/files.ts

@@ -0,0 +1,121 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { Effect } from 'effect';
+import { slackGet, slackDownload } from './http.js';
+import { SlackFileError } from './errors.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SlackFileInfo {
+  id: string;
+  name: string;
+  title: string;
+  mimetype: string;
+  filetype: string;
+  size: number;
+  urlPrivate: string;
+  permalink: string;
+  isImage: boolean;
+  imageWidth?: number;
+  imageHeight?: number;
+}
+
+export interface DownloadedFile {
+  info: SlackFileInfo;
+  localPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// Raw Slack shapes
+// ---------------------------------------------------------------------------
+
+interface RawFile {
+  id: string;
+  name: string;
+  title: string;
+  mimetype: string;
+  filetype: string;
+  size: number;
+  url_private: string;
+  permalink: string;
+  original_w?: number;
+  original_h?: number;
+}
+
+const IMAGE_MIMETYPES = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+]);
+
+function normalizeFileInfo(raw: RawFile): SlackFileInfo {
+  const isImage = IMAGE_MIMETYPES.has(raw.mimetype);
+  const info: SlackFileInfo = {
+    id: raw.id,
+    name: raw.name,
+    title: raw.title,
+    mimetype: raw.mimetype,
+    filetype: raw.filetype,
+    size: raw.size,
+    urlPrivate: raw.url_private,
+    permalink: raw.permalink,
+    isImage,
+  };
+  if (isImage && raw.original_w) info.imageWidth = raw.original_w;
+  if (isImage && raw.original_h) info.imageHeight = raw.original_h;
+  return info;
+}
+
+// ---------------------------------------------------------------------------
+// Temp directory for downloads
+// ---------------------------------------------------------------------------
+
+const DOWNLOAD_DIR = join(tmpdir(), 'pi-slack-files');
+
+function ensureDownloadDir() {
+  return Effect.tryPromise({
+    try: () => mkdir(DOWNLOAD_DIR, { recursive: true }),
+    catch: (err) => new SlackFileError({ fileId: 'n/a', reason: `Cannot create temp dir: ${err}` }),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Effects
+// ---------------------------------------------------------------------------
+
+export function getFileInfo(fileId: string) {
+  return Effect.gen(function* () {
+    const resp = yield* slackGet<{ ok: true; file: RawFile }>('files.info', {
+      file: fileId,
+    });
+    return normalizeFileInfo(resp.file);
+  });
+}
+
+export function downloadFile(fileId: string) {
+  return Effect.gen(function* () {
+    yield* ensureDownloadDir();
+
+    const info = yield* getFileInfo(fileId);
+
+    const buffer = yield* slackDownload(info.urlPrivate).pipe(
+      Effect.mapError((err) => new SlackFileError({ fileId, reason: `Download failed: ${err}` })),
+    );
+
+    const ext = info.name.includes('.') ? '' : `.${info.filetype}`;
+    const filename = `${info.id}-${info.name}${ext}`;
+    const localPath = join(DOWNLOAD_DIR, filename);
+
+    yield* Effect.tryPromise({
+      try: () => writeFile(localPath, Buffer.from(buffer)),
+      catch: (err) => new SlackFileError({ fileId, reason: `Write failed: ${err}` }),
+    });
+
+    return { info, localPath } satisfies DownloadedFile;
+  });
+}

package/extensions/slack/client/http.ts

@@ -0,0 +1,133 @@
+import { FetchHttpClient, HttpClient } from '@effect/platform';
+import { Context, Effect, Layer, Schedule } from 'effect';
+import type { SlackCredentials } from '../config.js';
+import { SlackApiError, SlackAuthError, SlackRateLimitError } from './errors.js';
+
+// ---------------------------------------------------------------------------
+// SlackConfig service — provides credentials to the HTTP layer
+// ---------------------------------------------------------------------------
+
+export class SlackConfig extends Context.Tag('SlackConfig')<SlackConfig, SlackCredentials>() {}
+
+// ---------------------------------------------------------------------------
+// Slack-specific JSON response shape
+// ---------------------------------------------------------------------------
+
+interface SlackOkResponse {
+  ok: true;
+  [key: string]: unknown;
+}
+
+interface SlackErrorResponse {
+  ok: false;
+  error: string;
+}
+
+type SlackResponse = SlackOkResponse | SlackErrorResponse;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SLACK_BASE_URL = 'https://slack.com/api';
+
+/**
+ * Make a GET request to a Slack Web API method, returning typed JSON.
+ * Handles auth injection, rate limiting (with retry), and error mapping.
+ */
+export function slackGet<T extends SlackOkResponse>(
+  method: string,
+  params: Record<string, string | number | boolean | undefined>,
+  options?: { useUserToken?: boolean },
+) {
+  return Effect.scoped(
+    Effect.gen(function* () {
+      const config = yield* SlackConfig;
+      const client = yield* HttpClient.HttpClient;
+
+      const token = options?.useUserToken ? config.userToken : config.botToken;
+      if (!token) {
+        return yield* new SlackAuthError({
+          reason: options?.useUserToken
+            ? 'SLACK_USER_TOKEN is required for this operation but not set'
+            : 'SLACK_BOT_TOKEN is required but not set',
+        });
+      }
+
+      // Build URL with query params
+      const url = new URL(`${SLACK_BASE_URL}/${method}`);
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) url.searchParams.set(key, String(value));
+      }
+
+      const response = yield* client.get(url.toString(), {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      // Handle rate limiting
+      if (response.status === 429) {
+        const retryAfter = Number(response.headers['retry-after']) || undefined;
+        return yield* new SlackRateLimitError({ method, retryAfter });
+      }
+
+      const json = (yield* response.json) as SlackResponse;
+
+      if (!json.ok) {
+        return yield* new SlackApiError({
+          method,
+          code: (json as SlackErrorResponse).error,
+        });
+      }
+
+      return json as T;
+    }),
+  );
+}
+
+/**
+ * Download a file from Slack using bot token authentication.
+ * Returns the raw ArrayBuffer.
+ */
+export function slackDownload(url: string) {
+  return Effect.scoped(
+    Effect.gen(function* () {
+      const config = yield* SlackConfig;
+      const client = yield* HttpClient.HttpClient;
+
+      if (!config.botToken) {
+        return yield* new SlackAuthError({
+          reason: 'SLACK_BOT_TOKEN is required for file downloads',
+        });
+      }
+
+      const response = yield* client.get(url, {
+        headers: { Authorization: `Bearer ${config.botToken}` },
+      });
+
+      if (response.status !== 200) {
+        return yield* Effect.fail(new Error(`Download failed with status ${response.status}`));
+      }
+
+      return yield* response.arrayBuffer;
+    }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Retry policy — respects rate limit backoff
+// ---------------------------------------------------------------------------
+
+const retryPolicy = Schedule.intersect(Schedule.recurs(3), Schedule.exponential('1 second'));
+
+// ---------------------------------------------------------------------------
+// Layers
+// ---------------------------------------------------------------------------
+
+/** FetchHttpClient with retry policy for Slack rate limits. */
+export const SlackHttpLive = FetchHttpClient.layer.pipe(
+  Layer.map((context) => {
+    const client = Context.get(context, HttpClient.HttpClient);
+    const retried = client.pipe(HttpClient.retry(retryPolicy));
+    return Context.make(HttpClient.HttpClient, retried);
+  }),
+);

package/extensions/slack/client/search.ts

@@ -0,0 +1,78 @@
+import { Effect } from 'effect';
+import { slackGet } from './http.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SearchMatch {
+  channel: { id: string; name: string };
+  user: string;
+  text: string;
+  ts: string;
+  permalink: string;
+}
+
+export interface SearchResult {
+  matches: SearchMatch[];
+  total: number;
+  cursor?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Raw Slack shapes
+// ---------------------------------------------------------------------------
+
+interface RawSearchMatch {
+  channel: { id: string; name: string };
+  username?: string;
+  user?: string;
+  text: string;
+  ts: string;
+  permalink: string;
+}
+
+// ---------------------------------------------------------------------------
+// Effect
+// ---------------------------------------------------------------------------
+
+export function searchMessages(params: {
+  query: string;
+  count?: number;
+  sort?: 'score' | 'timestamp';
+  sortDir?: 'asc' | 'desc';
+  cursor?: string;
+}) {
+  return Effect.gen(function* () {
+    const resp = yield* slackGet<{
+      ok: true;
+      messages: {
+        matches: RawSearchMatch[];
+        total: number;
+        pagination?: { next_cursor?: string };
+      };
+    }>(
+      'search.messages',
+      {
+        query: params.query,
+        count: params.count ?? 20,
+        sort: params.sort ?? 'timestamp',
+        sort_dir: params.sortDir ?? 'desc',
+        cursor: params.cursor,
+      },
+      { useUserToken: true },
+    );
+
+    return {
+      matches: resp.messages.matches.map((m) => ({
+        channel: m.channel,
+        user: m.username ?? m.user ?? 'unknown',
+        text: m.text,
+        ts: m.ts,
+        permalink: m.permalink,
+      })),
+      total: resp.messages.total,
+      cursor: resp.messages.pagination?.next_cursor || undefined,
+    } satisfies SearchResult;
+  });
+}

package/extensions/slack/config.ts

@@ -0,0 +1,96 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Project config (.pi/slack.json)
+// ---------------------------------------------------------------------------
+
+export interface SlackProjectConfig {
+  /** Default channel ID to read from. */
+  defaultChannel?: string;
+  /** Max messages per request (default 50). */
+  messageLimit: number;
+}
+
+interface RawConfig {
+  defaultChannel?: unknown;
+  messageLimit?: unknown;
+}
+
+const DEFAULT_CONFIG: SlackProjectConfig = {
+  messageLimit: 50,
+};
+
+export async function loadProjectConfig(cwd: string): Promise<SlackProjectConfig> {
+  const configPath = join(cwd, '.pi', 'slack.json');
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, 'utf-8');
+  } catch (err: unknown) {
+    if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ...DEFAULT_CONFIG };
+    }
+    throw new Error(`Failed to read ${configPath}: ${(err as Error).message}`);
+  }
+
+  let parsed: RawConfig;
+  try {
+    parsed = JSON.parse(raw) as RawConfig;
+  } catch {
+    throw new Error(`Invalid JSON in ${configPath}`);
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${configPath} must be a JSON object`);
+  }
+
+  return validateConfig(parsed, configPath);
+}
+
+function validateConfig(raw: RawConfig, configPath: string): SlackProjectConfig {
+  const config: SlackProjectConfig = { ...DEFAULT_CONFIG };
+
+  if (raw.defaultChannel !== undefined) {
+    if (typeof raw.defaultChannel !== 'string') {
+      throw new Error(`${configPath}: "defaultChannel" must be a string`);
+    }
+    config.defaultChannel = raw.defaultChannel;
+  }
+
+  if (raw.messageLimit !== undefined) {
+    if (typeof raw.messageLimit !== 'number' || raw.messageLimit < 1 || raw.messageLimit > 999) {
+      throw new Error(`${configPath}: "messageLimit" must be a number between 1 and 999`);
+    }
+    config.messageLimit = raw.messageLimit;
+  }
+
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Credentials from environment
+// ---------------------------------------------------------------------------
+
+export interface SlackCredentials {
+  botToken: string;
+  userToken?: string;
+}
+
+export function getCredentials(): SlackCredentials | null {
+  const botToken = process.env.SLACK_BOT_TOKEN;
+  if (!botToken) return null;
+
+  const userToken = process.env.SLACK_USER_TOKEN || undefined;
+  return { botToken, userToken };
+}
+
+export function getCredentialStatus(): {
+  hasBotToken: boolean;
+  hasUserToken: boolean;
+} {
+  return {
+    hasBotToken: Boolean(process.env.SLACK_BOT_TOKEN),
+    hasUserToken: Boolean(process.env.SLACK_USER_TOKEN),
+  };
+}

package/extensions/slack/format.ts

@@ -0,0 +1,107 @@
+import type { SlackChannel, SlackMessage, ReadMessagesResult } from './client/channels.js';
+import type { SearchResult } from './client/search.js';
+import type { DownloadedFile, SlackFileInfo } from './client/files.js';
+
+// ---------------------------------------------------------------------------
+// Channels
+// ---------------------------------------------------------------------------
+
+export function formatChannelList(channels: SlackChannel[]): string {
+  if (channels.length === 0) return 'No channels found.';
+
+  const lines = channels.map((ch) => {
+    const visibility = ch.isPrivate ? '🔒' : '#';
+    const members = `${ch.numMembers} members`;
+    const topic = ch.topic ? ` — ${ch.topic}` : '';
+    return `${visibility} **${ch.name}** (${ch.id}) · ${members}${topic}`;
+  });
+
+  return `**Channels** (${channels.length}):\n\n${lines.join('\n')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+
+function formatTimestamp(ts: string): string {
+  const date = new Date(Number(ts) * 1000);
+  return date
+    .toISOString()
+    .replace('T', ' ')
+    .replace(/\.\d{3}Z$/, ' UTC');
+}
+
+function formatSingleMessage(msg: SlackMessage): string {
+  const time = formatTimestamp(msg.ts);
+  const thread = msg.replyCount ? ` [${msg.replyCount} replies]` : '';
+  const reactions = msg.reactions
+    ? ` ${msg.reactions.map((r) => `:${r.name}: ${r.count}`).join(' ')}`
+    : '';
+  const files = msg.files ? `\n  📎 ${msg.files.map((f) => `${f.name} (${f.id})`).join(', ')}` : '';
+
+  return `[${time}] **${msg.user}**${thread}: ${msg.text}${reactions}${files}`;
+}
+
+export function formatMessages(result: ReadMessagesResult, channelId: string): string {
+  if (result.messages.length === 0) return `No messages found in channel ${channelId}.`;
+
+  const header = `**Messages** in ${channelId} (${result.messages.length}${result.hasMore ? ', more available' : ''}):`;
+  const msgs = result.messages.map(formatSingleMessage);
+
+  return `${header}\n\n${msgs.join('\n\n')}`;
+}
+
+export function formatThread(
+  result: ReadMessagesResult,
+  channelId: string,
+  threadTs: string,
+): string {
+  if (result.messages.length === 0) return `No replies found in thread ${threadTs}.`;
+
+  const header = `**Thread** ${threadTs} in ${channelId} (${result.messages.length} messages${result.hasMore ? ', more available' : ''}):`;
+  const msgs = result.messages.map(formatSingleMessage);
+
+  return `${header}\n\n${msgs.join('\n\n')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+
+export function formatSearchResults(result: SearchResult, query: string): string {
+  if (result.matches.length === 0) return `No results found for "${query}".`;
+
+  const header = `**Search results** for "${query}" (${result.matches.length} of ${result.total} total):`;
+  const matches = result.matches.map((m) => {
+    const time = formatTimestamp(m.ts);
+    return `[${time}] **${m.user}** in #${m.channel.name}: ${m.text}\n  🔗 ${m.permalink}`;
+  });
+
+  return `${header}\n\n${matches.join('\n\n')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Files
+// ---------------------------------------------------------------------------
+
+export function formatFileInfo(info: SlackFileInfo): string {
+  const size = formatFileSize(info.size);
+  const dims = info.isImage && info.imageWidth ? ` · ${info.imageWidth}×${info.imageHeight}` : '';
+
+  return `📎 **${info.title}** (${info.name})\n  Type: ${info.mimetype} · Size: ${size}${dims}\n  ID: ${info.id}\n  🔗 ${info.permalink}`;
+}
+
+export function formatDownloadedFile(result: DownloadedFile): string {
+  const info = formatFileInfo(result.info);
+  const hint = result.info.isImage
+    ? `\n\n💡 This is an image file. Use the \`read\` tool to view it:\n  \`read ${result.localPath}\``
+    : `\n\n📁 Downloaded to: ${result.localPath}`;
+
+  return `${info}${hint}`;
+}
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/extensions/slack/index.ts

@@ -0,0 +1,329 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Effect } from 'effect';
+import type { HttpClient } from '@effect/platform';
+import type { SlackConfig } from './client/http.js';
+import {
+  type SlackProjectConfig,
+  type SlackCredentials,
+  getCredentials,
+  getCredentialStatus,
+  loadProjectConfig,
+} from './config.js';
+import { makeRuntimeLayer } from './client/SlackClient.js';
+import { listChannels } from './client/channels.js';
+import { readMessages, readThread } from './client/channels.js';
+import { searchMessages } from './client/search.js';
+import { downloadFile } from './client/files.js';
+import {
+  formatChannelList,
+  formatMessages,
+  formatThread,
+  formatSearchResults,
+  formatDownloadedFile,
+} from './format.js';
+import {
+  TOOL_GUIDELINES,
+  listChannelsParams,
+  readMessagesParams,
+  readThreadParams,
+  searchParams,
+  downloadFileParams,
+} from './tools.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function textResult(text: string, details?: Record<string, unknown>) {
+  return {
+    content: [{ type: 'text' as const, text }],
+    details: (details ?? {}) as Record<string, unknown>,
+  };
+}
+
+function errorResult(text: string, details?: Record<string, unknown>) {
+  return {
+    content: [{ type: 'text' as const, text }],
+    details: (details ?? {}) as Record<string, unknown>,
+    isError: true,
+  };
+}
+
+function missingCredentials(which: 'bot' | 'user') {
+  const envVar = which === 'bot' ? 'SLACK_BOT_TOKEN' : 'SLACK_USER_TOKEN';
+  return errorResult(
+    `❌ Missing ${envVar}.\n\nSet this environment variable to enable this Slack tool.`,
+    { error: 'missing_credentials', missing: [envVar] },
+  );
+}
+
+/**
+ * Runs an Effect program with the Slack runtime layer.
+ * This is the boundary between Effect and plain-TS tool handlers.
+ */
+type SlackRuntime = SlackConfig | HttpClient.HttpClient;
+
+function runSlack<A, E>(
+  credentials: SlackCredentials,
+  program: Effect.Effect<A, E, SlackRuntime>,
+): Promise<A> {
+  const layer = makeRuntimeLayer(credentials);
+  return Effect.runPromise(program.pipe(Effect.provide(layer)));
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+export default function slackExtension(pi: ExtensionAPI) {
+  let projectConfig: SlackProjectConfig | null = null;
+
+  pi.on('session_start', async (_event, ctx) => {
+    try {
+      projectConfig = await loadProjectConfig(ctx.cwd);
+    } catch (err) {
+      ctx.ui.notify(`Slack config error: ${(err as Error).message}`, 'warning');
+      projectConfig = null;
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // slack_list_channels
+  // -------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: 'slack_list_channels',
+    label: 'Slack List Channels',
+    description: 'List Slack channels the bot has access to.',
+    promptSnippet: 'List available Slack channels',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: listChannelsParams,
+
+    async execute(
+      _toolCallId: string,
+      params: { limit?: number; cursor?: string; types?: string },
+    ) {
+      const creds = getCredentials();
+      if (!creds) return missingCredentials('bot');
+
+      try {
+        const result = await runSlack(creds, listChannels(params));
+        return textResult(formatChannelList(result.channels), {
+          count: result.channels.length,
+          cursor: result.cursor,
+        });
+      } catch (err) {
+        return errorResult(`❌ ${(err as Error).message}`);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // slack_read_messages
+  // -------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: 'slack_read_messages',
+    label: 'Slack Read Messages',
+    description:
+      'Read message history from a Slack channel. Returns messages with timestamps, users, reactions, and file attachments.',
+    promptSnippet: 'Read messages from a Slack channel',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: readMessagesParams,
+
+    async execute(
+      _toolCallId: string,
+      params: {
+        channel: string;
+        limit?: number;
+        oldest?: string;
+        latest?: string;
+        cursor?: string;
+      },
+    ) {
+      const creds = getCredentials();
+      if (!creds) return missingCredentials('bot');
+
+      const limit = params.limit ?? projectConfig?.messageLimit ?? 50;
+
+      try {
+        const result = await runSlack(creds, readMessages({ ...params, limit }));
+        return textResult(formatMessages(result, params.channel), {
+          count: result.messages.length,
+          hasMore: result.hasMore,
+          cursor: result.cursor,
+        });
+      } catch (err) {
+        return errorResult(`❌ ${(err as Error).message}`);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // slack_read_thread
+  // -------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: 'slack_read_thread',
+    label: 'Slack Read Thread',
+    description:
+      'Read all replies in a Slack thread. Provide the channel ID and the thread parent timestamp.',
+    promptSnippet: 'Read replies in a Slack thread',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: readThreadParams,
+
+    async execute(
+      _toolCallId: string,
+      params: {
+        channel: string;
+        thread_ts: string;
+        limit?: number;
+        cursor?: string;
+      },
+    ) {
+      const creds = getCredentials();
+      if (!creds) return missingCredentials('bot');
+
+      try {
+        const result = await runSlack(
+          creds,
+          readThread({
+            channel: params.channel,
+            threadTs: params.thread_ts,
+            limit: params.limit,
+            cursor: params.cursor,
+          }),
+        );
+        return textResult(formatThread(result, params.channel, params.thread_ts), {
+          count: result.messages.length,
+          hasMore: result.hasMore,
+          cursor: result.cursor,
+        });
+      } catch (err) {
+        return errorResult(`❌ ${(err as Error).message}`);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // slack_search
+  // -------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: 'slack_search',
+    label: 'Slack Search',
+    description:
+      'Full-text search across Slack messages. Supports Slack search syntax (in:#channel, from:@user, has:link). Requires SLACK_USER_TOKEN.',
+    promptSnippet: 'Search Slack messages across the workspace',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: searchParams,
+
+    async execute(
+      _toolCallId: string,
+      params: {
+        query: string;
+        count?: number;
+        sort?: 'score' | 'timestamp';
+        sort_dir?: 'asc' | 'desc';
+        cursor?: string;
+      },
+    ) {
+      const creds = getCredentials();
+      if (!creds) return missingCredentials('bot');
+      if (!creds.userToken) return missingCredentials('user');
+
+      try {
+        const result = await runSlack(
+          creds,
+          searchMessages({
+            query: params.query,
+            count: params.count,
+            sort: params.sort,
+            sortDir: params.sort_dir,
+            cursor: params.cursor,
+          }),
+        );
+        return textResult(formatSearchResults(result, params.query), {
+          total: result.total,
+          count: result.matches.length,
+          cursor: result.cursor,
+        });
+      } catch (err) {
+        return errorResult(`❌ ${(err as Error).message}`);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // slack_download_file
+  // -------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: 'slack_download_file',
+    label: 'Slack Download File',
+    description:
+      'Download a file or image shared in Slack. Saves to a temp directory and returns the local path. Use `read` to view downloaded images.',
+    promptSnippet: 'Download a Slack file/image to local temp directory',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: downloadFileParams,
+
+    async execute(_toolCallId: string, params: { file_id: string }) {
+      const creds = getCredentials();
+      if (!creds) return missingCredentials('bot');
+
+      try {
+        const result = await runSlack(creds, downloadFile(params.file_id));
+        return textResult(formatDownloadedFile(result), {
+          fileId: result.info.id,
+          localPath: result.localPath,
+          isImage: result.info.isImage,
+          mimetype: result.info.mimetype,
+          size: result.info.size,
+        });
+      } catch (err) {
+        return errorResult(`❌ ${(err as Error).message}`);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // /slack command — status check
+  // -------------------------------------------------------------------------
+
+  pi.registerCommand('slack', {
+    description: 'Show Slack extension configuration and connection status',
+    handler: async (
+      _args: string,
+      ctx: {
+        cwd: string;
+        hasUI: boolean;
+        ui: { notify(message: string, level: 'info' | 'warning' | 'error'): void };
+      },
+    ) => {
+      const credStatus = getCredentialStatus();
+      const config = projectConfig ?? (await loadProjectConfig(ctx.cwd).catch(() => null));
+
+      const lines: string[] = ['Slack Extension Status', ''];
+
+      lines.push(
+        `Bot Token: ${credStatus.hasBotToken ? '✅ Set' : '❌ Missing (SLACK_BOT_TOKEN)'}`,
+      );
+      lines.push(
+        `User Token: ${credStatus.hasUserToken ? '✅ Set' : '⚠️ Missing (SLACK_USER_TOKEN) — search disabled'}`,
+      );
+      lines.push('');
+
+      if (config) {
+        lines.push('Project Config (.pi/slack.json):');
+        lines.push(`  Default channel: ${config.defaultChannel ?? '(not set)'}`);
+        lines.push(`  Message limit: ${config.messageLimit}`);
+      } else {
+        lines.push('No .pi/slack.json found — using defaults.');
+      }
+
+      if (ctx.hasUI) {
+        ctx.ui.notify(lines.join('\n'), 'info');
+      }
+    },
+  });
+}

package/extensions/slack/tools.ts

@@ -0,0 +1,115 @@
+import { Type } from 'typebox';
+import { StringEnum } from '@earendil-works/pi-ai';
+
+// ---------------------------------------------------------------------------
+// Prompt guidelines injected into the system prompt
+// ---------------------------------------------------------------------------
+
+export const TOOL_GUIDELINES = [
+  'Use `slack_list_channels` to discover available Slack channels before reading messages.',
+  'Use `slack_read_messages` to read recent messages from a specific channel. Provide a channel ID (starts with C).',
+  'Use `slack_read_thread` to read all replies in a thread. You need both the channel ID and the thread timestamp (thread_ts).',
+  'Use `slack_search` for full-text search across the workspace. Requires SLACK_USER_TOKEN to be set.',
+  'Use `slack_download_file` to download images or files shared in Slack. The tool saves files to a temp directory and returns the path — use `read` to view images.',
+  'When messages reference files or images (shown with 📎), download them with `slack_download_file` using the file ID to get visual context.',
+  'Channel IDs look like C0123ABC456. Thread timestamps look like 1512085950.000216.',
+];
+
+// ---------------------------------------------------------------------------
+// Parameter schemas
+// ---------------------------------------------------------------------------
+
+export const listChannelsParams = Type.Object({
+  limit: Type.Optional(
+    Type.Number({
+      description: 'Max channels to return (1-200). Default 100.',
+      minimum: 1,
+      maximum: 200,
+    }),
+  ),
+  cursor: Type.Optional(
+    Type.String({ description: 'Pagination cursor from a previous response.' }),
+  ),
+  types: Type.Optional(
+    Type.String({
+      description: 'Comma-separated channel types. Default "public_channel,private_channel".',
+    }),
+  ),
+});
+
+export const readMessagesParams = Type.Object({
+  channel: Type.String({
+    description: 'Channel ID (e.g. C0123ABC456).',
+  }),
+  limit: Type.Optional(
+    Type.Number({
+      description: 'Max messages to return (1-100). Default from config or 50.',
+      minimum: 1,
+      maximum: 100,
+    }),
+  ),
+  oldest: Type.Optional(
+    Type.String({
+      description: 'Only messages after this Unix timestamp.',
+    }),
+  ),
+  latest: Type.Optional(
+    Type.String({
+      description: 'Only messages before this Unix timestamp.',
+    }),
+  ),
+  cursor: Type.Optional(
+    Type.String({ description: 'Pagination cursor from a previous response.' }),
+  ),
+});
+
+export const readThreadParams = Type.Object({
+  channel: Type.String({
+    description: 'Channel ID where the thread lives.',
+  }),
+  thread_ts: Type.String({
+    description: 'Timestamp of the parent message (thread_ts).',
+  }),
+  limit: Type.Optional(
+    Type.Number({
+      description: 'Max replies to return (1-200). Default 100.',
+      minimum: 1,
+      maximum: 200,
+    }),
+  ),
+  cursor: Type.Optional(
+    Type.String({ description: 'Pagination cursor from a previous response.' }),
+  ),
+});
+
+const SORT_ENUM = ['score', 'timestamp'] as const;
+const SORT_DIR_ENUM = ['asc', 'desc'] as const;
+
+export const searchParams = Type.Object({
+  query: Type.String({
+    description:
+      'Search query. Supports Slack search syntax (in:#channel, from:@user, has:link, etc.).',
+  }),
+  count: Type.Optional(
+    Type.Number({
+      description: 'Number of results (1-100). Default 20.',
+      minimum: 1,
+      maximum: 100,
+    }),
+  ),
+  sort: Type.Optional(
+    StringEnum(SORT_ENUM, { description: 'Sort by "score" or "timestamp". Default "timestamp".' }),
+  ),
+  sort_dir: Type.Optional(
+    StringEnum(SORT_DIR_ENUM, { description: 'Sort direction. Default "desc".' }),
+  ),
+  cursor: Type.Optional(
+    Type.String({ description: 'Pagination cursor from a previous response.' }),
+  ),
+});
+
+export const downloadFileParams = Type.Object({
+  file_id: Type.String({
+    description: 'Slack file ID to download (e.g. F0123ABC456).',
+  }),
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@dreki-gg/pi-slack",
+  "version": "0.1.0",
+  "description": "Slack read tools for pi — messages, threads, channels, search, and file/image downloads with Effect-powered client",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "slack",
+    "messages",
+    "images"
+  ],
+  "author": "Juan Albarran <jalbarrandev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreki-gg/pi-extensions",
+    "directory": "packages/slack"
+  },
+  "type": "module",
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "oxlint extensions test",
+    "format": "oxfmt --write extensions test",
+    "format:check": "oxfmt --check extensions test"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/slack"
+    ]
+  },
+  "dependencies": {
+    "effect": "^3.16.0",
+    "@effect/platform": "^0.78.0"
+  },
+  "devDependencies": {
+    "@types/node": "24",
+    "bun-types": "^1.3.14",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "typescript": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}