optimal-cli 1.0.0 → 1.1.0

package/lib/bot/coordinator.ts

@@ -1,254 +0,0 @@
-import {
-  listTasks,
-  updateTask,
-  claimTask,
-  logActivity,
-  listActivity,
-  type Task,
-} from '../board/index.js'
-import { sendHeartbeat, getActiveAgents } from './heartbeat.js'
-import { claimNextTask } from './claim.js'
-import { getAgentProfiles, matchTasksToAgent, type AgentProfile } from './skills.js'
-
-// --- Types ---
-
-export interface CoordinatorConfig {
-  pollIntervalMs: number
-  maxAgents: number
-  autoAssign: boolean
-}
-
-export interface CoordinatorStatus {
-  activeAgents: { agent: string; status: string; lastSeen: string }[]
-  idleAgents: AgentProfile[]
-  tasksInProgress: number
-  tasksReady: number
-  tasksBlocked: number
-  lastPollAt: string | null
-}
-
-export interface RebalanceResult {
-  releasedTasks: Task[]
-  reassignedTasks: Task[]
-}
-
-// --- State ---
-
-const DEFAULT_CONFIG: CoordinatorConfig = {
-  pollIntervalMs: 30_000,
-  maxAgents: 10,
-  autoAssign: true,
-}
-
-let lastPollAt: string | null = null
-
-// --- Coordinator loop ---
-
-export async function runCoordinatorLoop(
-  config?: Partial<CoordinatorConfig>,
-): Promise<void> {
-  const cfg: CoordinatorConfig = { ...DEFAULT_CONFIG, ...config }
-  let running = true
-
-  const shutdown = () => {
-    running = false
-    console.log('\nCoordinator shutting down...')
-  }
-  process.on('SIGINT', shutdown)
-
-  console.log(
-    `Coordinator started — poll every ${cfg.pollIntervalMs}ms, max ${cfg.maxAgents} agents, autoAssign=${cfg.autoAssign}`,
-  )
-
-  while (running) {
-    try {
-      await pollOnce(cfg)
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      console.error(`Coordinator poll error: ${msg}`)
-      await logActivity({
-        actor: 'coordinator',
-        action: 'poll_error',
-        new_value: { error: msg },
-      })
-    }
-
-    // Wait for next poll or until interrupted
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, cfg.pollIntervalMs)
-      if (!running) {
-        clearTimeout(timer)
-        resolve()
-      }
-    })
-  }
-
-  process.removeListener('SIGINT', shutdown)
-  console.log('Coordinator stopped.')
-}
-
-async function pollOnce(cfg: CoordinatorConfig): Promise<void> {
-  lastPollAt = new Date().toISOString()
-
-  const profiles = getAgentProfiles().slice(0, cfg.maxAgents)
-  const readyTasks = await listTasks({ status: 'ready' })
-  const claimedTasks = await listTasks({ status: 'claimed' })
-
-  // Send heartbeats for all active agents that have claimed tasks
-  const activeAgentIds = new Set(
-    claimedTasks.map((t) => t.claimed_by).filter(Boolean) as string[],
-  )
-  for (const agentId of activeAgentIds) {
-    await sendHeartbeat(agentId, 'working')
-  }
-
-  if (!cfg.autoAssign) {
-    await logActivity({
-      actor: 'coordinator',
-      action: 'poll',
-      new_value: {
-        readyTasks: readyTasks.length,
-        activeAgents: activeAgentIds.size,
-        autoAssign: false,
-        ts: lastPollAt,
-      },
-    })
-    return
-  }
-
-  // Find idle agents and try to assign tasks
-  let assignedCount = 0
-  for (const agent of profiles) {
-    // Check if agent has capacity
-    const agentClaimed = claimedTasks.filter((t) => t.claimed_by === agent.id)
-    if (agentClaimed.length >= agent.maxConcurrent) continue
-
-    // Match available tasks to this agent
-    const matched = matchTasksToAgent(agent, readyTasks)
-    if (matched.length === 0) continue
-
-    // Claim the top-priority matched task
-    const task = await claimNextTask(agent.id, agent.skills)
-    if (task) {
-      assignedCount++
-      console.log(`  Assigned "${task.title}" -> ${agent.id}`)
-      // Remove from local readyTasks to avoid double-assign
-      const idx = readyTasks.findIndex((t) => t.id === task.id)
-      if (idx >= 0) readyTasks.splice(idx, 1)
-    }
-  }
-
-  await logActivity({
-    actor: 'coordinator',
-    action: 'poll',
-    new_value: {
-      readyTasks: readyTasks.length,
-      activeAgents: activeAgentIds.size,
-      assigned: assignedCount,
-      ts: lastPollAt,
-    },
-  })
-
-  if (assignedCount > 0) {
-    console.log(`Poll complete: assigned ${assignedCount} task(s)`)
-  }
-}
-
-// --- Status ---
-
-export async function getCoordinatorStatus(): Promise<CoordinatorStatus> {
-  const profiles = getAgentProfiles()
-  const activeAgents = await getActiveAgents()
-  const readyTasks = await listTasks({ status: 'ready' })
-  const claimedTasks = await listTasks({ status: 'claimed' })
-  const inProgressTasks = await listTasks({ status: 'in_progress' })
-  const blockedTasks = await listTasks({ status: 'blocked' })
-
-  const activeIds = new Set(activeAgents.map((a) => a.agent))
-  const idleAgents = profiles.filter((p) => !activeIds.has(p.id))
-
-  return {
-    activeAgents,
-    idleAgents,
-    tasksInProgress: claimedTasks.length + inProgressTasks.length,
-    tasksReady: readyTasks.length,
-    tasksBlocked: blockedTasks.length,
-    lastPollAt,
-  }
-}
-
-// --- Manual assignment ---
-
-export async function assignTask(
-  taskId: string,
-  agentId: string,
-): Promise<Task> {
-  const task = await claimTask(taskId, agentId)
-
-  await logActivity({
-    actor: 'coordinator',
-    action: 'manual_assign',
-    task_id: taskId,
-    new_value: { agentId, title: task.title },
-  })
-
-  console.log(`Manually assigned "${task.title}" -> ${agentId}`)
-  return task
-}
-
-// --- Rebalance ---
-
-export async function rebalance(): Promise<RebalanceResult> {
-  const claimedTasks = await listTasks({ status: 'claimed' })
-  const now = Date.now()
-  const staleThreshold = 60 * 60 * 1000 // 1 hour
-
-  const releasedTasks: Task[] = []
-  const reassignedTasks: Task[] = []
-
-  for (const task of claimedTasks) {
-    if (!task.claimed_at) continue
-
-    const claimedAge = now - new Date(task.claimed_at).getTime()
-    if (claimedAge < staleThreshold) continue
-
-    // Check for recent activity on this task
-    const activity = await listActivity({ task_id: task.id, limit: 5 })
-    const recentActivity = activity.some((a) => {
-      const age = now - new Date(a.created_at).getTime()
-      return age < staleThreshold && a.action !== 'poll'
-    })
-
-    if (recentActivity) continue
-
-    // Release stale task
-    const released = await updateTask(
-      task.id,
-      {
-        status: 'ready',
-        claimed_by: null,
-        claimed_at: null,
-      },
-      'coordinator',
-    )
-
-    releasedTasks.push(released)
-
-    await logActivity({
-      actor: 'coordinator',
-      action: 'rebalance_release',
-      task_id: task.id,
-      new_value: {
-        previousAgent: task.claimed_by,
-        claimedAt: task.claimed_at,
-        reason: 'stale_claim',
-      },
-    })
-
-    console.log(
-      `Released stale task "${task.title}" (was claimed by ${task.claimed_by})`,
-    )
-  }
-
-  return { releasedTasks, reassignedTasks }
-}

