@usejarvis/brain 0.1.0

package/src/actions/tools/registry.ts

@@ -0,0 +1,171 @@
+import type { ContentBlock } from '../../llm/provider.ts';
+
+export type ToolParameter = {
+  type: string;
+  description: string;
+  required: boolean;
+};
+
+export type ToolResult = {
+  content: ContentBlock[];
+};
+
+export function isToolResult(v: unknown): v is ToolResult {
+  return v !== null && typeof v === 'object' && 'content' in (v as object) && Array.isArray((v as ToolResult).content);
+}
+
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  category: string;
+  parameters: Record<string, ToolParameter>;
+  execute: (params: Record<string, unknown>) => Promise<unknown>;
+};
+
+export class ToolRegistry {
+  private tools: Map<string, ToolDefinition> = new Map();
+
+  register(tool: ToolDefinition): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool '${tool.name}' is already registered`);
+    }
+
+    this.validateToolDefinition(tool);
+    this.tools.set(tool.name, tool);
+  }
+
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name);
+  }
+
+  list(category?: string): ToolDefinition[] {
+    const allTools = Array.from(this.tools.values());
+
+    if (!category) {
+      return allTools;
+    }
+
+    return allTools.filter(tool => tool.category === category);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  async execute(name: string, params: Record<string, unknown>): Promise<unknown> {
+    const tool = this.tools.get(name);
+
+    if (!tool) {
+      throw new Error(`Tool '${name}' not found in registry`);
+    }
+
+    this.validateParameters(tool, params);
+
+    try {
+      return await tool.execute(params);
+    } catch (error) {
+      throw new Error(
+        `Tool '${name}' execution failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  unregister(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  clear(): void {
+    this.tools.clear();
+  }
+
+  getCategories(): string[] {
+    const categories = new Set<string>();
+
+    for (const tool of this.tools.values()) {
+      categories.add(tool.category);
+    }
+
+    return Array.from(categories).sort();
+  }
+
+  count(): number {
+    return this.tools.size;
+  }
+
+  private validateToolDefinition(tool: ToolDefinition): void {
+    if (!tool.name || typeof tool.name !== 'string') {
+      throw new Error('Tool must have a valid name');
+    }
+
+    if (!tool.description || typeof tool.description !== 'string') {
+      throw new Error(`Tool '${tool.name}' must have a description`);
+    }
+
+    if (!tool.category || typeof tool.category !== 'string') {
+      throw new Error(`Tool '${tool.name}' must have a category`);
+    }
+
+    if (typeof tool.execute !== 'function') {
+      throw new Error(`Tool '${tool.name}' must have an execute function`);
+    }
+
+    if (typeof tool.parameters !== 'object' || tool.parameters === null) {
+      throw new Error(`Tool '${tool.name}' must have a parameters object`);
+    }
+
+    for (const [paramName, paramDef] of Object.entries(tool.parameters)) {
+      if (!paramDef.type || typeof paramDef.type !== 'string') {
+        throw new Error(`Parameter '${paramName}' in tool '${tool.name}' must have a type`);
+      }
+
+      if (!paramDef.description || typeof paramDef.description !== 'string') {
+        throw new Error(`Parameter '${paramName}' in tool '${tool.name}' must have a description`);
+      }
+
+      if (typeof paramDef.required !== 'boolean') {
+        throw new Error(`Parameter '${paramName}' in tool '${tool.name}' must specify if it's required`);
+      }
+    }
+  }
+
+  private validateParameters(tool: ToolDefinition, params: Record<string, unknown>): void {
+    for (const [paramName, paramDef] of Object.entries(tool.parameters)) {
+      const value = params[paramName];
+
+      if (paramDef.required && (value === undefined || value === null)) {
+        throw new Error(`Required parameter '${paramName}' missing for tool '${tool.name}'`);
+      }
+
+      if (value !== undefined && value !== null) {
+        const actualType = typeof value;
+        const expectedType = paramDef.type.toLowerCase();
+
+        if (expectedType === 'array' && !Array.isArray(value)) {
+          throw new Error(
+            `Parameter '${paramName}' for tool '${tool.name}' must be an array, got ${actualType}`
+          );
+        } else if (expectedType === 'object' && (actualType !== 'object' || Array.isArray(value))) {
+          throw new Error(
+            `Parameter '${paramName}' for tool '${tool.name}' must be an object, got ${actualType}`
+          );
+        } else if (
+          expectedType !== 'array' &&
+          expectedType !== 'object' &&
+          actualType !== expectedType &&
+          !(expectedType === 'number' && actualType === 'bigint')
+        ) {
+          throw new Error(
+            `Parameter '${paramName}' for tool '${tool.name}' must be ${expectedType}, got ${actualType}`
+          );
+        }
+      }
+    }
+
+    const unexpectedParams = Object.keys(params).filter(key => !tool.parameters[key]);
+    if (unexpectedParams.length > 0) {
+      console.warn(
+        `Unexpected parameters for tool '${tool.name}': ${unexpectedParams.join(', ')}`
+      );
+    }
+  }
+}

package/src/actions/tools/research.ts

@@ -0,0 +1,111 @@
+/**
+ * Research Queue Tool
+ *
+ * Lets the agent (or user via chat) manage the background research queue.
+ * Actions: add, list, remove.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import type { ResearchQueue, ResearchPriority } from '../../daemon/research-queue.ts';
+
+let queueRef: ResearchQueue | null = null;
+
+/**
+ * Wire the research queue instance. Must be called before tool use.
+ */
+export function setResearchQueueRef(queue: ResearchQueue): void {
+  queueRef = queue;
+}
+
+export const researchQueueTool: ToolDefinition = {
+  name: 'research_queue',
+  description: 'Manage the background research queue. Add topics for JARVIS to research during idle time, list current queue, or remove topics.',
+  category: 'productivity',
+  parameters: {
+    action: {
+      type: 'string',
+      description: 'Action to perform: "add", "list", or "remove"',
+      required: true,
+    },
+    topic: {
+      type: 'string',
+      description: 'The research topic (required for "add")',
+      required: false,
+    },
+    reason: {
+      type: 'string',
+      description: 'Why this topic should be researched (required for "add")',
+      required: false,
+    },
+    priority: {
+      type: 'string',
+      description: 'Priority: "high", "normal", or "low" (default: "normal", for "add" only)',
+      required: false,
+    },
+    id: {
+      type: 'string',
+      description: 'Topic ID to remove (required for "remove")',
+      required: false,
+    },
+    status: {
+      type: 'string',
+      description: 'Filter by status for "list": "queued", "in_progress", "completed", "failed"',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    if (!queueRef) {
+      return { error: 'Research queue not initialized' };
+    }
+
+    const action = String(params.action ?? '');
+
+    switch (action) {
+      case 'add': {
+        const topic = String(params.topic ?? '');
+        const reason = String(params.reason ?? 'No reason provided');
+        const priority = (params.priority as ResearchPriority) ?? 'normal';
+
+        if (!topic) {
+          return { error: 'Missing "topic" parameter' };
+        }
+
+        const entry = queueRef.addTopic(topic, reason, 'agent', priority);
+        return {
+          success: true,
+          id: entry.id,
+          message: `Added to research queue: "${topic}" (${priority} priority)`,
+        };
+      }
+
+      case 'list': {
+        const status = params.status as any;
+        const topics = queueRef.list(status || undefined);
+        return {
+          count: topics.length,
+          topics: topics.map((t) => ({
+            id: t.id,
+            topic: t.topic,
+            reason: t.reason,
+            priority: t.priority,
+            status: t.status,
+            source: t.source,
+            result: t.result ? (t.result.length > 200 ? t.result.slice(0, 197) + '...' : t.result) : undefined,
+          })),
+        };
+      }
+
+      case 'remove': {
+        const id = String(params.id ?? '');
+        if (!id) {
+          return { error: 'Missing "id" parameter' };
+        }
+        const removed = queueRef.remove(id);
+        return { success: removed, message: removed ? 'Topic removed' : 'Topic not found' };
+      }
+
+      default:
+        return { error: `Unknown action: "${action}". Use "add", "list", or "remove".` };
+    }
+  },
+};

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`;
+      }
+    },
+  };
+}