@kolisachint/hoobot 0.0.4 → 0.0.6

package/.env.example

@@ -1,25 +1,35 @@
 # Copy to .env and fill in. Never commit .env.
 
-# Developer portal → your app → Bot → Reset Token
+# Set Discord, Slack, or both. Each runs when its token(s) are set.
+
+# Discord: developer portal → your app → Bot → Reset Token
 DISCORD_TOKEN=
 
-# Comma-separated Discord user IDs allowed to use the bot.
+# Slack (Socket Mode, no public URL needed). See README "Slack setup".
+# Bot token: api.slack.com/apps → your app → OAuth & Permissions (xoxb-...)
+SLACK_BOT_TOKEN=
+# App-level token with connections:write: Basic Information → App-Level Tokens (xapp-...)
+SLACK_APP_TOKEN=
+
+# Comma-separated user IDs allowed to use the bot: Discord IDs (digits)
+# and Slack member IDs (U0123ABCD), mixed in one list.
 # Required: the bot refuses to start without it.
 ALLOWED_USER_IDS=758289752645959720
 
-# Only answer in the Hoo server.
+# Only answer in the Hoo server (Discord only).
 GUILD_ID=1554149385623838922
 
-# Optional: only answer in these channel IDs (comma-separated). Empty = all.
+# Optional: only answer in these channel IDs (comma-separated, Discord or Slack). Empty = all.
 CHANNEL_IDS=
 
 # Folder hoocode works in. Default: ./workspace
 HOO_WORKDIR=./workspace
 
 # Optional: give channels their own folder, one app-server each.
-# <channel id>=<folder>, comma-separated. Other channels use HOO_WORKDIR.
+# <channel id>=<folder>, comma-separated (Discord or Slack channel IDs).
+# Other channels use HOO_WORKDIR.
 # These channels are allowed even if CHANNEL_IDS is set. Not with APP_SERVER.
-#   WORKSPACES=123456789012345678=~/code/app,234567890123456789=~/code/site
+#   WORKSPACES=123456789012345678=~/code/app,C0123ABCD=~/code/site
 WORKSPACES=
 
 # Which Codex app-server to talk to. Empty = start `hoocode app-server`
@@ -37,12 +47,12 @@ HOOCODE_ARGS=
 # Optional model for new threads, e.g. anthropic/claude-sonnet-4-5
 MODEL=
 
-# Discord thread -> app-server thread links.
+# Chat channel/thread -> app-server thread links (Discord and Slack share it).
 # Default: ~/.local/share/hoobot/links.json
 LINKS_FILE=
 
 # auto = bash/edit/write run without asking (the bot works end to end).
-# ask  = they show Allow once / Deny buttons in Discord.
+# ask  = they show Allow once / Deny buttons in the chat.
 # Only ALLOWED_USER_IDS can talk to the bot either way.
 APPROVALS=auto
 

package/README.md

@@ -1,12 +1,16 @@
 # hoobot
 
-Use **hoocode** from Discord.
+Use **hoocode** from Discord and Slack.
 
 ```
-Discord  ⇄  this bot (Bun + discord.js)  ⇄  Codex app-server protocol  ⇄  hoocode app-server
+Discord ─┐
+         ├⇄  this bot (Bun)  ⇄  Codex app-server protocol  ⇄  hoocode app-server
+Slack ───┘
 ```
 
-Each Discord channel or thread is one shared app-server thread. The bot speaks only standard
+Each Discord or Slack channel or thread is one shared app-server thread.
+Run Discord, Slack or both from one process: each starts when its tokens
+are in `.env`. The bot speaks only standard
 Codex app-server methods, so the server is swappable: `hoocode app-server`
 (default), or the real `codex app-server`, set with `APP_SERVER` in `.env`.
 By default the bot starts `hoocode app-server` itself, in `HOO_WORKDIR`.
