claude-code-swarm 0.3.3 → 0.3.5

package/references/minimem/src/store/store-graph.ts

@@ -0,0 +1,252 @@
+/**
+ * StoreGraph: meta-layer above Minimem for managing linked stores.
+ *
+ * A StoreGraph resolves a store and its dependencies (depth 1),
+ * materializes them as needed, and produces an array of MemoryInstance
+ * objects that can be passed to MemoryToolExecutor or used directly.
+ *
+ * The Minimem class is unchanged — StoreGraph just orchestrates
+ * multiple independent Minimem instances.
+ */
+
+import path from "node:path";
+
+import { Minimem, type MinimemConfig } from "../minimem.js";
+import type { MemoryInstance } from "../server/tools.js";
+import {
+  loadManifest,
+  getLinkedStoreNames,
+  resolveStore,
+  resolveStoreName,
+  type StoreManifest,
+  type StoreDefinition,
+} from "./manifest.js";
+import { materializeStore, type MaterializeResult } from "./materialize.js";
+
+export type StoreGraphOptions = {
+  /** Path to the global manifest file (default: ~/.config/minimem/stores.json) */
+  manifestPath?: string;
+  /** Factory to create a MinimemConfig for a given store directory */
+  configFactory?: (memoryDir: string, storeName: string) => Promise<MinimemConfig>;
+  /** Debug logging */
+  debug?: (message: string) => void;
+};
+
+export type ResolvedStore = {
+  name: string;
+  definition: StoreDefinition;
+  materialization: MaterializeResult;
+  instance: Minimem;
+};
+
+export class StoreGraph {
+  private manifest: StoreManifest;
+  private resolved: Map<string, ResolvedStore> = new Map();
+  private configFactory: (memoryDir: string, storeName: string) => Promise<MinimemConfig>;
+  private debug?: (message: string) => void;
+
+  private constructor(
+    manifest: StoreManifest,
+    opts?: StoreGraphOptions,
+  ) {
+    this.manifest = manifest;
+    this.debug = opts?.debug;
+    this.configFactory = opts?.configFactory ?? defaultConfigFactory;
+  }
+
+  /**
+   * Create a StoreGraph from the global manifest.
+   */
+  static async create(opts?: StoreGraphOptions): Promise<StoreGraph> {
+    const manifest = await loadManifest(opts?.manifestPath);
+    return new StoreGraph(manifest, opts);
+  }
+
+  /**
+   * Create a StoreGraph from an explicit manifest object (useful for testing).
+   */
+  static fromManifest(
+    manifest: StoreManifest,
+    opts?: StoreGraphOptions,
+  ): StoreGraph {
+    return new StoreGraph(manifest, opts);
+  }
+
+  /**
+   * Get the loaded manifest.
+   */
+  getManifest(): StoreManifest {
+    return this.manifest;
+  }
+
+  /**
+   * Resolve a store by name: materialize it and all its linked stores (depth 1).
+   * Returns an array of MemoryInstance objects ready for search.
+   *
+   * Linked stores that fail to materialize are skipped with a warning.
+   */
+  async resolve(storeName: string): Promise<MemoryInstance[]> {
+    const instances: MemoryInstance[] = [];
+
+    // Resolve the primary store
+    const primary = await this.resolveOne(storeName);
+    if (!primary) {
+      throw new Error(`Store "${storeName}" not found or unavailable`);
+    }
+    instances.push({
+      minimem: primary.instance,
+      memoryDir: primary.materialization.path,
+      name: storeName,
+    });
+
+    // Resolve linked stores (depth 1)
+    const linkedNames = await getLinkedStoreNames(this.manifest, storeName);
+    for (const linkedName of linkedNames) {
+      if (linkedName === storeName) continue; // skip self-links
+
+      try {
+        const linked = await this.resolveOne(linkedName);
+        if (linked) {
+          instances.push({
+            minimem: linked.instance,
+            memoryDir: linked.materialization.path,
+            name: linkedName,
+          });
+        } else {
+          this.debug?.(`Linked store "${linkedName}" unavailable, skipping`);
+        }
+      } catch (err) {
+        this.debug?.(
+          `Failed to resolve linked store "${linkedName}": ${String(err)}`,
+        );
+      }
+    }
+
+    return instances;
+  }
+
+  /**
+   * Resolve a store by directory path (looks up the store name in the manifest).
+   * Falls back to creating a standalone instance if the directory isn't in the manifest.
+   */
+  async resolveByPath(dirPath: string): Promise<MemoryInstance[]> {
+    const storeName = resolveStoreName(this.manifest, dirPath);
+    if (storeName) {
+      return this.resolve(storeName);
+    }
+
+    // Not in manifest — return standalone instance with no links
+    this.debug?.(`Directory "${dirPath}" not in manifest, using standalone`);
+    const config = await this.configFactory(dirPath, path.basename(dirPath));
+    const instance = await Minimem.create(config);
+    return [
+      {
+        minimem: instance,
+        memoryDir: dirPath,
+        name: path.basename(dirPath),
+      },
+    ];
+  }
+
+  /**
+   * List all known stores from the manifest with their link info.
+   */
+  async listStores(): Promise<
+    Array<{
+      name: string;
+      path: string;
+      remote?: string;
+      links: string[];
+      available: boolean;
+    }>
+  > {
+    const result: Array<{
+      name: string;
+      path: string;
+      remote?: string;
+      links: string[];
+      available: boolean;
+    }> = [];
+
+    for (const [name, def] of Object.entries(this.manifest.stores)) {
+      const links = await getLinkedStoreNames(this.manifest, name);
+      const { existsSync } = await import("node:fs");
+      const available = existsSync(def.path) || !!def.remote;
+
+      result.push({
+        name,
+        path: def.path,
+        remote: def.remote,
+        links,
+        available,
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Close all resolved Minimem instances and clean up materializations.
+   */
+  async close(): Promise<void> {
+    for (const [, store] of this.resolved) {
+      try {
+        store.instance.close();
+      } catch {
+        // best effort
+      }
+      try {
+        await store.materialization.cleanup();
+      } catch {
+        // best effort
+      }
+    }
+    this.resolved.clear();
+  }
+
+  /**
+   * Resolve a single store by name.
+   * Returns cached instance if already resolved.
+   */
+  private async resolveOne(storeName: string): Promise<ResolvedStore | null> {
+    // Return cached if available
+    const cached = this.resolved.get(storeName);
+    if (cached) return cached;
+
+    const def = resolveStore(this.manifest, storeName);
+    if (!def) return null;
+
+    // Materialize
+    const materialization = await materializeStore(storeName, def);
+    if (!materialization) return null;
+
+    // Create Minimem instance
+    const config = await this.configFactory(materialization.path, storeName);
+    const instance = await Minimem.create(config);
+
+    const resolved: ResolvedStore = {
+      name: storeName,
+      definition: def,
+      materialization,
+      instance,
+    };
+
+    this.resolved.set(storeName, resolved);
+    return resolved;
+  }
+}
+
+/**
+ * Default config factory: creates a minimal config with auto embedding.
+ * In practice, the CLI will provide a factory that respects per-store configs.
+ */
+async function defaultConfigFactory(
+  memoryDir: string,
+  _storeName: string,
+): Promise<MinimemConfig> {
+  return {
+    memoryDir,
+    embedding: { provider: "auto" },
+    watch: { enabled: false },
+  };
+}

package/references/minimem/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/references/minimem/tsup.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig([
+  // Library build
+  {
+    entry: ["src/index.ts", "src/session.ts", "src/internal.ts"],
+    format: ["esm", "cjs"],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+    target: "node22",
+    external: ["node-llama-cpp"],
+  },
+  // CLI build - bundle everything into single file
+  {
+    entry: ["src/cli/index.ts"],
+    format: ["esm"],
+    outDir: "dist/cli",
+    sourcemap: true,
+    target: "node22",
+    external: ["node-llama-cpp", "commander"],
+    banner: {
+      js: "#!/usr/bin/env node",
+    },
+  },
+]);

package/references/minimem/vitest.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    watch: false,
+    include: ["src/**/*.test.ts"],
+    exclude: [
+      "**/node_modules/**",
+      "**/clawdbot/**",
+      "**/dist/**",
+      // These tests use node:sqlite which Vite can't handle
+      // Run with: npm run test:integration or npm run test:cli
+      "**/*.integration.test.ts",
+      "**/cli/__tests__/commands.test.ts",
+      // knowledge.test.ts uses node:sqlite for graph tests — run via test:knowledge
+      // Frontmatter tests are in knowledge-frontmatter.test.ts (vitest-compatible)
+      "src/__tests__/knowledge.test.ts",
+      // store-graph tests use Minimem (node:sqlite) — run via test:integration
+      "src/store/__tests__/store-graph.test.ts",
+    ],
+    // Run tests sequentially to avoid XDG_CONFIG_HOME conflicts
+    pool: "forks",
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});

package/references/openteams/src/cli/generate.ts

@@ -26,6 +26,7 @@ export function createGenerateCommands(): Command {
       "Output path (default: <dir>/SKILL.md)"
     )
     .option("--no-cli-examples", "Omit CLI usage examples")
+    .option("--no-spawn-rules", "Omit spawn rules section")
     .action((dir: string, opts) => {
       try {
         const template = TemplateLoader.load(dir);
@@ -33,6 +34,7 @@ export function createGenerateCommands(): Command {
         const content = generateSkillMd(template, {
           teamName,
           includeCliExamples: opts.cliExamples !== false,
+          includeSpawnRules: opts.spawnRules !== false,
         });
 
         const outputPath = opts.output ?? path.join(dir, "SKILL.md");
@@ -55,6 +57,8 @@ export function createGenerateCommands(): Command {
       "Output directory for prompt files (default: <dir>/agents/)"
     )
     .option("--preamble <text>", "Additional context to prepend to every prompt")
+    .option("--no-spawn-section", "Omit spawn permissions from agent prompts")
+    .option("--no-cli-section", "Omit CLI quick reference from agent prompts")
     .action((dir: string, opts) => {
       try {
         const template = TemplateLoader.load(dir);
@@ -62,6 +66,8 @@ export function createGenerateCommands(): Command {
         const prompts = generateAgentPrompts(template, {
           teamName,
           preamble: opts.preamble,
+          includeSpawnSection: opts.spawnSection !== false,
+          includeCliSection: opts.cliSection !== false,
         });
 
         const outputDir = opts.output ?? path.join(dir, "agents");
@@ -92,6 +98,9 @@ export function createGenerateCommands(): Command {
       "Output base directory (default: <dir>)"
     )
     .option("--preamble <text>", "Additional context for agent prompts")
+    .option("--no-spawn-rules", "Omit spawn rules from SKILL.md")
+    .option("--no-spawn-section", "Omit spawn permissions from agent prompts")
+    .option("--no-cli-section", "Omit CLI quick reference from agent prompts")
     .action((dir: string, opts) => {
       try {
         const template = TemplateLoader.load(dir);
@@ -99,7 +108,10 @@ export function createGenerateCommands(): Command {
         const baseDir = opts.output ?? dir;
 
         // Generate SKILL.md
-        const skillContent = generateSkillMd(template, { teamName });
+        const skillContent = generateSkillMd(template, {
+          teamName,
+          includeSpawnRules: opts.spawnRules !== false,
+        });
         const skillPath = path.join(baseDir, "SKILL.md");
         fs.writeFileSync(skillPath, skillContent, "utf-8");
         console.log(`Generated ${skillPath}`);
@@ -108,6 +120,8 @@ export function createGenerateCommands(): Command {
         const prompts = generateAgentPrompts(template, {
           teamName,
           preamble: opts.preamble,
+          includeSpawnSection: opts.spawnSection !== false,
+          includeCliSection: opts.cliSection !== false,
         });
         const agentsDir = path.join(baseDir, "agents");
         fs.mkdirSync(agentsDir, { recursive: true });
@@ -136,6 +150,8 @@ export function createGenerateCommands(): Command {
       "-o, --output <path>",
       "Output directory (default: <dir>/package/)"
     )
+    .option("--no-spawn-section", "Omit spawn permissions from role SKILL.md files")
+    .option("--no-cli-section", "Omit CLI quick reference from role SKILL.md files")
     .action((dir: string, opts) => {
       try {
         const template = TemplateLoader.load(dir);
@@ -145,6 +161,8 @@ export function createGenerateCommands(): Command {
         const result = generatePackage(template, {
           teamName,
           outputDir,
+          includeSpawnSection: opts.spawnSection !== false,
+          includeCliSection: opts.cliSection !== false,
         });
 
         console.log(`Generated skill package in ${outputDir}`);
@@ -194,12 +212,16 @@ export function createGenerateCommands(): Command {
     .requiredOption("-r, --role <role>", "Role name")
     .option("-n, --name <name>", "Override the team name")
     .option("-o, --output <path>", "Output path (default: stdout)")
+    .option("--no-spawn-section", "Omit spawn permissions section")
+    .option("--no-cli-section", "Omit CLI quick reference section")
     .action((dir: string, opts) => {
       try {
         const template = TemplateLoader.load(dir);
         const teamName = opts.name ?? template.manifest.name;
         const result = generateRoleSkillMd(template, opts.role, {
           teamName,
+          includeSpawnSection: opts.spawnSection !== false,
+          includeCliSection: opts.cliSection !== false,
         });
 
         if (opts.output) {

package/references/openteams/src/generators/agent-prompt-generator.test.ts

@@ -311,6 +311,100 @@ describe("generateRoleSkillMd", () => {
   });
 });
 
+describe("section exclusion options (generateAgentPrompts)", () => {
+  it("includes spawn and CLI sections by default", () => {
+    const prompts = generateAgentPrompts(makeFullTemplate());
+    const planner = prompts.find((p) => p.role === "planner")!;
+    expect(planner.prompt).toContain("## Spawn Permissions");
+    expect(planner.prompt).toContain("## CLI Quick Reference");
+  });
+
+  it("excludes spawn section when includeSpawnSection is false", () => {
+    const prompts = generateAgentPrompts(makeFullTemplate(), {
+      includeSpawnSection: false,
+    });
+    for (const prompt of prompts) {
+      expect(prompt.prompt).not.toContain("## Spawn Permissions");
+    }
+  });
+
+  it("excludes CLI section when includeCliSection is false", () => {
+    const prompts = generateAgentPrompts(makeFullTemplate(), {
+      includeCliSection: false,
+    });
+    for (const prompt of prompts) {
+      expect(prompt.prompt).not.toContain("## CLI Quick Reference");
+    }
+  });
+
+  it("excludes both sections when both are false", () => {
+    const prompts = generateAgentPrompts(makeFullTemplate(), {
+      includeSpawnSection: false,
+      includeCliSection: false,
+    });
+    for (const prompt of prompts) {
+      expect(prompt.prompt).not.toContain("## Spawn Permissions");
+      expect(prompt.prompt).not.toContain("## CLI Quick Reference");
+    }
+  });
+});
+
+describe("section exclusion options (generateAgentPrompt single)", () => {
+  it("excludes spawn section when includeSpawnSection is false", () => {
+    const prompt = generateAgentPrompt(makeFullTemplate(), "planner", {
+      includeSpawnSection: false,
+    });
+    expect(prompt.prompt).not.toContain("## Spawn Permissions");
+    expect(prompt.prompt).toContain("## CLI Quick Reference");
+  });
+
+  it("excludes CLI section when includeCliSection is false", () => {
+    const prompt = generateAgentPrompt(makeFullTemplate(), "planner", {
+      includeCliSection: false,
+    });
+    expect(prompt.prompt).toContain("## Spawn Permissions");
+    expect(prompt.prompt).not.toContain("## CLI Quick Reference");
+  });
+});
+
+describe("section exclusion options (generateRoleSkillMd)", () => {
+  it("includes spawn and CLI sections by default", () => {
+    const result = generateRoleSkillMd(makeFullTemplate(), "planner");
+    expect(result.content).toContain("## Spawn Permissions");
+    expect(result.content).toContain("## CLI Quick Reference");
+    expect(result.content).toContain("can_spawn: [grinder, planner]");
+  });
+
+  it("excludes spawn section and can_spawn frontmatter when includeSpawnSection is false", () => {
+    const result = generateRoleSkillMd(makeFullTemplate(), "planner", {
+      includeSpawnSection: false,
+    });
+    expect(result.content).not.toContain("## Spawn Permissions");
+    expect(result.content).not.toContain("can_spawn:");
+    // CLI should still be included
+    expect(result.content).toContain("## CLI Quick Reference");
+  });
+
+  it("excludes CLI section when includeCliSection is false", () => {
+    const result = generateRoleSkillMd(makeFullTemplate(), "planner", {
+      includeCliSection: false,
+    });
+    expect(result.content).not.toContain("## CLI Quick Reference");
+    // Spawn should still be included
+    expect(result.content).toContain("## Spawn Permissions");
+  });
+
+  it("excludes both sections when both are false", () => {
+    const result = generateRoleSkillMd(makeFullTemplate(), "planner", {
+      includeSpawnSection: false,
+      includeCliSection: false,
+    });
+    expect(result.content).not.toContain("## Spawn Permissions");
+    expect(result.content).not.toContain("## CLI Quick Reference");
+    expect(result.content).not.toContain("can_spawn:");
+  });
+});
+
 describe("generateAllRoleSkillMds", () => {
   it("generates a skill md for each role", () => {
     const results = generateAllRoleSkillMds(makeFullTemplate());

package/references/openteams/src/generators/agent-prompt-generator.ts

@@ -16,6 +16,10 @@ export interface AgentPromptGeneratorOptions {
   teamName?: string;
   /** Additional context to prepend to every agent prompt */
   preamble?: string;
+  /** Whether to include the "Spawn Permissions" section. Defaults to true. */
+  includeSpawnSection?: boolean;
+  /** Whether to include the "CLI Quick Reference" section. Defaults to true. */
+  includeCliSection?: boolean;
 }
 
 export interface RoleSkillMd {
@@ -26,6 +30,10 @@ export interface RoleSkillMd {
 export interface RoleSkillMdOptions {
   /** Team name override */
   teamName?: string;
+  /** Whether to include the "Spawn Permissions" section. Defaults to true. */
+  includeSpawnSection?: boolean;
+  /** Whether to include the "CLI Quick Reference" section. Defaults to true. */
+  includeCliSection?: boolean;
 }
 
 /**
@@ -46,8 +54,10 @@ export function generateAgentPrompts(
   options: AgentPromptGeneratorOptions = {}
 ): AgentPrompt[] {
   const teamName = options.teamName ?? template.manifest.name;
+  const includeSpawn = options.includeSpawnSection ?? true;
+  const includeCli = options.includeCliSection ?? true;
   return template.manifest.roles.map((roleName) =>
-    generateSingleAgentPrompt(template, roleName, teamName, options.preamble)
+    generateSingleAgentPrompt(template, roleName, teamName, options.preamble, includeSpawn, includeCli)
   );
 }
 
@@ -60,11 +70,15 @@ export function generateAgentPrompt(
   options: AgentPromptGeneratorOptions = {}
 ): AgentPrompt {
   const teamName = options.teamName ?? template.manifest.name;
+  const includeSpawn = options.includeSpawnSection ?? true;
+  const includeCli = options.includeCliSection ?? true;
   return generateSingleAgentPrompt(
     template,
     roleName,
     teamName,
-    options.preamble
+    options.preamble,
+    includeSpawn,
+    includeCli,
   );
 }
 
@@ -81,6 +95,8 @@ export function generateRoleSkillMd(
   options: RoleSkillMdOptions = {}
 ): RoleSkillMd {
   const teamName = options.teamName ?? template.manifest.name;
+  const includeSpawn = options.includeSpawnSection ?? true;
+  const includeCli = options.includeCliSection ?? true;
   const m = template.manifest;
   const role = template.roles.get(roleName);
   const rolePrompts = template.prompts.get(roleName);
@@ -88,7 +104,7 @@ export function generateRoleSkillMd(
   const sections: string[] = [];
 
   // YAML frontmatter
-  sections.push(generateRoleFrontmatter(template, roleName, teamName));
+  sections.push(generateRoleFrontmatter(template, roleName, teamName, includeSpawn));
 
   // Identity header
   sections.push(`# Role: ${roleName}`);
@@ -133,10 +149,14 @@ export function generateRoleSkillMd(
   }
 
   // Spawn permissions
-  sections.push(generateRoleSpawnSection(template, roleName));
+  if (includeSpawn) {
+    sections.push(generateRoleSpawnSection(template, roleName));
+  }
 
   // CLI reference
-  sections.push(generateRoleCliSection(roleName, teamName, template));
+  if (includeCli) {
+    sections.push(generateRoleCliSection(roleName, teamName, template));
+  }
 
   return {
     role: roleName,
@@ -159,7 +179,8 @@ export function generateAllRoleSkillMds(
 function generateRoleFrontmatter(
   template: ResolvedTemplate,
   roleName: string,
-  teamName: string
+  teamName: string,
+  includeSpawn: boolean = true,
 ): string {
   const m = template.manifest;
   const role = template.roles.get(roleName);
@@ -198,10 +219,12 @@ function generateRoleFrontmatter(
     lines.push(`emits: [${emissions.join(", ")}]`);
   }
 
-  const spawnRules = m.topology.spawn_rules?.[roleName];
-  if (spawnRules && spawnRules.length > 0) {
-    const names = spawnRules.map((e) => typeof e === "string" ? e : e.role);
-    lines.push(`can_spawn: [${names.join(", ")}]`);
+  if (includeSpawn) {
+    const spawnRules = m.topology.spawn_rules?.[roleName];
+    if (spawnRules && spawnRules.length > 0) {
+      const names = spawnRules.map((e) => typeof e === "string" ? e : e.role);
+      lines.push(`can_spawn: [${names.join(", ")}]`);
+    }
   }
 
   lines.push("---");
@@ -275,7 +298,9 @@ function generateSingleAgentPrompt(
   template: ResolvedTemplate,
   roleName: string,
   teamName: string,
-  preamble?: string
+  preamble?: string,
+  includeSpawn: boolean = true,
+  includeCli: boolean = true,
 ): AgentPrompt {
   const m = template.manifest;
   const role = template.roles.get(roleName);
@@ -318,10 +343,14 @@ function generateSingleAgentPrompt(
   }
 
   // Spawn permissions
-  sections.push(generateRoleSpawnSection(template, roleName));
+  if (includeSpawn) {
+    sections.push(generateRoleSpawnSection(template, roleName));
+  }
 
   // CLI reference
-  sections.push(generateRoleCliSection(roleName, teamName, template));
+  if (includeCli) {
+    sections.push(generateRoleCliSection(roleName, teamName, template));
+  }
 
   return {
     role: roleName,

package/references/openteams/src/generators/package-generator.ts

@@ -10,6 +10,10 @@ export interface PackageGeneratorOptions {
   teamName?: string;
   /** Output directory for the package */
   outputDir: string;
+  /** Whether to include spawn permissions in per-role SKILL.md. Defaults to true. */
+  includeSpawnSection?: boolean;
+  /** Whether to include CLI quick reference in per-role SKILL.md. Defaults to true. */
+  includeCliSection?: boolean;
 }
 
 export interface PackageResult {
@@ -51,7 +55,11 @@ export function generatePackage(
   fs.writeFileSync(catalogPath, catalogContent, "utf-8");
 
   // 2. Generate per-role SKILL.md files
-  const roleSkills = generateAllRoleSkillMds(template, { teamName });
+  const roleSkills = generateAllRoleSkillMds(template, {
+    teamName,
+    includeSpawnSection: options.includeSpawnSection,
+    includeCliSection: options.includeCliSection,
+  });
   const rolePaths: { role: string; path: string }[] = [];
 
   for (const roleSkill of roleSkills) {