Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

41.8 KB
Raw Blame
import { requireOwner } from '../owner-gate.js';
import { trackStream } from '../../security/live-streams.js';
import { principalKey, principalOf } from '../middleware.js';
import { Hono } from 'hono';
import { readFileSync, existsSync, statSync } from 'node:fs';
import { generateText } from 'ai';
import type { SubAgentSupervisor } from '../../core/supervisor.js';
import type { BoardManager } from '../../core/board-manager.js';
import type { ProviderRegistry } from '../../providers/registry.js';

const app = new Hono();

// Normalize backend card statuses to the frontend-expected values
// Backend uses: pending, running, paused, completed, failed, halted
// Frontend expects: pending, running, paused, done, failed
function normalizeCardStatus(status: string): string {
  if (status === 'completed' || status === 'halted') return 'done';
  return status;
}

function normalizeCard(card: any): any {
  return {
    ...card,
    status: normalizeCardStatus(card.status),
    tokensUsed: card.tokenUsage?.total ?? card.tokensUsed,
    tokenUsage: card.tokenUsage ?? null,
    tokenBudget: card.tokenBudget ?? null,
    pausedForTokens: card.pausedForTokens ?? false,
    createdAt: card.createdAt ?? card.startedAt ?? new Date().toISOString(),
    labels: card.labels ?? [],
    comments: card.comments ?? [],
    attachments: card.attachments ?? [],
    parentId: card.parentId ?? null,
    dependsOn: card.dependsOn ?? [],
    activityLog: card.activityLog ?? [],
  };
}

function normalizeBoard(board: any): any {
  return {
    ...board,
    active: board.status === 'active',
    cards: (board.cards ?? []).map(normalizeCard),
    createdAt: typeof board.createdAt === 'number' ? new Date(board.createdAt).toISOString() : board.createdAt,
  };
}

let supervisor: SubAgentSupervisor | undefined;
let boardManager: BoardManager | undefined;
let providerRegistry: ProviderRegistry | undefined;

// Maps cardId -> agentId for tracking runtime agent execution
const cardAgentMap: Map<string, string> = new Map();
// Reverse: agentId -> { boardId, cardId }
const agentCardMap: Map<string, { boardId: string; cardId: string }> = new Map();

export function setKanbanSupervisor(s: SubAgentSupervisor): void {
  supervisor = s;
}

export function setKanbanBoardManager(bm: BoardManager): void {
  boardManager = bm;
  // Hook into board changes for SSE
  bm.onBoardChange((boardId) => {
    emitBoardUpdate(boardId);
  });
}

export function setKanbanProviders(pr: ProviderRegistry): void {
  providerRegistry = pr;
}

export function getAgentCardMap(): Map<string, { boardId: string; cardId: string }> {
  return agentCardMap;
}

// ── SSE Board Events ─────────────────────────────────────────
// Clients subscribe to /api/boards/:id/events for real-time updates

type SSEClient = { boardId: string; controller: ReadableStreamDefaultController; encoder: InstanceType<typeof TextEncoder> };
const sseClients: Set<SSEClient> = new Set();

/** Debounced SSE emission — avoids flooding clients on rapid progress ticks */
const sseDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
const SSE_DEBOUNCE_MS = 800; // At most one update per 800ms per board

/** Broadcast a board update event to all SSE clients watching that board */
export function emitBoardUpdate(boardId: string, event: string = 'board-update', data?: any): void {
  if (!boardManager) return;

  // Feedback requests bypass debounce (user needs to see them immediately)
  if (event === 'feedback-request') {
    doEmit(boardId, event, data);
    return;
  }

  // Debounce regular board updates
  const existing = sseDebounceTimers.get(boardId);
  if (existing) clearTimeout(existing);
  sseDebounceTimers.set(boardId, setTimeout(() => {
    sseDebounceTimers.delete(boardId);
    doEmit(boardId, event, data);
  }, SSE_DEBOUNCE_MS));
}

function doEmit(boardId: string, event: string, data?: any): void {
  const board = boardManager!.getBoard(boardId);
  if (!board) return;
  const payload = data ?? normalizeBoard(board);
  for (const client of sseClients) {
    if (client.boardId !== boardId) continue;
    try {
      client.controller.enqueue(client.encoder.encode(`event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`));
    } catch {
      sseClients.delete(client);
    }
  }
}

