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.

8.8 KB
Raw Blame
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { randomUUID } from 'node:crypto';

/**
 * Durable fleet tasks (ADR-021). A task is a typed unit of delegated work:
 * who asked, who does it, the goal, the acceptance, a deadline, and — once
 * done — a typed result (outcome, deliverables, summary). Tasks are grouped
 * in batches so a lead that fans out N tasks is woken ONCE with a digest
 * when the batch completes (or its deadline passes), instead of N times
 * with N free-text mails.
 *
 * Storage is one JSON file next to the queue (atomic tmp+rename): task
 * volume is small, and it works on every device the JSON queue works on.
 */

export type BotTaskStatus = 'queued' | 'running' | 'done' | 'failed' | 'halted' | 'cancelled';

export interface BotTaskResult {
  outcome: string;
  summary: string;
  deliverables: string[];
  reasonCode?: string;
}

export interface BotTask {
  id: string;
  batchId: string;
  /** The bot that asked (a lead), or 'owner' for tasks created by a person. */
  requester: string;
  assignee: string;
  goal: string;
  acceptance?: string;
  /** Pipeline stage name when the task belongs to a pipeline run. */
  stage?: string;
  pipeline?: { runId: string; index: number; total: number; input: string; final: boolean };
  status: BotTaskStatus;
  jobId?: string;
  createdAt: number;
  startedAt?: number;
  completedAt?: number;
  result?: BotTaskResult;
}

export interface BotBatch {
  id: string;
  requester: string;
  label?: string;
  /** all = one wake when every task is settled; each = a wake per task. */
  wakeWhen: 'all' | 'each';
  createdAt: number;
  deadlineAt?: number;
  /** The requester has been woken for this batch (complete or deadline). */
  notifiedAt?: number;
}

interface TaskFile {
  batches: BotBatch[];
  tasks: BotTask[];
}

export const TASKS_FILE = 'tasks.json';
/** Settled tasks older than this are dropped from the file (the journal keeps the run). */
const RETAIN_SETTLED_MS = 7 * 24 * 60 * 60 * 1000;

const TERMINAL: ReadonlySet<BotTaskStatus> = new Set(['done', 'failed', 'halted', 'cancelled']);

export function isTerminalTask(status: BotTaskStatus): boolean {
  return TERMINAL.has(status);
}

export class BotTaskStore {
  private readonly file: string;
  private data: TaskFile;

  constructor(dir: string) {
    mkdirSync(dir, { recursive: true });
    this.file = join(dir, TASKS_FILE);
    this.data = this.read();
  }

  private read(): TaskFile {
    if (!existsSync(this.file)) return { batches: [], tasks: [] };
    try {
      const parsed = JSON.parse(readFileSync(this.file, 'utf-8')) as Partial<TaskFile>;
      return { batches: parsed.batches ?? [], tasks: parsed.tasks ?? [] };
    } catch {
      return { batches: [], tasks: [] };
    }
  }

  private flush(): void {
    const tmp = `${this.file}.tmp-${process.pid}`;
    writeFileSync(tmp, JSON.stringify(this.data), 'utf-8');
    renameSync(tmp, this.file);
  }

  createBatch(input: { requester: string; label?: string; wakeWhen?: 'all' | 'each'; deadlineAt?: number }): BotBatch {
    const batch: BotBatch = {
      id: randomUUID().slice(0, 8),
      requester: input.requester,
      label: input.label,
      wakeWhen: input.wakeWhen ?? 'all',
      createdAt: Date.now(),
      deadlineAt: input.deadlineAt,
    };
    this.data.batches.push(batch);
    this.flush();
    return batch;
  }

  /**
   * Create a task, or return the open task that already covers the same
   * goal for the same assignee (a lead re-running a delegation turn after a
   * restart must not double-dispatch).
   */
  createTask(input: Omit<BotTask, 'id' | 'status' | 'createdAt'>): { task: BotTask; duplicated: boolean } {
    const dup = this.data.tasks.find(t => t.requester === input.requester && t.assignee === input.assignee && t.goal === input.goal && !isTerminalTask(t.status));
    if (dup) return { task: dup, duplicated: true };
    const task: BotTask = { ...input, id: randomUUID().slice(0, 8), status: 'queued', createdAt: Date.now() };
    this.data.tasks.push(task);
    this.flush();
    return { task, duplicated: false };
  }

  get(taskId: string): BotTask | null {
    return this.data.tasks.find(t => t.id === taskId) ?? null;
  }

  byJob(jobId: string): BotTask | null {
    return this.data.tasks.find(t => t.jobId === jobId && !isTerminalTask(t.status)) ?? null;
  }

  batch(batchId: string): BotBatch | null {
    return this.data.batches.find(b => b.id === batchId) ?? null;
  }

