@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/thoughts/shared/research/2026-01-14-lead-slack-thread-context.md

@@ -1,277 +0,0 @@
----
-date: 2026-01-14T12:00:00-08:00
-researcher: Claude
-git_commit: 7ffa4d18b53c5422d59fdf53b00a8bab6f7a12fd
-branch: main
-repository: agent-swarm
-topic: "Lead Agent Slack Thread Context Handling"
-tags: [research, slack, lead-agent, thread-context, inbox-messages]
-status: complete
-last_updated: 2026-01-14
-last_updated_by: Claude
----
-
-# Research: Lead Agent Slack Thread Context Handling
-
-**Date**: 2026-01-14T12:00:00-08:00
-**Researcher**: Claude
-**Git Commit**: 7ffa4d18b53c5422d59fdf53b00a8bab6f7a12fd
-**Branch**: main
-**Repository**: agent-swarm
-
-## Research Question
-
-Why is the lead agent not properly following up on Slack messages? Specifically:
-- Not getting the thread context
-- Not able to follow up to previous messages
-- Needing to reference all context again and again for it to work
-
-## Summary
-
-The lead agent's difficulty with Slack thread context stems from **how inbox messages are presented to the agent, not how they are stored**. While the system correctly retrieves thread context from Slack (up to 20 messages) and stores it in inbox messages, the agent only sees a 100-character truncated preview in the trigger prompt. Additionally, there is no MCP tool for the agent to read the full inbox message content, and the base prompt does not explain the thread context format.
-
-## Detailed Findings
-
-### Component 1: Thread Context Retrieval (Working Correctly)
-
-**Location**: `src/slack/handlers.ts:45-90`
-
-The `getThreadContext()` function correctly fetches thread history from Slack:
-
-```typescript
-const result = await client.conversations.replies({
-  channel,
-  ts: threadTs,
-  limit: 20, // Last 20 messages max
-});
-```
-
-Thread messages are formatted with user display names or `[Agent]:` prefix for bot messages, and wrapped in XML-style tags:
-
-```
-<thread_context>
-John Doe: Can you help me with this bug?
-[Agent]: I'll look into that. The issue appears to be in the authentication module...
-John Doe: Thanks! Any update?
-</thread_context>
-
-<actual new message content here>
-```
-
-**Key Pattern**: Bot messages are truncated to 500 chars to keep context manageable (`handlers.ts:77`).
-
----
-
-### Component 2: Inbox Message Storage (Working Correctly)
-
-**Location**: `src/slack/handlers.ts:213-247`
-
-When creating inbox messages for the lead agent, the full task description includes thread context:
-
-```typescript
-const fullTaskDescription = threadContext + taskDescription;
-
-createInboxMessage(agent.id, fullTaskDescription, {
-  source: "slack",
-  slackChannelId: msg.channel,
-  slackThreadTs: threadTs,
-  slackUserId: msg.user,
-  matchedText: match.matchedText,
-});
-```
-
-The `InboxMessage` record in the database contains:
-- `content`: Full message including thread context (unlimited length)
-- `slackChannelId`: Channel ID for replies
-- `slackThreadTs`: Thread timestamp for replies
-- `slackUserId`: User who sent the message
-
----
-
-### Component 3: Prompt Formatting (Content Truncation)
-
-**Location**: `src/commands/runner.ts:368-382`
-
-When the lead agent receives a `slack_inbox_message` trigger, the content is **truncated to 100 characters**:
-
-```typescript
-case "slack_inbox_message": {
-  const inboxSummaries = (trigger.messages || [])
-    .map((m: { id: string; content: string }) => {
-      const preview = m.content.length > 100 ? `${m.content.slice(0, 100)}...` : m.content;
-      return `- "${preview}" (inboxMessageId: ${m.id})`;
-    })
-    .join("\n");
-
-  return `You have ${trigger.count} inbox message(s) from Slack:\n${inboxSummaries}\n\nFor each message, you can either:
-- Use \`slack-reply\` with the inboxMessageId to respond directly to the user
-- Use \`inbox-delegate\` to assign the request to a worker agent
-
-Review each message and decide the appropriate action.`;
-}
-```
-
-**Example of what the agent sees**:
-```
-You have 1 inbox message(s) from Slack:
-- "<thread_context>
-John Doe: Can you help me with this bug?
-[Agent]: I'll..." (inboxMessageId: abc-123)
-
-For each message, you can either:
-- Use `slack-reply` with the inboxMessageId to respond directly to the user
-- Use `inbox-delegate` to assign the request to a worker agent
-```
-
-**Impact**: The 100-character limit means the agent may only see the thread context header and some history, **but not the actual new message** that needs a response.
-
----
-
-### Component 4: No Tool to Read Full Inbox Content
-
-**Location**: `src/tools/` directory
-
-There is NO MCP tool that allows agents to read the full content of inbox messages. The existing tools:
-
-| Tool | Purpose | Can Read Full Inbox? |
-|------|---------|---------------------|
-| `slack-reply` | Reply to Slack threads | No - uses inbox internally but doesn't expose content |
-| `inbox-delegate` | Delegate to workers | No - uses inbox internally but doesn't expose content |
-| `read-messages` | Read internal channel messages | No - different message type |
-
-The full inbox message content is:
-- Available internally to `slack-reply` and `inbox-delegate` tools
-- Stored in the database (`getInboxMessageById()` at `db.ts:2610`)
-- **Not exposed to agents via any MCP tool**
-
----
-
-### Component 5: Base Prompt Guidance (Minimal)
-
-**Location**: `src/prompts/base-prompt.ts:20-24`
-
-The base prompt provides minimal guidance about Slack:
-
-```
-#### Slack Inbox
-When Slack messages are routed to you, they appear as "inbox messages" - NOT tasks.
-- Use `slack-reply` with the inboxMessageId to respond directly to the user
-- Use `inbox-delegate` with the inboxMessageId and agentId to create a task for a worker
-```
-
-**What's NOT explained**:
-- That thread context is included in messages
-- How to interpret `<thread_context>` tags
-- That the preview shown might be truncated
-- How to access the full message content
-
----
-
-### Component 6: Thread Follow-Up Routing (Working Correctly)
-
-**Location**: `src/slack/router.ts:139-144`
-
-When a message arrives in a thread, the router checks if an agent is already working on it:
-
-```typescript
-if (matches.length === 0 && threadContext) {
-  const workingAgent = getAgentWorkingOnThread(threadContext.channelId, threadContext.threadTs);
-  if (workingAgent && workingAgent.status !== "offline") {
-    matches.push({ agent: workingAgent, matchedText: "thread follow-up" });
-  }
-}
-```
-
-**Location**: `src/be/db.ts:1052-1083`
-
-The `getAgentWorkingOnThread()` function checks:
-1. `agent_tasks` table for workers with active tasks in that thread
-2. `inbox_messages` table for leads with messages in that thread
-
----
-
-### Component 7: Hook System Context (Limited)
-
-**Location**: `src/hooks/hook.ts:141-200`
-
-The hook system's "system tray" shows:
-- Unread message count
-- Mention count
-- Task counts
-
-It does NOT show:
-- Slack message content
-- Thread context
-- Message previews
-
----
-
-## Code References
-
-- `src/slack/handlers.ts:45-90` - Thread context retrieval (`getThreadContext()`)
-- `src/slack/handlers.ts:213-247` - Inbox message creation with context
-- `src/commands/runner.ts:368-382` - Prompt formatting with 100-char truncation
-- `src/tools/slack-reply.ts` - Reply tool (internal inbox access)
-- `src/tools/inbox-delegate.ts` - Delegate tool (internal inbox access)
-- `src/be/db.ts:2610` - `getInboxMessageById()` database function
-- `src/prompts/base-prompt.ts:20-24` - Lead agent Slack instructions
-- `src/slack/router.ts:139-144` - Thread follow-up routing
-
-## Architecture Documentation
-
-### Data Flow: Slack Message to Lead Agent
-
-```
-1. Slack message arrives
-   └─> handlers.ts:147 (message event handler)
-
-2. Thread context fetched
-   └─> handlers.ts:213-221 (getThreadContext())
-   └─> Returns: "<thread_context>\n...\n</thread_context>\n\n"
-
-3. Full description assembled
-   └─> handlers.ts:221: fullTaskDescription = threadContext + taskDescription
-
-4. Inbox message created (lead agents)
-   └─> handlers.ts:239-245 (createInboxMessage())
-   └─> Stores FULL content in database
-
-5. Agent polls for triggers
-   └─> http.ts:400-412 (GET /poll)
-   └─> Returns claimed inbox messages with FULL content
-
-6. Runner formats prompt
-   └─> runner.ts:368-382 (buildPromptForTrigger)
-   └─> TRUNCATES content to 100 chars
-   └─> Agent sees partial preview only
-
-7. Agent tries to respond
-   └─> Cannot read full message
-   └─> No tool available for reading inbox
-   └─> Must guess context from truncated preview
-```
-
-### Key Observations
-
-1. **Thread context is correctly captured** - The system fetches up to 20 messages with user names
-2. **Thread context is correctly stored** - Full content saved in `inbox_messages` table
-3. **Thread context is NOT correctly presented** - 100-char truncation cuts off most context
-4. **No mechanism to retrieve full content** - Agent has no tool to read the full message
-5. **Agent is not told about thread context** - Base prompt doesn't explain the format
-
-## Historical Context (from thoughts/)
-
-- `thoughts/shared/research/2025-12-18-slack-integration.md` - Original Slack integration research
-- `thoughts/shared/plans/2026-01-12-lead-inbox-model.md` - Lead inbox model design
-
-## Related Research
-
-- `thoughts/shared/research/2026-01-13-lead-duplicate-trigger-processing.md` - Related trigger handling research
-
-## Open Questions
-
-1. Should the 100-character truncation limit be increased or removed?
-2. Should a dedicated `read-inbox-message` MCP tool be created?
-3. Should the base prompt explain the `<thread_context>` format?
-4. Should follow-up messages in a thread show the previous response instead of full history?
-5. Should the thread context be presented differently (e.g., separate from main message)?

package/thoughts/shared/research/2026-01-15-ai-tracker-agent-swarm-integration.md

@@ -1,376 +0,0 @@
----
-date: 2026-01-15T13:15:00Z
-topic: "ai-tracker Integration for Agent-Swarm Workers"
-researcher: "Agent 16990304-76e4-4017-b991-f3e37b34cf73 (Researcher)"
-status: "complete"
----
-
-# Research: Integrating ai-tracker into Agent-Swarm Workers
-
-## Executive Summary
-
-This research investigates integrating `ai-tracker` from the `desplega-ai/ai-toolbox` repository into agent-swarm workers. Agent-swarm workers are Docker containers running Claude Code CLI in headless mode, which means ai-tracker's Claude Code hooks are directly applicable. The key requirement is adding environment variable support to ai-tracker for configurable database paths to enable per-agent tracking in a shared location.
-
----
-
-## 1. ai-tracker Overview
-
-### 1.1 What is ai-tracker?
-
-**Source**: [desplega-ai/ai-toolbox/ai-tracker](https://github.com/desplega-ai/ai-toolbox/tree/main/ai-tracker)
-**Package Name**: `cc-ai-tracker` (PyPI)
-**License**: MIT
-**Python Support**: 3.11, 3.12, 3.13
-
-**Purpose**: Track what percentage of code changes in git repos are AI-generated (via Claude Code) versus human-made.
-
-### 1.2 Installation Methods
-
-```bash
-# Option 1: uvx (no install needed)
-uvx cc-ai-tracker install
-
-# Option 2: Local install with uv
-uv tool install cc-ai-tracker
-ai-tracker install
-```
-
-### 1.3 How It Works
-
-ai-tracker operates through three integrated components:
-
-| Component | Function |
-|-----------|----------|
-| **Claude Code Hooks** | PreToolUse/PostToolUse hooks capture Edit/Write operations with line counts |
-| **Git Post-commit Hook** | Attributes committed changes to AI or human based on the edit log |
-| **CLI Statistics** | Queries SQLite database and displays formatted results |
-
-**Data Flow:**
-```
-Claude Code Edit/Write → PostToolUse Hook → SQLite (edits table)
-                                               ↓
-Git Commit → Post-commit Hook → SQLite (commits table with AI/human attribution)
-```
-
-### 1.4 Database and Configuration
-
-| Setting | Current Value |
-|---------|---------------|
-| **Database** | `~/.config/ai-tracker/tracker.db` (SQLite with WAL) |
-| **Config Dir** | `~/.config/ai-tracker/` |
-| **Git Hooks** | `~/.config/ai-tracker/git-hooks/` |
-| **Claude Settings** | `~/.claude/settings.json` |
-
-### 1.5 Claude Code Hooks (from setup.py)
-
-The `install` command adds these hooks to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": "Edit|Write",
-      "hooks": [{"type": "command", "command": "ai-tracker hook-post-tool"}]
-    }],
-    "PreToolUse": [{
-      "matcher": "Write",
-      "hooks": [{"type": "command", "command": "ai-tracker hook-pre-tool"}]
-    }]
-  }
-}
-```
-
-### 1.6 CLI Commands
-
-```bash
-ai-tracker install       # Install Claude Code + git hooks
-ai-tracker uninstall     # Remove all hooks
-ai-tracker stats         # Show all-time statistics
-ai-tracker stats --graph # Stats + chart for last 7 days
-ai-tracker stats --repo my-project  # Filter by repository
-```
-
----
-
-## 2. Agent-Swarm Worker Architecture
-
-### 2.1 Overview
-
-Agent-swarm workers are **Docker containers running Claude Code CLI in headless loop mode**. Each worker:
-- Runs as a non-root `worker` user
-- Has Claude Code CLI installed via official installer
-- Uses MCP (Model Context Protocol) to communicate with the swarm server
-- Has hooks configured in `~/.claude/settings.json`
-
-### 2.2 Key Files in agent-swarm
-
-| File | Purpose |
-|------|---------|
-| `Dockerfile.worker` | Worker container build (Ubuntu 24.04 base) |
-| `docker-entrypoint.sh` | Container startup script |
-| `src/cli.tsx` | Compiled agent-swarm binary |
-| `plugin/` | Claude Code commands, agents, and skills |
-
-### 2.3 Current Worker Hooks Configuration (Dockerfile.worker:89-101)
-
-```json
-{
-  "permissions": { "allow": ["mcp__agent-swarm__*"] },
-  "hooks": {
-    "SessionStart": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}],
-    "UserPromptSubmit": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}],
-    "PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}],
-    "PostToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]}]
-  }
-}
-```
-
-### 2.4 Worker Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `AGENT_ID` | UUID identifying the agent |
-| `AGENT_ROLE` | "worker" or "lead" |
-| `MCP_BASE_URL` | URL to MCP server |
-| `API_KEY` | Authentication for MCP |
-| `GITHUB_TOKEN` | Git operations authentication |
-
-### 2.5 Container Initialization (docker-entrypoint.sh)
-
-The entrypoint script:
-1. Validates required env vars (CLAUDE_CODE_OAUTH_TOKEN, API_KEY)
-2. Starts PM2 for background service management
-3. Creates `/workspace/.mcp.json` for MCP configuration
-4. Sets up git authentication if GITHUB_TOKEN provided
-5. Installs plugins from desplega-ai marketplace
-6. Executes optional `/workspace/start-up.*` script
-7. Runs `/usr/local/bin/agent-swarm <role>` to start Claude Code
-
----
-
-## 3. Integration Plan
-
-### 3.1 Required Changes to ai-tracker
-
-**Issue**: ai-tracker has a **hardcoded database path** in `config.py`:
-```python
-def get_db_path() -> Path:
-    return get_config_dir() / "tracker.db"  # Fixed to ~/.config/ai-tracker/
-
-def get_config_dir() -> Path:
-    config_dir = Path.home() / ".config" / "ai-tracker"
-    config_dir.mkdir(parents=True, exist_ok=True)
-    return config_dir
-```
-
-**Proposed Fix**: Add environment variable support:
-```python
-def get_db_path() -> Path:
-    if custom_path := os.environ.get("AI_TRACKER_DB_PATH"):
-        path = Path(custom_path)
-        path.parent.mkdir(parents=True, exist_ok=True)
-        return path
-    return get_config_dir() / "tracker.db"
-
-def get_config_dir() -> Path:
-    if custom_dir := os.environ.get("AI_TRACKER_CONFIG_DIR"):
-        config_dir = Path(custom_dir)
-    else:
-        config_dir = Path.home() / ".config" / "ai-tracker"
-    config_dir.mkdir(parents=True, exist_ok=True)
-    return config_dir
-```
-
-**GitHub Issue Required**: Create issue in `desplega-ai/ai-toolbox` repo requesting this feature.
-
-### 3.2 Docker Integration
-
-**Step 1: Install ai-tracker in Dockerfile.worker**
-
-Add after the Claude CLI installation (around line 80):
-```dockerfile
-# Install uv for Python package management
-RUN curl -LsSf https://astral.sh/uv/install.sh | sh
-ENV PATH="/home/worker/.local/bin:$PATH"
-
-# Install ai-tracker
-RUN uv tool install cc-ai-tracker
-```
-
-**Step 2: Add hooks to settings.json template**
-
-Modify the settings.json in Dockerfile.worker to include ai-tracker hooks:
-```json
-{
-  "permissions": { "allow": ["mcp__agent-swarm__*"] },
-  "hooks": {
-    "PreToolUse": [
-      {"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]},
-      {"matcher": "Write", "hooks": [{"type": "command", "command": "ai-tracker hook-pre-tool"}]}
-    ],
-    "PostToolUse": [
-      {"matcher": "*", "hooks": [{"type": "command", "command": "/usr/local/bin/agent-swarm hook"}]},
-      {"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "ai-tracker hook-post-tool"}]}
-    ]
-  }
-}
-```
-
-**Step 3: Configure per-agent database in docker-entrypoint.sh**
-
-Add after the workspace initialization section:
-```bash
-# Configure ai-tracker for per-agent database
-echo ""
-echo "=== AI Tracker Configuration ==="
-if [ -n "$AGENT_ID" ]; then
-    TRACKER_DIR="/workspace/shared/tracking"
-    mkdir -p "$TRACKER_DIR"
-    export AI_TRACKER_DB_PATH="${TRACKER_DIR}/${AGENT_ID}.db"
-    echo "AI Tracker DB: $AI_TRACKER_DB_PATH"
-
-    # Install git hooks for this agent
-    ai-tracker git-install --global 2>/dev/null || true
-else
-    echo "AGENT_ID not set, using default ai-tracker path"
-fi
-echo "================================"
-```
-
-### 3.3 Per-Agent Database Structure
-
-```
-/workspace/shared/tracking/
-├── 16990304-76e4-4017-b991-f3e37b34cf73.db   # Worker 1
-├── d454d1a5-4df9-49bd-8a89-e58d6a657dc3.db   # Lead Agent
-├── 38d36438-58a0-45b5-8602-a5d52b07c2f1.db   # Worker 2
-└── .gitkeep
-```
-
-Benefits:
-- Each agent has isolated tracking data
-- Shared volume allows aggregation/analysis
-- No SQLite concurrency issues between agents
-
----
-
-## 4. Implementation Steps
-
-### 4.1 Phase 1: ai-tracker Enhancement
-
-1. **Create GitHub Issue** in `desplega-ai/ai-toolbox`:
-   - Title: "Add environment variable support for configurable database path"
-   - Request: `AI_TRACKER_DB_PATH` and `AI_TRACKER_CONFIG_DIR` env vars
-   - Use case: Multi-agent environments where each agent needs its own database
-
-2. **Implement the change** (or wait for issue to be addressed):
-   - Modify `config.py` to check environment variables
-   - Update README with new configuration options
-
-### 4.2 Phase 2: Dockerfile.worker Updates
-
-1. Add `uv` installation for Python tool management
-2. Install `cc-ai-tracker` via `uv tool install`
-3. Update `settings.json` template with ai-tracker hooks
-
-### 4.3 Phase 3: docker-entrypoint.sh Updates
-
-1. Add tracking directory creation
-2. Set `AI_TRACKER_DB_PATH` environment variable
-3. Run `ai-tracker git-install` at startup
-
-### 4.4 Phase 4: Testing
-
-1. Build updated worker image
-2. Start multiple workers with different AGENT_IDs
-3. Verify each worker creates its own database
-4. Run some Edit/Write operations and git commits
-5. Check `ai-tracker stats` shows correct data per agent
-
----
-
-## 5. Alternative Approaches
-
-### 5.1 Use uvx at Runtime (No Install Required)
-
-Instead of installing ai-tracker in the image, use uvx in hooks:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": "Edit|Write",
-      "hooks": [{"type": "command", "command": "AI_TRACKER_DB_PATH=/workspace/shared/tracking/${AGENT_ID}.db uvx cc-ai-tracker hook-post-tool"}]
-    }]
-  }
-}
-```
-
-**Pros**: No image rebuild needed
-**Cons**: Slower (uvx fetches package each time), env var interpolation may not work in JSON
-
-### 5.2 Shared Single Database
-
-Instead of per-agent databases, use a single shared database with agent_id column:
-
-**Pros**: Easier aggregation
-**Cons**: SQLite concurrency issues, needs schema changes in ai-tracker
-
-### 5.3 External Tracking Service
-
-Send tracking data to a centralized service instead of local SQLite:
-
-**Pros**: Real-time aggregation, no storage management
-**Cons**: Requires new service, network dependency
-
----
-
-## 6. Recommendations
-
-### 6.1 Recommended Approach
-
-**Use per-agent databases with environment variable configuration:**
-
-1. Create issue in ai-toolbox for env var support
-2. Update Dockerfile.worker to install ai-tracker
-3. Update docker-entrypoint.sh to set per-agent paths
-4. Update settings.json to include ai-tracker hooks
-
-This approach:
-- Works with ai-tracker's existing architecture
-- Minimal changes required
-- Maintains agent isolation
-- Allows easy aggregation later
-
-### 6.2 Action Items
-
-| Priority | Action | Owner |
-|----------|--------|-------|
-| 1 | Create GitHub issue in ai-toolbox | Swarm Lead |
-| 2 | Implement env var support in ai-tracker | ai-toolbox maintainer |
-| 3 | Update Dockerfile.worker | agent-swarm PR |
-| 4 | Update docker-entrypoint.sh | agent-swarm PR |
-| 5 | Test multi-agent tracking | QA |
-
----
-
-## 7. Appendix
-
-### 7.1 ai-tracker Source Files Reviewed
-
-| File | Purpose |
-|------|---------|
-| `src/ai_tracker/config.py` | Path configuration (needs env var support) |
-| `src/ai_tracker/setup.py` | Claude Code hook installation |
-| `src/ai_tracker/cli.py` | CLI commands (install, stats, etc.) |
-| `src/ai_tracker/git/install.py` | Git hook installation |
-| `src/ai_tracker/hooks/log_claude_edit.py` | PostToolUse hook handler |
-| `src/ai_tracker/hooks/capture_before_write.py` | PreToolUse hook handler |
-
-### 7.2 agent-swarm Files Reviewed
-
-| File | Purpose |
-|------|---------|
-| `Dockerfile.worker` | Worker container build |
-| `docker-entrypoint.sh` | Container startup script |
-| `DEPLOYMENT.md` | Deployment documentation |