package/lib/bot/heartbeat.ts

@@ -1,37 +0,0 @@
-import { logActivity, listActivity } from '../board/index.js'
-
-export async function sendHeartbeat(
-  agentId: string,
-  status: 'idle' | 'working' | 'error',
-): Promise<void> {
-  await logActivity({
-    actor: agentId,
-    action: 'heartbeat',
-    new_value: { status, ts: new Date().toISOString() },
-  })
-}
-
-export async function getActiveAgents(): Promise<
-  { agent: string; status: string; lastSeen: string }[]
-> {
-  const entries = await listActivity({ limit: 200 })
-  const cutoff = Date.now() - 5 * 60 * 1000
-
-  const latest = new Map<string, { status: string; lastSeen: string }>()
-
-  for (const e of entries) {
-    if (e.action !== 'heartbeat') continue
-    if (new Date(e.created_at).getTime() < cutoff) continue
-    if (latest.has(e.actor)) continue
-    const nv = e.new_value as { status?: string } | null
-    latest.set(e.actor, {
-      status: nv?.status ?? 'unknown',
-      lastSeen: e.created_at,
-    })
-  }
-
-  return Array.from(latest.entries()).map(([agent, info]) => ({
-    agent,
-    ...info,
-  }))
-}

package/lib/bot/index.ts

