@adaptic/maestro 1.1.0 → 1.1.2

package/lib/tool-definitions.js

@@ -0,0 +1,510 @@
+/**
+ * Maestro — Comprehensive Tool Definitions
+ *
+ * Reusable tool schemas for Claude API tool_use, scoped by access level.
+ * Covers all operational capabilities an autonomous agent in an
+ * organisation like Adaptic might need.
+ *
+ * Categories:
+ *   1. Communication — Slack, Email, WhatsApp, SMS
+ *   2. Search / RAG — Email, Calendar, Files, Meetings, Slack, Web
+ *   3. Knowledge — Decisions, People, Regulatory, Strategy
+ *   4. Operations — Queues, Action Items, Scheduling
+ *   5. Analysis — Financial, Pipeline, Engineering Health
+ *   6. Document Generation — Memos, Briefs, Reports
+ *
+ * Usage:
+ *   import { getToolsForAccessLevel } from "@adaptic/maestro/lib/tool-definitions.js";
+ *   const tools = getToolsForAccessLevel("ceo");
+ *   // Pass to Claude API: { tools }
+ *
+ * @module tool-definitions
+ */
+
+// ============================================================================
+// 1. COMMUNICATION TOOLS
+// ============================================================================
+
+const slackSend = {
+  name: "slack_send",
+  description:
+    "Send a Slack message to a team member or channel. Confirm recipient and content before invoking.",
+  input_schema: {
+    type: "object",
+    properties: {
+      recipient: { type: "string", description: "Person or channel (e.g. 'Hootan', '#engineering')" },
+      message: { type: "string", description: "Message content" },
+      thread_ts: { type: "string", description: "Thread timestamp to reply in-thread (optional)" },
+      urgent: { type: "boolean", description: "Whether urgent (affects formatting)" },
+    },
+    required: ["recipient", "message"],
+  },
+};
+
+const draftEmail = {
+  name: "draft_email",
+  description:
+    "Draft or send an email. Drafts are saved for review; set urgency to 'immediate' to send now.",
+  input_schema: {
+    type: "object",
+    properties: {
+      to: { type: "string", description: "Recipient name or email" },
+      subject: { type: "string", description: "Subject line" },
+      body: { type: "string", description: "Email body" },
+      cc: { type: "string", description: "CC recipients (comma-separated)" },
+      voice: { type: "string", enum: ["agent", "principal"], description: "Whose voice (default: agent)" },
+      urgency: { type: "string", enum: ["routine", "urgent", "immediate"], description: "Urgency level" },
+    },
+    required: ["to", "subject", "body"],
+  },
+};
+
+const whatsappSend = {
+  name: "whatsapp_send",
+  description: "Send a WhatsApp message to a registered contact.",
+  input_schema: {
+    type: "object",
+    properties: {
+      recipient: { type: "string", description: "Person name" },
+      message: { type: "string", description: "Message content" },
+    },
+    required: ["recipient", "message"],
+  },
+};
+
+const smsSend = {
+  name: "sms_send",
+  description: "Send an SMS text message via Twilio.",
+  input_schema: {
+    type: "object",
+    properties: {
+      recipient: { type: "string", description: "Person name or phone number (E.164)" },
+      message: { type: "string", description: "Message content (160 char limit for single SMS)" },
+    },
+    required: ["recipient", "message"],
+  },
+};
+
+// ============================================================================
+// 2. SEARCH / RAG TOOLS
+// ============================================================================
+
+const searchEmail = {
+  name: "search_email",
+  description:
+    "Search Gmail for emails. Use for finding correspondence, checking what someone sent, recalling email threads.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Natural language or Gmail search syntax (e.g. 'from:hootan DFSA this week')" },
+      max_results: { type: "number", description: "Max results (default: 5)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchCalendar = {
+  name: "search_calendar",
+  description:
+    "Look up calendar events — meetings, availability, schedule. Returns titles, times, attendees.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to find (e.g. 'meetings tomorrow', 'next call with Shayan', 'free time Thursday')" },
+      time_range: { type: "string", description: "'today', 'tomorrow', 'this week', 'next week', or specific date" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchFiles = {
+  name: "search_files",
+  description:
+    "Search the agent's knowledge base, documents, and operational files. Covers knowledge/, config/, state/, docs/, outputs/.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to search for (e.g. 'DFSA submission status', 'rollup targets')" },
+      scope: { type: "string", enum: ["all", "knowledge", "config", "state", "docs", "outputs"], description: "Scope (default: all)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchMeetings = {
+  name: "search_meetings",
+  description:
+    "Search past meeting notes and transcripts. Use for recalling discussions, decisions, and action items from meetings.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to find in meeting notes (e.g. 'board meeting decisions', 'hiring discussion')" },
+      date_range: { type: "string", description: "Date range (e.g. 'last week', 'March 2026')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchSlack = {
+  name: "search_slack",
+  description:
+    "Search Slack message history across channels. Find conversations, decisions made in Slack, mentions.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query (e.g. 'Nima deployment', 'DFSA in #legal')" },
+      channel: { type: "string", description: "Limit to channel (optional)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchWeb = {
+  name: "search_web",
+  description:
+    "Search the web for current information. Use for market data, competitor intel, regulatory updates, news.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Web search query" },
+      max_results: { type: "number", description: "Max results (default: 5)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchDocuments = {
+  name: "search_documents",
+  description:
+    "Search shared documents in Google Drive, Confluence, or other document stores. Find reports, proposals, specs.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to find (e.g. 'investor deck Q1', 'board pack March')" },
+      doc_type: { type: "string", enum: ["all", "docs", "sheets", "slides", "pdf"], description: "Filter by type" },
+    },
+    required: ["query"],
+  },
+};
+
+// ============================================================================
+// 3. KNOWLEDGE / INSTITUTIONAL MEMORY TOOLS
+// ============================================================================
+
+const searchDecisions = {
+  name: "search_decisions",
+  description:
+    "Search the decision archive — past decisions, their rationale, who made them, and outcomes.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What decision to find (e.g. 'hiring freeze rationale', 'Singapore entity structure')" },
+    },
+    required: ["query"],
+  },
+};
+
+const lookupPerson = {
+  name: "lookup_person",
+  description:
+    "Look up information about a person — role, contact details, reporting line, recent activity, communication preferences.",
+  input_schema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Person's name" },
+      info_type: { type: "string", enum: ["all", "contact", "role", "activity", "preferences"], description: "What to look up" },
+    },
+    required: ["name"],
+  },
+};
+
+const searchRegulatory = {
+  name: "search_regulatory",
+  description:
+    "Search regulatory and compliance information — licence status, submission deadlines, compliance requirements, legal obligations.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Regulatory query (e.g. 'DFSA licence gaps', 'CIMA submission deadline', 'FCA requirements')" },
+      jurisdiction: { type: "string", description: "Jurisdiction filter (e.g. 'DIFC', 'Cayman', 'UK')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchStrategy = {
+  name: "search_strategy",
+  description:
+    "Search strategic context — priorities, OKRs, initiative status, strategic memos, competitive intelligence.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Strategic query (e.g. 'Project Aether status', 'Q2 priorities', 'competitive landscape')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchPrecedents = {
+  name: "search_precedents",
+  description:
+    "Search operational precedents — how similar situations were handled before, templates, playbooks.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Situation to find precedent for (e.g. 'investor objection handling', 'candidate rejection template')" },
+    },
+    required: ["query"],
+  },
+};
+
+// ============================================================================
+// 4. OPERATIONS TOOLS
+// ============================================================================
+
+const queueUpdate = {
+  name: "queue_update",
+  description:
+    "Update status or priority of an item in operational queues (action-stack, follow-ups, decision-queue).",
+  input_schema: {
+    type: "object",
+    properties: {
+      search_term: { type: "string", description: "Text to search in item titles (fuzzy match)" },
+      new_status: { type: "string", enum: ["open", "in_progress", "blocked", "resolved", "closed"] },
+      new_priority: { type: "string", enum: ["critical", "high", "medium", "low"] },
+      note: { type: "string", description: "Note to add to the item's history" },
+    },
+    required: ["search_term", "new_status"],
+  },
+};
+
+const createActionItem = {
+  name: "create_action_item",
+  description:
+    "Create a new action item, follow-up, or decision in the operational queues.",
+  input_schema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Brief title" },
+      queue: { type: "string", enum: ["action-stack", "follow-ups", "decision-queue", "tech-debt"], description: "Queue (default: action-stack)" },
+      priority: { type: "string", enum: ["critical", "high", "medium", "low"] },
+      due_date: { type: "string", description: "Due date YYYY-MM-DD" },
+      owner: { type: "string", description: "Responsible person (default: agent)" },
+      context: { type: "string", description: "Background context" },
+      blocked_by: { type: "string", description: "What blocks this item" },
+    },
+    required: ["title"],
+  },
+};
+
+const scheduleMeeting = {
+  name: "schedule_meeting",
+  description:
+    "Schedule a meeting on Google Calendar. Checks availability and sends invites.",
+  input_schema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Meeting title" },
+      attendees: { type: "string", description: "Attendee names or emails (comma-separated)" },
+      date: { type: "string", description: "Date (YYYY-MM-DD or 'tomorrow', 'next Monday')" },
+      time: { type: "string", description: "Time (HH:MM in agent timezone, or 'morning', 'afternoon')" },
+      duration: { type: "string", description: "Duration (e.g. '30m', '1h', default: 30m)" },
+      description: { type: "string", description: "Meeting description/agenda" },
+      location: { type: "string", description: "Location or video link" },
+    },
+    required: ["title", "attendees", "date"],
+  },
+};
+
+const createReminder = {
+  name: "create_reminder",
+  description:
+    "Set a reminder for the agent or principal. Fires via Slack DM at the specified time.",
+  input_schema: {
+    type: "object",
+    properties: {
+      message: { type: "string", description: "Reminder message" },
+      when: { type: "string", description: "When to remind (e.g. 'in 2 hours', 'tomorrow 9am', '2026-04-10 14:00')" },
+      for_whom: { type: "string", description: "Who to remind (default: principal)" },
+    },
+    required: ["message", "when"],
+  },
+};
+
+// ============================================================================
+// 5. ANALYSIS TOOLS
+// ============================================================================
+
+const searchFinancial = {
+  name: "search_financial",
+  description:
+    "Look up financial data — runway, burn rate, capital readiness, fundraising pipeline, AUM figures.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Financial query (e.g. 'current runway', 'fundraising status', 'AUM pipeline')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchPipeline = {
+  name: "search_pipeline",
+  description:
+    "Search the commercial/relationship pipeline — deal stages, partner status, investor conversations.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Pipeline query (e.g. 'acquisition targets status', 'investor conversations this month')" },
+      stage: { type: "string", enum: ["all", "prospecting", "engaged", "diligence", "closing", "closed"], description: "Filter by stage" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchEngineering = {
+  name: "search_engineering",
+  description:
+    "Search engineering health data — repo activity, PR status, delivery confidence, tech debt, deployment status.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Engineering query (e.g. 'adaptic-engine PR status', 'deployment blockers', 'tech debt priority')" },
+      repo: { type: "string", description: "Specific repository name (optional)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchHiring = {
+  name: "search_hiring",
+  description:
+    "Search hiring pipeline — open roles, candidate status, interview pipeline, offer tracking.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Hiring query (e.g. 'open engineering roles', 'candidates for CFO', 'offers pending')" },
+      status: { type: "string", enum: ["all", "open", "screening", "interviewing", "offer", "filled"], description: "Filter by status" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchRisk = {
+  name: "search_risk",
+  description:
+    "Search the enterprise risk register — active risks, mitigations, severity, ownership.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Risk query (e.g. 'critical risks', 'regulatory risks', 'unmitigated risks')" },
+      severity: { type: "string", enum: ["all", "critical", "high", "medium", "low"], description: "Filter by severity" },
+    },
+    required: ["query"],
+  },
+};
+
+// ============================================================================
+// 6. DOCUMENT GENERATION TOOLS
+// ============================================================================
+
+const generateMemo = {
+  name: "generate_memo",
+  description:
+    "Generate a branded PDF memo or brief. Saved to outputs/drafts/ and optionally shared via Slack.",
+  input_schema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Document title" },
+      content: { type: "string", description: "Memo content (markdown)" },
+      type: { type: "string", enum: ["memo", "brief", "board-pack", "letter", "investor"], description: "Document type" },
+      share_to: { type: "string", description: "Slack channel or person to share with (optional)" },
+    },
+    required: ["title", "content"],
+  },
+};
+
+const generateReport = {
+  name: "generate_report",
+  description:
+    "Generate an analytical report by aggregating data from dashboards, queues, and operational state.",
+  input_schema: {
+    type: "object",
+    properties: {
+      report_type: {
+        type: "string",
+        enum: ["executive-summary", "engineering-health", "hiring-pipeline", "strategy-scorecard", "leadership-accountability", "risk-register", "custom"],
+        description: "Report type",
+      },
+      custom_query: { type: "string", description: "For custom reports — what to analyse" },
+      time_range: { type: "string", description: "Time range (default: current)" },
+    },
+    required: ["report_type"],
+  },
+};
+
+// ============================================================================
+// ACCESS LEVEL SCOPING
+// ============================================================================
+
+// All lookup/search tools (read-only, safe for any authorised user)
+const lookupTools = [
+  searchEmail, searchCalendar, searchFiles, searchMeetings, searchSlack,
+  searchWeb, searchDocuments, searchDecisions, lookupPerson, searchRegulatory,
+  searchStrategy, searchPrecedents, searchFinancial, searchPipeline,
+  searchEngineering, searchHiring, searchRisk,
+];
+
+// Write tools (require higher access)
+const writeToolsCeo = [
+  slackSend, draftEmail, whatsappSend, smsSend,
+  queueUpdate, createActionItem, scheduleMeeting, createReminder,
+  generateMemo, generateReport,
+];
+
+const writeToolsLeadership = [
+  slackSend, draftEmail,
+  queueUpdate, createActionItem, scheduleMeeting, createReminder,
+];
+
+/**
+ * Get tools available for a caller's access level.
+ * @param {string} accessLevel - "ceo", "leadership", or "default"
+ * @returns {Array<object>} Claude API tool schemas
+ */
+export function getToolsForAccessLevel(accessLevel) {
+  switch (accessLevel) {
+    case "ceo":
+      return [...writeToolsCeo, ...lookupTools];
+    case "leadership":
+      return [...writeToolsLeadership, ...lookupTools];
+    case "default":
+      return [...lookupTools]; // Read-only — search and lookup only
+    default:
+      return [];
+  }
+}
+
+/**
+ * Get tool names for an access level.
+ * @param {string} accessLevel
+ * @returns {string[]}
+ */
+export function getToolNamesForAccessLevel(accessLevel) {
+  return getToolsForAccessLevel(accessLevel).map((t) => t.name);
+}
+
+/**
+ * Get all tool definitions (for documentation / init-maestro generation).
+ * @returns {{ communication: object[], search: object[], knowledge: object[], operations: object[], analysis: object[], documents: object[] }}
+ */
+export function getAllToolsByCategory() {
+  return {
+    communication: [slackSend, draftEmail, whatsappSend, smsSend],
+    search: [searchEmail, searchCalendar, searchFiles, searchMeetings, searchSlack, searchWeb, searchDocuments],
+    knowledge: [searchDecisions, lookupPerson, searchRegulatory, searchStrategy, searchPrecedents],
+    operations: [queueUpdate, createActionItem, scheduleMeeting, createReminder],
+    analysis: [searchFinancial, searchPipeline, searchEngineering, searchHiring, searchRisk],
+    documents: [generateMemo, generateReport],
+  };
+}

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {
     "maestro": "./bin/maestro.mjs"
   },
+  "exports": {
+    ".": "./lib/index.js",
+    "./tools": "./lib/tool-definitions.js",
+    "./executor": "./lib/action-executor.js",
+    "./singleton": "./lib/singleton.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin/",
+    "lib/",
     "scaffold/",
     "scripts/",
     "agents/",
@@ -24,6 +32,7 @@
     ".claude/commands/",
     ".claude/settings.json",
     ".env.example",
+    ".gitignore",
     "README.md"
   ],
   "publishConfig": {