@shykaruu/jarvis-brain 0.4.0

package/src/actions/tools/sidecar-list.ts

@@ -0,0 +1,57 @@
+/**
+ * List Sidecars Tool
+ *
+ * Returns live sidecar connection status. The AI calls this
+ * before routing commands to a remote machine via the `target` param.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import { getSidecarManager } from './sidecar-route.ts';
+
+export const listSidecarsTool: ToolDefinition = {
+  name: 'list_sidecars',
+  description: 'List enrolled sidecar machines with live connection status, capabilities, and system info. Use this to discover available remote targets before using run_command, read_file, write_file, or list_directory with a "target" parameter.',
+  category: 'sidecar',
+  parameters: {
+    filter: {
+      type: 'string',
+      description: 'Optional filter string — only sidecars whose name or ID contain this string are returned (case-insensitive). Omit to list all.',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const manager = getSidecarManager();
+    if (!manager) {
+      return 'Sidecar system not initialized.';
+    }
+
+    const filter = (params.filter as string | undefined)?.trim().toLowerCase();
+    let sidecars = manager.listSidecars();
+
+    if (filter) {
+      sidecars = sidecars.filter(
+        (s) => s.name.toLowerCase().includes(filter) || s.id.toLowerCase().includes(filter),
+      );
+    }
+
+    if (sidecars.length === 0) {
+      return filter
+        ? `No sidecars matching "${filter}".`
+        : 'No sidecars enrolled.';
+    }
+
+    return sidecars.map((s) => {
+      const status = s.connected ? 'CONNECTED' : 'OFFLINE';
+      const caps = s.capabilities?.length ? s.capabilities.join(', ') : 'none';
+      const host = s.hostname ?? 'unknown';
+      const os = s.os ?? 'unknown';
+      const lastSeen = s.last_seen_at ?? 'never';
+      let line = `[${status}] ${s.name} (${s.id})\n  Host: ${host} | OS: ${os} | Capabilities: ${caps} | Last seen: ${lastSeen}`;
+      if (s.unavailable_capabilities?.length) {
+        const unavailLines = s.unavailable_capabilities.map(u => `    - ${u.name}: ${u.reason}`);
+        line += `\n  Unavailable (missing deps):\n${unavailLines.join('\n')}`;
+      }
+      return line;
+    }).join('\n\n');
+  },
+};

package/src/actions/tools/sidecar-route.ts

@@ -0,0 +1,105 @@
+/**
+ * Sidecar Routing — Transparent Remote Execution
+ *
+ * Holds a reference to the SidecarManager and provides a helper
+ * that existing tools call when a `target` parameter is present.
+ * The AI decides where to run a command by specifying (or omitting) a target.
+ */
+
+import type { SidecarManager } from '../../sidecar/manager.ts';
+import type { SidecarCapability, SidecarInfo } from '../../sidecar/types.ts';
+
+let sidecarManager: SidecarManager | null = null;
+
+/**
+ * Inject the sidecar manager at startup. Called once from the daemon.
+ */
+export function setSidecarManagerRef(manager: SidecarManager): void {
+  sidecarManager = manager;
+}
+
+export function getSidecarManager(): SidecarManager | null {
+  return sidecarManager;
+}
+
+/**
+ * Find a sidecar by name or ID.
+ * Priority: exact ID → exact name (case-insensitive) → contains match.
+ */
+function findSidecar(nameOrId: string, sidecars: SidecarInfo[]): SidecarInfo | null {
+  const query = nameOrId.trim();
+  if (!query) return null;
+
+  // Exact ID match
+  const byId = sidecars.find((s) => s.id === query);
+  if (byId) return byId;
+
+  // Exact name (case-insensitive)
+  const lower = query.toLowerCase();
+  const byName = sidecars.find((s) => s.name.toLowerCase() === lower);
+  if (byName) return byName;
+
+  // Contains match
+  const byContains = sidecars.find((s) => s.name.toLowerCase().includes(lower));
+  return byContains ?? null;
+}
+
+/**
+ * Route an RPC call to a sidecar. Returns the result string, or an error message.
+ *
+ * @param target - Sidecar name or ID
+ * @param method - RPC method name (e.g. "run_command", "read_file")
+ * @param params - RPC parameters
+ * @param requiredCapability - The sidecar must advertise this capability
+ */
+export async function routeToSidecar(
+  target: string,
+  method: string,
+  params: Record<string, unknown>,
+  requiredCapability: SidecarCapability,
+): Promise<string> {
+  if (!sidecarManager) {
+    return 'Error: Sidecar system not initialized.';
+  }
+
+  const sidecars = sidecarManager.listSidecars();
+  const sidecar = findSidecar(target, sidecars);
+
+  if (!sidecar) {
+    const available = sidecars.map((s) => s.name).join(', ') || 'none';
+    return `Error: No sidecar found matching "${target}". Available: ${available}`;
+  }
+
+  if (!sidecar.connected) {
+    return `Error: Sidecar "${sidecar.name}" is offline.`;
+  }
+
+  // Check if capability is enabled but unavailable (missing system dependencies)
+  const unavail = sidecar.unavailable_capabilities?.find(u => u.name === requiredCapability);
+  if (unavail) {
+    return `Error: Sidecar "${sidecar.name}" has "${requiredCapability}" enabled but it is unavailable: ${unavail.reason}. Do NOT retry.`;
+  }
+
+  if (sidecar.capabilities && !sidecar.capabilities.includes(requiredCapability)) {
+    return `Error: Sidecar "${sidecar.name}" does not have the "${requiredCapability}" capability enabled. Available capabilities: ${sidecar.capabilities.join(', ')}. Do NOT retry — ask the user to enable it in the sidecar's config if needed.`;
+  }
+
+  try {
+    const result = await sidecarManager.dispatchRPC(sidecar.id, method, params);
+
+    if (result === 'detached') {
+      return `Task dispatched to "${sidecar.name}" and running in the background.`;
+    }
+
+    return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+
+    // METHOD_NOT_FOUND means the capability is disabled — tell the LLM not to retry
+    if (msg.includes('METHOD_NOT_FOUND')) {
+      return `Error [${sidecar.name}]: Method "${method}" is not available. The "${requiredCapability}" capability is not enabled on this sidecar. Do NOT retry this call — ask the user to enable the capability in the sidecar's config if needed.`;
+    }
+
+    return `Error [${sidecar.name}]: ${msg}`;
+  }
+}

