cmuxlayer

Instructions

Implementation Reference

• src/agent-engine.ts:317-340 (handler)

  The core implementation of the agent spawning logic.

  async spawnAgent(params: SpawnAgentParams): Promise<SpawnAgentResult> {
    const agentId = generateAgentId(params.model, params.repo);
  
    // Resolve parent hierarchy
    let spawnDepth = 0;
    let parentAgentId: string | null = null;
  
    if (params.parent_agent_id) {
      const parent = this.registry.get(params.parent_agent_id);
      if (!parent) {
        throw new Error(`Parent agent not found: ${params.parent_agent_id}`);
      }
      if (parent.spawn_depth >= MAX_SPAWN_DEPTH) {
        throw new Error(`Max spawn depth exceeded: ${MAX_SPAWN_DEPTH}`);
      }
      const children = this.registry.getChildren(params.parent_agent_id);
      if (children.length >= MAX_CHILDREN) {
        throw new Error(`Max children exceeded: ${MAX_CHILDREN}`);
      }
      spawnDepth = parent.spawn_depth + 1;
      parentAgentId = params.parent_agent_id;
    }
  
    // 1. Create cmux surface

• src/server.ts:684-714 (registration)

  Registration of the 'spawn_agent' MCP tool and its invocation handler in server.ts.

  server.tool(
    "spawn_agent",
    "Spawn an AI agent in a new terminal surface. Returns immediately — use wait_for to block until ready.",
    {
      repo: z
        .string()
        .describe("Repository name (e.g. 'brainlayer', 'golems')"),
      model: z
        .string()
        .describe("Model name (e.g. 'sonnet', 'codex', 'opus')"),
      cli: z
        .enum(["claude", "codex", "gemini", "kiro", "cursor"])
        .describe("CLI tool to launch"),
      prompt: z.string().describe("Task prompt to send after agent is ready"),
      workspace: z.string().optional().describe("Target workspace ref"),
    },
    async (args) => {
      try {
        const result = await engine.spawnAgent({
          repo: args.repo,
          model: args.model,
          cli: args.cli,
          prompt: args.prompt,
          workspace: args.workspace,
        });
        return ok({ ...result });
      } catch (e) {
        return err(e);
      }
    },
  );

• src/agent-engine.ts:20-28 (schema)

  Parameter definition for the spawnAgent operation.

  export interface SpawnAgentParams {
    repo: string;
    model: string;
    cli: CliType;
    prompt: string;
    workspace?: string;
    parent_agent_id?: string;
    max_cost_per_agent?: number;
  }