@usejarvis/brain 0.1.0

package/src/agents/agent.ts

@@ -0,0 +1,132 @@
+import type { RoleDefinition } from '../roles/types.ts';
+import type { LLMMessage } from '../llm/provider.ts';
+
+export type AgentStatus = 'active' | 'idle' | 'terminated';
+
+export type AuthorityBounds = {
+  max_authority_level: number;
+  allowed_tools: string[];
+  denied_tools: string[];
+  max_token_budget: number;
+  can_spawn_children: boolean;
+};
+
+export type Agent = {
+  id: string;
+  role: RoleDefinition;
+  parent_id: string | null;
+  status: AgentStatus;
+  session_id: string;
+  current_task: string | null;
+  authority: AuthorityBounds;
+  memory_scope: string[];
+  created_at: number;
+};
+
+/**
+ * Default authority bounds for an agent
+ */
+function getDefaultAuthority(role: RoleDefinition): AuthorityBounds {
+  return {
+    max_authority_level: role.authority_level,
+    allowed_tools: role.tools,
+    denied_tools: [],
+    max_token_budget: 100000,
+    can_spawn_children: role.sub_roles.length > 0,
+  };
+}
+
+/**
+ * Merge custom authority bounds with defaults
+ */
+function mergeAuthority(
+  defaultAuth: AuthorityBounds,
+  custom?: Partial<AuthorityBounds>
+): AuthorityBounds {
+  if (!custom) return defaultAuth;
+
+  return {
+    max_authority_level: custom.max_authority_level ?? defaultAuth.max_authority_level,
+    allowed_tools: custom.allowed_tools ?? defaultAuth.allowed_tools,
+    denied_tools: custom.denied_tools ?? defaultAuth.denied_tools,
+    max_token_budget: custom.max_token_budget ?? defaultAuth.max_token_budget,
+    can_spawn_children: custom.can_spawn_children ?? defaultAuth.can_spawn_children,
+  };
+}
+
+export class AgentInstance {
+  public readonly agent: Agent;
+  private messageHistory: LLMMessage[];
+
+  constructor(
+    role: RoleDefinition,
+    opts?: {
+      parent_id?: string;
+      authority?: Partial<AuthorityBounds>;
+      memory_scope?: string[];
+    }
+  ) {
+    const defaultAuth = getDefaultAuthority(role);
+    const authority = mergeAuthority(defaultAuth, opts?.authority);
+
+    this.agent = {
+      id: crypto.randomUUID(),
+      role,
+      parent_id: opts?.parent_id ?? null,
+      status: 'active',
+      session_id: crypto.randomUUID(),
+      current_task: null,
+      authority,
+      memory_scope: opts?.memory_scope ?? [],
+      created_at: Date.now(),
+    };
+
+    this.messageHistory = [];
+  }
+
+  get id(): string {
+    return this.agent.id;
+  }
+
+  get status(): AgentStatus {
+    return this.agent.status;
+  }
+
+  setTask(taskDescription: string): void {
+    this.agent.current_task = taskDescription;
+  }
+
+  clearTask(): void {
+    this.agent.current_task = null;
+  }
+
+  addMessage(role: 'user' | 'assistant' | 'system', content: string): void {
+    this.messageHistory.push({ role, content });
+  }
+
+  getMessages(): LLMMessage[] {
+    return [...this.messageHistory];
+  }
+
+  terminate(): void {
+    this.agent.status = 'terminated';
+    this.clearTask();
+  }
+
+  activate(): void {
+    if (this.agent.status !== 'terminated') {
+      this.agent.status = 'active';
+    }
+  }
+
+  idle(): void {
+    if (this.agent.status !== 'terminated') {
+      this.agent.status = 'idle';
+      this.clearTask();
+    }
+  }
+
+  toJSON(): Agent {
+    return { ...this.agent };
+  }
+}

package/src/agents/delegation.ts

