@adaptic/maestro 1.8.4 → 1.9.1

package/scripts/setup/init-backup.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * init-backup.mjs — Off-machine state backup wizard.
+ *
+ * Configures `.maestro/backup-config.yaml` with bucket details and seeds
+ * a daily launchd plist that runs scripts/maintenance/backup-to-cloud.sh.
+ * Requires interactive input — does NOT auto-run.
+ */
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-backup]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-backup]  ⚠ ${m}\n`);
+
+mkdirSync(join(AGENT_DIR, ".maestro"), { recursive: true });
+const cfg = join(AGENT_DIR, ".maestro/backup-config.yaml");
+if (existsSync(cfg)) {
+  ok("backup-config.yaml already present");
+  process.exit(0);
+}
+
+writeFileSync(cfg, `# Off-machine state backup configuration
+# Fill in the bucket details, then run:
+#   maestro init backup-replication --apply
+#
+# Backups cover (configurable below):
+#   - state/   (queues, dashboards, inboxes — minus state/tmp/)
+#   - knowledge/
+#   - outputs/
+#   - logs/ (rotated archives only — current-day logs excluded)
+#   - config/agent.json (identity SOT)
+
+enabled: false
+provider: gcs            # gcs | s3 | rsync
+bucket: ""               # e.g. adaptic-maestro-backups
+prefix: agent-name-here  # e.g. ravi-ai (typically the repoSlug)
+schedule: "0 3 * * *"    # daily 03:00 local (overrides via launchd plist)
+include:
+  - state
+  - knowledge
+  - outputs
+  - logs
+  - config/agent.json
+exclude:
+  - state/tmp
+  - state/rag/index/*.bin
+retention_days: 30
+`);
+ok(`wrote ${cfg}`);
+warn("Backup is configured but NOT enabled. Edit .maestro/backup-config.yaml + set enabled: true, then re-run init.");

package/scripts/setup/init-cadence-bus.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * init-cadence-bus.mjs — Idempotent init step for the cadence-bus feature.
+ *
+ * Called by `maestro init` / `maestro upgrade` (via the feature-init
+ * tracker). Safe to run repeatedly. Verifies state/cadence-bus/{inbox,
+ * claimed,processed,failed,dlq} exist + logs/cadence-bus/ exists +
+ * generated launchd plists are on the cadence-bus arch.
+ */
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-cadence-bus]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-cadence-bus]  ⚠ ${m}\n`);
+
+// Directory tree (mirror of cadence-bus.mjs's bootstrap).
+for (const d of [
+  "state/cadence-bus/inbox",
+  "state/cadence-bus/claimed",
+  "state/cadence-bus/processed",
+  "state/cadence-bus/failed",
+  "state/cadence-bus/dlq",
+  "logs/cadence-bus",
+]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Version marker file.
+const versionFile = join(AGENT_DIR, "state/cadence-bus/VERSION");
+if (!existsSync(versionFile)) {
+  writeFileSync(versionFile, "1\n");
+  ok("seeded state/cadence-bus/VERSION");
+}
+
+// Plist arch verification — flag (don't fix here, that's upgrade's job).
+const plistDir = join(AGENT_DIR, "scripts/local-triggers/plists");
+if (existsSync(plistDir)) {
+  let legacy = 0;
+  for (const name of readdirSync(plistDir)) {
+    if (!name.endsWith(".plist")) continue;
+    const body = readFileSync(join(plistDir, name), "utf-8");
+    if (body.includes("run-trigger.sh")) legacy++;
+  }
+  if (legacy > 0) {
+    warn(`${legacy} generated plist(s) still use the legacy spawn-per-tick pattern.`);
+    warn("  Run: npx @adaptic/maestro upgrade  (will back up + regenerate)");
+  } else {
+    ok("plist arch verified");
+  }
+}
+
+ok("done");

package/scripts/setup/init-cost-tracking.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * init-cost-tracking.mjs — Set up local cost tracking ledger + dashboard.
+ *
+ * State:
+ *   state/cost-tracking/<date>.jsonl    — per-day token ledger
+ *   state/dashboards/cost-summary.yaml  — rollup
+ *
+ * The actual tracker is scripts/cost/track-claude-usage.mjs (shipped by the
+ * framework) which is wired into the cadence-consumer's session-spawn path.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-cost-tracking]  ✓ ${m}\n`);
+
+for (const d of ["state/cost-tracking", "state/dashboards"]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+const summary = join(AGENT_DIR, "state/dashboards/cost-summary.yaml");
+if (!existsSync(summary)) {
+  writeFileSync(summary, `# Cost summary — auto-regenerated by scripts/cost/track-claude-usage.mjs
+generated: null
+window_days: 7
+totals:
+  sessions: 0
+  input_tokens: 0
+  output_tokens: 0
+  estimated_usd: 0
+by_model: {}
+by_cadence: {}
+`);
+  ok("seeded cost-summary.yaml");
+}
+
+ok("done");

package/scripts/setup/init-decision-capture.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * init-decision-capture.mjs — Wire decision-capture automation.
+ *
+ * Ensures knowledge/decisions/{decision-schema,index}.yaml exist and
+ * creates scripts/decisions/capture-decision.mjs locally (the helper
+ * that the agent invokes when recording a decision).
+ */
+import { existsSync, mkdirSync, writeFileSync, copyFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-decision-capture]  ✓ ${m}\n`);
+
+for (const d of ["knowledge/decisions", "knowledge/decisions/archive", "scripts/decisions"]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Copy the framework's capture-decision helper if present.
+const src = join(MAESTRO_ROOT, "scripts/decisions/capture-decision.mjs");
+const dst = join(AGENT_DIR, "scripts/decisions/capture-decision.mjs");
+if (existsSync(src) && !existsSync(dst)) {
+  copyFileSync(src, dst);
+  ok(`copied capture-decision.mjs`);
+}
+
+// Seed index.yaml + schema if missing.
+const schemaPath = join(AGENT_DIR, "knowledge/decisions/decision-schema.yaml");
+if (!existsSync(schemaPath)) {
+  writeFileSync(schemaPath, `# Decision Record Schema (Maestro decision-capture v1)
+# Each decision is a YAML doc named DEC-YYYY-MM-DD-NNN.yaml under knowledge/decisions/.
+
+schema:
+  version: "1"
+  fields:
+    id:               { type: string, format: "DEC-YYYY-MM-DD-NNN", required: true }
+    date:             { type: date,   format: "YYYY-MM-DD",         required: true }
+    title:            { type: string, required: true }
+    domain:           { type: string, required: true }
+    decision_maker:   { type: string, required: true }
+    decision_text:    { type: string, required: true }
+    context:          { type: string, required: true }
+    rationale:        { type: string, required: true }
+    alternatives:     { type: array,  required: false }
+    stakeholders:     { type: array,  required: false }
+    expires_at:       { type: date,   required: false }
+    status:           { type: string, enum: [active, superseded, reversed, completed], default: active }
+`);
+  ok("seeded decision-schema.yaml");
+}
+
+const indexPath = join(AGENT_DIR, "knowledge/decisions/index.yaml");
+if (!existsSync(indexPath)) {
+  writeFileSync(indexPath, "# Decision Index — auto-maintained by capture-decision.mjs\ndecisions: []\n");
+  ok("seeded decision index");
+}
+
+ok("done");

package/scripts/setup/init-known-agents.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * init-known-agents.mjs — Scaffold config/known-agents.json
+ *
+ * The Adaptic agent roster is shipped as a starter; agents that have
+ * already populated their own known-agents.json keep theirs (this init
+ * step is idempotent and never overwrites).
+ *
+ * classifier.mjs reads this file at runtime to detect peer @mentions in
+ * Slack/Gmail so an agent doesn't respond to messages routed at another
+ * agent.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-known-agents]  ✓ ${m}\n`);
+
+const TARGET = join(AGENT_DIR, "config", "known-agents.json");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+const SCAFFOLD = join(MAESTRO_ROOT, "scaffold", "config", "known-agents.json");
+
+mkdirSync(dirname(TARGET), { recursive: true });
+
+if (existsSync(TARGET)) {
+  // Already present — verify shape and exit. We don't merge upstream
+  // additions into existing files to avoid surprising the operator.
+  try {
+    const current = JSON.parse(readFileSync(TARGET, "utf-8"));
+    const count = Array.isArray(current.agents) ? current.agents.length : 0;
+    ok(`already present (${count} agents)`);
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`[init-known-agents] existing file is invalid JSON: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+// Copy from scaffold (the framework's canonical roster); fall back to a
+// minimal stub if the scaffold is missing.
+let payload;
+if (existsSync(SCAFFOLD)) {
+  payload = readFileSync(SCAFFOLD, "utf-8");
+  ok(`copied from ${SCAFFOLD}`);
+} else {
+  payload = JSON.stringify({
+    schema_version: "1",
+    agents: [],
+  }, null, 2) + "\n";
+  ok("scaffold not found — wrote empty roster");
+}
+
+writeFileSync(TARGET, payload);
+ok(`wrote ${TARGET}`);

package/scripts/setup/init-memory-executive.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * init-memory-executive.mjs — Create memory/executive/ + memory/workstreams/
+ * Referenced by agents/ceo-briefing/agent.md and several skill prompts.
+ *
+ * Seeds priorities.md and open-loops.md so morning-brief / evening-wrap
+ * don't fail on a missing file.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-memory-executive]  ✓ ${m}\n`);
+
+const DIRS = [
+  "memory/executive",
+  "memory/workstreams",
+];
+
+for (const d of DIRS) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+const seeds = {
+  "memory/executive/priorities.md": "# Executive Priorities\n\nCurrent strategic priorities maintained by the agent. Updated weekly.\n\n_Populate via /init-maestro or by the weekly-priorities cadence._\n",
+  "memory/executive/open-loops.md": "# Open Loops\n\nOutstanding commitments awaiting closure. Updated by inbox-processor and evening-wrap cadences.\n\n_Format: each loop has owner, deadline, blocker, last-touched._\n",
+  "memory/workstreams/README.md": "# Workstreams\n\nOne markdown file per active workstream. Updated by the relevant cadence (weekly-execution, weekly-engineering-health, etc.) to reflect current status, blockers, and next milestones.\n",
+};
+
+for (const [path, body] of Object.entries(seeds)) {
+  const full = join(AGENT_DIR, path);
+  if (!existsSync(full)) {
+    writeFileSync(full, body);
+    ok(`seeded ${path}`);
+  }
+}
+
+ok("done");

package/scripts/setup/init-rag.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * init-rag.mjs — Bootstrap the local RAG index.
+ *
+ * Auto-discovers candidate repos under ~/ and writes them to
+ * config/repo-registry.yaml. By default this script is *not* auto-run
+ * because picking the right repos requires operator judgement. When run
+ * interactively, it lists candidates and asks for confirmation; when run
+ * with --yes it picks all ~/{repo}-ai siblings + adapticai/* clones.
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-rag]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-rag]  ⚠ ${m}\n`);
+
+const args = new Set(process.argv.slice(2));
+const autoYes = args.has("--yes") || args.has("-y");
+
+for (const d of ["state/rag", "state/rag/index", "scripts/rag"]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Discover candidate repos under $HOME.
+function discoverRepos() {
+  const home = homedir();
+  const candidates = [];
+  for (const name of readdirSync(home)) {
+    if (name.startsWith(".") || name === "ravi-ai" || name === "Library" || name === "Applications") continue;
+    const full = join(home, name);
+    try {
+      const st = statSync(full);
+      if (!st.isDirectory()) continue;
+      // Heuristic: looks like a code repo (.git or package.json or pyproject.toml).
+      const isRepo =
+        existsSync(join(full, ".git")) ||
+        existsSync(join(full, "package.json")) ||
+        existsSync(join(full, "pyproject.toml")) ||
+        existsSync(join(full, "go.mod")) ||
+        existsSync(join(full, "Cargo.toml"));
+      if (isRepo) {
+        candidates.push({ name, path: full });
+      }
+    } catch { /* ignore */ }
+  }
+  return candidates;
+}
+
+const candidates = discoverRepos();
+ok(`discovered ${candidates.length} candidate repo(s) under ${homedir()}`);
+
+const registryPath = join(AGENT_DIR, "config/repo-registry.yaml");
+let registry = { repositories: [] };
+if (existsSync(registryPath)) {
+  // Crude YAML re-read: just check whether `repositories: []` is empty.
+  const body = readFileSync(registryPath, "utf-8");
+  if (/repositories:\s*\[\s*\]/.test(body) || /repositories:\s*$/m.test(body)) {
+    // empty list — overwrite with discovered set if user opted in.
+  } else {
+    ok("config/repo-registry.yaml already populated — leaving as-is");
+    process.exit(0);
+  }
+}
+
+if (!autoYes) {
+  warn("Not running interactively — to populate, run with --yes:");
+  warn("  node scripts/setup/init-rag.mjs --yes");
+  warn("Candidates that would be added:");
+  for (const c of candidates) warn(`  - ${c.name} (${c.path})`);
+  process.exit(0);
+}
+
+// Build the YAML.
+const lines = [
+  "# Source Repository Registry",
+  "# Populated by scripts/setup/init-rag.mjs. Add/remove entries as needed.",
+  "# Format:",
+  "#   - name:    repo-slug",
+  "#     path:    ~/repo-slug",
+  "#     purpose: what this repo contains",
+  "#     index:   true | false  (indexed by state/rag/)",
+  "",
+  "repositories:",
+];
+for (const c of candidates) {
+  lines.push(`  - name: ${c.name}`);
+  lines.push(`    path: ${c.path}`);
+  lines.push(`    purpose: ""`);
+  lines.push(`    index: true`);
+}
+writeFileSync(registryPath, lines.join("\n") + "\n");
+ok(`wrote ${candidates.length} entries to config/repo-registry.yaml`);
+
+ok("done");

