@moikapy/lich 0.3.1 → 0.5.0

package/docs/user-guide/cli.md

@@ -2,22 +2,28 @@
 
 > What you'll learn: every CLI mode, flag, and default; how provider/model resolution works; the config file schema; session files, exit codes, and log levels; and practical recipes.
 
-## The four modes
+## Entry points
 
 ```sh
+lich                   # open the TUI; first run on a TTY starts the setup wizard
+lich init              # write .lich/config.json without the wizard (flags apply; never overwrites)
 lich "one shot task"   # run a single task and print the reply
 lich chat              # interactive chat (commands: /exit, /quit)
 lich tui               # interactive terminal UI (ink)
 lich gateway <plat..>  # messaging gateway (webhook|telegram|discord|twitch)
 lich config            # print a starter config template
+lich update            # install a newer npm release, if one exists
 lich --help            # usage text
 lich --version         # print 0.3.0
 ```
 
+- **Bare `lich`** opens the same TUI as `lich tui`. It does not print usage. On a TTY, if neither `.lich/config.json` nor `~/.config/lich/config.json` exists and `LICH_MODEL` / `--model` is unset, a setup wizard runs first (name, provider, optional gateway env-var names, optional plugins) and writes `.lich/config.json` once. An existing `.lich/config.json` skips the wizard and is not replaced. Non-TTY stdin skips the wizard and prints guidance instead of hanging. `lich --help` still prints usage.
+- **`lich init`** writes that starter file without prompts, using the same writer as the wizard. Existing flags such as `--model` are written into the file and win over `LICH_MODEL`. It never overwrites an existing `.lich/config.json`. `.lich/` is gitignored.
 - **One-shot** joins all positional words into a single task, runs the agent loop, prints the final answer to stdout, and exits. Progress (turn numbers, tool results) goes to stderr.
 - **Chat** is a readline REPL over one long-lived agent: each line is a turn, memory persists across lines, and an empty line, `/exit`, or `/quit` ends the session. After each turn it prints a `[turns N | tokens M]` footer.
 - **TUI** launches the ink interface. See the [TUI guide](tui.md).
 - **Gateway** runs platform adapters (defaults to `webhook` when no platform is given). See the [Gateway guide](gateway.md). Unknown platform names are skipped with a warning; if none remain, the CLI exits `1`.
