ai_ops/test_run.md

• For this repo, a “test run” can mean 3 different things. Configure based on which one you want.

1. npm run verify (typecheck + tests + build)

• Required:
  • Node + npm
  • Dependencies installed: npm install
• Not required:
  • API keys
• Command:
  • npm run verify

2. UI dry run (no external model calls, safest first run)

• Required:
  • npm install
  • topologies, personas, relationships, topologyConstraints
  • pipeline with entryNodeId, nodes, edges

3. Provider-backed run (Codex/Claude via CLI or UI executionMode=provider)

• Required:
  • Everything in #2
  • Auth for chosen provider:
    • Codex/OpenAI: OPENAI_AUTH_MODE + (CODEX_API_KEY or OPENAI_API_KEY) or existing Codex login
    • Claude: CLAUDE_CODE_OAUTH_TOKEN (preferred) or ANTHROPIC_API_KEY or existing Claude login
  • git available and workspace is a valid git repo (runtime provisions git worktrees)
• Optional:
  • mcp.config.json (default missing file is allowed if path is default)
• Important:
  • If you set custom MCP_CONFIG_PATH, that file must exist.

Environment groups you can tune (defaults already exist)

• Provider/auth: keys, auth mode, base URL, model, MCP path
• Limits: AGENT_MAX_, AGENT_TOPOLOGY_, AGENT_RELATIONSHIP_MAX_CHILDREN
• Provisioning: worktree root/base ref, port range/locks, discovery relative path
• Security: violation mode, allowlisted binaries, timeout, audit path, env inherit/scrub
• Telemetry/UI: runtime event log + Discord settings, AGENT_UI_HOST/PORT
• Do not set runtime-injected vars manually (AGENT_WORKTREE_PATH, AGENT_PORT_RANGE_START, etc.).

Practical first-run sequence

1. npm install
2. cp .env.example .env
3. npm run verify
4. npm run ui
5. Start a run in mock mode with a valid manifest
6. Switch to provider mode after auth is confirmed