optimal-cli 0.1.0 → 1.0.1

package/dist/lib/board/index.js

@@ -0,0 +1,285 @@
+import { getSupabase } from '../supabase.js';
+export * from './types.js';
+const sb = () => getSupabase('optimal');
+// --- Helpers ---
+export function formatBoardTable(tasks) {
+    if (tasks.length === 0)
+        return 'No tasks found.';
+    const lines = [
+        '| Status      | P | Title                          | Agent   | Skill           | Effort |',
+        '|-------------|---|--------------------------------|---------|-----------------|--------|',
+    ];
+    const order = ['in_progress', 'claimed', 'blocked', 'ready', 'review', 'backlog', 'done'];
+    const sorted = [...tasks].sort((a, b) => {
+        const ai = order.indexOf(a.status);
+        const bi = order.indexOf(b.status);
+        if (ai !== bi)
+            return ai - bi;
+        return a.priority - b.priority;
+    });
+    for (const t of sorted) {
+        const title = t.title.length > 30 ? t.title.slice(0, 27) + '...' : t.title.padEnd(30);
+        const agent = (t.claimed_by ?? t.assigned_to ?? '—').padEnd(7);
+        const skill = (t.skill_required ?? '—').padEnd(15);
+        const effort = (t.estimated_effort ?? '—').padEnd(6);
+        lines.push(`| ${t.status.padEnd(11)} | ${t.priority} | ${title} | ${agent} | ${skill} | ${effort} |`);
+    }
+    lines.push(`\nTotal: ${tasks.length} tasks`);
+    return lines.join('\n');
+}
+export function getNextClaimable(readyTasks, allTasks) {
+    for (const task of readyTasks) {
+        if (!task.blocked_by || task.blocked_by.length === 0)
+            return task;
+        const allDone = task.blocked_by.every(depId => {
+            const dep = allTasks.find(t => t.id === depId);
+            return dep && (dep.status === 'done');
+        });
+        if (allDone)
+            return task;
+    }
+    return null;
+}
+// --- Projects ---
+export async function createProject(input) {
+    const { data, error } = await sb()
+        .from('projects')
+        .insert({
+        slug: input.slug,
+        name: input.name,
+        description: input.description ?? null,
+        owner: input.owner ?? null,
+        priority: input.priority ?? 3,
+    })
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to create project: ${error.message}`);
+    return data;
+}
+export async function getProjectBySlug(slug) {
+    const { data, error } = await sb()
+        .from('projects')
+        .select('*')
+        .eq('slug', slug)
+        .single();
+    if (error)
+        throw new Error(`Project not found: ${slug} — ${error.message}`);
+    return data;
+}
+export async function listProjects() {
+    const { data, error } = await sb()
+        .from('projects')
+        .select('*')
+        .neq('status', 'archived')
+        .order('priority', { ascending: true });
+    if (error)
+        throw new Error(`Failed to list projects: ${error.message}`);
+    return (data ?? []);
+}
+export async function updateProject(slug, updates) {
+    const { data, error } = await sb()
+        .from('projects')
+        .update(updates)
+        .eq('slug', slug)
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to update project: ${error.message}`);
+    return data;
+}
+// --- Milestones ---
+export async function createMilestone(input) {
+    const { data, error } = await sb()
+        .from('milestones')
+        .insert({
+        project_id: input.project_id,
+        name: input.name,
+        description: input.description ?? null,
+        due_date: input.due_date ?? null,
+    })
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to create milestone: ${error.message}`);
+    return data;
+}
+export async function listMilestones(projectId) {
+    let query = sb().from('milestones').select('*').order('due_date', { ascending: true });
+    if (projectId)
+        query = query.eq('project_id', projectId);
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`Failed to list milestones: ${error.message}`);
+    return (data ?? []);
+}
+// --- Labels ---
+export async function createLabel(name, color) {
+    const { data, error } = await sb()
+        .from('labels')
+        .insert({ name, color: color ?? null })
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to create label: ${error.message}`);
+    return data;
+}
+export async function listLabels() {
+    const { data, error } = await sb().from('labels').select('*').order('name');
+    if (error)
+        throw new Error(`Failed to list labels: ${error.message}`);
+    return (data ?? []);
+}
+export async function getLabelByName(name) {
+    const { data } = await sb().from('labels').select('*').eq('name', name).single();
+    return data ?? null;
+}
+// --- Tasks ---
+export async function createTask(input) {
+    const { labels: labelNames, ...rest } = input;
+    const { data, error } = await sb()
+        .from('tasks')
+        .insert({
+        ...rest,
+        milestone_id: rest.milestone_id ?? null,
+        description: rest.description ?? null,
+        priority: rest.priority ?? 3,
+        skill_required: rest.skill_required ?? null,
+        source_repo: rest.source_repo ?? null,
+        target_module: rest.target_module ?? null,
+        estimated_effort: rest.estimated_effort ?? null,
+        blocked_by: rest.blocked_by ?? [],
+    })
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to create task: ${error.message}`);
+    const task = data;
+    if (labelNames && labelNames.length > 0) {
+        for (const name of labelNames) {
+            const label = await getLabelByName(name);
+            if (label) {
+                await sb().from('task_labels').insert({ task_id: task.id, label_id: label.id });
+            }
+        }
+    }
+    await logActivity({ task_id: task.id, project_id: task.project_id, actor: 'system', action: 'created', new_value: { title: task.title } });
+    return task;
+}
+export async function updateTask(taskId, updates, actor) {
+    const old = await getTask(taskId);
+    const { data, error } = await sb()
+        .from('tasks')
+        .update(updates)
+        .eq('id', taskId)
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to update task ${taskId}: ${error.message}`);
+    const task = data;
+    if (actor) {
+        await logActivity({
+            task_id: taskId,
+            project_id: task.project_id,
+            actor,
+            action: updates.status ? 'status_changed' : 'updated',
+            old_value: { status: old.status, assigned_to: old.assigned_to },
+            new_value: updates,
+        });
+    }
+    return task;
+}
+export async function getTask(taskId) {
+    const { data, error } = await sb()
+        .from('tasks')
+        .select('*')
+        .eq('id', taskId)
+        .single();
+    if (error)
+        throw new Error(`Task not found: ${taskId}`);
+    return data;
+}
+export async function listTasks(opts) {
+    let query = sb().from('tasks').select('*');
+    if (opts?.project_id)
+        query = query.eq('project_id', opts.project_id);
+    if (opts?.status)
+        query = query.eq('status', opts.status);
+    if (opts?.claimed_by)
+        query = query.eq('claimed_by', opts.claimed_by);
+    if (opts?.assigned_to)
+        query = query.eq('assigned_to', opts.assigned_to);
+    query = query.order('priority', { ascending: true }).order('sort_order', { ascending: true });
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`Failed to list tasks: ${error.message}`);
+    return (data ?? []);
+}
+export async function claimTask(taskId, agent) {
+    const task = await updateTask(taskId, {
+        status: 'claimed',
+        claimed_by: agent,
+        claimed_at: new Date().toISOString(),
+    }, agent);
+    await addComment({ task_id: taskId, author: agent, body: `Claimed by ${agent}`, comment_type: 'claim' });
+    return task;
+}
+export async function completeTask(taskId, actor) {
+    return updateTask(taskId, {
+        status: 'done',
+        completed_at: new Date().toISOString(),
+    }, actor);
+}
+// --- Comments ---
+export async function addComment(input) {
+    const { data, error } = await sb()
+        .from('comments')
+        .insert({
+        task_id: input.task_id,
+        author: input.author,
+        body: input.body,
+        comment_type: input.comment_type ?? 'comment',
+    })
+        .select()
+        .single();
+    if (error)
+        throw new Error(`Failed to add comment: ${error.message}`);
+    return data;
+}
+export async function listComments(taskId) {
+    const { data, error } = await sb()
+        .from('comments')
+        .select('*')
+        .eq('task_id', taskId)
+        .order('created_at', { ascending: true });
+    if (error)
+        throw new Error(`Failed to list comments: ${error.message}`);
+    return (data ?? []);
+}
+// --- Activity Log ---
+export async function logActivity(entry) {
+    const { error } = await sb()
+        .from('activity_log')
+        .insert({
+        task_id: entry.task_id ?? null,
+        project_id: entry.project_id ?? null,
+        actor: entry.actor,
+        action: entry.action,
+        old_value: entry.old_value ?? null,
+        new_value: entry.new_value ?? null,
+    });
+    if (error)
+        throw new Error(`Failed to log activity: ${error.message}`);
+}
+export async function listActivity(opts) {
+    let query = sb().from('activity_log').select('*');
+    if (opts?.task_id)
+        query = query.eq('task_id', opts.task_id);
+    if (opts?.actor)
+        query = query.eq('actor', opts.actor);
+    query = query.order('created_at', { ascending: false }).limit(opts?.limit ?? 50);
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`Failed to list activity: ${error.message}`);
+    return (data ?? []);
+}

