@agent-e/server 1.4.0

package/README.md

@@ -0,0 +1,167 @@
+# @agent-e/server
+
+Plug-and-play HTTP + WebSocket server for AgentE. Send your game's economy state, get back parameter adjustments.
+
+## Quick Start
+
+```ts
+import { startServer } from '@agent-e/server';
+
+const server = await startServer({ port: 3000 });
+// Server is running — POST /tick, GET /health, etc.
+```
+
+Or with full configuration:
+
+```ts
+import { AgentEServer } from '@agent-e/server';
+
+const server = new AgentEServer({
+  port: 3000,
+  host: '0.0.0.0',
+  agentEConfig: {
+    mode: 'autonomous',     // or 'advisor' for recommendations only
+    gracePeriod: 50,         // no interventions before tick 50
+    checkInterval: 5,        // analyze every 5 ticks
+    dominantRoles: ['Fighter'],
+    maxAdjustmentPercent: 0.15,
+    cooldownTicks: 15,
+  },
+});
+
+await server.start();
+```
+
+## API Reference
+
+### POST /tick
+
+Send economy state, receive parameter adjustments.
+
+**Request:**
+```json
+{
+  "state": {
+    "tick": 100,
+    "roles": ["Fighter", "Crafter"],
+    "resources": ["ore", "weapons"],
+    "currencies": ["gold"],
+    "agentBalances": { "a1": { "gold": 150 } },
+    "agentRoles": { "a1": "Fighter" },
+    "agentInventories": { "a1": { "weapons": 2 } },
+    "marketPrices": { "gold": { "ore": 15 } },
+    "recentTransactions": []
+  },
+  "events": []
+}
+```
+
+**Response (200):**
+```json
+{
+  "adjustments": [{ "key": "craftingCost", "value": 12.5 }],
+  "alerts": [{ "principle": "P1", "severity": 7 }],
+  "health": 85,
+  "decisions": [{ "id": "d_1", "parameter": "craftingCost", "result": "applied" }]
+}
+```
+
+**Error (400):** Invalid state returns validation errors.
+
+### GET /health
+
+```json
+{
+  "health": 85,
+  "tick": 100,
+  "mode": "autonomous",
+  "activePlans": 1,
+  "uptime": 60000
+}
+```
+
+### GET /decisions
+
+Query parameters: `?limit=50`, `?since=100`
+
+```json
+{
+  "decisions": [{
+    "id": "d_1",
+    "tick": 100,
+    "principle": "P1",
+    "parameter": "craftingCost",
+    "result": "applied",
+    "reasoning": "..."
+  }]
+}
+```
+
+### POST /config
+
+Lock/unlock parameters, change mode.
+
+```json
+{ "action": "lock", "param": "craftingCost" }
+{ "action": "unlock", "param": "craftingCost" }
+{ "action": "constrain", "param": "miningYield", "min": 0.5, "max": 2.0 }
+{ "action": "mode", "mode": "advisor" }
+```
+
+### GET /principles
+
+Lists all 60 built-in principles.
+
+### POST /diagnose
+
+Run Observer + Diagnoser without side effects (no parameter changes).
+
+```json
+{ "state": { ... } }
+```
+
+## WebSocket
+
+Connect to the same port via WebSocket upgrade.
+
+### Client → Server Messages
+
+```json
+{ "type": "tick", "state": {...}, "events": [...] }
+{ "type": "event", "event": { "type": "trade", ... } }
+{ "type": "health" }
+{ "type": "diagnose", "state": {...} }
+```
+
+### Server → Client Messages
+
+```json
+{ "type": "tick_result", "adjustments": [...], "health": 85 }
+{ "type": "health_result", "health": 85, "uptime": 60000 }
+{ "type": "diagnose_result", "diagnoses": [...] }
+{ "type": "validation_error", "validation": {...} }
+{ "type": "validation_warning", "warning": {...} }
+{ "type": "error", "error": "..." }
+```
+
+Heartbeat: Server pings every 30 seconds.
+
+## State Validation
+
+All incoming state is validated before processing. Invalid state returns detailed errors with paths:
+
+```json
+{
+  "error": "Invalid state",
+  "validation": {
+    "valid": false,
+    "errors": [{
+      "path": "agentBalances.a1.gold",
+      "expected": "number >= 0",
+      "received": "string",
+      "message": "agentBalances.a1.gold must be a non-negative number"
+    }],
+    "warnings": []
+  }
+}
+```

package/dist/AgentEServer-IF7QK2SK.mjs

@@ -0,0 +1,7 @@
+import {
+  AgentEServer
+} from "./chunk-VNNX52KX.mjs";
+export {
+  AgentEServer
+};
+//# sourceMappingURL=AgentEServer-IF7QK2SK.mjs.map

