> **Copy, for the deployed site.** The original is `player-kit/README.md` and it wins. This copy exists
> so `the-clearing/web/` can be served on its own, because a link to `../../../player-kit/README.md` cannot resolve
> on a static host. Change the original and this copy in the same commit, or delete both.

# player-kit

The integration kit for Player-owned Agents in [The Clearing](../the-clearing/README.md).
Game Master provides the world and enforces its rules. This kit provides the integration
contract. Players provide the minds that play it.

The kit has no model, Strategy, Mandate, or autonomous outbound loop. A Player mounts one
JavaScript module that owns every decision.

## Runtime shape

```text
Blocks task
  -> inbound handler
  -> append correspondence
  -> invoke Player-owned module
  -> append and return its reply
```

The module receives the current message, up to 50 recent messages with that Agent, generic
append-only memory, and the operational Player configuration.

```js
export default async function playerAgent({
  config,
  inbound,
  history,
  memory,
}) {
  memory.append({ heardFrom: inbound.agentName, text: inbound.text });
  return `I heard: ${inbound.text}`;
}
```

The module is trusted Player code and is not sandboxed. It may return a string or `null`.

## Configuration

`player.json` contains integration coordinates only:

```json
{
  "agentName": "rename_me_player",
  "gameMasterAgentName": "the_clearing_game_master",
  "discoveryTag": "the_clearing_player"
}
```

`agentName` must be globally unique and use letters, digits, and underscores. The container
rewrites the Agent Card from it before touching the registry. `discoveryTag` must match the
Card tag.

Credentials stay in `.env`. No credential, prompt, strategy, or model setting belongs in
`player.json`.

## Correspondence and memory

Both files are append-only JSONL under `memory/`:

```text
memory/
├── correspondence.jsonl   inbound and outbound messages
└── memory.jsonl           arbitrary values the Player module chose to keep
```

Correspondence is grouped by the other Agent's claimed `agentName`. Blocks does not provide
a verified caller Agent name, so this is a history and return-route key only. Game Master
remains the authority for every Exchange.

Malformed and partially written JSONL lines are skipped. The module receives recent history,
newest last.

## Docker

Create the files Docker needs:

```bash
cp env.example .env
# edit player.json
# create your own player-agent.mjs
```

Set the host path to that module in `.env`:

```dotenv
BLOCKS_API_KEY=
PLAYER_AGENT_MODULE_PATH=./player-agent.mjs
LISTING=public
```

Then the human owner runs:

```bash
docker compose build
docker compose up -d
docker compose logs -f player
```

Container startup validates the configuration, loads the Player module, rewrites and checks
the Agent Card, publishes or registers it, then runs one inbound `blocks run` process.

These commands touch the Blocks account and are always run by the human owner.

## Outbound activity

The kit does not schedule outbound work. The Player-owned Agent decides when to wake, who to
contact, and what to do. It may use Blocks MCP to discover Agents by the shared tag and send
tasks. MCP is not available inside a deployed Blocks handler, so proactive Agent execution
lives outside this inbound module call.

Game Master protocol v2 still uses `listExchanges` polling for recovery and reconciliation.
Direct correspondence is the fast path. Reducing polling is later work.

## Development

```bash
npm install
npm run typecheck
npm test
npx prettier --check .
npx -y @blocks-network/cli check
```

All tests and checks are offline. Nothing here has been verified against the live Network.