@moikapy/lich 0.4.0 → 0.5.0

package/examples/game_bridge/enemy_actions.mjs

@@ -0,0 +1,44 @@
+import { append_jsonl, ensure_game_dir, tool_failure } from "./bridge_io.mjs";
+import { ORDERS_FILE, game_file } from "./bridge_paths.mjs";
+import { read_snapshot_round } from "./snapshot.mjs";
+import { enemy_actions_schema } from "./schemas.mjs";
+import { normalize_actions, validate_enemy_actions } from "./validate_order.mjs";
+
+export const enemy_actions_tool = {
+  name: "enemy_actions",
+  description: "Queue every enemy action for one combat round. Godot drains the order next tick.",
+  parameters: enemy_actions_schema,
+  execute: queue_enemy_actions,
+};
+
+async function queue_enemy_actions(args, context) {
+  const problem = validate_enemy_actions(args);
+  if (problem !== undefined) {
+    return { ok: false, output: "", error: problem };
+  }
+  try {
+    await ensure_game_dir(context.work_dir);
+    const actions = normalize_actions(args.actions);
+    const written = await append_jsonl(game_file(context.work_dir, ORDERS_FILE), {
+      ts: new Date().toISOString(),
+      round: args.round,
+      actions,
+      rationale: args.rationale,
+    });
+    if (written.ok === false) {
+      return { ok: false, output: "", error: written.error };
+    }
+    const snapshot_round = await read_snapshot_round(context.work_dir);
+    return { ok: true, output: format_count(actions.length, args.round, snapshot_round) };
+  } catch (error) {
+    return tool_failure(error);
+  }
+}
+
+function format_count(count, round, snapshot_round) {
+  const base = `appended ${count} orders for round ${round}`;
+  if (snapshot_round === undefined || snapshot_round === round) {
+    return base;
+  }
+  return `${base}; snapshot_round_mismatch: snapshot=${snapshot_round}`;
+}

package/examples/game_bridge/game_bridge.plugin.mjs

@@ -0,0 +1,17 @@
+/**
+ * Combat-commander bridge. Tools write `.lich/game/` files; Godot drains them.
+ * Plain `.mjs` so Node (>=20) loads it from config.plugins with no type-strip.
+ */
+import { dungeon_memory_read_tool, dungeon_memory_write_tool } from "./dungeon_memory.mjs";
+import { enemy_actions_tool } from "./enemy_actions.mjs";
+import { meteor_veto } from "./meteor_veto.mjs";
+
+const game_bridge = {
+  name: "game_bridge",
+  tools: [enemy_actions_tool, dungeon_memory_read_tool, dungeon_memory_write_tool],
+  hooks: {
+    before_tool_call: meteor_veto,
+  },
+};
+
+export default game_bridge;

package/examples/game_bridge/meteor_veto.mjs

@@ -0,0 +1,22 @@
+const METEOR_GATE_ROUND = 3;
+const METEOR_REASON = "meteor_gates_closed_until_round_3";
+
+export async function meteor_veto(info) {
+  if (info.tool_name !== "enemy_actions") {
+    return;
+  }
+  const round = Number(info.args.round ?? 0);
+  const actions = Array.isArray(info.args.actions) ? info.args.actions : [];
+  if (round < METEOR_GATE_ROUND && uses_meteor(actions) === true) {
+    return { block: true, reason: METEOR_REASON };
+  }
+}
+
+function uses_meteor(actions) {
+  return actions.some((action) => {
+    if (typeof action !== "object" || action === null) {
+      return false;
+    }
+    return String(action.action).includes("meteor");
+  });
+}

package/examples/game_bridge/schemas.mjs

@@ -0,0 +1,48 @@
+export const enemy_actions_schema = {
+  type: "object",
+  properties: {
+    round: {
+      type: "number",
+      description: "Current combat round number (from the battle snapshot).",
+    },
+    actions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          enemy_id: { type: "string", description: "Acting enemy's id." },
+          action: {
+            type: "string",
+            description: "Ability id from the enemy's kit, or the literal move: attack|defend|flee.",
+          },
+          target_ref: { type: "string", description: "Target reference: hero:<id> or enemy:<id>." },
+        },
+        required: ["enemy_id", "action", "target_ref"],
+      },
+    },
+    rationale: {
+      type: "string",
+      description: "One-line explanation of the round plan; doubles as the replayable combat log entry.",
+    },
+  },
+  required: ["round", "actions", "rationale"],
+  additionalProperties: false,
+};
+
+export const dungeon_memory_read_schema = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+};
+
+export const dungeon_memory_write_schema = {
+  type: "object",
+  properties: {
+    note: {
+      type: "string",
+      description: "Durable cross-run observation about the player; appended to dungeon memory.",
+    },
+  },
+  required: ["note"],
+  additionalProperties: false,
+};

package/examples/game_bridge/snapshot.mjs

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import { STATE_FILE, game_file } from "./bridge_paths.mjs";
+
+/** Godot may refresh state.json; a missing or partial snapshot is not an error. */
+export async function read_snapshot_round(work_dir) {
+  try {
+    const raw = await readFile(game_file(work_dir, STATE_FILE), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return undefined;
+    }
+    if (typeof parsed.round !== "number" || Number.isFinite(parsed.round) === false) {
+      return undefined;
+    }
+    return parsed.round;
+  } catch {
+    return undefined;
+  }
+}

package/examples/game_bridge/validate_order.mjs

@@ -0,0 +1,44 @@
+const TARGET_REF = /^(hero|enemy):.+$/;
+
+export function validate_enemy_actions(args) {
+  if (typeof args.round !== "number" || Number.isFinite(args.round) === false) {
+    return "round_must_be_number";
+  }
+  if (typeof args.rationale !== "string" || args.rationale.length === 0) {
+    return "rationale_required";
+  }
+  if (Array.isArray(args.actions) === false) {
+    return "actions_must_be_array";
+  }
+  for (const action of args.actions) {
+    const problem = validate_action(action);
+    if (problem !== undefined) {
+      return problem;
+    }
+  }
+  return undefined;
+}
+
+export function normalize_actions(actions) {
+  return actions.map((action) => ({
+    enemy_id: action.enemy_id,
+    action: action.action,
+    target_ref: action.target_ref,
+  }));
+}
+
+function validate_action(action) {
+  if (typeof action !== "object" || action === null || Array.isArray(action)) {
+    return "action_must_be_object";
+  }
+  if (typeof action.enemy_id !== "string" || action.enemy_id.length === 0) {
+    return "enemy_id_required";
+  }
+  if (typeof action.action !== "string" || action.action.length === 0) {
+    return "action_required";
+  }
+  if (typeof action.target_ref !== "string" || TARGET_REF.test(action.target_ref) === false) {
+    return "target_ref_must_be_hero_or_enemy";
+  }
+  return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moikapy/lich",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Lich — a TypeScript AI agent harness (library + CLI) inspired by Hermes",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,7 @@
     "docs",
     "!docs/.vitepress/dist",
     "!docs/.vitepress/cache",
+    "examples/game_bridge",
     "README.md",
     "CHANGELOG.md"
   ],