app.get('/api/boards/:id/events', (c: any) => {
  const boardId = c.req.param('id');
  if (!boardManager) return c.json({ error: 'Board manager not available' }, 503);

  const stream = new ReadableStream({
    start(controller) {
      const encoder = new TextEncoder();
      const client: SSEClient = { boardId, controller, encoder };
      sseClients.add(client);

      // Send initial state
      const board = boardManager!.getBoard(boardId);
      if (board) {
        try {
          controller.enqueue(encoder.encode(`event: board-update\ndata: ${JSON.stringify(normalizeBoard(board))}\n\n`));
        } catch {}
      }

      // Keepalive
      const keepalive = setInterval(() => {
        try { controller.enqueue(encoder.encode(': keepalive\n\n')); } catch { clearInterval(keepalive); sseClients.delete(client); }
      }, 15000);

      // Cleanup on close (controller error signals disconnect)
      const cleanup = () => { clearInterval(keepalive); sseClients.delete(client); untrack(); };
      const untrack = trackStream(principalKey(principalOf(c)), () => { cleanup(); try { controller.close(); } catch { /* closed */ } });
      c.req.raw.signal?.addEventListener('abort', cleanup);
    },
    cancel() {}
  });

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  });
});

// ══════════════════════════════════════════════════════════
// Board CRUD
// ══════════════════════════════════════════════════════════

// List all boards
app.get('/api/boards', (c: any) => {
  if (!boardManager) return c.json({ boards: [], available: false });
  const boards = boardManager.getAllBoards().map(b => {
    const nb = normalizeBoard(b);
    return {
      ...nb,
      cardCount: b.cards.length,
      pendingCount: b.cards.filter((c: any) => c.status === 'pending').length,
      runningCount: b.cards.filter((c: any) => c.status === 'running').length,
      doneCount: b.cards.filter((c: any) => c.status === 'completed' || c.status === 'failed' || c.status === 'halted').length,
    };
  });
  return c.json({ boards, available: true });
});

// Get single board with cards
app.get('/api/boards/:id', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const board = boardManager.getBoard(c.req.param('id'));
  if (!board) return c.json({ error: 'Board not found' }, 404);

  const sysResources = supervisor ? supervisor.getResourceUsage() : null;
  const nb = normalizeBoard(board);
  // Transform to frontend-expected BoardResources shape
  const resources = {
    totalTokens: nb.cards.reduce((sum: number, c: any) => sum + (c.tokensUsed ?? 0), 0),
    runningCount: nb.cards.filter((c: any) => c.status === 'running').length,
    pendingCount: nb.cards.filter((c: any) => c.status === 'pending' || c.status === 'paused').length,
    doneCount: nb.cards.filter((c: any) => c.status === 'done').length,
    failedCount: nb.cards.filter((c: any) => c.status === 'failed').length,
    ...(sysResources ? { system: sysResources } : {}),
  };
  return c.json({ board: nb, resources });
});

// Create board
app.post('/api/boards', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { name, description } = body;
  if (!name || typeof name !== 'string' || name.trim().length === 0) {
    return c.json({ error: 'Board name required' }, 400);
  }
  const board = boardManager.createBoard(name.trim(), (description || '').trim());
  return c.json({ ok: true, board });
});

// Update board
app.patch('/api/boards/:id', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const board = boardManager.updateBoard(c.req.param('id'), body);
  if (!board) return c.json({ error: 'Board not found' }, 404);
  return c.json({ ok: true, board });
});

// Delete board
app.delete('/api/boards/:id', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const deleted = boardManager.deleteBoard(c.req.param('id'));
  if (!deleted) return c.json({ error: 'Cannot delete board (not found or has running agents)' }, 400);
  return c.json({ ok: true });
});

// Activate board
app.post('/api/boards/:id/activate', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const activated = boardManager.activateBoard(c.req.param('id'));
  if (!activated) return c.json({ error: 'Cannot activate (another board has running agents)' }, 400);
  return c.json({ ok: true });
});

// Deactivate board
app.post('/api/boards/:id/deactivate', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const deactivated = boardManager.deactivateBoard(c.req.param('id'));
  if (!deactivated) return c.json({ error: 'Cannot deactivate (has running agents)' }, 400);
  return c.json({ ok: true });
});