package/src/actions/tools/workflows.ts

@@ -0,0 +1,216 @@
+/**
+ * Manage Workflow Tool — Chat-Driven Workflow Automation
+ *
+ * Allows the primary agent to create, list, run, delete, enable/disable,
+ * and describe workflows directly from natural language chat.
+ * Uses the NLWorkflowBuilder to parse descriptions into workflow definitions.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import type { WorkflowEngine } from '../../workflows/engine.ts';
+import type { NLWorkflowBuilder } from '../../workflows/nl-builder.ts';
+import type { TriggerManager } from '../../workflows/triggers/manager.ts';
+import * as vault from '../../vault/workflows.ts';
+
+export type WorkflowToolDeps = {
+  workflowEngine: WorkflowEngine;
+  nlBuilder: NLWorkflowBuilder;
+  triggerManager: TriggerManager;
+};
+
+export function createManageWorkflowTool(deps: WorkflowToolDeps): ToolDefinition {
+  return {
+    name: 'manage_workflow',
+    description: [
+      'Create, list, run, delete, enable/disable, and inspect workflow automations.',
+      'Workflows are event-driven: "when X happens, do Y". They support triggers (cron, webhook, file changes, screen events),',
+      'actions (HTTP requests, send messages, run tools, agent tasks), logic (if/else, loops, delays), and error handling.',
+      '',
+      'Actions: create, list, run, delete, enable, disable, describe',
+    ].join('\n'),
+    category: 'automation',
+    parameters: {
+      action: {
+        type: 'string',
+        description: 'The action: "create", "list", "run", "delete", "enable", "disable", "describe"',
+        required: true,
+      },
+      name: {
+        type: 'string',
+        description: 'Workflow name (required for "create")',
+        required: false,
+      },
+      description: {
+        type: 'string',
+        description: 'Natural language description of what the workflow should do (for "create"). Example: "Every morning at 9am, check my email and send a Telegram summary"',
+        required: false,
+      },
+      workflow_id: {
+        type: 'string',
+        description: 'Target workflow ID (for "run", "delete", "enable", "disable", "describe")',
+        required: false,
+      },
+    },
+    execute: async (params) => {
+      const action = String(params.action ?? '').toLowerCase();
+
+      switch (action) {
+        case 'create': {
+          const name = params.name as string;
+          const description = params.description as string;
+          if (!description) return 'Error: "description" is required for create. Describe what the workflow should do in natural language.';
+
+          try {
+            // Use NL builder to parse description into a workflow definition
+            const definition = await deps.nlBuilder.parseDescription(description);
+
+            // Create the workflow in vault
+            const workflow = vault.createWorkflow(
+              name || 'Untitled Workflow',
+              { description },
+            );
+
+            // Create first version with the generated definition
+            vault.createVersion(workflow.id, definition, 'Created via chat');
+
+            // Register triggers so cron/webhook/poll triggers activate
+            try {
+              deps.triggerManager.registerWorkflow(workflow.id, definition);
+            } catch {
+              // Non-fatal — triggers can be registered later
+            }
+
+            const nodeTypes = definition.nodes.map(n => n.type).join(', ');
+            return `Workflow created successfully!\n\n` +
+              `- **ID**: ${workflow.id}\n` +
+              `- **Name**: ${name || 'Untitled Workflow'}\n` +
+              `- **Nodes**: ${definition.nodes.length} (${nodeTypes})\n` +
+              `- **Edges**: ${definition.edges.length}\n` +
+              `- **Version**: 1\n\n` +
+              `The workflow is enabled and its triggers are active. ` +
+              `You can view and edit it in the Workflows dashboard, or run it manually.`;
+          } catch (err) {
+            return `Failed to create workflow: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'list': {
+          const workflows = vault.findWorkflows();
+          if (workflows.length === 0) {
+            return 'No workflows found. Use action "create" with a description to create one.';
+          }
+
+          const lines = workflows.map(wf => {
+            const status = wf.enabled ? 'Active' : 'Disabled';
+            const lastRun = wf.last_executed_at
+              ? new Date(wf.last_executed_at).toLocaleString()
+              : 'Never';
+            return `- **${wf.name}** (${wf.id})\n  Status: ${status} | v${wf.current_version} | ${wf.execution_count} runs | Last: ${lastRun}`;
+          });
+
+          return `Found ${workflows.length} workflow(s):\n\n${lines.join('\n\n')}`;
+        }
+
+        case 'run': {
+          const id = params.workflow_id as string;
+          if (!id) return 'Error: "workflow_id" is required for run.';
+
+          try {
+            const execution = await deps.workflowEngine.execute(id, 'manual');
+            return `Workflow execution started.\n\n- **Execution ID**: ${execution.id}\n- **Status**: ${execution.status}\n\nThe workflow is running in the background. Check the Workflows dashboard for real-time progress.`;
+          } catch (err) {
+            return `Failed to run workflow: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'delete': {
+          const id = params.workflow_id as string;
+          if (!id) return 'Error: "workflow_id" is required for delete.';
+
+          try {
+            const wf = vault.getWorkflow(id);
+            if (!wf) return `Workflow "${id}" not found.`;
+
+            deps.triggerManager.unregisterWorkflow(id);
+            vault.deleteWorkflow(id);
+            return `Workflow "${wf.name}" (${id}) has been deleted.`;
+          } catch (err) {
+            return `Failed to delete workflow: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'enable': {
+          const id = params.workflow_id as string;
+          if (!id) return 'Error: "workflow_id" is required for enable.';
+
+          try {
+            vault.updateWorkflow(id, { enabled: true });
+            const version = vault.getLatestVersion(id);
+            if (version) {
+              deps.triggerManager.registerWorkflow(id, version.definition);
+            }
+            return `Workflow "${id}" is now enabled. Triggers are active.`;
+          } catch (err) {
+            return `Failed to enable workflow: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'disable': {
+          const id = params.workflow_id as string;
+          if (!id) return 'Error: "workflow_id" is required for disable.';
+
+          try {
+            vault.updateWorkflow(id, { enabled: false });
+            deps.triggerManager.unregisterWorkflow(id);
+            return `Workflow "${id}" is now disabled. Triggers are deactivated.`;
+          } catch (err) {
+            return `Failed to disable workflow: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'describe': {
+          const id = params.workflow_id as string;
+          if (!id) return 'Error: "workflow_id" is required for describe.';
+
+          try {
+            const wf = vault.getWorkflow(id);
+            if (!wf) return `Workflow "${id}" not found.`;
+
+            const version = vault.getLatestVersion(id);
+            const def = version?.definition;
+
+            let result = `**${wf.name}** (${wf.id})\n\n`;
+            if (wf.description) result += `${wf.description}\n\n`;
+            result += `- Status: ${wf.enabled ? 'Active' : 'Disabled'}\n`;
+            result += `- Version: ${wf.current_version}\n`;
+            result += `- Executions: ${wf.execution_count}\n`;
+            if (wf.tags.length > 0) result += `- Tags: ${wf.tags.join(', ')}\n`;
+
+            if (def) {
+              result += `\n**Nodes (${def.nodes.length}):**\n`;
+              for (const node of def.nodes) {
+                result += `  - ${node.label} (${node.type})\n`;
+              }
+              result += `\n**Connections (${def.edges.length}):**\n`;
+              for (const edge of def.edges) {
+                const srcNode = def.nodes.find(n => n.id === edge.source);
+                const tgtNode = def.nodes.find(n => n.id === edge.target);
+                result += `  - ${srcNode?.label ?? edge.source} → ${tgtNode?.label ?? edge.target}`;
+                if (edge.sourceHandle) result += ` [${edge.sourceHandle}]`;
+                result += '\n';
+              }
+              result += `\n**Settings:** retries=${def.settings.maxRetries}, timeout=${def.settings.timeoutMs}ms, onError=${def.settings.onError}`;
+            }
+
+            return result;
+          } catch (err) {
+            return `Failed to describe workflow: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        default:
+          return `Unknown action "${action}". Available actions: create, list, run, delete, enable, disable, describe`;
+      }
+    },
+  };
+}

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();
+}