@@ -0,0 +1,107 @@
+import type { AgentInstance } from './agent.ts';
+import type { Commitment } from '../vault/commitments.ts';
+import { createCommitment } from '../vault/commitments.ts';
+import { sendMessage, type MessagePriority } from './messaging.ts';
+
+export type DelegationResult = {
+  success: boolean;
+  agent_id: string;
+  commitment_id: string;
+  message?: string;
+};
+
+/**
+ * Delegate a task from parent to child agent
+ */
+export function delegateTask(
+  parent: AgentInstance,
+  child: AgentInstance,
+  task: {
+    what: string;
+    context: string;
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+    deadline?: number;
+  }
+): DelegationResult {
+  // Verify parent-child relationship
+  if (child.agent.parent_id !== parent.id) {
+    return {
+      success: false,
+      agent_id: child.id,
+      commitment_id: '',
+      message: 'Agent is not a child of the parent agent',
+    };
+  }
+
+  // Verify parent has authority to spawn children
+  if (!parent.agent.authority.can_spawn_children) {
+    return {
+      success: false,
+      agent_id: child.id,
+      commitment_id: '',
+      message: 'Parent agent does not have authority to delegate tasks',
+    };
+  }
+
+  // Create a commitment for the child agent
+  const commitment = createCommitment(task.what, {
+    context: task.context,
+    priority: task.priority ?? 'normal',
+    when_due: task.deadline,
+    assigned_to: child.id,
+    created_from: parent.id,
+  });
+
+  // Send a task message to the child
+  const message = sendMessage(parent.id, child.id, 'task', task.what, {
+    priority: (task.priority === 'critical' ? 'urgent' : task.priority ?? 'normal') as MessagePriority,
+    requires_response: true,
+    deadline: task.deadline,
+  });
+
+  // Set the task on the child agent
+  child.setTask(task.what);
+
+  return {
+    success: true,
+    agent_id: child.id,
+    commitment_id: commitment.id,
+    message: `Task delegated successfully (message: ${message.id})`,
+  };
+}
+
+/**
+ * Report task completion back to parent
+ */
+export function reportCompletion(
+  child: AgentInstance,
+  parent: AgentInstance,
+  result: {
+    success: boolean;
+    summary: string;
+    details?: string;
+  }
+): void {
+  // Verify parent-child relationship
+  if (child.agent.parent_id !== parent.id) {
+    throw new Error('Agent is not a child of the specified parent');
+  }
+
+  // Build report content
+  const content = JSON.stringify({
+    task: child.agent.current_task,
+    success: result.success,
+    summary: result.summary,
+    details: result.details,
+  });
+
+  // Send a report message to the parent
+  sendMessage(child.id, parent.id, 'report', content, {
+    priority: result.success ? 'normal' : 'high',
+    requires_response: false,
+  });
+
+  // Clear the child's current task
+  child.clearTask();
+  child.idle();
+}

package/src/agents/hierarchy.ts

