@usejarvis/brain 0.1.0

package/src/agents/sub-agent-runner.ts

@@ -0,0 +1,307 @@
+/**
+ * Sub-Agent Runner — Generic LLM+Tool Loop
+ *
+ * Runs any AgentInstance through the LLM+tool execution loop.
+ * Mirrors orchestrator.processMessage() but parameterized on agent
+ * instead of hardcoded to primary. Supports progress callbacks for
+ * real-time streaming to clients.
+ */
+
+import type { AgentInstance } from './agent.ts';
+import type { LLMManager } from '../llm/manager.ts';
+import type { LLMMessage, LLMResponse, LLMToolCall, LLMTool } from '../llm/provider.ts';
+import { ToolRegistry } from '../actions/tools/registry.ts';
+import { toolDefToLLMTool, BUILTIN_TOOLS } from '../actions/tools/builtin.ts';
+import type { ActionCategory } from '../roles/authority.ts';
+import type { AuthorityEngine } from '../authority/engine.ts';
+import type { AuditTrail } from '../authority/audit.ts';
+import type { EmergencyController } from '../authority/emergency.ts';
+import { getActionForTool } from '../authority/tool-action-map.ts';
+
+const MAX_TOOL_ITERATIONS = 100; // Lower than primary's 200 — sub-agents should be focused
+const MAX_TOOL_RESULT_CHARS = 6000;
+
+export type SubAgentResult = {
+  success: boolean;
+  response: string;
+  toolsUsed: string[];
+  tokensUsed: { input: number; output: number };
+};
+
+export type ProgressCallback = (event: {
+  type: 'text' | 'tool_call' | 'done';
+  agentName: string;
+  agentId: string;
+  data: unknown;
+}) => void;
+
+export type RunSubAgentOptions = {
+  agent: AgentInstance;
+  task: string;
+  context: string;
+  llmManager: LLMManager;
+  toolRegistry: ToolRegistry;
+  onProgress?: ProgressCallback;
+  maxIterations?: number;
+  // Authority engine components (optional — if not provided, no gate applied)
+  authorityEngine?: AuthorityEngine;
+  auditTrail?: AuditTrail;
+  emergencyController?: EmergencyController;
+  temporaryGrants?: Map<string, ActionCategory[]>;
+};
+
+/**
+ * Build a system prompt for a sub-agent from its role definition.
+ */
+function buildSubAgentPrompt(agent: AgentInstance, context: string): string {
+  const role = agent.agent.role;
+
+  const parts = [
+    `You are ${role.name}.`,
+    '',
+    role.description,
+    '',
+    '## Your Responsibilities',
+    ...role.responsibilities.map(r => `- ${r}`),
+    '',
+    '## Rules',
+    '- Focus on completing the specific task assigned to you.',
+    '- Use your tools to accomplish the task — don\'t just describe what you would do.',
+    '- Be thorough but efficient. Don\'t do unnecessary work.',
+    '- Return a clear, structured result when done.',
+  ];
+
+  if (context) {
+    parts.push('', '## Context', context);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Get LLM-formatted tools from a scoped ToolRegistry.
+ */
+function getLLMTools(registry: ToolRegistry): LLMTool[] | undefined {
+  if (registry.count() === 0) return undefined;
+  return registry.list().map(toolDefToLLMTool);
+}
+
+/**
+ * Execute a single tool call via a ToolRegistry.
+ * Includes optional authority gate for sub-agents.
+ */
+async function executeTool(
+  registry: ToolRegistry,
+  toolCall: LLMToolCall,
+  authorityCtx?: {
+    agent: AgentInstance;
+    engine: AuthorityEngine;
+    auditTrail?: AuditTrail;
+    emergencyController?: EmergencyController;
+    temporaryGrants?: Map<string, ActionCategory[]>;
+  }
+): Promise<string> {
+  // Authority gate (if engine provided)
+  if (authorityCtx) {
+    const { agent, engine, auditTrail, emergencyController, temporaryGrants } = authorityCtx;
+
+    // Emergency check
+    if (emergencyController && !emergencyController.canExecute()) {
+      return `[SYSTEM ${emergencyController.getState().toUpperCase()}] Tool execution suspended.`;
+    }
+
+    const tool = registry.get(toolCall.name);
+    const actionCategory = getActionForTool(toolCall.name, tool?.category ?? 'unknown');
+
+    const decision = engine.checkAuthority({
+      agentId: agent.id,
+      agentAuthorityLevel: agent.agent.authority.max_authority_level,
+      agentRoleId: agent.agent.role.id,
+      toolName: toolCall.name,
+      toolCategory: tool?.category ?? 'unknown',
+      actionCategory,
+      temporaryGrants: temporaryGrants ?? new Map(),
+    });
+
+    auditTrail?.log({
+      agent_id: agent.id,
+      agent_name: agent.agent.role.name,
+      tool_name: toolCall.name,
+      action_category: actionCategory,
+      authority_decision: decision.allowed ? 'allowed' : 'denied',
+      executed: decision.allowed,
+    });
+
+    if (!decision.allowed) {
+      return `[AUTHORITY DENIED] ${toolCall.name}: ${decision.reason}`;
+    }
+
+    // Sub-agents don't get approval flow — they're denied outright for governed actions
+    if (decision.requiresApproval) {
+      return `[AUTHORITY DENIED] ${toolCall.name} requires user approval. Sub-agents cannot request approvals directly.`;
+    }
+  }
+
+  try {
+    const raw = await registry.execute(toolCall.name, toolCall.arguments);
+    let result: string = typeof raw === 'string' ? raw : JSON.stringify(raw);
+
+    if (result.length > MAX_TOOL_RESULT_CHARS) {
+      result = result.slice(0, MAX_TOOL_RESULT_CHARS) + `\n... (truncated, was ${result.length} chars)`;
+    }
+
+    return result;
+  } catch (err) {
+    return `Error executing ${toolCall.name}: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
+
+/**
+ * Run a sub-agent through the full LLM+tool execution loop.
+ *
+ * This is the core engine that powers sub-agent execution.
+ * It works exactly like the primary agent's processMessage() loop
+ * but operates on any AgentInstance with its own scoped tools.
+ */
+export async function runSubAgent(opts: RunSubAgentOptions): Promise<SubAgentResult> {
+  const {
+    agent,
+    task,
+    context,
+    llmManager,
+    toolRegistry,
+    onProgress,
+    maxIterations = MAX_TOOL_ITERATIONS,
+    authorityEngine,
+    auditTrail,
+    emergencyController,
+    temporaryGrants,
+  } = opts;
+
+  // Build authority context if engine provided
+  const authorityCtx = authorityEngine ? {
+    agent,
+    engine: authorityEngine,
+    auditTrail,
+    emergencyController,
+    temporaryGrants,
+  } : undefined;
+
+  const agentName = agent.agent.role.name;
+  const agentId = agent.id;
+  const toolsUsed: string[] = [];
+  const totalUsage = { input: 0, output: 0 };
+
+  // Set the task on the agent
+  agent.setTask(task);
+  agent.activate();
+
+  // Build system prompt
+  const systemPrompt = buildSubAgentPrompt(agent, context);
+
+  // Add the task as a user message
+  agent.addMessage('user', task);
+
+  // Build messages array
+  const messages: LLMMessage[] = [
+    { role: 'system', content: systemPrompt },
+    ...agent.getMessages(),
+  ];
+
+  const tools = getLLMTools(toolRegistry);
+  let finalText = '';
+
+  try {
+    // Tool execution loop
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      const llmResponse: LLMResponse = await llmManager.chat(messages, { tools });
+
+      totalUsage.input += llmResponse.usage.input_tokens;
+      totalUsage.output += llmResponse.usage.output_tokens;
+
+      if (llmResponse.finish_reason === 'tool_use' && llmResponse.tool_calls.length > 0) {
+        // Add assistant message with tool calls
+        messages.push({
+          role: 'assistant',
+          content: llmResponse.content,
+          tool_calls: llmResponse.tool_calls,
+        });
+
+        // Notify about text if any
+        if (llmResponse.content && onProgress) {
+          onProgress({ type: 'text', agentName, agentId, data: llmResponse.content });
+        }
+
+        // Execute each tool
+        for (const tc of llmResponse.tool_calls) {
+          toolsUsed.push(tc.name);
+
+          // Notify about tool call
+          if (onProgress) {
+            onProgress({
+              type: 'tool_call',
+              agentName,
+              agentId,
+              data: { name: tc.name, arguments: tc.arguments },
+            });
+          }
+
+          const result = await executeTool(toolRegistry, tc, authorityCtx);
+          messages.push({
+            role: 'tool',
+            content: result,
+            tool_call_id: tc.id,
+          });
+
+          console.log(`[SubAgent:${agentName}] Tool ${tc.name} -> ${result.slice(0, 100)}...`);
+        }
+
+        continue;
+      }
+
+      // No tool calls — this is the final response
+      finalText = llmResponse.content;
+
+      if (onProgress) {
+        onProgress({ type: 'text', agentName, agentId, data: finalText });
+        onProgress({ type: 'done', agentName, agentId, data: { tokensUsed: totalUsage } });
+      }
+
+      break;
+    }
+
+    // Add final response to agent's history
+    agent.addMessage('assistant', finalText);
+
+    return {
+      success: true,
+      response: finalText,
+      toolsUsed: [...new Set(toolsUsed)],
+      tokensUsed: totalUsage,
+    };
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.error(`[SubAgent:${agentName}] Error:`, errorMsg);
+
+    return {
+      success: false,
+      response: `Sub-agent error: ${errorMsg}`,
+      toolsUsed: [...new Set(toolsUsed)],
+      tokensUsed: totalUsage,
+    };
+  }
+}
+
+/**
+ * Create a scoped ToolRegistry for a sub-agent.
+ * Only includes builtin tools whose category is in the allowed list.
+ */
+export function createScopedToolRegistry(allowedCategories: string[]): ToolRegistry {
+  const registry = new ToolRegistry();
+  for (const tool of BUILTIN_TOOLS) {
+    if (allowedCategories.includes(tool.category)) {
+      registry.register(tool);
+    }
+  }
+  return registry;
+}

package/src/agents/task-manager.ts

@@ -0,0 +1,151 @@
+/**
+ * Agent Task Manager — Background Async Task Runner
+ *
+ * Manages sub-agent tasks as background Promises. When a task is launched,
+ * runSubAgent() fires without blocking — the caller gets a task ID and can
+ * check status / collect results later.
+ */
+
+import { runSubAgent, type SubAgentResult, type ProgressCallback } from './sub-agent-runner.ts';
+import type { AgentInstance } from './agent.ts';
+import type { LLMManager } from '../llm/manager.ts';
+import type { ToolRegistry } from '../actions/tools/registry.ts';
+
+export type AsyncTaskStatus = 'running' | 'completed' | 'failed';
+
+export type AsyncTask = {
+  id: string;
+  agentId: string;
+  agentName: string;
+  specialistId: string;
+  task: string;
+  status: AsyncTaskStatus;
+  startedAt: number;
+  completedAt: number | null;
+  result: SubAgentResult | null;
+};
+
+export type LaunchOptions = {
+  agent: AgentInstance;
+  task: string;
+  context: string;
+  llmManager: LLMManager;
+  toolRegistry: ToolRegistry;
+  onProgress?: ProgressCallback;
+  onComplete?: (task: AsyncTask) => void;
+};
+
+export class AgentTaskManager {
+  private tasks = new Map<string, AsyncTask>();
+
+  /**
+   * Launch a sub-agent task in the background. Returns task ID immediately.
+   */
+  launch(opts: LaunchOptions): string {
+    const { agent, task, context, llmManager, toolRegistry, onProgress, onComplete } = opts;
+
+    const taskId = crypto.randomUUID();
+    const asyncTask: AsyncTask = {
+      id: taskId,
+      agentId: agent.id,
+      agentName: agent.agent.role.name,
+      specialistId: agent.agent.role.id,
+      task,
+      status: 'running',
+      startedAt: Date.now(),
+      completedAt: null,
+      result: null,
+    };
+
+    this.tasks.set(taskId, asyncTask);
+
+    // Fire runSubAgent without awaiting — runs in background
+    runSubAgent({
+      agent,
+      task,
+      context,
+      llmManager,
+      toolRegistry,
+      onProgress,
+    }).then((result) => {
+      asyncTask.status = 'completed';
+      asyncTask.completedAt = Date.now();
+      asyncTask.result = result;
+      console.log(`[TaskManager] Task ${taskId} completed (${asyncTask.agentName})`);
+      onComplete?.(asyncTask);
+    }).catch((err) => {
+      asyncTask.status = 'failed';
+      asyncTask.completedAt = Date.now();
+      asyncTask.result = {
+        success: false,
+        response: `Task failed: ${err instanceof Error ? err.message : String(err)}`,
+        toolsUsed: [],
+        tokensUsed: { input: 0, output: 0 },
+      };
+      console.error(`[TaskManager] Task ${taskId} failed (${asyncTask.agentName}):`, err);
+      onComplete?.(asyncTask);
+    });
+
+    return taskId;
+  }
+
+  /**
+   * Get a task by its ID.
+   */
+  getTask(taskId: string): AsyncTask | undefined {
+    return this.tasks.get(taskId);
+  }
+
+  /**
+   * Find the current/most recent task for an agent.
+   */
+  getAgentTask(agentId: string): AsyncTask | undefined {
+    let latest: AsyncTask | undefined;
+    for (const task of this.tasks.values()) {
+      if (task.agentId === agentId) {
+        if (!latest || task.startedAt > latest.startedAt) {
+          latest = task;
+        }
+      }
+    }
+    return latest;
+  }
+
+  /**
+   * Check if an agent is currently running a task.
+   */
+  isAgentBusy(agentId: string): boolean {
+    for (const task of this.tasks.values()) {
+      if (task.agentId === agentId && task.status === 'running') {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * List all tasks, optionally filtered by status.
+   */
+  listTasks(filter?: { status?: AsyncTaskStatus }): AsyncTask[] {
+    const all = Array.from(this.tasks.values());
+    if (filter?.status) {
+      return all.filter(t => t.status === filter.status);
+    }
+    return all;
+  }
+
+  /**
+   * Remove completed/failed tasks older than maxAge (default 10 min).
+   */
+  cleanup(maxAgeMs = 10 * 60_000): number {
+    let removed = 0;
+    const now = Date.now();
+    for (const [id, task] of this.tasks) {
+      if (task.status !== 'running' && task.completedAt && now - task.completedAt > maxAgeMs) {
+        this.tasks.delete(id);
+        removed++;
+      }
+    }
+    return removed;
+  }
+}

package/src/authority/approval-delivery.ts

@@ -0,0 +1,59 @@
+/**
+ * Approval Delivery — Pushes approval requests to the user through
+ * appropriate channels (WebSocket always, Telegram/Discord if urgent).
+ */
+
+import type { ApprovalRequest } from './approval.ts';
+
+export type ApprovalBroadcaster = {
+  broadcastApprovalRequest(request: ApprovalRequest): void;
+};
+
+export type ChannelSender = {
+  broadcastToAll(text: string): Promise<void>;
+};
+
+export class ApprovalDelivery {
+  private broadcaster: ApprovalBroadcaster | null = null;
+  private channelSender: ChannelSender | null = null;
+
+  setBroadcaster(broadcaster: ApprovalBroadcaster): void {
+    this.broadcaster = broadcaster;
+  }
+
+  setChannelSender(sender: ChannelSender): void {
+    this.channelSender = sender;
+  }
+
+  /**
+   * Deliver an approval request to all appropriate channels.
+   */
+  async deliver(request: ApprovalRequest): Promise<void> {
+    // Always push to dashboard via WebSocket
+    this.broadcaster?.broadcastApprovalRequest(request);
+
+    // If urgent, also push to Telegram/Discord
+    if (request.urgency === 'urgent' && this.channelSender) {
+      const message = this.formatApprovalMessage(request);
+      try {
+        await this.channelSender.broadcastToAll(message);
+      } catch (err) {
+        console.error('[ApprovalDelivery] Failed to send to external channels:', err);
+      }
+    }
+  }
+
+  private formatApprovalMessage(request: ApprovalRequest): string {
+    const shortId = request.id.slice(0, 8);
+    return [
+      `[APPROVAL NEEDED]`,
+      `Action: ${request.tool_name} (${request.action_category})`,
+      `Agent: ${request.agent_name}`,
+      `Reason: ${request.reason}`,
+      ``,
+      `Reply with:`,
+      `  approve ${shortId}`,
+      `  deny ${shortId}`,
+    ].join('\n');
+  }
+}

package/src/authority/approval.ts

@@ -0,0 +1,196 @@
+/**
+ * Approval Manager — Handles the lifecycle of approval requests.
+ *
+ * Persists to SQLite: pending → approved/denied → executed
+ */
+
+import { getDb, generateId } from '../vault/schema.ts';
+import type { ActionCategory } from '../roles/authority.ts';
+
+export type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'executed';
+export type ApprovalUrgency = 'urgent' | 'normal';
+
+export type ApprovalRequest = {
+  id: string;
+  agent_id: string;
+  agent_name: string;
+  tool_name: string;
+  tool_arguments: string; // JSON string
+  action_category: ActionCategory;
+  urgency: ApprovalUrgency;
+  reason: string;
+  context: string;
+  status: ApprovalStatus;
+  decided_at: number | null;
+  decided_by: string | null;
+  executed_at: number | null;
+  execution_result: string | null;
+  created_at: number;
+};
+
+export class ApprovalManager {
+  /**
+   * Create a new approval request and persist to DB.
+   */
+  createRequest(params: {
+    agentId: string;
+    agentName: string;
+    toolName: string;
+    toolArguments: Record<string, unknown>;
+    actionCategory: ActionCategory;
+    urgency: ApprovalUrgency;
+    reason: string;
+    context: string;
+  }): ApprovalRequest {
+    const db = getDb();
+    const id = generateId();
+    const now = Date.now();
+    const toolArgs = JSON.stringify(params.toolArguments);
+
+    db.run(
+      `INSERT INTO approval_requests (id, agent_id, agent_name, tool_name, tool_arguments, action_category, urgency, reason, context, status, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?)`,
+      [id, params.agentId, params.agentName, params.toolName, toolArgs, params.actionCategory, params.urgency, params.reason, params.context, now]
+    );
+
+    return {
+      id,
+      agent_id: params.agentId,
+      agent_name: params.agentName,
+      tool_name: params.toolName,
+      tool_arguments: toolArgs,
+      action_category: params.actionCategory as ActionCategory,
+      urgency: params.urgency,
+      reason: params.reason,
+      context: params.context,
+      status: 'pending',
+      decided_at: null,
+      decided_by: null,
+      executed_at: null,
+      execution_result: null,
+      created_at: now,
+    };
+  }
+
+  /**
+   * Get a request by ID.
+   */
+  getRequest(requestId: string): ApprovalRequest | null {
+    const db = getDb();
+    const row = db.query('SELECT * FROM approval_requests WHERE id = ?').get(requestId) as ApprovalRequest | null;
+    return row;
+  }
+
+  /**
+   * Find a request by short ID prefix (for Telegram/Discord commands).
+   */
+  findByShortId(shortId: string): ApprovalRequest | null {
+    const db = getDb();
+    const row = db.query('SELECT * FROM approval_requests WHERE id LIKE ? AND status = ?')
+      .get(`${shortId}%`, 'pending') as ApprovalRequest | null;
+    return row;
+  }
+
+  /**
+   * Approve a pending request.
+   */
+  approve(requestId: string, decidedBy: string): ApprovalRequest | null {
+    const db = getDb();
+    const now = Date.now();
+
+    const result = db.run(
+      `UPDATE approval_requests SET status = 'approved', decided_at = ?, decided_by = ? WHERE id = ? AND status = 'pending'`,
+      [now, decidedBy, requestId]
+    );
+
+    if (result.changes === 0) return null;
+    return this.getRequest(requestId);
+  }
+
+  /**
+   * Deny a pending request.
+   */
+  deny(requestId: string, decidedBy: string): ApprovalRequest | null {
+    const db = getDb();
+    const now = Date.now();
+
+    const result = db.run(
+      `UPDATE approval_requests SET status = 'denied', decided_at = ?, decided_by = ? WHERE id = ? AND status = 'pending'`,
+      [now, decidedBy, requestId]
+    );
+
+    if (result.changes === 0) return null;
+    return this.getRequest(requestId);
+  }
+
+  /**
+   * Mark an approved request as executed with its result.
+   */
+  markExecuted(requestId: string, executionResult: string): void {
+    const db = getDb();
+    const now = Date.now();
+
+    db.run(
+      `UPDATE approval_requests SET status = 'executed', executed_at = ?, execution_result = ? WHERE id = ?`,
+      [now, executionResult, requestId]
+    );
+  }
+
+  /**
+   * Get all pending requests.
+   */
+  getPending(): ApprovalRequest[] {
+    const db = getDb();
+    return db.query(
+      `SELECT * FROM approval_requests WHERE status = 'pending' ORDER BY created_at DESC`
+    ).all() as ApprovalRequest[];
+  }
+
+  /**
+   * Get approval history with optional filters.
+   */
+  getHistory(opts?: {
+    limit?: number;
+    action?: ActionCategory;
+    agentId?: string;
+    status?: ApprovalStatus;
+  }): ApprovalRequest[] {
+    const db = getDb();
+    const conditions: string[] = [];
+    const values: unknown[] = [];
+
+    if (opts?.action) {
+      conditions.push('action_category = ?');
+      values.push(opts.action);
+    }
+    if (opts?.agentId) {
+      conditions.push('agent_id = ?');
+      values.push(opts.agentId);
+    }
+    if (opts?.status) {
+      conditions.push('status = ?');
+      values.push(opts.status);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = opts?.limit ?? 50;
+
+    return db.query(
+      `SELECT * FROM approval_requests ${where} ORDER BY created_at DESC LIMIT ?`
+    ).all(...[...values, limit] as any[]) as ApprovalRequest[];
+  }
+
+  /**
+   * Expire old pending requests.
+   */
+  expireOld(maxAgeMs: number): number {
+    const db = getDb();
+    const cutoff = Date.now() - maxAgeMs;
+
+    const result = db.run(
+      `UPDATE approval_requests SET status = 'expired' WHERE status = 'pending' AND created_at < ?`,
+      [cutoff]
+    );
+    return result.changes;
+  }
+}