package/dist/AgentEServer-IF7QK2SK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-VNNX52KX.mjs

@@ -0,0 +1,468 @@
+// src/AgentEServer.ts
+import * as http from "http";
+import {
+  AgentE
+} from "@agent-e/core";
+
+// src/routes.ts
+import { validateEconomyState } from "@agent-e/core";
+function setCorsHeaders(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+}
+function json(res, status, data) {
+  setCorsHeaders(res);
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+function createRouteHandler(server) {
+  return async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const path = url.pathname;
+    const method = req.method?.toUpperCase() ?? "GET";
+    if (method === "OPTIONS") {
+      setCorsHeaders(res);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    try {
+      if (path === "/tick" && method === "POST") {
+        const body = await readBody(req);
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          json(res, 400, { error: "Invalid JSON" });
+          return;
+        }
+        if (!parsed || typeof parsed !== "object") {
+          json(res, 400, { error: "Body must be a JSON object" });
+          return;
+        }
+        const payload = parsed;
+        const state = payload["state"] ?? parsed;
+        const events = payload["events"];
+        const validation = validateEconomyState(state);
+        if (!validation.valid) {
+          json(res, 400, {
+            error: "Invalid state",
+            validation
+          });
+          return;
+        }
+        const result = await server.processTick(
+          state,
+          Array.isArray(events) ? events : void 0
+        );
+        json(res, 200, {
+          adjustments: result.adjustments,
+          alerts: result.alerts.map((a) => ({
+            principle: a.principle.id,
+            name: a.principle.name,
+            severity: a.violation.severity,
+            evidence: a.violation.evidence,
+            suggestedAction: a.violation.suggestedAction
+          })),
+          health: result.health,
+          decisions: result.decisions.map((d) => ({
+            id: d.id,
+            tick: d.tick,
+            principle: d.diagnosis.principle.id,
+            parameter: d.plan.parameter,
+            result: d.result,
+            reasoning: d.reasoning
+          }))
+        });
+        return;
+      }
+      if (path === "/health" && method === "GET") {
+        const agentE = server.getAgentE();
+        json(res, 200, {
+          health: agentE.getHealth(),
+          tick: agentE.metrics.latest()?.tick ?? 0,
+          mode: agentE.getMode(),
+          activePlans: agentE.getActivePlans().length,
+          uptime: server.getUptime()
+        });
+        return;
+      }
+      if (path === "/decisions" && method === "GET") {
+        const limit = parseInt(url.searchParams.get("limit") ?? "50", 10);
+        const since = url.searchParams.get("since");
+        const agentE = server.getAgentE();
+        let decisions;
+        if (since) {
+          decisions = agentE.getDecisions({ since: parseInt(since, 10) });
+        } else {
+          decisions = agentE.log.latest(limit);
+        }
+        json(res, 200, {
+          decisions: decisions.map((d) => ({
+            id: d.id,
+            tick: d.tick,
+            timestamp: d.timestamp,
+            principle: d.diagnosis.principle.id,
+            principeName: d.diagnosis.principle.name,
+            parameter: d.plan.parameter,
+            currentValue: d.plan.currentValue,
+            targetValue: d.plan.targetValue,
+            result: d.result,
+            reasoning: d.reasoning
+          }))
+        });
+        return;
+      }
+      if (path === "/config" && method === "POST") {
+        const body = await readBody(req);
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          json(res, 400, { error: "Invalid JSON" });
+          return;
+        }
+        const config = parsed;
+        if (config["action"] === "lock" && typeof config["param"] === "string") {
+          server.lock(config["param"]);
+          json(res, 200, { ok: true, action: "lock", param: config["param"] });
+        } else if (config["action"] === "unlock" && typeof config["param"] === "string") {
+          server.unlock(config["param"]);
+          json(res, 200, { ok: true, action: "unlock", param: config["param"] });
+        } else if (config["action"] === "constrain" && typeof config["param"] === "string" && typeof config["min"] === "number" && typeof config["max"] === "number") {
+          server.constrain(config["param"], { min: config["min"], max: config["max"] });
+          json(res, 200, { ok: true, action: "constrain", param: config["param"] });
+        } else if (config["action"] === "mode" && (config["mode"] === "autonomous" || config["mode"] === "advisor")) {
+          server.setMode(config["mode"]);
+          json(res, 200, { ok: true, action: "mode", mode: config["mode"] });
+        } else {
+          json(res, 400, {
+            error: "Invalid config action. Use: lock, unlock, constrain, or mode"
+          });
+        }
+        return;
+      }
+      if (path === "/principles" && method === "GET") {
+        const principles = server.getAgentE().getPrinciples();
+        json(res, 200, {
+          count: principles.length,
+          principles: principles.map((p) => ({
+            id: p.id,
+            name: p.name,
+            category: p.category,
+            description: p.description
+          }))
+        });
+        return;
+      }
+      if (path === "/diagnose" && method === "POST") {
+        const body = await readBody(req);
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          json(res, 400, { error: "Invalid JSON" });
+          return;
+        }
+        const payload = parsed;
+        const state = payload["state"] ?? parsed;
+        const validation = validateEconomyState(state);
+        if (!validation.valid) {
+          json(res, 400, { error: "Invalid state", validation });
+          return;
+        }
+        const result = server.diagnoseOnly(state);
+        json(res, 200, {
+          health: result.health,
+          diagnoses: result.diagnoses.map((d) => ({
+            principle: d.principle.id,
+            name: d.principle.name,
+            severity: d.violation.severity,
+            evidence: d.violation.evidence,
+            suggestedAction: d.violation.suggestedAction
+          }))
+        });
+        return;
+      }
+      json(res, 404, { error: "Not found" });
+    } catch (err) {
+      json(res, 500, { error: "Internal server error" });
+    }
+  };
+}
+
+// src/websocket.ts
+import { WebSocketServer, WebSocket } from "ws";
+import { validateEconomyState as validateEconomyState2 } from "@agent-e/core";
+function send(ws, data) {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(data));
+  }
+}
+function createWebSocketHandler(httpServer, server) {
+  const wss = new WebSocketServer({ server: httpServer });
+  const heartbeatInterval = setInterval(() => {
+    for (const ws of wss.clients) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.ping();
+      }
+    }
+  }, 3e4);
+  wss.on("connection", (ws) => {
+    ws.on("message", async (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        send(ws, { type: "error", error: "Invalid JSON" });
+        return;
+      }
+      if (!msg.type || typeof msg.type !== "string") {
+        send(ws, { type: "error", error: 'Missing "type" field' });
+        return;
+      }
+      switch (msg.type) {
+        case "tick": {
+          const state = msg["state"];
+          const events = msg["events"];
+          const validation = validateEconomyState2(state);
+          if (!validation.valid) {
+            send(ws, { type: "validation_error", validation });
+            for (const w of validation.warnings) {
+              send(ws, { type: "validation_warning", warning: w });
+            }
+            return;
+          }
+          for (const w of validation.warnings) {
+            send(ws, { type: "validation_warning", warning: w });
+          }
+          try {
+            const result = await server.processTick(
+              state,
+              Array.isArray(events) ? events : void 0
+            );
+            send(ws, {
+              type: "tick_result",
+              adjustments: result.adjustments,
+              alerts: result.alerts.map((a) => ({
+                principle: a.principle.id,
+                name: a.principle.name,
+                severity: a.violation.severity,
+                suggestedAction: a.violation.suggestedAction
+              })),
+              health: result.health,
+              decisions: result.decisions.map((d) => ({
+                id: d.id,
+                tick: d.tick,
+                principle: d.diagnosis.principle.id,
+                parameter: d.plan.parameter,
+                result: d.result
+              }))
+            });
+          } catch (err) {
+            send(ws, { type: "error", error: "Tick processing failed" });
+          }
+          break;
+        }
+        case "event": {
+          const event = msg["event"];
+          if (event) {
+            server.getAgentE().ingest(event);
+            send(ws, { type: "event_ack" });
+          } else {
+            send(ws, { type: "error", error: 'Missing "event" field' });
+          }
+          break;
+        }
+        case "health": {
+          const agentE = server.getAgentE();
+          send(ws, {
+            type: "health_result",
+            health: agentE.getHealth(),
+            tick: agentE.metrics.latest()?.tick ?? 0,
+            mode: agentE.getMode(),
+            activePlans: agentE.getActivePlans().length,
+            uptime: server.getUptime()
+          });
+          break;
+        }
+        case "diagnose": {
+          const state = msg["state"];
+          const validation = validateEconomyState2(state);
+          if (!validation.valid) {
+            send(ws, { type: "validation_error", validation });
+            return;
+          }
+          const result = server.diagnoseOnly(state);
+          send(ws, {
+            type: "diagnose_result",
+            health: result.health,
+            diagnoses: result.diagnoses.map((d) => ({
+              principle: d.principle.id,
+              name: d.principle.name,
+              severity: d.violation.severity,
+              suggestedAction: d.violation.suggestedAction
+            }))
+          });
+          break;
+        }
+        default:
+          send(ws, { type: "error", error: `Unknown message type: "${msg.type}"` });
+      }
+    });
+  });
+  return () => {
+    clearInterval(heartbeatInterval);
+    wss.close();
+  };
+}
+
+// src/AgentEServer.ts
+var AgentEServer = class {
+  constructor(config = {}) {
+    this.lastState = null;
+    this.adjustmentQueue = [];
+    this.alerts = [];
+    this.startedAt = Date.now();
+    this.cleanupWs = null;
+    this.port = config.port ?? 3e3;
+    this.host = config.host ?? "0.0.0.0";
+    const adapter = {
+      getState: () => {
+        if (!this.lastState) {
+          return {
+            tick: 0,
+            roles: [],
+            resources: [],
+            currencies: ["default"],
+            agentBalances: {},
+            agentRoles: {},
+            agentInventories: {},
+            marketPrices: {},
+            recentTransactions: []
+          };
+        }
+        return this.lastState;
+      },
+      setParam: (key, value) => {
+        this.adjustmentQueue.push({ key, value });
+      }
+    };
+    const agentEConfig = {
+      adapter,
+      mode: config.agentEConfig?.mode ?? "autonomous",
+      gracePeriod: config.agentEConfig?.gracePeriod ?? 0,
+      checkInterval: config.agentEConfig?.checkInterval ?? 1,
+      ...config.agentEConfig?.dominantRoles ? { dominantRoles: config.agentEConfig.dominantRoles } : {},
+      ...config.agentEConfig?.idealDistribution ? { idealDistribution: config.agentEConfig.idealDistribution } : {},
+      ...config.agentEConfig?.maxAdjustmentPercent !== void 0 ? { maxAdjustmentPercent: config.agentEConfig.maxAdjustmentPercent } : {},
+      ...config.agentEConfig?.cooldownTicks !== void 0 ? { cooldownTicks: config.agentEConfig.cooldownTicks } : {},
+      ...config.agentEConfig?.thresholds ? { thresholds: config.agentEConfig.thresholds } : {}
+    };
+    this.agentE = new AgentE(agentEConfig);
+    this.agentE.on("alert", (diagnosis) => {
+      this.alerts.push(diagnosis);
+    });
+    this.agentE.connect(adapter).start();
+    const routeHandler = createRouteHandler(this);
+    this.server = http.createServer(routeHandler);
+  }
+  async start() {
+    this.cleanupWs = createWebSocketHandler(this.server, this);
+    return new Promise((resolve) => {
+      this.server.listen(this.port, this.host, () => {
+        resolve();
+      });
+    });
+  }
+  async stop() {
+    this.agentE.stop();
+    if (this.cleanupWs) this.cleanupWs();
+    return new Promise((resolve, reject) => {
+      this.server.close((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+  getAgentE() {
+    return this.agentE;
+  }
+  getAddress() {
+    const addr = this.server.address();
+    if (addr && typeof addr === "object") {
+      return { port: addr.port, host: addr.address };
+    }
+    return { port: this.port, host: this.host };
+  }
+  getUptime() {
+    return Date.now() - this.startedAt;
+  }
+  /**
+   * Process a tick with the given state.
+   * 1. Clear adjustment queue
+   * 2. Set state
+   * 3. Ingest events
+   * 4. Run agentE.tick(state)
+   * 5. Drain adjustment queue
+   * 6. Return response
+   */
+  async processTick(state, events) {
+    this.adjustmentQueue = [];
+    this.alerts = [];
+    this.lastState = state;
+    if (events) {
+      for (const event of events) {
+        this.agentE.ingest(event);
+      }
+    }
+    await this.agentE.tick(state);
+    const adjustments = [...this.adjustmentQueue];
+    this.adjustmentQueue = [];
+    const decisions = this.agentE.getDecisions({ since: state.tick, until: state.tick });
+    return {
+      adjustments,
+      alerts: [...this.alerts],
+      health: this.agentE.getHealth(),
+      decisions
+    };
+  }
+  /**
+   * Run Observer + Diagnoser without side effects (no execution)
+   */
+  diagnoseOnly(state) {
+    const prevState = this.lastState;
+    this.lastState = state;
+    const diagnoser = this.agentE;
+    const diagnoses = diagnoser.diagnoseNow();
+    const health = diagnoser.getHealth();
+    this.lastState = prevState;
+    return { diagnoses, health };
+  }
+  setMode(mode) {
+    this.agentE.setMode(mode);
+  }
+  lock(param) {
+    this.agentE.lock(param);
+  }
+  unlock(param) {
+    this.agentE.unlock(param);
+  }
+  constrain(param, bounds) {
+    this.agentE.constrain(param, bounds);
+  }
+};
+
+export {
+  AgentEServer
+};
+//# sourceMappingURL=chunk-VNNX52KX.mjs.map