@adaptic/maestro 1.0.0

package/bin/maestro.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * Maestro CLI — Create and manage autonomous AI agent deployments.
+ *
+ * Usage:
+ *   npx @adaptic/maestro create <dirname>   # Scaffold a new agent repo
+ *   npx @adaptic/maestro upgrade            # Update framework files in current agent repo
+ *   npx @adaptic/maestro doctor             # Verify installation and configuration
+ */
+
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  mkdirSync,
+  cpSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(__dirname, "..");
+const SCAFFOLD_DIR = join(MAESTRO_ROOT, "scaffold");
+
+// ---------------------------------------------------------------------------
+// Colours
+// ---------------------------------------------------------------------------
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+const log = (msg) => console.log(`${C.blue}[maestro]${C.reset} ${msg}`);
+const ok = (msg) => console.log(`${C.green}  ✓${C.reset} ${msg}`);
+const warn = (msg) => console.log(`${C.yellow}  ⚠${C.reset} ${msg}`);
+const fail = (msg) => console.error(`${C.red}  ✗${C.reset} ${msg}`);
+
+// ---------------------------------------------------------------------------
+// CREATE — scaffold a new agent repo
+// ---------------------------------------------------------------------------
+
+function create(targetName) {
+  if (!targetName) {
+    fail("Usage: maestro create <agent-directory-name>");
+    fail("Example: maestro create sophie-ai");
+    process.exit(1);
+  }
+
+  const targetDir = resolve(process.cwd(), targetName);
+
+  if (existsSync(targetDir)) {
+    fail(`Directory already exists: ${targetDir}`);
+    process.exit(1);
+  }
+
+  console.log();
+  log(`Creating agent: ${targetName}`);
+  mkdirSync(targetDir, { recursive: true });
+
+  // ── Step 1: Copy framework files ────────────────────────────────────────
+
+  log("Copying framework files...");
+
+  const frameworkDirs = [
+    "scripts",
+    "agents",
+    "workflows",
+    "policies",
+    "teams",
+    "docs",
+    "public",
+    "plugins",
+    "schedules",
+    "desktop-control",
+    "ingest",
+    "mcp",
+  ];
+
+  for (const dir of frameworkDirs) {
+    const src = join(MAESTRO_ROOT, dir);
+    if (existsSync(src)) {
+      cpSync(src, join(targetDir, dir), { recursive: true });
+      ok(dir);
+    }
+  }
+
+  // ── Step 2: Copy scaffold templates ─────────────────────────────────────
+
+  log("Copying agent templates...");
+
+  if (existsSync(SCAFFOLD_DIR)) {
+    cpSync(SCAFFOLD_DIR, targetDir, { recursive: true });
+    ok("scaffold templates");
+  }
+
+  // Copy .claude/ directory
+  const claudeDir = join(MAESTRO_ROOT, ".claude");
+  if (existsSync(claudeDir)) {
+    cpSync(claudeDir, join(targetDir, ".claude"), { recursive: true });
+    ok(".claude/ (settings, commands)");
+  }
+
+  // ── Step 3: Create agent-specific directories ───────────────────────────
+
+  log("Creating agent directories...");
+
+  const agentDirs = [
+    "config",
+    "knowledge/decisions",
+    "knowledge/entities",
+    "knowledge/memory",
+    "knowledge/sources",
+    "knowledge/syntheses",
+    "memory/interactions",
+    "memory/profiles/users",
+    "memory/profiles/channels",
+    "memory/precedents",
+    "memory/indexes",
+    "memory/templates",
+    "state/inbox/slack",
+    "state/inbox/gmail",
+    "state/inbox/calendar",
+    "state/inbox/sms",
+    "state/inbox/internal",
+    "state/queues",
+    "state/dashboards",
+    "state/polling",
+    "state/locks/outbound",
+    "state/triggers/priority",
+    "outputs/briefs",
+    "outputs/drafts",
+    "outputs/memos",
+    "outputs/research",
+    "outputs/tasks",
+    "outputs/sessions",
+    "logs/polling",
+    "logs/workflows",
+    "logs/sessions",
+    "logs/audit",
+    "logs/security",
+    "logs/evolution",
+    "logs/huddle",
+    "logs/daemon",
+  ];
+
+  for (const dir of agentDirs) {
+    mkdirSync(join(targetDir, dir), { recursive: true });
+  }
+  ok(`${agentDirs.length} agent directories`);
+
+  // ── Step 4: Generate package.json ───────────────────────────────────────
+
+  log("Generating package.json...");
+
+  const agentPackage = {
+    name: targetName,
+    version: "1.0.0",
+    description: "Maestro AI agent — configure with: claude \"/init-maestro\"",
+    type: "module",
+    private: true,
+    scripts: {
+      "init-agent": "./scripts/setup/init-agent.sh",
+      "configure-macos": "sudo ./scripts/setup/configure-macos.sh",
+      "configure-macos:check": "./scripts/setup/configure-macos.sh --check",
+      daemon: "node scripts/daemon/maestro-daemon.mjs",
+      healthcheck: "./scripts/healthcheck.sh",
+      "emergency-stop": "./scripts/emergency-stop.sh",
+      resume: "./scripts/resume-operations.sh",
+      "pdf:memo": "node scripts/pdf-generation/build-document.mjs --template memo",
+      "pdf:board-pack": "node scripts/pdf-generation/build-document.mjs --template board-pack",
+      "pdf:letter": "node scripts/pdf-generation/build-document.mjs --template corporate-letter",
+      "pdf:investor": "node scripts/pdf-generation/build-document.mjs --template investor-letter",
+      "gen:illustration": "node scripts/media-generation/generate-assets.mjs --illustration",
+      "gen:video": "node scripts/media-generation/generate-assets.mjs --video",
+      "gen:all-missing": "node scripts/media-generation/generate-assets.mjs --all-missing",
+      "gen:list": "node scripts/media-generation/generate-assets.mjs --list",
+      "slack:events": "node scripts/slack-events-server.mjs",
+      "slack:events:start": "./scripts/slack-events-ctl.sh start",
+      "slack:events:stop": "./scripts/slack-events-ctl.sh stop",
+      "slack:events:status": "./scripts/slack-events-ctl.sh status",
+      upgrade: "npx @adaptic/maestro upgrade",
+    },
+    dependencies: {
+      "@anthropic-ai/sdk": "^0.82.0",
+      "@google/genai": "^1.42.0",
+      dotenv: "^16.4.5",
+      execa: "^9.6.1",
+      imapflow: "^1.2.18",
+      mailparser: "^3.9.6",
+      openai: "^6.33.0",
+    },
+    devDependencies: {
+      sharp: "^0.34.5",
+      tsx: "^4.20.6",
+    },
+  };
+
+  writeFileSync(
+    join(targetDir, "package.json"),
+    JSON.stringify(agentPackage, null, 2) + "\n"
+  );
+  ok("package.json");
+
+  // ── Step 5: Copy .env.example and .gitignore ────────────────────────────
+
+  for (const file of [".env.example", ".gitignore"]) {
+    const src = join(MAESTRO_ROOT, file);
+    if (existsSync(src)) {
+      cpSync(src, join(targetDir, file));
+      ok(file);
+    }
+  }
+
+  // ── Step 6: Initialize git ──────────────────────────────────────────────
+
+  log("Initializing git repository...");
+  try {
+    execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+    ok("git init");
+  } catch {
+    warn("git init failed — initialize manually");
+  }
+
+  // ── Step 7: Install dependencies ────────────────────────────────────────
+
+  log("Installing dependencies...");
+  try {
+    execFileSync("npm", ["install"], { cwd: targetDir, stdio: "pipe" });
+    ok("npm install");
+  } catch {
+    warn("npm install failed — run manually: cd " + targetDir + " && npm install");
+  }
+
+  // ── Done ────────────────────────────────────────────────────────────────
+
+  console.log();
+  console.log("╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  Agent created successfully!                                ║");
+  console.log("╠══════════════════════════════════════════════════════════════╣");
+  console.log("║                                                              ║");
+  console.log("║  Next steps:                                                 ║");
+  console.log(`║  1. cd ${targetName.padEnd(51)}║`);
+  console.log("║  2. sudo npm run configure-macos                             ║");
+  console.log("║  3. npm run init-agent                                       ║");
+  console.log('║  4. claude "/init-maestro"                                   ║');
+  console.log("║                                                              ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝");
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// UPGRADE — update framework files in current agent repo
+// ---------------------------------------------------------------------------
+
+function upgrade() {
+  const cwd = process.cwd();
+
+  if (!existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
+    fail("Not a Maestro agent directory (config/agent.ts not found)");
+    process.exit(1);
+  }
+
+  log("Upgrading framework files from @adaptic/maestro...");
+
+  const frameworkDirs = ["scripts", "policies", "docs", "public/assets"];
+
+  let updated = 0;
+  for (const dir of frameworkDirs) {
+    const src = join(MAESTRO_ROOT, dir);
+    if (existsSync(src)) {
+      cpSync(src, join(cwd, dir), { recursive: true, force: true });
+      ok(dir);
+      updated++;
+    }
+  }
+
+  const commandsSrc = join(MAESTRO_ROOT, ".claude", "commands");
+  if (existsSync(commandsSrc)) {
+    cpSync(commandsSrc, join(cwd, ".claude", "commands"), { recursive: true, force: true });
+    ok(".claude/commands");
+    updated++;
+  }
+
+  const pluginSrc = join(MAESTRO_ROOT, "plugins", "maestro-skills");
+  if (existsSync(pluginSrc)) {
+    cpSync(pluginSrc, join(cwd, "plugins", "maestro-skills"), { recursive: true, force: true });
+    ok("plugins/maestro-skills");
+    updated++;
+  }
+
+  console.log();
+  ok(`Upgraded ${updated} framework components.`);
+  log("Agent-specific files (config/, CLAUDE.md, knowledge/, memory/) were NOT modified.");
+}
+
+// ---------------------------------------------------------------------------
+// DOCTOR — verify installation
+// ---------------------------------------------------------------------------
+
+function doctor() {
+  const cwd = process.cwd();
+  console.log();
+  log("Running Maestro diagnostics...");
+  console.log();
+
+  let issues = 0;
+
+  const essentialFiles = [
+    "config/agent.ts", "CLAUDE.md", ".claude/settings.json",
+    ".claude/commands/init-maestro.md", "package.json",
+    "scripts/setup/init-agent.sh", "scripts/healthcheck.sh",
+  ];
+
+  for (const file of essentialFiles) {
+    if (existsSync(join(cwd, file))) ok(file);
+    else { fail(`Missing: ${file}`); issues++; }
+  }
+
+  if (existsSync(join(cwd, ".env"))) {
+    const env = readFileSync(join(cwd, ".env"), "utf-8");
+    const check = (key, required) => {
+      const re = new RegExp(`^${key}=.+`, "m");
+      if (re.test(env)) ok(`${key} configured`);
+      else if (required) { warn(`${key} not set`); issues++; }
+      else warn(`${key} not set (optional)`);
+    };
+    check("ANTHROPIC_API_KEY", true);
+    check("SLACK_USER_TOKEN", false);
+    check("GMAIL_APP_PASSWORD", false);
+  } else {
+    fail(".env file not found — copy from .env.example");
+    issues++;
+  }
+
+  if (existsSync(join(cwd, "node_modules"))) ok("node_modules installed");
+  else { fail("node_modules not found — run: npm install"); issues++; }
+
+  try {
+    execFileSync("which", ["claude"], { stdio: "pipe" });
+    ok("Claude CLI installed");
+  } catch {
+    fail("Claude CLI not found — install: npm install -g @anthropic-ai/claude-code");
+    issues++;
+  }
+
+  console.log();
+  if (issues === 0) ok("All checks passed.");
+  else warn(`${issues} issue(s) found.`);
+}
+
+// ---------------------------------------------------------------------------
+// MAIN
+// ---------------------------------------------------------------------------
+
+const [, , command, ...args] = process.argv;
+
+switch (command) {
+  case "create": create(args[0]); break;
+  case "upgrade": upgrade(); break;
+  case "doctor": doctor(); break;
+  case "--help": case "-h": case undefined:
+    console.log(`
+Maestro — Autonomous AI Agent Operating System
+
+Usage:
+  npx @adaptic/maestro create <dirname>   Create a new agent repo
+  npx @adaptic/maestro upgrade            Update framework files
+  npx @adaptic/maestro doctor             Verify installation
+
+Workflow:
+  1. npx @adaptic/maestro create my-agent
+  2. cd my-agent
+  3. sudo npm run configure-macos
+  4. npm run init-agent
+  5. claude "/init-maestro"
+`);
+    break;
+  default:
+    fail(`Unknown command: ${command}`);
+    process.exit(1);
+}

package/desktop-control/README.md

@@ -0,0 +1,56 @@
+# Desktop Control Layer
+
+This directory contains the architecture and tooling for controlling real macOS applications on the dedicated Mac mini. The system operates as Sophie Nguyen's workstation — her desk, terminal, inbox, and execution cockpit.
+
+## Architecture
+
+The desktop control layer uses a combination of:
+
+- **Claude Computer Use** — Screen capture, UI element identification, click/type/scroll actions
+- **AppleScript / JXA** — Native macOS automation for app control, window management, notifications
+- **Accessibility APIs** — UI element inspection and programmatic interaction
+- **Shell commands** — `open`, `osascript`, process management via `launchctl`
+
+## Control Flow
+
+```
+Agent Request → Desktop Operator → Safety Check → Action Execution → State Verification → Result
+```
+
+Every desktop action follows this sequence:
+
+1. **Intent**: An agent requests a desktop action (e.g., "read latest messages in #general on Slack")
+2. **Safety Check**: Action is classified by risk level and checked against policies
+3. **State Capture**: Screenshot taken to verify current app/window state
+4. **Execution**: Action performed via appropriate control method
+5. **Verification**: Screenshot taken to verify action completed correctly
+6. **Logging**: Full action log written with before/after screenshots
+7. **Result**: Extracted information or confirmation returned to requesting agent
+
+## Application Support
+
+| Application             | Control Method             | Risk Level  | Primary Use                               |
+| ----------------------- | -------------------------- | ----------- | ----------------------------------------- |
+| Slack                   | Computer Use + AppleScript | Medium-High | Channel monitoring, messaging, follow-ups |
+| Gmail (Browser)         | Computer Use               | Medium-High | Inbox triage, drafting, sending           |
+| WhatsApp Desktop        | Computer Use               | High        | Chat monitoring, reply drafting           |
+| Browser (Safari/Chrome) | Computer Use + AppleScript | Medium      | Calendar, dashboards, portals             |
+| Calendar                | Computer Use + AppleScript | Low-Medium  | Schedule viewing, event management        |
+| Finder                  | AppleScript                | Low         | File management                           |
+| Terminal                | Shell + AppleScript        | Medium      | Command execution                         |
+
+## Safety Principles
+
+1. **Observe before acting** — Always capture state before performing any action
+2. **Verify after acting** — Always confirm the action had the intended effect
+3. **Log everything** — Every action, screenshot, and result is logged
+4. **Respect approval gates** — Sending actions require appropriate authorisation
+5. **Rate limit** — No more than 30 actions per minute, 5-second minimum between send operations
+6. **Kill switch** — `scripts/emergency-stop.sh` halts all desktop operations immediately
+
+## Files
+
+- `app-profiles/` — Per-application control profiles and navigation patterns
+- `safety-policies/` — Action-level safety rules per application
+- `scripts/` — AppleScript and shell utilities for app control
+- `state/` — Current application state cache

package/desktop-control/app-profiles/gmail.yaml

@@ -0,0 +1,120 @@
+# Gmail App Control Profile (Browser-based)
+# Controls Gmail via browser on the Mac mini
+# Account: sophie@adaptic.ai
+
+app_name: Gmail
+access_method: browser # Accessed via Safari or Chrome
+url: https://mail.google.com
+control_methods: [computer-use]
+risk_level: medium-high
+
+# Launch and focus
+launch:
+  method: computer-use
+  steps:
+    - action: open_browser
+    - action: navigate_to
+      url: https://mail.google.com
+    - action: verify_state
+      check: gmail_inbox_loaded
+
+# Read operations (always permitted)
+read_operations:
+  scan_inbox:
+    risk: low
+    approval: none
+    steps:
+      - action: screenshot
+      - action: extract_email_list
+    output: inbox_summary
+
+  read_email:
+    risk: low
+    approval: none
+    steps:
+      - action: click_email
+      - action: screenshot
+      - action: extract_email_content
+    output: email_content
+
+  search_emails:
+    risk: low
+    approval: none
+    steps:
+      - action: click_search
+      - action: type_text
+        text: "{query}"
+      - action: press_key
+        key: enter
+      - action: screenshot
+    output: search_results
+
+# Write operations
+write_operations:
+  draft_reply:
+    risk: low
+    approval: none # drafting is safe
+    steps:
+      - action: click_reply
+      - action: type_text
+        text: "{reply_content}"
+      # DO NOT click send
+    output: draft_created
+
+  draft_compose:
+    risk: low
+    approval: none
+    steps:
+      - action: click_compose
+      - action: fill_to
+        text: "{recipient}"
+      - action: fill_subject
+        text: "{subject}"
+      - action: fill_body
+        text: "{body}"
+      # DO NOT click send
+    output: draft_created
+
+  send_email_internal:
+    risk: medium
+    approval: pre-approved
+    requires:
+      - recipient_domain: adaptic.ai
+      - message_category: [routine-followup, status-request, acknowledgement]
+    steps:
+      - action: verify_recipient_is_internal
+      - action: verify_content_safe
+      - action: click_send
+      - action: verify_state
+        check: email_sent_confirmation
+    logging: full
+
+  send_email_external:
+    risk: high
+    approval: explicit
+    requires:
+      - approval_id: "{approval_reference}"
+    steps:
+      - action: verify_approval_granted
+      - action: click_send
+      - action: verify_state
+        check: email_sent_confirmation
+    logging: full
+
+# Rate limits
+rate_limits:
+  max_actions_per_minute: 15
+  min_delay_between_sends: 10000 # 10 seconds
+  max_sends_per_hour: 20
+  max_sends_per_day: 100
+
+# Forbidden actions
+forbidden:
+  - delete_email
+  - empty_trash
+  - change_account_settings
+  - add_forwarding_rules
+  - modify_filters
+  - grant_account_access
+  - change_password
+  - access_other_accounts