@moikapy/lich 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.6.0 (unreleased)
+
+- document a per-persona orchestrator example: one agent per NPC, the
+  webhook `POST /message` shape, and history serialization the game repo
+  copies. lich does not ship the service. see
+  examples/persona_orchestrator.
+- document session JSONL as a combat log, with jq recipes for rationale,
+  ability use, vetoes, rejects, and `run_end` token totals. see
+  docs/user-guide/games.md.
+- append a `run_end` meta record (`stopped_reason`, `usage`) on every
+  completed run so token spend is in the transcript. `budget_exhausted`
+  is still written when the stop reason is budget.
+- add a display-only undead theme: frozen `lich` strings, `theme` / `--theme`, and `~/.lich/themes/<name>.json` that falls back to the built-in theme when missing or invalid.
+
+## 0.5.1
+
+- fix the CLI so bun's global bin enters main (symlink argv no longer skips the entry).
+- read LICH_VERSION from package.json so lich --version is not stuck at 0.3.0.
+
 ## 0.5.0
 
 - add a `game_bridge` example plugin that queues batched enemy actions

package/README.md

@@ -1,10 +1,29 @@
-# lich
+# ⚱ lich
 
 Lich is a TypeScript AI agent harness (library + CLI) that runs a
 Think-Act-Observe loop: an LLM plans, calls tools, observes results, and
 repeats until it produces a final answer. It ships with provider failover,
 tool guardrails, context compression, and JSONL session persistence.
 
+## Lore glossary
+
+Lore names are prose only. Identifiers, config keys, event types, and tool
+names do not change. The default system prompt is a myth-free behavior spec;
+mythology lives in display strings only.
+
+| Lore term | Actual concept | Where it appears |
+| --- | --- | --- |
+| **phylacteries** | JSONL session files in `.lich/sessions/` — conversations survive process death | This glossary; TUI `/sessions` listing label |
+| **vessel-hopping** | Provider failover: 429/5xx retried with backoff, then the next provider takes over | This glossary |
+| **the lair / wards** | `work_dir` confinement + `path_escape` guardrails | This glossary |
+| **lair actions** | Plugin hooks that observe or veto tool calls | This glossary |
+| **familiars** | Gateway adapters (webhook/telegram/discord/twitch) routing into one shared agent | This glossary |
+| **spells** | Builtin tools in the registry | This glossary |
+| **distillation** | Context compression: old turns summarized to fit the token budget | TUI compress notice |
+| **the ritual is spent** | Turn-budget exhaustion | TUI + CLI budget notices |
+| **dormant / deliberating / casting** | idle / thinking / tool phases | TUI status bar phase labels |
+| **mortal** | The human user | TUI user transcript label |
+
 ## Documentation
 
 | Page | Contents |
@@ -15,6 +34,8 @@ tool guardrails, context compression, and JSONL session persistence.
 | [TUI guide](docs/user-guide/tui.md) | Launch, slash commands, status bar, memory semantics. |
 | [Gateway guide](docs/user-guide/gateway.md) | Webhook/Telegram/Discord/Twitch setup and the webhook API. |
 | [Library guide](docs/user-guide/library.md) | Embedding: `create_agent`, events, multi-turn history, errors. |
+| [Games guide](docs/user-guide/games.md) | Session JSONL as a combat log, and jq recipes over it. |
+| [Persona example](examples/persona_orchestrator/README.md) | Per-NPC agents the game repo copies. Not a second core. |
 
 ## Quick start (CLI)
 
@@ -184,6 +205,42 @@ lich tui
 Slash commands: `/help`, `/model`, `/usage`, `/clear`, `/sessions`,
 `/exit` (also `/quit`, `/q`). The transcript shows the newest 50 blocks.
 