// Generate cards from board description using LLM (with dependency tree)
app.post('/api/boards/:id/generate', async (c: any) => {
  if (!boardManager || !providerRegistry) {
    return c.json({ error: 'Not available' }, 400);
  }

  const boardId = c.req.param('id');
  const board = boardManager.getBoard(boardId);
  if (!board) return c.json({ error: 'Board not found' }, 404);

  if (!board.description || board.description.trim().length === 0) {
    return c.json({ error: 'Board needs a description to generate cards from' }, 400);
  }

  try {
    const provider = providerRegistry.getDefault();
    const result = await generateText({
      model: provider.getModelInstance(),
      system: `You are a project planning assistant. Given a board description, break it down into a dependency tree of task cards for an AI coding agent to execute.

Rules:
- Create parent tasks for major features/milestones and child tasks for their implementation steps
- Each task should be a single, focused unit of work
- Child tasks should reference their parent by index (0-based) in the "parentIndex" field
- Tasks with dependencies should list the indices they depend on in "dependsOnIndices"
- Root tasks (no parent) should have parentIndex: null
- Order tasks logically — parents before children, dependencies before dependents
- Assign priority: "high" for critical/blocking tasks, "normal" for standard work, "low" for nice-to-haves
- Return ONLY valid JSON, no markdown fences, no explanation

Return a JSON array of objects:
{
  "task": "description",
  "priority": "high"|"normal"|"low",
  "parentIndex": number|null,
  "dependsOnIndices": number[]
}

Example:
[
  {"task":"Set up database schema for users","priority":"high","parentIndex":null,"dependsOnIndices":[]},
  {"task":"Create user model and migrations","priority":"high","parentIndex":0,"dependsOnIndices":[0]},
  {"task":"Build authentication endpoints","priority":"high","parentIndex":0,"dependsOnIndices":[1]},
  {"task":"Set up frontend routing","priority":"normal","parentIndex":null,"dependsOnIndices":[]},
  {"task":"Build login page UI","priority":"normal","parentIndex":3,"dependsOnIndices":[2,3]}
]`,
      messages: [
        {
          role: 'user',
          content: `Board: "${board.name}"\n\nDescription:\n${board.description}\n\nGenerate task cards with parent-child relationships and dependencies for this board.`,
        },
      ],
    });

    const text = (result.text || '').trim();

    // Parse the JSON response — handle markdown fences if present
    let jsonStr = text;
    const fenceMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
    if (fenceMatch) {
      jsonStr = fenceMatch[1].trim();
    }

    let rawCards: Array<{ task: string; priority?: string; parentIndex?: number | null; dependsOnIndices?: number[] }>;
    try {
      rawCards = JSON.parse(jsonStr);
    } catch {
      return c.json({ error: 'Failed to parse generated cards. LLM response was not valid JSON.', raw: text }, 500);
    }

    if (!Array.isArray(rawCards) || rawCards.length === 0) {
      return c.json({ error: 'No cards generated', raw: text }, 500);
    }

    // Validate and sanitize
    const validCards = rawCards
      .filter(c => c && typeof c.task === 'string' && c.task.trim().length > 0)
      .map(c => ({
        task: c.task.trim(),
        priority: (['high', 'normal', 'low'].includes(c.priority || '') ? c.priority : 'normal') as 'high' | 'normal' | 'low',
        parentIndex: typeof c.parentIndex === 'number' ? c.parentIndex : null,
        dependsOnIndices: Array.isArray(c.dependsOnIndices) ? c.dependsOnIndices.filter(i => typeof i === 'number') : [],
      }));

    if (validCards.length === 0) {
      return c.json({ error: 'No valid cards in generated output', raw: text }, 500);
    }

    // First pass: create all cards (without deps)
    const created = boardManager.addCards(boardId, validCards.map(c => ({ task: c.task, priority: c.priority })));

    // Second pass: wire up parentId and dependsOn using the created card IDs
    for (let i = 0; i < validCards.length; i++) {
      const spec = validCards[i];
      const card = created[i];
      if (!card) continue;

      // Set parent
      if (spec.parentIndex !== null && spec.parentIndex >= 0 && spec.parentIndex < created.length && spec.parentIndex !== i) {
        const parentCard = created[spec.parentIndex];
        if (parentCard) {
          boardManager.setParent(boardId, card.id, parentCard.id);
        }
      }

      // Set dependsOn
      for (const depIdx of spec.dependsOnIndices) {
        if (depIdx >= 0 && depIdx < created.length && depIdx !== i) {
          const depCard = created[depIdx];
          if (depCard) {
            boardManager.addDependency(boardId, card.id, depCard.id);
          }
        }
      }
    }

    // Re-fetch cards after wiring deps
    const updatedBoard = boardManager.getBoard(boardId);
    const finalCards = updatedBoard ? updatedBoard.cards.slice(-created.length).map(normalizeCard) : created.map(normalizeCard);

    return c.json({ ok: true, cards: finalCards, count: created.length });
  } catch (err: any) {
    return c.json({ error: 'Generation failed: ' + (err.message || 'unknown error') }, 500);
  }
});

// ══════════════════════════════════════════════════════════
// Card CRUD
// ══════════════════════════════════════════════════════════