package/dist/lib/board/types.d.ts

@@ -0,0 +1,111 @@
+export interface Project {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    status: 'active' | 'paused' | 'completed' | 'archived';
+    owner: string | null;
+    priority: 1 | 2 | 3 | 4;
+    created_at: string;
+    updated_at: string;
+}
+export interface Milestone {
+    id: string;
+    project_id: string;
+    name: string;
+    description: string | null;
+    due_date: string | null;
+    status: 'open' | 'completed' | 'missed';
+    created_at: string;
+    updated_at: string;
+}
+export interface Label {
+    id: string;
+    name: string;
+    color: string | null;
+    created_at: string;
+}
+export type TaskStatus = 'backlog' | 'ready' | 'claimed' | 'in_progress' | 'review' | 'done' | 'blocked';
+export type Priority = 1 | 2 | 3 | 4;
+export type Effort = 'xs' | 's' | 'm' | 'l' | 'xl';
+export interface Task {
+    id: string;
+    project_id: string;
+    milestone_id: string | null;
+    title: string;
+    description: string | null;
+    status: TaskStatus;
+    priority: Priority;
+    assigned_to: string | null;
+    claimed_by: string | null;
+    claimed_at: string | null;
+    skill_required: string | null;
+    source_repo: string | null;
+    target_module: string | null;
+    estimated_effort: Effort | null;
+    blocked_by: string[];
+    sort_order: number;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+}
+export interface Comment {
+    id: string;
+    task_id: string;
+    author: string;
+    body: string;
+    comment_type: 'comment' | 'status_change' | 'claim' | 'review';
+    created_at: string;
+}
+export interface ActivityEntry {
+    id: string;
+    task_id: string | null;
+    project_id: string | null;
+    actor: string;
+    action: string;
+    old_value: Record<string, unknown> | null;
+    new_value: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface CreateProjectInput {
+    slug: string;
+    name: string;
+    description?: string;
+    owner?: string;
+    priority?: Priority;
+}
+export interface CreateMilestoneInput {
+    project_id: string;
+    name: string;
+    description?: string;
+    due_date?: string;
+}
+export interface CreateTaskInput {
+    project_id: string;
+    title: string;
+    description?: string;
+    priority?: Priority;
+    milestone_id?: string;
+    skill_required?: string;
+    source_repo?: string;
+    target_module?: string;
+    estimated_effort?: Effort;
+    blocked_by?: string[];
+    labels?: string[];
+}
+export interface UpdateTaskInput {
+    status?: TaskStatus;
+    priority?: Priority;
+    assigned_to?: string | null;
+    claimed_by?: string | null;
+    claimed_at?: string | null;
+    milestone_id?: string | null;
+    description?: string;
+    completed_at?: string | null;
+}
+export interface CreateCommentInput {
+    task_id: string;
+    author: string;
+    body: string;
+    comment_type?: 'comment' | 'status_change' | 'claim' | 'review';
+}

package/dist/lib/board/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/bot/claim.d.ts

@@ -0,0 +1,3 @@
+import { type Task } from '../board/index.js';
+export declare function claimNextTask(agentId: string, skills?: string[]): Promise<Task | null>;
+export declare function releaseTask(taskId: string, agentId: string, reason?: string): Promise<Task>;

package/dist/lib/bot/claim.js

@@ -0,0 +1,20 @@
+import { listTasks, claimTask, updateTask, getNextClaimable, } from '../board/index.js';
+export async function claimNextTask(agentId, skills) {
+    const readyTasks = await listTasks({ status: 'ready' });
+    const allTasks = await listTasks();
+    let candidates = readyTasks;
+    if (skills && skills.length > 0) {
+        candidates = readyTasks.filter((t) => !t.skill_required || skills.includes(t.skill_required));
+    }
+    const next = getNextClaimable(candidates, allTasks);
+    if (!next)
+        return null;
+    return claimTask(next.id, agentId);
+}
+export async function releaseTask(taskId, agentId, reason) {
+    return updateTask(taskId, {
+        status: 'ready',
+        claimed_by: null,
+        claimed_at: null,
+    }, agentId);
+}

package/dist/lib/bot/coordinator.d.ts

@@ -0,0 +1,27 @@
+import { type Task } from '../board/index.js';
+import { type AgentProfile } from './skills.js';
+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[];
+}
+export declare function runCoordinatorLoop(config?: Partial<CoordinatorConfig>): Promise<void>;
+export declare function getCoordinatorStatus(): Promise<CoordinatorStatus>;
+export declare function assignTask(taskId: string, agentId: string): Promise<Task>;
+export declare function rebalance(): Promise<RebalanceResult>;

