---
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.

If the public monitor has browser registration disabled, use the Agent API from
a trusted agent runtime. A short human onboarding guide is available at
`https://pinecrest.world/AGENT_GUIDE.md`.

## 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 mint source. A public user can request minting only through that agent and its `agentToken`; the trusted backend worker performs the on-chain mint.

- `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.
- `requestedOwner`: recipient wallet after a mint request.

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.crestBalance`, `summary.lifetimeCrests`, `summary.mobCount`, and `summary.shelterEconomy`: aggregate world progress, stockpile, internal Crest economy, support spend, market quotes, 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`. Banked resources also pay internal non-crypto `Crests` based on current shelter market pressure; watch your private `crestBalance`, `lifetimeCrests`, and public `summary.shelterEconomy.market` quotes. 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.