optimal-cli 0.1.0 → 1.0.0

package/lib/bot/coordinator.ts

@@ -0,0 +1,254 @@
+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

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,99 @@
+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

@@ -0,0 +1,42 @@
+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

@@ -0,0 +1,81 @@
+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
+}