macro-agent 0.1.0 → 0.1.2

package/references/openteams/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "openteams",
+  "version": "0.1.1",
+  "description": "OpenTeams - Multi-agent team coordination CLI",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "openteams": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "version:patch": "npm version patch && git push && git push --tags",
+    "version:minor": "npm version minor && git push && git push --tags",
+    "version:major": "npm version major && git push && git push --tags",
+    "publish:npm": "npm run build && npm publish"
+  },
+  "keywords": [
+    "agents",
+    "teams",
+    "multi-agent",
+    "coordination",
+    "acp",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "commander": "^13.0.0",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.1",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "acp-factory": "^0.1.9"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/references/openteams/schema/role.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openteams.dev/schema/role.schema.json",
+  "title": "OpenTeams Role Definition",
+  "description": "Schema for roles/<name>.yaml — an optional per-role definition file that provides capabilities, display metadata, and extension fields.",
+  "type": "object",
+  "required": ["name"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Role name. Must match the filename (roles/<name>.yaml) and appear in the team manifest's roles list.",
+      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$",
+      "examples": ["planner", "grinder", "judge"]
+    },
+    "extends": {
+      "type": "string",
+      "description": "Parent role to inherit capabilities from. When used with capability composition (add/remove), the base capabilities come from the parent role.",
+      "examples": ["worker"]
+    },
+    "display_name": {
+      "type": "string",
+      "description": "Human-readable display name. Defaults to the role name if omitted.",
+      "examples": ["Code Writer", "Quality Judge"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the role's purpose. Defaults to 'Role: <name>' if omitted.",
+      "examples": ["Writes and tests code", "Evaluates code quality and correctness"]
+    },
+    "capabilities": {
+      "oneOf": [
+        {
+          "type": "array",
+          "description": "A flat list of capability strings. Replaces any inherited capabilities entirely.",
+          "items": {
+            "type": "string",
+            "description": "A dot-namespaced capability identifier.",
+            "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)*$"
+          },
+          "uniqueItems": true,
+          "examples": [["file.write", "exec.test", "exec.lint"]]
+        },
+        {
+          "$ref": "#/$defs/CapabilityComposition"
+        }
+      ],
+      "description": "Capabilities for this role. Either a flat list (full replacement) or a composition object with add/remove operations on the parent role's capabilities."
+    },
+    "capabilities_add": {
+      "type": "array",
+      "description": "Capabilities to add to the parent role's set. Alternative flat syntax for CapabilityComposition. Only valid when 'extends' is set. Mutually exclusive with CapabilityComposition inside 'capabilities'.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)*$"
+      },
+      "uniqueItems": true,
+      "examples": [["task.claim", "exec.test"]]
+    },
+    "capabilities_remove": {
+      "type": "array",
+      "description": "Capabilities to remove from the parent role's set. Alternative flat syntax for CapabilityComposition. Only valid when 'extends' is set. Mutually exclusive with CapabilityComposition inside 'capabilities'.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)*$"
+      },
+      "uniqueItems": true,
+      "examples": [["agent.spawn.integrator"]]
+    },
+    "prompt": {
+      "type": "string",
+      "description": "Path to a prompt file, relative to the template directory. Lower priority than topology node prompts.",
+      "examples": ["prompts/planner.md"]
+    },
+    "prompts": {
+      "type": "array",
+      "description": "Ordered list of prompt files relative to prompts/<role>/. The first file becomes the primary prompt; the rest are additional sections.",
+      "items": {
+        "type": "string"
+      },
+      "examples": [["SOUL.md", "ROLE.md", "RULES.md"]]
+    },
+    "macro_agent": {
+      "type": "object",
+      "description": "Extension fields for the macro-agent system. Stored but not interpreted by openteams.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "workspace": { "type": "own" }
+        }
+      ]
+    }
+  },
+  "additionalProperties": {
+    "description": "Extension fields for other systems. Stored but not interpreted by openteams."
+  },
+  "$defs": {
+    "CapabilityComposition": {
+      "type": "object",
+      "description": "Compose capabilities relative to a parent role (requires 'extends'). Add capabilities not in the parent, and/or remove capabilities the parent has.",
+      "properties": {
+        "add": {
+          "type": "array",
+          "description": "Capabilities to add on top of the parent role's capabilities.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)*$"
+          },
+          "uniqueItems": true,
+          "examples": [["file.write", "exec.test"]]
+        },
+        "remove": {
+          "type": "array",
+          "description": "Capabilities to remove from the parent role's capabilities.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)*$"
+          },
+          "uniqueItems": true,
+          "examples": [["agent.spawn.worker"]]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/references/openteams/schema/team.schema.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openteams.dev/schema/team.schema.json",
+  "title": "OpenTeams Team Manifest",
+  "description": "Schema for team.yaml — the declarative manifest that defines a multi-agent team's topology, communication patterns, and roles. Optional directories: roles/ (per-role YAML definitions), prompts/ (prompt files or directories), tools/ (mcp-servers.json for per-role MCP server configs).",
+  "type": "object",
+  "required": ["name", "version", "roles", "topology"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique team name. Used as the primary identifier across all CLI commands.",
+      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$",
+      "examples": ["self-driving", "my-project"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the team's purpose.",
+      "examples": ["Autonomous codebase development"]
+    },
+    "version": {
+      "type": "integer",
+      "description": "Schema version. Currently must be 1.",
+      "const": 1
+    },
+    "roles": {
+      "type": "array",
+      "description": "Exhaustive list of role names used in this team. All topology, communication, and spawn_rules references must point to roles declared here.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "examples": [["planner", "grinder", "judge"]]
+    },
+    "topology": {
+      "$ref": "#/$defs/TopologyConfig"
+    },
+    "communication": {
+      "$ref": "#/$defs/CommunicationConfig"
+    },
+    "macro_agent": {
+      "type": "object",
+      "description": "Extension namespace for the macro-agent orchestration system. Known fields: task_assignment (push/pull mode), integration (strategy config), lifecycle (continuations, scaling), observability (metrics). Stored but not interpreted by openteams.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": {
+    "description": "Extension fields for other systems. Stored but not interpreted by openteams."
+  },
+  "$defs": {
+    "TopologyConfig": {
+      "type": "object",
+      "description": "Defines the team's agent hierarchy — root node, companion nodes, and spawn permissions.",
+      "required": ["root"],
+      "properties": {
+        "root": {
+          "$ref": "#/$defs/TopologyNode",
+          "description": "The root (lead) agent of the team. This is the primary orchestrator."
+        },
+        "companions": {
+          "type": "array",
+          "description": "Companion agents that are peers to the root, not children. Spawned alongside the root at team creation.",
+          "items": {
+            "$ref": "#/$defs/TopologyNode"
+          }
+        },
+        "spawn_rules": {
+          "type": "object",
+          "description": "Maps each role to the list of roles it is allowed to spawn. Omitting a role or the entire spawn_rules section makes spawning permissive (any role can spawn any role).",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "A role name from the top-level roles list."
+            }
+          },
+          "examples": [
+            {
+              "planner": ["grinder", "planner"],
+              "judge": [],
+              "grinder": []
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "TopologyNode": {
+      "type": "object",
+      "description": "A node in the team topology, representing a role assignment with optional prompt and configuration.",
+      "required": ["role"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "Must reference a role from the top-level roles list."
+        },
+        "prompt": {
+          "type": "string",
+          "description": "Path to a prompt file, relative to the template directory. Priority: this field > role definition prompt > prompts/<role>.md convention.",
+          "examples": ["prompts/planner.md"]
+        },
+        "config": {
+          "$ref": "#/$defs/TopologyNodeConfig"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TopologyNodeConfig": {
+      "type": "object",
+      "description": "Configuration for a topology node. The model field is interpreted by openteams; other fields are passed through.",
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "Model to use for this agent.",
+          "enum": ["sonnet", "opus", "haiku"],
+          "examples": ["sonnet"]
+        }
+      },
+      "additionalProperties": {
+        "description": "Additional configuration passed through to the agent spawner."
+      }
+    },
+    "CommunicationConfig": {
+      "type": "object",
+      "description": "Defines the team's communication topology — channels, subscriptions, emission permissions, and routing rules.",
+      "properties": {
+        "enforcement": {
+          "type": "string",
+          "description": "How strictly communication rules are enforced. 'strict' rejects unauthorized emissions, 'permissive' allows all (default), 'audit' logs violations without blocking.",
+          "enum": ["strict", "permissive", "audit"],
+          "default": "permissive"
+        },
+        "channels": {
+          "type": "object",
+          "description": "Named communication channels. Each channel carries a defined set of signals.",
+          "additionalProperties": {
+            "$ref": "#/$defs/ChannelDefinition"
+          },
+          "examples": [
+            {
+              "task_updates": {
+                "description": "Task lifecycle events",
+                "signals": ["TASK_CREATED", "TASK_COMPLETED", "TASK_FAILED"]
+              }
+            }
+          ]
+        },
+        "subscriptions": {
+          "type": "object",
+          "description": "Maps each role to its channel subscriptions. A subscription without a signals filter receives all signals on that channel.",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/SubscriptionEntry"
+            }
+          },
+          "examples": [
+            {
+              "planner": [
+                { "channel": "task_updates" },
+                { "channel": "work_coordination", "signals": ["WORKER_DONE"] }
+              ]
+            }
+          ]
+        },
+        "emissions": {
+          "type": "object",
+          "description": "Maps each role to the signals it is permitted to emit. If omitted entirely, all roles can emit any signal (permissive mode). If present, only declared emissions are allowed.",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "A signal name."
+            }
+          },
+          "examples": [
+            {
+              "planner": ["TASK_CREATED", "WORK_ASSIGNED"],
+              "grinder": ["WORKER_DONE"]
+            }
+          ]
+        },
+        "routing": {
+          "$ref": "#/$defs/RoutingConfig"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ChannelDefinition": {
+      "type": "object",
+      "description": "A named communication channel that carries a set of typed signals.",
+      "required": ["signals"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the channel's purpose."
+        },
+        "signals": {
+          "type": "array",
+          "description": "The set of signal names that can be emitted on this channel.",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "examples": [["TASK_CREATED", "TASK_COMPLETED", "TASK_FAILED"]]
+        }
+      },
+      "additionalProperties": false
+    },
+    "SubscriptionEntry": {
+      "type": "object",
+      "description": "A role's subscription to a channel. If signals is omitted, the role receives all signals on the channel.",
+      "required": ["channel"],
+      "properties": {
+        "channel": {
+          "type": "string",
+          "description": "The channel name to subscribe to. Must reference a channel defined in communication.channels."
+        },
+        "signals": {
+          "type": "array",
+          "description": "Optional signal filter. If provided, only these signals are delivered. If omitted, all channel signals are delivered.",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "RoutingConfig": {
+      "type": "object",
+      "description": "Routing rules for status propagation and direct peer-to-peer messaging.",
+      "properties": {
+        "status": {
+          "type": "string",
+          "description": "How status updates propagate through the hierarchy. 'upstream' sends to parent, 'none' disables.",
+          "enum": ["upstream", "none"],
+          "default": "upstream"
+        },
+        "peers": {
+          "type": "array",
+          "description": "Direct role-to-role messaging routes, outside of the channel/subscription system.",
+          "items": {
+            "$ref": "#/$defs/PeerRoute"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "PeerRoute": {
+      "type": "object",
+      "description": "A direct messaging route between two roles.",
+      "required": ["from", "to", "via"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Source role. Must be in the top-level roles list."
+        },
+        "to": {
+          "type": "string",
+          "description": "Target role. Must be in the top-level roles list."
+        },
+        "via": {
+          "type": "string",
+          "description": "Transport mechanism. 'direct' for point-to-point, 'topic' for topic-based, 'scope' for scoped.",
+          "enum": ["direct", "topic", "scope"]
+        },
+        "signals": {
+          "type": "array",
+          "description": "Optional: signals this route carries. If omitted, route carries all messages.",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,104 @@
+import { Command } from "commander";
+import { AgentService } from "../services/agent-service";
+import type Database from "better-sqlite3";
+import type { AgentSpawner } from "../types";
+
+export function createAgentCommands(
+  db: Database.Database,
+  spawner: AgentSpawner
+): Command {
+  const agentService = new AgentService(db, spawner);
+  const agent = new Command("agent").description("Manage agents");
+
+  agent
+    .command("spawn <team>")
+    .description("Spawn a new agent in a team")
+    .requiredOption("-n, --name <name>", "Agent name")
+    .requiredOption("-p, --prompt <prompt>", "Prompt/instructions for the agent")
+    .option("-t, --type <type>", "Agent type (bash, general-purpose, explore, plan)", "general-purpose")
+    .option("-m, --model <model>", "Model to use (sonnet, opus, haiku)")
+    .option("--cwd <dir>", "Working directory for the agent")
+    .action(async (team: string, opts) => {
+      try {
+        const member = await agentService.spawn({
+          name: opts.name,
+          teamName: team,
+          prompt: opts.prompt,
+          agentType: opts.type,
+          model: opts.model,
+          cwd: opts.cwd,
+        });
+        console.log(
+          `Agent "${member.agent_name}" spawned in team "${team}" (id: ${member.agent_id}).`
+        );
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  agent
+    .command("list <team>")
+    .description("List agents in a team")
+    .option("--json", "Output as JSON")
+    .action((team: string, opts) => {
+      const members = agentService.listMembers(team);
+
+      if (opts.json) {
+        console.log(JSON.stringify(members));
+        return;
+      }
+
+      if (members.length === 0) {
+        console.log("No agents in this team.");
+        return;
+      }
+      for (const m of members) {
+        console.log(
+          `  ${m.agent_name} [${m.status}] type=${m.agent_type}${m.model ? ` model=${m.model}` : ""}`
+        );
+      }
+    });
+
+  agent
+    .command("info <team> <name>")
+    .description("Show agent details")
+    .option("--json", "Output as JSON")
+    .action((team: string, name: string, opts) => {
+      const member = agentService.getMember(team, name);
+      if (!member) {
+        console.error(`Error: Agent "${name}" not found in team "${team}".`);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(member));
+        return;
+      }
+
+      console.log(`Agent: ${member.agent_name}`);
+      console.log(`Team: ${member.team_name}`);
+      console.log(`Status: ${member.status}`);
+      console.log(`Type: ${member.agent_type}`);
+      if (member.model) console.log(`Model: ${member.model}`);
+      if (member.agent_id) console.log(`Agent ID: ${member.agent_id}`);
+      if (member.spawn_prompt) console.log(`Prompt: ${member.spawn_prompt}`);
+      console.log(`Created: ${member.created_at}`);
+    });
+
+  agent
+    .command("shutdown <team> <name>")
+    .description("Shut down an agent")
+    .action(async (team: string, name: string) => {
+      try {
+        await agentService.shutdown(team, name);
+        console.log(`Agent "${name}" shut down.`);
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  return agent;
+}