macro-agent 0.1.2 → 0.1.3

package/src/integrations/context-builder.ts

@@ -0,0 +1,280 @@
+/**
+ * Capabilities Context Builder
+ *
+ * Builds markdown context describing available swarmkit integrations
+ * for injection into agent system prompts. Matches cc-swarm's
+ * `buildCapabilitiesContext()` pattern from `context-output.mjs`.
+ *
+ * @module integrations/context-builder
+ */
+
+export interface CapabilitiesConfig {
+  /** Agent role (null = orchestrator/main, string = spawned agent) */
+  role?: string | null;
+  /** Team name for context */
+  teamName?: string;
+  minimem?: { enabled: boolean; status?: string };
+  skilltree?: { enabled: boolean; status?: string; profile?: string };
+  sessionlog?: { enabled: boolean; sync?: string };
+  mesh?: { enabled: boolean };
+  map?: { enabled: boolean; scope?: string; status?: string };
+  opentasks?: { enabled: boolean; status?: string };
+  inbox?: { enabled: boolean };
+}
+
+/**
+ * Build capabilities markdown for injection into agent system prompt.
+ * Matches cc-swarm's context format for consistency.
+ */
+export function buildCapabilitiesContext(
+  config: CapabilitiesConfig,
+): string {
+  const isAgent = config.role != null;
+  const lines: string[] = ["## Swarm Capabilities", ""];
+
+  // ── Team Orchestration ─────────────────────────────────────────
+  lines.push("### Team Orchestration");
+  lines.push("");
+  if (isAgent && config.teamName) {
+    lines.push(
+      `You are part of the **${config.teamName}** team. The orchestrator spawns and coordinates all teammates — spawned agents cannot spawn other agents.`,
+    );
+  } else {
+    lines.push(
+      "Use `/swarm` to launch a team from the configured topology, or `/swarm <template>` to pick a different one.",
+    );
+    lines.push(
+      "Available templates: **gsd**, **bmad-method**, **bug-fix-pipeline**, **docs-sync**, **security-audit**, and more.",
+    );
+    lines.push(
+      "Only the orchestrator spawns teammates — spawned agents cannot spawn other agents.",
+    );
+  }
+  lines.push("");
+
+  // ── Task Management ────────────────────────────────────────────
+  lines.push("### Task Management");
+  lines.push("");
+  const otActive =
+    config.opentasks?.enabled &&
+    (config.opentasks.status === "connected" ||
+      config.opentasks.status === "enabled");
+  if (otActive) {
+    lines.push("Use **opentasks MCP tools** for task management:");
+    lines.push(
+      "- `opentasks__create_task` — create tasks with metadata and links",
+    );
+    lines.push(
+      "- `opentasks__update_task` — claim, update status, annotate",
+    );
+    lines.push(
+      "- `opentasks__list_tasks` / `opentasks__query` — check progress, filter by status/assignee",
+    );
+    lines.push(
+      "Cross-system task graph supports linking (`opentasks__link`) and annotations.",
+    );
+    lines.push(
+      "Native Claude tasks are auto-federated into the graph via the claude-tasks provider.",
+    );
+  } else {
+    lines.push("Use Claude Code native task tools:");
+    lines.push("- `TaskCreate` — create tasks for the team");
+    lines.push("- `TaskUpdate` — claim (set owner), update status");
+    lines.push("- `TaskList` — check progress");
+    lines.push(
+      "Tasks are shared team-wide when agents use the same `team_name`.",
+    );
+  }
+  lines.push("");
+
+  // ── Communication ──────────────────────────────────────────────
+  lines.push("### Communication");
+  lines.push("");
+  lines.push(
+    'Use `SendMessage` for quick same-team agent-to-agent messaging:',
+  );
+  lines.push(
+    '- Direct: `SendMessage(recipient="<agent-name>", content="...")`',
+  );
+  lines.push(
+    "- Broadcast only when truly necessary (messages every teammate).",
+  );
+  lines.push("");
+  if (config.inbox?.enabled) {
+    lines.push(
+      "**Structured messaging** via agent-inbox MCP tools (persistent, threaded, cross-system):",
+    );
+    lines.push(
+      "- `agent-inbox__check_inbox(agentId)` — check for new messages (auto-marks as read)",
+    );
+    lines.push(
+      '- `agent-inbox__send_message(to, body, from)` — send to an agent, or `agent@system` for federated',
+    );
+    lines.push(
+      "- `agent-inbox__read_thread(threadTag)` — read full conversation thread",
+    );
+    lines.push(
+      "- `agent-inbox__list_agents()` — see who is registered (local + federated)",
+    );
+    lines.push("");
+    lines.push(
+      "Use inbox for: cross-system messages, threaded conversations, delivery tracking, messaging external observers.",
+    );
+    lines.push(
+      "Use `SendMessage` for: quick same-team coordination that doesn't need persistence.",
+    );
+  }
+  if (config.mesh?.enabled) {
+    lines.push(
+      "Encrypted P2P transport via MeshPeer with agent discovery.",
+    );
+  }
+  lines.push("");
+
+  // ── Memory (minimem) ───────────────────────────────────────────
+  if (
+    config.minimem?.enabled &&
+    config.minimem.status !== "disabled"
+  ) {
+    lines.push("### Memory");
+    lines.push("");
+    const ready =
+      !config.minimem.status || config.minimem.status === "ready";
+    if (ready) {
+      lines.push(
+        "Use **minimem MCP tools** for persistent, searchable team memory. Memory is shared team-wide.",
+      );
+      lines.push("");
+      lines.push("**Searching (two-phase workflow):**");
+      lines.push(
+        "1. `minimem__memory_search(query)` — returns compact index (path, score, preview)",
+      );
+      lines.push(
+        '2. `minimem__memory_get_details(results)` — fetch full text for relevant results',
+      );
+      lines.push(
+        'Use `detail: "full"` for quick lookups. Filter by type: `type: "decision"` (decision, bugfix, feature, discovery, context, note).',
+      );
+      lines.push("");
+      lines.push("**Knowledge search** (structured metadata):");
+      lines.push(
+        "- `minimem__knowledge_search(query, { domain, entities, minConfidence })` — filter by domain/entity/confidence",
+      );
+      lines.push(
+        "- `minimem__knowledge_graph(nodeId, depth)` — traverse knowledge relationships",
+      );
+      lines.push(
+        "- `minimem__knowledge_path(fromId, toId)` — find path between knowledge nodes",
+      );
+      lines.push("");
+      if (!isAgent) {
+        lines.push(
+          "**Storing memories** (use filesystem tools to write Markdown):",
+        );
+        lines.push(
+          "- `MEMORY.md` — important decisions and architecture notes",
+        );
+        lines.push(
+          "- `memory/YYYY-MM-DD.md` — daily logs and session notes",
+        );
+        lines.push("- `memory/<topic>.md` — topic-specific files");
+        lines.push("");
+        lines.push(
+          "Format entries with a type comment for filtered search:",
+        );
+        lines.push("```");
+        lines.push("### YYYY-MM-DD HH:MM");
+        lines.push("<!-- type: decision -->");
+        lines.push("<content>");
+        lines.push("```");
+        lines.push(
+          "Types: `decision`, `bugfix`, `feature`, `discovery`, `context`, `note`.",
+        );
+        lines.push(
+          "Wrap secrets in `<private>` tags to exclude from indexing.",
+        );
+        lines.push("");
+        lines.push(
+          "**Team strategy**: Search memory before spawning agents for prior context on the user's goal. After team completion, store key decisions and outcomes.",
+        );
+      } else {
+        lines.push(
+          "**Before major work**: Search memory for relevant prior decisions and context.",
+        );
+        lines.push(
+          "**After completing work**: Store key decisions and findings using filesystem tools — write to `memory/` files with `<!-- type: decision -->` tags.",
+        );
+      }
+    } else {
+      lines.push(
+        `Memory: ${config.minimem.status} (minimem installed but not fully ready).`,
+      );
+    }
+    lines.push("");
+  }
+
+  // ── Per-Role Skills (skill-tree) ───────────────────────────────
+  if (
+    config.skilltree?.enabled &&
+    config.skilltree.status !== "disabled"
+  ) {
+    lines.push("### Per-Role Skills");
+    lines.push("");
+    if (isAgent) {
+      lines.push(
+        "Your **skill loadout** is embedded in the `## Skills` section below. These are versioned, reusable patterns selected for your role.",
+      );
+      if (config.skilltree.profile) {
+        lines.push(
+          `Your loadout was compiled from the **${config.skilltree.profile}** profile.`,
+        );
+      }
+      lines.push(
+        "Read and apply these skills to guide your approach — they represent proven patterns for your type of work.",
+      );
+    } else {
+      lines.push(
+        "Each spawned agent receives a **skill loadout** compiled per-role and embedded in their system prompt.",
+      );
+      lines.push(
+        "Skills are versioned, reusable patterns from the skill-tree library, selected based on role profiles.",
+      );
+      lines.push("");
+      lines.push(
+        "Loadouts are configured via the `skilltree:` block in team.yaml, or auto-inferred from role names.",
+      );
+      lines.push(
+        "Built-in profiles: **code-review**, **implementation**, **debugging**, **security**, **testing**, **refactoring**, **documentation**, **devops**.",
+      );
+    }
+    lines.push("");
+  }
+
+  // ── External Observability (MAP) ───────────────────────────────
+  lines.push("### External Observability");
+  lines.push("");
+  if (config.map?.enabled) {
+    if (isAgent) {
+      lines.push(
+        "MAP is active — lifecycle and task events are emitted automatically. No direct interaction needed.",
+      );
+    } else {
+      lines.push(
+        `MAP: ${config.map.status ?? "connected"} (scope: ${config.map.scope ?? "default"})`,
+      );
+      lines.push(
+        "Agent lifecycle and task events are emitted automatically. No direct MAP interaction needed.",
+      );
+    }
+    if (config.sessionlog?.sync && config.sessionlog.sync !== "off") {
+      lines.push(
+        `Session trajectory checkpoints synced to MAP (level: ${config.sessionlog.sync}).`,
+      );
+    }
+  } else {
+    lines.push("No external observability configured.");
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/integrations/sessionlog.ts

@@ -0,0 +1,194 @@
+/**
+ * Sessionlog Integration
+ *
+ * Reads sessionlog state files to enrich trajectory checkpoints with
+ * turn-level metadata (turn IDs, token usage, step counts, etc.).
+ *
+ * Works with sessionlog's file format regardless of agent type —
+ * sessionlog has adapters for Claude Code, Codex, and generic agents.
+ *
+ * @module integrations/sessionlog
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { TrajectoryCheckpointPayload } from "../map/types.js";
+
+/** Sessionlog session state (subset of fields we need) */
+export interface SessionState {
+  sessionId: string;
+  phase: "active" | "ended";
+  turnId?: string;
+  stepCount?: number;
+  lastCheckpointId?: string;
+  tokenUsage?: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens?: number;
+    cache_read_tokens?: number;
+    api_call_count?: number;
+  };
+  filesTouched?: string[];
+  startedAt?: string;
+  endedAt?: string;
+}
+
+/**
+ * Find the active sessionlog session in the given working directory.
+ *
+ * Sessionlog stores state in `.git/sessionlog-sessions/<sessionId>/state.json`
+ * or in `.swarm/sessionlog/sessions/` depending on configuration.
+ */
+export function findActiveSession(cwd: string): SessionState | null {
+  const searchPaths = [
+    join(cwd, ".git", "sessionlog-sessions"),
+    join(cwd, ".swarm", "sessionlog", "sessions"),
+  ];
+
+  for (const sessionsDir of searchPaths) {
+    if (!existsSync(sessionsDir)) continue;
+
+    try {
+      const entries = readdirSync(sessionsDir, { withFileTypes: true });
+      const sessionDirs = entries
+        .filter((e) => e.isDirectory())
+        .sort((a, b) => b.name.localeCompare(a.name)); // Most recent first
+
+      for (const dir of sessionDirs) {
+        const statePath = join(sessionsDir, dir.name, "state.json");
+        if (!existsSync(statePath)) continue;
+
+        try {
+          const raw = readFileSync(statePath, "utf-8");
+          const state = JSON.parse(raw);
+
+          // Only return active (non-ended) sessions
+          if (state.phase === "ended") continue;
+
+          return {
+            sessionId: state.sessionId ?? dir.name,
+            phase: state.phase ?? "active",
+            turnId: state.turnId ?? state.currentTurnId,
+            stepCount: state.stepCount ?? state.totalSteps,
+            lastCheckpointId: state.lastCheckpointId,
+            tokenUsage: state.tokenUsage
+              ? {
+                  input_tokens: state.tokenUsage.inputTokens ?? state.tokenUsage.input_tokens ?? 0,
+                  output_tokens: state.tokenUsage.outputTokens ?? state.tokenUsage.output_tokens ?? 0,
+                  cache_creation_tokens: state.tokenUsage.cacheCreationTokens ?? state.tokenUsage.cache_creation_tokens,
+                  cache_read_tokens: state.tokenUsage.cacheReadTokens ?? state.tokenUsage.cache_read_tokens,
+                  api_call_count: state.tokenUsage.apiCallCount ?? state.tokenUsage.api_call_count,
+                }
+              : undefined,
+            filesTouched: state.filesTouched ?? state.files_touched,
+            startedAt: state.startedAt ?? state.started_at,
+            endedAt: state.endedAt ?? state.ended_at,
+          };
+        } catch {
+          // Corrupted state file — skip
+          continue;
+        }
+      }
+    } catch {
+      // Can't read sessions directory
+      continue;
+    }
+  }
+
+  return null;
+}
+
+/** Metadata to annotate a sessionlog session with swarm context */
+export interface SessionAnnotation {
+  teamName?: string;
+  template?: string;
+  scope?: string;
+  swarmId?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Annotate a sessionlog session with swarm metadata.
+ * Writes/merges metadata into the session's state.json file.
+ *
+ * Searches the same paths as `findActiveSession()`.
+ */
+export function annotateSession(
+  cwd: string,
+  metadata: SessionAnnotation,
+): boolean {
+  const searchPaths = [
+    join(cwd, ".git", "sessionlog-sessions"),
+    join(cwd, ".swarm", "sessionlog", "sessions"),
+  ];
+
+  for (const sessionsDir of searchPaths) {
+    if (!existsSync(sessionsDir)) continue;
+
+    try {
+      const entries = readdirSync(sessionsDir, { withFileTypes: true });
+      const sessionDirs = entries
+        .filter((e) => e.isDirectory())
+        .sort((a, b) => b.name.localeCompare(a.name));
+
+      for (const dir of sessionDirs) {
+        const statePath = join(sessionsDir, dir.name, "state.json");
+        if (!existsSync(statePath)) continue;
+
+        try {
+          const raw = readFileSync(statePath, "utf-8");
+          const state = JSON.parse(raw);
+
+          // Only annotate active sessions
+          if (state.phase === "ended") continue;
+
+          // Merge metadata into existing state
+          const annotated = {
+            ...state,
+            swarm: {
+              ...(state.swarm ?? {}),
+              ...metadata,
+            },
+          };
+          writeFileSync(statePath, JSON.stringify(annotated, null, 2));
+          return true;
+        } catch {
+          continue;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Enrich a trajectory checkpoint with sessionlog state data.
+ * Sessionlog data takes precedence over the base checkpoint when available.
+ */
+export function enrichCheckpoint(
+  state: SessionState,
+  base: TrajectoryCheckpointPayload,
+): TrajectoryCheckpointPayload {
+  return {
+    ...base,
+    // Use sessionlog token usage if available (more accurate than ACP stream tracking)
+    ...(state.tokenUsage ? { token_usage: state.tokenUsage } : {}),
+    // Merge files from sessionlog with existing
+    files_touched: [
+      ...new Set([
+        ...base.files_touched,
+        ...(state.filesTouched ?? []),
+      ]),
+    ],
+    metadata: {
+      ...base.metadata,
+      turnId: state.turnId ?? base.metadata?.turnId,
+      stepCount: state.stepCount ?? base.metadata?.stepCount,
+      lastCheckpointID: state.lastCheckpointId ?? base.metadata?.lastCheckpointID,
+      startedAt: state.startedAt ?? base.metadata?.startedAt,
+    },
+  };
+}

package/src/integrations/skilltree.ts

@@ -0,0 +1,183 @@
+/**
+ * Skill-tree Integration
+ *
+ * Compiles per-role skill loadouts from skill-tree's SkillBank API.
+ * Mirrors cc-swarm's `skilltree-client.mjs` but adapted for TypeScript
+ * and macro-agent's AgentManager.setSkillLoadout() API.
+ *
+ * Gracefully degrades when skill-tree is not installed — all public
+ * functions return null/empty rather than throwing.
+ *
+ * @module integrations/skilltree
+ */
+
+import { existsSync } from "node:fs";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Criteria for selecting skills into a loadout */
+export interface LoadoutCriteria {
+  profile?: string;
+  tags?: string[];
+  include?: string[];
+  taskDescription?: string;
+  maxSkills?: number;
+}
+
+/** Configuration for the skill-tree integration */
+export interface SkillTreeConfig {
+  enabled?: boolean;
+  basePath?: string;
+  defaultProfile?: string;
+}
+
+/** Result of compiling a role's loadout */
+export interface CompiledLoadout {
+  content: string;
+  profile: string;
+}
+
+// =============================================================================
+// Module cache
+// =============================================================================
+
+let _skillTreeModule: any = undefined;
+let _loadAttempted = false;
+
+/**
+ * Dynamically load the skill-tree package.
+ * Returns null if not available (graceful degradation).
+ */
+async function loadSkillTree(): Promise<any> {
+  if (_loadAttempted) return _skillTreeModule ?? null;
+  _loadAttempted = true;
+
+  try {
+    _skillTreeModule = await import("skill-tree");
+    return _skillTreeModule;
+  } catch {
+    _skillTreeModule = null;
+    return null;
+  }
+}
+
+// Exposed for testing
+export function _resetSkillTreeCache(): void {
+  _skillTreeModule = undefined;
+  _loadAttempted = false;
+}
+
+// =============================================================================
+// Role → Profile mapping
+// =============================================================================
+
+const ROLE_PROFILE_MAP: Record<string, string> = {
+  worker: "implementation",
+  executor: "implementation",
+  developer: "implementation",
+  "quick-flow-dev": "implementation",
+  debugger: "debugging",
+  verifier: "testing",
+  monitor: "testing",
+  qa: "testing",
+  "plan-checker": "code-review",
+  "integration-checker": "code-review",
+  integrator: "code-review",
+  "tech-writer": "documentation",
+  architect: "refactoring",
+  coordinator: "implementation",
+  "ux-designer": "documentation",
+  "security-auditor": "security",
+};
+
+/**
+ * Infer a skill-tree profile from a role name.
+ * Returns empty string if no match found.
+ */
+export function inferProfileFromRole(roleName: string): string {
+  // Direct match
+  if (ROLE_PROFILE_MAP[roleName]) return ROLE_PROFILE_MAP[roleName];
+
+  // Partial match (e.g., "senior-developer" matches "developer")
+  for (const [pattern, profile] of Object.entries(ROLE_PROFILE_MAP)) {
+    if (roleName.includes(pattern)) return profile;
+  }
+
+  return "";
+}
+
+// =============================================================================
+// Compilation
+// =============================================================================
+
+/**
+ * Compile a skill loadout for a single role.
+ * Creates a SkillBank, sets the loadout from profile/criteria,
+ * and returns the rendered markdown string.
+ *
+ * Returns null if skill-tree is not installed or compilation fails.
+ */
+export async function compileRoleLoadout(
+  roleName: string,
+  config: SkillTreeConfig = {},
+): Promise<string | null> {
+  const st = await loadSkillTree();
+  if (!st?.createSkillBank) return null;
+
+  const basePath = config.basePath ?? ".swarm/skill-tree";
+  if (!existsSync(basePath)) return null;
+
+  // Determine profile from config or inference
+  const profile = config.defaultProfile || inferProfileFromRole(roleName);
+  if (!profile) return null;
+
+  try {
+    const bank = st.createSkillBank({
+      storage: { basePath },
+    });
+    await bank.initialize();
+
+    try {
+      const { server } = await bank.createServingLayer({
+        outputFormat: "markdown",
+      });
+
+      try {
+        await server.setLoadoutFromProfile(profile);
+      } catch {
+        // Profile not found — skip
+        return null;
+      }
+
+      return server.renderSystemPrompt() as string;
+    } finally {
+      await bank.shutdown();
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compile skill loadouts for multiple roles.
+ * Returns a Map of roleName → rendered markdown content.
+ *
+ * Roles that fail to compile are silently skipped.
+ */
+export async function compileAllRoleLoadouts(
+  roles: string[],
+  config: SkillTreeConfig = {},
+): Promise<Map<string, string>> {
+  const result = new Map<string, string>();
+
+  for (const roleName of roles) {
+    const content = await compileRoleLoadout(roleName, config);
+    if (content) {
+      result.set(roleName, content);
+    }
+  }
+
+  return result;
+}