@moikapy/lich 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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).

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-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