// Add card to board
app.post('/api/boards/:id/cards', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { task, priority, tokenBudget } = body;
  if (!task || typeof task !== 'string' || task.trim().length === 0) {
    return c.json({ error: 'Task description required' }, 400);
  }
  const card = boardManager.addCard(c.req.param('id'), task.trim(), priority || 'normal');
  if (!card) return c.json({ error: 'Board not found' }, 404);
  // Set token budget if provided
  if (tokenBudget && typeof tokenBudget === 'number' && tokenBudget > 0) {
    card.tokenBudget = tokenBudget;
  }
  return c.json({ ok: true, card: normalizeCard(card) });
});

// Add multiple cards
app.post('/api/boards/:id/cards/bulk', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { cards } = body;
  if (!Array.isArray(cards) || cards.length === 0) {
    return c.json({ error: 'Cards array required' }, 400);
  }
  const created = boardManager.addCards(c.req.param('id'), cards);
  if (created.length === 0) return c.json({ error: 'Board not found' }, 404);
  return c.json({ ok: true, cards: created.map(normalizeCard) });
});

// Update card
app.patch('/api/boards/:boardId/cards/:cardId', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const card = boardManager.updateCard(c.req.param('boardId'), c.req.param('cardId'), body);
  if (!card) return c.json({ error: 'Card not found' }, 404);
  return c.json({ ok: true, card: normalizeCard(card) });
});

// Delete card
app.delete('/api/boards/:boardId/cards/:cardId', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const deleted = boardManager.deleteCard(c.req.param('boardId'), c.req.param('cardId'));
  if (!deleted) return c.json({ error: 'Cannot delete card (not found or running)' }, 400);
  return c.json({ ok: true });
});

// Reorder cards
app.post('/api/boards/:id/cards/reorder', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { cardIds } = body;
  if (!Array.isArray(cardIds)) return c.json({ error: 'cardIds array required' }, 400);
  const ok = boardManager.reorderCards(c.req.param('id'), cardIds);
  return c.json({ ok });
});

// Clear done cards
app.post('/api/boards/:id/cards/clear-done', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const cleared = boardManager.clearDoneCards(c.req.param('id'));
  return c.json({ ok: true, cleared });
});

// ══════════════════════════════════════════════════════════
// Card Execution (spawn agent for a card)
// ══════════════════════════════════════════════════════════

// Execute a single card
app.post('/api/boards/:boardId/cards/:cardId/run', async (c: any) => {
  if (!boardManager || !supervisor) return c.json({ error: 'Not available' }, 400);

  const boardId = c.req.param('boardId');
  const cardId = c.req.param('cardId');

  const board = boardManager.getBoard(boardId);
  if (!board) return c.json({ error: 'Board not found' }, 404);
  if (board.status !== 'active') return c.json({ error: 'Board is not active. Activate it first.' }, 400);

  const card = board.cards.find(cc => cc.id === cardId);
  if (!card) return c.json({ error: 'Card not found' }, 404);
  if (card.status === 'running') {
    return c.json({ error: 'Card is already running' }, 400);
  }

  const body = await c.req.json().catch(() => ({}));

  // If resuming a token-paused card, allow budget override
  if (card.pausedForTokens && body.tokenBudget) {
    boardManager.updateCard(boardId, cardId, { tokenBudget: body.tokenBudget, pausedForTokens: false } as any);
  } else if (card.pausedForTokens && body.overrideBudget) {
    // Remove budget entirely
    boardManager.updateCard(boardId, cardId, { tokenBudget: undefined, pausedForTokens: false } as any);
  } else if (card.pausedForTokens) {
    // Clear the flag so it can re-run (with same budget — will pause again if still over)
    boardManager.updateCard(boardId, cardId, { pausedForTokens: false } as any);
  }

  // Build board context for inter-card sharing
  const boardContext = boardManager.buildCardContext(boardId, cardId);
  const taskWithContext = boardContext ? `${card.task}\n${boardContext}` : card.task;
  const ctx = boardManager.getBoardContext(boardId);

  const agentId = await supervisor.spawn({
    task: taskWithContext,
    priority: card.priority,
    maxSteps: body.maxSteps || 25,
    sourceChannelType: 'web',
    sourceChannelId: `board:${boardId}`,
    workingDirectory: ctx?.workingDirectory,
  });

  // Track mapping
  cardAgentMap.set(cardId, agentId);
  agentCardMap.set(agentId, { boardId, cardId });

  // Update card status
  boardManager.updateCard(boardId, cardId, {
    status: 'running',
    startedAt: Date.now(),
    progress: 'Spawned agent ' + agentId,
  });

  // Initialize activity log
  boardManager.pushActivity(boardId, cardId, { type: 'started', message: 'Agent spawned and starting task' });

  return c.json({ ok: true, agentId });
});

