@moikapy/lich 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.7.0 (unreleased)
+
+- add a general MCP client. `mcp_servers` is a closed record of named
+  stdio or loopback-http entries, default off. tool names are
+  `mcp_<server>_<tool>`. `tools_enabled: []` drops them. the commander
+  persona does not copy `mcp_servers`. redot is a catalog entry (local
+  `redot` binary, `--headless --mcp-server --path <project>`, five
+  upstream controllers, no execute). godot has no official server; lich
+  does not download a community addon. play stays the webhook and
+  game_bridge, the opposite direction. see docs/user-guide/redot.md.
+- add `lich mcp` to list, add, enable, disable, and remove servers.
+  add uses the catalog or `--command`/`--url`, stays disabled, and
+  updates `.lich/config.json` through the existing writer without
+  dropping other keys.
+- sync user docs with this tree. the published package is 0.6.0
+  (`lich --version` reads package.json). MCP commands are not in that
+  package. CLI, config, plugin load, and sidebar links match the code.
+  0.7.0 is not released.
+
+## 0.6.0
+
+- 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,20 +1,44 @@
-# 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 |
 | --- | --- |
 | [Docs home](docs/index.md) | Overview, feature map, and a 60-second quickstart. |
 | [Getting started](docs/getting-started.md) | Zero-to-first-reply: install, config paths, one-shot, TUI, gateway. |
-| [CLI reference](docs/user-guide/cli.md) | All four modes, flags, provider resolution, config schema, recipes. |
+| [CLI reference](docs/user-guide/cli.md) | Modes, flags, provider resolution, config schema, `lich mcp`, recipes. |
 | [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. |
+| [Plugins guide](docs/user-guide/plugins.md) | User tools and hooks, and the self-improvement loop. |
+| [Godot guide](docs/user-guide/godot.md) | The game connects to lich (webhook + `game_bridge`). |
+| [Redot guide](docs/user-guide/redot.md) | lich connects to editor MCP servers. Redot is a catalog entry. |
+| [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)
 
@@ -42,7 +66,8 @@ lich gateway webhook
 
 The CLI has four modes: **one-shot** (`lich "task"`), **chat**
 (`lich chat`), **tui** (`lich tui`), and **gateway**
-(`lich gateway <platform...>`).
+(`lich gateway <platform...>`). Other commands do not start an agent:
+`lich init`, `lich config`, `lich update`, and `lich mcp`.
 
 Or use a JSON config file: `lich --config lich.json "task"` (see
 `AgentConfig` in `src/agent/config.ts` for the schema).
@@ -92,7 +117,9 @@ snake_case args and are registered under the `builtin` toolset.
 Customize lich with your own tools and lifecycle hooks: keep a `Plugin`
 object (`{name, tools?, hooks?}`) in your repo, list its file path in the
 `plugins` config array, and the agent merges your tools and lets your hooks
-observe or veto tool calls. See
+observe or veto tool calls. Bare `lich`, one-shot, chat, tui, and gateway
+all load `config.plugins` (`create_agent_with_plugins`). `create_agent` does
+not. See
 [docs/user-guide/plugins.md](docs/user-guide/plugins.md).
 
 Skills are markdown files you write to `.lich/skills/` with `write_file`;
@@ -184,6 +211,59 @@ 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}`.
+
+## Editor MCP
+
+Two directions. lich connects **to** an editor MCP server (stdio local
+command, or loopback HTTP). The game connects **to** lich through the webhook
+and [`examples/game_bridge`](examples/game_bridge/README.md). Default is off.
+`mcp_servers` is a closed record. Names are `mcp_<server>_<tool>`. `npx`,
+`npm`, `bunx`, `uvx`, `curl`, `wget`, remote URLs, and shell metacharacters
+are refused.
+
+This source has `lich mcp list|add|enable|disable|remove` (changelog 0.7.0,
+unreleased). The published npm package is 0.6.0 and does not include those
+commands; `lich --version` still prints `0.6.0` because it reads
+`package.json`. From a clone: `bun src/cli.ts mcp list`. Redot is a catalog
+entry (`redot --headless --mcp-server`), not a fork inside lich. Godot has
+no official MCP server; lich does not download a community addon. See
+[docs/user-guide/redot.md](docs/user-guide/redot.md).
+
 ## Development
 
 ```sh

package/dist/chunk-JYURFAGB.js