+## Themes
+
+Display strings come from one active theme per process. Set `"theme": "lich"`
+in `.lich/config.json`, or pass `--theme <name>`. The built-in `lich` theme
+is frozen data: `~/.lich/themes/lich.json` is ignored. Any other name is read
+from `~/.lich/themes/<name>.json`. A missing file, invalid JSON, or a file
+that fails the theme schema logs one warning and falls back to `lich`. Themes
+do not change the system prompt, tool descriptions, event types, or slash
+command names.
+
+The built-in tagline is `the agent that will not stay dead`, and it appears once, in the TUI banner (`welcome`). Greppable keywords
+stay in place: budget notices still start with `budget exhausted`, and
+compression notices still start with `context compressed`.
+
+```json
+{
+  "name": "vampire",
+  "agent_name": "vampire",
+  "glyph": "🦇",
+  "tagline": "night's clerk, unpaid",
+  "welcome": "🦇 vampire v{version} — night's clerk, unpaid · {model} ({kind})",
+  "goodbye": "dawn approaches",
+  "response_label": "vampire",
+  "user_label": "mortal",
+  "phase_labels": { "idle": "sleeping", "thinking": "scheming", "tool": "feeding" },
+  "notices": {
+    "budget_exhausted": "budget exhausted — the blood bank is dry (turn cap reached)",
+    "compressed": "context compressed — memories enthralled (summary {chars} chars)",
+    "sessions": "coffins ({count}):"
+  }
+}
+```
+
+`welcome` substitutes `{version}`, `{model}`, and `{kind}`. `notices.compressed`
+substitutes `{chars}`; `notices.sessions` substitutes `{count}`.
+
 ## Development
 
 ```sh

package/dist/chunk-6M6OAQGN.js

@@ -0,0 +1,17 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+function read_package_version() {
+  const pkg_path = fileURLToPath(new URL("../package.json", import.meta.url));
+  const pkg = JSON.parse(readFileSync(pkg_path, "utf8"));
+  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    throw new Error("package.json is missing version");
+  }
+  return pkg.version;
+}
+var LICH_VERSION = read_package_version();
+
+export {
+  LICH_VERSION
+};
+//# sourceMappingURL=chunk-6M6OAQGN.js.map

package/dist/chunk-6M6OAQGN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Public surface of the lich agent harness. Pure re-exports, plus the package version.\n */\nimport { readFileSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\n\nfunction read_package_version(): string {\n  const pkg_path = fileURLToPath(new URL(\"../package.json\", import.meta.url));\n  const pkg = JSON.parse(readFileSync(pkg_path, \"utf8\")) as { version?: unknown };\n  if (typeof pkg.version !== \"string\" || pkg.version.length === 0) {\n    throw new Error(\"package.json is missing version\");\n  }\n  return pkg.version;\n}\n\nexport const LICH_VERSION = read_package_version();\n\nexport { Agent, create_agent, run_agent, create_agent_with_plugins } from \"./agent/agent.js\";\nexport type { AgentRunOptions, AgentRunResult } from \"./agent/agent.js\";\nexport type { AgentConfig } from \"./agent/config.js\";\nexport { parse_agent_config } from \"./agent/config.js\";\nexport { AgentEmitter } from \"./agent/events.js\";\nexport type { AgentEvent, AgentEventHandler, AgentEvents } from \"./agent/events.js\";\nexport type { LoopOutcome, LoopParams } from \"./agent/loop.js\";\nexport type {\n  ChatOptions,\n  ChatResult,\n  Message,\n  ProviderConfig,\n  ToolCall,\n  ToolDefinition,\n  Usage,\n} from \"./providers/types.js\";\nexport { ProviderError } from \"./providers/types.js\";\nexport { ToolExecutor } from \"./tools/executor.js\";\nexport { ToolRegistry } from \"./tools/registry.js\";\nexport type { Tool, ToolContext, ToolResult } from \"./tools/types.js\";\nexport { register_builtin_tools } from \"./tools/builtin/index.js\";\nexport { HookedToolRunner } from \"./plugins/hooks.js\";\nexport { load_plugins, plugin_errors_summary } from \"./plugins/loader.js\";\nexport type { LoadedPlugin, PluginLoadError } from \"./plugins/loader.js\";\nexport type {\n  AfterToolCallInfo,\n  BeforeToolCallInfo,\n  BeforeToolCallResult,\n  HookContext,\n  Plugin,\n  PluginHooks,\n  RunEndInfo,\n} from \"./plugins/types.js\";"],"mappings":";AAGA,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAE9B,SAAS,uBAA+B;AACtC,QAAM,WAAW,cAAc,IAAI,IAAI,mBAAmB,YAAY,GAAG,CAAC;AAC1E,QAAM,MAAM,KAAK,MAAM,aAAa,UAAU,MAAM,CAAC;AACrD,MAAI,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,WAAW,GAAG;AAC/D,UAAM,IAAI,MAAM,iCAAiC;AAAA,EACnD;AACA,SAAO,IAAI;AACb;AAEO,IAAM,eAAe,qBAAqB;","names":[]}

package/dist/{chunk-CV2YH3FH.js → chunk-7HLVKVIG.js}

@@ -1930,7 +1930,7 @@ var provider_schema = z.object({
   fetch_fn: z.custom(() => true).optional()
 }).passthrough();
 var agent_config_schema = z.object({
-  /** Display name used by the TUI banner. */
+  /** Wizard label. The TUI banner uses the active theme welcome string. */
   agent_name: z.string().min(1).default("lich"),
   system_prompt: z.string().optional(),
   max_turns: z.number().int().min(1).default(25),
@@ -1946,7 +1946,8 @@ var agent_config_schema = z.object({
   /** Plugin entry module specifiers, relative to work_dir or absolute. */
   plugins: z.array(z.string()).default([]),
   gateway: gateway_schema,
-  log_level: z.enum(["debug", "info", "warn", "error"]).default("info")
+  log_level: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  theme: z.string().min(1).default("lich")
 }).transform((config) => {
   const work_dir = config.work_dir ?? process.cwd();
   return {
@@ -3640,6 +3641,17 @@ function collect_usage(total) {
 function append_meta(handle, meta) {
   return handle.append({ ts: (/* @__PURE__ */ new Date()).toISOString(), kind: "meta", meta });
 }
+function append_run_end(handle, stopped_reason, usage_total) {
+  return append_meta(handle, {
+    event: "run_end",
+    stopped_reason,
+    usage: {
+      prompt_tokens: usage_total.prompt_tokens,
+      completion_tokens: usage_total.completion_tokens,
+      total_tokens: usage_total.total_tokens
+    }
+  });
+}
 function register_plugin_tools(registry, plugins) {
   for (const loaded of plugins) {
     for (const tool of loaded.plugin.tools ?? []) {
@@ -3716,7 +3728,7 @@ var Agent = class {
         await this.call_plugin_run_end(outcome);
       }
     }
-    const session_path = await this.persist_session(outcome, options);
+    const session_path = await this.persist_session(outcome, options, usage_total);
     const full_messages = [...options.history ?? [], ...outcome.messages];
     return { outcome, messages: full_messages, usage_total, session_path };
   }
@@ -3750,7 +3762,7 @@ var Agent = class {
     );
   }
   /** Best-effort JSONL transcript: never fails the run, returns undefined path on error. */
-  async persist_session(outcome, options) {
+  async persist_session(outcome, options, usage_total) {
     try {
       const handle = await open_session(this.config.session_dir, options.label);
       await append_meta(handle, { event: "run_start", input_chars: options.input.length, history_size: outcome.messages.length });
@@ -3760,6 +3772,7 @@ var Agent = class {
       if (outcome.stopped_reason === "budget") {
         await append_meta(handle, { event: "budget_exhausted" });
       }
+      await append_run_end(handle, outcome.stopped_reason, usage_total);
       return handle.path;
     } catch (error) {
       logger.warn("session persistence failed; continuing without transcript", error);
@@ -3806,4 +3819,4 @@ export {
   create_agent_with_plugins,
   run_agent
 };
-//# sourceMappingURL=chunk-CV2YH3FH.js.map
+//# sourceMappingURL=chunk-7HLVKVIG.js.map