// Execute all pending cards on active board
app.post('/api/boards/:id/run-all', async (c: any) => {
  if (!boardManager || !supervisor) return c.json({ error: 'Not available' }, 400);

  const boardId = c.req.param('id');
  const board = boardManager.getBoard(boardId);
  if (!board) return c.json({ error: 'Board not found' }, 404);
  if (board.status !== 'active') return c.json({ error: 'Board is not active' }, 400);

  const body = await c.req.json().catch(() => ({}));
  const pending = board.cards.filter(c => c.status === 'pending').sort((a, b) => a.order - b.order);
  const spawned: string[] = [];
  const ctx = boardManager.getBoardContext(boardId);

  for (const card of pending) {
    const boardContext = boardManager.buildCardContext(boardId, card.id);
    const taskWithContext = boardContext ? `${card.task}\n${boardContext}` : card.task;

    const agentId = await supervisor.spawn({
      task: taskWithContext,
      priority: card.priority,
      maxSteps: body.maxSteps || 25,
      sourceChannelType: 'web',
      sourceChannelId: `board:${boardId}`,
      workingDirectory: ctx?.workingDirectory,
    });

    cardAgentMap.set(card.id, agentId);
    agentCardMap.set(agentId, { boardId, cardId: card.id });

    boardManager.updateCard(boardId, card.id, {
      status: 'running',
      startedAt: Date.now(),
      progress: 'Spawned agent ' + agentId,
    });

    spawned.push(agentId);
  }

  return c.json({ ok: true, spawned });
});

// Halt a running card
app.post('/api/boards/:boardId/cards/:cardId/halt', async (c: any) => {
  if (!boardManager || !supervisor) return c.json({ error: 'Not available' }, 400);

  const cardId = c.req.param('cardId');
  const agentId = cardAgentMap.get(cardId);
  if (!agentId) return c.json({ error: 'No running agent for this card' }, 400);

  const halted = await supervisor.halt(agentId);
  if (halted) {
    boardManager.updateCard(c.req.param('boardId'), cardId, {
      status: 'halted',
      completedAt: Date.now(),
      progress: 'Halted by user',
    });
    cardAgentMap.delete(cardId);
    agentCardMap.delete(agentId);
  }
  return c.json({ ok: halted });
});

// Halt all running cards on a board
app.post('/api/boards/:id/halt-all', async (c: any) => {
  if (!boardManager || !supervisor) return c.json({ error: 'Not available' }, 400);

  const boardId = c.req.param('id');
  const board = boardManager.getBoard(boardId);
  if (!board) return c.json({ error: 'Board not found' }, 404);

  for (const card of board.cards) {
    if (card.status === 'running' || card.status === 'paused') {
      const agentId = cardAgentMap.get(card.id);
      if (agentId) {
        await supervisor.halt(agentId);
        cardAgentMap.delete(card.id);
        agentCardMap.delete(agentId);
      }
      boardManager.updateCard(boardId, card.id, {
        status: 'halted',
        completedAt: Date.now(),
        progress: 'Halted by user',
      });
    }
  }
  return c.json({ ok: true });
});

// ══════════════════════════════════════════════════════════
// Smart Execute (dependency-aware)
// ══════════════════════════════════════════════════════════

// Get execution plan (preview)
app.get('/api/boards/:id/execution-plan', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const batches = boardManager.getSmartExecutionOrder(boardId);
  return c.json({
    ok: true,
    batches: batches.map((batch, i) => ({
      wave: i + 1,
      cards: batch.map(normalizeCard),
    })),
    totalBatches: batches.length,
    totalCards: batches.reduce((sum, b) => sum + b.length, 0),
  });
});

