slackhive 0.1.37 → 0.1.39

package/cli/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}

package/docker-compose.yml

@@ -0,0 +1,122 @@
+# =============================================================================
+# SlackHive — Docker Compose
+#
+# Services:
+#   postgres  — Primary database (port 5432)
+#   redis     — Pub/sub for agent hot-reload events (port 6379)
+#   web       — Next.js management UI (port 3000)
+#   runner    — Agent runner service (manages all Slack bots)
+# =============================================================================
+
+services:
+  # ---------------------------------------------------------------------------
+  # postgres — Primary datastore
+  # Schema is auto-applied on first start from schema.sql.
+  # ---------------------------------------------------------------------------
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-agentteam}
+      POSTGRES_USER: ${POSTGRES_USER:-agentteam}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-agentteam}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./packages/shared/src/db/schema.sql:/docker-entrypoint-initdb.d/01-schema.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-agentteam} -d ${POSTGRES_DB:-agentteam}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # ---------------------------------------------------------------------------
+  # redis — Lightweight pub/sub broker
+  # Used for agent reload signals from web → runner.
+  # ---------------------------------------------------------------------------
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: sh -c "redis-server --requirepass $$REDIS_PASSWORD"
+    environment:
+      REDIS_PASSWORD: ${REDIS_PASSWORD}
+    healthcheck:
+      test: ["CMD-SHELL", "redis-cli -a $$REDIS_PASSWORD ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # ---------------------------------------------------------------------------
+  # web — Next.js 15 management UI
+  # Provides agent onboarding wizard, skill editor, MCP catalog,
+  # memory viewer, live logs, and start/stop controls.
+  # ---------------------------------------------------------------------------
+  web:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+      args:
+        AUTH_SECRET: ${AUTH_SECRET:-change-this-secret-in-production}
+        ADMIN_PASSWORD: ${ADMIN_PASSWORD:-changeme}
+    restart: unless-stopped
+    ports:
+      - "3001:3000"
+    environment:
+      DATABASE_URL: postgresql://${POSTGRES_USER:-agentteam}:${POSTGRES_PASSWORD:-agentteam}@postgres:5432/${POSTGRES_DB:-agentteam}
+      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379
+      NODE_ENV: ${NODE_ENV:-production}
+      ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
+      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-changeme}
+      AUTH_SECRET: ${AUTH_SECRET:-change-this-secret-in-production}
+    env_file:
+      - .env
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      # Docker socket so the logs API can tail runner container logs
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+  # ---------------------------------------------------------------------------
+  # runner — Agent runner service
+  # Loads all active agents from Postgres at startup, then manages one
+  # @slack/bolt App instance per agent. Listens on Redis for reload events.
+  #
+  # /tmp/agents is mounted to allow the runner to write ephemeral CLAUDE.md
+  # files for the Claude Code SDK, and to watch for memory file writes.
+  # ---------------------------------------------------------------------------
+  runner:
+    build:
+      context: .
+      dockerfile: apps/runner/Dockerfile
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgresql://${POSTGRES_USER:-agentteam}:${POSTGRES_PASSWORD:-agentteam}@postgres:5432/${POSTGRES_DB:-agentteam}
+      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379
+      NODE_ENV: ${NODE_ENV:-production}
+    env_file:
+      - .env
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      # Ephemeral per-agent working directories (CLAUDE.md + memory watch)
+      - /tmp/agents:/tmp/agents
+      # Mount host Claude config (read-only for credentials safety)
+      - ${HOME}/.claude:/root/.claude:ro
+      # Writable overlays for SDK runtime state (session-env, shell-snapshots)
+      - claude-session-env:/root/.claude/session-env
+      - claude-shell-snapshots:/root/.claude/shell-snapshots
+      # Mount host home so MCP server paths resolve inside container
+      - ${HOME}:${HOME}:ro
+
+volumes:
+  pgdata:
+    driver: local
+  claude-session-env:
+    driver: local
+  claude-shell-snapshots:
+    driver: local

