@moikapy/lich 0.3.0 → 0.4.0

package/docs/user-guide/gateway.md

@@ -19,10 +19,10 @@ flowchart LR
 Platforms: `webhook` (HTTP server), `telegram` (long-poll), `discord` (gateway WebSocket), `twitch` (IRC over WebSocket). Pick any combination:
 
 ```sh
-bun src/cli.ts gateway webhook                 # http only
-bun src/cli.ts gateway webhook telegram        # http + telegram polling
-bun src/cli.ts gateway telegram discord twitch # no webhook server
-bun src/cli.ts gateway                         # defaults to webhook
+lich gateway webhook                 # http only
+lich gateway webhook telegram        # http + telegram polling
+lich gateway telegram discord twitch # no webhook server
+lich gateway                         # defaults to webhook
 ```
 
 The gateway is silent after startup: Telegram/Discord/Twitch respond only in chats, channels, or servers the bot can see or has joined, and the webhook only serves HTTP. Telegram media messages arrive as the placeholder text `media not supported yet`; other non-text events are ignored. Telegram `/start` is answered like a plain "hello".
@@ -32,7 +32,7 @@ The gateway is silent after startup: Telegram/Discord/Twitch respond only in cha
 Zero configuration — the server binds `0.0.0.0:$LICH_GATEWAY_PORT` (default 8089).
 
 ```sh
-bun src/cli.ts gateway webhook
+lich gateway webhook
 ```
 
 ```sh
@@ -47,7 +47,7 @@ curl -s http://localhost:8089/health
 With token auth, every POST must carry the exact `x-lich-token` header; mismatched or missing tokens get `401 {"error":"unauthorized"}`:
 
 ```sh
-LICH_GATEWAY_TOKEN=s3cret bun src/cli.ts gateway webhook
+LICH_GATEWAY_TOKEN=s3cret lich gateway webhook
 curl -s -X POST http://localhost:8089/message \
   -H "x-lich-token: s3cret" -H "content-type: application/json" -d '{"text": "hello"}'
 ```
@@ -61,7 +61,7 @@ Payload fields (all optional except `text`): `platform` (default `"webhook"`), `
 
 ```sh
 export LICH_TELEGRAM_BOT_TOKEN=123456:ABC-your-token
-bun src/cli.ts gateway telegram
+lich gateway telegram
 ```
 
 3. Open your bot in Telegram, send a message, get a reply. Media messages arrive as the text `media not supported yet`; the bot replies from there.
@@ -78,7 +78,7 @@ Telegram uses long polling (no public URL needed). Replies split at 4096 chars.
 ```sh
 export LICH_DISCORD_BOT_TOKEN=your-bot-token
 export LICH_DISCORD_BOT_ID=123456789012345678
-bun src.cli.ts gateway discord
+lich gateway discord
 ```
 
 5. Send the bot a message (DM or any channel it can read — every non-bot message gets a reply); each channel has its own conversation memory (keyed by `channel_id`). Replies split at 2000 chars. Bot-authored messages are ignored (no loops).
@@ -94,7 +94,7 @@ bun src.cli.ts gateway discord
 export LICH_TWITCH_OAUTH_TOKEN=oauth:abc123...
 export LICH_TWITCH_NICK=mylichbot
 export LICH_TWITCH_CHANNELS=channelone,channeltwo
-bun src/cli.ts gateway twitch
+lich gateway twitch
 ```
 
 3. The bot joins `#channelone` and `#channeltwo` and replies in chat (own messages are ignored). Replies split at 512 chars; IRC PING/PONG is answered automatically.
@@ -107,7 +107,7 @@ List the platforms in one command; all configured adapters start together and sh
 
 ```sh
 LICH_TELEGRAM_BOT_TOKEN=... LICH_DISCORD_BOT_TOKEN=... \
-  bun src/cli.ts gateway webhook telegram discord
+  lich gateway webhook telegram discord
 ```
 
 Adapters whose credentials are missing start **idle** (a warning is logged, e.g. `gateway discord adapter idle: LICH_DISCORD_BOT_TOKEN not set`) and the rest keep running — so the same command works on machines with partial credentials. If no platform name is valid, the CLI exits `1` with `gateway needs at least one valid platform`.

package/docs/user-guide/library.md

@@ -4,12 +4,16 @@
 
 ## Install
 