// Smart Execute: run cards in dependency order
app.post('/api/boards/:id/smart-execute', async (c: any) => {
  if (!boardManager || !supervisor) return c.json({ error: 'Not available' }, 400);

  const boardId = c.req.param('id');
  const board = boardManager.getBoard(boardId);
  if (!board) return c.json({ error: 'Board not found' }, 404);
  if (board.status !== 'active') return c.json({ error: 'Board is not active' }, 400);

  const body = await c.req.json().catch(() => ({}));
  const batches = boardManager.getSmartExecutionOrder(boardId);
  if (batches.length === 0) return c.json({ ok: true, message: 'No pending cards to execute', spawned: [] });

  // Start the first batch — subsequent batches auto-start via cascade
  const firstBatch = batches[0];
  const spawned: string[] = [];
  const ctx = boardManager.getBoardContext(boardId);

  for (const card of firstBatch) {
    const boardContext = boardManager.buildCardContext(boardId, card.id);
    const taskWithContext = boardContext ? `${card.task}\n${boardContext}` : card.task;

    const agentId = await supervisor.spawn({
      task: taskWithContext,
      priority: card.priority,
      maxSteps: body.maxSteps || 25,
      sourceChannelType: 'web',
      sourceChannelId: `board:${boardId}`,
      workingDirectory: ctx?.workingDirectory,
    });

    cardAgentMap.set(card.id, agentId);
    agentCardMap.set(agentId, { boardId, cardId: card.id });

    boardManager.updateCard(boardId, card.id, {
      status: 'running',
      startedAt: Date.now(),
      progress: `Wave 1 — Spawned agent ${agentId}`,
    });

    spawned.push(agentId);
  }

  return c.json({
    ok: true,
    spawned,
    plan: {
      totalBatches: batches.length,
      currentBatch: 1,
      remainingBatches: batches.length - 1,
      nextBatchCards: batches.length > 1 ? batches[1].map(c => c.id) : [],
    },
  });
});

// Check and cascade: called when a card completes to auto-start unblocked children
app.post('/api/boards/:boardId/cards/:cardId/cascade', async (c: any) => {
  if (!boardManager || !supervisor) return c.json({ error: 'Not available' }, 400);

  const boardId = c.req.param('boardId');
  const board = boardManager.getBoard(boardId);
  if (!board || board.status !== 'active') return c.json({ ok: true, cascaded: [] });

  const body = await c.req.json().catch(() => ({}));
  const unblocked = boardManager.getUnblockedCards(boardId);
  const cascaded: string[] = [];
  const ctx = boardManager.getBoardContext(boardId);

  for (const card of unblocked) {
    const boardContext = boardManager.buildCardContext(boardId, card.id);
    const taskWithContext = boardContext ? `${card.task}\n${boardContext}` : card.task;

    const agentId = await supervisor.spawn({
      task: taskWithContext,
      priority: card.priority,
      maxSteps: body.maxSteps || 25,
      sourceChannelType: 'web',
      sourceChannelId: `board:${boardId}`,
      workingDirectory: ctx?.workingDirectory,
    });

    cardAgentMap.set(card.id, agentId);
    agentCardMap.set(agentId, { boardId, cardId: card.id });

    boardManager.updateCard(boardId, card.id, {
      status: 'running',
      startedAt: Date.now(),
      progress: `Auto-cascaded — Spawned agent ${agentId}`,
    });

    cascaded.push(card.id);
  }

  return c.json({ ok: true, cascaded });
});

// ══════════════════════════════════════════════════════════
// Card Comments
// ══════════════════════════════════════════════════════════

app.get('/api/boards/:boardId/cards/:cardId/comments', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const card = boardManager.getCard(c.req.param('boardId'), c.req.param('cardId'));
  if (!card) return c.json({ error: 'Card not found' }, 404);
  return c.json({ comments: card.comments ?? [] });
});

app.post('/api/boards/:boardId/cards/:cardId/comments', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { content, author, authorName } = body;
  if (!content || typeof content !== 'string') return c.json({ error: 'Content required' }, 400);
  const comment = boardManager.addComment(
    c.req.param('boardId'),
    c.req.param('cardId'),
    author || 'user',
    authorName || 'Admin',
    content.trim(),
  );
  if (!comment) return c.json({ error: 'Card not found' }, 404);
  return c.json({ ok: true, comment });
});

app.delete('/api/boards/:boardId/cards/:cardId/comments/:commentId', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const deleted = boardManager.deleteComment(c.req.param('boardId'), c.req.param('cardId'), c.req.param('commentId'));
  if (!deleted) return c.json({ error: 'Comment not found' }, 404);
  return c.json({ ok: true });
});

// ══════════════════════════════════════════════════════════
// Card Attachments
// ══════════════════════════════════════════════════════════

app.get('/api/boards/:boardId/cards/:cardId/attachments', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const card = boardManager.getCard(c.req.param('boardId'), c.req.param('cardId'));
  if (!card) return c.json({ error: 'Card not found' }, 404);
  return c.json({ attachments: card.attachments ?? [] });
});

app.post('/api/boards/:boardId/cards/:cardId/attachments', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { name, path, type, size, addedBy } = body;
  if (!name || !path) return c.json({ error: 'name and path required' }, 400);
  const attachment = boardManager.addAttachment(c.req.param('boardId'), c.req.param('cardId'), {
    name,
    path,
    type: type || 'other',
    size,
    addedBy: addedBy || 'agent',
  });
  if (!attachment) return c.json({ error: 'Card not found' }, 404);
  return c.json({ ok: true, attachment });
});

