@usejarvis/brain 0.1.0

package/src/actions/tools/commitments.ts

@@ -0,0 +1,192 @@
+/**
+ * Commitments Tool
+ *
+ * Allows the agent to manage tasks/commitments:
+ * list, get, create, update status, set due date.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import type { CommitmentPriority, CommitmentStatus } from '../../vault/commitments.ts';
+import {
+  createCommitment, getCommitment, findCommitments,
+  updateCommitmentStatus, updateCommitmentDue, getUpcoming,
+} from '../../vault/commitments.ts';
+
+const VALID_STATUSES = ['pending', 'active', 'completed', 'failed', 'escalated'];
+const VALID_PRIORITIES = ['low', 'normal', 'high', 'critical'];
+
+export const commitmentsTool: ToolDefinition = {
+  name: 'commitments',
+  description: [
+    'Manage tasks and commitments. Use this to create, update, and track scheduled tasks.',
+    '',
+    'Actions:',
+    '  list          — List commitments, filtered by status/priority/assigned_to/overdue',
+    '  get           — Get a single commitment by ID',
+    '  create        — Create a new task (required: what. optional: when_due, priority, context, assigned_to)',
+    '  update_status — Update a commitment\'s status (pending, active, completed, failed)',
+    '  set_due       — Set or clear a commitment\'s due date',
+    '',
+    'For when_due, use ISO 8601 format (e.g., "2026-02-28T14:00:00") or "null" to clear.',
+    'Priorities: low, normal, high, critical',
+    'Statuses: pending, active, completed, failed, escalated',
+  ].join('\n'),
+  category: 'tasks',
+  parameters: {
+    action: {
+      type: 'string',
+      description: 'The action: list, get, create, update_status, set_due',
+      required: true,
+    },
+    id: {
+      type: 'string',
+      description: 'Commitment ID (required for get, update_status, set_due)',
+      required: false,
+    },
+    what: {
+      type: 'string',
+      description: 'Task description (required for create)',
+      required: false,
+    },
+    when_due: {
+      type: 'string',
+      description: 'Due date in ISO 8601 format (e.g., "2026-02-28T14:00:00"). Use "null" to clear.',
+      required: false,
+    },
+    priority: {
+      type: 'string',
+      description: 'Priority: low, normal, high, critical',
+      required: false,
+    },
+    context: {
+      type: 'string',
+      description: 'Additional context for the task',
+      required: false,
+    },
+    assigned_to: {
+      type: 'string',
+      description: 'Who the task is assigned to (e.g., "jarvis", "user")',
+      required: false,
+    },
+    status: {
+      type: 'string',
+      description: 'New status for update_status: pending, active, completed, failed',
+      required: false,
+    },
+    result: {
+      type: 'string',
+      description: 'Result text (optional, for update_status when completing/failing)',
+      required: false,
+    },
+    filter_status: {
+      type: 'string',
+      description: 'Filter by status (for list action)',
+      required: false,
+    },
+    filter_overdue: {
+      type: 'string',
+      description: 'Set to "true" to list only overdue commitments',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const action = params.action as string;
+
+    switch (action) {
+      case 'list': {
+        const query: { status?: CommitmentStatus; priority?: CommitmentPriority; assigned_to?: string; overdue?: boolean } = {};
+        if (params.filter_status) query.status = params.filter_status as CommitmentStatus;
+        if (params.priority) query.priority = params.priority as CommitmentPriority;
+        if (params.assigned_to) query.assigned_to = params.assigned_to as string;
+        if (params.filter_overdue === 'true') query.overdue = true;
+
+        const items = findCommitments(query);
+        if (items.length === 0) return 'No commitments found matching the criteria.';
+        return items.map(c => {
+          const due = c.when_due ? ` (due: ${new Date(c.when_due).toLocaleString()})` : '';
+          const assignee = c.assigned_to ? ` [${c.assigned_to}]` : '';
+          return `[${c.id}] [${c.priority}] ${c.what}${due} — ${c.status}${assignee}`;
+        }).join('\n');
+      }
+
+      case 'get': {
+        if (!params.id) return 'Error: "id" is required for get action';
+        const item = getCommitment(params.id as string);
+        if (!item) return `Commitment not found: ${params.id}`;
+        return [
+          `ID: ${item.id}`,
+          `Task: ${item.what}`,
+          `Status: ${item.status}`,
+          `Priority: ${item.priority}`,
+          `Due: ${item.when_due ? new Date(item.when_due).toLocaleString() : 'none'}`,
+          `Assigned to: ${item.assigned_to || 'unassigned'}`,
+          `Context: ${item.context || 'none'}`,
+          `Created: ${new Date(item.created_at).toLocaleString()}`,
+          item.completed_at ? `Completed: ${new Date(item.completed_at).toLocaleString()}` : null,
+          item.result ? `Result: ${item.result}` : null,
+        ].filter(Boolean).join('\n');
+      }
+
+      case 'create': {
+        if (!params.what) return 'Error: "what" is required for create action';
+
+        let whenDue: number | undefined;
+        if (params.when_due && params.when_due !== 'null') {
+          const parsed = new Date(params.when_due as string).getTime();
+          if (isNaN(parsed)) return `Error: Invalid date format for when_due: "${params.when_due}". Use ISO 8601 (e.g., "2026-02-28T14:00:00")`;
+          whenDue = parsed;
+        }
+
+        if (params.priority && !VALID_PRIORITIES.includes(params.priority as string)) {
+          return `Error: Invalid priority "${params.priority}". Must be: ${VALID_PRIORITIES.join(', ')}`;
+        }
+
+        const item = createCommitment(params.what as string, {
+          when_due: whenDue,
+          priority: (params.priority as CommitmentPriority) || undefined,
+          context: params.context as string | undefined,
+          assigned_to: params.assigned_to as string | undefined,
+          created_from: 'jarvis',
+        });
+
+        const due = item.when_due ? ` — due: ${new Date(item.when_due).toLocaleString()}` : '';
+        return `Created commitment: [${item.id}] "${item.what}" (${item.priority})${due}`;
+      }
+
+      case 'update_status': {
+        if (!params.id) return 'Error: "id" is required for update_status action';
+        if (!params.status) return 'Error: "status" is required for update_status action';
+        if (!VALID_STATUSES.includes(params.status as string)) {
+          return `Error: Invalid status "${params.status}". Must be: ${VALID_STATUSES.join(', ')}`;
+        }
+
+        const updated = updateCommitmentStatus(
+          params.id as string,
+          params.status as CommitmentStatus,
+          params.result as string | undefined,
+        );
+        if (!updated) return `Commitment not found: ${params.id}`;
+        return `Updated: [${updated.id}] "${updated.what}" — now ${updated.status}${updated.result ? ` (result: ${updated.result})` : ''}`;
+      }
+
+      case 'set_due': {
+        if (!params.id) return 'Error: "id" is required for set_due action';
+
+        let whenDue: number | null = null;
+        if (params.when_due && params.when_due !== 'null') {
+          const parsed = new Date(params.when_due as string).getTime();
+          if (isNaN(parsed)) return `Error: Invalid date format: "${params.when_due}". Use ISO 8601 (e.g., "2026-02-28T14:00:00")`;
+          whenDue = parsed;
+        }
+
+        const updated = updateCommitmentDue(params.id as string, whenDue);
+        if (!updated) return `Commitment not found: ${params.id}`;
+        const due = updated.when_due ? new Date(updated.when_due).toLocaleString() : 'cleared';
+        return `Due date updated: [${updated.id}] "${updated.what}" — due: ${due}`;
+      }
+
+      default:
+        return `Unknown action: "${action}". Valid actions: list, get, create, update_status, set_due`;
+    }
+  },
+};

package/src/actions/tools/content.ts

@@ -0,0 +1,217 @@
+/**
+ * Content Pipeline Tool
+ *
+ * Allows the agent to manage the content pipeline:
+ * list, get, create, update, advance stage, add notes, get notes.
+ *
+ * IMPORTANT: For long content (drafts, scripts, articles), use append_body
+ * to write in chunks rather than sending the entire text in a single update.
+ * This avoids token limit truncation.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import type { ContentStage, ContentType } from '../../vault/content-pipeline.ts';
+import {
+  createContent, getContent, findContent, updateContent,
+  advanceStage, regressStage,
+  addStageNote, getStageNotes,
+  CONTENT_STAGES, CONTENT_TYPES,
+} from '../../vault/content-pipeline.ts';
+
+export const contentPipelineTool: ToolDefinition = {
+  name: 'content_pipeline',
+  description: [
+    'Manage the content creation pipeline. Use this tool to create, update, and track content items',
+    'through their lifecycle stages: idea → research → outline → draft → assets → review → scheduled → published.',
+    '',
+    'Actions:',
+    '  list        — List content items, optionally filtered by stage, type, or tag',
+    '  get         — Get a single content item by ID',
+    '  create      — Create a new content item',
+    '  update      — Update a content item (title, stage, tags, etc.)',
+    '  set_body    — Replace the entire body text (use for SHORT content only)',
+    '  append_body — Append text to the body (use for LONG content like drafts, scripts, articles)',
+    '  advance     — Move content to the next stage',
+    '  regress     — Move content to the previous stage',
+    '  add_note    — Add a note to a specific stage of content',
+    '  get_notes   — Get notes for a content item (optionally for a specific stage)',
+    '',
+    'IMPORTANT: For writing drafts, scripts, or any content longer than a few paragraphs,',
+    'use append_body in multiple calls (e.g., intro, then body sections, then conclusion).',
+    'Use set_body with body="" first to clear the body if you need to rewrite from scratch.',
+    'This prevents data loss from output token limits.',
+    '',
+    'Content types: ' + CONTENT_TYPES.join(', '),
+    'Stages: ' + CONTENT_STAGES.join(' → '),
+  ].join('\n'),
+  category: 'content',
+  parameters: {
+    action: {
+      type: 'string',
+      description: 'The action: list, get, create, update, set_body, append_body, advance, regress, add_note, get_notes',
+      required: true,
+    },
+    id: {
+      type: 'string',
+      description: 'Content item ID (required for get, update, set_body, append_body, advance, regress, add_note, get_notes)',
+      required: false,
+    },
+    title: {
+      type: 'string',
+      description: 'Content title (required for create, optional for update)',
+      required: false,
+    },
+    body: {
+      type: 'string',
+      description: 'Content text. For set_body: replaces entire body. For append_body: appended to existing body. Keep under 1000 words per call.',
+      required: false,
+    },
+    content_type: {
+      type: 'string',
+      description: 'Content type: youtube, blog, twitter, instagram, tiktok, linkedin, podcast, newsletter, short_form, other',
+      required: false,
+    },
+    stage: {
+      type: 'string',
+      description: 'Pipeline stage (for filtering in list, or setting in update, or specifying in add_note/get_notes)',
+      required: false,
+    },
+    tags: {
+      type: 'string',
+      description: 'Comma-separated tags (for create/update/filter)',
+      required: false,
+    },
+    note: {
+      type: 'string',
+      description: 'Note text (required for add_note)',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const action = params.action as string;
+
+    switch (action) {
+      case 'list': {
+        const query: { stage?: ContentStage; content_type?: ContentType; tag?: string } = {};
+        if (params.stage) query.stage = params.stage as ContentStage;
+        if (params.content_type) query.content_type = params.content_type as ContentType;
+        if (params.tags) query.tag = params.tags as string;
+        const items = findContent(query);
+        if (items.length === 0) return 'No content items found matching the criteria.';
+        return items.map(i =>
+          `[${i.id}] "${i.title}" (${i.content_type}) — stage: ${i.stage}, tags: ${i.tags.join(', ') || 'none'}, updated: ${new Date(i.updated_at).toLocaleString()}`
+        ).join('\n');
+      }
+
+      case 'get': {
+        if (!params.id) return 'Error: "id" is required for get action';
+        const item = getContent(params.id as string);
+        if (!item) return `Content item not found: ${params.id}`;
+        return [
+          `Title: ${item.title}`,
+          `Type: ${item.content_type}`,
+          `Stage: ${item.stage}`,
+          `Tags: ${item.tags.join(', ') || 'none'}`,
+          `Created by: ${item.created_by}`,
+          `Created: ${new Date(item.created_at).toLocaleString()}`,
+          `Updated: ${new Date(item.updated_at).toLocaleString()}`,
+          `Body length: ${item.body.length} chars`,
+          item.scheduled_at ? `Scheduled: ${new Date(item.scheduled_at).toLocaleString()}` : null,
+          item.published_url ? `Published URL: ${item.published_url}` : null,
+          '',
+          '--- Body ---',
+          item.body || '(empty)',
+        ].filter(Boolean).join('\n');
+      }
+
+      case 'create': {
+        if (!params.title) return 'Error: "title" is required for create action';
+        const tags = params.tags ? (params.tags as string).split(',').map(t => t.trim()) : undefined;
+        const item = createContent(params.title as string, {
+          body: params.body as string | undefined,
+          content_type: params.content_type as ContentType | undefined,
+          stage: params.stage as ContentStage | undefined,
+          tags,
+          created_by: 'jarvis',
+        });
+        return `Created content item: [${item.id}] "${item.title}" (${item.content_type}, stage: ${item.stage})`;
+      }
+
+      case 'update': {
+        if (!params.id) return 'Error: "id" is required for update action';
+        const updates: Record<string, unknown> = {};
+        if (params.title !== undefined) updates.title = params.title;
+        if (params.content_type !== undefined) updates.content_type = params.content_type;
+        if (params.stage !== undefined) updates.stage = params.stage;
+        if (params.tags !== undefined) {
+          updates.tags = (params.tags as string).split(',').map(t => t.trim());
+        }
+        // Note: body is NOT handled here. Use set_body or append_body instead.
+        const updated = updateContent(params.id as string, updates);
+        if (!updated) return `Content item not found: ${params.id}`;
+        return `Updated: [${updated.id}] "${updated.title}" — stage: ${updated.stage}, body: ${updated.body.length} chars`;
+      }
+
+      case 'set_body': {
+        if (!params.id) return 'Error: "id" is required for set_body action';
+        if (params.body === undefined) return 'Error: "body" is required for set_body action';
+        const updated = updateContent(params.id as string, { body: params.body as string });
+        if (!updated) return `Content item not found: ${params.id}`;
+        return `Body set: ${updated.body.length} chars saved for "${updated.title}"`;
+      }
+
+      case 'append_body': {
+        if (!params.id) return 'Error: "id" is required for append_body action';
+        if (!params.body) return 'Error: "body" is required for append_body action (the text to append)';
+        const existing = getContent(params.id as string);
+        if (!existing) return `Content item not found: ${params.id}`;
+        const newBody = existing.body + (existing.body ? '\n\n' : '') + (params.body as string);
+        const updated = updateContent(params.id as string, { body: newBody });
+        if (!updated) return `Failed to append body`;
+        return `Appended ${(params.body as string).length} chars. Total body: ${updated.body.length} chars for "${updated.title}"`;
+      }
+
+      case 'advance': {
+        if (!params.id) return 'Error: "id" is required for advance action';
+        const advanced = advanceStage(params.id as string);
+        if (!advanced) return 'Cannot advance: item not found or already at last stage (published).';
+        return `Advanced to stage: ${advanced.stage} — "${advanced.title}"`;
+      }
+
+      case 'regress': {
+        if (!params.id) return 'Error: "id" is required for regress action';
+        const regressed = regressStage(params.id as string);
+        if (!regressed) return 'Cannot regress: item not found or already at first stage (idea).';
+        return `Regressed to stage: ${regressed.stage} — "${regressed.title}"`;
+      }
+
+      case 'add_note': {
+        if (!params.id) return 'Error: "id" is required for add_note action';
+        if (!params.stage) return 'Error: "stage" is required for add_note action';
+        if (!params.note) return 'Error: "note" is required for add_note action';
+        const stageNote = addStageNote(
+          params.id as string,
+          params.stage as ContentStage,
+          params.note as string,
+          'jarvis',
+        );
+        return `Note added to ${stageNote.stage} stage: "${stageNote.note.slice(0, 100)}${stageNote.note.length > 100 ? '...' : ''}"`;
+      }
+
+      case 'get_notes': {
+        if (!params.id) return 'Error: "id" is required for get_notes action';
+        const notes = getStageNotes(
+          params.id as string,
+          params.stage as ContentStage | undefined,
+        );
+        if (notes.length === 0) return 'No notes found.';
+        return notes.map(n =>
+          `[${n.stage}] (${n.author}, ${new Date(n.created_at).toLocaleString()}): ${n.note}`
+        ).join('\n');
+      }
+
+      default:
+        return `Unknown action: "${action}". Valid actions: list, get, create, update, set_body, append_body, advance, regress, add_note, get_notes`;
+    }
+  },
+};

package/src/actions/tools/delegate.ts

@@ -0,0 +1,147 @@
+/**
+ * Delegate Task Tool — Multi-Agent Delegation
+ *
+ * Allows the primary agent (PA) to delegate tasks to specialist sub-agents.
+ * The tool spawns a specialist, runs it through a full LLM+tool loop,
+ * and returns the result to the PA.
+ *
+ * Supports sync mode (tool blocks until done) and async mode (background).
+ */
+
+import type { AgentOrchestrator } from '../../agents/orchestrator.ts';
+import type { LLMManager } from '../../llm/manager.ts';
+import type { RoleDefinition } from '../../roles/types.ts';
+import type { ToolDefinition } from './registry.ts';
+import { runSubAgent, createScopedToolRegistry, type ProgressCallback } from '../../agents/sub-agent-runner.ts';
+
+export type DelegateToolDeps = {
+  orchestrator: AgentOrchestrator;
+  llmManager: LLMManager;
+  specialists: Map<string, RoleDefinition>;
+  onProgress?: ProgressCallback;
+  onDelegation?: (specialistName: string, task: string) => void;
+};
+
+/**
+ * Create the delegate_task tool definition.
+ * The deps are captured in the closure so the tool has access at execution time.
+ */
+export function createDelegateTool(deps: DelegateToolDeps): ToolDefinition {
+  return {
+    name: 'delegate_task',
+    description: [
+      'Quick sync delegation: spawns a specialist, runs the task to completion, returns the result.',
+      'The specialist has its own LLM and tools. Blocks until done — use for focused, quick tasks.',
+      'For persistent agents or parallel work, use manage_agents instead.',
+      '',
+      'Available specialists: ' + Array.from(deps.specialists.keys()).join(', '),
+    ].join('\n'),
+    category: 'delegation',
+    parameters: {
+      specialist: {
+        type: 'string',
+        description: 'The specialist role ID to delegate to (e.g., "research-analyst", "software-engineer")',
+        required: true,
+      },
+      task: {
+        type: 'string',
+        description: 'Clear description of what the specialist should do',
+        required: true,
+      },
+      context: {
+        type: 'string',
+        description: 'Background information, relevant details, or constraints for the task',
+        required: true,
+      },
+    },
+    execute: async (params) => {
+      const specialistId = params.specialist as string;
+      const task = params.task as string;
+      const context = params.context as string;
+
+      // Validate specialist exists
+      const specialistRole = deps.specialists.get(specialistId);
+      if (!specialistRole) {
+        const available = Array.from(deps.specialists.keys()).join(', ');
+        return `Error: Unknown specialist "${specialistId}". Available: ${available}`;
+      }
+
+      // Get the primary agent as parent
+      const primary = deps.orchestrator.getPrimary();
+      if (!primary) {
+        return 'Error: No primary agent exists to delegate from';
+      }
+
+      console.log(`[DelegateTool] Delegating to ${specialistRole.name}: ${task.slice(0, 100)}...`);
+
+      // Notify task board: ownership is transferring to specialist
+      deps.onDelegation?.(specialistRole.name, task);
+
+      // Notify progress: delegation starting
+      if (deps.onProgress) {
+        deps.onProgress({
+          type: 'text',
+          agentName: specialistRole.name,
+          agentId: 'pending',
+          data: `[Delegating to ${specialistRole.name}...]`,
+        });
+      }
+
+      // Spawn sub-agent
+      const subAgent = deps.orchestrator.spawnSubAgent(primary.id, specialistRole);
+
+      // Create scoped tool registry based on specialist's allowed tools
+      const scopedRegistry = createScopedToolRegistry(subAgent.agent.authority.allowed_tools);
+
+      console.log(`[DelegateTool] Spawned ${specialistRole.name} (${subAgent.id}) with ${scopedRegistry.count()} tools`);
+
+      try {
+        // Run the sub-agent (sync — blocks until complete)
+        const result = await runSubAgent({
+          agent: subAgent,
+          task,
+          context,
+          llmManager: deps.llmManager,
+          toolRegistry: scopedRegistry,
+          onProgress: deps.onProgress,
+        });
+
+        // Terminate sub-agent after completion
+        deps.orchestrator.terminateAgent(subAgent.id);
+
+        // Format result for the PA
+        const toolsList = result.toolsUsed.length > 0
+          ? `\nTools used: ${result.toolsUsed.join(', ')}`
+          : '';
+        const tokens = `\nTokens: ${result.tokensUsed.input + result.tokensUsed.output}`;
+
+        if (result.success) {
+          return [
+            `[${specialistRole.name} completed]`,
+            '',
+            result.response,
+            toolsList,
+            tokens,
+          ].join('\n');
+        } else {
+          return [
+            `[${specialistRole.name} failed]`,
+            '',
+            result.response,
+            toolsList,
+            tokens,
+          ].join('\n');
+        }
+      } catch (err) {
+        // Clean up on error
+        try {
+          deps.orchestrator.terminateAgent(subAgent.id);
+        } catch { /* ignore cleanup errors */ }
+
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[DelegateTool] Error:`, errorMsg);
+        return `Error: Delegation to ${specialistRole.name} failed: ${errorMsg}`;
+      }
+    },
+  };
+}

package/src/actions/tools/desktop.test.ts

@@ -0,0 +1,55 @@
+import { test, expect, describe } from 'bun:test';
+import { DESKTOP_TOOLS } from './desktop.ts';
+
+describe('DESKTOP_TOOLS', () => {
+  test('contains 9 desktop tools', () => {
+    expect(DESKTOP_TOOLS).toHaveLength(9);
+  });
+
+  test('all have desktop category', () => {
+    for (const tool of DESKTOP_TOOLS) {
+      expect(tool.category).toBe('desktop');
+    }
+  });
+
+  test('tool names match expected desktop tools', () => {
+    const names = DESKTOP_TOOLS.map((t: any) => t.name).sort();
+    expect(names).toEqual([
+      'desktop_click',
+      'desktop_find_element',
+      'desktop_focus_window',
+      'desktop_launch_app',
+      'desktop_list_windows',
+      'desktop_press_keys',
+      'desktop_screenshot',
+      'desktop_snapshot',
+      'desktop_type',
+    ]);
+  });
+
+  test('all tools have execute functions', () => {
+    for (const tool of DESKTOP_TOOLS) {
+      expect(typeof tool.execute).toBe('function');
+    }
+  });
+
+  test('all tools have descriptions', () => {
+    for (const tool of DESKTOP_TOOLS) {
+      expect(tool.description.length).toBeGreaterThan(10);
+    }
+  });
+
+  test('all tools have target parameter', () => {
+    for (const tool of DESKTOP_TOOLS) {
+      expect(tool.parameters.target).toBeDefined();
+      expect(tool.parameters.target!.type).toBe('string');
+    }
+  });
+
+  test('returns not-implemented error without target (local execution stub)', async () => {
+    for (const tool of DESKTOP_TOOLS) {
+      const result = await tool.execute({});
+      expect(String(result)).toContain('not yet implemented');
+    }
+  });
+});