@@ -1,9 +0,0 @@
-export { sendHeartbeat, getActiveAgents } from './heartbeat.js'
-export { claimNextTask, releaseTask } from './claim.js'
-export { reportProgress, reportCompletion, reportBlocked } from './reporter.js'
-export { getAgentProfiles, matchTasksToAgent, findBestAgent } from './skills.js'
-export type { AgentProfile } from './skills.js'
-export { runCoordinatorLoop, getCoordinatorStatus, assignTask, rebalance } from './coordinator.js'
-export type { CoordinatorConfig, CoordinatorStatus, RebalanceResult } from './coordinator.js'
-export { processAgentMessage } from './protocol.js'
-export type { AgentMessage, AgentResponse } from './protocol.js'

package/lib/bot/protocol.ts

@@ -1,99 +0,0 @@
-import { sendHeartbeat } from './heartbeat.js'
-import { claimNextTask, releaseTask } from './claim.js'
-import { reportProgress, reportCompletion, reportBlocked } from './reporter.js'
-
-// --- Types ---
-
-export interface AgentMessage {
-  type: 'heartbeat' | 'claim' | 'progress' | 'complete' | 'blocked' | 'release'
-  agentId: string
-  taskId?: string
-  payload?: Record<string, unknown>
-}
-
-export interface AgentResponse {
-  success: boolean
-  data?: unknown
-  error?: string
-}
-
-// --- Message processor ---
-
-export async function processAgentMessage(
-  msg: AgentMessage,
-): Promise<AgentResponse> {
-  try {
-    switch (msg.type) {
-      case 'heartbeat':
-        return await handleHeartbeat(msg)
-      case 'claim':
-        return await handleClaim(msg)
-      case 'progress':
-        return await handleProgress(msg)
-      case 'complete':
-        return await handleComplete(msg)
-      case 'blocked':
-        return await handleBlocked(msg)
-      case 'release':
-        return await handleRelease(msg)
-      default:
-        return { success: false, error: `Unknown message type: ${(msg as AgentMessage).type}` }
-    }
-  } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err)
-    return { success: false, error: errorMsg }
-  }
-}
-
-// --- Handlers ---
-
-async function handleHeartbeat(msg: AgentMessage): Promise<AgentResponse> {
-  const status = (msg.payload?.status as 'idle' | 'working' | 'error') ?? 'idle'
-  await sendHeartbeat(msg.agentId, status)
-  return { success: true, data: { agentId: msg.agentId, status } }
-}
-
-async function handleClaim(msg: AgentMessage): Promise<AgentResponse> {
-  const skills = msg.payload?.skills as string[] | undefined
-  const task = await claimNextTask(msg.agentId, skills)
-  if (!task) {
-    return { success: true, data: null }
-  }
-  return { success: true, data: { taskId: task.id, title: task.title } }
-}
-
-async function handleProgress(msg: AgentMessage): Promise<AgentResponse> {
-  if (!msg.taskId) {
-    return { success: false, error: 'taskId is required for progress messages' }
-  }
-  const message = (msg.payload?.message as string) ?? 'Progress update'
-  await reportProgress(msg.taskId, msg.agentId, message)
-  return { success: true, data: { taskId: msg.taskId } }
-}
-
-async function handleComplete(msg: AgentMessage): Promise<AgentResponse> {
-  if (!msg.taskId) {
-    return { success: false, error: 'taskId is required for complete messages' }
-  }
-  const summary = (msg.payload?.summary as string) ?? 'Task completed'
-  await reportCompletion(msg.taskId, msg.agentId, summary)
-  return { success: true, data: { taskId: msg.taskId, status: 'done' } }
-}
-
-async function handleBlocked(msg: AgentMessage): Promise<AgentResponse> {
-  if (!msg.taskId) {
-    return { success: false, error: 'taskId is required for blocked messages' }
-  }
-  const reason = (msg.payload?.reason as string) ?? 'No reason given'
-  await reportBlocked(msg.taskId, msg.agentId, reason)
-  return { success: true, data: { taskId: msg.taskId, status: 'blocked' } }
-}
-
-async function handleRelease(msg: AgentMessage): Promise<AgentResponse> {
-  if (!msg.taskId) {
-    return { success: false, error: 'taskId is required for release messages' }
-  }
-  const reason = msg.payload?.reason as string | undefined
-  const task = await releaseTask(msg.taskId, msg.agentId, reason)
-  return { success: true, data: { taskId: task.id, status: 'ready' } }
-}