@@ -54,7 +58,57 @@ hoobot
    bun start
    ```
 
-   You should see `Logged in as hoo#1234`.
+   You should see `Discord: logged in as hoo#1234`.
+
+## Slack setup
+
+Slack uses Socket Mode: the bot opens the connection, so it needs no
+public URL. Discord can stay on or off; set only the Slack tokens for a
+Slack-only bot.
+
+1. At [api.slack.com/apps](https://api.slack.com/apps), **Create New App** →
+   **From an app manifest**, pick your workspace and paste:
+
+   ```yaml
+   display_information:
+     name: hoo
+   features:
+     bot_user:
+       display_name: hoo
+       always_online: true
+   oauth_config:
+     scopes:
+       bot:
+         - app_mentions:read
+         - channels:history
+         - groups:history
+         - channels:read
+         - groups:read
+         - chat:write
+         - files:read
+         - files:write
+         - users:read
+   settings:
+     event_subscriptions:
+       bot_events:
+         - message.channels
+         - message.groups
+     interactivity:
+       is_enabled: true
+     socket_mode_enabled: true
+   ```
+
+2. **Basic Information → App-Level Tokens → Generate Token**, add the
+   `connections:write` scope. Put the `xapp-…` token in `SLACK_APP_TOKEN=`.
+3. **Install App** to the workspace. Put the **Bot User OAuth Token**
+   (`xoxb-…`) in `SLACK_BOT_TOKEN=`.
+4. Add your Slack member ID to `ALLOWED_USER_IDS` (profile → ⋮ → **Copy
+   member ID**, e.g. `U0123ABCD`). Discord and Slack IDs go in the same list.
+5. Invite the bot to a channel (`/invite @hoo`), then `bun start`. You
+   should see `Slack: logged in as @hoo in <workspace>`.
+
+`CHANNEL_IDS` and `WORKSPACES` take Slack channel IDs too (channel details
+→ bottom of the **About** tab, e.g. `C0123ABCD`).
 
 ## Run in the background (macOS)
 
@@ -78,20 +132,21 @@ The Mac must be awake and logged in for the bot to answer.
 Every channel and every thread is a shared space where people and the bot
 work together. Each has its own hoocode conversation, model and settings.
 
-- **Call it:** mention the bot (`@hoo fix what we discussed above`) or
-  reply to one of its messages. Only `ALLOWED_USER_IDS` can call it.
-  It answers right there, as a reply to your message.
+- **Call it:** mention the bot (`@hoo fix what we discussed above`) or,
+  on Discord, reply to one of its messages. Only `ALLOWED_USER_IDS` can
+  call it. It answers right there (on Discord as a reply to your message).
 - **Context:** when called, it reads everyone's messages in that space
   since it last looked (up to 30, ~12k characters, newest kept), with
   names, as background. The first call reads the last 30. It never sends
   a message twice; messages sent while it was offline go with the next call.
   Replying to someone's message includes that message too.
-- **Threads:** open a Discord thread for a side task. It gets its own
+- **Threads:** open a thread for a side task. It gets its own
   conversation in the same folder; its first call also reads the channel
   messages that led up to it. Results stay in the thread.
 - **Steer:** calling it while it's busy redirects the current run.
-- **Needs** the **Read Message History** permission in those channels;
-  without it, it works with no context (and logs why).
+- **Needs** the **Read Message History** permission in those channels
+  (Slack: the bot must be in the channel); without it, it works with no
+  context (and logs why).
 - **Model per space:** `!model` lists hoocode's scoped models (your
   `enabledModels`, set with the model picker in the hoocode TUI). The pick
   applies from the next message, the conversation carries on, and it is
@@ -106,13 +161,29 @@ work together. Each has its own hoocode conversation, model and settings.
   line is removed and only the final answer is posted, with a short footer:
   PR link, commit, files edited, steps, time and model.
   `!verbose` shows every step and in-between message instead.
+- **Files:** files it writes in the work folder (`.html`, images, `.pdf`,
+  `.md`, `.txt`, `.csv`, `.json`, Office files, `.zip`), creates with a shell
+  command, or names in its answer are attached to the answer. Source code isn't; nothing outside the work
+  folder is. Up to 10 files and ~9.5 MB per answer. HTML arrives as a
+  download; Discord doesn't render it.
+  A channel and its threads share a folder. When two of them are working at
+  the same time, each answer only gets the files it wrote or names, so a
+  file isn't posted in both places. A file nobody names is left out rather
+  than guessed.
+- **Sending files:** files on the message that calls it, and on the message
+  it replies to (Discord), are saved in the work folder under
+  `.discord/<channel>/<message>/` (Slack: `.slack/…`) and the prompt says where they are, so it
+  can read, run or edit them. Text files up to 32 KB are pasted into the
+  prompt too; images are also shown to the model as images. Up to 25 MB a
+  file. `.discord/` and `.slack/` are git-ignored, cleared by `!new`, and files are deleted
+  after 7 days. Files in other people's earlier messages are only named.
 
 ### Commands (in a channel or thread, after the mention)
 
 | Command | What it does |
 |---|---|
 | `!stop` | Stop the current run |
-| `!new` | Start a fresh conversation here, for everyone |
+| `!new` | Start a fresh conversation here, for everyone (deletes files sent here) |
 | `!status` | Model, busy or not, folder, thread, server |
 | `!model` | Pick this space's model from a dropdown |
 | `!model <part of name>` | Pick it directly, e.g. `!model kimi` |
