Massgen Run

You are orchestrating a MassGen multi-agent run. Multiple LLM agents will collaborate on the user's task through answer generation, voting, and consensus.

Pre-Flight Checks

Before doing anything else, verify the environment:

1. Read .massgen-quality/environment.json — check massgen.available and note massgen.source ("uvx" or "local:/path") for Step 3 launch method
2. If massgen unavailable: tell the user and provide install instructions:

   cd /path/to/massgen && uv sync
   

3. Read api_keys from .massgen-quality/environment.json — check which providers are authenticated. The hook checks both environment variables AND .env files (at $CWD/.env and $HOME/.env). If all keys show missing but the user says keys exist, check for a .env file and suggest creating one:

   # .env (at project root or $HOME)
   OPENAI_API_KEY=sk-...
   GOOGLE_API_KEY=AI...
   ANTHROPIC_API_KEY=sk-ant-...
   

   MassGen Docker configs already use env_file: .env for credential injection, so a .env file ensures keys are available in containers too.
4. Map requested backends to required keys:
   • openai, codex → openai key
   • gemini → google key
   • claude, claude_code → anthropic key
   • grok → xai key
5. Warn if any requested backend lacks its API key — skip that backend
6. If ALL backends lack keys: abort with clear message

Docker checks (unless --no-docker)

Docker is the default. Check:

1. Read docker from .massgen-quality/environment.json — check docker.available
2. If Docker unavailable: warn, suggest --no-docker, or ask user to start Docker
3. Check docker.image_available — if false:

   docker pull ghcr.io/massgen/mcp-runtime-sudo:latest
   # or build locally:
   cd /path/to/massgen && bash massgen/docker/build.sh --sudo
   

4. If user passed --no-docker: skip Docker config, use local execution mode

Step 1: Parse Arguments

Parse from the user's input:

• query: the task/question for agents
• --models: list of backend/model pairs (e.g., codex/gpt-5.4 gemini/gemini-3.1-pro-preview)
• --no-docker: disable Docker containerization
• --max-duration N: override orchestrator timeout (default: 1800s)

If no --models specified, use defaults based on available API keys:

• If openai + google available: openai/gpt-5.4 gemini/gemini-3.1-pro-preview (default pair)
• If only openai: openai/gpt-5.4
• If only google: gemini/gemini-3.1-pro-preview
• Include additional backends (claude, grok) as available

Note: coding agent backends (codex, claude_code) require Docker mode. Default to openai and gemini backends which work without Docker.

Step 2: Generate YAML Config

Write config to .massgen-quality/sessions/<session_id>/configs/run_<timestamp>.yaml (where <session_id> is run_<YYYYMMDD_HHMMSS>).

For each backend/model pair, create an agent entry. See references/config-templates.md for the full template.

context_paths (critical): Lives under orchestrator:, not agents:. Each entry is a {path, permission} dict. Agents can only see files in paths listed here. If the task involves specific files or a project directory, you MUST include the absolute path. Use read for reference material, write if agents should modify files:

orchestrator:
  context_paths:
    - path: "/absolute/path/to/project"
      permission: "read"

Key settings:

• ui.display_type: "simple" (must be valid; --automation overrides to silent)
• ui.logging_enabled: true

If Docker mode (not --no-docker), add per-agent:

• enable_code_based_tools: true
• exclude_file_operation_mcps: true
• enable_mcp_command_line: true
• command_line_execution_mode: docker
• command_line_docker_image: ghcr.io/massgen/mcp-runtime-sudo:latest
• command_line_docker_credentials with env_file and API keys

If --no-docker (or Docker unavailable): use local CLI execution instead:

• enable_mcp_command_line: true
• command_line_execution_mode: local
• Do NOT include Docker-specific fields (image, network, sudo, credentials) Agents can run commands and edit files directly on the host via local execution.

Step 3: Launch MassGen

MassGen runs take a while (often 5-30 minutes). Always use run_in_background: true on the Bash tool — the hard 10-minute timeout will kill foreground runs.

Read plugin_dir from .massgen-quality/environment.json. Use the massgen wrapper which handles API key sourcing and massgen resolution automatically:

bash "<plugin_dir>/scripts/run-massgen.sh" --automation \
  --config "<config_path>" \
  "<query>" 2>&1

Parse stderr output for automation status lines:

• LOG_DIR: <path> — the session log directory
• STATUS: <path> — path to status.json for monitoring

Launch sequence:

1. Run the command with run_in_background: true on the Bash tool
2. Tell the user the run is in progress and will take a while
3. Spawn a massgen-monitor background agent with the PID and LOG_DIR
4. The user will be notified on completion

Step 4: Extract and Present Results

Find status.json at <LOG_DIR>/turn_0/attempt_0/status.json (or latest turn/attempt).

Read and extract:

• results.winner — the winning agent ID
• results.votes — vote distribution
• agents.<id>.answer — each agent's answer
• agents.<id>.status — each agent's final status
• meta.elapsed_seconds — duration
• costs.total_estimated_cost — cost estimate

Present to the user:

1. Winning answer (from the consensus winner)
2. Vote distribution (which agents voted for whom)
3. Per-agent answers (collapsed/summarized if long)
4. Duration and cost

If the user wants to use the answer, offer to write it to a file or apply it.

Error Handling

• Exit code 1 (config error): Check the YAML config for syntax issues. Read the massgen log for details.
• Exit code 2 (execution error): An agent failed. Read status.json for agents.<id>.error details.
• Exit code 3 (timeout): Increase --max-duration or reduce agent count.
• massgen not found: Provide install instructions.
• Docker not available: Suggest --no-docker or starting Docker.