package/lib/bot/reporter.ts

@@ -1,42 +0,0 @@
-import { addComment, updateTask, completeTask } from '../board/index.js'
-
-export async function reportProgress(
-  taskId: string,
-  agentId: string,
-  message: string,
-): Promise<void> {
-  await addComment({
-    task_id: taskId,
-    author: agentId,
-    body: message,
-    comment_type: 'comment',
-  })
-}
-
-export async function reportCompletion(
-  taskId: string,
-  agentId: string,
-  summary: string,
-): Promise<void> {
-  await completeTask(taskId, agentId)
-  await addComment({
-    task_id: taskId,
-    author: agentId,
-    body: summary,
-    comment_type: 'status_change',
-  })
-}
-
-export async function reportBlocked(
-  taskId: string,
-  agentId: string,
-  reason: string,
-): Promise<void> {
-  await updateTask(taskId, { status: 'blocked' }, agentId)
-  await addComment({
-    task_id: taskId,
-    author: agentId,
-    body: `Blocked: ${reason}`,
-    comment_type: 'status_change',
-  })
-}

package/lib/bot/skills.ts

@@ -1,81 +0,0 @@
-import { readFileSync, existsSync } from 'node:fs'
-import { resolve, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import type { Task } from '../board/types.js'
-
-export interface AgentProfile {
-  id: string
-  skills: string[]
-  maxConcurrent: number
-  status: 'idle' | 'working' | 'error'
-}
-
-const DEFAULT_PROFILE: AgentProfile = {
-  id: 'default',
-  skills: ['*'],
-  maxConcurrent: 1,
-  status: 'idle',
-}
-
-/**
- * Reads agent profiles from agents/profiles.json.
- * Falls back to a single default wildcard profile if the file doesn't exist.
- */
-export function getAgentProfiles(): AgentProfile[] {
-  const root = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
-  const profilesPath = resolve(root, 'agents', 'profiles.json')
-
-  if (!existsSync(profilesPath)) {
-    return [DEFAULT_PROFILE]
-  }
-
-  try {
-    const raw = readFileSync(profilesPath, 'utf-8')
-    const parsed = JSON.parse(raw) as AgentProfile[]
-    return parsed
-  } catch {
-    return [DEFAULT_PROFILE]
-  }
-}
-
-/**
- * Filters and ranks tasks an agent can work on.
- *
- * - Includes tasks whose skill_required is in the agent's skills list,
- *   or tasks with no skill_required, or if agent has wildcard '*'.
- * - Sorts by priority (P1 first), then sort_order.
- * - Returns at most agent.maxConcurrent tasks.
- */
-export function matchTasksToAgent(agent: AgentProfile, tasks: Task[]): Task[] {
-  const hasWildcard = agent.skills.includes('*')
-
-  const matched = tasks.filter((t) => {
-    if (hasWildcard) return true
-    if (!t.skill_required) return true
-    return agent.skills.includes(t.skill_required)
-  })
-
-  matched.sort((a, b) => {
-    if (a.priority !== b.priority) return a.priority - b.priority
-    return a.sort_order - b.sort_order
-  })
-
-  return matched.slice(0, agent.maxConcurrent)
-}
-
-/**
- * Finds the first idle agent whose skills match the task's skill_required.
- * Returns null if no suitable idle agent exists.
- */
-export function findBestAgent(
-  profiles: AgentProfile[],
-  task: Task,
-): AgentProfile | null {
-  for (const agent of profiles) {
-    if (agent.status !== 'idle') continue
-    if (agent.skills.includes('*')) return agent
-    if (!task.skill_required) return agent
-    if (agent.skills.includes(task.skill_required)) return agent
-  }
-  return null
-}

package/lib/errors.ts

@@ -1,129 +0,0 @@
-/**
- * Centralized error handling for the Optimal CLI.
- *
- * Provides a typed CliError class, a user-friendly formatter,
- * and a wrapCommand helper for Commander action handlers.
- */
-
-// ── Error codes ──────────────────────────────────────────────────────────────
-
-export type ErrorCode =
-  | 'MISSING_ENV'
-  | 'NOT_FOUND'
-  | 'SUPABASE_ERROR'
-  | 'VALIDATION_ERROR'
-  | 'AUTH_ERROR'
-  | 'NETWORK_ERROR'
-  | 'FILE_ERROR'
-  | 'UNKNOWN'
-
-// ── CliError ─────────────────────────────────────────────────────────────────
-
-export class CliError extends Error {
-  constructor(
-    message: string,
-    public code: ErrorCode,
-    public suggestion?: string,
-  ) {
-    super(message)
-    this.name = 'CliError'
-  }
-}
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-const SUGGESTIONS: Record<string, string> = {
-  MISSING_ENV:
-    'Ensure the required environment variables are set in your .env file or shell.',
-  NOT_FOUND: 'Double-check the identifier (slug, ID, or name) and try again.',
-  SUPABASE_ERROR:
-    'Verify your Supabase URL and service key are correct and the database is reachable.',
-  VALIDATION_ERROR: 'Review the command options with --help.',
-  AUTH_ERROR:
-    'Check your API token or credentials and make sure they have not expired.',
-  NETWORK_ERROR:
-    'Check your internet connection and verify the remote service is available.',
-  FILE_ERROR: 'Verify the file path exists and you have read/write permissions.',
-}
-
-function classifyError(err: unknown): { code: ErrorCode; message: string } {
-  if (err instanceof CliError) {
-    return { code: err.code, message: err.message }
-  }
-
-  if (err instanceof Error) {
-    const msg = err.message
-
-    // Supabase / fetch errors
-    if (msg.includes('PGRST') || msg.includes('supabase') || msg.includes('relation')) {
-      return { code: 'SUPABASE_ERROR', message: msg }
-    }
-    if (msg.includes('ENOENT') || msg.includes('no such file')) {
-      return { code: 'FILE_ERROR', message: msg }
-    }
-    if (msg.includes('ECONNREFUSED') || msg.includes('fetch failed') || msg.includes('ETIMEDOUT')) {
-      return { code: 'NETWORK_ERROR', message: msg }
-    }
-    if (
-      msg.includes('OPTIMAL_SUPABASE_URL') ||
-      msg.includes('OPTIMAL_SUPABASE_SERVICE_KEY') ||
-      msg.includes('env')
-    ) {
-      return { code: 'MISSING_ENV', message: msg }
-    }
-
-    return { code: 'UNKNOWN', message: msg }
-  }
-
-  return { code: 'UNKNOWN', message: String(err) }
-}
-
-// ── handleError ──────────────────────────────────────────────────────────────
-
-/**
- * Format an error for CLI output, print it to stderr, and exit with code 1.
- */
-export function handleError(err: unknown): never {
-  const { code, message } = classifyError(err)
-
-  const suggestion =
-    err instanceof CliError && err.suggestion
-      ? err.suggestion
-      : SUGGESTIONS[code] ?? ''
-
-  const lines: string[] = [
-    '',
-    `  Error [${code}]: ${message}`,
-  ]
-
-  if (suggestion) {
-    lines.push(`  Suggestion: ${suggestion}`)
-  }
-
-  lines.push('')
-
-  process.stderr.write(lines.join('\n'))
-  process.exit(1)
-}
-
-// ── wrapCommand ──────────────────────────────────────────────────────────────
-
-/**
- * Wrap a Commander action handler so any thrown error is routed through
- * handleError, giving the user a consistent, friendly message instead of
- * an unhandled-rejection stack trace.
- *
- * Usage:
- *   .action(wrapCommand(async (opts) => { ... }))
- */
-export function wrapCommand<A extends unknown[]>(
-  fn: (...args: A) => Promise<void>,
-): (...args: A) => Promise<void> {
-  return async (...args: A) => {
-    try {
-      await fn(...args)
-    } catch (err) {
-      handleError(err)
-    }
-  }
-}