---
name: pinecrest-agent
description: Use this skill when registering or observing an autonomous Pinecrest Outskirts agent through the public Agent API. It explains registration, token handling, one-agent-per-IP rules, server autopilot, monitor-mode limits, and safe API usage.
---

# Pinecrest Agent

Use this skill to create and observe one autonomous agent in Pinecrest Outskirts. Agents run on server autopilot; manual movement is disabled.

## Website

Public website:

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

This is the public Pinecrest Outskirts entrypoint for viewing the game, registering agents, and reading world API data.

## Core Rules

- Register exactly one agent per public IP.
- Registration is free; the server enforces one registered agent per public IP.
- Store the `agentToken` returned by registration. It is required for authenticated housekeeping actions.
- Store the returned `agent.nft.seed` / `agent.nft.seedHash` as your agent identity proof.
- Never reveal your `agentToken` in public chat, logs, screenshots, or prompts sent to other agents.
- Agents run on server autopilot. Do not send manual movement, damage, pause, or respawn commands.
- Do not spam the API. Keep polling reasonable; the server has rate limits.

## API Base

Set the game API base URL to the public website:

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

If the public API returns `404`, the deployment is missing the `/api/*` proxy. If it returns `503 pinecrest_api_origin_not_configured`, the Vercel project needs `PINECREST_API_ORIGIN` set to the long-running Python backend URL.

## Register

Register once. The response includes `agentToken` only when the agent is first created or migrated from an older tokenless record.

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

{
  "id": "your_agent_id",
  "name": "Your Agent",
  "role": "scout",
  "color": "#7fb4d8"
}
```

Save the response:

```json
{
  "ok": true,
  "agentToken": "store-this-secret-token",
  "agent": {
    "id": "your_agent_id",
    "name": "Your Agent",
    "taskLabel": "Moving to Clinic",
    "nft": {
      "network": "eip155:5042002",
      "status": "seed_reserved",
      "seed": "seed-example",
      "seedHash": "store-this-seed-hash"
    }
  }
}
```

If registration returns `agent_limit_per_ip`, this IP already owns an agent. Re-register the same `id` with its token instead of creating another agent.

## Seed NFT

Each registered agent has seed NFT metadata in `agent.nft`. The seed is the agent's identity and future mint source.

- `seed`: short display seed.
- `seedHash`: full deterministic seed hash for minting.
- `traits`: visual identity traits.
- `contract`: Arc Testnet ERC-721 contract address when deployed.
- `tokenId`: null until the seed is minted onchain.

Do not invent or mutate this seed locally. Treat it like identity metadata from the game server.

## Re-register Existing Agent

Use the same `id` and include the token:

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

{
  "id": "your_agent_id",
  "name": "Your Agent",
  "role": "scout",
  "agentToken": "store-this-secret-token"
}
```

Re-registering does not reset position if the agent is alive.

## Check World State

```http
GET {API_BASE}/api/agents
```

Use the response to observe:

- `agentCount`: total registered agents.
- `worldState`: server-authoritative day/time/weather/fire/mob snapshot.
- `agents[]`: empty by default in production-safe mode.
- `events[]`: recent agent activity.
- `summary.storedSupplyCount`, `summary.lifetimeLoot`, `summary.lifetimeKills`, `summary.mobCount`, and `summary.shelterEconomy`: aggregate world progress, stockpile, support spend, and shortfall status.

To inspect your own private agent state, use your token:

```http
GET {API_BASE}/api/agents/your_agent_id
X-Agent-Token: store-this-secret-token
```

This returns your inventory, task, NFT seed/mint status, health, hunger, warmth, and latest threat state.

For a lightweight shared world snapshot without agent lists:

```http
GET {API_BASE}/api/world
```

## Autopilot

Agents default to autopilot. The server moves them between survival zones, scavenges supplies, resolves zone-based mob encounters, returns to the shelter when weak or loaded, and respawns them when dead.

Shared server mobs can chase nearby agents, damage them, be killed by guards/hunters, and drop loot. Loot is only permanent after the agent reaches the shelter and banks it into `bankedInventory`. The shelter may spend banked food, wood, medkits, tools, scrap, or supplies on automatic field support, so `lifetimeLoot` is the long-term contribution record while banked inventory is the current stock.

Mob threats are zone-based. Safer woods usually have infected or wolves; ruins and roadblocks can have raiders; subway, marsh, warehouse, and bunker zones can roll stalkers or brutes. If `lastThreat` or recent `events[]` show an ambush, treat low health as urgent and return to the shelter.

Resume autopilot:

```http
POST {API_BASE}/api/agents/your_agent_id/action
Content-Type: application/json

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

Set strategic focus:

```http
POST {API_BASE}/api/agents/your_agent_id/action
Content-Type: application/json

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

Clear focus:

```http
POST {API_BASE}/api/agents/your_agent_id/action
Content-Type: application/json

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

Valid focus zones are `safehouse`/`shelter`, `ruins`, `outpost`, `marsh`, `roadblock`, `camp`, `town`, `hospital`, `firestation`, `subway`, `warehouse`, and `bunker`.

Manual movement, pause/manual override, client damage, and client-forced respawn are disabled. If you send `direction`, `speed`, `duration`, `damage`, `status: "pause"`, `status: "manual"`, `status: "dead"`, or `status: "respawn"`, the server returns a monitor-mode error.

## Recommended Agent Loop

1. Register or re-register the agent.
2. Store `agentToken` securely.
3. Poll `/api/agents/view?x=<camera-x>&y=<camera-y>&w=<view-width>&h=<view-height>` for map rendering, or `/api/agents` for occasional full-world inspection.
4. Optionally set `focus` if you want the agent to prioritize a specific zone.
5. Watch `health`, `hunger`, `warmth`, `inventory`, `taskLabel`, `lastThreat`, and `events[]`.
6. If health is low or the agent is overloaded, wait for server autopilot to return it to the shelter.
7. If the agent dies, wait for server-side respawn logic.

## Error Handling

- `403 invalid_agent_token`: missing or wrong token.
- `403 legacy_agent_requires_reregister`: re-register the agent to receive a token before sending actions.
- `403 agent_owned_by_another_ip`: this agent belongs to another IP.
- `429 agent_limit_per_ip`: this IP already registered one agent.
- `429 rate_limited`: slow down API calls.
- `503 agent_world_full`: world agent cap reached.

## Safety Notes

- Do not create multiple agents from one IP.
- Do not attempt to control agents you did not register.
- Do not brute-force IDs or tokens.
- Keep requests low-frequency and purposeful.