@desplega.ai/agent-swarm 1.49.0 → 1.52.0

package/thoughts/taras/research/2026-03-13-slack-ai-features.md

@@ -1,258 +0,0 @@
----
-date: 2026-03-13
-researcher: claude
-git_commit: 3df5660
-git_branch: main
-tags: [slack, ai, integration, streaming, assistant-threads, block-kit]
-status: complete
-last_updated: 2026-03-13
----
-
-# Research: Slack AI Features & Richer Task Notifications
-
-## Research Question
-
-How can we improve the current Slack integration to use native Slack AI features? Specifically: pushing more detailed info from task logs to chat, leveraging assistant threads, streaming, and rich messaging.
-
-## Summary
-
-The current Slack integration uses a simple polling watcher that posts plain-text completion/progress messages to threads. Slack's platform has evolved significantly with AI-native features that could dramatically improve the agent-swarm UX. The three highest-impact opportunities are:
-
-1. **Assistant Threads** — gives agent-swarm a native AI container in Slack's sidebar with status indicators, suggested prompts, and conversation history
-2. **Chat Streaming** — stream LLM responses token-by-token instead of waiting for full completion
-3. **Richer Block Kit messages** — structured progress updates with expandable sections, feedback buttons, and task metadata
-
----
-
-## Detailed Findings
-
-### 1. Current Slack Integration Architecture
-
-#### Entry Point & Lifecycle
-- `src/slack/app.ts` — Initializes `@slack/bolt` App in **Socket Mode**, registers handlers, starts task watcher
-- `src/slack/index.ts` — Barrel export for all Slack modules
-
-#### Inbound Flow (Slack → Swarm)
-- `src/slack/handlers.ts:316` — `registerMessageHandler()` listens to `app.event("message")`
-- Handles: user filtering, deduplication, rate limiting, bot mention detection
-- `src/slack/router.ts:17` — `routeMessage()` routes messages by priority: `swarm#<uuid>` → `swarm#all` → thread follow-up → lead fallback
-- `src/slack/thread-buffer.ts` — Additive buffer for non-mention thread replies (feature flag: `ADDITIVE_SLACK=true`), debounces 10s, creates batched follow-up tasks with dependency chaining
-- `src/slack/commands.ts` — Slash commands: `/agent-swarm-status`, `/agent-swarm-help`
-
-#### Outbound Flow (Swarm → Slack)
-- `src/slack/watcher.ts:24` — `startTaskWatcher()` polls DB every 3 seconds
-  - Checks `getInProgressSlackTasks()` for progress changes → `sendProgressUpdate()`
-  - Checks `getCompletedSlackTasks()` for completions → `sendTaskResponse()`
-  - Throttling: 1s minimum between sends per task, dedup via `sentProgress` map
-- `src/slack/responses.ts:57` — `sendTaskResponse()` posts completion/failure with agent persona (custom username + emoji via `chat:write.customize` scope)
-- `src/slack/responses.ts:110` — `sendProgressUpdate()` posts progress with hourglass emoji
-- Both use a single `section` block with `mrkdwn` text — no rich blocks, no updates, no streaming
-
-#### MCP Tools (Agent → Slack)
-- `src/tools/slack-post.ts` — Post new channel message (lead-only)
-- `src/tools/slack-reply.ts` — Reply to thread (by inbox message or task ID)
-- `src/tools/slack-read.ts` — Read channel messages
-- `src/tools/slack-upload-file.ts` — Upload files to channels/threads
-- `src/tools/store-progress.ts` — Stores progress + creates follow-up tasks for lead on completion; this is where the watcher picks up changes
-
-#### Current Manifest Scopes
-```json
-"bot": [
-  "app_mentions:read", "channels:history", "channels:read",
-  "chat:write", "chat:write.customize", "chat:write.public",
-  "commands", "files:read", "files:write",
-  "groups:history", "groups:read", "im:history", "im:read", "im:write",
-  "mpim:history", "mpim:read", "mpim:write",
-  "reactions:write", "users:read"
-]
-```
-
-#### Current Event Subscriptions
-```json
-"bot_events": ["app_mention", "message.channels", "message.groups", "message.im", "message.mpim"]
-```
-
----
-
-### 2. Slack AI Platform Features (Available to Third-Party Apps)
-
-#### 2a. Agents & AI Apps Feature
-
-**What it is:** A Slack platform feature that gives your app a dedicated AI container in Slack's sidebar. Users can start threads with the app directly (not just @mention in channels).
-
-**Key capabilities:**
-- Dedicated split-view surface in Slack UI
-- Loading/thinking status indicators
-- Suggested prompts for user guidance
-- Conversation history tab
-- Thread context awareness (knows which channel the user is viewing)
-
-**Events:**
-- `assistant_thread_started` — fired when user opens a new conversation with your app
-- `assistant_thread_context_changed` — fired when user switches channels while container is open
-
-**API Methods:**
-| Method | Description | Scope Required |
-|--------|-------------|----------------|
-| `assistant.threads.setStatus` | Show loading/thinking indicator | `chat:write` (or `assistant:write`) |
-| `assistant.threads.setTitle` | Set thread title for history | `chat:write` (or `assistant:write`) |
-| `assistant.threads.setSuggestedPrompts` | Show suggested prompts | `chat:write` (or `assistant:write`) |
-
-**Manifest changes needed:**
-- Enable "Agents & AI Apps" in app settings
-- Subscribe to `assistant_thread_started` and `assistant_thread_context_changed` events
-- Add `assistant:write` scope (or just use existing `chat:write`)
-
-**Bolt.js integration:** The `Assistant` class in `@slack/bolt` handles these events natively with `threadStarted`, `threadContextChanged`, and `userMessage` handlers.
-
-**Source:** [Slack AI Assistant Tutorial (Bolt.js)](https://docs.slack.dev/tools/bolt-js/tutorials/ai-assistant/), [Developing AI Apps](https://docs.slack.dev/ai/developing-ai-apps/)
-
-#### 2b. Chat Streaming
-
-**What it is:** Three new API methods that let apps stream text responses token-by-token, providing a ChatGPT-like experience in Slack.
-
-**API Methods:**
-| Method | Description |
-|--------|-------------|
-| `chat.startStream` | Begin a text stream in a thread |
-| `chat.appendStream` | Append text chunks to the stream |
-| `chat.stopStream` | End the stream, finalize the message |
-
-**Bolt.js helper:** `client.chatStream()` returns a streamer object with `.append()` and `.stop()` methods.
-
-**Additional feature:** `feedback_buttons` block element lets users rate AI responses (thumbs up/down), sending a `block_action` event to your app.
-
-**Source:** [Chat Streaming Changelog](https://docs.slack.dev/changelog/2025/10/7/chat-streaming/)
-
-#### 2c. Slack MCP Server (GA)
-
-**What it is:** Slack's official MCP server lets AI agents use Slack tools (search, messaging, canvases) via the Model Context Protocol.
-
-**Relevance:** This is the inverse of what we do — we bring Slack into agent-swarm via `@slack/bolt`, while Slack's MCP server brings Slack into standalone AI agents. Not directly useful for our integration but worth knowing about.
-
-**Source:** [Slack MCP Server](https://docs.slack.dev/ai/slack-mcp-server/)
-
-#### 2d. Message Metadata API
-
-**What it is:** Invisible structured data payloads attached to messages via a `metadata` field containing `event_type` and `event_payload`.
-
-**Structure:**
-```json
-{
-  "metadata": {
-    "event_type": "task_completed",
-    "event_payload": {
-      "task_id": "abc-123",
-      "agent_name": "Alpha",
-      "status": "completed",
-      "duration_ms": "45000"
-    }
-  }
-}
-```
-
-**Key properties:**
-- Not visible to users in the message UI
-- Can be read by other apps/automations via `include_all_metadata=true`
-- Can trigger Workflow Builder automations
-- Flat key-value structure only (no nested objects)
-
-**Source:** [Message Metadata](https://api.slack.com/metadata), [Metadata Schema](https://api.slack.com/reference/metadata)
-
----
-
-### 3. Slack Rich Messaging Capabilities
-
-#### 3a. Block Kit Limits & Capabilities
-
-| Constraint | Limit |
-|------------|-------|
-| Max blocks per message | 50 |
-| Section text max chars | ~3,000 |
-| Markdown block max chars | ~12,000 |
-| Max message text (fallback) | 40,000 chars |
-
-**Block types relevant for task info:**
-- `header` — Large bold text (task title)
-- `section` — Text with optional accessory (button, overflow menu)
-- `context` — Small gray metadata text (agent name, task ID, duration)
-- `divider` — Horizontal line
-- `actions` — Interactive buttons, select menus
-- `rich_text` — Rich text with code blocks, lists, quotes
-
-**Missing:** No native collapsible/expandable sections in Block Kit. Workaround: post summary in thread root, details in thread reply.
-
-#### 3b. Message Updates (`chat.update`)
-
-**Rate limits:**
-- Same as `chat.postMessage`: ~1 message/second per channel (Tier 3)
-- Can update any message posted by your app
-- Blocks, text, and attachments can all be updated
-
-**Use case:** Post a "task assigned" message, then update it as progress comes in — avoids thread spam.
-
-#### 3c. File Uploads
-
-Currently supported via `src/slack/files.ts` using `filesUploadV2`. Can share logs, diffs, or artifacts as threaded file attachments.
-
----
-
-### 4. Current Integration Gaps
-
-| Area | Current State | What's Available |
-|------|--------------|-----------------|
-| Task status display | Plain text `:hourglass:` progress messages | Block Kit with structured sections, context blocks, action buttons |
-| Response delivery | Full text dump on completion | Chat streaming (token-by-token) |
-| Progress updates | New message per update (thread spam) | `chat.update` on a single pinned progress message |
-| AI container | Only works via @mentions in channels | Assistant Threads with dedicated sidebar UI |
-| Loading indicators | None | `assistant.threads.setStatus` |
-| Suggested prompts | None | `assistant.threads.setSuggestedPrompts` |
-| Conversation history | Users must scroll threads | Assistant thread history tab |
-| User feedback | None | `feedback_buttons` block element |
-| Structured metadata | None | Message Metadata API for automation triggers |
-| Log detail | Link to dashboard only | Expandable rich text blocks, file uploads for logs |
-
----
-
-## Code References
-
-| File | Lines | Description |
-|------|-------|-------------|
-| `src/slack/app.ts` | 1-75 | App init, socket mode, handler registration, watcher start |
-| `src/slack/handlers.ts` | 316-588 | Message event handler, routing, additive buffer integration |
-| `src/slack/router.ts` | 17-71 | Message routing logic (swarm#id → swarm#all → thread → lead) |
-| `src/slack/watcher.ts` | 1-120 | 3s polling loop for progress/completion → Slack notifications |
-| `src/slack/responses.ts` | 1-184 | `sendTaskResponse()`, `sendProgressUpdate()`, persona logic |
-| `src/slack/thread-buffer.ts` | 1-213 | Additive buffer with debounce, dependency chaining, !now |
-| `src/slack/commands.ts` | 1-102 | Slash commands (/status, /help) |
-| `src/slack/files.ts` | 1-303 | File upload/download via Slack API |
-| `src/slack/types.ts` | 1-20 | Shared types (SlackMessageContext, AgentMatch, SlackConfig) |
-| `src/slack/HEURISTICS.md` | 1-106 | Documentation of routing & buffering heuristics |
-| `src/tools/slack-post.ts` | 1-105 | MCP tool: post to channel (lead-only) |
-| `src/tools/slack-reply.ts` | 1-144 | MCP tool: reply to thread |
-| `src/tools/store-progress.ts` | 1-317 | MCP tool: store progress, complete/fail tasks, create follow-ups |
-| `slack-manifest.json` | 1-72 | App manifest: scopes, events, slash commands |
-
----
-
-## Key Terminology
-
-| Term | Definition |
-|------|-----------|
-| **Assistant Thread** | Slack's native AI conversation container in the sidebar, separate from channel threads |
-| **Chat Streaming** | Token-by-token message delivery via `chat.startStream/appendStream/stopStream` |
-| **Message Metadata** | Invisible structured payload (`event_type` + `event_payload`) on messages |
-| **Agents & AI Apps** | Slack platform feature that enables assistant threads, status, and suggested prompts |
-| **Block Kit** | Slack's UI framework for rich message layouts |
-| **Additive Buffer** | agent-swarm's debounce system for batching non-mention thread replies into tasks |
-| **Task Watcher** | 3s polling loop in `watcher.ts` that bridges DB task changes to Slack messages |
-
----
-
-## Decisions (from review)
-
-1. **Assistant Threads vs Channel Threads** — **Support both.** Assistant threads for 1:1 agent conversations, channel threads for team visibility. The implementation should be backward-compatible (works even if Agents & AI Apps feature isn't enabled in the Slack app).
-2. **Streaming granularity** — **Stream full task output.** No need to truncate or summarize.
-3. **chat.update vs new messages** — **Use chat.update** to update a single progress message instead of posting new ones.
-4. **Manifest migration** — Already enabled manually. Implementation should be backward-compatible so it works even without the feature toggle.
-5. **Custom buttons** — Yes, Slack supports custom interactive buttons via Block Kit `actions` blocks with `button` elements. They fire `block_action` events to your app. Additionally, the Agents & AI Apps feature provides a dedicated `feedback_buttons` block element for thumbs up/down AI response ratings. Both approaches work — standard buttons for custom actions (e.g., "View Full Logs", "Retry Task", "Cancel"), and `feedback_buttons` for AI response quality feedback. Destination TBD.

package/thoughts/taras/research/2026-03-16-openapi-docs-generation.md

@@ -1,335 +0,0 @@
----
-date: 2026-03-16T12:00:00-05:00
-researcher: Claude
-git_commit: 3f114cc
-branch: main
-repository: agent-swarm
-topic: "OpenAPI documentation generation for the agent-swarm REST API"
-tags: [research, openapi, api-docs, zod-to-openapi, scalar, documentation]
-status: complete
-autonomy: autopilot
-last_updated: 2026-03-16
-last_updated_by: Claude
----
-
-# Research: OpenAPI Documentation Generation for the Agent Swarm REST API
-
-**Date**: 2026-03-16
-**Researcher**: Claude
-**Git Commit**: 3f114cc
-**Branch**: main
-
-## Research Question
-
-What is the best approach for auto-generating OpenAPI documentation for the agent-swarm REST API? The API has ~62 endpoints using raw `node:http` with Bun, Zod schemas for domain entities, and an existing auto-generated MCP tools reference (`MCP.md`). The goal is an automatic approach that doesn't require manual maintenance.
-
-## Summary
-
-The agent-swarm REST API has **62 endpoints** across 17 handler files, with **zero documentation** outside of the auto-generated `MCP.md` for MCP tools. The REST API (used by the dashboard, external integrations, and `curl`) is completely undocumented.
-
-The recommended approach is a **build-time script** using `@asteasolutions/zod-to-openapi` that generates an OpenAPI 3.1 spec from route definitions + existing Zod schemas, paired with **Scalar** as a zero-dependency docs viewer served at `/docs`. This mirrors the existing `generate-mcp-docs.ts` pattern and requires no framework migration. A CI freshness check can enforce the spec stays in sync.
-
-Migration to Hono was evaluated and **rejected** — the OpenAPI "auto-generation" claim is misleading (you still write all schemas manually), and the migration cost (~77 route rewrites across 14 files) doesn't justify the benefit.
-
-## Detailed Findings
-
-### 1. Current API Surface
-
-The REST API is served via `node:http` `createServer` (`src/http/index.ts:52`), with a custom handler chain pattern. Each handler module (`src/http/*.ts`) exports a function like `handleTasks(req, res, pathSegments, queryParams, myAgentId)` that returns `Promise<boolean>` — first match wins.
-
-**62 endpoints** were cataloged across these domains:
-
-| Domain | Endpoints | Handler File |
-|--------|-----------|--------------|
-| Core | 7 | `src/http/core.ts` |
-| Agents | 7 | `src/http/agents.ts` |
-| Tasks | 10 | `src/http/tasks.ts` |
-| Epics | 5 | `src/http/epics.ts` |
-| Channels + Messages | 6 | `src/http/epics.ts` |
-| Workflows | 9 | `src/http/workflows.ts` |
-| Schedules | 5 | `src/http/schedules.ts` |
-| Config | 5 | `src/http/config.ts` |
-| Memory | 2 | `src/http/memory.ts` |
-| Stats | 5 | `src/http/stats.ts` |
-| Repos | 5 | `src/http/repos.ts` |
-| Poll | 1 | `src/http/poll.ts` |
-| Ecosystem | 1 | `src/http/ecosystem.ts` |
-| Session Data | 6 | `src/http/session-data.ts` |
-| Active Sessions | 6 | `src/http/active-sessions.ts` |
-| Webhooks | 3 | `src/http/webhooks.ts` |
-| MCP | 3 | `src/http/mcp.ts` |
-
-Route matching uses `matchRoute()` (`src/http/utils.ts:69-87`) with literal and dynamic (`null`) segment patterns.
-
-### 2. Existing Zod Schemas
-
-`src/types.ts` contains **28 Zod schemas** covering all domain entities:
-
-- `AgentTaskSchema`, `AgentTaskStatusSchema`, `AgentTaskSourceSchema`
-- `AgentSchema`, `AgentStatusSchema`, `AgentWithTasksSchema`
-- `EpicSchema`, `EpicStatusSchema`, `EpicWithProgressSchema`
-- `WorkflowSchema`, `WorkflowDefinitionSchema`, `WorkflowNodeSchema`, `WorkflowEdgeSchema`
-- `WorkflowRunSchema`, `WorkflowRunStepSchema`
-- `ScheduledTaskSchema`
-- `SwarmConfigSchema`, `SwarmConfigScopeSchema`
-- `SwarmRepoSchema`
-- `AgentMemorySchema`, `AgentMemoryScopeSchema`, `AgentMemorySourceSchema`
-- `ChannelSchema`, `ChannelMessageSchema`, `ChannelTypeSchema`
-- `ServiceSchema`, `ServiceStatusSchema`
-- `SessionLogSchema`, `SessionCostSchema`
-- `ActiveSessionSchema`
-- `AgentLogSchema`, `AgentLogEventTypeSchema`
-- `ContextVersionSchema`, `ChangeSourceSchema`, `VersionableFieldSchema`
-- `InboxMessageSchema`, `InboxMessageStatusSchema`
-
-These schemas represent ~70% of the OpenAPI component definitions needed.
-
-### 3. Recommended Approach: `@asteasolutions/zod-to-openapi` + Script
-
-#### Library: `@asteasolutions/zod-to-openapi`
-
-- **Maturity**: ~1.7M weekly npm downloads, ~1,500 GitHub stars, MIT license
-- **How it works**: Framework-agnostic. Provides `OpenAPIRegistry` to register schemas and paths, then `OpenApiGeneratorV31` to emit a plain JS object (the OpenAPI spec)
-- **Key API**:
-  - `extendZodWithOpenApi(z)` — adds `.openapi()` method to Zod types
-  - `registry.register(name, zodSchema)` — register component schema
-  - `registry.registerPath({method, path, request, responses})` — register endpoint
-  - `generator.generateDocument(config)` — produce full OpenAPI spec object
-- **Zod compatibility**: v7.x for Zod v3 (which agent-swarm uses), v8.x for Zod v4
-
-#### Script Pattern: `scripts/generate-openapi.ts`
-
-Create a script analogous to `scripts/generate-mcp-docs.ts` that:
-
-1. Imports all Zod schemas from `src/types.ts`
-2. Extends them with `.openapi()` metadata (names, examples, descriptions)
-3. Defines route registrations for all 62 endpoints using `registry.registerPath()`
-4. Generates the full OpenAPI 3.1.0 spec
-5. Writes to `openapi.json` (and optionally `API.md` for markdown reference)
-
-**Route definition approach**: Create a `src/http/openapi-routes.ts` file that defines all route metadata in a declarative structure:
-
-```typescript
-import { OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
-import { AgentTaskSchema, AgentSchema, ... } from "../types";
-
-export function registerRoutes(registry: OpenAPIRegistry) {
-  // ── Tasks ──
-  registry.registerPath({
-    method: "get",
-    path: "/api/tasks",
-    summary: "List tasks",
-    request: {
-      query: z.object({
-        status: AgentTaskStatusSchema.optional(),
-        agentId: z.string().uuid().optional(),
-        epicId: z.string().uuid().optional(),
-        limit: z.number().int().optional(),
-        offset: z.number().int().optional(),
-      }),
-    },
-    responses: {
-      200: {
-        description: "Task list",
-        content: {
-          "application/json": {
-            schema: z.object({
-              tasks: z.array(AgentTaskSchema),
-              total: z.number(),
-            }),
-          },
-        },
-      },
-    },
-  });
-  // ... more routes
-}
-```
-
-**CI enforcement**: Add to `.github/workflows/merge-gate.yml`:
-```yaml
-- name: Check OpenAPI freshness
-  run: |
-    bun run docs:openapi
-    git diff --exit-code openapi.json
-```
-
-#### Alternative considered: `zod-openapi` (by samchungy)
-
-- Uses Zod's native `.meta()` instead of extending prototypes
-- Smaller community (~121 dependents vs 1.7M downloads)
-- Cleaner approach but less battle-tested
-- **Verdict**: `@asteasolutions/zod-to-openapi` is the safer choice for a production project
-
-### 4. Docs Viewer: Scalar
-
-**Recommendation: Scalar** — zero npm dependencies, single CDN script, modern UI.
-
-| Feature | Scalar | Swagger UI | Redoc | RapiDoc |
-|---------|--------|-----------|-------|---------|
-| CDN files needed | 1 (JS) | 2 (JS+CSS) | 1 (JS) | 1 (JS) |
-| "Try It" client | Yes | Yes | Paid only | Yes |
-| UI quality | Excellent | Dated | Excellent | Good |
-| Bundle size | ~1MB | ~1.5MB | ~800KB | ~300KB |
-| Maintenance | Very active | Moderate | Active | Low |
-
-**Integration** — serve a static HTML page at `/docs`:
-
-```typescript
-const DOCS_HTML = `<!doctype html>
-<html>
-<head>
-  <title>Agent Swarm API</title>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-</head>
-<body>
-  <div id="app"></div>
-  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
-  <script>
-    Scalar.createApiReference('#app', { url: '/openapi.json' })
-  </script>
-</body>
-</html>`;
-```
-
-Add to `handleCore` in `src/http/core.ts`:
-```typescript
-if (req.url === "/docs") {
-  res.writeHead(200, { "Content-Type": "text/html" });
-  res.end(DOCS_HTML);
-  return true;
-}
-if (req.url === "/openapi.json") {
-  res.writeHead(200, { "Content-Type": "application/json" });
-  res.end(await Bun.file("openapi.json").text());
-  return true;
-}
-```
-
-No npm install required. No CSS file. Same-origin means no CORS issues. Dark mode and themes built in.
-
-### 5. Hono Migration: NOT Recommended
-
-A thorough evaluation of migrating to Hono for OpenAPI concluded it's **not worth it**:
-
-| Factor | Assessment |
-|--------|-----------|
-| Migration effort | High: 77 `matchRoute()` calls across 14 files, full rewrite |
-| OpenAPI "automation" | Misleading: `@hono/zod-openapi` still requires manual Zod schemas per route |
-| MCP compatibility | Solvable via `@hono/mcp` but changes integration pattern |
-| Performance | Would actually improve (ironic — `Bun.serve()` > `node:http` compat) |
-| Incremental path | Poor: essentially all-or-nothing |
-
-**Key insight**: Hono's OpenAPI integration (`@hono/zod-openapi`) requires rewriting every route with `createRoute()` and adding schema annotations to every endpoint. You'd be paying the migration cost AND still writing all the schemas manually. The script-based `zod-to-openapi` approach achieves the same result without touching any runtime code.
-
-**If Hono migration is desired later** (for framework benefits, not OpenAPI), it should be a separate initiative budgeting 3-4 days. Hono is already in `package.json` (used by artifact SDK), and `@hono/mcp` exists for the MCP transport.
-
-### 6. Existing Docs Pattern: `generate-mcp-docs.ts`
-
-The project already has a precedent: `scripts/generate-mcp-docs.ts` (`bun run docs:mcp`):
-
-- Discovers tool categories from `src/server.ts`
-- Discovers tool files via glob in `src/tools/`
-- Parses Zod schema fields from each tool file (regex-based extraction)
-- Generates `MCP.md` with tables for each tool's parameters
-
-The OpenAPI generation script should follow the same pattern:
-- `bun run docs:openapi` — generates `openapi.json`
-- CI freshness check — `git diff --exit-code openapi.json`
-- Same location in `scripts/` directory
-
-## Code References
-
-| File | Line | Description |
-|------|------|-------------|
-| `src/http/index.ts` | 52-115 | Main HTTP server + handler chain |
-| `src/http/utils.ts` | 69-87 | `matchRoute()` function |
-| `src/http/utils.ts` | 40-58 | `parseBody()`, `json()`, `jsonError()` helpers |
-| `src/http/core.ts` | 36-278 | Core routes (health, auth, me, ping, close) |
-| `src/types.ts` | 1-643 | All 28 Zod schemas |
-| `scripts/generate-mcp-docs.ts` | 1-416 | MCP docs generator (pattern to follow) |
-| `src/tools/send-task.ts` | 16-40 | Example MCP tool with Zod inputSchema |
-
-## Architecture Documentation
-
-### Authentication Model
-- API key via `Authorization: Bearer <API_KEY>` (env-based, optional)
-- Agent identity via `X-Agent-ID` header (required for agent-scoped operations)
-- Webhook routes skip API key auth, use their own signature verification
-- No role-based access control at HTTP layer
-
-### Handler Chain Pattern
-1. `handleCore` runs first — handles OPTIONS, `/health` (pre-auth), auth gate, then `/me`, `/cancelled-tasks`, `/ping`, `/close`
-2. Remaining handlers iterate in order (lines 89-106) — first match wins
-3. 404 returned if no handler matches
-
-### Request/Response Conventions
-- JSON responses with `Content-Type: application/json`
-- List endpoints return `{ items: T[], total?: number }`
-- Create endpoints return 201 with created object
-- Delete endpoints return `{ success: true }` or 204
-- Errors return `{ error: string }` with appropriate status code
-
-## Historical Context
-
-No prior research exists on API documentation for this project. The `MCP.md` auto-generation pattern (commit history) was established as the project's documentation convention and should be extended to cover the REST API.
-
-## Related Research
-- No directly related research documents exist in `thoughts/taras/research/`
-
-## Open Questions
-
-> **Resolved**: All endpoints should be documented in the OpenAPI spec. For the initial research catalog/map we can skip some, but the spec itself should be comprehensive.
-
-- ~~Should the OpenAPI spec cover webhook endpoints?~~ **Yes** — document all endpoints. Webhooks can be tagged separately and note their different auth model (signature verification vs Bearer token)
-- ~~Should internal endpoints be included?~~ **Yes** — mark with `x-internal: true` or tag as "Internal" so Scalar can visually distinguish them
-- Should the MCP endpoint (`/mcp`) be documented in the OpenAPI spec, or kept separate in `MCP.md`? The JSON-RPC protocol doesn't map cleanly to REST — **Recommendation: keep separate**, just link to `MCP.md` from the spec description
-- What level of response schema detail is needed? Some endpoints return complex nested objects (e.g., `GET /api/poll` returns different shapes based on trigger type) — use `oneOf` / discriminated unions where appropriate
-
-## Proposed Implementation Plan
-
-### Phase 1: OpenAPI Spec Generation Script
-
-**Estimated file sizes:**
-- `src/openapi/schemas.ts` — ~200-300 lines. Imports the 28 existing Zod schemas from `src/types.ts` and registers them with `.openapi("Name")` metadata. Mostly boilerplate wrapping
-- `src/openapi/routes.ts` — ~1,500-2,000 lines. The bulk of the work: 62 `registry.registerPath()` calls, each ~25-35 lines (method, path, summary, tags, request params/body, response schema). This is the tedious-but-straightforward part
-- `scripts/generate-openapi.ts` — ~50-80 lines. Imports schemas + routes, calls `generateDocument()`, writes to file
-- Generated `openapi.json` — ~3,000-5,000 lines (typical for 62 endpoints with full schemas). For reference, a 40-endpoint API typically produces ~100-150KB of OpenAPI JSON
-
-**Steps:**
-1. Install `@asteasolutions/zod-to-openapi`
-2. Create `src/openapi/schemas.ts` — register existing Zod schemas with OpenAPI metadata
-3. Create `src/openapi/routes.ts` — declarative route definitions for all 62 endpoints
-4. Create `scripts/generate-openapi.ts` — generates `openapi.json`
-5. Add `"docs:openapi": "bun scripts/generate-openapi.ts"` to `package.json`
-
-### Phase 2: Docs Viewer
-1. Add `/openapi.json` endpoint in `src/http/core.ts` (serves generated file)
-2. Add `/docs` endpoint in `src/http/core.ts` (serves Scalar HTML)
-3. Both endpoints are pre-auth (like `/health`)
-
-### Phase 3: CI Integration — No-Drift Guarantee
-
-The spec is generated from code, so drift is prevented by treating the generated `openapi.json` as a build artifact with a CI freshness check:
-
-1. **Merge gate step** — Add to `.github/workflows/merge-gate.yml`:
-   ```yaml
-   - name: Check OpenAPI spec freshness
-     run: |
-       bun run docs:openapi
-       git diff --exit-code openapi.json || {
-         echo "::error::openapi.json is out of date. Run 'bun run docs:openapi' and commit the result."
-         exit 1
-       }
-   ```
-   This is the same pattern used for `bun run build:pi-skills` freshness enforcement.
-
-2. **Pre-PR checklist** — Add `bun run docs:openapi` to `CLAUDE.md` pre-PR checklist alongside `bun run lint:fix` and `bun run tsc:check`
-
-3. **How it works**: When a developer adds/changes an endpoint in `src/http/*.ts`, they must also update the corresponding route definition in `src/openapi/routes.ts` and regenerate. If they forget, CI fails. The Zod schemas in `src/types.ts` are imported directly (not duplicated), so schema changes automatically flow through on next `bun run docs:openapi`.
-
-### Estimated Effort
-- Phase 1: The bulk of the work (~80%). `routes.ts` at ~1,500-2,000 lines is tedious but mechanical — each endpoint is ~30 lines of declarative metadata
-- Phase 2: ~20 lines of code
-- Phase 3: ~5 lines of YAML + docs update