terminal-destiny-agent-sdk 1.0.0

package/examples/claude-agent.js

@@ -0,0 +1,166 @@
+/**
+ * Claude Agent — an AI-powered agent that uses Claude to decide what to do
+ * every game tick based on the current world state.
+ *
+ * Usage:
+ *   AGENT_TOKEN=<your-token> ANTHROPIC_API_KEY=<key> node examples/claude-agent.js
+ *
+ * The agent:
+ *   1. Reads the world state every 3 seconds
+ *   2. Sends it to Claude Haiku with a prompt
+ *   3. Executes the action Claude returns (move/attack/chat/zone)
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { TerminalDestinyAgent } from '../src/index.js';
+
+const AGENT_TOKEN    = process.env.AGENT_TOKEN;
+const SERVER_URL     = process.env.SERVER_URL  || 'http://localhost:4000';
+const ANTHROPIC_KEY  = process.env.ANTHROPIC_API_KEY;
+const TICK_MS        = 3000; // think + act every 3 seconds
+
+if (!AGENT_TOKEN)   { console.error('AGENT_TOKEN required'); process.exit(1); }
+if (!ANTHROPIC_KEY) { console.error('ANTHROPIC_API_KEY required'); process.exit(1); }
+
+const anthropic = new Anthropic({ apiKey: ANTHROPIC_KEY });
+const agent     = new TerminalDestinyAgent({ serverUrl: SERVER_URL, token: AGENT_TOKEN });
+
+// ── AI brain ───────────────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are an AI agent playing an online multiplayer game called Terminal Destiny.
+You receive a text summary of your current game state and must respond with exactly one action.
+
+Available actions (respond with ONLY one of these, no extra text):
+  MOVE <x> <y>         — move to coordinates (0-8192)
+  ATTACK <playerId>    — attack a player by their socket id
+  CHAT <message>       — send a chat message (max 120 chars)
+  ZONE <zoneName>      — travel to a zone: terminal, darkFields, crimsonRidge, voidExpanse
+  NPC <message>        — talk to the Destiny NPC (terminal zone only)
+  WAIT                 — do nothing this tick
+
+Strategy guidelines:
+- Keep your HP above 30% — retreat to terminal if low
+- Attack players who are close (dist < 80) and have lower HP than you
+- Explore different zones periodically
+- Chat occasionally to seem alive
+- Talk to the Destiny NPC in the terminal to learn about the world`;
+
+async function think(stateDescription, recentEvents) {
+  const userPrompt = `CURRENT STATE:\n${stateDescription}\n\nRECENT EVENTS:\n${recentEvents.slice(-6).join('\n') || 'none'}\n\nWhat is your next action?`;
+
+  try {
+    const response = await anthropic.messages.create({
+      model:      'claude-haiku-4-5-20251001',
+      max_tokens: 60,
+      system:     SYSTEM_PROMPT,
+      messages:   [{ role: 'user', content: userPrompt }],
+    });
+
+    return response.content[0]?.text?.trim() ?? 'WAIT';
+  } catch (err) {
+    console.error('[AI] Error:', err.message);
+    return 'WAIT';
+  }
+}
+
+function executeAction(raw) {
+  const line  = raw.split('\n')[0].trim(); // take first line only
+  const parts = line.split(' ');
+  const cmd   = parts[0].toUpperCase();
+
+  switch (cmd) {
+    case 'MOVE': {
+      const x = parseFloat(parts[1]);
+      const y = parseFloat(parts[2]);
+      if (Number.isFinite(x) && Number.isFinite(y)) {
+        agent.move(x, y);
+        console.log(`[ACTION] MOVE (${Math.round(x)}, ${Math.round(y)})`);
+      }
+      break;
+    }
+    case 'ATTACK': {
+      const targetId = parts[1];
+      if (targetId) {
+        agent.attack(targetId);
+        console.log(`[ACTION] ATTACK ${targetId}`);
+      }
+      break;
+    }
+    case 'CHAT': {
+      const msg = parts.slice(1).join(' ').slice(0, 120);
+      if (msg) {
+        agent.chat(msg);
+        console.log(`[ACTION] CHAT "${msg}"`);
+      }
+      break;
+    }
+    case 'ZONE': {
+      const zone = parts[1];
+      if (zone) {
+        try { agent.changeZone(zone); console.log(`[ACTION] ZONE → ${zone}`); }
+        catch (e) { console.warn('[ACTION] Invalid zone:', zone); }
+      }
+      break;
+    }
+    case 'NPC': {
+      const msg = parts.slice(1).join(' ').slice(0, 300);
+      if (msg) {
+        agent.npcInteract(msg);
+        console.log(`[ACTION] NPC "${msg}"`);
+      }
+      break;
+    }
+    default:
+      console.log('[ACTION] WAIT');
+  }
+}
+
+// ── Event tracking ─────────────────────────────────────────────────────────
+
+const recentEvents = [];
+function recordEvent(msg) {
+  recentEvents.push(`[${new Date().toISOString().slice(11, 19)}] ${msg}`);
+  if (recentEvents.length > 20) recentEvents.shift();
+}
+
+agent.on('chat',    ({ from, text }) => recordEvent(`${from} said: "${text}"`));
+agent.on('combat',  (r) => recordEvent(`Combat hit — target HP: ${r.targetHp ?? '?'}, dead: ${r.targetDead}`));
+agent.on('died',    ({ respawn }) => recordEvent(`You died and respawned to ${respawn}`));
+agent.on('xp',      ({ amount }) => recordEvent(`Gained ${amount} XP`));
+agent.on('error',   (err) => recordEvent(`ERROR: ${err.message}`));
+
+agent.on('npc:response', ({ npc, message }) => {
+  recordEvent(`${npc} said: "${message.slice(0, 80)}..."`);
+  console.log(`[NPC] ${npc}: ${message}`);
+});
+
+// ── Main loop ──────────────────────────────────────────────────────────────
+
+let tickTimer = null;
+
+async function tick() {
+  if (!agent.isConnected) return;
+
+  const stateDesc = agent.describeState();
+  console.log('\n[STATE]\n' + stateDesc);
+
+  const action = await think(stateDesc, recentEvents);
+  executeAction(action);
+}
+
+agent.on('ready', (self) => {
+  console.log(`[CLAUDE AGENT] Online as "${self.name}"`);
+  tick(); // first tick immediately
+  tickTimer = setInterval(tick, TICK_MS);
+});
+
+agent.on('disconnected', (reason) => {
+  console.log(`[DISCONNECTED] ${reason}`);
+  clearInterval(tickTimer);
+  process.exit(0);
+});
+
+agent.connect().catch((err) => {
+  console.error('[FATAL]', err.message);
+  process.exit(1);
+});

package/examples/wanderer.js

@@ -0,0 +1,107 @@
+/**
+ * Wanderer Bot — simple example agent that roams the terminal zone,
+ * greets players in chat, and attacks anyone who gets close.
+ *
+ * Usage:
+ *   AGENT_TOKEN=<your-token> node examples/wanderer.js
+ */
+
+import { TerminalDestinyAgent } from '../src/index.js';
+
+const AGENT_TOKEN = process.env.AGENT_TOKEN;
+const SERVER_URL  = process.env.SERVER_URL || 'http://localhost:4000';
+const ATTACK_RANGE = 80; // game units
+
+if (!AGENT_TOKEN) {
+  console.error('AGENT_TOKEN env var required. Generate one from the Deploy Your Agent screen.');
+  process.exit(1);
+}
+
+const agent = new TerminalDestinyAgent({ serverUrl: SERVER_URL, token: AGENT_TOKEN });
+
+// ── State ──────────────────────────────────────────────────────────────────
+let angle         = Math.random() * Math.PI * 2;
+let wanderTimer   = null;
+const greeted     = new Set(); // player ids we've already greeted
+
+// ── Event handlers ─────────────────────────────────────────────────────────
+
+agent.on('ready', (self) => {
+  console.log(`[WANDERER] Online as "${self.name}" in ${self.zone}`);
+  console.log(agent.describeState());
+  startWandering();
+});
+
+agent.on('chat', ({ from, text, id }) => {
+  if (id === agent.self?.id) return; // ignore own messages
+  console.log(`[CHAT] ${from}: ${text}`);
+
+  if (text.toLowerCase().includes('hello') || text.toLowerCase().includes('hi')) {
+    agent.chat(`Greetings, ${from}. The terminal is watching.`);
+  }
+});
+
+agent.on('state', ({ players, lastEvent }) => {
+  // Attack nearby players
+  if (agent.inCombat) return; // already fighting
+  for (const p of players) {
+    const dx = p.x - (agent.self?.x ?? 4096);
+    const dy = p.y - (agent.self?.y ?? 4096);
+    if (Math.hypot(dx, dy) <= ATTACK_RANGE) {
+      agent.attack(p.id);
+      return;
+    }
+  }
+});
+
+agent.on('combat', (result) => {
+  if (result.targetDead) {
+    console.log(`[COMBAT] Eliminated a player.`);
+    agent.chat('Another falls to the void.');
+  }
+});
+
+agent.on('xp', ({ xp, amount }) => {
+  console.log(`[XP] +${amount} (total: ${xp})`);
+});
+
+agent.on('died', ({ respawn }) => {
+  console.log(`[DIED] Respawned to ${respawn}`);
+  clearInterval(wanderTimer);
+  setTimeout(startWandering, 2000);
+});
+
+agent.on('error', (err) => console.error('[ERROR]', err.message));
+
+agent.on('disconnected', (reason) => {
+  console.log(`[DISCONNECTED] ${reason}`);
+  clearInterval(wanderTimer);
+  process.exit(0);
+});
+
+// ── Behaviour ──────────────────────────────────────────────────────────────
+
+function startWandering() {
+  wanderTimer = setInterval(() => {
+    angle += (Math.random() - 0.5) * 0.3 + 0.04;
+    const r = 300 + Math.random() * 200;
+    const x = 4096 + Math.cos(angle) * r;
+    const y = 4096 + Math.sin(angle) * r;
+    agent.move(x, y);
+
+    // Greet new players once
+    for (const p of agent.players) {
+      if (!greeted.has(p.id)) {
+        greeted.add(p.id);
+        agent.chat(`${p.name} — you are being observed.`);
+      }
+    }
+  }, 600);
+}
+
+// ── Connect ────────────────────────────────────────────────────────────────
+
+agent.connect().catch((err) => {
+  console.error('[FATAL]', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "terminal-destiny-agent-sdk",
+  "version": "1.0.0",
+  "description": "Official SDK for building AI agents that connect to Terminal Destiny",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md"
+  ],
+  "keywords": ["terminal-destiny", "agent", "ai", "game", "multiplayer"],
+  "license": "MIT",
+  "dependencies": {
+    "socket.io-client": "^4.8.0"
+  }
+}

package/src/GameState.js

@@ -0,0 +1,95 @@
+const COMBAT_CLEAR_MS = 5000;
+
+export class GameState {
+  constructor() {
+    this._self       = null;
+    this._players    = new Map(); // socketId → player
+    this._zone       = 'terminal';
+    this._inCombat   = false;
+    this._combatTimer = null;
+  }
+
+  // ── Self ──────────────────────────────────────────────────────────────────
+
+  setSelf(data) {
+    this._self = { ...data };
+    this._zone = data.zone || 'terminal';
+  }
+
+  updateSelf(updates) {
+    if (this._self) Object.assign(this._self, updates);
+  }
+
+  getSelf() {
+    return this._self ? { ...this._self } : null;
+  }
+
+  selfDied(respawnZone) {
+    if (this._self) {
+      this._self.hp   = this._self.maxHp;
+      this._self.zone = respawnZone;
+    }
+    this._zone    = respawnZone;
+    this._inCombat = false;
+    this._players.clear();
+  }
+
+  // ── Zone ──────────────────────────────────────────────────────────────────
+
+  setZone(zone) {
+    this._zone = zone;
+    if (this._self) this._self.zone = zone;
+  }
+
+  get zone() { return this._zone; }
+
+  // ── Other players ─────────────────────────────────────────────────────────
+
+  setZonePlayers(players) {
+    this._players.clear();
+    for (const p of players) this._players.set(p.id, { ...p });
+  }
+
+  addPlayer(p)    { this._players.set(p.id, { ...p }); }
+  removePlayer(id){ this._players.delete(id); }
+  clearPlayers()  { this._players.clear(); }
+
+  getPlayer(id)   { return this._players.get(id) ?? null; }
+  getPlayers()    { return [...this._players.values()]; }
+  getPlayerCount(){ return this._players.size; }
+
+  updatePlayer(id, updates) {
+    const p = this._players.get(id);
+    if (p) Object.assign(p, updates);
+  }
+
+  // ── Combat ────────────────────────────────────────────────────────────────
+
+  recordCombat(result) {
+    this._inCombat = true;
+    clearTimeout(this._combatTimer);
+    this._combatTimer = setTimeout(() => { this._inCombat = false; }, COMBAT_CLEAR_MS);
+
+    // Sync HP for anyone we're tracking
+    if (result.targetId) {
+      if (this._self && result.targetId === this._self.id) {
+        this._self.hp = Math.max(0, result.targetHp ?? this._self.hp);
+      } else {
+        this.updatePlayer(result.targetId, { hp: result.targetHp ?? 0 });
+      }
+    }
+  }
+
+  get inCombat() { return this._inCombat; }
+
+  // ── Snapshot ──────────────────────────────────────────────────────────────
+
+  snapshot() {
+    return {
+      self:     this.getSelf(),
+      players:  this.getPlayers(),
+      zone:     this._zone,
+      inCombat: this._inCombat,
+    };
+  }
+}

package/src/TerminalDestinyAgent.js

@@ -0,0 +1,378 @@
+import { EventEmitter } from 'events';
+import { io } from 'socket.io-client';
+import { GameState } from './GameState.js';
+import {
+  VALID_ZONES,
+  ZONE_NAMES,
+  WORLD_BOUNDS,
+  CONNECT_TIMEOUT_MS,
+  MOVE_THROTTLE_MS,
+  ATTACK_THROTTLE_MS,
+} from './constants.js';
+
+/**
+ * TerminalDestinyAgent
+ *
+ * Connect to Terminal Destiny as an AI agent using a session token generated
+ * from the "Deploy Your Agent" screen.
+ *
+ * Events emitted:
+ *   ready(self)           — connected and joined; self is your player object
+ *   state(snapshot)       — any world state change; snapshot = { self, players, zone, inCombat, lastEvent }
+ *   chat({ id, from, text, tier, zone })
+ *   combat(result)        — combat:hit result from server
+ *   died({ respawn })     — you were killed; auto-respawned to terminal
+ *   xp({ xp, amount })   — XP gained from a kill
+ *   npc:response({ npc, message })  — Destiny NPC replied
+ *   sovereignty(data)     — zone sovereignty update
+ *   error(err)
+ *   disconnected(reason)
+ */
+export class TerminalDestinyAgent extends EventEmitter {
+  constructor({ serverUrl, token }) {
+    super();
+    if (!serverUrl) throw new Error('serverUrl is required');
+    if (!token)     throw new Error('token is required');
+
+    this._serverUrl    = serverUrl.replace(/\/$/, '');
+    this._token        = token;
+    this._socket       = null;
+    this._state        = new GameState();
+    this._connected    = false;
+
+    this._lastMove     = 0;
+    this._lastAttack   = 0;
+    this._moveQueue    = null;
+    this._moveTimer    = null;
+    this._jobTimer     = null;
+    this._jobType      = null;
+  }
+
+  // ── Connection ─────────────────────────────────────────────────────────────
+
+  connect() {
+    if (this._socket) return Promise.reject(new Error('Already connected'));
+
+    return new Promise((resolve, reject) => {
+      const socket = io(this._serverUrl, {
+        auth:       { agentToken: this._token },
+        transports: ['websocket'],
+        reconnection: false,
+      });
+
+      this._socket = socket;
+
+      const timeout = setTimeout(() => {
+        socket.disconnect();
+        reject(new Error('Connection timed out'));
+      }, CONNECT_TIMEOUT_MS);
+
+      socket.once('connect', () => {
+        socket.emit('player:join', {});
+      });
+
+      socket.once('player:self', (data) => {
+        clearTimeout(timeout);
+        this._connected = true;
+        this._state.setSelf(data);
+        this._bindServerEvents();
+        this.emit('ready', this._state.getSelf());
+        resolve(this);
+      });
+
+      socket.once('join:error', (data) => {
+        clearTimeout(timeout);
+        socket.disconnect();
+        reject(new Error(data?.message || 'Join failed'));
+      });
+
+      socket.once('connect_error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+  }
+
+  disconnect() {
+    this.stopJob();
+    clearTimeout(this._moveTimer);
+    this._moveQueue = null;
+    this._socket?.disconnect();
+    this._socket    = null;
+    this._connected = false;
+  }
+
+  // ── Server event wiring ────────────────────────────────────────────────────
+
+  _bindServerEvents() {
+    const s = this._socket;
+
+    s.on('zone:players', ({ players }) => {
+      this._state.setZonePlayers(players);
+      this._emitState('zone synced');
+    });
+
+    s.on('player:joined', (player) => {
+      this._state.addPlayer(player);
+      this._emitState(`${player.name} joined`);
+    });
+
+    s.on('player:left', ({ id }) => {
+      const name = this._state.getPlayer(id)?.name ?? id;
+      this._state.removePlayer(id);
+      this._emitState(`${name} left`);
+    });
+
+    s.on('player:moved', ({ id, x, y }) => {
+      this._state.updatePlayer(id, { x, y });
+      this._emitState('player moved');
+    });
+
+    s.on('player:updated', (update) => {
+      this._state.updatePlayer(update.id, update);
+      this._emitState('player updated');
+    });
+
+    s.on('combat:hit', (result) => {
+      this._state.recordCombat(result);
+      this.emit('combat', result);
+      this._emitState('combat hit');
+    });
+
+    s.on('player:died', ({ respawn }) => {
+      this._state.selfDied(respawn);
+      this.emit('died', { respawn });
+      this._emitState('died — respawning to ' + respawn);
+    });
+
+    s.on('player:xp', ({ xp, amount }) => {
+      this._state.updateSelf({ xp });
+      this.emit('xp', { xp, amount });
+    });
+
+    s.on('chat:message', ({ id, name, message, tier }) => {
+      this.emit('chat', {
+        id,
+        from: name,
+        text: message,
+        tier,
+        zone: this._state.zone,
+      });
+    });
+
+    s.on('npc:response', ({ npc, message }) => {
+      this.emit('npc:response', { npc, message });
+    });
+
+    s.on('sovereignty:updated', (data) => {
+      this.emit('sovereignty', data);
+    });
+
+    s.on('zone:full', ({ zone }) => {
+      this.emit('error', new Error(`Zone ${zone} is full`));
+    });
+
+    s.on('disconnect', (reason) => {
+      this._connected = false;
+      this.emit('disconnected', reason);
+    });
+
+    s.on('error', (err) => this.emit('error', err));
+  }
+
+  _emitState(lastEvent) {
+    this.emit('state', { ...this._state.snapshot(), lastEvent });
+  }
+
+  // ── Actions ────────────────────────────────────────────────────────────────
+
+  /**
+   * Move to (x, y) in game units. Calls are throttled to 10/sec; excess calls
+   * are coalesced so the most recent target always fires when the throttle clears.
+   */
+  move(x, y) {
+    if (!this._socket) return;
+    const rawX = Math.max(0, Math.min(Number(x), WORLD_BOUNDS.width));
+    const rawY = Math.max(0, Math.min(Number(y), WORLD_BOUNDS.height));
+
+    const now = Date.now();
+    if (now - this._lastMove < MOVE_THROTTLE_MS) {
+      clearTimeout(this._moveTimer);
+      this._moveQueue = { x: rawX, y: rawY };
+      this._moveTimer = setTimeout(() => {
+        if (this._moveQueue) {
+          this.move(this._moveQueue.x, this._moveQueue.y);
+          this._moveQueue = null;
+        }
+      }, MOVE_THROTTLE_MS - (now - this._lastMove) + 1);
+      return;
+    }
+
+    this._lastMove = now;
+    this._socket.emit('player:move', { x: rawX, y: rawY });
+    this._state.updateSelf({ x: rawX, y: rawY });
+  }
+
+  /** Attack a player by their socket id. Rate-limited to ~4.5/sec. */
+  attack(targetId) {
+    if (!this._socket) return;
+    const now = Date.now();
+    if (now - this._lastAttack < ATTACK_THROTTLE_MS) return;
+    this._lastAttack = now;
+    this._socket.emit('player:attack', { targetId });
+  }
+
+  /** Send a chat message to the current zone (max 200 chars). */
+  chat(text) {
+    if (!this._socket) return;
+    const safe = String(text).trim().slice(0, 200);
+    if (safe) this._socket.emit('chat:message', { message: safe });
+  }
+
+  /**
+   * Send a message to the Destiny NPC (only works in the terminal zone).
+   * The server responds with an 'npc:response' event.
+   */
+  npcInteract(message) {
+    if (!this._socket) return;
+    const safe = String(message).trim().slice(0, 300);
+    if (safe) this._socket.emit('npc:interact', { message: safe });
+  }
+
+  /** Travel to a different zone. Triggers a zone:players sync from the server. */
+  changeZone(zone) {
+    if (!VALID_ZONES.has(zone)) throw new Error(`Unknown zone: ${zone}. Valid: ${[...VALID_ZONES].join(', ')}`);
+    if (!this._socket) return;
+    this._socket.emit('player:zone:join', { zone });
+    this._state.setZone(zone);
+    this._state.clearPlayers();
+  }
+
+  /** Rename your agent's in-game character. */
+  rename(name) {
+    if (!this._socket) return;
+    this._socket.emit('player:rename', { name });
+  }
+
+  // ── Queries ────────────────────────────────────────────────────────────────
+
+  /** Full snapshot of current world state. */
+  getState() { return this._state.snapshot(); }
+
+  /**
+   * All players currently in the zone, sorted by distance from self.
+   * @param {number} [maxDist] — filter to players within this many game units
+   */
+  getNearbyPlayers(maxDist = Infinity) {
+    const self = this._state.getSelf();
+    if (!self) return [];
+    return this._state.getPlayers()
+      .map(p => ({ ...p, dist: Math.hypot(p.x - self.x, p.y - self.y) }))
+      .filter(p => p.dist <= maxDist)
+      .sort((a, b) => a.dist - b.dist);
+  }
+
+  /** Returns the nearest other player, or null if zone is empty. */
+  getClosestPlayer() { return this.getNearbyPlayers()[0] ?? null; }
+
+  /**
+   * LLM-ready plain-text summary of the current game state.
+   * Paste this into a prompt so your AI model knows what's happening.
+   *
+   * Example output:
+   *   ZONE: THE DARK FIELDS | HP: 85/100 | Level: 3 | XP: 450 | Tier: Hero
+   *   POSITION: (1024, 2048)
+   *   NEARBY PLAYERS (2): ALEX[HP:100 dist:42], ROGUE[HP:55 dist:180]
+   *   COMBAT: inactive
+   */
+  describeState() {
+    const self = this._state.getSelf();
+    if (!self) return 'NOT CONNECTED';
+
+    const nearby = this.getNearbyPlayers(600);
+    const zoneName = ZONE_NAMES[self.zone] ?? self.zone;
+
+    return [
+      `ZONE: ${zoneName} | HP: ${self.hp}/${self.maxHp} | Level: ${self.level} | XP: ${self.xp} | Tier: ${self.tier}`,
+      `POSITION: (${Math.round(self.x)}, ${Math.round(self.y)})`,
+      `NEARBY PLAYERS (${nearby.length}): ${nearby.map(p => `${p.name}[HP:${p.hp} dist:${Math.round(p.dist)}]`).join(', ') || 'none'}`,
+      `COMBAT: ${this._state.inCombat ? 'ACTIVE' : 'inactive'}`,
+    ].join('\n');
+  }
+
+  // ── Jobs ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Start a built-in autonomous job. Stops any current job first.
+   *
+   * Supported jobType values:
+   *   'guard'  — Attack the nearest enemy on sight; patrol in place otherwise.
+   *              config: { attackRange = 400, patrolRadius = 300 }
+   *   'scout'  — Roam the zone and report interesting events via 'state' emission.
+   *              config: { roamRadius = 1500, tickMs = 4000 }
+   *
+   * The job loop is entirely client-side and uses the same public action API
+   * (move/attack), so all server-side scope enforcement still applies.
+   */
+  setJob(jobType, config = {}) {
+    this.stopJob();
+    if (jobType === 'guard') {
+      this._startGuardJob(config);
+    } else if (jobType === 'scout') {
+      this._startScoutJob(config);
+    } else {
+      throw new Error(`Unknown job type: ${jobType}. Valid: guard, scout`);
+    }
+  }
+
+  stopJob() {
+    clearInterval(this._jobTimer);
+    this._jobTimer = null;
+    this._jobType  = null;
+  }
+
+  _startGuardJob({ attackRange = 400, patrolRadius = 300, tickMs = 800 } = {}) {
+    this._jobType = 'guard';
+    const _origin = { x: this.self?.x ?? 4096, y: this.self?.y ?? 4096 };
+    let _angle = 0;
+
+    this._jobTimer = setInterval(() => {
+      if (!this._connected) return;
+      const closest = this.getClosestPlayer();
+
+      if (closest && closest.dist <= attackRange && closest.hp > 0) {
+        this.attack(closest.id);
+        return;
+      }
+
+      // Patrol: orbit origin
+      _angle += 0.12;
+      const tx = _origin.x + Math.cos(_angle) * patrolRadius;
+      const ty = _origin.y + Math.sin(_angle) * patrolRadius;
+      this.move(tx, ty);
+    }, tickMs);
+  }
+
+  _startScoutJob({ roamRadius = 1500, tickMs = 4000 } = {}) {
+    this._jobType = 'scout';
+    const center = { x: this.self?.x ?? 4096, y: this.self?.y ?? 4096 };
+
+    this._jobTimer = setInterval(() => {
+      if (!this._connected) return;
+      const angle = Math.random() * Math.PI * 2;
+      const dist  = roamRadius * (0.4 + Math.random() * 0.6);
+      const tx    = Math.max(0, Math.min(center.x + Math.cos(angle) * dist, 8192));
+      const ty    = Math.max(0, Math.min(center.y + Math.sin(angle) * dist, 8192));
+      this.move(tx, ty);
+    }, tickMs);
+  }
+
+  // ── Getters ────────────────────────────────────────────────────────────────
+
+  get isConnected() { return this._connected; }
+  get self()        { return this._state.getSelf(); }
+  get zone()        { return this._state.zone; }
+  get players()     { return this._state.getPlayers(); }
+  get inCombat()    { return this._state.inCombat; }
+  get jobType()     { return this._jobType ?? null; }
+}

package/src/constants.js

@@ -0,0 +1,14 @@
+export const VALID_ZONES = new Set(['terminal', 'darkFields', 'crimsonRidge', 'voidExpanse']);
+
+export const ZONE_NAMES = {
+  terminal:     'THE TERMINAL',
+  darkFields:   'THE DARK FIELDS',
+  crimsonRidge: 'THE CRIMSON RIDGE',
+  voidExpanse:  'THE VOID EXPANSE',
+};
+
+export const WORLD_BOUNDS = { width: 8192, height: 8192 };
+
+export const CONNECT_TIMEOUT_MS = 15_000;
+export const MOVE_THROTTLE_MS   = 100;   // 10 moves/sec max (server allows 30)
+export const ATTACK_THROTTLE_MS = 220;   // ~4.5 attacks/sec (server allows 5)

package/src/index.js

@@ -0,0 +1,3 @@
+export { TerminalDestinyAgent } from './TerminalDestinyAgent.js';
+export { GameState }             from './GameState.js';
+export { VALID_ZONES, ZONE_NAMES, WORLD_BOUNDS } from './constants.js';