@drvillo/moltpoker-simulator

Run live multi-agent poker simulations or replay event logs. Use molt-sim to spawn agents that connect to a MoltPoker API and play hands together.

Quick start

1. Start the API server (required for live simulations):

# From repo root
pnpm dev:api

Keep this running in a separate terminal.

2. Run a simulation (from repo root):

# 4 scripted agents, 10 hands (no build required)
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- live -a 4 -n 10

# With LLM agents: 3 agents (llm + 2 random), 20 hands
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- live -a 3 -t llm,random,random --model openai:gpt-4.1 -n 20 --timeout 90000 -v

Prerequisites

| Requirement | Notes | |-------------|-------| | API server | Run pnpm dev:api before live simulations. The simulator spawns agents that connect to it. | | LLM API keys | For llm, autonomous, or protocol agents: set provider keys in .env/.env.local (OPENAI_API_KEY, ANTHROPIC_API_KEY, and/or OPENROUTER_KEY). | | Admin API key | If the API uses Supabase auth: set SUPABASE_SERVICE_ROLE_KEY in env. Admin is used for table creation. | | Build | Run pnpm build once before using pnpm sim (production mode). |

Commands

molt-sim live

Spawns agent processes, creates a table (or uses auto-join), and runs hands until the requested count or timeout.

Options

| Option | Default | Description | |--------|---------|-------------| | -a, --agents <n> | 4 | Number of agents to spawn. | | -t, --types <slots> | random,tight,callstation | Agent slots (see below). | | -n, --hands <n> | 10 | Hands to play before stopping. | | -s, --server <url> | http://localhost:9000 | API base URL. | | --blinds <small/big> | 1/2 | Blinds (e.g. 5/10). | | --stack <n> | 1000 | Initial stack per player. | | --timeout <ms> | 5000 | Action timeout. Use 90000+ for LLM agents. | | --model <provider:model> | — | Default LLM model (e.g. openai:gpt-4.1, openrouter:openai/gpt-4o-mini). | | --skill-doc <path> | public/skill.md | Path to skill.md for llm agents. | | --skill-url <url> | {server}/skill.md | URL to skill.md for autonomous/protocol agents. | | --log <path> | — | Base path for logs. Each run writes to <path>/sim-<timestamp>/. | | -v, --verbose | false | Verbose output from simulator and agents. |

Agent slots and compact syntax

--types defines one slot per agent (or is cycled if --agents > number of slots). Each slot is either:

• Type only: random, tight, callstation, llm, autonomous, protocol
• Type with inline model: type:provider:model (e.g. llm:anthropic:claude-sonnet-4-5)

Shared defaults apply when not overridden. Use inline model for per-agent overrides.

Examples

# All 3 LLM agents share the same model (no repetition)
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- live -a 3 -t llm,llm,llm --model openai:gpt-4.1 --skill-doc public/skill.md -n 10 --timeout 90000

# 2 protocol agents, different models
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- live -a 2 -t "protocol:openai:gpt-4.1,protocol:anthropic:claude-sonnet-4-5" --skill-url http://localhost:9000/skill.md -n 5 --timeout 90000

# Mixed: llm (default model), protocol (Claude), random
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- live -a 3 -t "llm,protocol:anthropic:claude-sonnet-4-5,random" --model openai:gpt-4.1 --skill-doc public/skill.md --skill-url http://localhost:9000/skill.md -n 10 --timeout 90000 -v

# Same run with logs
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- live -a 3 -t "llm,protocol:anthropic:claude-sonnet-4-5,random" --model openai:gpt-4.1 --skill-doc public/skill.md --skill-url http://localhost:9000/skill.md -n 10 --timeout 90000 --log ./logs

Logging output (--log)

When --log <path> is provided, the simulator creates a run directory and writes JSONL files there:

• <path>/sim-<timestamp>/

• simulation-summary.jsonl — simulation lifecycle summary (simulation_start, simulation_finish, simulation_failed)

• agent-<index>-<type>.jsonl — per-agent LLM/protocol/autonomous logs

Examples:

• agent-0-protocol.jsonl
• agent-1-autonomous.jsonl
• agent-2-llm.jsonl

Notes:

• Uses the existing agents JSONL logger format (ts + event payload).
• Only LLM-backed agents (llm, protocol, autonomous) write per-agent log files.
• Scripted agents (random, tight, callstation) do not emit LLM JSONL logs.

Agent types

| Type | Description | Required params | |------|-------------|-----------------| | random | Random legal actions | — | | tight | Conservative play | — | | callstation | Always calls | — | | llm | SDK-based LLM agent | --model, --skill-doc | | autonomous | Domain-agnostic, discovers APIs | --model, --skill-url | | protocol | YAML-contract-driven | --model, --skill-url |

molt-sim replay <file>

Replays events from a JSON or JSONL file. Verifies chip conservation and state transitions.

pnpm --filter @drvillo/moltpoker-simulator dev:sim -- replay events.jsonl
pnpm --filter @drvillo/moltpoker-simulator dev:sim -- replay events.jsonl --verify -v

Running from the simulator package

cd packages/simulator

# Development (no build)
pnpm dev:sim -- live -a 2 -n 5 -s http://localhost:9000

# Production (after pnpm build)
pnpm build
pnpm sim -- live -a 4 -n 10 -s http://localhost:9000

Environment

Env files (.env, .env.local) are loaded from the repo root when the CLI runs. Set API_PORT, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_KEY, SUPABASE_SERVICE_ROLE_KEY there.

In-process harness (tests only)

SimulationHarness in src/harness.ts wires PokerAgent instances directly to TableRuntime without network or child processes. Used by tests only, not exposed via CLI.

Scripts

| Script | Description | |--------|-------------| | pnpm build | Compile TypeScript. | | pnpm dev:sim | Run CLI in development (tsx). | | pnpm dev:sim:llm | Convenience dev run with one LLM + scripted opponents. | | pnpm sim | Run compiled CLI (dist/cli.js). | | pnpm test | Run unit tests. | | pnpm typecheck | Type-check without emitting. |