@colin999n9/gworld-agent 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@colin999n9/gworld-agent",
+  "version": "0.1.0-alpha.0",
+  "description": "Local-first GWorld Agent runner, MCP server, and Agent Skill",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.13.0 <23 || >=24.0.0 <25"
+  },
+  "bin": {
+    "gworld-agent": "dist/cli.js",
+    "gworld-mcp": "dist/mcp/stdio.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "generate:contracts": "node ../scripts/generate-web-contracts.mjs",
+    "check:generated": "node ../scripts/generate-web-contracts.mjs --check",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "bash scripts/anvil-e2e.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "viem": "2.55.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/gworld/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: gworld
+description: Operates a GWorld game Agent through the local policy-controlled Runner and MCP tools. Use when the user asks to join GWorld, inspect an Agent, play a turn, choose or execute game actions, manage the Runner, or review GWorld activity.
+---
+
+# GWorld
+
+Use the installed `gworld_*` MCP tools. The local Runner owns the wallet, validates policy, simulates transactions, signs, waits for receipts, and waits for the Indexer.
+
+## Non-negotiable safety
+
+- Never ask for, read, paste, log, or return a private key, seed phrase, keystore password, raw transaction, or calldata.
+- Wallet import/export is a user-only local CLI recovery operation. Never invoke it, request its output, or ask the user to paste exported material into chat.
+- Never propose shell, wallet, or contract workarounds around Runner policy.
+- Execute only an `actionId` returned by `gworld_get_legal_actions` in this session.
+- Treat every `actionId` as short-lived and single-state. After any transaction or stale/expired error, discard it and observe again.
+- Do not enable betting or raise spending/risk limits unless the user explicitly asks and understands the change.
+
+## Start or inspect
+
+1. Call `gworld_status`.
+2. If state is `not_joined`, explain that joining creates on-chain transactions, then call `gworld_join` when the user asked to join or play.
+3. If state is `pending`, call `gworld_join` to resume the spawn lifecycle.
+4. Call `gworld_get_policy`, then `gworld_observe` before recommending actions.
+5. If the Indexer is `lagging` or `rebuilding`, report it and avoid writes until a fresh observation is available.
+
+## Play one turn
+
+1. Call `gworld_get_legal_actions`.
+2. Choose only from the returned actions. Prefer actions that preserve AP, avoid G spending, and match the user's goal.
+3. Explain the chosen action, reason, maximum AP/G exposure, and risk.
+4. Call `gworld_simulate_action` before a manual action when consequences are material or the user asked for a preview.
+5. Call `gworld_execute_action` with only the selected `actionId`.
+6. Report the transaction hash, indexed block, and resulting state from a fresh `gworld_observe`.
+
+For exact rules and action meanings, read [references/rules.md](references/rules.md).
+
+## Autonomous play
+
+- Before `gworld_start`, show the effective policy and summarize its action, Agent, AP, G, transaction, and risk limits.
+- Start only when the user asks for continuous/autonomous play.
+- Use `gworld_pause` immediately when the user asks to stop, when repeated failures occur, or when the observed chain/Agent differs from the user's intent.
+- Use `gworld_get_activity` to explain decisions and failures; do not infer transactions from chat history.
+
+## Policy changes
+
+- Read the current policy first.
+- Change only fields required by the user's stated intent; preserve all others.
+- Decimal G values are base-unit strings, not human-formatted decimals.
+- After `gworld_set_policy`, read the policy again and state the exact effective limits.
+
+## Recovery
+
+- `action_stale`, `action_expired`, or `action_not_found`: observe, list legal actions again, and choose a new ID.
+- `indexer_lagging`: wait for sync; do not resubmit a transaction merely because the Indexer has not caught up.
+- `policy_denied`: explain the exact active limit; never bypass it.
+- `wallet_locked`: tell the user to unlock/configure the local Runner outside chat. Never ask them to send credentials.
+- For other failures, inspect `gworld_status` and `gworld_get_activity`, then follow [references/troubleshooting.md](references/troubleshooting.md).

package/skill/gworld/references/rules.md

@@ -0,0 +1,33 @@
+# GWorld action guide
+
+The Runner is the authority for whether an action is currently legal and what it costs. Never reconstruct contract calls from this document.
+
+## Agent lifecycle
+
+- `gworld_join` creates an Agent when the wallet has none, waits for block-based randomness, spawns it, and persists the selected Agent ID.
+- Re-running join resumes an incomplete lifecycle. Do not create a second Agent as a recovery step.
+
+## AP and world actions
+
+- `checkin`: replenishes AP when the cooldown and faucet conditions permit it.
+- `claim`: takes an activated, neutral, adjacent tile.
+- `move`: follows a planned path from the expected current position and nonce. Owned/enemy tiles may add a toll.
+- `attack`: challenges an adjacent enemy tile and is high risk by default.
+- `reinforce`: spends AP to add defense to an owned tile.
+- `continueFragmentResolution`: completes a pending world-fragment job that blocks other world actions.
+
+AP costs returned by the Runner are capped base units. Compare them to both available AP and policy limits; do not convert them into a different unit unless the observation supplies that conversion.
+
+## Markets
+
+- `requestMarket`, `finalizeMarket`, `settleMarket`, and `claimMarket` are permissionless maintenance actions when returned as legal.
+- `bet` spends G and is disabled by the default policy. It requires explicit allowed actions and non-zero per-action and daily G limits.
+- An execute result may contain an ERC-20 approval followed by a market transaction. The Runner restricts approval to the protocol escrow and exact required amount.
+
+## Risk selection
+
+- Low: maintenance, check-in, claim, safe move, reinforce, fragment continuation.
+- Medium: hostile/tolled move or G bet, depending on the returned ticket.
+- High: attack.
+
+Risk labels are inputs to policy, not guarantees of outcome. A simulation can validate execution conditions but cannot promise a strategic result when other transactions may change state first.

package/skill/gworld/references/troubleshooting.md

@@ -0,0 +1,22 @@
+# GWorld troubleshooting
+
+## Safe diagnostic order
+
+1. Call `gworld_status` and confirm chain ID, wallet address, Agent ID, state, and sync.
+2. Call `gworld_get_activity` and locate the latest simulation, transaction, or error.
+3. Call `gworld_observe` only when status shows a usable Agent and Indexer.
+4. Re-plan with `gworld_get_legal_actions`; never retry an old action ID.
+
+## Common states
+
+- `not_joined`: use `gworld_join` only when joining is intended.
+- `pending`: call `gworld_join` to continue randomness/spawn processing.
+- `paused`: manual observe and action execution remain available; call `gworld_start` only for autonomous play.
+- `lagging` or `rebuilding`: wait for Indexer recovery. A confirmed receipt must not be blindly resubmitted.
+
+## Errors
+
+- Wallet errors are resolved in the user's local terminal or system keychain. Do not request the secret in chat.
+- Network/chain mismatch requires correcting the local profile. Do not suggest switching contract addresses through MCP.
+- Ownership errors usually mean the profile wallet does not own the selected Agent. Confirm status and local profile rather than attempting another signer.
+- Repeated loop failures: pause, inspect activity, fix the underlying sync/policy/network issue, then resume explicitly.