macro-agent 0.2.4 → 0.2.6

package/src/integrations/context-builder.ts

@@ -1,280 +0,0 @@
-/**
- * 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

@@ -1,194 +0,0 @@
-/**
- * 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

@@ -1,184 +0,0 @@
-/**
- * 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 {
-    // @ts-ignore - optional peer dependency, may not be installed
-    _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;
-}