-From a checkout of this repository (or a published tarball):
+```sh
+npm install @moikapy/lich
+```
+
+From source instead (`dist/` is not committed, so build first — see [development install](../getting-started.md#development-install-from-source)):
 
 ```sh
-npm install /path/to/lich-0.2.0.tgz    # after `npm run build` in the lich repo
-# or point package.json at the git repo
-npm install git+ssh://example.com/you/lich.git
+git clone https://github.com/Moikapy/lich.git && cd lich
+bun install && bun run build
+# then, from your project: npm install <path-to>/lich
 ```
 
 The package ships ESM (`dist/index.js`, types at `dist/index.d.ts`, binary at `dist/cli.js`); `main`/`types`/`bin` are wired in `package.json`.
@@ -19,7 +23,7 @@ The package ships ESM (`dist/index.js`, types at `dist/index.d.ts`, binary at `d
 `create_agent(raw_config)` validates the config (zod, defaults applied, frozen result) and returns an `Agent` with a `.run()` loop:
 
 ```ts
-import { create_agent } from "lich";
+import { create_agent } from "@moikapy/lich";
 
 const agent = create_agent({
   providers: [{ kind: "ollama", name: "local", model: "llama3.2:latest" }],
@@ -33,7 +37,7 @@ console.log(`tokens: ${result.usage_total.total_tokens}`);
 The one-liner `run_agent(config, input)` is equivalent when you only need a single run:
 
 ```ts
-import { run_agent } from "lich";
+import { run_agent } from "@moikapy/lich";
 
 const result = await run_agent(
   { providers: [{ kind: "ollama", name: "local", model: "llama3.2:latest" }] },
@@ -43,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 |
 | --- | --- | --- |
@@ -137,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:
@@ -162,7 +168,7 @@ Provider failures throw `ProviderError`, an `Error` subclass with `kind`, `provi
 | `unknown` | Non-provider errors (e.g. tool crashes surfaced as strings). | Treated as fatal for the provider. |
 
 ```ts
-import { ProviderError } from "lich";
+import { ProviderError } from "@moikapy/lich";
 
 try {
   await agent.run({ input: "hello" });
@@ -178,4 +184,4 @@ When every configured provider fails, the last `ProviderError` is thrown. Tool f
 
 ## Session access
 
-Each `run()` appends a transcript line-by-line under `config.session_dir` (default `<work_dir>/.lich/sessions`); `result.session_path` gives the exact file. Records carry `{ts, kind: "message"|"meta", message?, meta?}`; read them with `jq` or the exported `read_session_messages(path)` helper from `src/session/store.ts`. Persistence is best-effort: a write failure logs a warning, returns `session_path: undefined`, and never fails the run.
+Each `run()` appends a transcript line-by-line under `config.session_dir` (default `<work_dir>/.lich/sessions`); `result.session_path` gives the exact file. Records carry `{ts, kind: "message"|"meta", message?, meta?}`; read them with `jq` (or the `read_session_messages(path)` helper if you are working from a source checkout). Persistence is best-effort: a write failure logs a warning, returns `session_path: undefined`, and never fails the run.

package/docs/user-guide/plugins.md

@@ -14,7 +14,7 @@ Create the plugin module (defaults to `.lich/plugins/`, but any path works):
 
 ```ts
 // .lich/plugins/my-plugin.ts
-import type { Plugin } from "lich";
+import type { Plugin } from "@moikapy/lich";
 
 const my_plugin: Plugin = {
   name: "my-plugin",
@@ -47,18 +47,18 @@ 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
 
 Plugin tools implement the same `Tool` interface as builtins: a `name`, a `description` the model reads, a JSON Schema `parameters` object, and an async `execute(args, context)` returning `{ok, output, error?}`:
 
 ```ts
-import type { Plugin, Tool } from "lich";
+import type { Plugin, Tool } from "@moikapy/lich";
 
 const upper_tool: Tool = {
   name: "upper_case",
@@ -112,9 +112,62 @@ Failures are contained at every layer:
 
 ## Runtime notes
 
-- **Bun** runs TypeScript plugin files natively — `.ts` entries just work (`bun src/cli.ts ...`).
+- **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`.
 
+## 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,15 @@
 ## Launching
 
 ```sh
-bun src/cli.ts tui     # or: lich tui
+lich tui     # or, 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.2.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 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.2.0 — llama3.2 (ollama)        <- header: version, model, provider kind
+lich v0.3.0 — llama3.2 (ollama)        <- header: version, model, provider 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moikapy/lich",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Lich — a TypeScript AI agent harness (library + CLI) inspired by Hermes",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,8 @@
     "test": "node node_modules/vitest/vitest.mjs run",
     "test:watch": "node node_modules/vitest/vitest.mjs",
     "cli": "bun src/cli.ts",
+    "release": "bun scripts/release.ts",
+    "release:package": "bun scripts/release.ts",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
@@ -51,4 +53,4 @@
     "vitest": "^3.0.0",
     "vitepress": "^1.6.4"
   }
-}
+}