app.delete('/api/boards/:boardId/cards/:cardId/attachments/:attachmentId', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const deleted = boardManager.deleteAttachment(c.req.param('boardId'), c.req.param('cardId'), c.req.param('attachmentId'));
  if (!deleted) return c.json({ error: 'Attachment not found' }, 404);
  return c.json({ ok: true });
});

// ══════════════════════════════════════════════════════════
// Card Labels
// ══════════════════════════════════════════════════════════

app.post('/api/boards/:boardId/cards/:cardId/labels', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { name, color } = body;
  if (!name || !color) return c.json({ error: 'name and color required' }, 400);
  const label = boardManager.addLabel(c.req.param('boardId'), c.req.param('cardId'), name, color);
  if (!label) return c.json({ error: 'Card not found' }, 404);
  return c.json({ ok: true, label });
});

app.delete('/api/boards/:boardId/cards/:cardId/labels/:labelId', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const deleted = boardManager.removeLabel(c.req.param('boardId'), c.req.param('cardId'), c.req.param('labelId'));
  if (!deleted) return c.json({ error: 'Label not found' }, 404);
  return c.json({ ok: true });
});

// ══════════════════════════════════════════════════════════
// Card Dependencies
// ══════════════════════════════════════════════════════════

app.post('/api/boards/:boardId/cards/:cardId/parent', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { parentId } = body;
  const ok = boardManager.setParent(c.req.param('boardId'), c.req.param('cardId'), parentId ?? null);
  if (!ok) return c.json({ error: 'Invalid parent (not found, self-reference, or circular)' }, 400);
  return c.json({ ok: true });
});

app.post('/api/boards/:boardId/cards/:cardId/dependencies', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const body = await c.req.json();
  const { dependsOnCardId } = body;
  if (!dependsOnCardId) return c.json({ error: 'dependsOnCardId required' }, 400);
  const ok = boardManager.addDependency(c.req.param('boardId'), c.req.param('cardId'), dependsOnCardId);
  if (!ok) return c.json({ error: 'Invalid dependency (not found, self-reference, or circular)' }, 400);
  return c.json({ ok: true });
});

app.delete('/api/boards/:boardId/cards/:cardId/dependencies/:depId', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const ok = boardManager.removeDependency(c.req.param('boardId'), c.req.param('cardId'), c.req.param('depId'));
  if (!ok) return c.json({ error: 'Dependency not found' }, 404);
  return c.json({ ok: true });
});

// ══════════════════════════════════════════════════════════
// Attachment File Serving (preview/download)
// ══════════════════════════════════════════════════════════

app.get('/api/boards/:boardId/cards/:cardId/attachments/:attachmentId/content', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const card = boardManager.getCard(c.req.param('boardId'), c.req.param('cardId'));
  if (!card) return c.json({ error: 'Card not found' }, 404);
  const att = card.attachments?.find(a => a.id === c.req.param('attachmentId'));
  if (!att) return c.json({ error: 'Attachment not found' }, 404);

  if (!existsSync(att.path)) {
    return c.json({ error: 'File not found on disk', path: att.path }, 404);
  }

  try {
    const stat = statSync(att.path);
    const content = readFileSync(att.path, 'utf-8');
    return c.json({
      ok: true,
      attachment: att,
      content,
      size: stat.size,
    });
  } catch (err: any) {
    return c.json({ error: 'Failed to read file: ' + err.message }, 500);
  }
});

// Download endpoint — returns raw file
app.get('/api/boards/:boardId/cards/:cardId/attachments/:attachmentId/download', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const card = boardManager.getCard(c.req.param('boardId'), c.req.param('cardId'));
  if (!card) return c.json({ error: 'Card not found' }, 404);
  const att = card.attachments?.find(a => a.id === c.req.param('attachmentId'));
  if (!att) return c.json({ error: 'Attachment not found' }, 404);

  if (!existsSync(att.path)) {
    return c.json({ error: 'File not found on disk' }, 404);
  }

  try {
    const content = readFileSync(att.path);
    const mimeTypes: Record<string, string> = {
      markdown: 'text/markdown',
      document: 'application/octet-stream',
      image: 'image/' + (att.path.endsWith('.png') ? 'png' : att.path.endsWith('.svg') ? 'svg+xml' : 'jpeg'),
      presentation: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
      other: 'application/octet-stream',
    };
    const mime = mimeTypes[att.type] ?? 'application/octet-stream';
    return new Response(content, {
      headers: {
        'Content-Type': mime,
        'Content-Disposition': `attachment; filename="${att.name}"`,
      },
    });
  } catch (err: any) {
    return c.json({ error: 'Failed to read file: ' + err.message }, 500);
  }
});