+- **Update** compares the installed version to the npm registry and, when a newer release exists, runs `npm install -g @moikapy/lich@latest`. Exit any running TUI or gateway first; npm cannot replace the package while those processes are running. A git clone is told to `git pull`. See [Updating](../getting-started.md#updating).
 
 The installed `lich` binary and `bun src/cli.ts` (from a repository clone) accept identical arguments.
 
@@ -105,6 +111,8 @@ Validated by zod (top-level unknown keys are silently stripped; extra keys insid
 | `providers[].timeout_ms` | positive int | none | Per-request abort deadline. |
 | `providers[].think` | boolean | – | Ollama only: request thinking mode. |
 | `providers[].keep_alive` | string | – | Ollama only: model residency (e.g. `"10m"`). |
+| `agent_name` | string | `lich` | Display name in the TUI banner. |
+| `gateway` | object | omitted | Optional. `platforms` (`webhook` \| `telegram` \| `discord` \| `twitch`) and `token_envs` (platform → env-var name). Secrets stay in the environment. |
 | `system_prompt` | string | built-in | Replaces the default system prompt. |
 | `max_turns` | int >= 1 | `25` | Turn budget per run. |
 | `work_dir` | string | cwd | Root for all file tools; paths outside are rejected. |
@@ -129,6 +137,19 @@ Minimal per-provider examples:
 
 Listed providers form a failover chain: the router walks them in order, retrying `rate_limit`/`network` errors (bounded backoff) on the current provider before moving on, and failing over immediately on `auth`, `overflow`, and `bad_request`.
 
+## Self-improvement environment
+
+These are process-env knobs, not config fields. They are assembled in code and
+never accepted as a config passthrough.
+
+| Variable | Meaning |
+| --- | --- |
+| `LICH_ALLOW_SELF_COMMIT` | Set to `1` to allow one gated `git_commit` per run. Unset or any other value is fail-closed. Read at agent construction. |
+| `LICH_TEST_COMMAND` | Command `run_tests` runs in `work_dir` (default `node node_modules/vitest/vitest.mjs run`). An optional `filter` argument is appended. |
+
+Veto reasons, the terminal git denylist, skills, and `MEMORY.md` are in the
+[plugins guide](plugins.md#self-improvement-loop).
+
 ## Session files
 
 Each run writes `.lich/sessions/<timestamp36>-<counter>[-label].jsonl` where the label is the run origin: `-tui`, or `-gw-<platform>-<chat_id>` for gateway conversations. One-shot and chat runs get no label. Records are JSON lines of two kinds: `{"ts","kind":"meta","meta":{...}}` (run start, budget exhaustion) and `{"ts","kind":"message","message":{...}}` for each system/user/assistant/tool message.
@@ -145,8 +166,8 @@ jq -r 'select(.kind=="message") | "\(.message.role): \(.message.content // "(too
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Success: final answer produced (also `--help`, `--version`, `config`). |
-| `1` | Any failure: unknown flag, missing model, unreadable config, provider error after failover, aborted run, or budget exhaustion (`[lich] budget exhausted after N turns` is printed to stderr). |
+| `0` | Success: final answer produced (also `--help`, `--version`, `config`, `init`, and a TUI that exits cleanly). |
+| `1` | Any failure: unknown flag, missing model, unreadable config, provider error after failover, aborted run, budget exhaustion, non-TTY bare `lich`, or a cancelled setup wizard. |
 
 ## Log levels
 

package/docs/user-guide/godot.md

@@ -0,0 +1,160 @@
+# Godot guide
+
+> What you'll learn: how to run lich beside a Godot game — the webhook call, the `game_bridge` plugin path, and the `.lich/game/` files Godot drains. Godot never links lich.
+
+lich is the AI brain in a separate process. Godot speaks HTTP. This page is the recipe; the file contract and tool list live in [`examples/game_bridge/README.md`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/README.md). Plugin authoring is the [plugins guide](plugins.md). Platform setup beyond the webhook is the [gateway guide](gateway.md). A TypeScript game backend that embeds the library uses the [library guide](library.md) — Godot itself does not.
+
+## Architecture
+
+Two tiers:
+
+- **Dialogue.** `lich gateway webhook` plus a `chat_id`. No plugin. The reply text is the line.
+- **Combat commander.** The same webhook, with [`examples/game_bridge/game_bridge.plugin.mjs`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/game_bridge.plugin.mjs) loaded. The model queues a round by calling `enemy_actions`. Godot never parses tool calls out of `reply`; it drains the order file the tool appends.
+
+LLM latency is seconds, not frames. Call lich **once per combat round**, never per frame and never from input-handling logic. Mask the wait in the turn: the enemy commander looks over the field, then the round resolves. Do not start round N+1 for the same `chat_id` until round N's HTTP call has finished — the gateway already serializes that conversation, so an early follow-up only queues behind the slow one.
+
+```mermaid
+flowchart LR
+    A[round start] --> B[optional state.json]
+    B --> C["POST /message"]
+    C --> D[diegetic wait]
+    D --> E[reply or local timeout]
+    E --> F[read orders.jsonl]
+    F --> G[apply, then truncate]
+    G --> H[resolve the round]
+```
+
+A game backend may instead call `run_agent`, which loads `config.plugins`. `create_agent` does not. Godot still reaches that backend over HTTP; it does not import the package.
+
+## Gateway contract
+
+`lich gateway webhook` binds `0.0.0.0` on `LICH_GATEWAY_PORT` (default `8089`). `GET /health` is `200 {"status":"ok"}` — the process is up, not that a provider is healthy. Check it before the first round.
+
+`POST /message`. Only `text` is required. Omitted fields default to `platform` `"webhook"`, `chat_id` `"default"`, `user_id` `"anonymous"`.
+
+```sh
+LICH_GATEWAY_TOKEN=s3cret lich gateway webhook
+```
+
+```sh
+curl -s -X POST http://127.0.0.1:8089/message \
+  -H "x-lich-token: s3cret" -H "content-type: application/json" \
+  -d '{"text":"round 1: hero1 at full. goblin is the only living enemy.","chat_id":"run-1"}'
+```
+
+Success is exactly one JSON object. This endpoint always sends `usage: null` — it does not forward provider token counts:
+
+```json
+{"reply":"...","usage":null}
+```
+
+| Status | Body |
+| --- | --- |
+| `400` | `{"error":"text is required"}` |
+| `401` | `{"error":"unauthorized"}` when `LICH_GATEWAY_TOKEN` is set and `x-lich-token` does not match |
+| `404` | `{"error":"not found"}` for any other method or path |
+| `500` | `{"error":"internal error"}` if the handler throws before a response is sent |
+
+A failed run is still `200`. `reply` is then a sanitized `agent error: ...` line. There is no streaming, pagination, or cursor. Full platform notes: [webhook API](gateway.md#webhook-api-reference).
+
+Memory is keyed `platform:chat_id`, capped at 40 messages (oldest dropped) and 200 conversations (oldest dropped). For a roguelike, `chat_id` = the run id gives the commander that process's memory of the run. A new run id starts a fresh history. That history is in memory only — restarting the gateway clears it. Restate facts the digest still needs. Durable notes are a different file, below.
+
+## Wire the example plugin
+
+Node `>=20` loads the `.mjs` entry. Restart to reload; there is no hot reload. Paths in `config.plugins` are relative to `work_dir`.
+
+If `work_dir` is the lich checkout:
+
+```json
+{
+  "plugins": ["./examples/game_bridge/game_bridge.plugin.mjs"]
+}
+```
+
+If `work_dir` is the game repo, copy the `examples/game_bridge/` folder into that repo and point `plugins` at the copy the same way. Restart the gateway (or whichever entry you use) after changing the list. The gateway loads plugins; a config entry is not ignored.
+
+The prompt `text` is yours. The plugin does not parse it. Put the battle digest there — party, living enemies, kits, last round — as plain text or as JSON inside the string.
+
+## Dialogue autoload
+
+Sketch only. The game repo owns the real autoload. One `HTTPRequest` per in-flight call; `CONNECT_ONE_SHOT` so two speakers do not share a callback. Set `timeout` yourself (Godot's `0` means no timeout). On timeout, non-200, or a body that is not the object above, emit your own fallback and resolve the beat. Do not wait on the frame path.
+
+```gdscript
+# Sketch — not shipped as a Godot project in this repo.
+extends Node
+signal reply_received(text: String)
+var request: HTTPRequest
+
+func _ready() -> void:
+	request = HTTPRequest.new()
+	request.timeout = 45.0
+	add_child(request)
+
+func ask(chat_id: String, text: String, token: String) -> void:
+	var body := JSON.stringify({"text": text, "chat_id": chat_id})
+	var headers := PackedStringArray([
+		"Content-Type: application/json", "x-lich-token: %s" % token
+	])
+	request.request_completed.connect(_on_done, CONNECT_ONE_SHOT)
+	request.request(
+		"http://127.0.0.1:8089/message", headers, HTTPClient.METHOD_POST, body
+	)
+
+func _on_done(result: int, code: int, _headers: PackedStringArray, raw: PackedByteArray) -> void:
+	var reply := ""
+	if result == HTTPRequest.RESULT_SUCCESS and code == 200:
+		var parsed: Variant = JSON.parse_string(raw.get_string_from_utf8())
+		if parsed is Dictionary:
+			reply = str(parsed.get("reply", ""))
+	reply_received.emit(reply)
+```
+
+## Combat tick
+
+Godot, each tick, against files under `work_dir/.lich/game/` — not `res://` unless that directory is `work_dir`:
+
+1. Read `orders.jsonl`.
+2. Apply the lines.
+3. Truncate the file. Read then truncate; do not rewrite lines in place.
+4. Optionally refresh `state.json` with the current snapshot (`round`, hero ids, enemy ids).
+
+Append-only writes keep a drain race from corrupting a line. A line appended during truncate can still be lost; drain under the game's own lock if that matters. The first call creates `.lich/game/` if it is missing.
+
+`enemy_actions` appends one JSONL line and echoes the action count (`appended 2 orders for round 1`). An order line:
+
+```json
+{"ts":"2026-01-01T00:00:00.000Z","round":1,"actions":[{"enemy_id":"goblin","action":"attack","target_ref":"hero:hero1"}],"rationale":"open with a strike"}
+```
+
+`action` is an ability id from that enemy's kit, or `attack`, `defend`, or `flee`. `target_ref` is `hero:<id>` or `enemy:<id>`. `rationale` is the combat-log line. One call per round is the intended cadence. The plugin does not stop a second call.
+
+`state.json` is written by Godot and read when `enemy_actions` runs. The plugin compares `round` only:
+
+```json
+{"round":1,"heroes":[{"id":"hero1"}],"enemies":[{"id":"goblin"}]}
+```
+
+A round that does not match is still appended. Tool output then includes `snapshot_round_mismatch: snapshot=<n>`. A missing or unreadable snapshot is ignored. Refresh `state.json` before the POST if that comparison should see this round; the tick's optional refresh is for the next read.
+
+`dungeon_memory_write` / `dungeon_memory_read` are a separate append-only `memory.jsonl` (read returns the latest 20 notes, or `(none)`). That is not the combat queue. Do not drain it as orders. Shape and failure strings: [`examples/game_bridge/README.md`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/README.md).
+
+The plugin checks the line shape and returns `{ok: false, error}` instead of throwing. It does not know your units. Unknown ids, dead units, abilities outside a kit, whether a boss may `flee`, and duplicate lines for one round stay in the game. `flee` is a valid literal even in a boss fight. Drain even when `reply` looks fine — the model may never have called the tool, or it may have called it twice.
+
+## Meteor gate
+
+`before_tool_call` vetoes `enemy_actions` when any `action` string contains `meteor` and `round` is below 3. The executor does not run, so no line is written. The model sees `blocked_by_plugin: meteor_gates_closed_until_round_3` as an error tool result and can call again in the same run. Round 3 and later are not vetoed. That is the whole gate — one hardcoded check, not a table of encounter caps.
+
+## Security
+
+Set `LICH_GATEWAY_TOKEN`. The webhook binds all interfaces, so an open port is an open chatbot with your provider keys and your tools. Mismatch or a missing header is `401`.
+
+Players' Godot clients do not talk to lich in production. Godot talks to your backend; the backend holds the token, sets `chat_id` / `user_id`, and rate-limits. Same split as embedding the library in that backend.
+
+Plugins run in-process with the agent's privileges (files, network, environment). Load only plugins you wrote or audited. The order file is the crossing into the game, and the game still applies its own rules to every line.
+
+## Limits
+
+- A long run evicts gateway history past 40 messages. Put habits that still matter in the digest, or in `memory.jsonl` if they must survive a restart.
+- More than 200 concurrent `chat_id`s on one process drops the oldest conversation. Fine for one developer machine; a host of many runs should know the cap.
+- Combat must finish if the gateway is down, the call times out, or `orders.jsonl` is empty or garbage. The game's fallback is the game's — this repo does not ship one.
+- Same-`chat_id` calls run one after another. Different `chat_id`s run concurrently. The plugin itself makes no concurrency guarantee; one bridge per `chat_id` is the intended pattern.

package/docs/user-guide/library.md

@@ -34,7 +34,7 @@ console.log(result.outcome.final?.content);
 console.log(`tokens: ${result.usage_total.total_tokens}`);
 ```
 
-The one-liner `run_agent(config, input)` is equivalent when you only need a single run:
+`run_agent(config, input)` loads `config.plugins`, then runs once. `create_agent` does not load plugins.
 
 ```ts
 import { run_agent } from "@moikapy/lich";
@@ -47,7 +47,7 @@ const result = await run_agent(
 
 ## Agent class
 
-`new Agent(config)` (or `create_agent(raw)`) builds the provider router, registers the twelve builtin tools (filtered by `tools_enabled`), and exposes:
+`new Agent(config)` (or `create_agent(raw)`) builds the provider router, registers the builtin tools (filtered by `tools_enabled`) plus the gatekeeper's `git_commit`, and exposes:
 
 | Member | Type | Purpose |
 | --- | --- | --- |
@@ -141,6 +141,8 @@ const config = {
 
 Listed providers form a failover chain tried in order: `rate_limit`/`network` errors retry with backoff (3 attempts) on the current provider before failing over; `auth`, `overflow`, and `bad_request` fail over immediately. The last error is rethrown when all providers fail.
 
+`LICH_ALLOW_SELF_COMMIT` and `LICH_TEST_COMMAND` are process-env knobs, not config fields. See the [CLI environment](cli.md#self-improvement-environment).
+
 ## Custom tool filtering
 
 `tools_enabled` accepts `"all"` (default) or an array of builtin tool names to register; everything else stays unregistered and invisible to the model:

package/docs/user-guide/plugins.md

@@ -47,11 +47,11 @@ All hooks are awaited. Hook errors are logged as warnings and skipped — a brok
 | Hook | Signature | Purpose |
 | --- | --- | --- |
 | `before_tool_call` | `(info: {tool_name, args}, ctx) => {block?: boolean, reason?: string} \| void` | Runs before each tool call in plugin registration order. Return `{block: true, reason}` to veto. |
-| `after_tool_call` | `(info: {tool_name, args, result_summary}, ctx) => void` | Runs after each tool call with a 300-char result summary. |
+| `after_tool_call` | `(info: {tool_name, args, result_summary, ok, error?}, ctx) => void` | Runs after each tool call with a 300-char summary plus structured `ok`/`error`. |
 | `on_run_start` | `(info: {input_chars}, ctx) => void` | Runs once before the conversation loop starts. |
 | `on_run_end` | `(info: {stopped_reason, turns_used}, ctx) => void` | Runs once after the loop ends with the outcome. |
 
-`ctx` is `{work_dir: string}` — the agent's working directory.
+`ctx` is `{work_dir, state?}` — the agent's working directory plus that plugin's per-run bag.
 
 ## Tool authoring
 
@@ -112,9 +112,83 @@ Failures are contained at every layer:
 
 ## Runtime notes
 
-- **Bun** runs TypeScript plugin files natively — `.ts` entries just work (`bun src/cli.ts ...` from a clone).
-- **Node** (the built `dist/cli.js`) uses the native ESM loader, which does not compile TS. For node deployments, compile your plugin or ship it as `.mjs`/plain JS and list that file in `plugins`.
+`package.json` `engines.node` is `>=20`. The CLI loads `config.plugins` before the run. A broken entry logs one `plugin load errors` warning and the run continues without that plugin.
+
+`.mjs` and other plain JS (no type syntax) are the form that matches `engines.node` `>=20`. They load on Node and on Bun with no plugin-load warning.
+
+Checked with Node 26.8.2 (`node dist/cli.js`) and Bun 1.3.14 (`bun src/cli.ts`):
+
+- Erasable `.ts` (`import type`, annotations) loads under `node dist/cli.js` only where Node strips types by default (22.18+, 23.6+, 24+, 26). Node 22.18's disable flag is `--no-experimental-strip-types`. Bun 1.3.14 loads that same file with no plugin-load warning. The Node 26.8.2 check type-strips by default and does not bundle. `node --no-strip-types` warns (`Unknown file extension ".ts"`) and continues.
+- On Node 20 and Node 22 before 22.18, a `.ts` entry still warns and the run continues without that plugin.
+- Syntax Node cannot strip (for example `enum`) warns and continues. Bun runs that same file with no plugin-load warning. A syntax error warns on both and the run continues.
+
+The combat-commander reference is `examples/game_bridge/game_bridge.plugin.mjs`. Point `config.plugins` at `./examples/game_bridge/game_bridge.plugin.mjs` (relative to `work_dir`). See `examples/game_bridge/README.md`. Embedding it beside a Godot game: [Godot guide](godot.md).
+
+Plain JS (matches `engines.node` `>=20`):
+
+```mjs
+// .lich/plugins/my-plugin.mjs
+const my_plugin = {
+  name: "my-plugin",
+  tools: [],
+};
+
+export default my_plugin;
+```
+
+## Self-improvement loop
+
+The agent can write a tool, prove it with `run_tests`, and commit it with
+`git_commit` — one commit per run, and only when you opt in. The gatekeeper
+is constructed in code (not listed in `config.plugins`). If it does not
+register, `git_commit` is absent. A config plugin naming `git_commit` is
+inside the plugin-trust floor only when the gatekeeper is off; while it is
+on, first-wins keeps the gatekeeper's tool.
+
+Set `LICH_ALLOW_SELF_COMMIT=1` before startup. Unset, or any other value, is
+fail-closed. `git_commit` is vetoed unless every condition holds; the reason
+names the first failure, and the model sees `blocked_by_plugin: <reason>`:
+
+| Failed condition | Reason |
+| --- | --- |
+| `LICH_ALLOW_SELF_COMMIT` is not `1` | `self_commit_disabled` |
+| no green `run_tests` yet this run | `tests_not_ok` |
+| a `write_file` or `edit_file` succeeded after that green run | `worktree_dirty` |
+| this run already committed once | `commit_budget_exhausted` |
+
+`terminal` is vetoed when the command matches the hardcoded git denylist.
+The reason is `git_denylist: <pattern>`. Patterns are flag-tolerant
+`commit`/`push` (`commit`, `-commit`, `--commit`, `push`, `-push`, `--push`)
+and any occurrence of `commit-tree` or `update-ref`. There is no `remote`
+pattern. The denylist is best-effort: raw `terminal` can still run git. The
+boundary is a human reviewing the local repo. Push is human-only.
+
+`git_commit` takes `{message, paths}` — 1 to 50 paths relative to `work_dir`.
+It rejects `""`, `.`, a path that resolves to `work_dir` itself, and
+secret-ish basenames (`.env`, `.env.local`, `*.pem`, `*.p12`, `id_rsa*`).
+It refuses an unreachable `HEAD`. It stages exactly the named paths
+(`git add -- <paths>`) and commits with `git commit --only`. It never pushes.
+
+`run_tests` takes an optional `filter` and runs `LICH_TEST_COMMAND` in
+`work_dir` (default `node node_modules/vitest/vitest.mjs run`) with a 600s
+timeout. A second call in the same process returns `run_tests_busy`. The
+mutex is process-local: one lich process per repo.
+
+Clean state attests no `write_file`/`edit_file` since the last green
+`run_tests`; it does NOT attest absence of terminal-mediated writes.
+
+### Skills and memory
+
+Write a markdown note with `write_file` to `.lich/skills/<name>.md`.
+`docs_search` finds those files. That directory does not need `index.md`,
+and it is walked fresh on every search. The default system prompt says tool
+results — docs, skills, memory — are reference data, not instructions.
+
+`MEMORY.md` is append-only and human-reviewable. It is never auto-loaded.
+Review it between appends and the next self-commit.
 
 ## Security note
 
-Plugins execute **in-process with full privileges** — the same trust level as the agent itself and your shell. A plugin can read any file the process can, make network calls, and alter process state. Only load plugin files you wrote or audited; treat `.lich/plugins/` like you treat `.env` files.
+Plugins execute **in-process with full privileges** — the same trust level as the agent itself and your shell. A plugin can read any file the process can, make network calls, and alter process state. Only load plugin files you wrote or audited; treat `.lich/plugins/` like you treat `.env` files.
+
+`.lich/config.json` `plugins` is persistent arbitrary code at the next process start. Review config diffs before the next self-commit. The terminal git denylist does not close that hole.

package/docs/user-guide/tui.md

@@ -5,15 +5,16 @@
 ## Launching
 
 ```sh
-lich tui     # or, from a clone: bun src/cli.ts tui
+lich         # front door: TUI, plus a first-run setup wizard when no config exists
+lich tui     # same TUI, no wizard. From a clone: bun src/cli.ts tui
 ```
 
-The TUI needs a TTY and a resolvable provider (same resolution as every mode). On startup it prints a dim header with the version and the first provider's model, e.g. `lich v0.3.0 — llama3.2 (ollama)`. Quit with `/exit`, `/quit`, `/q`, or Ctrl+C.
+The TUI needs a TTY and a resolvable provider (same resolution as every mode). On startup it prints a dim header with `agent_name` (default `lich`), the version, and the first provider's model, e.g. `lich v0.3.0 — llama3.2 (ollama)`. Quit with `/exit`, `/quit`, `/q`, or Ctrl+C.
 
 ## Anatomy
 
 ```
-lich v0.3.0 — llama3.2 (ollama)        <- header: version, model, provider kind
+lich v0.3.0 — llama3.2 (ollama)        <- header: agent_name (default lich), version, model, kind
 you › list the files here              <- your input, echoed into the transcript
 ⏺ list_dir({})                        <- live tool-call row (name + args preview)
   ⏷ list_dir: ok (d src/ d test/ ...)  <- result row (ok/error + output preview)

package/examples/game_bridge/README.md

@@ -0,0 +1,68 @@
+# game_bridge
+
+Reference plugin: a lich agent queues Final-Fantasy-style enemy turns for a Godot process. lich and Godot do not share memory. Tools write files under `.lich/game/`; Godot drains them each tick. Godot-side code lives in the game repo.
+
+Node `>=20` loads this entry. Point `config.plugins` at the `.mjs` file (paths are relative to `work_dir`):
+
+```json
+{
+  "plugins": ["./examples/game_bridge/game_bridge.plugin.mjs"]
+}
+```
+
+Restart the agent after changing the list. There is no hot reload. Copy this folder into the game repo if `work_dir` is not the lich checkout, and point `plugins` at that copy the same way.
+
+## Round cadence
+
+One `enemy_actions` call per combat round decides every enemy. The gateway serializes runs per conversation, so one bridge per `chat_id` is the intended pattern. The plugin itself makes no concurrency guarantee.
+
+Godot, each tick:
+
+1. Read `.lich/game/orders.jsonl`.
+2. Apply the lines.
+3. Truncate the file (read + truncate; do not rewrite lines in place).
+4. Optionally refresh `.lich/game/state.json` with the current battle snapshot (`round`, hero ids, enemy ids).
+
+Append-only writes keep a drain race from corrupting a line. A line appended during truncate can still be lost; Godot should drain under its own lock if that matters. Duplicate lines for one round are possible if the model calls twice. Dedupe on the Godot side.
+
+`rationale` is the replayable combat-log entry. The agent session JSONL already stores tool-call arguments, so the rationale is in that transcript. This plugin does not write the session store.
+
+## Tools
+
+| Tool | Effect |
+| --- | --- |
+| `enemy_actions` | Appends one JSONL order line to `.lich/game/orders.jsonl`. Output echoes the appended action count. |
+| `dungeon_memory_write` | Appends one note to `.lich/game/memory.jsonl`. |
+| `dungeon_memory_read` | Returns the most recent 20 notes, joined by newlines. Empty memory returns `(none)`. |
+
+`action` is an ability id from that enemy's kit, or one of `attack`, `defend`, `flee`. `target_ref` is `hero:<id>` or `enemy:<id>`. `flee` is a valid literal even in a boss fight; Godot decides whether it is allowed.
+
+## File contract
+
+Order line (`orders.jsonl`):
+
+```json
+{"ts":"2026-01-01T00:00:00.000Z","round":1,"actions":[{"enemy_id":"goblin","action":"attack","target_ref":"hero:hero1"}],"rationale":"open with a strike"}
+```
+
+Memory line (`memory.jsonl`):
+
+```json
+{"ts":"2026-01-01T00:00:00.000Z","note":"the player always heals below half"}
+```
+
+Snapshot (`state.json`, written by Godot, read by `enemy_actions`):
+
+```json
+{"round":1,"heroes":[{"id":"hero1"}],"enemies":[{"id":"goblin"}]}
+```
+
+A round that does not match `state.json` is still appended. The tool output then includes `snapshot_round_mismatch: snapshot=<n>`. A missing or unreadable snapshot is ignored.
+
+## Difficulty gate
+
+`before_tool_call` blocks `enemy_actions` when any `action` contains `meteor` and `round` is below 3. The model sees `blocked_by_plugin: meteor_gates_closed_until_round_3` and re-plans in the same run. Round 3 and later pass through. The executor never runs on a blocked call, so no order line is written.
+
+## Failures
+
+Tools return `{ok: false, error}` and do not throw. Reads skip malformed JSONL lines. The first call creates `.lich/game/` if it is missing. `memory.jsonl` grows forever; only the read is capped.

package/examples/game_bridge/bridge_io.mjs

@@ -0,0 +1,60 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export function tool_failure(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return { ok: false, output: "", error: message };
+}
+
+export async function ensure_game_dir(work_dir) {
+  await mkdir(path.join(work_dir, ".lich", "game"), { recursive: true });
+}
+
+export async function append_jsonl(file_path, record) {
+  let line;
+  try {
+    line = JSON.stringify(record);
+  } catch (error) {
+    return tool_failure(error);
+  }
+  await appendFile(file_path, `${line}\n`, "utf8");
+  return { ok: true };
+}
+
+export async function read_jsonl_records(file_path) {
+  let raw = "";
+  try {
+    raw = await readFile(file_path, "utf8");
+  } catch (error) {
+    if (is_missing(error) === true) {
+      return [];
+    }
+    throw error;
+  }
+  const records = [];
+  for (const line of raw.split("\n")) {
+    const parsed = parse_line(line);
+    if (parsed !== undefined) {
+      records.push(parsed);
+    }
+  }
+  return records;
+}
+
+function parse_line(line) {
+  if (line.length === 0) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(line);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return undefined;
+    }
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+function is_missing(error) {
+  return typeof error === "object" && error !== null && error.code === "ENOENT";
+}

package/examples/game_bridge/bridge_paths.mjs

@@ -0,0 +1,11 @@
+import path from "node:path";
+
+export const ORDERS_FILE = "orders.jsonl";
+export const MEMORY_FILE = "memory.jsonl";
+export const STATE_FILE = "state.json";
+/** Most recent notes returned by dungeon_memory_read; writes stay append-only. */
+export const MEMORY_READ_LIMIT = 20;
+
+export function game_file(work_dir, file_name) {
+  return path.join(work_dir, ".lich", "game", file_name);
+}

package/examples/game_bridge/dungeon_memory.mjs

@@ -0,0 +1,56 @@
+import { append_jsonl, ensure_game_dir, read_jsonl_records, tool_failure } from "./bridge_io.mjs";
+import { MEMORY_FILE, MEMORY_READ_LIMIT, game_file } from "./bridge_paths.mjs";
+import { dungeon_memory_read_schema, dungeon_memory_write_schema } from "./schemas.mjs";
+
+export const dungeon_memory_read_tool = {
+  name: "dungeon_memory_read",
+  description: "Read the most recent durable cross-run notes about the player.",
+  parameters: dungeon_memory_read_schema,
+  execute: read_memory,
+};
+
+export const dungeon_memory_write_tool = {
+  name: "dungeon_memory_write",
+  description: "Append one durable cross-run observation about the player.",
+  parameters: dungeon_memory_write_schema,
+  execute: write_memory,
+};
+
+async function read_memory(_args, context) {
+  try {
+    const records = await read_jsonl_records(game_file(context.work_dir, MEMORY_FILE));
+    const notes = recent_notes(records);
+    return { ok: true, output: notes.length > 0 ? notes.join("\n") : "(none)" };
+  } catch (error) {
+    return tool_failure(error);
+  }
+}
+
+async function write_memory(args, context) {
+  if (typeof args.note !== "string" || args.note.length === 0) {
+    return { ok: false, output: "", error: "note_required" };
+  }
+  try {
+    await ensure_game_dir(context.work_dir);
+    const written = await append_jsonl(game_file(context.work_dir, MEMORY_FILE), {
+      ts: new Date().toISOString(),
+      note: args.note,
+    });
+    if (written.ok === false) {
+      return { ok: false, output: "", error: written.error };
+    }
+    return { ok: true, output: "appended 1 note" };
+  } catch (error) {
+    return tool_failure(error);
+  }
+}
+
+function recent_notes(records) {
+  const notes = [];
+  for (const record of records) {
+    if (typeof record.note === "string") {
+      notes.push(record.note);
+    }
+  }
+  return notes.slice(-MEMORY_READ_LIMIT);
+}

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;