@shykaruu/jarvis-brain 0.4.0

package/src/actions/tools/goals.ts

@@ -0,0 +1,376 @@
+/**
+ * Manage Goals Tool — Chat-Driven Goal Pursuit
+ *
+ * Allows the agent to create, list, score, update, decompose, replan,
+ * and run daily rhythm from natural language chat.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import type { GoalService } from '../../goals/service.ts';
+import type { NLGoalBuilder } from '../../goals/nl-builder.ts';
+import type { GoalEstimator } from '../../goals/estimator.ts';
+import type { DailyRhythm } from '../../goals/rhythm.ts';
+import type { AccountabilityEngine } from '../../goals/accountability.ts';
+import * as vault from '../../vault/goals.ts';
+
+export type GoalToolDeps = {
+  goalService: GoalService;
+  nlBuilder: NLGoalBuilder;
+  estimator: GoalEstimator;
+  rhythm: DailyRhythm;
+  accountability: AccountabilityEngine;
+};
+
+export function createManageGoalsTool(deps: GoalToolDeps): ToolDefinition {
+  return {
+    name: 'manage_goals',
+    description: [
+      'Manage OKR-style goals with hierarchical structure (objective → key_result → milestone → task → daily_action).',
+      'Google-style 0.0-1.0 scoring (0.7 = good, 1.0 = aimed too low).',
+      '',
+      'Actions: create, list, get, score, update_status, update, decompose, replan, estimate,',
+      '         morning_plan, evening_review, metrics, delete, tree, overdue, escalations',
+    ].join('\n'),
+    category: 'goals',
+    parameters: {
+      action: {
+        type: 'string',
+        description: 'The action to perform',
+        required: true,
+      },
+      text: {
+        type: 'string',
+        description: 'Natural language goal description (for "create")',
+        required: false,
+      },
+      goal_id: {
+        type: 'string',
+        description: 'Target goal ID',
+        required: false,
+      },
+      score: {
+        type: 'number',
+        description: 'Score value 0.0-1.0 (for "score")',
+        required: false,
+      },
+      reason: {
+        type: 'string',
+        description: 'Reason for score update',
+        required: false,
+      },
+      status: {
+        type: 'string',
+        description: 'New status (for "update_status"): draft, active, paused, completed, failed, killed',
+        required: false,
+      },
+      title: {
+        type: 'string',
+        description: 'Goal title (for quick "create" without NL)',
+        required: false,
+      },
+      level: {
+        type: 'string',
+        description: 'Goal level: objective, key_result, milestone, task, daily_action',
+        required: false,
+      },
+      parent_id: {
+        type: 'string',
+        description: 'Parent goal ID (for "create")',
+        required: false,
+      },
+      filter_status: {
+        type: 'string',
+        description: 'Filter by status (for "list")',
+        required: false,
+      },
+      filter_level: {
+        type: 'string',
+        description: 'Filter by level (for "list")',
+        required: false,
+      },
+      limit: {
+        type: 'number',
+        description: 'Max results (for "list")',
+        required: false,
+      },
+    },
+    execute: async (params) => {
+      const action = String(params.action ?? '').toLowerCase();
+
+      switch (action) {
+        case 'create': {
+          const text = params.text as string | undefined;
+          const title = params.title as string | undefined;
+
+          if (text) {
+            // NL goal creation
+            try {
+              const proposal = await deps.nlBuilder.parseGoal(text);
+
+              if (proposal.clarifying_questions?.length) {
+                return `Before creating this goal, I have some questions:\n${proposal.clarifying_questions.map((q, i) => `${i + 1}. ${q}`).join('\n')}\n\nPlease answer these and I'll create the full OKR breakdown.`;
+              }
+
+              const goals = deps.nlBuilder.createFromProposal(
+                proposal,
+                params.parent_id as string | undefined,
+              );
+
+              const summary = goals.map(g =>
+                `${'  '.repeat(levelDepth(g.level))}${g.level}: ${g.title}`
+              ).join('\n');
+
+              return `Created ${goals.length} goals:\n${summary}`;
+            } catch (err) {
+              return `Error creating goal from NL: ${err instanceof Error ? err.message : err}`;
+            }
+          }
+
+          if (title) {
+            // Quick creation
+            const level = (params.level as string) ?? 'task';
+            const goal = deps.goalService.createGoal(title, level as any, {
+              parent_id: params.parent_id as string | undefined,
+            });
+            return `Created ${level}: "${goal.title}" (${goal.id})`;
+          }
+
+          return 'Error: Provide either "text" (NL description) or "title" (quick create).';
+        }
+
+        case 'list': {
+          const goals = vault.findGoals({
+            status: params.filter_status as any,
+            level: params.filter_level as any,
+            limit: params.limit as number ?? 20,
+          });
+
+          if (goals.length === 0) return 'No goals found matching filters.';
+
+          return goals.map(g =>
+            `[${g.status}] ${g.title} (${g.level}, score: ${g.score}, health: ${g.health})` +
+            (g.deadline ? ` — due ${new Date(g.deadline).toLocaleDateString()}` : '')
+          ).join('\n');
+        }
+
+        case 'get': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+
+          const goal = vault.getGoal(goalId);
+          if (!goal) return `Goal "${goalId}" not found.`;
+
+          const children = vault.getGoalChildren(goalId);
+          const progress = vault.getProgressHistory(goalId, 5);
+
+          let result = `**${goal.title}**\n`;
+          result += `Level: ${goal.level} | Status: ${goal.status} | Health: ${goal.health}\n`;
+          result += `Score: ${goal.score}${goal.score_reason ? ` (${goal.score_reason})` : ''}\n`;
+          result += `Time horizon: ${goal.time_horizon}\n`;
+          if (goal.description) result += `Description: ${goal.description}\n`;
+          if (goal.success_criteria) result += `Success criteria: ${goal.success_criteria}\n`;
+          if (goal.deadline) result += `Deadline: ${new Date(goal.deadline).toLocaleDateString()}\n`;
+          if (goal.tags.length) result += `Tags: ${goal.tags.join(', ')}\n`;
+          if (goal.escalation_stage !== 'none') result += `Escalation: ${goal.escalation_stage}\n`;
+
+          if (children.length > 0) {
+            result += `\nChildren (${children.length}):\n`;
+            result += children.map(c => `  - ${c.title} (${c.level}, ${c.score})`).join('\n');
+          }
+
+          if (progress.length > 0) {
+            result += `\nRecent progress:\n`;
+            result += progress.map(p =>
+              `  ${new Date(p.created_at).toLocaleDateString()}: ${p.score_before} → ${p.score_after} (${p.note})`
+            ).join('\n');
+          }
+
+          return result;
+        }
+
+        case 'score': {
+          const goalId = params.goal_id as string;
+          const score = params.score as number;
+          const reason = (params.reason as string) ?? '';
+          if (!goalId) return 'Error: "goal_id" is required.';
+          if (score === undefined || score === null) return 'Error: "score" is required (0.0-1.0).';
+
+          const goal = deps.goalService.scoreGoal(goalId, score, reason);
+          if (!goal) return `Goal "${goalId}" not found.`;
+          return `Updated score for "${goal.title}": ${goal.score} — ${reason}`;
+        }
+
+        case 'update_status': {
+          const goalId = params.goal_id as string;
+          const status = params.status as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+          if (!status) return 'Error: "status" is required.';
+
+          const goal = deps.goalService.updateStatus(goalId, status as any);
+          if (!goal) return `Goal "${goalId}" not found.`;
+          return `Updated "${goal.title}" status to: ${goal.status}`;
+        }
+
+        case 'update': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+
+          const updates: Record<string, unknown> = {};
+          if (params.title) updates.title = params.title;
+          if (params.reason) updates.description = params.reason; // overloaded field
+
+          const goal = deps.goalService.updateGoal(goalId, updates as any);
+          if (!goal) return `Goal "${goalId}" not found.`;
+          return `Updated "${goal.title}".`;
+        }
+
+        case 'decompose': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+
+          try {
+            const proposal = await deps.nlBuilder.decompose(goalId);
+            if (!proposal) return 'Could not decompose — goal not found or already at lowest level.';
+
+            const goals = deps.nlBuilder.createFromProposal(proposal, goalId);
+            const summary = goals.map(g =>
+              `${'  '.repeat(levelDepth(g.level))}${g.level}: ${g.title}`
+            ).join('\n');
+            return `Decomposed into ${goals.length} sub-goals:\n${summary}`;
+          } catch (err) {
+            return `Decomposition error: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'replan': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+
+          const goal = vault.getGoal(goalId);
+          if (!goal) return `Goal "${goalId}" not found.`;
+
+          try {
+            const analysis = await deps.accountability.generateReplanOptions(goal);
+            let result = `**Replan Analysis: ${goal.title}**\n\n`;
+            result += `Analysis: ${analysis.analysis}\n\n`;
+            result += `Options:\n`;
+            for (const opt of analysis.options) {
+              result += `  [${opt.impact.toUpperCase()}] ${opt.label}: ${opt.description}\n`;
+            }
+            result += `\nRecommendation: ${analysis.recommendation}`;
+            return result;
+          } catch (err) {
+            return `Replan error: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'estimate': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+
+          try {
+            const estimate = await deps.estimator.estimate(goalId);
+            if (!estimate) return `Goal "${goalId}" not found.`;
+
+            return `**Estimate:** ${estimate.final_estimate_hours}h (confidence: ${(estimate.confidence * 100).toFixed(0)}%)\n` +
+              `LLM: ${estimate.llm_estimate_hours}h | Historical: ${estimate.historical_estimate_hours ?? 'N/A'}h\n` +
+              `${estimate.reasoning}` +
+              (estimate.similar_past_goals.length > 0
+                ? `\nBased on ${estimate.similar_past_goals.length} similar past goal(s)`
+                : '');
+          } catch (err) {
+            return `Estimation error: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'morning_plan': {
+          try {
+            const result = await deps.rhythm.runMorningPlan();
+            let output = `**Morning Plan**\n\n`;
+            output += `${result.message}\n\n`;
+            if (result.warnings.length) {
+              output += `Warnings:\n${result.warnings.map(w => `  ⚠ ${w}`).join('\n')}\n\n`;
+            }
+            output += `Focus areas:\n${result.focusAreas.map(f => `  → ${f}`).join('\n')}\n\n`;
+            output += `Today's actions:\n${result.dailyActions.map(a => `  □ ${a}`).join('\n')}`;
+            return output;
+          } catch (err) {
+            return `Morning plan error: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'evening_review': {
+          try {
+            const result = await deps.rhythm.runEveningReview();
+            let output = `**Evening Review**\n\n`;
+            output += `${result.message}\n\n`;
+            output += `Assessment: ${result.assessment}\n`;
+            if (result.scoreUpdates.length) {
+              output += `\nScore updates:\n${result.scoreUpdates.map(s => `  ${s.goalId}: ${s.newScore} — ${s.reason}`).join('\n')}`;
+            }
+            return output;
+          } catch (err) {
+            return `Evening review error: ${err instanceof Error ? err.message : err}`;
+          }
+        }
+
+        case 'metrics': {
+          const m = deps.goalService.getMetrics();
+          return `**Goal Metrics**\n` +
+            `Total: ${m.total} | Active: ${m.active} | Completed: ${m.completed}\n` +
+            `Failed: ${m.failed} | Killed: ${m.killed}\n` +
+            `Avg OKR Score: ${m.avg_score.toFixed(2)}\n` +
+            `On Track: ${m.on_track} | At Risk: ${m.at_risk} | Behind: ${m.behind} | Critical: ${m.critical}\n` +
+            `Overdue: ${m.overdue}`;
+        }
+
+        case 'delete': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+          const deleted = deps.goalService.deleteGoal(goalId);
+          return deleted ? `Goal deleted (and all children).` : `Goal "${goalId}" not found.`;
+        }
+
+        case 'tree': {
+          const goalId = params.goal_id as string;
+          if (!goalId) return 'Error: "goal_id" is required.';
+
+          const tree = vault.getGoalTree(goalId);
+          if (tree.length === 0) return `Goal "${goalId}" not found.`;
+
+          return tree.map(g =>
+            `${'  '.repeat(levelDepth(g.level))}[${g.status}] ${g.title} (${g.level}, ${g.score})`
+          ).join('\n');
+        }
+
+        case 'overdue': {
+          const overdue = vault.getOverdueGoals();
+          if (overdue.length === 0) return 'No overdue goals. Keep it up.';
+          return `**${overdue.length} Overdue Goal(s):**\n` +
+            overdue.map(g =>
+              `  ${g.title} — due ${new Date(g.deadline!).toLocaleDateString()} (score: ${g.score})`
+            ).join('\n');
+        }
+
+        case 'escalations': {
+          const actions = deps.accountability.runEscalationCheck();
+          if (actions.length === 0) return 'No goals need escalation right now.';
+          return `**${actions.length} Escalation(s) Needed:**\n` +
+            actions.map(a =>
+              `  ${a.goalTitle}: ${a.currentStage} → ${a.newStage} (${a.weeksBehind} weeks behind)\n    ${a.message}`
+            ).join('\n\n');
+        }
+
+        default:
+          return `Unknown action "${action}". Available: create, list, get, score, update_status, update, decompose, replan, estimate, morning_plan, evening_review, metrics, delete, tree, overdue, escalations`;
+      }
+    },
+  };
+}
+
+function levelDepth(level: string): number {
+  const depths: Record<string, number> = {
+    objective: 0, key_result: 1, milestone: 2, task: 3, daily_action: 4,
+  };
+  return depths[level] ?? 0;
+}

package/src/actions/tools/local-tools-guard.ts

@@ -0,0 +1,31 @@
+/**
+ * Local Tools Guard — Module-level flag for --no-local-tools mode.
+ *
+ * Separate file to avoid circular dependencies between builtin.ts and desktop.ts.
+ */
+
+let _noLocalTools = false;
+
+export function setNoLocalTools(enabled: boolean): void {
+  _noLocalTools = enabled;
+  if (enabled) {
+    console.log('[Tools] Local tool execution disabled (--no-local-tools). Tools require a target sidecar.');
+  }
+}
+
+export function isNoLocalTools(): boolean {
+  return _noLocalTools;
+}
+
+export const LOCAL_DISABLED_MSG = 'Error: Local tool execution is disabled (--no-local-tools). Specify a "target" sidecar to route this command to a remote machine. Use list_sidecars to see available sidecars.';
+
+/** Default working directory for tools — set by site builder context per conversation turn. */
+let _defaultCwd: string | null = null;
+
+export function setDefaultCwd(cwd: string | null): void {
+  _defaultCwd = cwd;
+}
+
+export function getDefaultCwd(): string | null {
+  return _defaultCwd;
+}

package/src/actions/tools/registry.ts

@@ -0,0 +1,173 @@
+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();
+  /** Default working directory for tools like run_command. Set by site builder context. */
+  defaultCwd: string | null = null;
+
+  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".` };
+    }
+  },
+};