// ══════════════════════════════════════════════════════════
// Board Context API
// ══════════════════════════════════════════════════════════

// Get board context
app.get('/api/boards/:id/context', (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const ctx = boardManager.getBoardContext(boardId);
  if (!ctx) return c.json({ error: 'Board not found' }, 404);
  return c.json({ ok: true, context: ctx });
});

// Set board working directory
app.post('/api/boards/:id/context/directory', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const { directory } = await c.req.json();
  if (!directory) return c.json({ error: 'directory required' }, 400);
  // Board agents run in this folder.
  const wait = requireOwner(c, { id: `boards.directory:${boardId}:${directory}`, title: 'Change the folder a board’s agents work in', detail: String(directory) });
  if (wait) return wait;
  boardManager.setBoardWorkingDirectory(boardId, directory);
  boardManager.saveBatch(boardId);
  return c.json({ ok: true });
});

// Set context variable
app.post('/api/boards/:id/context/variables', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const { key, value } = await c.req.json();
  if (!key) return c.json({ error: 'key required' }, 400);
  boardManager.setContextVariable(boardId, key, value);
  return c.json({ ok: true });
});

// Set project instructions
app.post('/api/boards/:id/context/instructions', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const { instructions } = await c.req.json();
  if (!instructions) return c.json({ error: 'instructions required' }, 400);
  boardManager.setProjectInstructions(boardId, instructions);
  return c.json({ ok: true });
});

// Set project structure
app.post('/api/boards/:id/context/structure', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const { structure } = await c.req.json();
  if (!structure || typeof structure !== 'object') return c.json({ error: 'structure object required' }, 400);
  boardManager.setProjectStructure(boardId, structure);
  return c.json({ ok: true });
});

// Add knowledge entry
app.post('/api/boards/:id/context/knowledge', async (c: any) => {
  if (!boardManager) return c.json({ error: 'Not available' }, 400);
  const boardId = c.req.param('id');
  const { knowledge } = await c.req.json();
  if (!knowledge) return c.json({ error: 'knowledge required' }, 400);
  boardManager.addKnowledge(boardId, knowledge);
  return c.json({ ok: true });
});

// ══════════════════════════════════════════════════════════
// Feedback Queue API
// ══════════════════════════════════════════════════════════

interface FeedbackRequest {
  id: string;
  boardId: string;
  cardId: string;
  agentId: string;
  question: string;
  options?: string[];
  createdAt: number;
  resolved: boolean;
  response?: string;
}

const feedbackQueue: Map<string, FeedbackRequest> = new Map();
const feedbackResolvers: Map<string, (response: string) => void> = new Map();

/** Called by agent when it needs a decision. Returns a promise that resolves with the user's response. */
export function requestFeedback(boardId: string, cardId: string, agentId: string, question: string, options?: string[]): Promise<string> {
  const id = `fb_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
  const request: FeedbackRequest = {
    id, boardId, cardId, agentId, question, options, createdAt: Date.now(), resolved: false,
  };
  feedbackQueue.set(id, request);

  // Update card status to 'question' to halt execution visually
  if (boardManager) {
    boardManager.updateCard(boardId, cardId, { status: 'question', progress: `Awaiting feedback: ${question}` });
  }

  // Emit SSE event for real-time notification
  emitBoardUpdate(boardId, 'feedback-request', request);

  return new Promise((resolve) => {
    feedbackResolvers.set(id, resolve);
  });
}

// Get pending feedback requests for a board
app.get('/api/boards/:id/feedback', (c: any) => {
  const boardId = c.req.param('id');
  const pending = [...feedbackQueue.values()].filter(f => f.boardId === boardId && !f.resolved);
  return c.json({ ok: true, feedback: pending });
});

// Respond to a feedback request
app.post('/api/boards/:boardId/feedback/:feedbackId/respond', async (c: any) => {
  const feedbackId = c.req.param('feedbackId');
  const { response } = await c.req.json();
  if (!response) return c.json({ error: 'response required' }, 400);

  const request = feedbackQueue.get(feedbackId);
  if (!request) return c.json({ error: 'Feedback request not found' }, 404);
  if (request.resolved) return c.json({ error: 'Already resolved' }, 400);

  request.resolved = true;
  request.response = response;

  // Resume the agent
  const resolver = feedbackResolvers.get(feedbackId);
  if (resolver) {
    resolver(response);
    feedbackResolvers.delete(feedbackId);
  }

  // Update card status back to running
  if (boardManager) {
    boardManager.updateCard(request.boardId, request.cardId, { status: 'running', progress: `Feedback received: ${response}` });
  }

  return c.json({ ok: true });
});

export default app;