@@ -133,7 +204,8 @@ work together. Each has its own hoocode conversation, model and settings.
 How it works: on start the bot writes
 `workspace/.cortexcode/hoo-config.json`, which puts that folder in a
 custom `discord` mode (`auto_allow` follows `APPROVALS`), plus a short
-Discord system prompt in `modes/discord/system.md`. It only rewrites
+chat system prompt in `modes/discord/system.md` (it names Slack when Slack
+runs; the mode keeps the name `discord` so existing folders stay in it). It only rewrites
 these files while they still hold what it generated; edit them and they
 are left alone. With `ask`, the server sends approvals to every client on
 the thread; the first answer wins and the others see it resolved.
@@ -142,19 +214,28 @@ the thread; the first answer wins and the others see it resolved.
 
 | Path | Purpose |
 |---|---|
-| `src/index.ts` | Discord side: who can call it, spaces, commands |
+| `src/index.ts` | Starts Discord and/or Slack, whichever have tokens |
+| `src/core.ts` | Shared by both: app-servers per folder, sessions, allow list, commands, prompt building |
+| `src/chat.ts` | The `ChatSpace` interface a session talks to |
+| `src/discord.ts` | Discord side: mentions and replies → calls; channels and threads → spaces; buttons, menus |
+| `src/slack.ts` | Slack side (Socket Mode): mentions → calls; channels and threads → spaces; Block Kit buttons, menus |
+| `src/mrkdwn.ts` | Markdown → Slack mrkdwn, and Slack text → plain text |
 | `src/context.ts` | What people said since the bot last read a space |
 | `src/session.ts` | One app-server thread per channel or thread; notifications → messages, buttons → approvals |
 | `src/codex-client.ts` | Codex app-server client (`unix://` WebSocket or `stdio:`) |
 | `src/links.ts` | Channel/thread → app-server thread, model, last read message (`LINKS_FILE`) |
