@moikapy/lich 0.5.1 → 0.7.0

package/dist/{tui-2VO6LAFM.js → tui-L6RABP2J.js}

@@ -1,10 +1,14 @@
+import {
+  fill_template,
+  load_theme
+} from "./chunk-JYURFAGB.js";
 import {
   LICH_VERSION
-} from "./chunk-6M6OAQGN.js";
+} from "./chunk-SAEB3QL3.js";
 import {
   create_agent_with_plugins,
   truncate_text
-} from "./chunk-CV2YH3FH.js";
+} from "./chunk-QVJCIZIF.js";
 
 // src/tui.tsx
 import { render } from "ink";
@@ -90,24 +94,24 @@ function parse_command(raw_input) {
   }
   return { kind: "slash", name: body.slice(0, space_index), args: body.slice(space_index + 1).trim() };
 }
-function tui_banner_text(agent_name, version, model, kind) {
-  return `${agent_name} v${version} \u2014 ${model} (${kind})`;
+function tui_banner_text(theme, version, model, kind) {
+  return fill_template(theme.welcome, { version, model, kind });
 }
 function format_usage(total_tokens) {
   return total_tokens.toLocaleString("en-US");
 }
-function assistant_result_block(message) {
+function assistant_result_block(message, theme) {
   if (message.content.length === 0) {
     return void 0;
   }
-  return { role: "lich", lines: [`lich \u203A ${message.content}`] };
+  return { role: "lich", lines: [`${theme.response_label} \u203A ${message.content}`] };
 }
-function run_notice_blocks(result) {
+function run_notice_blocks(result, theme) {
   const blocks = [];
   if (result.outcome.stopped_reason === "budget") {
-    blocks.push({ role: "error", lines: ["\xB7 budget exhausted (turn cap reached)"] });
+    blocks.push({ role: "error", lines: [`\xB7 ${fill_template(theme.notices.budget_exhausted, {})}`] });
   }
-  const final_block = result.outcome.final === void 0 ? void 0 : assistant_result_block(result.outcome.final);
+  const final_block = result.outcome.final === void 0 ? void 0 : assistant_result_block(result.outcome.final, theme);
   if (final_block !== void 0) {
     blocks.push(final_block);
   }
@@ -124,8 +128,9 @@ function tool_result_block(call, ok, result_content) {
   ];
   return { role: ok === true ? "tool" : "error", lines };
 }
-function compress_notice_block(summary_chars) {
-  return { role: "meta", lines: [`\xB7 context compressed (summary ${summary_chars} chars)`] };
+function compress_notice_block(summary_chars, theme) {
+  const line = fill_template(theme.notices.compressed, { chars: summary_chars });
+  return { role: "meta", lines: [`\xB7 ${line}`] };
 }
 function error_notice_block(message) {
   return { role: "error", lines: [`\xB7 error: ${truncate_text(message, ERROR_PREVIEW_CHARS)}`] };
@@ -150,12 +155,13 @@ function usage_notice_block(total_tokens) {
 function unknown_command_block(name) {
   return { role: "error", lines: [`\xB7 unknown command: /${name} (try /help)`] };
 }
-function session_list_block(entries, cap = 10) {
+function session_list_block(entries, theme, cap = 10) {
   const sorted = [...entries].sort((a, b) => b.mtime_ms - a.mtime_ms).slice(0, cap);
   if (sorted.length === 0) {
     return { role: "meta", lines: ["\xB7 no session files yet"] };
   }
-  const lines = [`\xB7 sessions (${sorted.length}):`];
+  const label = fill_template(theme.notices.sessions, { count: sorted.length });
+  const lines = [`\xB7 ${label}`];
   for (const entry of sorted) {
     lines.push(`  ${entry.name} (${format_usage(entry.size_bytes)} bytes)`);
   }
@@ -211,20 +217,15 @@ function MessageView({ blocks, state }) {
 // src/tui/status_bar.tsx
 import { Box as Box2, Text as Text2 } from "ink";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
-var PHASE_LABELS = {
-  idle: "idle",
-  thinking: "thinking",
-  tool: "tool"
-};
-function StatusBar({ state, model }) {
-  const phase = PHASE_LABELS[state.phase];
+function StatusBar({ state, model, theme }) {
+  const phase = theme.phase_labels[state.phase];
   return /* @__PURE__ */ jsxs2(Box2, { children: [
     /* @__PURE__ */ jsxs2(Text2, { dimColor: true, children: [
       `model ${model} \xB7 turns ${state.turns_used} \xB7 tokens ${format_usage(state.usage.total_tokens)} \xB7 [${phase}]`,
       state.compress_count > 0 ? ` \xB7 compressed ${state.compress_count}` : "",
       state.session_path !== void 0 ? ` \xB7 ${state.session_path}` : ""
     ] }),
-    state.budget_exhausted ? /* @__PURE__ */ jsx2(Text2, { color: "red", children: " \xB7 budget exhausted" }) : null
+    state.budget_exhausted ? /* @__PURE__ */ jsx2(Text2, { color: "red", children: ` \xB7 ${theme.notices.budget_exhausted}` }) : null
   ] });
 }
 
@@ -292,12 +293,12 @@ function CommandBar({ busy, on_submit }) {
 // src/tui/app.tsx
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 var SESSION_LIST_CAP = 10;
-function event_blocks(event) {
+function event_blocks(event, theme) {
   if (event.type === "tool_call_end") {
     return [tool_result_block(event.call, event.result.ok === true, event.result.output)];
   }
   if (event.type === "compress_end") {
-    return [compress_notice_block(event.summary_chars)];
+    return [compress_notice_block(event.summary_chars, theme)];
   }
   if (event.type === "error") {
     return [error_notice_block(event.error instanceof Error ? event.error.message : String(event.error))];
@@ -313,7 +314,7 @@ async function run_agent_turn(agent, history, input, on_event, on_done, signal)
     stop_listening();
   }
 }
-async function sessions_block(config) {
+async function sessions_block(config, theme) {
   try {
     const dir_entries = await readdir(config.session_dir, { withFileTypes: true });
     const entries = [];
@@ -324,7 +325,7 @@ async function sessions_block(config) {
       const info = await stat(`${config.session_dir}/${entry.name}`);
       entries.push({ name: entry.name, size_bytes: info.size, mtime_ms: info.mtimeMs });
     }
-    return session_list_block(entries, SESSION_LIST_CAP);
+    return session_list_block(entries, theme, SESSION_LIST_CAP);
   } catch {
     return { role: "meta", lines: ["\xB7 no session files yet"] };
   }
@@ -332,23 +333,23 @@ async function sessions_block(config) {
 function run_error_text(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function use_agent_run(agent, add_blocks, set_state, set_blocks) {
+function use_agent_run(agent, theme, add_blocks, set_state, set_blocks) {
   const history_ref = useRef([]);
   const controller_ref = useRef(void 0);
   const finish_run = useCallback((result) => {
     history_ref.current = result.messages;
     set_state((current) => apply_run_result(current, result));
-    add_blocks(run_notice_blocks(result));
-  }, [add_blocks, set_state]);
+    add_blocks(run_notice_blocks(result, theme));
+  }, [add_blocks, set_state, theme]);
   const start_message_run = useCallback(
     (text) => {
-      add_blocks([{ role: "user", lines: [`you \u203A ${text}`] }]);
+      add_blocks([{ role: "user", lines: [`${theme.user_label} \u203A ${text}`] }]);
       set_state((current) => ({ ...current, phase: "thinking", active_tool: void 0 }));
       const controller = new AbortController();
       controller_ref.current = controller;
       const on_event = (event) => {
         set_state((current) => apply_event(current, event));
-        set_blocks((current) => [...current, ...event_blocks(event)].slice(-HISTORY_CAP));
+        set_blocks((current) => [...current, ...event_blocks(event, theme)].slice(-HISTORY_CAP));
       };
       void run_agent_turn(agent, history_ref.current, text, on_event, finish_run, controller.signal).catch((error) => {
         add_blocks([error_notice_block(run_error_text(error))]);
@@ -359,12 +360,12 @@ function use_agent_run(agent, add_blocks, set_state, set_blocks) {
         }
       });
     },
-    [agent, add_blocks, finish_run, set_blocks, set_state]
+    [agent, add_blocks, finish_run, set_blocks, set_state, theme]
   );
   useEffect2(() => () => controller_ref.current?.abort(), []);
   return start_message_run;
 }
-function use_slash_commands(agent, add_blocks, set_blocks, total_tokens) {
+function use_slash_commands(agent, theme, add_blocks, set_blocks, total_tokens) {
   const handle = useCallback(
     (parsed) => {
       if (parsed.name === "exit" || parsed.name === "quit" || parsed.name === "q") {
@@ -380,16 +381,16 @@ function use_slash_commands(agent, add_blocks, set_blocks, total_tokens) {
       } else if (parsed.name === "clear") {
         set_blocks([]);
       } else if (parsed.name === "sessions") {
-        void sessions_block(agent.config).then((block) => add_blocks([block]));
+        void sessions_block(agent.config, theme).then((block) => add_blocks([block]));
       } else {
         add_blocks([unknown_command_block(parsed.name)]);
       }
     },
-    [agent, add_blocks, set_blocks, total_tokens]
+    [agent, add_blocks, set_blocks, theme, total_tokens]
   );
   return handle;
 }
-function TuiApp({ agent }) {
+function TuiApp({ agent, theme }) {
   const [blocks, set_blocks] = useState3([]);
   const [state, set_state] = useState3(INITIAL_UI_STATE);
   const add_blocks = useCallback((added) => {
@@ -398,8 +399,8 @@ function TuiApp({ agent }) {
     }
     set_blocks((current) => [...current, ...added].slice(-HISTORY_CAP));
   }, []);
-  const start_message_run = use_agent_run(agent, add_blocks, set_state, set_blocks);
-  const handle_slash = use_slash_commands(agent, add_blocks, set_blocks, state.usage.total_tokens);
+  const start_message_run = use_agent_run(agent, theme, add_blocks, set_state, set_blocks);
+  const handle_slash = use_slash_commands(agent, theme, add_blocks, set_blocks, state.usage.total_tokens);
   const submit = useCallback(
     (text) => {
       const parsed = parse_command(text);
@@ -415,9 +416,9 @@ function TuiApp({ agent }) {
   );
   const provider = agent.config.providers[0];
   return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", minHeight: 8, children: [
-    /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: tui_banner_text(agent.config.agent_name, LICH_VERSION, provider?.model ?? "unknown", provider?.kind ?? "unknown") }),
+    /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: tui_banner_text(theme, LICH_VERSION, provider?.model ?? "unknown", provider?.kind ?? "unknown") }),
     /* @__PURE__ */ jsx4(MessageView, { blocks, state }),
-    /* @__PURE__ */ jsx4(StatusBar, { state, model: provider?.model ?? "unknown" }),
+    /* @__PURE__ */ jsx4(StatusBar, { state, model: provider?.model ?? "unknown", theme }),
     /* @__PURE__ */ jsx4(CommandBar, { busy: state.phase !== "idle", on_submit: submit })
   ] });
 }
@@ -426,11 +427,12 @@ function TuiApp({ agent }) {
 import { jsx as jsx5 } from "react/jsx-runtime";
 async function run_tui(config) {
   const agent = await create_agent_with_plugins(config);
-  const instance = render(/* @__PURE__ */ jsx5(TuiApp, { agent }));
+  const theme = load_theme(config.theme);
+  const instance = render(/* @__PURE__ */ jsx5(TuiApp, { agent, theme }));
   await instance.waitUntilExit();
   return 0;
 }
 export {
   run_tui
 };
-//# sourceMappingURL=tui-2VO6LAFM.js.map
+//# sourceMappingURL=tui-L6RABP2J.js.map

package/dist/tui-L6RABP2J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tui.tsx","../src/tui/app.tsx","../src/tui/state.ts","../src/tui/message_view.tsx","../src/tui/status_bar.tsx","../src/tui/command_bar.tsx"],"sourcesContent":["/**\n * TUI entry: builds the agent from the parsed config and renders the ink app\n * until exit. The CLI dynamic-imports this module for `lich tui`.\n */\nimport { render } from \"ink\";\nimport { create_agent_with_plugins } from \"./agent/agent.js\";\nimport type { AgentConfig } from \"./agent/config.js\";\nimport { TuiApp } from \"./tui/app.js\";\nimport { load_theme } from \"./util/theme.js\";\n\nexport async function run_tui(config: AgentConfig): Promise<number> {\n  const agent = await create_agent_with_plugins(config);\n  const theme = load_theme(config.theme);\n  const instance = render(<TuiApp agent={agent} theme={theme} />);\n  await instance.waitUntilExit();\n  return 0;\n}","/**\n * Root ink component for the lich TUI: wires agent events into the UI state\n * machine, drives agent.run with history continuity, and lays out header,\n * transcript, status bar, and the command input row.\n */\nimport { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from \"react\";\nimport { Box, Text } from \"ink\";\nimport type { Agent, AgentRunResult } from \"../agent/agent.js\";\nimport type { AgentEvent } from \"../agent/events.js\";\nimport type { AgentConfig } from \"../agent/config.js\";\nimport type { Message } from \"../providers/types.js\";\nimport { LICH_VERSION } from \"../index.js\";\nimport type { ThemeSpec } from \"../util/lore.js\";\nimport { readdir, stat } from \"node:fs/promises\";\nimport {\n  apply_event,\n  apply_run_result,\n  compress_notice_block,\n  error_notice_block,\n  help_block,\n  HISTORY_CAP,\n  INITIAL_UI_STATE,\n  model_label_block,\n  parse_command,\n  tui_banner_text,\n  run_notice_blocks,\n  session_list_block,\n  tool_result_block,\n  unknown_command_block,\n  usage_notice_block,\n  type HistoryBlock,\n  type ParsedInput,\n  type SessionEntryInfo,\n  type UiState,\n} from \"./state.js\";\nimport { MessageView } from \"./message_view.js\";\nimport { StatusBar } from \"./status_bar.js\";\nimport { CommandBar } from \"./command_bar.js\";\n\nconst SESSION_LIST_CAP = 10;\n\ntype SlashInput = Extract<ParsedInput, { kind: \"slash\" }>;\ntype AddBlocks = (added: readonly HistoryBlock[]) => void;\ntype SetUiState = Dispatch<SetStateAction<UiState>>;\ntype SetBlocks = Dispatch<SetStateAction<readonly HistoryBlock[]>>;\n\n/** Map one agent event to optional transcript blocks (tool rows, notices). */\nfunction event_blocks(event: AgentEvent, theme: ThemeSpec): readonly HistoryBlock[] {\n  if (event.type === \"tool_call_end\") {\n    return [tool_result_block(event.call, event.result.ok === true, event.result.output)];\n  }\n  if (event.type === \"compress_end\") {\n    return [compress_notice_block(event.summary_chars, theme)];\n  }\n  if (event.type === \"error\") {\n    return [error_notice_block(event.error instanceof Error ? event.error.message : String(event.error))];\n  }\n  return [];\n}\n\n/** One agent turn: subscribe to events, run, unsubscribe in finally. */\nasync function run_agent_turn(\n  agent: Agent,\n  history: readonly Message[],\n  input: string,\n  on_event: (event: AgentEvent) => void,\n  on_done: (result: AgentRunResult) => void,\n  signal: AbortSignal,\n): Promise<void> {\n  const stop_listening = agent.events.on(on_event);\n  try {\n    const result = await agent.run({ input, history, signal, label: \"tui\" });\n    on_done(result);\n  } finally {\n    stop_listening();\n  }\n}\n\n/** Async /sessions listing as a meta block (never throws). */\nasync function sessions_block(config: AgentConfig, theme: ThemeSpec): Promise<HistoryBlock> {\n  try {\n    const dir_entries = await readdir(config.session_dir, { withFileTypes: true });\n    const entries: SessionEntryInfo[] = [];\n    for (const entry of dir_entries) {\n      if (entry.isFile() === false || entry.name.endsWith(\".jsonl\") === false) {\n        continue;\n      }\n      const info = await stat(`${config.session_dir}/${entry.name}`);\n      entries.push({ name: entry.name, size_bytes: info.size, mtime_ms: info.mtimeMs });\n    }\n    return session_list_block(entries, theme, SESSION_LIST_CAP);\n  } catch {\n    return { role: \"meta\", lines: [\"· no session files yet\"] };\n  }\n}\n\nfunction run_error_text(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** Runs one message exchange; owns history continuity and abort wiring. */\nfunction use_agent_run(\n  agent: Agent,\n  theme: ThemeSpec,\n  add_blocks: AddBlocks,\n  set_state: SetUiState,\n  set_blocks: SetBlocks,\n): (text: string) => void {\n  const history_ref = useRef<readonly Message[]>([]);\n  const controller_ref = useRef<AbortController | undefined>(undefined);\n\n  const finish_run = useCallback((result: AgentRunResult): void => {\n    history_ref.current = result.messages;\n    set_state((current) => apply_run_result(current, result));\n    add_blocks(run_notice_blocks(result, theme));\n  }, [add_blocks, set_state, theme]);\n\n  const start_message_run = useCallback(\n    (text: string): void => {\n      add_blocks([{ role: \"user\", lines: [`${theme.user_label} › ${text}`] }]);\n      set_state((current) => ({ ...current, phase: \"thinking\", active_tool: undefined }));\n      const controller = new AbortController();\n      controller_ref.current = controller;\n      const on_event = (event: AgentEvent): void => {\n        set_state((current) => apply_event(current, event));\n        set_blocks((current) => [...current, ...event_blocks(event, theme)].slice(-HISTORY_CAP));\n      };\n      void run_agent_turn(agent, history_ref.current, text, on_event, finish_run, controller.signal)\n        .catch((error: unknown) => {\n          add_blocks([error_notice_block(run_error_text(error))]);\n          set_state((current) => ({ ...current, phase: \"idle\" }));\n        })\n        .finally(() => {\n          if (controller_ref.current === controller) {\n            controller_ref.current = undefined;\n          }\n        });\n    },\n    [agent, add_blocks, finish_run, set_blocks, set_state, theme],\n  );\n\n  useEffect(() => () => controller_ref.current?.abort(), []);\n\n  return start_message_run;\n}\n\n/** Slash-command dispatch: pure client-side actions, never hits the agent. */\nfunction use_slash_commands(\n  agent: Agent,\n  theme: ThemeSpec,\n  add_blocks: AddBlocks,\n  set_blocks: SetBlocks,\n  total_tokens: number,\n): (parsed: SlashInput) => void {\n  const handle = useCallback(\n    (parsed: SlashInput): void => {\n      if (parsed.name === \"exit\" || parsed.name === \"quit\" || parsed.name === \"q\") {\n        process.exit(0);\n        return;\n      }\n      if (parsed.name === \"help\") {\n        add_blocks([help_block()]);\n      } else if (parsed.name === \"model\") {\n        add_blocks([model_label_block(agent.config)]);\n      } else if (parsed.name === \"usage\") {\n        add_blocks([usage_notice_block(total_tokens)]);\n      } else if (parsed.name === \"clear\") {\n        set_blocks([]);\n      } else if (parsed.name === \"sessions\") {\n        void sessions_block(agent.config, theme).then((block) => add_blocks([block]));\n      } else {\n        add_blocks([unknown_command_block(parsed.name)]);\n      }\n    },\n    [agent, add_blocks, set_blocks, theme, total_tokens],\n  );\n  return handle;\n}\n\ninterface TuiAppProps {\n  readonly agent: Agent;\n  readonly theme: ThemeSpec;\n}\n\nexport function TuiApp({ agent, theme }: TuiAppProps): React.JSX.Element {\n  const [blocks, set_blocks] = useState<readonly HistoryBlock[]>([]);\n  const [state, set_state] = useState(INITIAL_UI_STATE);\n\n  const add_blocks = useCallback<AddBlocks>((added: readonly HistoryBlock[]): void => {\n    if (added.length === 0) {\n      return;\n    }\n    set_blocks((current) => [...current, ...added].slice(-HISTORY_CAP));\n  }, []);\n\n  const start_message_run = use_agent_run(agent, theme, add_blocks, set_state, set_blocks);\n  const handle_slash = use_slash_commands(agent, theme, add_blocks, set_blocks, state.usage.total_tokens);\n\n  const submit = useCallback(\n    (text: string): void => {\n      const parsed = parse_command(text);\n      if (parsed.kind === \"message\") {\n        if (parsed.text.length > 0) {\n          start_message_run(parsed.text);\n        }\n        return;\n      }\n      handle_slash(parsed);\n    },\n    [handle_slash, start_message_run],\n  );\n\n  const provider = agent.config.providers[0];\n  return (\n    <Box flexDirection=\"column\" minHeight={8}>\n      <Text dimColor>{tui_banner_text(theme, LICH_VERSION, provider?.model ?? \"unknown\", provider?.kind ?? \"unknown\")}</Text>\n      <MessageView blocks={blocks} state={state} />\n      <StatusBar state={state} model={provider?.model ?? \"unknown\"} theme={theme} />\n      <CommandBar busy={state.phase !== \"idle\"} on_submit={submit} />\n    </Box>\n  );\n}","/**\n * Pure state logic for the ink TUI: UI-state transitions from agent events,\n * slash-command parsing, transcript block mapping, and display formatters.\n * No ink/react imports here — this module is unit-tested without a TTY.\n */\nimport type { AgentEvent } from \"../agent/events.js\";\nimport type { AgentRunResult } from \"../agent/agent.js\";\nimport type { AssistantMessage, Message, ToolCall, Usage } from \"../providers/types.js\";\nimport { safe_json_parse, truncate_text } from \"../util/json.js\";\nimport type { ThemeSpec } from \"../util/lore.js\";\nimport { fill_template } from \"../util/theme.js\";\n\nexport type UiPhase = \"idle\" | \"thinking\" | \"tool\";\n\nexport interface UiState {\n  readonly phase: UiPhase;\n  readonly turns_used: number;\n  readonly usage: Usage;\n  readonly session_path: string | undefined;\n  readonly compress_count: number;\n  readonly budget_exhausted: boolean;\n  readonly last_error: string | undefined;\n  readonly active_tool: ToolCall | undefined;\n}\n\nexport const INITIAL_UI_STATE: UiState = {\n  phase: \"idle\",\n  turns_used: 0,\n  usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },\n  session_path: undefined,\n  compress_count: 0,\n  budget_exhausted: false,\n  last_error: undefined,\n  active_tool: undefined,\n};\n\nexport const HISTORY_CAP = 50;\nconst TOOL_ARGS_PREVIEW_CHARS = 80;\nconst TOOL_OUTPUT_PREVIEW_CHARS = 120;\nconst ERROR_PREVIEW_CHARS = 300;\n\nfunction error_text(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n  return String(error);\n}\n\n/** Reducer over UiState; one pure mapping per AgentEvent variant. */\nexport function apply_event(state: UiState, event: AgentEvent): UiState {\n  switch (event.type) {\n    case \"llm_start\":\n      return { ...state, phase: \"thinking\", active_tool: undefined };\n    case \"llm_end\":\n      return {\n        ...state,\n        usage: {\n          prompt_tokens: state.usage.prompt_tokens + event.result.usage.prompt_tokens,\n          completion_tokens: state.usage.completion_tokens + event.result.usage.completion_tokens,\n          total_tokens: state.usage.total_tokens + event.result.usage.total_tokens,\n        },\n      };\n    case \"tool_call_start\":\n      return { ...state, phase: \"tool\", active_tool: event.call };\n    case \"tool_call_end\":\n      return {\n        ...state,\n        phase: \"thinking\",\n        active_tool: undefined,\n        last_error: event.result.ok === true ? state.last_error : (event.result.error ?? \"tool failed\"),\n      };\n    case \"turn_end\":\n      return { ...state, turns_used: event.turn };\n    case \"compress_start\":\n      return { ...state, compress_count: state.compress_count + 1 };\n    case \"budget_exhausted\":\n      return { ...state, budget_exhausted: true };\n    case \"error\":\n      return { ...state, last_error: error_text(event.error) };\n    default:\n      return state;\n  }\n}\n\n/** Fold an AgentRunResult back into UiState after the run promise resolves. */\nexport function apply_run_result(state: UiState, result: AgentRunResult): UiState {\n  return {\n    ...state,\n    phase: \"idle\",\n    turns_used: result.outcome.turns_used,\n    session_path: result.session_path ?? state.session_path,\n    last_error: result.outcome.stopped_reason === \"aborted\" ? \"run aborted\" : state.last_error,\n  };\n}\n\nexport type ParsedInput = { kind: \"slash\"; name: string; args: string } | { kind: \"message\"; text: string };\n\n/** Split trimmed input into slash command vs plain message (empty input = message). */\nexport function parse_command(raw_input: string): ParsedInput {\n  const text = raw_input.trim();\n  if (text.startsWith(\"/\") === false) {\n    return { kind: \"message\", text };\n  }\n  const body = text.slice(1);\n  const space_index = body.indexOf(\" \");\n  if (space_index === -1) {\n    return { kind: \"slash\", name: body, args: \"\" };\n  }\n  return { kind: \"slash\", name: body.slice(0, space_index), args: body.slice(space_index + 1).trim() };\n}\n\n/** Dim header: the theme welcome string, the one tagline placement. */\nexport function tui_banner_text(theme: ThemeSpec, version: string, model: string, kind: string): string {\n  return fill_template(theme.welcome, { version, model, kind });\n}\n\n/** 1234567 -> \"1,234,567\" (US grouping, matching the status bar style). */\nexport function format_usage(total_tokens: number): string {\n  return total_tokens.toLocaleString(\"en-US\");\n}\n\nexport type BlockRole = \"user\" | \"lich\" | \"tool\" | \"meta\" | \"error\";\n\nexport interface HistoryBlock {\n  readonly role: BlockRole;\n  readonly lines: readonly string[];\n}\n\nfunction assistant_tool_line(call: ToolCall): string {\n  const args_json = JSON.stringify(call.args) ?? \"{}\";\n  return `  \\u23bf ${truncate_text(args_json, TOOL_ARGS_PREVIEW_CHARS)}`;\n}\n\nfunction format_message_lines(message: Message, theme: ThemeSpec): string[] {\n  if (message.role === \"user\") {\n    return [`${theme.user_label} \\u203a ${message.content}`];\n  }\n  if (message.role === \"assistant\") {\n    const lines = [`${theme.response_label} \\u203a ${message.content}`];\n    for (const call of message.tool_calls ?? []) {\n      lines.push(assistant_tool_line(call));\n    }\n    return lines;\n  }\n  if (message.role === \"tool\") {\n    const flag = message.is_error === true ? \"error\" : \"ok\";\n    return [`  \\u23bf ${message.name}: ${flag} (${truncate_text(message.content, TOOL_OUTPUT_PREVIEW_CHARS)})`];\n  }\n  return [`\\u00b7 system: ${message.content}`];\n}\n\n/** Map one transcript Message to display lines with its role tag. */\nexport function format_message_block(message: Message, theme: ThemeSpec): HistoryBlock {\n  if (message.role === \"tool\") {\n    const ok = message.is_error !== true;\n    return { role: ok === true ? \"tool\" : \"error\", lines: format_message_lines(message, theme) };\n  }\n  const roles: Record<Exclude<Message[\"role\"], \"tool\">, BlockRole> = {\n    system: \"meta\",\n    user: \"user\",\n    assistant: \"lich\",\n  };\n  return { role: roles[message.role], lines: format_message_lines(message, theme) };\n}\n\n/** Keep the newest `cap` non-system messages as renderable blocks. */\nexport function split_history_blocks(messages: readonly Message[], cap: number, theme: ThemeSpec): HistoryBlock[] {\n  const visible = messages.filter((message) => message.role !== \"system\");\n  const start = Math.max(0, visible.length - cap);\n  return visible.slice(start).map((message) => format_message_block(message, theme));\n}\n\nfunction assistant_result_block(message: AssistantMessage, theme: ThemeSpec): HistoryBlock | undefined {\n  if (message.content.length === 0) {\n    return undefined;\n  }\n  return { role: \"lich\", lines: [`${theme.response_label} \\u203a ${message.content}`] };\n}\n\n/** Post-run meta blocks: compression notices, budget, errors, final answer. */\nexport function run_notice_blocks(result: AgentRunResult, theme: ThemeSpec): HistoryBlock[] {\n  const blocks: HistoryBlock[] = [];\n  if (result.outcome.stopped_reason === \"budget\") {\n    blocks.push({ role: \"error\", lines: [`\\u00b7 ${fill_template(theme.notices.budget_exhausted, {})}`] });\n  }\n  const final_block = result.outcome.final === undefined ? undefined : assistant_result_block(result.outcome.final, theme);\n  if (final_block !== undefined) {\n    blocks.push(final_block);\n  }\n  return blocks;\n}\n\nfunction truncate_tool_preview(result_content: string, ok: boolean): string {\n  return `  \\u23bf ${ok === true ? \"ok\" : \"error\"} (${truncate_text(result_content, TOOL_OUTPUT_PREVIEW_CHARS)})`;\n}\n\n/** One finalized live tool row; falls back to the transcript copy when absent. */\nexport function tool_result_block(call: ToolCall, ok: boolean, result_content: string): HistoryBlock {\n  const args_json = JSON.stringify(call.args) ?? \"{}\";\n  const lines = [\n    `\\u23fa ${call.name}(${truncate_text(args_json, TOOL_ARGS_PREVIEW_CHARS)})`,\n    truncate_tool_preview(result_content, ok),\n  ];\n  return { role: ok === true ? \"tool\" : \"error\", lines };\n}\n\nexport function parse_tool_message_content(content: string): { ok: boolean; output: string } {\n  const parsed = safe_json_parse<{ ok?: unknown; output?: unknown }>(content);\n  if (parsed !== undefined && typeof parsed.ok === \"boolean\" && typeof parsed.output === \"string\") {\n    return { ok: parsed.ok, output: parsed.output };\n  }\n  return { ok: true, output: content };\n}\n\nexport function compress_notice_block(summary_chars: number, theme: ThemeSpec): HistoryBlock {\n  const line = fill_template(theme.notices.compressed, { chars: summary_chars });\n  return { role: \"meta\", lines: [`\\u00b7 ${line}`] };\n}\n\nexport function error_notice_block(message: string): HistoryBlock {\n  return { role: \"error\", lines: [`\\u00b7 error: ${truncate_text(message, ERROR_PREVIEW_CHARS)}`] };\n}\n\nexport function tool_args_preview(args: Record<string, unknown>): string {\n  const args_json = JSON.stringify(args) ?? \"{}\";\n  return truncate_text(args_json, TOOL_ARGS_PREVIEW_CHARS);\n}\n\nexport function help_block(): HistoryBlock {\n  return { role: \"meta\", lines: [...HELP_LINES] };\n}\n\nexport function model_label_block(config: { providers: readonly { model: string; kind: string }[] }): HistoryBlock {\n  const provider = config.providers[0];\n  return {\n    role: \"meta\",\n    lines: [`\\u00b7 model: ${provider?.model ?? \"unknown\"} \\u00b7 provider: ${provider?.kind ?? \"unknown\"}`],\n  };\n}\n\nexport function usage_notice_block(total_tokens: number): HistoryBlock {\n  return { role: \"meta\", lines: [`\\u00b7 tokens used this session: ${format_usage(total_tokens)}`] };\n}\n\nexport function unknown_command_block(name: string): HistoryBlock {\n  return { role: \"error\", lines: [`\\u00b7 unknown command: /${name} (try /help)`] };\n}\n\nexport interface SessionEntryInfo {\n  readonly name: string;\n  readonly size_bytes: number;\n  readonly mtime_ms: number;\n}\n\n/** Newest-first session listing, capped at `cap` entries. */\nexport function session_list_block(entries: readonly SessionEntryInfo[], theme: ThemeSpec, cap: number = 10): HistoryBlock {\n  const sorted = [...entries].sort((a, b) => b.mtime_ms - a.mtime_ms).slice(0, cap);\n  if (sorted.length === 0) {\n    return { role: \"meta\", lines: [\"\\u00b7 no session files yet\"] };\n  }\n  const label = fill_template(theme.notices.sessions, { count: sorted.length });\n  const lines: string[] = [`\\u00b7 ${label}`];\n  for (const entry of sorted) {\n    lines.push(`  ${entry.name} (${format_usage(entry.size_bytes)} bytes)`);\n  }\n  return { role: \"meta\", lines };\n}\n\nexport const SLASH_COMMAND_NAMES: readonly string[] = [\n  \"exit\",\n  \"quit\",\n  \"q\",\n  \"help\",\n  \"model\",\n  \"usage\",\n  \"clear\",\n  \"sessions\",\n];\n\nexport const HELP_LINES: readonly string[] = [\n  \"commands: /help /model /usage /clear /sessions /exit (aliases: /quit /q)\",\n  \"enter submits \\u00b7 backspace deletes \\u00b7 up/down recalls history \\u00b7 pasted newlines become spaces\",\n];","/**\n * Transcript rendering: maps HistoryBlock descriptors to ink elements with\n * role-based colors, and shows an animated braille spinner while thinking.\n * Blocks are pre-capped by the app, so a plain flex column is sufficient.\n */\nimport { useEffect, useState } from \"react\";\nimport { Box, Text } from \"ink\";\nimport { tool_args_preview, type HistoryBlock, type UiState } from \"./state.js\";\n\nconst SPINNER_FRAMES: readonly string[] = [\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"];\nconst SPINNER_INTERVAL_MS = 80;\n\n/** Braille spinner frames on an 80ms interval; clears on unmount. */\nfunction use_spinner(): string {\n  const [frame, set_frame] = useState(SPINNER_FRAMES[0] ?? \"⠋\");\n  useEffect(() => {\n    const timer = setInterval(() => {\n      const next = SPINNER_FRAMES[(SPINNER_FRAMES.indexOf(frame) + 1) % SPINNER_FRAMES.length];\n      set_frame(next ?? \"⠋\");\n    }, SPINNER_INTERVAL_MS);\n    return () => {\n      clearInterval(timer);\n    };\n  }, [frame]);\n  return frame;\n}\n\nfunction ThinkingLine(): React.JSX.Element {\n  const frame = use_spinner();\n  return <Text dimColor>{`${frame} thinking…`}</Text>;\n}\n\nconst ROLE_COLORS: Record<HistoryBlock[\"role\"], string | undefined> = {\n  user: \"white\",\n  lich: \"green\",\n  tool: \"cyan\",\n  meta: undefined,\n  error: \"red\",\n};\n\nfunction BlockLines({ block }: { block: HistoryBlock }): React.JSX.Element {\n  const color = ROLE_COLORS[block.role];\n  return (\n    <>\n      {block.lines.map((line, index) => (\n        <Text key={index} color={color} dimColor={color === undefined}>{line}</Text>\n      ))}\n    </>\n  );\n}\n\ninterface MessageViewProps {\n  readonly blocks: readonly HistoryBlock[];\n  readonly state: UiState;\n}\n\n/** Transcript column plus the live phase line (spinner / running tool row). */\nexport function MessageView({ blocks, state }: MessageViewProps): React.JSX.Element {\n  return (\n    <Box flexDirection=\"column\" flexGrow={1}>\n      {blocks.map((block, index) => (\n        <Box key={index} flexDirection=\"column\">\n          <BlockLines block={block} />\n        </Box>\n      ))}\n      {state.phase === \"thinking\" ? <ThinkingLine /> : null}\n      {state.phase === \"tool\" && state.active_tool !== undefined ? (\n        <Text color=\"cyan\">{`⏺ ${state.active_tool.name}(${tool_args_preview(state.active_tool.args)})`}</Text>\n      ) : null}\n    </Box>\n  );\n}","/**\n * Bottom status line: model, turns, token totals, phase tag, compression\n * count, and the session path once the agent has persisted a transcript.\n */\nimport { Box, Text } from \"ink\";\nimport type { ThemeSpec } from \"../util/lore.js\";\nimport { format_usage, type UiState } from \"./state.js\";\n\ninterface StatusBarProps {\n  readonly state: UiState;\n  readonly model: string;\n  readonly theme: ThemeSpec;\n}\n\nexport function StatusBar({ state, model, theme }: StatusBarProps): React.JSX.Element {\n  const phase = theme.phase_labels[state.phase];\n  return (\n    <Box>\n      <Text dimColor>\n        {`model ${model} · turns ${state.turns_used} · tokens ${format_usage(state.usage.total_tokens)} · [${phase}]`}\n        {state.compress_count > 0 ? ` · compressed ${state.compress_count}` : \"\"}\n        {state.session_path !== undefined ? ` · ${state.session_path}` : \"\"}\n      </Text>\n      {state.budget_exhausted ? <Text color=\"red\">{` · ${theme.notices.budget_exhausted}`}</Text> : null}\n    </Box>\n  );\n}","/**\n * Input row: printable characters accumulate in a buffer, Enter submits,\n * Backspace/Delete edits, Up/Down walk a 20-entry recall ring, and pasted\n * newlines collapse to spaces. Ctrl+C is left to ink's default handling.\n */\nimport { useState } from \"react\";\nimport { Box, Text, useInput } from \"ink\";\n\nconst INPUT_HISTORY_CAP = 20;\n\ninterface CommandBarProps {\n  readonly busy: boolean;\n  readonly on_submit: (text: string) => void;\n}\n\n/** Push onto a capped ring (newest first) without mutating the source. */\nfunction push_history(ring: readonly string[], entry: string): readonly string[] {\n  return [entry, ...ring.filter((item) => item !== entry)].slice(0, INPUT_HISTORY_CAP);\n}\n\nexport function CommandBar({ busy, on_submit }: CommandBarProps): React.JSX.Element {\n  const [buffer, set_buffer] = useState(\"\");\n  const [recall_ring, set_recall_ring] = useState<readonly string[]>([]);\n  const [recall_index, set_recall_index] = useState<number | undefined>(undefined);\n\n  const submit_buffer = (): void => {\n    const text = buffer.trim();\n    set_buffer(\"\");\n    set_recall_index(undefined);\n    if (text.length > 0) {\n      set_recall_ring((current) => push_history(current, text));\n      on_submit(text);\n    }\n  };\n\n  const walk_recall = (direction: 1 | -1): void => {\n    if (recall_ring.length === 0) {\n      return;\n    }\n    const current = recall_index ?? -direction;\n    const next = Math.min(Math.max(current + direction, 0), recall_ring.length - 1);\n    set_recall_index(next);\n    set_buffer(recall_ring[next] ?? \"\");\n  };\n\n  useInput((input, key) => {\n    if (key.return === true) {\n      submit_buffer();\n      return;\n    }\n    if (key.upArrow === true) {\n      walk_recall(-1);\n      return;\n    }\n    if (key.downArrow === true) {\n      walk_recall(1);\n      return;\n    }\n    if (key.backspace === true || key.delete === true) {\n      set_buffer((current) => current.slice(0, -1));\n      return;\n    }\n    if (key.ctrl === true || key.escape === true || key.tab === true || key.meta === true) {\n      return;\n    }\n    if (input.length > 0) {\n      set_buffer((current) => current + input.replaceAll(\"\\n\", \" \").replaceAll(\"\\r\", \" \"));\n    }\n  });\n\n  return (\n    <Box>\n      <Text dimColor>{busy ? \"  … \" : \"› \"}</Text>\n      <Text>{buffer}</Text>\n      <Text dimColor>▌</Text>\n    </Box>\n  );\n}"],"mappings":"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","names":["useEffect","useState","Box","Text","Box","Text","jsx","jsxs","Box","Text","useState","Box","Text","jsx","jsxs","jsx","jsxs","useEffect","useState","Box","Text","jsx"]}

package/docs/.vitepress/config.mts

@@ -28,7 +28,11 @@ export default defineConfig({
           { text: 'CLI reference', link: '/user-guide/cli' },
           { text: 'TUI guide', link: '/user-guide/tui' },
           { text: 'Gateway guide', link: '/user-guide/gateway' },
-          { text: 'Library guide', link: '/user-guide/library' }
+          { text: 'Library guide', link: '/user-guide/library' },
+          { text: 'Plugins guide', link: '/user-guide/plugins' },
+          { text: 'Godot guide', link: '/user-guide/godot' },
+          { text: 'Redot guide', link: '/user-guide/redot' },
+          { text: 'Games guide', link: '/user-guide/games' }
         ]
       },
       {
@@ -38,6 +42,7 @@ export default defineConfig({
           { text: 'Agent loop', link: '/architecture/agent-loop' },
           { text: 'Providers', link: '/architecture/providers' },
           { text: 'Tools', link: '/architecture/tools' },
+          { text: 'Plugins', link: '/architecture/plugins' },
           { text: 'Extending', link: '/architecture/extending' }
         ]
       }

package/docs/architecture/agent-loop.md

@@ -187,9 +187,11 @@ coarse - see the trade-off note in [overview](./overview.md#design-trade-offs).
 
 What gets persisted, per run (`Agent.persist_session`): a `run_start` meta
 record, one `message` record per outcome message (including the seeded system
-message and tool messages), and a `budget_exhausted` meta record when the run
-stopped on budget. Everything is best-effort: any error logs a warning and
-returns `session_path: undefined` instead of failing the run.
+message and tool messages), a `budget_exhausted` meta record when the run
+stopped on budget, and a `run_end` meta record (`stopped_reason`, `usage`)
+on every completed run. `usage` is the run's `usage_total`. Everything is
+best-effort: any error logs a warning and returns `session_path: undefined`
+instead of failing the run.
 
 `read_session_messages(path)` parses a file back into `Message[]`: per line it
 JSON-parses leniently, accepts only records with a `kind: "message"`-shaped

package/docs/architecture/overview.md

@@ -1,21 +1,24 @@
 # Architecture Overview
 
-Lich v0.3.0 is a small TypeScript AI agent harness: it drives a chat model in a
+Lich is a small TypeScript AI agent harness: it drives a chat model in a
 think-act-observe loop, lets the model call tools, compresses history when the
-context budget demands it, and persists transcripts. It runs on Bun, is ESM
-with NodeNext resolution, and its only runtime dependencies are `zod` (config
-validation) and `ink` (the TUI). Everything else is Node/Bun built-ins.
+context budget demands it, and persists transcripts. The published npm package
+is 0.6.0. This tree also includes unreleased editor MCP (changelog 0.7.0);
+`package.json` is still 0.6.0, so `lich --version` prints `0.6.0`. It runs on
+Node >= 20 and on Bun, is ESM with NodeNext resolution, and its runtime
+dependencies are `zod` (config validation), `ink`, and `react` (the TUI).
+Everything else is Node/Bun built-ins.
 
 This page is the map. The follow-up pages go deep on each area:
 [agent loop](./agent-loop.md), [providers](./providers.md),
-[tools](./tools.md), and [extending](./extending.md).
+[tools](./tools.md), [plugins](./plugins.md), and [extending](./extending.md).
 
 ## Layer diagram
 
 ```mermaid
 flowchart TB
     subgraph entry["Entry surfaces"]
-        CLI["src/cli.ts<br/>one-shot and chat"]
+        CLI["src/cli.ts<br/>one-shot, chat, tui,<br/>gateway, mcp"]
         TUI["src/tui/app.tsx<br/>ink TUI"]
         GW["src/gateway/runner.ts<br/>webhook, telegram,<br/>discord, twitch"]
         LIB["src/index.ts<br/>library exports"]
@@ -94,35 +97,42 @@ Why this matters:
 Walkthrough of a single `Agent.run({ input })` call
 ([`src/agent/agent.ts`](../../src/agent/agent.ts)):
 
-1. **Usage collector attached.** `run()` subscribes a `collect_usage` handler
+1. **MCP attach, once.** Before the first model call, enabled `mcp_servers`
+   are connected (`initialize`, `notifications/initialized`, then `tools/list`)
+   and registered as `mcp_<server>_<tool>`. An empty `tools_enabled` never
+   connects. Disabled servers are skipped. A connect failure logs a warning
+   and the run continues. This client is in this source only (0.7.0 unreleased).
+2. **Usage collector attached.** `run()` subscribes a `collect_usage` handler
    on `agent.events`; every `llm_end` event adds the call's token usage into a
    per-run `Usage` total. The subscription is removed in a `finally` block.
-2. **Seed messages.** The caller's `history` (if any) is copied into a fresh
+3. **Seed messages.** The caller's `history` (if any) is copied into a fresh
    array and the new user message is appended. The caller's array is never
    mutated.
-3. **Loop starts.** `run_conversation(deps, seed, params)` first applies the
+4. **Loop starts.** `run_conversation(deps, seed, params)` first applies the
    system prompt via `seed_system_prompt` (prepend, or replace an existing
    system message if its content differs) and then enters the turn loop
    described in [agent loop](./agent-loop.md).
-4. **Each turn.** Abort check at the top of the turn, optional compression
+5. **Each turn.** Abort check at the top of the turn, optional compression
    check, then one LLM call through the router (`chat_with_failover`, which
    walks providers with bounded in-place retries). The assistant message is
    pushed onto the history.
-5. **Tools.** If the assistant message carries `tool_calls`, each call runs
-   through the `ToolExecutor` (30 s timeout, abort linking, output clamping)
-   and a `tool` message is appended per call. The loop then starts the next
+6. **Tools.** If the assistant message carries `tool_calls`, each call runs
+   through the `ToolExecutor` (per-tool `timeout_ms`, else 30 s; abort linking,
+   output clamping) and a `tool` message is appended per call. `terminal` sets
+   300000 ms; `run_tests` sets 600000. The loop then starts the next
    turn. A turn with no tool calls is the final turn.
-6. **Outcome.** The loop returns a `LoopOutcome`: the full `messages` array,
+7. **Outcome.** The loop returns a `LoopOutcome`: the full `messages` array,
    the final assistant message (or the last one seen), the last `ChatResult`
    on a real final, `turns_used`, and a `stopped_reason` of `final`, `budget`,
    or `aborted`.
-7. **Session persist.** `persist_session()` appends one `meta` record
+8. **Session persist.** `persist_session()` appends one `meta` record
    (`run_start`), then one `message` record per outcome message, then a
-   `budget_exhausted` meta record if the budget stopped the run, to a JSONL
-   file under `session_dir` (default `<work_dir>/.lich/sessions`). Persistence
-   is best-effort: failures are logged and the run still succeeds with
-   `session_path: undefined`.
-8. **Return.** `AgentRunResult` bundles the outcome, the full transcript
+   `budget_exhausted` meta record if the budget stopped the run, then a
+   `run_end` meta record (`stopped_reason`, `usage`) for every completed
+   run, to a JSONL file under `session_dir` (default
+   `<work_dir>/.lich/sessions`). Persistence is best-effort: failures are
+   logged and the run still succeeds with `session_path: undefined`.
+9. **Return.** `AgentRunResult` bundles the outcome, the full transcript
    (prior history plus the new exchange), the collected `usage_total`, and the
    session path.
 
@@ -149,8 +159,11 @@ Walkthrough of a single `Agent.run({ input })` call
 | Path | Responsibility |
 | --- | --- |
 | `src/index.ts` | Public library surface; pure re-exports plus `LICH_VERSION`. |
-| `src/cli.ts` | Zero-dependency CLI: one-shot, `chat`, `tui`, `gateway`, `config`. |
-| `src/cli_config.ts` | Config file discovery, loading, flag overrides, template. |
+| `src/cli.ts` | CLI: one-shot, `chat`, `tui`, `gateway`, `init`, `config`, `update`, `mcp`. |
+| `src/cli_config.ts` | Config file discovery, loading, flag overrides, template, writer. |
+| `src/cli_update.ts` | `lich update`: npm view, then `npm install -g` when newer. Git clones are told to `git pull`. |
+| `src/cli_mcp.ts` | `lich mcp` list/add/enable/disable/remove against work-dir config. |
+| `src/mcp/*` | MCP client: catalog, stdio/loopback HTTP, tool registration. |
 | `src/agent/agent.ts` | `Agent`: wires router, registry, executor; sessions; usage. |
 | `src/agent/loop.ts` | `run_conversation`: the think-act-observe loop. |
 | `src/agent/config.ts` | Zod config schema, defaults, derived `session_dir`, freeze. |
@@ -169,6 +182,7 @@ Walkthrough of a single `Agent.run({ input })` call
 | `src/tools/registry.ts` | Name-keyed tool registry; duplicate rejection. |
 | `src/tools/executor.ts` | Never-throw execution with timeout and abort. |
 | `src/tools/builtin/*` | Builtin tools, including `run_tests` (see [tools](./tools.md)). |
+| `src/plugins/*` | Plugin loader and hooks. Gatekeeper registers `git_commit` in code. |
 | `src/gateway/bus.ts` | Conversation-keyed runner over one shared `Agent`. |
 | `src/gateway/runner.ts` | Adapter construction, signal handling, process lifetime. |
 | `src/gateway/{telegram,discord,twitch,webhook}.ts` | Platform adapters. |

package/docs/architecture/plugins.md

@@ -59,7 +59,7 @@ sequenceDiagram
     end
 ```
 
-Lifecycle fan-outs live on the same wrapper: `Agent.run` calls `call_run_start({input_chars})` before `run_conversation` and `call_run_end({stopped_reason, turns_used})` after it (including the abort/throw path, via `finally`). Both are best-effort: hook throws are logged at `warn` and the run proceeds.
+Lifecycle fan-outs live on the same wrapper: `Agent.run` calls `call_run_start({input_chars})` before `run_conversation` and `call_run_end({stopped_reason, turns_used})` in `finally` only when the loop returned an outcome (`final`, `budget`, or `aborted`). A provider throw leaves `outcome` undefined, so `on_run_end` is skipped and no `run_end` session record is written. Both fan-outs are best-effort: hook throws are logged at `warn` and the run proceeds.
 
 ## Builtin gatekeeper
 

package/docs/architecture/tools.md

@@ -39,7 +39,9 @@ result either way.
 **`ToolContext`** gives each execution a working directory (`work_dir`, the
 confinement root), a process environment map (the agent injects
 `LICH_TERMINAL_TIMEOUT_MS`), and an abort `signal` that fires on caller abort
-**or** the executor's own 30 s deadline.
+**or** the executor deadline (`tool.timeout_ms`, else
+`DEFAULT_TOOL_TIMEOUT_MS` = 30000). `terminal` sets 300000, `run_tests` sets
+600000, and registered MCP tools set 120000.
 
 **Parameter schemas.** `parameters` is a `JsonSchemaObject`
 (`src/util/json_schema.ts`) passed through verbatim into provider requests.
@@ -187,6 +189,9 @@ instructions. See the [plugins guide](../user-guide/plugins.md#skills-and-memory
 - **Enabling a subset** is done by rebuilding a fresh registry: `Agent`'s
   `filter_registry` (src/agent/agent.ts) iterates `base.list()` and registers
   only allowed names onto a new `ToolRegistry` when `tools_enabled` is a list
-  (`"all"` returns the base registry untouched).
+  (`"all"` returns the base registry untouched). Plugin tools, including the
+  gatekeeper's `git_commit`, register after that filter, so `tools_enabled: []`
+  still leaves `git_commit`. MCP tools register later, on first `run()`, and
+  only when the allowlist is `"all"` or names an `mcp_` tool.
 
 For building your own tool, see [extending](./extending.md#add-a-builtin-tool).

package/docs/getting-started.md

@@ -10,12 +10,12 @@
 
 ```sh
 npm install -g @moikapy/lich
-lich --version   # -> 0.3.0
+lich --version   # -> 0.6.0 (reads package.json)
 ```
 
 ## Choose a configuration path
 
-Lich needs exactly one thing before it runs: a model. You can provide it three ways, and they can be mixed (flags override env vars, and both override the config file).
+Lich needs exactly one thing before it runs: a model. You can provide it three ways. Flags override a config file and override `LICH_*` env vars. Those env vars apply only when no config file is found; they are not merged into a discovered file.
 
 ### Path A: environment variables only
 
@@ -42,7 +42,7 @@ lich config > .lich/config.json
 
 `lich config` honors `LICH_PROVIDER_KIND` and `LICH_MODEL` when you have them set, and otherwise prints an ollama-oriented template. The file is picked up automatically from `.lich/config.json` in the working directory (or `~/.config/lich/config.json` as a fallback) — after this, plain `lich "task"` needs no env vars.
 
-`lich init` writes that same starter file for you (it creates `.lich/` and never overwrites an existing `.lich/config.json`). Bare `lich` on a TTY, with no config in that search chain and no `LICH_MODEL`, runs a setup wizard and writes `.lich/config.json` once before opening the TUI. `.lich/` is gitignored.
+`lich init` writes that same starter file for you (it creates `.lich/` and never overwrites an existing `.lich/config.json`). Bare `lich` on a TTY, with no config in that search chain, runs a setup wizard and writes `.lich/config.json` once before opening the TUI. `LICH_MODEL` / `--model` prefills the model prompt; it does not skip the wizard. Non-TTY stdin skips the wizard. `.lich/` is gitignored.
 
 ### Path C: an explicit config file
 
@@ -121,10 +121,10 @@ jq -r 'select(.kind=="message") | "\(.message.role): \(.message.content)"' .lich
 | Symptom | Cause and fix |
 | --- | --- |
 | `no model configured: set LICH_MODEL, pass --model, or create .lich/config.json` | No provider was resolvable. Set `LICH_MODEL`, pass `--model`, or save a config file (`lich init` or `lich config`). |
-| `lich: config not found: <path>` | `--config` was given a path that does not exist. Check the path or drop the flag to use discovery. |
+| `lich: cannot use config file <path>: ...` | `--config` was given a path that does not exist or is not readable JSON. Check the path or drop the flag to use discovery. |
 | Provider error `kind=auth`, http 401/403 | The api key is missing or wrong. Verify the env var named by `LICH_API_KEY_ENV` (default `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`) is exported in the same shell. |
 | `fetch failed` / connection refused | The endpoint is unreachable. For ollama, check `ollama serve` is running on `http://localhost:11434`; for remote APIs, check `LICH_BASE_URL`. |
-| `[lich] budget exhausted after N turns` | The task did not finish within `max_turns` (default 25). Raise it with `--max-turns 50` or in config. |
+| `[lich] budget exhausted after N turns — the ritual is spent` | The task did not finish within `max_turns` (default 25). The `budget exhausted` keyword stays; the flavor suffix comes from the theme. Raise the cap with `--max-turns 50` or in config. |
 | `unknown flag: --foo` | Flag typo, or the flag was placed where a subcommand is expected. Run `lich --help`. |
 
 ## Updating
@@ -153,7 +153,7 @@ To hack on Lich itself, run the CLI straight from a clone instead of the npm pac
 ```sh
 git clone https://github.com/Moikapy/lich.git && cd lich
 bun install
-bun src/cli.ts --version   # -> 0.3.0
+bun src/cli.ts --version   # -> 0.6.0 (package.json; MCP in this tree is unreleased)
 ```
 
 `bun src/cli.ts` accepts the same arguments as the installed `lich` binary, so every command on this page works unchanged.
@@ -163,4 +163,6 @@ bun src/cli.ts --version   # -> 0.3.0
 - All four CLI modes, flags, and provider resolution: [CLI reference](user-guide/cli.md).
 - Slash commands and the status bar: [TUI guide](user-guide/tui.md).
 - Telegram, Discord, Twitch, and webhook setup: [Gateway guide](user-guide/gateway.md).
-- Embedding the agent in your own TypeScript: [Library guide](user-guide/library.md).
+- Embedding the agent in your own TypeScript: [Library guide](user-guide/library.md).
+- Session JSONL as a combat log: [Games guide](user-guide/games.md).
+- Editor MCP (`lich mcp`, unreleased in the published 0.6.0 package): [Redot guide](user-guide/redot.md). Play is still the [Godot guide](user-guide/godot.md).

package/docs/index.md

@@ -8,7 +8,7 @@ outline: [2, 3]
 
 Lich is a TypeScript AI agent harness: a library and a CLI that run a chat model inside a Think-Act-Observe loop. A chat wrapper forwards one prompt and prints one completion. A harness keeps going: the model plans (think), calls tools such as `read_file` or `terminal` (act), reads the tool results (observe), and repeats until it can produce a final answer. Lich wraps that loop with the machinery real deployments need: provider failover with bounded retries, path confinement and output clamps on every tool, context compression when the transcript grows past a token budget, and append-only JSONL session transcripts.
 
-One package, four ways to drive the same agent: a one-shot CLI, an interactive chat REPL, an ink-based terminal UI, and a long-running messaging gateway that bridges Telegram, Discord, Twitch, and a zero-config HTTP webhook. All four share the same builtin tools, the same provider configuration, and the same session store.
+One package, four ways to drive the same agent: a one-shot CLI, an interactive chat REPL, an ink-based terminal UI, and a long-running messaging gateway that bridges Telegram, Discord, Twitch, and a zero-config HTTP webhook. All four share the same builtin tools, the same provider configuration, and the same session store. `lich init`, `lich config`, `lich update`, and `lich mcp` do not start that loop.
 
 ## Feature overview
 
@@ -18,7 +18,7 @@ One package, four ways to drive the same agent: a one-shot CLI, an interactive c
 | Tools | Builtins (file read/write/edit, directory listing, shell, grep, HTTP fetch/request, web search, process list, disk usage, env inspection, `run_tests`), all confined to the working directory. `git_commit` is the gatekeeper's tool, not a config plugin. |
 | Context compression | Transcript summarized in place when estimated tokens cross `compress_threshold` of `context_budget_tokens`; the 8 most recent turns always stay verbatim. |
 | Sessions | Every run persists a `.jsonl` transcript under `.lich/sessions/`, labeled by origin (`tui`, `gw:<platform>:<chat>`). |
-| CLI | One-shot tasks, chat REPL, TUI, gateway, and a `config` template command, all with flag/env/config-file configuration. |
+| CLI | One-shot tasks, chat REPL, TUI, gateway, `init`, `update`, `config`, and (in this source) `lich mcp`. Flag, env, and config-file configuration. |
 | TUI | Live ink transcript with tool-call rows, status bar (model, turns, tokens, session path), and slash commands. |
 | Gateway | One shared agent behind webhook/Telegram/Discord/Twitch with per-conversation memory (40-message history cap) and per-platform message splitting. |
 | Library | `create_agent` / `run_agent` with typed events (`AgentEmitter`), multi-turn history, and `ProviderError` kinds for error handling. |
@@ -29,12 +29,14 @@ One package, four ways to drive the same agent: a one-shot CLI, an interactive c
 | Page | Read it to |
 | --- | --- |
 | [Getting started](getting-started.md) | Install, configure a provider, and get your first reply in any mode. |
-| [CLI reference](user-guide/cli.md) | Master all four modes, flags, provider resolution, and config files. |
+| [CLI reference](user-guide/cli.md) | Modes, flags, provider resolution, config files, and `lich mcp`. |
 | [TUI guide](user-guide/tui.md) | Run the terminal UI and use slash commands and the status bar. |
 | [Gateway guide](user-guide/gateway.md) | Wire Telegram, Discord, Twitch, and the HTTP webhook to one agent. |
 | [Library guide](user-guide/library.md) | Embed the agent in TypeScript with events and multi-turn history. |
 | [Plugins guide](user-guide/plugins.md) | Add your own tools and lifecycle hooks, and run the self-improvement loop. |
 | [Godot guide](user-guide/godot.md) | Run lich beside a Godot game and drain `.lich/game/` orders each tick. |
+| [Redot guide](user-guide/redot.md) | Add editor MCP servers (Redot catalog entry). Play still uses the game bridge, the opposite direction. |
+| [Games guide](user-guide/games.md) | Replay session JSONL as a combat log, including token totals. |
 | [Architecture overview](architecture/overview.md) | Understand how the harness works inside. |
 
 ## How it works
@@ -66,4 +68,4 @@ Working from a clone of the repository? `bun install`, then run the same command
 
 ## Version compatibility
 
-Documented for **v0.3.0**. The npm package requires Node >= 20 (`engines` in `package.json`); Bun is the recommended runtime for development from a clone (`bun src/cli.ts ...`). The TUI needs a TTY; the gateway and library run headless on both runtimes.
+The published npm package is **0.6.0**. `lich --version` reads `package.json`, so this tree also prints `0.6.0`. Editor MCP (`mcp_servers`, `lich mcp`) is in this source under changelog **0.7.0 (unreleased)** and is not in the published package. Node >= 20 (`engines` in `package.json`); Bun is the recommended runtime for development from a clone (`bun src/cli.ts ...`). The TUI needs a TTY; the gateway and library run headless on both runtimes.