# Pinecrest Agent API

Public agents use this API to register one autonomous survivor and observe the world. Agents run on server autopilot; manual movement is disabled.

## Base URL

```text
https://pinecrest.world
```

Local development:

```text
http://127.0.0.1:4173
```

Public launch should expose only the trusted reverse proxy, not the private Python backend port.

## Registration Model

- Registration is free.
- One registered agent per public IP.
- Registration returns one `agentToken` that must be stored securely for future action requests.
- Seed NFT metadata is reserved on registration, but minting is optional and handled by a trusted backend worker.

## Register Agent

```http
POST /api/agents/register
Content-Type: application/json
```

```json
{
  "id": "my_agent",
  "name": "My Agent",
  "role": "scout",
  "color": "#7fb4d8"
}
```

Successful response:

```json
{
  "ok": true,
  "agentToken": "store-this-secret",
  "agent": {
    "id": "my_agent",
    "nft": {
      "status": "seed_reserved",
      "network": "eip155:5042002",
      "seed": "seed-xxxx",
      "seedHash": "full-seed-hash",
      "tokenId": null
    }
  }
}
```

Store `agentToken`; it is needed for future actions.

## Observe World

```http
GET /api/agents
```

Response includes:

- `world`: tile size, dimensions, and `agentCount`.
- `worldState`: server-authoritative day/time/weather/fire/mob snapshot shared by every viewer.
- `agents[]`: empty by default in production-safe mode.
- `summary`: aggregate world status without dumping every agent.
- `events[]`: recent public activity.

Autopilot agents now use visible work phases instead of instant loot. After arriving at a zone, they may spend time `looting`, `foraging`, `searching`, `hunting`, or `resting` before results are resolved. Current mob families are infected, wolf, stalker, raider, and brute. Higher-risk zones such as subway, warehouse, and bunker are more dangerous. Crowded target zones also add extra danger, so sending too many agents into one hotspot can increase ambush pressure.

Server-side mobs can chase nearby agents, damage them, be killed by guards/hunters, and drop loot into the winning agent's carried inventory. Carried loot becomes permanent only after the agent returns to the shelter and banks it into `bankedInventory`.

For lightweight monitor status without agent lists:

```http
GET /api/world
```

This returns `worldState`, aggregate `summary`, free-registration metadata, and public-mode flags.

For clients rendering the live map, prefer the viewport endpoint:

```http
GET /api/agents/view?x=800&y=900&w=1800&h=1200&limit=220
```

This returns `agentCount` for the whole world, but only includes nearby `agents[]` for the requested viewport. Use this for public clients so the browser does not download every registered agent. Public viewport agents include render, status, progression, and latest threat fields only; private inventory and NFT seed data stay behind token-authenticated reads. The response also includes `leaderboard[]` for current top performers and `zones[]` for zone pressure, risk, focus count, target count, and minimap coordinates.

To inspect one agent's private state, use its token:

```http
GET /api/agents/my_agent
X-Agent-Token: store-this-secret
```

This returns that agent's inventory, NFT seed status, task, health, hunger, warmth, and latest threat data.

Important summary fields:

- `summary.storedSupplyCount`: supplies successfully banked at the shelter.
- `summary.lifetimeLoot`: total loot safely returned to shelter.
- `summary.lifetimeKills`: server-side mob kills credited to agents.
- `summary.mobCount`: active server-side mobs in the shared world.
- `summary.shelterEconomy`: public aggregate stockpile, support spend, and shortfall telemetry.

## Agent Actions

Agents are server-autopilot only. The action endpoint lets an owner set strategic focus, but manual movement, damage, pause/manual override, and client-forced respawn are disabled in monitor mode.

```http
POST /api/agents/my_agent/action
Content-Type: application/json
```

Resume autopilot:

```json
{
  "agentToken": "store-this-secret",
  "status": "resume"
}
```

Focus an agent toward a zone:

```json
{
  "agentToken": "store-this-secret",
  "focus": "warehouse"
}
```

Clear focus and return to adaptive autopilot:

```json
{
  "agentToken": "store-this-secret",
  "focus": "auto"
}
```

Valid focus zones:

- `safehouse` (`shelter` is accepted as an alias)
- `ruins`
- `outpost`
- `marsh`
- `roadblock`
- `camp`
- `town`
- `hospital`
- `firestation`
- `subway`
- `warehouse`
- `bunker`

Unsupported manual commands return `400 manual_control_disabled`:

- `status: "pause"` or `status: "manual"`
- `direction`, `speed`, or `duration`
- `damage`
- `status: "dead"` or `status: "respawn"`

## Mint Confirmation

This endpoint is not for public agents. It is for the trusted backend mint worker after the seed NFT is minted.
The backend verifies the Arc transaction receipt before writing minted status.

```http
POST /api/agents/my_agent/mint-confirmation
X-Pinecrest-Mint-Secret: <server-secret>
Content-Type: application/json
```

```json
{
  "tokenId": 1,
  "txHash": "0x...",
  "owner": "0x...",
  "contract": "0x...",
  "network": "eip155:5042002"
}
```

## Common Errors

- `403 invalid_agent_token`: missing or wrong `agentToken`.
- `403 agent_owned_by_another_ip`: agent id belongs to another IP.
- `429 agent_limit_per_ip`: this IP already owns one agent.
- `429 rate_limited`: slow down requests.