-| `src/format.ts` | Splits long replies to fit Discord's 2000-character limit |
+| `src/attachments.ts` | Picks written files to attach to the answer |
+| `src/inbound.ts` | Saves files sent on Discord or Slack into the work folder for the prompt |
+| `src/format.ts` | Splits long replies to fit the chat's message limit |
 | `workspace/` | hoocode's working folder (git-ignored); sessions are saved by hoocode |
 
 ## Tests
 
 ```sh
-bun run test                # message splitting (what CI runs)
-bun test/session.e2e.ts     # real app-server, fake Discord (uses API credits)
+bun run test                # unit tests (what CI runs)
+bun test/session.e2e.ts     # real app-server, fake chat (uses API credits)
+bun test/attachments.e2e.ts # real app-server writes files; checks they're attached
+bun test/inbound.e2e.ts     # files sent to it reach a real app-server
 APP_SERVER="stdio:codex app-server" bun test/session.e2e.ts   # same, real Codex
 bun run typecheck
 bun run check               # typecheck + unit tests

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kolisachint/hoobot",
-  "version": "0.0.4",
-  "description": "Use hoocode from Discord: a Discord bot that talks the Codex app-server protocol",
+  "version": "0.0.6",
+  "description": "Use hoocode from Discord and Slack: a chat bot that talks the Codex app-server protocol",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -30,13 +30,15 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
+    "@slack/socket-mode": "^2",
+    "@slack/web-api": "^7",
     "discord.js": "^14.27.0"
   },
   "scripts": {
     "start": "bun src/index.ts",
     "dev": "bun --watch src/index.ts",
     "typecheck": "tsc --noEmit",
-    "test": "bun test test/format.test.ts test/codex-client.test.ts test/summary.test.ts test/session.test.ts test/config.test.ts test/context.test.ts",
+    "test": "bun test test/mrkdwn.test.ts test/slack.test.ts test/format.test.ts test/codex-client.test.ts test/summary.test.ts test/session.test.ts test/config.test.ts test/context.test.ts test/attachments.test.ts test/inbound.test.ts",
     "check": "bun run typecheck && bun run test"
   }
 }

package/src/attachments.ts

@@ -0,0 +1,186 @@
+/**
+ * Files the model wrote during a turn that are worth sending back to the chat
+ * (HTML pages, images, PDFs, ...). Only regular files inside the work folder,
+ * of a known type and under Discord's upload limit (the smaller one), are picked.
+ */
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { INBOX_DIRS } from "./inbound.ts";
+
+/** File types sent back as attachments. Source code is left out on purpose. */
+export const ATTACH_EXTENSIONS = new Set([
+  ".html", ".htm", ".svg",
+  ".png", ".jpg", ".jpeg", ".gif", ".webp",
+  ".pdf", ".md", ".txt", ".csv", ".json",
+  ".docx", ".xlsx", ".pptx", ".zip",
+]);
+
+/** Discord's default upload limit is 10 MiB per message; stay under it. */
+export const MAX_TOTAL_BYTES = 9.5 * 1024 * 1024;
+/** Discord allows at most 10 attachments per message. */
+export const MAX_FILES = 10;
+
+export type Attachment = { attachment: string; name: string };
+
+/**
+ * File paths named in the model's answer, e.g. "Saved `out/report.html`".
+ * Catches files written by shell commands, which aren't tracked as edits.
+ */
+export function pathsInText(text: string): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(/[\w./~-]+\.[A-Za-z0-9]{2,5}\b/g)) {
+    const p = m[0].replace(/^\.\//, "");
+    if (p.startsWith("//")) continue; // the tail of a URL
+    if (ATTACH_EXTENSIONS.has(extname(p).toLowerCase())) out.push(p);
+  }
+  return out;
+}
+
+/** Folders never scanned: tooling, dependencies, build output. */
+const SKIP_DIRS = new Set(["node_modules", "target", "dist", "build", "__pycache__", "venv"]);
+/** Stop scanning after this many entries, so a huge folder can't stall a reply. */
+const SCAN_LIMIT = 20_000;
+
+/**
+ * Files of an attachable type under `workdir` modified at or after `sinceMs`,
+ * oldest first. Catches files written by shell commands (`python gen.py >
+ * out.html`), which the server doesn't report as edits. Skips dot folders
+ * (`.git`, `.cortexcode`, ...) and the folders in SKIP_DIRS.
+ */
+export function changedSince(workdir: string, sinceMs: number): string[] {
+  const found: { path: string; mtime: number }[] = [];
+  let seen = 0;
+  const walk = (dir: string) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (++seen > SCAN_LIMIT) return;
+      const path = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!e.name.startsWith(".") && !SKIP_DIRS.has(e.name)) walk(path);
+      } else if (e.isFile() && ATTACH_EXTENSIONS.has(extname(e.name).toLowerCase())) {
+        try {
+          const mtime = statSync(path).mtimeMs;
+          if (mtime >= sinceMs) found.push({ path, mtime });
+        } catch {}
+      }
+    }
+  };
+  walk(workdir);
+  return found.sort((a, b) => a.mtime - b.mtime).map((f) => f.path);
+}
+
+/**
+ * Turns running per work folder, so a file changed in a shared folder goes
+ * back only to the turn that made it. A channel and its threads share one
+ * folder; when their turns overlap, a scan of the folder can't tell whose
+ * file is whose.
+ */
+export class TurnLog {
+  private turns = new Map<string, Map<string, { start: number; end: number | null }>>();
+
+  begin(workdir: string, key: string, now = Date.now()) {
+    let byKey = this.turns.get(workdir);
+    if (!byKey) this.turns.set(workdir, (byKey = new Map()));
+    byKey.set(key, { start: now, end: null });
+  }
+
+  end(workdir: string, key: string, now = Date.now()) {
+    const t = this.turns.get(workdir)?.get(key);
+    if (t && t.end === null) t.end = now;
+    this.prune(now);
+  }
+
+  /** Whether another turn in `workdir` ran at some point during `key`'s turn. */
+  overlapped(workdir: string, key: string, now = Date.now()): boolean {
+    const byKey = this.turns.get(workdir);
+    const me = byKey?.get(key);
+    if (!byKey || !me) return false;
+    const myEnd = me.end ?? now;
+    for (const [k, t] of byKey) {
+      if (k === key) continue;
+      if (t.start <= myEnd && (t.end ?? now) >= me.start) return true;
+    }
+    return false;
+  }
+
+  /** Forget turns that ended over an hour ago; no running turn can overlap them. */
+  private prune(now: number) {
+    for (const [dir, byKey] of this.turns) {
+      for (const [k, t] of byKey) if (t.end !== null && now - t.end > 60 * 60 * 1000) byKey.delete(k);
+      if (byKey.size === 0) this.turns.delete(dir);
+    }
+  }
+}
+
+/** One log for the whole process: every session in a folder shares it. */
+export const turnLog = new TurnLog();
+
+/**
+ * Of `changed` (files changed in the folder during a turn), the ones this
+ * turn can claim. Alone in the folder: all of them. Overlapping another
+ * turn: only those its answer or shell commands name (by path or file name);
+ * the rest are ambiguous and go to nobody rather than to everyone.
+ */
+export function claimChanged(changed: string[], workdir: string, alone: boolean, mentions: string): string[] {
+  if (alone) return changed;
+  return changed.filter((p) => {
+    const rel = relative(workdir, p);
+    // Whole names only: `b.svg` matches `> b.svg` or `./b.svg`, not `xb.svg.bak` or `sub/b.svg`.
+    return [p, rel, basename(p)].some((name) =>
+      new RegExp(`(^|[^\\w./-]|(?<![\\w.])\\./)${escapeRe(name)}($|[^\\w./-]|\\.(?!\\w))`).test(mentions),
+    );
+  });
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * The files to attach, in the order given. Relative paths resolve against
+ * `workdir`. Skips anything missing, outside `workdir` (after following
+ * symlinks), of another type, or past the size/count limits.
+ */
+export function pickAttachments(paths: Iterable<string>, workdir: string): { files: Attachment[]; skipped: string[] } {
+  const files: Attachment[] = [];
+  const skipped: string[] = [];
+  let root: string;
+  try {
+    root = realpathSync(workdir);
+  } catch {
+    return { files, skipped };
+  }
+  const seen = new Set<string>();
+  let total = 0;
+  for (const p of paths) {
+    if (!ATTACH_EXTENSIONS.has(extname(p).toLowerCase())) continue;
+    let real: string;
+    let size: number;
+    try {
+      real = realpathSync(resolve(workdir, p));
+      const st = statSync(real);
+      if (!st.isFile()) continue;
+      size = st.size;
+    } catch {
+      continue; // deleted or never written
+    }
+    const rel = relative(root, real);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) continue;
+    // Files people sent on a chat: never echoed back.
+    if (Object.values(INBOX_DIRS).some((dir) => rel === dir || rel.startsWith(`${dir}/`))) continue;
+    if (seen.has(real)) continue;
+    seen.add(real);
+    if (files.length >= MAX_FILES || total + size > MAX_TOTAL_BYTES) {
+      skipped.push(basename(real));
+      continue;
+    }
+    total += size;
+    files.push({ attachment: real, name: basename(real) });
+  }
+  return { files, skipped };
+}

package/src/chat.ts

@@ -0,0 +1,66 @@
+/**
+ * What a session needs from a chat surface (Discord, Slack). A space is a
+ * channel or a thread; each has its own app-server conversation.
+ *
+ * Text is Discord-flavoured Markdown (`**bold**`, `-# small`, `[text](<url>)`);
+ * a surface that renders something else converts it when sending.
+ */
+import type { Attachment } from "./attachments.ts";
+
+export type Surface = "discord" | "slack";
+
+/** A message the bot posted. */
+export interface Posted {
+  /** Replace the text (and drop any buttons or menu). */
+  edit(text: string): Promise<unknown>;
+  delete(): Promise<unknown>;
+}
+
+export type Choice = {
+  label: string;
+  value: string;
+  description?: string;
+  /** Pre-selected in a menu. */
+  default?: boolean;
+  style?: "primary" | "danger";
+};
+
+/** A pick by an allowed user. */
+export interface Picked {
+  value: string;
+  /** Display name of who picked. */
+  user: string;
+  /** Replace the message's text and remove the controls. */
+  update(text: string): Promise<unknown>;
+}
+
+export interface ChatSpace {
+  /** Unique within the surface (Discord: channel or thread id; Slack: `channel` or `channel/thread_ts`). */
+  id: string;
+  surface: Surface;
+  /** "Discord", "Slack": for messages people read. */
+  label: string;
+  /** Longest message text the surface takes (before conversion). */
+  maxLength: number;
+  /** Most options a menu can show. */
+  maxChoices: number;
+  /**
+   * Post `text`. `replyTo`: the message it answers (a quoted reply where the
+   * surface has them). `files`: attached, or posted right after.
+   */
+  send(text: string, opts?: { replyTo?: string | null; files?: Attachment[] }): Promise<Posted>;
+  /** Show "typing…" where the surface can; else nothing. */
+  sendTyping(): Promise<unknown>;
+  /**
+   * Post `text` with buttons or a menu. `msg` is the posted message;
+   * `pick` resolves with the first pick by an allowed user (others are told
+   * no) and rejects after `timeoutMs`.
+   */
+  choose(
+    text: string,
+    kind: "buttons" | "menu",
+    choices: Choice[],
+    timeoutMs: number,
+    placeholder?: string,
+  ): Promise<{ msg: Posted; pick: Promise<Picked> }>;
+}