package/scripts/setup/init-session-router.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * init-session-router.mjs — Opt-in session router enablement.
+ *
+ * Session router enables LRU reuse of long-running Claude sessions for
+ * conversational items (Slack threads, Gmail threads). Requires
+ * SESSION_ROUTER_ENABLED=1 in .env. This init step appends that line if
+ * absent, but is intentionally `auto: false` in the registry so the
+ * operator confirms the decision.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-session-router]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-session-router]  ⚠ ${m}\n`);
+
+const envFile = join(AGENT_DIR, ".env");
+if (!existsSync(envFile)) {
+  warn(".env not present — create it first (copy .env.example).");
+  process.exit(0);
+}
+
+const body = readFileSync(envFile, "utf-8");
+if (/^SESSION_ROUTER_ENABLED=/m.test(body)) {
+  ok("SESSION_ROUTER_ENABLED already configured");
+} else {
+  const updated = body.replace(/\n*$/, "") + `\n\n# Session router (LRU reuse) — disabled by default. Set to 1 to enable.\nSESSION_ROUTER_ENABLED=1\n`;
+  writeFileSync(envFile, updated);
+  ok("appended SESSION_ROUTER_ENABLED=1 to .env");
+}
+
+// Touch the registry dir.
+mkdirSync(join(AGENT_DIR, "state/sessions"), { recursive: true });
+ok("done");