  tasksInBatch(batchId: string): BotTask[] {
    return this.data.tasks.filter(t => t.batchId === batchId);
  }

  /** Open (unsettled) tasks, optionally for one requester or one assignee. */
  open(filter: { requester?: string; assignee?: string } = {}): BotTask[] {
    return this.data.tasks.filter(t => !isTerminalTask(t.status)
      && (!filter.requester || t.requester === filter.requester)
      && (!filter.assignee || t.assignee === filter.assignee));
  }

  /** Most recent tasks for a requester, newest first (open and settled). */
  recent(requester: string, limit = 20): BotTask[] {
    return this.data.tasks.filter(t => t.requester === requester).sort((a, b) => b.createdAt - a.createdAt).slice(0, limit);
  }

  update(taskId: string, patch: Partial<BotTask>): BotTask | null {
    const task = this.get(taskId);
    if (!task) return null;
    Object.assign(task, patch);
    this.flush();
    return task;
  }

  markBatchNotified(batchId: string): void {
    const batch = this.batch(batchId);
    if (batch) {
      batch.notifiedAt = Date.now();
      this.flush();
    }
  }

  /** Batches whose deadline has passed with open tasks and no wake yet. */
  overdueBatches(now = Date.now()): BotBatch[] {
    return this.data.batches.filter(b => b.deadlineAt !== undefined && b.deadlineAt <= now && !b.notifiedAt
      && this.tasksInBatch(b.id).some(t => !isTerminalTask(t.status)));
  }

  /** Drop settled tasks (and empty batches) older than the retention window. */
  prune(now = Date.now()): number {
    const before = this.data.tasks.length;
    this.data.tasks = this.data.tasks.filter(t => !isTerminalTask(t.status) || (t.completedAt ?? t.createdAt) > now - RETAIN_SETTLED_MS);
    const live = new Set(this.data.tasks.map(t => t.batchId));
    this.data.batches = this.data.batches.filter(b => live.has(b.id) || b.createdAt > now - RETAIN_SETTLED_MS);
    if (this.data.tasks.length !== before) this.flush();
    return before - this.data.tasks.length;
  }

  /** Remove every task a bot asked for or was assigned (delete lifecycle). */
  purgeBot(botId: string): void {
    this.data.tasks = this.data.tasks.filter(t => t.requester !== botId && t.assignee !== botId);
    this.data.batches = this.data.batches.filter(b => b.requester !== botId);
    this.flush();
  }
}

/** The prompt a crew bot receives for a task: typed, self-contained, with the previous stage's hand-off. */
export function renderTaskPrompt(task: BotTask, requesterName: string, previous?: BotTaskResult): string {
  const lines = [`Task ${task.id} from ${requesterName}${task.stage ? ` — pipeline stage "${task.stage}"${task.pipeline ? ` (${task.pipeline.index + 1}/${task.pipeline.total})` : ''}` : ''}:`, '', task.goal];
  if (task.acceptance) lines.push('', `Done means: ${task.acceptance}`);
  if (previous) {
    lines.push('', 'Hand-off from the previous stage:');
    if (previous.deliverables.length > 0) lines.push(...previous.deliverables.map(p => `- file: ${p}`));
    if (previous.summary) lines.push(`- summary: ${previous.summary.slice(0, 1500)}`);
  }
  lines.push('', 'When finished, deliver your result with bot_deliver (a file) and summarise it in your reply. Your reply and deliverables are returned to the requester automatically.');
  return lines.join('\n');
}

/** The digest a requester is woken with when a batch settles (or runs late). */
export function renderBatchDigest(batch: BotBatch, tasks: BotTask[], botName: (id: string) => string): string {
  const open = tasks.filter(t => !isTerminalTask(t.status));
  const head = batch.label ? `Batch "${batch.label}"` : 'Delegated work';
  const lines = [open.length === 0 ? `${head} is complete (${tasks.length} task${tasks.length === 1 ? '' : 's'}):` : `${head}: ${tasks.length - open.length} of ${tasks.length} tasks done, ${open.length} still running past the deadline:`];
  for (const t of tasks) {
    const icon = t.status === 'done' ? '✅' : t.status === 'failed' ? '❌' : t.status === 'cancelled' ? '🚫' : t.status === 'halted' ? '⏹' : '⏳';
    const r = t.result;
    lines.push('', `${icon} ${botName(t.assignee)} — task ${t.id}${t.stage ? ` (${t.stage})` : ''}: ${t.status}${r?.outcome ? ` · ${r.outcome}` : ''}${r?.reasonCode ? ` [${r.reasonCode}]` : ''}`);
    for (const d of r?.deliverables ?? []) lines.push(`   📁 ${d}`);
    if (r?.summary) lines.push(`   ${r.summary.slice(0, 1200).replace(/\n+/g, '\n   ')}`);
  }
  return lines.join('\n');
}