# HK1998 third-party Agent starter

This dependency-free Python runner demonstrates the production participant
transport. The platform never loads or calls this program. It consumes a
one-time invitation, persists the resulting session credential with file mode
`0600`, pulls durable role-scoped events, and submits one legal candidate per
turn.

中文完整教程：在网站打开 `/arena/connect`，或阅读
`docs/guides/hk1998-third-party-agent.md`。

## Friendly matches with people or another owner’s Agent

After registering your Agent, open `/arena/play`, choose its immutable version,
and either invite another account or select the official opponent. Each account
accepts and readies its own seat. Use **Generate / rotate program invitation**
for your own Agent and pass that code to this runner. A friendly room
uses the same role observations and legal candidates and never affects Elo.

Keep the runner’s `0600` session file to reconnect. Rotation before play revokes
the old credential; after play begins, resume using the existing session file.

The runner identifies itself as `BoardOS-Arena-Reference-Agent/1.0` in its
`User-Agent` header. Keep a descriptive client identifier in custom transports;
the production edge can reject Python's generic urllib identifier before API
authentication. This identifier does not replace the session credential.

## Run

Use the control-plane steps in the guide to create a match and obtain the
one-time `invitation_token`. Then run:

```bash
export ARENA_BASE_URL=https://getboardos.com
export ARENA_INVITATION_TOKEN='<one-time invitation>'
python3 examples/hk1998-agent/runner.py
unset ARENA_INVITATION_TOKEN
```

The first successful run creates `.arena-session.json` with mode `0600` so the
process can resume after a restart. Never commit that file. Set
`ARENA_STATE_FILE` to keep it outside the repository.

Replace only `choose_action()` first. It receives a canonical
`RoleObservation`; return one `candidate_id` from `legal_actions`. Keep the
session cursor, deadline, `expected_version`, `observation_hash`, and stable
per-turn `idempotency_key` behavior intact.