macro-agent 0.2.5 → 0.2.6

package/docs/configuration.md

@@ -1,323 +0,0 @@
-# Configuration Reference
-
-Complete reference for configuring macro-agent.
-
-## Environment Variables
-
-### Task Backend
-
-| Variable | Description | Values | Default |
-|----------|-------------|--------|---------|
-| `MACRO_TASK_BACKEND` | Task backend type | `memory`, `opentasks` | `memory` |
-| `OPENTASKS_SOCKET_PATH` | Path to OpenTasks socket | Socket path | — |
-
-### Agent Subprocess
-
-These are set automatically when spawning agent subprocesses:
-
-| Variable | Description |
-|----------|-------------|
-| `MACRO_AGENT_ID` | Agent's unique identifier |
-| `MACRO_PARENT_ID` | Parent agent's ID (if any) |
-| `MACRO_TASK_ID` | Assigned task ID (if any) |
-| `MACRO_AGENT_CWD` | Working directory for this agent |
-| `MACRO_INSTANCE_ID` | Global instance identifier |
-| `MACRO_AGENT_SERVER_ONLY` | Set to `1` for server-only mode |
-
-### Testing
-
-| Variable | Description | Values | Default |
-|----------|-------------|--------|---------|
-| `RUN_E2E_TESTS` | Enable E2E tests | `true`, `1` | (disabled) |
-| `DEBUG_E2E` | Enable E2E test debugging | `true`, `1` | (disabled) |
-| `ANTHROPIC_API_KEY` | API key for integration tests | API key | (required for e2e) |
-
-## Programmatic Configuration
-
-### Task Backend Configuration
-
-```typescript
-import { createTaskBackend, loadTaskConfigFromEnv } from 'macro-agent';
-
-// Load from environment
-const config = loadTaskConfigFromEnv();
-
-// Or configure manually
-const config = {
-  backend: {
-    type: 'memory',
-  },
-};
-
-const { backend, openTasksClient } = await createTaskBackend(config, eventStore);
-```
-
-### InMemory Backend Config
-
-```typescript
-interface InMemoryBackendConfig {
-  type: 'memory';
-}
-```
-
-### OpenTasks Backend Config
-
-```typescript
-interface OpenTasksBackendConfig {
-  type: 'opentasks';
-
-  /** Path to OpenTasks socket */
-  socketPath?: string;
-}
-```
-
-## Workspace Configuration
-
-### Dataplane Config
-
-```typescript
-interface DataplaneConfig {
-  /** Whether dataplane is enabled */
-  enabled: boolean;
-
-  /** Path to the git repository */
-  repoPath?: string;
-
-  /** Table prefix for dataplane tables */
-  tablePrefix?: string;  // Default: 'dataplane_'
-
-  /** Path to SQLite database file */
-  dbPath?: string;
-
-  /** Existing database connection to share */
-  db?: Database.Database;
-
-  /** Enable verbose logging */
-  verbose?: boolean;  // Default: false
-
-  /** Skip recovery process on startup */
-  skipRecovery?: boolean;  // Default: false
-}
-```
-
-### Workspace Directory Config
-
-```typescript
-interface WorkspaceDirectoryConfig {
-  /** Base directory for worktrees */
-  worktreeDir?: string;  // Default: <repoPath>/.worktrees
-
-  /** Maximum number of concurrent worktrees */
-  maxWorktrees?: number;  // Default: 50
-
-  /** Use themed names for worktree directories */
-  useThemedNames?: boolean;  // Default: false
-
-  /** Custom themed names for worktree directories */
-  themedNames?: string[];
-}
-```
-
-## Agent Manager Configuration
-
-```typescript
-interface AgentManagerConfig {
-  /** Default permission mode for spawned agents */
-  defaultPermissionMode?: PermissionMode;
-
-  /** Maximum agents allowed in hierarchy */
-  maxAgents?: number;
-
-  /** Timeout for agent spawn operations (ms) */
-  spawnTimeout?: number;
-}
-
-type PermissionMode =
-  | 'auto-approve'  // All tool calls approved automatically
-  | 'auto-deny'     // All tool calls denied
-  | 'callback'      // External system decides
-  | 'interactive';  // User prompted for each call
-```
-
-## API Server Configuration
-
-### CLI Options
-
-```bash
-# Server (default mode runs full ACP + MAP + REST)
-multiagent [options]
-  --port <port>               Port (default: 3001)
-  --host <host>               Host (default: localhost)
-  --cwd <path>                Working directory
-  --acp                       Stdio ACP-only mode (for acp-factory)
-
-# CLI tools (for management/inspection)
-multiagent-cli start [options]
-  -p, --port <port>           Port (default: 3000)
-  -h, --host <host>           Host (default: localhost)
-  --cwd <path>                Working directory
-```
-
-### Programmatic API Server
-
-```typescript
-import { createAPIServer, createAPIApp } from 'macro-agent';
-
-// Full server with WebSocket
-const { app, server, wss } = createAPIServer({
-  eventStore,
-  agentManager,
-  taskManager,
-  messageRouter,
-});
-
-server.listen(3000);
-
-// Express app only (for custom server setup)
-const app = createAPIApp({
-  eventStore,
-  agentManager,
-  taskManager,
-  messageRouter,
-});
-```
-
-## Event Store Configuration
-
-```typescript
-import { createEventStore } from 'macro-agent';
-
-// In-memory store (for unit testing only)
-// ⚠️ WARNING: MCP tools (done, spawn_agent, etc.) will NOT work with in-memory storage
-// because MCP servers run as separate subprocesses that cannot access in-memory data.
-const eventStore = await createEventStore({ inMemory: true });
-
-// SQLite store (for production - required for MCP tools)
-const eventStore = await createEventStore({
-  instanceId: 'my-project',
-  baseDir: './data',
-});
-
-// Legacy path option (deprecated)
-const eventStore = await createEventStore({
-  path: './data/events.json', // Use instanceId + baseDir instead
-});
-```
-
-> **Important**: Always use file-based storage (SQLite) for workflows that involve real agents with MCP tools. The `inMemory` option is only suitable for unit tests that don't spawn actual Claude Code processes.
-
-## Message Router Configuration
-
-```typescript
-import { createMessageRouter } from 'macro-agent';
-
-const messageRouter = createMessageRouter(eventStore, {
-  /** Default message priority */
-  defaultPriority: 'normal',
-
-  /** Enable activity waking for monitors */
-  enableActivityWaking: true,
-});
-```
-
-### Priority Levels
-
-| Priority | Description |
-|----------|-------------|
-| `urgent` | Immediate delivery, interrupts current work |
-| `high` | High priority, processed before normal |
-| `normal` | Standard priority (default) |
-| `low` | Background messages |
-
-## Task Tool Provider
-
-The unified task tool provider exposes 7 MCP tools to agents:
-
-| Tool | Always Available | OpenTasks Only | Pull Mode Only |
-|------|------------------|----------------|----------------|
-| `create_task` | ✓ | | |
-| `get_task` | ✓ | | |
-| `list_tasks` | ✓ | | |
-| `assign_task` | ✓ | | |
-| `task` (upsert) | | ✓ | |
-| `link` | | ✓ | |
-| `annotate` | | ✓ | |
-| `claim_task` | | | ✓ |
-| `unclaim_task` | | | ✓ |
-| `list_claimable_tasks` | | | ✓ |
-
-## Example Configurations
-
-### Development (In-Memory)
-
-```bash
-# Start full server with default settings
-npx multiagent
-```
-
-### Production with OpenTasks
-
-```bash
-export MACRO_TASK_BACKEND=opentasks
-export OPENTASKS_SOCKET_PATH=/path/to/socket
-
-npx multiagent --port 3001
-```
-
-### Server Mode (Default)
-
-```bash
-# Full server with ACP + MAP + REST API
-npx multiagent --port 3001 --host 0.0.0.0
-
-# Endpoints available:
-#   ws://host:port/acp      - ACP protocol
-#   ws://host:port/map      - MAP protocol
-#   ws://host:port/api/ws   - Real-time subscriptions
-#   http://host:port/api/*  - REST API
-```
-
-### Stdio ACP Mode (for acp-factory)
-
-```bash
-# For embedded use with acp-factory
-npx multiagent --acp --cwd /path/to/project
-```
-
-### Programmatic Full Setup
-
-```typescript
-import {
-  createEventStore,
-  createAgentManager,
-  createMessageRouter,
-  createTaskBackend,
-  loadTaskConfigFromEnv,
-  createAPIServer,
-} from 'macro-agent';
-
-// Initialize stores
-const eventStore = await createEventStore({ dbPath: './data/events.db' });
-
-// Initialize services
-const messageRouter = createMessageRouter(eventStore);
-const taskConfig = loadTaskConfigFromEnv();
-const { backend: taskBackend, openTasksClient } = await createTaskBackend(taskConfig, eventStore);
-
-// Initialize agent manager
-const agentManager = createAgentManager(eventStore, messageRouter, {
-  defaultPermissionMode: 'auto-approve',
-});
-
-// Start API server
-const { server } = createAPIServer({
-  eventStore,
-  agentManager,
-  taskManager: taskBackend,
-  messageRouter,
-});
-
-server.listen(3000, () => {
-  console.log('macro-agent running on port 3000');
-});
-```