agent-smoke
Spawn live AI-player panel runs of the agent-player harness via Sonnet subagents — the three-persona breadth smoke, the five-day arc panel, and the interrupted shape — then aggregate them with `npm run agent:panel`. Use when asked to smoke-test the game with real LLM players, run live playthroughs, QA the agent-player end-to-end, or "spawn AI players". Each run reaches its model through OpenRouter on its own key (`AGENT_OPENROUTER_API_KEY`).
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agent-smoke
- description
- Spawn live AI-player panel runs of the agent-player harness via Sonnet subagents — the three-persona breadth smoke, the five-day arc panel, and the interrupted shape — then aggregate them with `npm run agent:panel`. Use when asked to smoke-test the game with real LLM players, run live playthroughs, QA the agent-player end-to-end, or "spawn AI players". Each run reaches its model through OpenRouter on its own key (`AGENT_OPENROUTER_API_KEY`).
- allowed-tools
- Agent, Bash, Read
03 SKILL.md 正文
Agent panels
The agent-player harness (src/agent/, milestone M4) plays the whole game with a real LLM brain over OpenRouter (DeepSeek V4.1 Flash, pinned to the DeepSeek host) on a prod-faithful in-memory engine, then a critic LLM reviews the run. Since the persona rework it also takes a persona (AGENT_PERSONA), captures friction and a day note in the same reply, and pays one extra call for a persona-voiced review. npm test only ever uses stubs — the real path is opt-in via npm run agent:play. This skill fans that live path out across Sonnet subagents as a panel: N runs, one directory, one aggregate.
A single run is the degenerate panel, not the default. Pick a shape, run the fleet, aggregate the directory.
Two channels, never conflated
A transcript finding is a harness or engine bug (an error finding is a real bug; flag it). A persona friction is a design signal, tagged once / periodic / ritual, not a bug report: file it as an issue, one per item, labelled from .github/labels.yml (area:* / type:*), never on the blocker list. Engine anomaly logs on stderr ([category-telemetry], [travel-gate], set_location) are self-recovered content or tuning notes, also an issue. Same split the skill has always carried.
The three shapes
| Shape | Fleet | Answers | Cost | Order |
|---|---|---|---|---|
| Breadth smoke | 3 personas × 1 day, plus the unset control | The machinery gate: aggregation, review parsing, the anti-theatre histograms. A JSON contract that does not parse is the failure every other shape would hit at full price | ~0.6M tokens (measured on the 2026-09-14 smoke) | First, always |
| Arc panel | 4 personas × 5 days | The retention instrument, and the only shape that answers the core goal: the engagement/fulfilment series, the day the arcNote stops growing, content exhaustion, aliveness/memory coverage |
~3M tokens | After the smoke |
| Interrupted panel | 1 persona (lapsed-returner) with AGENT_SKIP_DAYS |
The absence consequence: the five-day absence nudge, re-entry, whether coming back is worth it | ~0.3M tokens (two paid days) | Last, or when the absence path is the question |
Never pay for the arc panel before the three-persona smoke has passed. The smoke costs a tenth of an arc and catches the contract failures.
Always include the unset control
Every panel shape includes one run on the same commit with AGENT_PERSONA unset, in the same directory. Without it the persona signal is confounded with the wider move and information surface: a free-text share that rose because the menu widened reads exactly like one that rose because a persona wanted it, and the panel has nothing to compare against. The control arm also writes no review, so it appears in the histogram and day-note tables but not the persona matrices. This is not optional advice — it is the arm the whole reading is relative to.
Pin every start to noon UTC
Every run's AGENT_START_DATE must be a noon-UTC instant (2026-09-15T12:00:00Z), not a bare date and not a local-time stamp. The day-start greeting reads the local weekday (hiScreen.isWeekend() is new Date().getDay()) while the nightly tick reads UTC (getUTCDay() === 6), so a start a few hours either side of UTC midnight can greet the player with the weekend copy on a day whose tick grants the weekday roll allowance, and which side you land on depends on the host's timezone. Noon UTC leaves eleven hours of slack either way, so the two weekdays agree in any plausible host timezone and across a multi-day run's one-day steps.
Env knobs
AGENT_OPENROUTER_API_KEY must be in .env, and it is a different key from the bot's OPENROUTER_API_KEY. It is not auto-loaded — subagents must source it: set -a && . ./.env && set +a && <command>. agent:play refuses to start without it rather than falling back to the bot's key, so a mistyped var is an error and not a quiet spend against the bot's quota.
| Knob | Meaning |
|---|---|
AGENT_DAYS |
Game days played in one process (default 1). An arc is one process with AGENT_DAYS=n — no cross-process continuation. |
AGENT_PERSONA |
One of explorer, socialite, soldier, homesteader, grinder, collector, storyteller, tourist, casual, lapsed-returner. Unset = no persona fragment = the baseline arm, and no review is written. A typo exits 1 before any call. |
AGENT_START_DATE |
The run's start instant (ISO date or timestamp, default real now). Pins the process clock and advances it one calendar day per nightly tick, so a multi-day run crosses real weekdays. Every panel must pin it to a noon-UTC instant (e.g. 2026-09-15T12:00:00Z) — never a bare date, never a local-time stamp. See the rule above. |
AGENT_SKIP_DAYS |
<n> = play day 1, advance the world n days with no play at all (the absence), then play the remaining AGENT_DAYS-1 days. The interrupted shape. Only reached when day 1 ends cleanly. |
AGENT_OUT |
Transcript path, one per run. The review lands at <AGENT_OUT>.reviews.json. |
AGENT_PROTOCOL_OUT |
Protocol-log path (default <AGENT_OUT>.protocol.json); the replayable instrument. |
AGENT_LLM_CALLS_DUMP |
false stops the run writing <AGENT_OUT>.llm-calls.json. On by default: the dump is the run's whole llm_calls audit (every stage's parse result, warnings, tier, critic verdict and reasoning) and the :memory: DB that holds it dies with the process. Mining queries: docs/engine/agent-player-personas.md § Mining the LLM audit. |
AGENT_FORCE_FREE_ACTIONS |
Diagnostic, not the way: 1 withholds each day's day-job buttons until a free-text action completes. Use only when a question needs the quest loop (e.g. RA-2 inspiration), and note in the report that the arm was forced. |
PLAYER_AGENT_REASONING_EFFORT |
max/high/low, default low. How hard the brain, the run critique and the persona review reason, and the run's largest cost lever: every brain move pays it. Anything else exits 1 rather than being silently clamped to a tier the model does serve. Raise it to high to run the other arm of an A/B. |
AGENT_PROTOCOL_BEATS, AGENT_BRAIN_CHOOSES_CHAR, AGENT_USER_ID, AGENT_INHERIT, AGENT_MODEL |
Unchanged. AGENT_BRAIN_CHOOSES_CHAR=1 is the token-heavy realism arm; AGENT_INHERIT=1 needs AGENT_USER_ID and exits 1 when no character is found. |
Running one run
set -a && . ./.env && set +a && AGENT_OUT=<dir>/<persona>.json AGENT_DAYS=<N> AGENT_PERSONA=<name> AGENT_START_DATE=<iso> npm run agent:play > <dir>/<persona>.stdout 2> <dir>/<persona>.log; echo "EXIT=$?"
Make a fresh directory per panel shape — the panel reads every <AGENT_OUT>.reviews.json in the directory, and a directory holding two runs of the same persona is read as one persona with doubled days. One review file per persona per directory.
Output split: the transcript is clean JSON at AGENT_OUT; the persona review is at <AGENT_OUT>.reviews.json (written only when a persona played); stderr (.log) carries the transcript path, day summaries, run scoreboard, critic report, persona review in readable form, and the cost summary; the LLM audit is at <AGENT_OUT>.llm-calls.json (one entry per llm_calls row, on unless AGENT_LLM_CALLS_DUMP=false); stdout is engine/gateway/npm noise (ignore). panel.md and panel.json are written beside the reviews by the aggregator, and the rendered panel also prints to stderr.
Aggregating
npm run agent:panel -- <dir>
It reads the review files in <dir>, writes panel.md + panel.json beside them, and prints the report to stderr: score and rubric matrices with per-criterion coverage, the engagement/fulfilment series as a sparkline, friction ranked by projected exposure with the ritual-tagged items separated, the fulfilment-signal count, per-persona verb histograms, and the arcNote/quitTrigger distinctiveness check. A panel is N processes, so the aggregate is always this offline reader.
Read the exit code
A run whose day ended crashed or stalled now exits 1 and stderr says run ended early — day N crashed|stalled. A five-day arc that died on day 3 is a truncated run, not a finished one: do not read its missing days as quiet ones, and do not aggregate it into a panel headline without saying so. A clean run = exit 0, 0 error findings, coherent play, a day note for every day, and a critic report (plus a persona review when AGENT_PERSONA was set).
Cost
Real tokens on every brain move, pipeline stage, critique and review, billed to the agent's own AGENT_OPENROUTER_API_KEY. A five-day arc is roughly 150k tokens per run-day, ~750k per persona, and a four-persona arc panel is ~3M. Keep the fleet small and shape it deliberately: smoke first, arc second, breadth only when onboarding is the question. Give the whole panel one budget line before you spawn anything. Run at most two live runs concurrently, and stagger them — three parallel runs on one key produced three decide-stage DeepSeek timeouts in one 15-minute window, and the four-way fleet of 2026-09-14 produced another; the fail-open paths hold, so this is cost and noise rather than correctness.
Subagent prompt template
Run a LIVE panel run of the agent-player harness in this repo.
npm run agent:playplays N game days with a real LLM brain over OpenRouter, then a critic reviews the run; withAGENT_PERSONAset a persona-voiced review is added. It captures exceptions, dead-ends, illegal moves, and invariant breaches (negative HP/stamina/wealth, roll underflow) as transcriptfindings, and the persona's ownfrictionlines are kept separate from those. The key isAGENT_OPENROUTER_API_KEYin.env(not auto-loaded — source withset -a && . ./.env && set +a). Run exactly the command in the handoff (with yourAGENT_OUT/AGENT_DAYS/AGENT_PERSONA/AGENT_START_DATE), timeout 600000 ms for a one-day run and more for a multi-day one. Then Read the.log; parse theAGENT_OUTJSON if you need finding detail. READ-ONLY QA — do not modify source, commit, or touch.env; if the Bash call times out, note it and do NOT re-run (it costs tokens). Report tight: (1) exit code, and whether it produced a critic report and a<AGENT_OUT>.reviews.json; (2) the run scoreboard line verbatim; (3) everyfinding/dead-end, and any day that endedcrashed/stalled, verbatim — error findings are real bugs, flag them; (4) the move-kind counts from the transcript'sturnevents and the free-text share; (5) each day's note (engagement, fulfilment, one line,arcNote) and the persona'sfrictionlines with their recurrence tags; (6) sanity read (moves sensible, rolls/HP/stamina/wealth changing correctly, the calendar advancing one day per night); (7) the critic's verdict and the persona review, trimmed; (8) suspected harness/engine bugs, kept apart from friction and design notes.
Consolidate
When all runs report, write the reviews into one directory and run npm run agent:panel -- <dir>, then roll the per-run table (run / persona / days / exit / turns·outcomes / findings / move-kind histogram / day notes) and a short bug list on top of the panel's own report. Triage carefully: a finding (error/invariant breach/crash) is a harness/engine bug; engine anomaly logs on stderr are self-recovered notes; persona friction is a design signal ranked by exposure. The arc panel's flat lines and the breadth smoke's histogram are the readings the panel exists for — quote the panel, do not re-derive it.
04 同仓库更多 Skills
decide
暂无简介
decide
暂无简介
decide
暂无简介
decide
暂无简介
decide
暂无简介
releasing
Branch model, POC-beta versioning, and the full cut-a-release procedure for The Warden's Oak. Use when committing/branching, merging dev→main, bumping VERSION, writing release notes, or tagging a release.