package/docs/agents/boss-agents.mdx

@@ -0,0 +1,108 @@
+---
+title: "Boss Agents"
+description: "Set up orchestrating Boss agents that delegate tasks to specialist teams."
+---
+
+## What is a Boss agent?
+
+A Boss agent is a special type of SlackHive agent whose sole job is to receive high-level requests and delegate them to the right specialist agents. The Boss never does the specialist work itself — it orchestrates.
+
+```
+User:     @boss help me analyze last week's bookings
+Boss:     I'll get @data-bot on this 👇
+          @data-bot — user wants booking analysis for last week.
+          When you're done, please tag @boss so I can confirm.
+DataBot:  [reads full thread, runs Redshift query via MCP]
+          Bookings were up 12% to 4,320...
+Boss:     Thanks @data-bot! Here's the summary: bookings increased 12%...
+```
+
+The Boss reads the message, looks up its team registry, and delegates to the right specialist by @mentioning them in the same Slack thread. The specialist receives the full thread as context — nothing is lost in the handoff.
+
+## Creating a Boss agent
+
+During agent creation (Step 1 — Name & Role), toggle **This agent is a Boss**.
+
+When the Boss toggle is enabled:
+- The Tools step (Step 4) is skipped — Boss agents don't need MCP servers or skills
+- `CLAUDE.md` is auto-generated from the team registry instead of using a custom identity file
+- The Boss agent connects to Slack like any other agent and receives @mentions normally
+
+## The team registry
+
+Each Boss gets a `CLAUDE.md` compiled from its team registry. The registry is a Markdown document injected into the Boss's identity that lists every specialist reporting to it.
+
+Example registry section:
+
+```markdown
+## Your Team
+
+- **DataBot** (<@U12345678>) — Data warehouse NLQ, Redshift queries, business metrics
+- **Writer** (<@U87654321>) — Content generation, Slack summaries, announcements
+- **Engineer** (<@U11112222>) — Code review, debugging, GitHub PR summaries
+```
+
+The registry also includes explicit delegation rules:
+
+```markdown
+## Delegation Rules
+- ALWAYS delegate — do not attempt to perform specialist work yourself
+- Use the thread so specialists have full context
+- If unsure who to delegate to, ask the user for clarification
+- Always instruct the specialist to @mention you when they are done
+```
+
+**The registry auto-regenerates** whenever any agent is created, updated, or deleted. You never need to maintain it manually.
+
+## Setting reportsTo
+
+To add a specialist to a Boss's team, set the **Reports To** field on the specialist agent:
+
+1. Open the specialist agent's **Overview** tab
+2. Select one or more Boss agents in the **Reports To** dropdown
+3. Save — the Boss's registry regenerates automatically within seconds
+
+A specialist can report to multiple bosses. It will appear in each selected boss's team registry. This supports multi-domain setups where the same specialist (e.g. an "Engineer" agent) is available to multiple boss agents (e.g. "Product Boss" and "Infra Boss").
+
+## Multiple Boss agents
+
+You can create as many Boss agents as needed. Common patterns:
+
+| Pattern | Example |
+|---------|---------|
+| **Single Boss** | One orchestrator for the entire team |
+| **Domain Bosses** | Separate Boss per team (eng-boss, data-boss, content-boss) |
+| **Hierarchical** | A meta-boss delegates to domain bosses, which delegate to specialists |
+
+Each Boss only sees the specialists that explicitly report to it.
+
+## Delegation flow in detail
+
+When the Boss receives a message:
+
+1. Boss reads the user's request
+2. Checks the team registry to identify the right specialist
+3. @mentions the specialist in the **same thread** with a clear task description
+4. Instructs the specialist to tag the Boss when done
+5. Specialist picks up the full thread context and completes the task
+6. Specialist tags the Boss to signal completion
+7. Boss reviews the result, confirms for the user, and decides if another specialist is needed or the task is done
+
+The key design: everything happens **in the Slack thread**. Every participant can see the full conversation history — no context loss when multiple agents collaborate.
+
+## CLAUDE.md for Boss agents
+
+The Boss's `CLAUDE.md` is fully auto-generated and managed by SlackHive. You cannot manually edit it through the CLAUDE.md editor (the editor is read-only for Boss agents).
+
+The generated content includes:
+- The Boss's name and orchestrator role description
+- Your Role section with delegation rules
+- The full team roster with Slack user IDs and descriptions
+- Delegation format instructions (exact phrasing to use)
+- Instructions for what to do after a specialist responds
+
+## Scheduled jobs
+
+Boss agents work great with scheduled jobs — set up a daily cross-team digest, a weekly summary, or an alert that fires when something needs escalation across multiple specialists.
+
+→ See [Scheduled Jobs](/features/scheduled-jobs) for the full setup guide.

