@moikapy/lich 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -23,107 +23,6 @@ interface JsonSchemaObject {
     additionalProperties?: boolean;
 }
 
-interface ToolResult {
-    ok: boolean;
-    output: string;
-    error?: string;
-}
-interface ToolContext {
-    work_dir: string;
-    env: Record<string, string>;
-    signal?: AbortSignal;
-}
-interface Tool {
-    name: string;
-    description: string;
-    parameters: JsonSchemaObject;
-    /** Per-tool executor timeout override in ms; unset tools get the 30s default. */
-    timeout_ms?: number;
-    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
-}
-interface Toolset {
-    name: string;
-    tools: Tool[];
-}
-
-/**
- * Plugin surface: user-authored tools and lifecycle hooks loaded at startup.
- *
- * A plugin is a plain object exported from a TS/JS module. Hooks observe and
- * (in the case of before_tool_call) veto tool executions; tools merge into the
- * agent registry after builtin filtering.
- */
-
-/** Runtime info handed to every hook call. */
-interface HookContext {
-    work_dir: string;
-    /**
-     * This plugin's own per-run state sub-map. Every hook invocation receives
-     * a ctx exposing only the invoking plugin's bag; the bag is swapped fresh
-     * at each run start. Absent only on hand-built contexts outside the runner.
-     */
-    state?: Map<string, unknown>;
-}
-/** Argument passed to before_tool_call hooks. */
-interface BeforeToolCallInfo {
-    tool_name: string;
-    args: Record<string, unknown>;
-}
-/** Return value that vetoes a tool call; other hooks still run. */
-interface BeforeToolCallResult {
-    block?: boolean;
-    reason?: string;
-}
-/** Argument passed to after_tool_call hooks. */
-interface AfterToolCallInfo extends BeforeToolCallInfo {
-    result_summary: string;
-    /** Structured executor outcome; gate on this, never parse result_summary. */
-    ok: boolean;
-    error?: string;
-}
-interface RunEndInfo {
-    stopped_reason: string;
-    turns_used: number;
-}
-/** Optional lifecycle hooks a plugin may implement. All hooks are awaited. */
-interface PluginHooks {
-    before_tool_call?(info: BeforeToolCallInfo, ctx: HookContext): Promise<BeforeToolCallResult | void> | BeforeToolCallResult | void;
-    after_tool_call?(info: AfterToolCallInfo, ctx: HookContext): Promise<void> | void;
-    on_run_start?(info: {
-        input_chars: number;
-    }, ctx: HookContext): Promise<void> | void;
-    on_run_end?(info: RunEndInfo, ctx: HookContext): Promise<void> | void;
-}
-/** A user plugin: required unique name, optional tools and hooks. */
-interface Plugin {
-    name: string;
-    version?: string;
-    tools?: Tool[];
-    hooks?: PluginHooks;
-}
-
-/** A successfully loaded plugin plus the entry path it came from. */
-interface LoadedPlugin {
-    plugin: Plugin;
-    entry: string;
-}
-/** One failed entry: the specifier and why it failed. */
-interface PluginLoadError {
-    entry: string;
-    error_message: string;
-}
-/**
- * Load plugins from explicit entry paths (relative to `base_dir` or absolute).
- * Broken imports, missing exports, and duplicate names become error entries;
- * nothing is thrown for a bad plugin.
- */
-declare function load_plugins(entries: readonly string[], base_dir: string): Promise<{
-    plugins: LoadedPlugin[];
-    errors: PluginLoadError[];
-}>;
-/** Joined one-liner per load error, for a single warn log. */
-declare function plugin_errors_summary(errors: readonly PluginLoadError[]): string;
-
 type FinishReason = "stop" | "tool_calls" | "length" | "error" | "unknown";
 type ProviderErrorKind = "rate_limit" | "network" | "auth" | "overflow" | "bad_request" | "unknown";
 interface ToolCall {
@@ -270,10 +169,52 @@ declare const agent_config_schema: z.ZodEffects<z.ZodObject<{
     }>>;
     log_level: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
     theme: z.ZodDefault<z.ZodString>;
+    /** Named MCP servers. Each entry is stdio or loopback http. Default off. */
+    mcp_servers: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        command: string;
+        args: string[];
+        env?: Record<string, string> | undefined;
+    }, {
+        command: string;
+        enabled?: boolean | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>, z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        url: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        url: string;
+        enabled: boolean;
+    }, {
+        url: string;
+        enabled?: boolean | undefined;
+    }>]>>, Record<string, {
+        enabled: boolean;
+        command: string;
+        args: string[];
+        env?: Record<string, string> | undefined;
+    } | {
+        url: string;
+        enabled: boolean;
+    }>, Record<string, {
+        command: string;
+        enabled?: boolean | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    } | {
+        url: string;
+        enabled?: boolean | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
-    plugins: string[];
-    agent_name: string;
     max_turns: number;
+    log_level: "debug" | "info" | "warn" | "error";
+    theme: string;
     providers: z.objectOutputType<{
         kind: z.ZodEnum<["openai_compat", "anthropic", "ollama"]>;
         name: z.ZodString;
@@ -285,21 +226,30 @@ declare const agent_config_schema: z.ZodEffects<z.ZodObject<{
         /** Injectable fetch, mainly for tests; passes through untouched. */
         fetch_fn: z.ZodOptional<z.ZodType<typeof fetch, z.ZodTypeDef, typeof fetch>>;
     }, z.ZodTypeAny, "passthrough">[];
+    agent_name: string;
     tools_enabled: string[] | "all";
     context_budget_tokens: number;
     compress_threshold: number;
     terminal_timeout_ms: number;
-    log_level: "debug" | "info" | "warn" | "error";
-    theme: string;
-    temperature?: number | undefined;
-    max_tokens?: number | undefined;
-    system_prompt?: string | undefined;
+    plugins: string[];
     work_dir?: string | undefined;
+    system_prompt?: string | undefined;
     session_dir?: string | undefined;
     gateway?: {
         platforms: ("webhook" | "telegram" | "discord" | "twitch")[];
         token_envs: Record<string, string>;
     } | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    mcp_servers?: Record<string, {
+        enabled: boolean;
+        command: string;
+        args: string[];
+        env?: Record<string, string> | undefined;
+    } | {
+        url: string;
+        enabled: boolean;
+    }> | undefined;
 }, {
     providers: z.objectInputType<{
         kind: z.ZodEnum<["openai_compat", "anthropic", "ollama"]>;
@@ -312,44 +262,62 @@ declare const agent_config_schema: z.ZodEffects<z.ZodObject<{
         /** Injectable fetch, mainly for tests; passes through untouched. */
         fetch_fn: z.ZodOptional<z.ZodType<typeof fetch, z.ZodTypeDef, typeof fetch>>;
     }, z.ZodTypeAny, "passthrough">[];
-    plugins?: string[] | undefined;
-    temperature?: number | undefined;
-    max_tokens?: number | undefined;
-    agent_name?: string | undefined;
-    system_prompt?: string | undefined;
-    max_turns?: number | undefined;
     work_dir?: string | undefined;
-    tools_enabled?: string[] | "all" | undefined;
-    context_budget_tokens?: number | undefined;
-    compress_threshold?: number | undefined;
+    max_turns?: number | undefined;
+    system_prompt?: string | undefined;
     session_dir?: string | undefined;
-    terminal_timeout_ms?: number | undefined;
+    log_level?: "debug" | "info" | "warn" | "error" | undefined;
+    theme?: string | undefined;
     gateway?: {
         platforms?: ("webhook" | "telegram" | "discord" | "twitch")[] | undefined;
         token_envs?: Record<string, string> | undefined;
     } | undefined;
-    log_level?: "debug" | "info" | "warn" | "error" | undefined;
-    theme?: string | undefined;
+    agent_name?: string | undefined;
+    tools_enabled?: string[] | "all" | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    context_budget_tokens?: number | undefined;
+    compress_threshold?: number | undefined;
+    terminal_timeout_ms?: number | undefined;
+    plugins?: string[] | undefined;
+    mcp_servers?: Record<string, {
+        command: string;
+        enabled?: boolean | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    } | {
+        url: string;
+        enabled?: boolean | undefined;
+    }> | undefined;
 }>, {
     work_dir: string;
     providers: ProviderConfig[];
     session_dir: string;
-    plugins: string[];
-    agent_name: string;
     max_turns: number;
+    log_level: "debug" | "info" | "warn" | "error";
+    theme: string;
+    agent_name: string;
     tools_enabled: string[] | "all";
     context_budget_tokens: number;
     compress_threshold: number;
     terminal_timeout_ms: number;
-    log_level: "debug" | "info" | "warn" | "error";
-    theme: string;
-    temperature?: number | undefined;
-    max_tokens?: number | undefined;
+    plugins: string[];
     system_prompt?: string | undefined;
     gateway?: {
         platforms: ("webhook" | "telegram" | "discord" | "twitch")[];
         token_envs: Record<string, string>;
     } | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    mcp_servers?: Record<string, {
+        enabled: boolean;
+        command: string;
+        args: string[];
+        env?: Record<string, string> | undefined;
+    } | {
+        url: string;
+        enabled: boolean;
+    }> | undefined;
 }, {
     providers: z.objectInputType<{
         kind: z.ZodEnum<["openai_compat", "anthropic", "ollama"]>;
@@ -362,28 +330,172 @@ declare const agent_config_schema: z.ZodEffects<z.ZodObject<{
         /** Injectable fetch, mainly for tests; passes through untouched. */
         fetch_fn: z.ZodOptional<z.ZodType<typeof fetch, z.ZodTypeDef, typeof fetch>>;
     }, z.ZodTypeAny, "passthrough">[];
-    plugins?: string[] | undefined;
-    temperature?: number | undefined;
-    max_tokens?: number | undefined;
-    agent_name?: string | undefined;
-    system_prompt?: string | undefined;
-    max_turns?: number | undefined;
     work_dir?: string | undefined;
-    tools_enabled?: string[] | "all" | undefined;
-    context_budget_tokens?: number | undefined;
-    compress_threshold?: number | undefined;
+    max_turns?: number | undefined;
+    system_prompt?: string | undefined;
     session_dir?: string | undefined;
-    terminal_timeout_ms?: number | undefined;
+    log_level?: "debug" | "info" | "warn" | "error" | undefined;
+    theme?: string | undefined;
     gateway?: {
         platforms?: ("webhook" | "telegram" | "discord" | "twitch")[] | undefined;
         token_envs?: Record<string, string> | undefined;
     } | undefined;
-    log_level?: "debug" | "info" | "warn" | "error" | undefined;
-    theme?: string | undefined;
+    agent_name?: string | undefined;
+    tools_enabled?: string[] | "all" | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    context_budget_tokens?: number | undefined;
+    compress_threshold?: number | undefined;
+    terminal_timeout_ms?: number | undefined;
+    plugins?: string[] | undefined;
+    mcp_servers?: Record<string, {
+        command: string;
+        enabled?: boolean | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    } | {
+        url: string;
+        enabled?: boolean | undefined;
+    }> | undefined;
 }>;
 type AgentConfig = z.infer<typeof agent_config_schema>;
 declare function parse_agent_config(raw: unknown): AgentConfig;
 
+interface ToolResult {
+    ok: boolean;
+    output: string;
+    error?: string;
+}
+interface ToolContext {
+    work_dir: string;
+    env: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface Tool {
+    name: string;
+    description: string;
+    parameters: JsonSchemaObject;
+    /** Per-tool executor timeout override in ms; unset tools get the 30s default. */
+    timeout_ms?: number;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
+}
+interface Toolset {
+    name: string;
+    tools: Tool[];
+}
+
+/**
+ * Name-keyed registry of tools and toolsets. Registration rejects duplicate
+ * tool names so conflicting builtins fail loudly at startup.
+ */
+declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool): void;
+    register_toolset(toolset: Toolset): void;
+    get(name: string): Tool | undefined;
+    has(name: string): boolean;
+    list(): Tool[];
+    /** Map registered tools onto the provider-facing wire shape. */
+    definitions(): ToolDefinition[];
+}
+
+interface LineChild {
+    write_line(line: string): void;
+    read_line(): Promise<string | undefined>;
+    stop(): void;
+    failed(): string | undefined;
+}
+type LineSpawner = (command: string, args: readonly string[], env?: Record<string, string>) => LineChild;
+
+/**
+ * Discover tools/list for each enabled server and register mcp_<server>_<tool>.
+ * tools_enabled filters them. An empty allowlist never connects.
+ */
+
+interface McpRuntime {
+    spawn?: LineSpawner;
+    fetch_fn?: typeof fetch;
+    env_path?: string;
+}
+
+/**
+ * Plugin surface: user-authored tools and lifecycle hooks loaded at startup.
+ *
+ * A plugin is a plain object exported from a TS/JS module. Hooks observe and
+ * (in the case of before_tool_call) veto tool executions; tools merge into the
+ * agent registry after builtin filtering.
+ */
+
+/** Runtime info handed to every hook call. */
+interface HookContext {
+    work_dir: string;
+    /**
+     * This plugin's own per-run state sub-map. Every hook invocation receives
+     * a ctx exposing only the invoking plugin's bag; the bag is swapped fresh
+     * at each run start. Absent only on hand-built contexts outside the runner.
+     */
+    state?: Map<string, unknown>;
+}
+/** Argument passed to before_tool_call hooks. */
+interface BeforeToolCallInfo {
+    tool_name: string;
+    args: Record<string, unknown>;
+}
+/** Return value that vetoes a tool call; other hooks still run. */
+interface BeforeToolCallResult {
+    block?: boolean;
+    reason?: string;
+}
+/** Argument passed to after_tool_call hooks. */
+interface AfterToolCallInfo extends BeforeToolCallInfo {
+    result_summary: string;
+    /** Structured executor outcome; gate on this, never parse result_summary. */
+    ok: boolean;
+    error?: string;
+}
+interface RunEndInfo {
+    stopped_reason: string;
+    turns_used: number;
+}
+/** Optional lifecycle hooks a plugin may implement. All hooks are awaited. */
+interface PluginHooks {
+    before_tool_call?(info: BeforeToolCallInfo, ctx: HookContext): Promise<BeforeToolCallResult | void> | BeforeToolCallResult | void;
+    after_tool_call?(info: AfterToolCallInfo, ctx: HookContext): Promise<void> | void;
+    on_run_start?(info: {
+        input_chars: number;
+    }, ctx: HookContext): Promise<void> | void;
+    on_run_end?(info: RunEndInfo, ctx: HookContext): Promise<void> | void;
+}
+/** A user plugin: required unique name, optional tools and hooks. */
+interface Plugin {
+    name: string;
+    version?: string;
+    tools?: Tool[];
+    hooks?: PluginHooks;
+}
+
+/** A successfully loaded plugin plus the entry path it came from. */
+interface LoadedPlugin {
+    plugin: Plugin;
+    entry: string;
+}
+/** One failed entry: the specifier and why it failed. */
+interface PluginLoadError {
+    entry: string;
+    error_message: string;
+}
+/**
+ * Load plugins from explicit entry paths (relative to `base_dir` or absolute).
+ * Broken imports, missing exports, and duplicate names become error entries;
+ * nothing is thrown for a bad plugin.
+ */
+declare function load_plugins(entries: readonly string[], base_dir: string): Promise<{
+    plugins: LoadedPlugin[];
+    errors: PluginLoadError[];
+}>;
+/** Joined one-liner per load error, for a single warn log. */
+declare function plugin_errors_summary(errors: readonly PluginLoadError[]): string;
+
 /**
  * Typed event emitter for the agent loop.
  *
@@ -492,8 +604,14 @@ declare class Agent {
     private readonly registry;
     private readonly executor;
     private readonly hook_runner;
-    constructor(config: AgentConfig, plugins?: readonly LoadedPlugin[]);
+    private readonly mcp_runtime;
+    private mcp_attached;
+    constructor(config: AgentConfig, plugins?: readonly LoadedPlugin[], runtime?: {
+        mcp?: McpRuntime;
+    });
     run(options: AgentRunOptions): Promise<AgentRunResult>;
+    /** tools/list once, before the model sees definitions. Empty allowlists never connect. */
+    private attach_mcp_once;
     /** Per-run deps: the built-once ToolContext threads through every tool execution. */
     private loop_deps;
     /** Best-effort on_run_start fan-out; hook errors are logged, never fatal. */
@@ -511,20 +629,8 @@ declare function run_agent(raw_config: unknown, input: string, options?: {
     label?: string;
 }): Promise<AgentRunResult>;
 
-/**
- * Name-keyed registry of tools and toolsets. Registration rejects duplicate
- * tool names so conflicting builtins fail loudly at startup.
- */
-declare class ToolRegistry {
-    private readonly tools;
-    register(tool: Tool): void;
-    register_toolset(toolset: Toolset): void;
-    get(name: string): Tool | undefined;
-    has(name: string): boolean;
-    list(): Tool[];
-    /** Map registered tools onto the provider-facing wire shape. */
-    definitions(): ToolDefinition[];
-}
+/** Write the client entry. The user sets enabled. Godot has nothing to write. */
+declare function catalog_client_entry(name: string, substitutes?: Record<string, string>): Record<string, unknown> | string;
 
 interface ExecutorDefaults {
     work_dir?: string;
@@ -588,4 +694,4 @@ declare class HookedToolRunner {
 
 declare const LICH_VERSION: string;
 
-export { type AfterToolCallInfo, Agent, type AgentConfig, AgentEmitter, type AgentEvent, type AgentEventHandler, type AgentEvents, type AgentRunOptions, type AgentRunResult, type BeforeToolCallInfo, type BeforeToolCallResult, type ChatOptions, type ChatResult, type HookContext, HookedToolRunner, LICH_VERSION, type LoadedPlugin, type LoopOutcome, type LoopParams, type Message, type Plugin, type PluginHooks, type PluginLoadError, type ProviderConfig, ProviderError, type RunEndInfo, type Tool, type ToolCall, type ToolContext, type ToolDefinition, ToolExecutor, ToolRegistry, type ToolResult, type Usage, create_agent, create_agent_with_plugins, load_plugins, parse_agent_config, plugin_errors_summary, register_builtin_tools, run_agent };
+export { type AfterToolCallInfo, Agent, type AgentConfig, AgentEmitter, type AgentEvent, type AgentEventHandler, type AgentEvents, type AgentRunOptions, type AgentRunResult, type BeforeToolCallInfo, type BeforeToolCallResult, type ChatOptions, type ChatResult, type HookContext, HookedToolRunner, LICH_VERSION, type LoadedPlugin, type LoopOutcome, type LoopParams, type Message, type Plugin, type PluginHooks, type PluginLoadError, type ProviderConfig, ProviderError, type RunEndInfo, type Tool, type ToolCall, type ToolContext, type ToolDefinition, ToolExecutor, ToolRegistry, type ToolResult, type Usage, catalog_client_entry, create_agent, create_agent_with_plugins, load_plugins, parse_agent_config, plugin_errors_summary, register_builtin_tools, run_agent };

package/dist/index.js

@@ -1,6 +1,7 @@
 import {
-  LICH_VERSION
-} from "./chunk-6M6OAQGN.js";
+  LICH_VERSION,
+  catalog_client_entry
+} from "./chunk-SAEB3QL3.js";
 import {
   Agent,
   AgentEmitter,
@@ -15,7 +16,7 @@ import {
   plugin_errors_summary,
   register_builtin_tools,
   run_agent
-} from "./chunk-7HLVKVIG.js";
+} from "./chunk-QVJCIZIF.js";
 export {
   Agent,
   AgentEmitter,
@@ -24,6 +25,7 @@ export {
   ProviderError,
   ToolExecutor,
   ToolRegistry,
+  catalog_client_entry,
   create_agent,
   create_agent_with_plugins,
   load_plugins,

package/dist/{tui-LOUJVZ6A.js → tui-L6RABP2J.js}

@@ -1,14 +1,14 @@
 import {
   fill_template,
   load_theme
-} from "./chunk-JC2G3XH2.js";
+} from "./chunk-JYURFAGB.js";
 import {
   LICH_VERSION
-} from "./chunk-6M6OAQGN.js";
+} from "./chunk-SAEB3QL3.js";
 import {
   create_agent_with_plugins,
   truncate_text
-} from "./chunk-7HLVKVIG.js";
+} from "./chunk-QVJCIZIF.js";
 
 // src/tui.tsx
 import { render } from "ink";
@@ -435,4 +435,4 @@ async function run_tui(config) {
 export {
   run_tui
 };
-//# sourceMappingURL=tui-LOUJVZ6A.js.map
+//# sourceMappingURL=tui-L6RABP2J.js.map

package/docs/.vitepress/config.mts

@@ -29,6 +29,9 @@ export default defineConfig({
           { text: 'TUI guide', link: '/user-guide/tui' },
           { text: 'Gateway guide', link: '/user-guide/gateway' },
           { 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' }
         ]
       },
@@ -39,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/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,36 +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, 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`.
-8. **Return.** `AgentRunResult` bundles the outcome, the full transcript
+9. **Return.** `AgentRunResult` bundles the outcome, the full transcript
    (prior history plus the new exchange), the collected `usage_total`, and the
    session path.
 
@@ -150,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. |
@@ -170,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. |