@@ -0,0 +1,92 @@
+import {
+  logger
+} from "./chunk-QVJCIZIF.js";
+
+// src/util/theme.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+import { z } from "zod";
+
+// src/util/lore.ts
+var phase_labels = Object.freeze({
+  idle: "dormant",
+  thinking: "deliberating",
+  tool: "casting"
+});
+var notices = Object.freeze({
+  budget_exhausted: "budget exhausted \u2014 the ritual is spent (turn cap reached)",
+  compressed: "context compressed \u2014 memories distilled (summary {chars} chars)",
+  sessions: "phylacteries ({count}):"
+});
+var LICH_THEME = Object.freeze({
+  name: "lich",
+  agent_name: "lich",
+  glyph: "\u26B1",
+  tagline: "the agent that will not stay dead",
+  welcome: "\u26B1 lich v{version} \u2014 the agent that will not stay dead \xB7 {model} ({kind})",
+  goodbye: "the lich endures",
+  response_label: "lich",
+  user_label: "mortal",
+  phase_labels,
+  notices
+});
+
+// src/util/theme.ts
+var text = z.string().min(1);
+var theme_schema = z.object({
+  name: text,
+  agent_name: text,
+  glyph: text,
+  tagline: text,
+  welcome: text,
+  goodbye: text,
+  response_label: text,
+  user_label: text,
+  phase_labels: z.object({ idle: text, thinking: text, tool: text }),
+  notices: z.object({ budget_exhausted: text, compressed: text, sessions: text })
+});
+function fill_template(template, vars) {
+  let filled = template;
+  for (const [key, value] of Object.entries(vars)) {
+    filled = filled.replaceAll(`{${key}}`, String(value));
+  }
+  return filled;
+}
+function notice_flavor(notice) {
+  const start = notice.indexOf(" \u2014 ");
+  if (start === -1) {
+    return "";
+  }
+  const rest = notice.slice(start + 3);
+  const end = rest.indexOf(" (");
+  return end === -1 ? rest : rest.slice(0, end);
+}
+function load_theme(name, themes_dir) {
+  if (name === "lich" || name.length === 0) {
+    return LICH_THEME;
+  }
+  try {
+    return read_theme_file(name, themes_dir);
+  } catch (error) {
+    logger.warn(`theme '${name}' unavailable; using default lich theme`, error);
+    return LICH_THEME;
+  }
+}
+function read_theme_file(name, themes_dir) {
+  if (path.basename(name) !== name) {
+    throw new Error("invalid theme name");
+  }
+  const root = themes_dir ?? path.join(homedir(), ".lich", "themes");
+  const theme = theme_schema.parse(JSON.parse(readFileSync(path.join(root, `${name}.json`), "utf8")));
+  Object.freeze(theme.phase_labels);
+  Object.freeze(theme.notices);
+  return Object.freeze(theme);
+}
+
+export {
+  fill_template,
+  notice_flavor,
+  load_theme
+};
+//# sourceMappingURL=chunk-JYURFAGB.js.map