@@ -0,0 +1,113 @@
+import type { AgentInstance } from './agent.ts';
+
+export type AgentTreeNode = {
+  agent: AgentInstance;
+  children: AgentTreeNode[];
+};
+
+export class AgentHierarchy {
+  private agents: Map<string, AgentInstance>;
+  private children: Map<string, Set<string>>; // parent_id -> child_ids
+
+  constructor() {
+    this.agents = new Map();
+    this.children = new Map();
+  }
+
+  addAgent(agent: AgentInstance): void {
+    this.agents.set(agent.id, agent);
+
+    // Track parent-child relationship
+    const parentId = agent.agent.parent_id;
+    if (parentId) {
+      if (!this.children.has(parentId)) {
+        this.children.set(parentId, new Set());
+      }
+      this.children.get(parentId)!.add(agent.id);
+    }
+  }
+
+  removeAgent(agentId: string): void {
+    const agent = this.agents.get(agentId);
+    if (!agent) return;
+
+    // Recursively remove all children first
+    const childIds = this.children.get(agentId);
+    if (childIds) {
+      for (const childId of Array.from(childIds)) {
+        this.removeAgent(childId);
+      }
+      this.children.delete(agentId);
+    }
+
+    // Remove from parent's children set
+    const parentId = agent.agent.parent_id;
+    if (parentId) {
+      const siblings = this.children.get(parentId);
+      if (siblings) {
+        siblings.delete(agentId);
+      }
+    }
+
+    // Remove the agent
+    this.agents.delete(agentId);
+  }
+
+  getAgent(agentId: string): AgentInstance | undefined {
+    return this.agents.get(agentId);
+  }
+
+  getChildren(agentId: string): AgentInstance[] {
+    const childIds = this.children.get(agentId);
+    if (!childIds) return [];
+
+    return Array.from(childIds)
+      .map((id) => this.agents.get(id))
+      .filter((agent): agent is AgentInstance => agent !== undefined);
+  }
+
+  getParent(agentId: string): AgentInstance | undefined {
+    const agent = this.agents.get(agentId);
+    if (!agent?.agent.parent_id) return undefined;
+
+    return this.agents.get(agent.agent.parent_id);
+  }
+
+  getPrimary(): AgentInstance | undefined {
+    // Find the agent with no parent
+    for (const agent of this.agents.values()) {
+      if (agent.agent.parent_id === null) {
+        return agent;
+      }
+    }
+    return undefined;
+  }
+
+  getAllAgents(): AgentInstance[] {
+    return Array.from(this.agents.values());
+  }
+
+  getActiveAgents(): AgentInstance[] {
+    return this.getAllAgents().filter((agent) => agent.status === 'active');
+  }
+
+  /**
+   * Get the full tree structure for display
+   */
+  getTree(): AgentTreeNode {
+    const primary = this.getPrimary();
+    if (!primary) {
+      throw new Error('No primary agent found in hierarchy');
+    }
+
+    return this.buildTreeNode(primary);
+  }
+
+  private buildTreeNode(agent: AgentInstance): AgentTreeNode {
+    const children = this.getChildren(agent.id);
+    return {
+      agent,
+      children: children.map((child) => this.buildTreeNode(child)),
+    };
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,19 @@
+// Agent lifecycle
+export { AgentInstance } from './agent.ts';
+export type { Agent, AgentStatus, AuthorityBounds } from './agent.ts';
+
+// Inter-agent communication
+export { sendMessage, getMessages, getPendingMessages } from './messaging.ts';
+export type { AgentMessage, MessageType, MessagePriority } from './messaging.ts';
+
+// Task delegation
+export { delegateTask, reportCompletion } from './delegation.ts';
+export type { DelegationResult } from './delegation.ts';
+
+// Hierarchy management
+export { AgentHierarchy } from './hierarchy.ts';
+export type { AgentTreeNode } from './hierarchy.ts';
+
+// Main orchestrator
+export { AgentOrchestrator } from './orchestrator.ts';
+export type { LLMManager } from '../llm/manager.ts';

package/src/agents/messaging.ts

@@ -0,0 +1,125 @@
+import { getDb, generateId } from '../vault/schema.ts';
+
+export type MessageType = 'task' | 'report' | 'question' | 'escalation';
+export type MessagePriority = 'low' | 'normal' | 'high' | 'urgent';
+
+export type AgentMessage = {
+  id: string;
+  from_agent: string;
+  to_agent: string;
+  type: MessageType;
+  content: string;
+  priority: MessagePriority;
+  requires_response: boolean;
+  deadline: number | null;
+  created_at: number;
+};
+
+type MessageRow = {
+  id: string;
+  from_agent: string;
+  to_agent: string;
+  type: MessageType;
+  content: string;
+  priority: MessagePriority;
+  requires_response: number;
+  deadline: number | null;
+  created_at: number;
+};
+
+/**
+ * Convert database row to AgentMessage
+ */
+function parseMessage(row: MessageRow): AgentMessage {
+  return {
+    ...row,
+    requires_response: row.requires_response === 1,
+  };
+}
+
+/**
+ * Send a message between agents (persisted to SQLite)
+ */
+export function sendMessage(
+  from: string,
+  to: string,
+  type: MessageType,
+  content: string,
+  opts?: {
+    priority?: MessagePriority;
+    requires_response?: boolean;
+    deadline?: number;
+  }
+): AgentMessage {
+  const db = getDb();
+  const id = generateId();
+  const now = Date.now();
+  const priority = opts?.priority ?? 'normal';
+  const requiresResponse = opts?.requires_response ?? false;
+  const deadline = opts?.deadline ?? null;
+
+  const stmt = db.prepare(
+    'INSERT INTO agent_messages (id, from_agent, to_agent, type, content, priority, requires_response, deadline, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)'
+  );
+
+  stmt.run(
+    id,
+    from,
+    to,
+    type,
+    content,
+    priority,
+    requiresResponse ? 1 : 0,
+    deadline,
+    now
+  );
+
+  return {
+    id,
+    from_agent: from,
+    to_agent: to,
+    type,
+    content,
+    priority,
+    requires_response: requiresResponse,
+    deadline,
+    created_at: now,
+  };
+}
+
+/**
+ * Get messages for an agent
+ */
+export function getMessages(
+  agentId: string,
+  opts?: {
+    type?: MessageType;
+    limit?: number;
+  }
+): AgentMessage[] {
+  const db = getDb();
+  const conditions: string[] = ['to_agent = ?'];
+  const params: unknown[] = [agentId];
+
+  if (opts?.type) {
+    conditions.push('type = ?');
+    params.push(opts.type);
+  }
+
+  const where = conditions.join(' AND ');
+  const limitClause = opts?.limit ? `LIMIT ${opts.limit}` : '';
+
+  const stmt = db.prepare(
+    `SELECT * FROM agent_messages WHERE ${where} ORDER BY created_at DESC ${limitClause}`
+  );
+
+  const rows = stmt.all(...params as string[]) as MessageRow[];
+  return rows.map(parseMessage);
+}
+
+/**
+ * Get unread/pending messages (all messages for now - could add read tracking)
+ */
+export function getPendingMessages(agentId: string): AgentMessage[] {
+  return getMessages(agentId);
+}