package/dist/lib/bot/coordinator.js

@@ -0,0 +1,178 @@
+import { listTasks, updateTask, claimTask, logActivity, listActivity, } from '../board/index.js';
+import { sendHeartbeat, getActiveAgents } from './heartbeat.js';
+import { claimNextTask } from './claim.js';
+import { getAgentProfiles, matchTasksToAgent } from './skills.js';
+// --- State ---
+const DEFAULT_CONFIG = {
+    pollIntervalMs: 30_000,
+    maxAgents: 10,
+    autoAssign: true,
+};
+let lastPollAt = null;
+// --- Coordinator loop ---
+export async function runCoordinatorLoop(config) {
+    const cfg = { ...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((resolve) => {
+            const timer = setTimeout(resolve, cfg.pollIntervalMs);
+            if (!running) {
+                clearTimeout(timer);
+                resolve();
+            }
+        });
+    }
+    process.removeListener('SIGINT', shutdown);
+    console.log('Coordinator stopped.');
+}
+async function pollOnce(cfg) {
+    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));
+    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() {
+    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, agentId) {
+    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() {
+    const claimedTasks = await listTasks({ status: 'claimed' });
+    const now = Date.now();
+    const staleThreshold = 60 * 60 * 1000; // 1 hour
+    const releasedTasks = [];
+    const reassignedTasks = [];
+    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/dist/lib/bot/heartbeat.d.ts

@@ -0,0 +1,6 @@
+export declare function sendHeartbeat(agentId: string, status: 'idle' | 'working' | 'error'): Promise<void>;
+export declare function getActiveAgents(): Promise<{
+    agent: string;
+    status: string;
+    lastSeen: string;
+}[]>;

package/dist/lib/bot/heartbeat.js

@@ -0,0 +1,30 @@
+import { logActivity, listActivity } from '../board/index.js';
+export async function sendHeartbeat(agentId, status) {
+    await logActivity({
+        actor: agentId,
+        action: 'heartbeat',
+        new_value: { status, ts: new Date().toISOString() },
+    });
+}
+export async function getActiveAgents() {
+    const entries = await listActivity({ limit: 200 });
+    const cutoff = Date.now() - 5 * 60 * 1000;
+    const latest = new Map();
+    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;
+        latest.set(e.actor, {
+            status: nv?.status ?? 'unknown',
+            lastSeen: e.created_at,
+        });
+    }
+    return Array.from(latest.entries()).map(([agent, info]) => ({
+        agent,
+        ...info,
+    }));
+}

package/dist/lib/bot/index.d.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/dist/lib/bot/index.js

@@ -0,0 +1,6 @@
+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 { runCoordinatorLoop, getCoordinatorStatus, assignTask, rebalance } from './coordinator.js';
+export { processAgentMessage } from './protocol.js';