package/dist/chunk-JYURFAGB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/util/theme.ts","../src/util/lore.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport path from \"node:path\";\nimport { z } from \"zod\";\nimport { logger } from \"./log.js\";\nimport { LICH_THEME, type ThemeSpec } from \"./lore.js\";\n\nconst text = z.string().min(1);\n\nexport const theme_schema = z.object({\n  name: text, agent_name: text, glyph: text, tagline: text,\n  welcome: text, goodbye: text, response_label: text, user_label: text,\n  phase_labels: z.object({ idle: text, thinking: text, tool: text }),\n  notices: z.object({ budget_exhausted: text, compressed: text, sessions: text }),\n});\n\nexport function fill_template(template: string, vars: Record<string, string | number>): string {\n  let filled = template;\n  for (const [key, value] of Object.entries(vars)) {\n    filled = filled.replaceAll(`{${key}}`, String(value));\n  }\n  return filled;\n}\n\nexport function notice_flavor(notice: string): string {\n  const start = notice.indexOf(\" — \");\n  if (start === -1) {\n    return \"\";\n  }\n  const rest = notice.slice(start + 3);\n  const end = rest.indexOf(\" (\");\n  return end === -1 ? rest : rest.slice(0, end);\n}\n\nexport function load_theme(name: string, themes_dir?: string): ThemeSpec {\n  if (name === \"lich\" || name.length === 0) {\n    return LICH_THEME;\n  }\n  try {\n    return read_theme_file(name, themes_dir);\n  } catch (error) {\n    logger.warn(`theme '${name}' unavailable; using default lich theme`, error);\n    return LICH_THEME;\n  }\n}\n\nfunction read_theme_file(name: string, themes_dir?: string): ThemeSpec {\n  if (path.basename(name) !== name) {\n    throw new Error(\"invalid theme name\");\n  }\n  const root = themes_dir ?? path.join(homedir(), \".lich\", \"themes\");\n  const theme: ThemeSpec = theme_schema.parse(JSON.parse(readFileSync(path.join(root, `${name}.json`), \"utf8\")));\n  Object.freeze(theme.phase_labels);\n  Object.freeze(theme.notices);\n  return Object.freeze(theme);\n}\n","/**\n * Default lich theme as frozen display data. No loader logic here.\n * Mythology stays in these strings; the system prompt stays myth-free.\n */\nexport interface ThemeSpec {\n  readonly name: string;\n  readonly agent_name: string;\n  readonly glyph: string;\n  readonly tagline: string;\n  readonly welcome: string;\n  readonly goodbye: string;\n  readonly response_label: string;\n  readonly user_label: string;\n  readonly phase_labels: {\n    readonly idle: string;\n    readonly thinking: string;\n    readonly tool: string;\n  };\n  readonly notices: {\n    readonly budget_exhausted: string;\n    readonly compressed: string;\n    readonly sessions: string;\n  };\n}\n\nconst phase_labels = Object.freeze({\n  idle: \"dormant\",\n  thinking: \"deliberating\",\n  tool: \"casting\",\n});\n\nconst notices = Object.freeze({\n  budget_exhausted: \"budget exhausted — the ritual is spent (turn cap reached)\",\n  compressed: \"context compressed — memories distilled (summary {chars} chars)\",\n  sessions: \"phylacteries ({count}):\",\n});\n\nexport const LICH_THEME: ThemeSpec = Object.freeze({\n  name: \"lich\",\n  agent_name: \"lich\",\n  glyph: \"⚱\",\n  tagline: \"the agent that will not stay dead\",\n  welcome: \"⚱ lich v{version} — the agent that will not stay dead · {model} ({kind})\",\n  goodbye: \"the lich endures\",\n  response_label: \"lich\",\n  user_label: \"mortal\",\n  phase_labels,\n  notices,\n});\n"],"mappings":";;;;;AAAA,SAAS,oBAAoB;AAC7B,SAAS,eAAe;AACxB,OAAO,UAAU;AACjB,SAAS,SAAS;;;ACsBlB,IAAM,eAAe,OAAO,OAAO;AAAA,EACjC,MAAM;AAAA,EACN,UAAU;AAAA,EACV,MAAM;AACR,CAAC;AAED,IAAM,UAAU,OAAO,OAAO;AAAA,EAC5B,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,UAAU;AACZ,CAAC;AAEM,IAAM,aAAwB,OAAO,OAAO;AAAA,EACjD,MAAM;AAAA,EACN,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,SAAS;AAAA,EACT,SAAS;AAAA,EACT,SAAS;AAAA,EACT,gBAAgB;AAAA,EAChB,YAAY;AAAA,EACZ;AAAA,EACA;AACF,CAAC;;;ADzCD,IAAM,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AAEtB,IAAM,eAAe,EAAE,OAAO;AAAA,EACnC,MAAM;AAAA,EAAM,YAAY;AAAA,EAAM,OAAO;AAAA,EAAM,SAAS;AAAA,EACpD,SAAS;AAAA,EAAM,SAAS;AAAA,EAAM,gBAAgB;AAAA,EAAM,YAAY;AAAA,EAChE,cAAc,EAAE,OAAO,EAAE,MAAM,MAAM,UAAU,MAAM,MAAM,KAAK,CAAC;AAAA,EACjE,SAAS,EAAE,OAAO,EAAE,kBAAkB,MAAM,YAAY,MAAM,UAAU,KAAK,CAAC;AAChF,CAAC;AAEM,SAAS,cAAc,UAAkB,MAA+C;AAC7F,MAAI,SAAS;AACb,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,aAAS,OAAO,WAAW,IAAI,GAAG,KAAK,OAAO,KAAK,CAAC;AAAA,EACtD;AACA,SAAO;AACT;AAEO,SAAS,cAAc,QAAwB;AACpD,QAAM,QAAQ,OAAO,QAAQ,UAAK;AAClC,MAAI,UAAU,IAAI;AAChB,WAAO;AAAA,EACT;AACA,QAAM,OAAO,OAAO,MAAM,QAAQ,CAAC;AACnC,QAAM,MAAM,KAAK,QAAQ,IAAI;AAC7B,SAAO,QAAQ,KAAK,OAAO,KAAK,MAAM,GAAG,GAAG;AAC9C;AAEO,SAAS,WAAW,MAAc,YAAgC;AACvE,MAAI,SAAS,UAAU,KAAK,WAAW,GAAG;AACxC,WAAO;AAAA,EACT;AACA,MAAI;AACF,WAAO,gBAAgB,MAAM,UAAU;AAAA,EACzC,SAAS,OAAO;AACd,WAAO,KAAK,UAAU,IAAI,2CAA2C,KAAK;AAC1E,WAAO;AAAA,EACT;AACF;AAEA,SAAS,gBAAgB,MAAc,YAAgC;AACrE,MAAI,KAAK,SAAS,IAAI,MAAM,MAAM;AAChC,UAAM,IAAI,MAAM,oBAAoB;AAAA,EACtC;AACA,QAAM,OAAO,cAAc,KAAK,KAAK,QAAQ,GAAG,SAAS,QAAQ;AACjE,QAAM,QAAmB,aAAa,MAAM,KAAK,MAAM,aAAa,KAAK,KAAK,MAAM,GAAG,IAAI,OAAO,GAAG,MAAM,CAAC,CAAC;AAC7G,SAAO,OAAO,MAAM,YAAY;AAChC,SAAO,OAAO,MAAM,OAAO;AAC3B,SAAO,OAAO,OAAO,KAAK;AAC5B;","names":[]}