lithe-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{lithe_cli-0.1.0 → lithe_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lithe-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Command-line interface for the lithe agent kernel: chat, one-shot runs, undo, and run inspection.
 License: MIT License
         
@@ -49,13 +49,14 @@ Dynamic: license-file
 
 [![PyPI](https://img.shields.io/pypi/v/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
-[![License: MIT](https://img.shields.io/pypi/l/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
+[![License: MIT](https://img.shields.io/pypi/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
 
 **lithe-cli** is the command-line interface for
 [lithe](https://pypi.org/project/lithe/) — the storage-free ReAct agent
 kernel. Installing it pulls in `lithe` automatically and gives you a `lithe`
 command: chat with an agent that reads and writes files in your workspace,
-run one-shot tasks, inspect stored runs, and undo a run's mutations.
+runs code, searches the web through MCP tools, inspects stored runs, and
+undoes a run's mutations.
 
 ```bash
 pip install lithe-cli
@@ -76,6 +77,10 @@ Flags (`--api-key`, `--base-url`, `--model`) override the environment.
 `LITHE_HOME` (default `~/.lithe`) locates the run store; the agent's
 workspace defaults to the current directory (`--workspace` to change).
 
+`lithe doctor` prints the effective configuration — endpoint (with a
+masked key), store, workspace, sandbox backend, skills, MCP servers — so
+you can see what a run would use before starting one.
+
 ## Use
 
 ### One-shot task
@@ -84,10 +89,11 @@ workspace defaults to the current directory (`--workspace` to change).
 $ cd my-project
 $ lithe run "总结 README.md 的要点，存到 SUMMARY.md"
   ⚒ read_file {"path": "README.md"}
-  ✓ 已读取 README.md（120 行）
+  ✓ 已读取 README.md（120 行） 0.1s
   ⚒ write_file {"path": "SUMMARY.md", "content": "..."}
-  ✓ 写入 SUMMARY.md
+  ✓ 写入 SUMMARY.md 0.0s
 已把要点写入 SUMMARY.md。
+── done · steps 3 · tokens 2100 · cost 0.0042
 ```
 
 `--stream` streams tokens as they generate; `-v` adds per-call
@@ -98,16 +104,40 @@ usage/context gauges; `--max-steps` caps the tool loop;
 
 ```bash
 $ lithe chat
-lithe 0.1.0 — /exit 退出，输入任务开始。
-lithe> 把 a.txt 改成三行待办清单
+╭──────────────────────────────────────╮
+│ lithe 0.2.0                          │
+│ model   your-model                   │
+│ workdir /home/me/my-project          │
+│ /help 查看会话命令，/exit 退出       │
+╰──────────────────────────────────────╯
+lithe ❯ 把 a.txt 改成三行待办清单
   ⚒ write_file {"path": "a.txt", ...}
-  ✓ 写入 a.txt
+  ✓ 写入 a.txt 0.0s
 已完成。
-lithe> /exit
+── done · steps 2 · tokens 180
+lithe ❯ /exit
 ```
 
 History carries across turns within a session (each turn is its own run in
-the store, replayed as context for the next).
+the store, replayed as context for the next). `/new` clears the session,
+`/tools` lists the registered tools, `/help` lists the commands.
+
+### Extra capabilities
+
+The kernel ships these as bundles; the CLI grants them per flag:
+
+| Flag | Tools granted | Notes |
+| --- | --- | --- |
+| `--code` | `run_code` / `run_file` | Python under bubblewrap when installed (passthrough otherwise); `doctor` shows which |
+| `--skills DIR` | `load_skill` | markdown skill library; defaults to `$LITHE_HOME/skills` when it exists, `--skills ""` disables |
+| `--download` | `download_file` | SSRF-guarded, size-capped network fetch |
+| `--vision` | `image_info` / `analyze_image` | image probe is stdlib-only; analysis routes one vision call to the main endpoint |
+| `--mcp SPEC` | whatever the servers expose | JSON array/object or `@file` (env `LITHE_MCP`); stdio and streamable-http; failed servers degrade gracefully |
+
+```bash
+$ lithe run --code "用 run_code 验证 results.csv 的行数"
+$ lithe chat --skills ~/my-skills --mcp @~/mcp.json
+```
 
 ### Undo a run
 
@@ -116,35 +146,47 @@ configuration:
 
 ```bash
 $ lithe runs                     # find the run
-abc123def456   done        steps=3  ...
+run           status  steps  cost  task
+────────────  ──────  ─────  ────  ────────────────
+abc123def456  done    3      0.01  总结 README.md …
 $ lithe undo abc123def456
-已撤销 2 个操作（run abc123def456）
+✓ 已撤销 2 个操作（run abc123def456）
 ```
 
 A file the run created is deleted; a file it overwrote is restored.
+(`run_code` side effects are not revertible — its tool description warns
+the model.)
 
 ### Inspect
 
 ```bash
 $ lithe runs                     # stored runs (newest last)
 $ lithe log abc123def456         # messages + actions of one run
+$ lithe doctor                   # config + capability status
 ```
 
 ### Tools
 
 ```bash
 $ lithe tools                    # what the agent can do
-apply_patch      WRITE  以行级 patch 一次修改多个文件...
-edit_file        WRITE  局部替换文件中的文本...
-read_file        READ   读取文件内容...
+tool          category  description
+────────────  ────────  ──────────────────────────────
+apply_patch   WRITE     以行级 patch 一次修改多个文件…
+read_file     READ      读取文件内容…
 ...
 ```
 
 The default tool set is the workspace bundle (`read_file` / `write_file` /
 `edit_file` / `list_files` / `search_files` / `glob_files` /
-`apply_patch`) plus todos (`update_todos` / `list_todos`).
-`--download` additionally grants `download_file` — the SSRF-guarded,
-size-capped network fetch — for runs and chats.
+`apply_patch`) plus todos (`update_todos` / `list_todos`); the flags above
+add capabilities. (MCP tools attach at run time, so `lithe tools` lists
+them only after a session has started the servers.)
+
+### Colors
+
+Output is colored when stdout is a TTY and `NO_COLOR` is unset; `--color`
+/ `--no-color` force either way. Rendering has zero dependencies — plain
+text degrades cleanly through pipes and cron.
 
 ## Where things land
 
@@ -153,6 +195,7 @@ size-capped network fetch — for runs and chats.
 | current dir (or `--workspace`) | the agent's sandboxed workspace — every tool path resolves strictly inside it |
 | `~/.lithe/runs` (or `--store`) | JSONL run store: messages, actions, undo records |
 | `~/.lithe/runs/todos-<user>.json` | the agent's task list |
+| `~/.lithe/skills` (or `--skills`) | the markdown skill library, when enabled |
 
 ## Design notes
 

lithe_cli-0.2.0/README.md

@@ -0,0 +1,164 @@
+# lithe-cli
+
+[![PyPI](https://img.shields.io/pypi/v/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
+[![License: MIT](https://img.shields.io/pypi/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
+
+**lithe-cli** is the command-line interface for
+[lithe](https://pypi.org/project/lithe/) — the storage-free ReAct agent
+kernel. Installing it pulls in `lithe` automatically and gives you a `lithe`
+command: chat with an agent that reads and writes files in your workspace,
+runs code, searches the web through MCP tools, inspects stored runs, and
+undoes a run's mutations.
+
+```bash
+pip install lithe-cli
+```
+
+## Configure
+
+There is no default endpoint — the CLI refuses to run rather than silently
+hitting some third-party URL. Point it at any OpenAI-compatible endpoint:
+
+```bash
+export LITHE_API_KEY=sk-...
+export LITHE_BASE_URL=https://your-endpoint/api/v1
+export LITHE_MODEL=your-model
+```
+
+Flags (`--api-key`, `--base-url`, `--model`) override the environment.
+`LITHE_HOME` (default `~/.lithe`) locates the run store; the agent's
+workspace defaults to the current directory (`--workspace` to change).
+
+`lithe doctor` prints the effective configuration — endpoint (with a
+masked key), store, workspace, sandbox backend, skills, MCP servers — so
+you can see what a run would use before starting one.
+
+## Use
+
+### One-shot task
+
+```bash
+$ cd my-project
+$ lithe run "总结 README.md 的要点，存到 SUMMARY.md"
+  ⚒ read_file {"path": "README.md"}
+  ✓ 已读取 README.md（120 行） 0.1s
+  ⚒ write_file {"path": "SUMMARY.md", "content": "..."}
+  ✓ 写入 SUMMARY.md 0.0s
+已把要点写入 SUMMARY.md。
+── done · steps 3 · tokens 2100 · cost 0.0042
+```
+
+`--stream` streams tokens as they generate; `-v` adds per-call
+usage/context gauges; `--max-steps` caps the tool loop;
+`--context-window` enables fullness gauges.
+
+### Interactive chat
+
+```bash
+$ lithe chat
+╭──────────────────────────────────────╮
+│ lithe 0.2.0                          │
+│ model   your-model                   │
+│ workdir /home/me/my-project          │
+│ /help 查看会话命令，/exit 退出       │
+╰──────────────────────────────────────╯
+lithe ❯ 把 a.txt 改成三行待办清单
+  ⚒ write_file {"path": "a.txt", ...}
+  ✓ 写入 a.txt 0.0s
+已完成。
+── done · steps 2 · tokens 180
+lithe ❯ /exit
+```
+
+History carries across turns within a session (each turn is its own run in
+the store, replayed as context for the next). `/new` clears the session,
+`/tools` lists the registered tools, `/help` lists the commands.
+
+### Extra capabilities
+
+The kernel ships these as bundles; the CLI grants them per flag:
+
+| Flag | Tools granted | Notes |
+| --- | --- | --- |
+| `--code` | `run_code` / `run_file` | Python under bubblewrap when installed (passthrough otherwise); `doctor` shows which |
+| `--skills DIR` | `load_skill` | markdown skill library; defaults to `$LITHE_HOME/skills` when it exists, `--skills ""` disables |
+| `--download` | `download_file` | SSRF-guarded, size-capped network fetch |
+| `--vision` | `image_info` / `analyze_image` | image probe is stdlib-only; analysis routes one vision call to the main endpoint |
+| `--mcp SPEC` | whatever the servers expose | JSON array/object or `@file` (env `LITHE_MCP`); stdio and streamable-http; failed servers degrade gracefully |
+
+```bash
+$ lithe run --code "用 run_code 验证 results.csv 的行数"
+$ lithe chat --skills ~/my-skills --mcp @~/mcp.json
+```
+
+### Undo a run
+
+The bundled file and todo tools register reverters, so undo works with zero
+configuration:
+
+```bash
+$ lithe runs                     # find the run
+run           status  steps  cost  task
+────────────  ──────  ─────  ────  ────────────────
+abc123def456  done    3      0.01  总结 README.md …
+$ lithe undo abc123def456
+✓ 已撤销 2 个操作（run abc123def456）
+```
+
+A file the run created is deleted; a file it overwrote is restored.
+(`run_code` side effects are not revertible — its tool description warns
+the model.)
+
+### Inspect
+
+```bash
+$ lithe runs                     # stored runs (newest last)
+$ lithe log abc123def456         # messages + actions of one run
+$ lithe doctor                   # config + capability status
+```
+
+### Tools
+
+```bash
+$ lithe tools                    # what the agent can do
+tool          category  description
+────────────  ────────  ──────────────────────────────
+apply_patch   WRITE     以行级 patch 一次修改多个文件…
+read_file     READ      读取文件内容…
+...
+```
+
+The default tool set is the workspace bundle (`read_file` / `write_file` /
+`edit_file` / `list_files` / `search_files` / `glob_files` /
+`apply_patch`) plus todos (`update_todos` / `list_todos`); the flags above
+add capabilities. (MCP tools attach at run time, so `lithe tools` lists
+them only after a session has started the servers.)
+
+### Colors
+
+Output is colored when stdout is a TTY and `NO_COLOR` is unset; `--color`
+/ `--no-color` force either way. Rendering has zero dependencies — plain
+text degrades cleanly through pipes and cron.
+
+## Where things land
+
+| Path | Contents |
+| --- | --- |
+| current dir (or `--workspace`) | the agent's sandboxed workspace — every tool path resolves strictly inside it |
+| `~/.lithe/runs` (or `--store`) | JSONL run store: messages, actions, undo records |
+| `~/.lithe/runs/todos-<user>.json` | the agent's task list |
+| `~/.lithe/skills` (or `--skills`) | the markdown skill library, when enabled |
+
+## Design notes
+
+- The CLI is a thin host: it supplies tools, a system prompt, and the
+  kernel's `JsonlRunStore`; everything else (ReAct loop, streaming, budgets,
+  replay, undo engine) is reused from lithe.
+- End-to-end behavior is tested offline against a scripted transport — no
+  test spends tokens.
+- `python -m lithe_cli` works alongside the `lithe` console script.
+
+## License
+
+MIT

{lithe_cli-0.1.0 → lithe_cli-0.2.0}/lithe_cli/__init__.py

@@ -1,3 +1,3 @@
 """lithe-cli: the command-line interface for the lithe agent kernel."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

lithe_cli-0.2.0/lithe_cli/agent.py

@@ -0,0 +1,207 @@
+"""Host wiring: tools, store, LLM config, and the event renderer.
+
+Everything here maps lithe's host contract onto CLI defaults:
+
+- workspace — the sandboxed file root the agent reads/writes (``--workspace``,
+  default the current directory);
+- store — ``JsonlRunStore`` under ``~/.lithe/runs`` (``--store``), the
+  kernel's zero-database default;
+- tools — the workspace bundle (read/write/edit/list/search/glob +
+  apply_patch) and todos, plus opt-in capabilities: ``--code`` (sandboxed
+  Python), ``--skills`` (markdown skill library), ``--vision`` (image
+  probe/analysis), ``--download`` (SSRF-guarded network fetch) and
+  ``--mcp`` (external MCP servers);
+- undo — the bundled tools register reverters, so ``lithe undo`` works with
+  zero configuration.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+import time
+import uuid
+from typing import Any
+
+from lithe import AgentContext, LLMConfig, ToolRegistry
+from lithe.bundles import (
+    AgentHost, JsonlRunStore, JsonTodoStore, Workspace, undo_run,
+)
+from lithe.bundles.download import register_download_tools
+from lithe.bundles.patch import register_apply_patch_tool
+from lithe.bundles.workspace import register_file_tools
+from lithe.bundles.todos import register_todo_tools
+
+from .config import Config
+from .ui import CYAN, GREEN, YELLOW, ui
+
+SYSTEM_PROMPT_BASE = (
+    "你是运行在命令行里的助理，工作区是用户的当前目录。"
+    "用提供的文件工具完成任务（读写前先读、谨慎修改），"
+    "需要多步任务时先用 update_todos 列出计划，最后用简洁中文汇报结果。"
+)
+
+
+def sandbox_backend() -> str:
+    """bwrap when present (full isolation), else passthrough."""
+    return "bwrap" if shutil.which("bwrap") else "passthrough"
+
+
+def build_system_prompt(cfg: Config) -> str:
+    """Base prompt plus one line per enabled capability."""
+    extras = []
+    if cfg.code:
+        extras.append("可以用 run_code 执行 Python 来验证想法、计算或测试。")
+    if cfg.download:
+        extras.append("可以用 download_file 下载网络文件到工作区。")
+    if cfg.skills_dir is not None:
+        extras.append("可以先 load_skill 查看可用技能并按需加载规范。")
+    if not extras:
+        return SYSTEM_PROMPT_BASE
+    return SYSTEM_PROMPT_BASE + "".join(extras)
+
+
+def build_llm(cfg: Config) -> LLMConfig:
+    return LLMConfig(
+        model=cfg.model or "unused",
+        base_url=cfg.base_url or "unused",
+        api_key=cfg.api_key or "unused",
+        timeout=cfg.timeout,
+        attempts=cfg.attempts,
+        stream=cfg.stream,
+        context_window=cfg.context_window,
+        transport=cfg.transport,
+    )
+
+
+def build_registry(cfg: Config) -> ToolRegistry:
+    """Register the CLI's tool set against the configured workspace."""
+    reg = ToolRegistry()
+
+    def workspace_for(ctx) -> Workspace:
+        return Workspace(cfg.workspace_dir.resolve())
+
+    register_file_tools(reg, workspace_for)
+    register_apply_patch_tool(reg, workspace_for)
+    todo_path = cfg.store_dir / f"todos-{cfg.user_id}.json"
+    register_todo_tools(reg, lambda ctx: JsonTodoStore(todo_path))
+    if cfg.download:
+        register_download_tools(reg, workspace_for)
+    if cfg.code:
+        from lithe.bundles.sandbox import CodeRunner, register_code_tools
+
+        runner = CodeRunner(sys.executable, backend=sandbox_backend())
+        register_code_tools(
+            reg, lambda ctx: str(cfg.workspace_dir.resolve()), runner)
+    if cfg.skills_dir is not None:
+        from lithe.bundles.skills import SkillLibrary, register_skill_tool
+
+        register_skill_tool(reg, SkillLibrary(cfg.skills_dir))
+    if cfg.vision:
+        from lithe.bundles.images import register_image_tools
+
+        register_image_tools(reg, workspace_for, llm_config=build_llm(cfg))
+    return reg
+
+
+def build_host(cfg: Config, reg: ToolRegistry) -> AgentHost:
+    """Build the AgentHost; the store lands under cfg.store_dir."""
+    store = JsonlRunStore(cfg.store_dir)
+    prompt = build_system_prompt(cfg)
+    return AgentHost(
+        reg, build_llm(cfg), store, max_steps=cfg.max_steps,
+        build_system_prompt=lambda ctx, mode, anchor: prompt,
+    )
+
+
+def render_event(
+    ev: dict, verbose: bool = False, stream: bool = False,
+    pending: dict | None = None,
+) -> None:
+    """Render one runtime event onto the terminal.
+
+    ``pending`` maps tool-call ids to their start time so results can show
+    elapsed seconds. ``stream`` suppresses the full-text echo of the final
+    answer when its tokens were already streamed.
+    """
+    t = ev.get("type")
+    pending = pending if pending is not None else {}
+    if t == "assistant_delta":
+        ui.delta(ev.get("text", ""))
+        pending["_deltas"] = pending.get("_deltas", 0) + 1
+    elif t == "assistant":
+        text = ev.get("text") or ""
+        # Streaming already showed every token; echoing the whole answer
+        # again would duplicate it.
+        if text and not (stream and pending.get("_deltas")):
+            ui.assistant(text)
+    elif t == "tool_call":
+        args = json.dumps(ev.get("args", {}), ensure_ascii=False)
+        ui.tool_call(str(ev.get("name")), args[:120])
+        if ev.get("id") is not None:
+            pending[ev["id"]] = time.monotonic()
+    elif t == "tool_result":
+        summary = (ev.get("summary") or "").replace("\n", " ")
+        started = pending.pop(ev.get("id"), None) if ev.get("id") else None
+        elapsed = (time.monotonic() - started) if started is not None else None
+        ui.tool_result(bool(ev.get("ok")), summary[:160], elapsed)
+    elif t == "error":
+        ui.error(str(ev.get("message", "")))
+    elif t == "cancelled":
+        ui.warn("已取消")
+    elif verbose and t == "usage":
+        print(ui.usage(ev.get("prompt_tokens"), ev.get("completion_tokens"),
+                       ev.get("context_tokens"), ev.get("context_percent")))
+    elif verbose and t == "reasoning":
+        digest = (ev.get("summary") or "").replace("\n", " ")
+        if digest:
+            print(ui.reasoning(digest[:120]))
+
+
+async def execute(
+    cfg: Config, task: str, history: list[dict] | None = None,
+    run_id: str | None = None,
+) -> tuple[str, dict, Any]:
+    """Run one task end-to-end; returns (run_id, done_event, host)."""
+    reg = build_registry(cfg)
+    host = build_host(cfg, reg)
+    rid = run_id or uuid.uuid4().hex[:12]
+    ctx = AgentContext(run_id=rid, user_id=cfg.user_id)
+    manager = None
+    if cfg.mcp_servers:
+        from lithe.bundles.mcp import MCPManager
+
+        manager = MCPManager(cfg.mcp_servers)
+        try:
+            report = await manager.attach(reg)
+        except Exception as exc:  # degrade gracefully, like the bundle
+            ui.error(f"MCP attach 失败：{exc}")
+            report = {}
+        for name, res in report.items():
+            if isinstance(res, list):
+                print(ui.s(f"  ⚙ MCP {name}: {len(res)} 个工具", CYAN))
+            else:
+                ui.error(f"MCP {name}: {res}")
+    ev: dict = {}
+    pending: dict[str, float] = {}
+    try:
+        async for ev in host.run(ctx, task, history=history):
+            render_event(ev, cfg.verbose, cfg.stream, pending)
+        if ev.get("type") == "done":
+            if cfg.stream and pending.get("_deltas"):
+                print()  # close the streaming line before the footer
+            ui.footer(ev)
+    finally:
+        if manager is not None:
+            await manager.close()
+    return rid, ev, host
+
+
+async def undo(cfg: Config, run_id: str) -> int:
+    """Revert a run's mutations with the bundled tools' reverters."""
+    reg = build_registry(cfg)
+    host = build_host(cfg, reg)
+    report = await undo_run(host, run_id, cfg.user_id)
+    mark = ui.s("✓", GREEN) if report.reverted else ui.s("·", YELLOW)
+    print(f"{mark} 已撤销 {report.reverted} 个操作（run {run_id}）")
+    return 0