package/docs/agents/creating-agents.mdx

@@ -0,0 +1,132 @@
+---
+title: "Creating Agents"
+description: "Create a Claude agent and deploy it to Slack using the 5-step wizard."
+---
+
+Click **New Agent** in the sidebar to open the creation wizard. Creating an agent takes about 5 minutes if you have your Slack credentials ready.
+
+## Step 1: Name & Role
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Display name shown in the UI and Slack (e.g. "Ava Engineer") |
+| **Slug** | URL-safe identifier auto-generated from the name (e.g. `ava-engineer`). Used internally and as the agent's workspace directory name. |
+| **Description** | What this agent does. Shown in Boss agent team registries so the Boss knows who to delegate to. |
+| **Persona** | Free-form personality and behavioral instructions. Compiled into `CLAUDE.md` as the agent's identity section. |
+| **Model** | The Claude model this agent uses. |
+
+### Model selection
+
+| Model | Best for |
+|-------|---------|
+| `claude-opus-4-6` | Complex reasoning, Boss agents, multi-step planning |
+| `claude-sonnet-4-6` | Balanced capability and speed — good default for most agents |
+| `claude-haiku-4-5-20251001` | Fast, lightweight tasks and high-volume operations |
+
+### Boss vs specialist
+
+Toggle **This agent is a Boss** if this agent should orchestrate a team:
+
+- Boss agents skip the Tools step (they delegate rather than use tools directly)
+- Boss `CLAUDE.md` is auto-generated from the team registry — it lists all specialists that report to this boss and includes explicit delegation rules
+- The registry regenerates automatically whenever any agent is added, updated, or deleted
+
+For specialist agents, use **Reports To** to select which Boss agent(s) they report to. A specialist can report to multiple bosses and will appear in each selected boss's registry.
+
+## Step 2: Slack App
+
+SlackHive generates a Slack app manifest tailored for your agent. The manifest pre-configures:
+- All required OAuth scopes
+- Socket Mode enabled
+- Bot display name matching your agent's name
+
+**To create the Slack app:**
+1. Click **Generate Manifest** in the wizard
+2. Open [api.slack.com/apps](https://api.slack.com/apps) in a new tab
+3. Click **Create New App** → **From a manifest**
+4. Select your workspace, paste the manifest, click **Create**
+5. Go to **OAuth & Permissions** → **Install to Workspace** → **Allow**
+
+See [Slack App Setup](/configuration/slack-app) for a detailed walkthrough.
+
+## Step 3: Credentials
+
+Paste the three values from your Slack app settings:
+
+| Field | Where to find it |
+|-------|-----------------|
+| **Bot Token** (`xoxb-...`) | OAuth & Permissions → Bot User OAuth Token |
+| **App Token** (`xapp-...`) | Basic Information → App-Level Tokens (create with `connections:write` scope) |
+| **Signing Secret** | Basic Information → App Credentials |
+
+After saving, SlackHive verifies the Slack connection. If it fails, confirm that Socket Mode is enabled on your app.
+
+## Step 4: Tools
+
+<Note>This step is skipped for Boss agents.</Note>
+
+### Skill template
+
+Select a starting template for the agent's skill set:
+
+| Template | Description |
+|----------|-------------|
+| **Blank** | No starter skills — clean slate |
+| **Data Analyst** | SQL query patterns, data summarization, charting guidance |
+| **Writer** | Content drafting, editing, tone adjustment |
+| **Developer** | Code review, debugging, PR summaries, architecture commands |
+
+Skills are Markdown files compiled as Claude Code slash commands. They can be edited or replaced at any time from the agent's **Skills** tab.
+
+### MCP servers
+
+Assign MCP servers from the platform catalog to give this agent access to external tools. Each assigned server's tools become available as `mcp__{serverName}__{toolName}`.
+
+Servers can be added or removed later from the agent's **Tools** tab.
+
+## Step 5: Review
+
+Review the summary:
+- Agent name, slug, model, persona
+- Boss/specialist configuration
+- Slack app connection status
+- Assigned skills and MCP servers
+
+Click **Create Agent** to finalize. The runner picks up the new agent within seconds via Redis pub/sub.
+
+## After creation
+
+1. The agent appears in the dashboard with **Active** status
+2. Invite the bot to a Slack channel: `/invite @your-agent-name`
+3. @mention it to start a conversation
+
+<Tip>
+  Test your agent by opening a Slack DM with it. DMs don't require a channel invite.
+</Tip>
+
+## Editing an agent
+
+All fields are editable after creation from the agent's detail page tabs:
+
+| Tab | What you can edit |
+|-----|------------------|
+| **Overview** | Name, description, persona, model, Slack credentials, channel restrictions |
+| **CLAUDE.md** | The agent's main instruction/identity file directly |
+| **Skills** | Skill files (slash commands), add/edit/delete |
+| **Tools** | MCP server assignments, tool permissions (allowlist/denylist) |
+| **Memory** | Browse, inspect, and delete agent memories |
+| **History** | Version control — browse snapshots, view diffs, restore |
+
+Every save to skills, CLAUDE.md, tools, or permissions is auto-snapshotted. Changes are live-reloaded by the runner within seconds.
+
+## Channel restrictions
+
+By default, an agent responds in any channel it's invited to. To restrict to specific channels:
+
+1. Go to the agent's **Overview** tab
+2. Scroll to **Allowed Channels**
+3. Enter one or more Slack channel IDs (e.g. `C12345678`)
+
+When a channel list is set, the agent silently ignores messages from other channels. If the bot is invited to a non-allowed channel, it posts a notice and immediately leaves.
+
+Find a channel ID in Slack by right-clicking the channel name → **Copy link** — the ID is the `C...` segment at the end of the URL.

package/docs/agents/memory.mdx

@@ -0,0 +1,113 @@
+---
+title: "Agent Memory"
+description: "How agents learn from conversations and recall knowledge on demand."
+---
+
+## How memory works
+
+Agents learn over time by writing structured memory files during conversations. SlackHive persists these to Postgres and materializes them back to disk on the next startup — so every agent picks up exactly where it left off.
+
+```
+Agent writes memory/{type}_{name}.md
+  └─► MemoryWatcher detects change (fs.watch, 200ms debounce)
+        └─► Parses YAML frontmatter (name, type)
+              └─► Upserts into memories table (Postgres)
+
+On next agent start:
+  DB memories ──► materializeMemoryFiles ──► /tmp/agents/{slug}/memory/
+                                                └─► Agent uses /recall to read them
+```
+
+## Recalling memories
+
+Agents use the built-in `/recall` skill to load relevant memories on demand. This keeps the context window clean — memories are only loaded when they're relevant, not stuffed into every conversation.
+
+**The agent runs `/recall` automatically** at the start of each conversation and when the topic shifts. It reads `memory/MEMORY.md` for the index, then loads specific files that match.
+
+```
+/recall database preferences
+  └─► Reads memory/MEMORY.md (index)
+        └─► Reads memory/feedback_avoid_mocking.md
+              └─► Applies the knowledge to the current response
+```
+
+You can also trigger it manually in Slack:
+
+```
+/recall Kai's preferences
+```
+
+## When agents save memories
+
+Agents are instructed to save memories when they learn something worth keeping:
+
+- **User explicitly corrects or guides** — "don't do X", "always do Y"
+- **Recurring pattern detected** — same question asked repeatedly, same mistake made, same preference shown multiple times
+- **User role or working style** — who someone is, what tools they use, how they like to communicate
+- **Project decisions or constraints** — goals, deadlines, architectural choices that affect future work
+
+Memories are saved using the Write tool to create a file in `memory/`. The agent must actually write the file — not just say it saved.
+
+## Memory file format
+
+```markdown
+---
+name: kai_team_lead
+description: Kai is the data team lead, prefers concise answers
+type: user
+---
+
+Kai is the lead of the data team. They prefer concise, direct answers
+without lengthy preamble. They use BigQuery, not Redshift.
+They prefer SQL examples over written explanations.
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Snake_case identifier — used as the unique key per agent |
+| `type` | Yes | One of `user`, `feedback`, `project`, `reference` |
+| `description` | No | One-line summary shown in the Memory tab |
+
+## Memory types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `feedback` | Behavioral corrections and validated approaches | "Don't mock the database in integration tests" |
+| `user` | Information about people the agent works with | "Kai is the data team lead, prefers concise answers" |
+| `project` | Ongoing work context, goals, decisions, deadlines | "Merge freeze starts March 5 for mobile release" |
+| `reference` | Pointers to external systems and resources | "Pipeline bugs tracked in Linear project INGEST" |
+
+## Memory storage layout
+
+Each agent has two memory locations:
+
+```
+/tmp/agents/{slug}/
+  memory/                          ← read-only, materialized from DB on startup
+    MEMORY.md                      ← index file listing all memories
+    user_kai_team_lead.md
+    feedback_avoid_mocking.md
+    project_mobile_release.md
+
+  sessions/{userId}-{channelId}-{threadTs}/
+    memory/                        ← where agent writes new memories during conversations
+      feedback_new_learning.md
+```
+
+The root `memory/` directory is read-only — written once at startup from the database. New memories are written to the session's `memory/` directory, picked up by `MemoryWatcher`, and persisted to Postgres. On the next restart, they appear in the root directory.
+
+## Viewing and managing memories
+
+Open any agent's detail page and click the **Memory** tab. You can:
+
+- View the full content of each memory
+- See the memory type and description
+- Delete a memory (removes it from the database and it won't appear on next reload)
+
+## Updating a memory
+
+When an agent learns something that supersedes an existing memory, it overwrites the file with the same `name`. The database uses `(agent_id, name)` as the unique key — so updating never creates a duplicate.
+
+## Memory does not expire
+
+Memories persist until you explicitly delete them. There is no TTL. Agents accumulate knowledge over time and build a richer understanding of their users and projects with every conversation.

package/docs/agents/tools.mdx

@@ -0,0 +1,103 @@
+---
+title: "Tools & Permissions"
+description: "Control which tools agents can use: built-in Claude tools, MCP server tools, and the permissions system."
+---
+
+## Available tools
+
+SlackHive agents can use three categories of tools:
+
+### Always-allowed tools
+
+Two tools are always available to every agent regardless of permissions settings:
+
+| Tool | Purpose |
+|------|---------|
+| `Read` | Read files from the agent's working directory. Used to read project context, CLAUDE.md, and reference files. |
+| `Write` | Write files to the agent's working directory. **Required for the memory system** — agents must be able to write `memory/*.md` files. |
+
+These tools cannot be removed via the permissions UI. They are hardcoded in the runner as `alwaysAllowed = ['Read', 'Write']`.
+
+### MCP server tools
+
+Tools provided by assigned MCP servers. Each tool is prefixed with `mcp__{serverName}__`:
+
+- `mcp__redshift__query` — a `query` tool from a server named `redshift`
+- `mcp__github__create_issue` — a `create_issue` tool from a server named `github`
+- `mcp__filesystem__read_file` — a `read_file` tool from a server named `filesystem`
+
+All tools from all assigned MCP servers are automatically allowed when a server is assigned to an agent. To restrict specific tools, use the denylist.
+
+### Additional Claude tools
+
+The Claude Code provides built-in tools beyond `Read` and `Write`. These can be added to the agent's allowlist:
+
+| Tool | Description |
+|------|-------------|
+| `Bash` | Execute shell commands |
+| `Edit` | Make targeted edits to files |
+| `MultiEdit` | Make multiple edits to a file at once |
+| `Glob` | Find files by pattern |
+| `Grep` | Search file contents |
+| `LS` | List directory contents |
+| `WebFetch` | Fetch content from a URL |
+| `WebSearch` | Search the web |
+| `TodoRead` | Read the agent's task list |
+| `TodoWrite` | Update the agent's task list |
+
+## Configuring permissions
+
+Agent tool permissions are managed from the **Tools** tab on the agent's detail page.
+
+### Allowlist
+
+Tools in the allowlist are available to the agent. The effective tool set is:
+
+```
+effective = (alwaysAllowed + allowlist + mcpToolPrefixes) - denylist
+```
+
+To add a tool, type its name (e.g. `Bash`, `WebFetch`) or paste an MCP tool prefix (e.g. `mcp__redshift`) to allow all tools from that server.
+
+### Denylist
+
+Tools in the denylist are blocked even if they appear in the allowlist. Use this to selectively exclude tools from an MCP server you've otherwise allowed.
+
+For example, to allow a GitHub MCP server but block the `delete_branch` tool:
+- Allowlist: `mcp__github` (allows all GitHub tools)
+- Denylist: `mcp__github__delete_branch` (blocks this specific tool)
+
+### Default behavior
+
+When no permissions are configured for an agent:
+- `Read` and `Write` are always available
+- All tools from assigned MCP servers are available
+- No additional Claude Code tools are available
+
+## Permission mode
+
+All SlackHive agents run with `permissionMode: 'acceptEdits'`. This means:
+- File edits and tool use are automatically approved without prompting
+- Claude does not need to ask for confirmation before running tools
+- The only control is through the allowlist/denylist
+
+This is appropriate for the Slack context where agents are expected to act autonomously.
+
+## MCP server tool prefixes
+
+When you assign an MCP server to an agent, its tool prefix (`mcp__{serverName}`) is automatically added to the allowlist. Removing the server from the agent removes the prefix from the allowlist.
+
+If you want to assign an MCP server but only allow specific tools from it:
+1. Assign the server (adds `mcp__{serverName}` prefix)
+2. Add the specific tools you want to the allowlist directly (e.g. `mcp__redshift__query`)
+3. Add `mcp__{serverName}` to the denylist to remove the broad prefix
+
+Or equivalently, don't assign the server via the UI but manually add the specific tool names to the allowlist.
+
+## Best practices
+
+- **Keep allowlists minimal**: Only add tools the agent actually needs for its role
+- **Boss agents need no tools**: Boss agents should not have MCP servers or extra tools — they delegate rather than act
+- **Use `Bash` carefully**: Shell access is powerful; only add it to agents where it's necessary
+- **Use denylist for destructive tools**: If an MCP server has delete/destroy tools you don't want the agent to use, add them to the denylist
+- **`Write` is required for memory**: Never add `Write` to the denylist — it breaks the memory system