@moikapy/lich 0.3.0

package/docs/user-guide/plugins.md

@@ -0,0 +1,120 @@
+# Plugins
+
+> What you'll learn: how to extend lich with your own tools and lifecycle hooks — a quickstart, the full hook reference, tool authoring, blocking semantics, error isolation, naming rules, and security notes.
+
+## What plugins are
+
+A plugin is a plain TypeScript (or JavaScript) module you keep in your repo that exports a `Plugin` object: a unique `name`, optional `tools` to merge into the agent's registry, and optional `hooks` that observe (and can veto) tool calls and run lifecycle events. Plugins load at agent startup from explicit paths listed in your config — no installation step, no registry service, just files you control.
+
+Plugins are inspired by [Hermes](https://github.com/NousResearch/Hermes-Function-calling) style customization: the harness stays small; your repo grows around it.
+
+## Quickstart
+
+Create the plugin module (defaults to `.lich/plugins/`, but any path works):
+
+```ts
+// .lich/plugins/my-plugin.ts
+import type { Plugin } from "lich";
+
+const my_plugin: Plugin = {
+  name: "my-plugin",
+  tools: [],
+  hooks: {
+    on_run_start: async (_info, ctx) => {
+      console.log(`run starting in ${ctx.work_dir}`);
+    },
+  },
+};
+
+export default my_plugin;
+```
+
+Point your config at it and restart:
+
+```json
+{
+  "providers": [ ... ],
+  "plugins": ["./.lich/plugins/my-plugin.ts"]
+}
+```
+
+Entry paths are relative to `work_dir` (or absolute). Restarting the agent reloads plugins — there is no hot reload.
+
+## Hook reference
+
+All hooks are awaited. Hook errors are logged as warnings and skipped — a broken hook never breaks the run.
+
+| 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. |
+| `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.
+
+## 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";
+
+const upper_tool: Tool = {
+  name: "upper_case",
+  description: "Uppercase a short piece of text.",
+  parameters: {
+    type: "object",
+    properties: {
+      text: { type: "string", description: "Text to uppercase" },
+    },
+    required: ["text"],
+    additionalProperties: false,
+  },
+  execute: async (args, context) => {
+    const text = typeof args.text === "string" ? args.text : "";
+    return { ok: true, output: text.toUpperCase() };
+  },
+};
+
+export const upper_case_plugin: Plugin = {
+  name: "upper-case",
+  tools: [upper_tool],
+};
+```
+
+Guidelines:
+
+- `name` must be unique across builtins and all plugins; duplicates are warned and skipped at registration.
+- Keep `description` crisp — the model chooses tools from it.
+- Tool failures return `{ok: false, error}` rather than throwing; the loop turns that into an error tool message the model can react to.
+
+## before_tool_call blocking semantics
+
+Hooks run in plugin registration order (config array order). The **first hook to return `{block: true}` wins**; later hooks do not run for that call and the real executor is never invoked. The model receives a tool message with error `blocked_by_plugin: <reason>` (or `blocked_by_plugin: plugin-less` when no reason is given) and can adapt, end the run, or try another approach. Non-blocking return values (including `undefined`) fall through to the next hook.
+
+Blocking is observe-then-veto, not middleware: you cannot rewrite `args` or the result, only allow or veto. This keeps v1 semantics predictable.
+
+## Error isolation
+
+Failures are contained at every layer:
+
+- **Broken import** (missing file, syntax error, missing export): the loader records the entry as an error, logs one warning with `plugin_errors_summary`, and starts the agent without that plugin.
+- **Duplicate plugin names**: later duplicates become error entries; the first registration wins.
+- **Throwing hook**: logged as a warning; the run continues as if the hook did not exist.
+- **Throwing tool**: the executor captures it and returns `{ok: false, error}` to the loop.
+
+## Naming rules
+
+- `plugin.name` is required, must be a non-empty string, and must be unique per agent.
+- Tool `name`s share one namespace with builtin tools — pick a prefix unique to your plugin (e.g. `mycorp_`).
+- Entry modules must have a module extension (`.ts`, `.js`, `.mjs`, `.mts`, `.cts`, `.jsx`, `.tsx`).
+
+## Runtime notes
+
+- **Bun** runs TypeScript plugin files natively — `.ts` entries just work (`bun src/cli.ts ...`).
+- **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`.
+
+## 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.

package/docs/user-guide/tui.md

@@ -0,0 +1,76 @@
+# TUI guide
+
+> What you'll learn: how to launch the terminal UI, read its layout and status bar, use slash commands and input history, and how memory and session persistence work across turns.
+
+## Launching
+
+```sh
+bun src/cli.ts tui     # or: lich 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.
+
+## Anatomy
+
+```
+lich v0.2.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)
+lich › Here is what I found ...        <- the agent's reply
+model llama3.2 · turns 2 · tokens 1,204 · [idle] · /path/.lich/sessions/...jsonl
+› ▌                                    <- input row (cursor block)
+```
+
+- **Header** — static version/model/provider line.
+- **Transcript** — user lines (`you ›`), replies (`lich ›`), tool rows (`⏺ name(args)` with a result line), and meta notices (`· context compressed ...`, `· error: ...`). The view keeps the newest 50 blocks; older lines scroll out of the transcript (session JSONLs still hold everything — see [limitations](#known-limitations)).
+- **Input row** — `› ` when idle, `… ` while the agent works; Enter submits, Backspace edits, pasted newlines collapse to spaces.
+- **Status bar** — see below.
+
+## Slash commands
+
+| Command | Effect |
+| --- | --- |
+| `/help` | Print the command list and key hints. |
+| `/model` | Show the active model and provider kind (from `providers[0]`). |
+| `/usage` | Show tokens used this session (cumulative across turns). |
+| `/clear` | Wipe the on-screen transcript. Does **not** reset agent memory — the next message still sees prior turns. |
+| `/sessions` | List the 10 newest `.jsonl` files in `session_dir` with sizes. |
+| `/exit`, `/quit`, `/q` | Exit the TUI. |
+
+Unknown commands print `· unknown command: /x (try /help)`. Slash commands are handled client-side and never invoke the model.
+
+## Input history
+
+Up/Down arrow keys walk a 20-entry recall ring of previously submitted lines (newest first); submitted duplicates move to the top instead of repeating. Recall position resets when you submit.
+
+## Status bar
+
+The bottom line shows, left to right:
+
+| Segment | Meaning |
+| --- | --- |
+| `model <name>` | First provider's model from config. |
+| `turns N` | Turns used by the most recent run (resets each message). |
+| `tokens N` | Cumulative session token usage (prompt + completion, across all turns). |
+| `[idle]` / `[thinking]` / `[tool]` | Current phase: waiting for input, calling the model, or executing a tool. |
+| `compressed N` | How many times context compression fired this session (hidden when 0). |
+| `<session path>` | Path of the newest persisted transcript (appears after the first run). |
+| `· budget exhausted` | Red notice when a run hit the turn cap. |
+
+## Multi-turn memory
+
+The TUI keeps one conversation: every submitted message is sent together with the full prior message history, so the agent remembers earlier turns for as long as the session stays open. When estimated tokens cross `compress_threshold` of `context_budget_tokens`, older turns are replaced by an LLM-generated summary (the 8 most recent messages always stay verbatim) and a `· context compressed` notice appears. There is deliberately no per-conversation reset command — `/clear` only clears the display; start a fresh `lich tui` process for an empty context.
+
+## Known limitations
+
+- The transcript keeps only the newest 50 blocks; older context scrolls away (it remains in the session file).
+- No token streaming: replies appear once the model finishes the turn.
+- No per-conversation reset — `/clear` is cosmetic; restart the TUI to reset memory.
+- Tool output previews are truncated to 120 chars per row; read the session JSONL for full output.
+
+## Tips
+
+- Use `/clear` when the transcript is visually noisy and you want to keep reading from the top — memory is unaffected.
+- After a long session, inspect what actually happened: `jq -r 'select(.kind=="message") | "\(.message.role): \(.message.content // "(tool call)")"' .lich/sessions/<newest>-tui.jsonl`.
+- Watch `compressed N` in the status bar: if it climbs steadily in short sessions, lower `context_budget_tokens` or expect summarization of older details (file paths survive compression; long verbatim outputs do not).

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@moikapy/lich",
+  "version": "0.3.0",
+  "description": "Lich — a TypeScript AI agent harness (library + CLI) inspired by Hermes",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moikapy/lich.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "lich": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "!docs/.vitepress/dist",
+    "!docs/.vitepress/cache",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node node_modules/tsup/dist/cli-default.js src/index.ts src/cli.ts --format esm --dts --clean --sourcemap",
+    "typecheck": "bun x tsc --noEmit",
+    "test": "node node_modules/vitest/vitest.mjs run",
+    "test:watch": "node node_modules/vitest/vitest.mjs",
+    "cli": "bun src/cli.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "ink": "^6.0.0",
+    "react": "^19.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0",
+    "vitepress": "^1.6.4"
+  }
+}