paimon 0.2.5__tar.gz → 0.2.7__tar.gz

{paimon-0.2.5/paimon.egg-info → paimon-0.2.7}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: paimon
-Version: 0.2.5
+Version: 0.2.7
 Summary: A minimal code agent built on pydantic-ai + textual
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.27
-Requires-Dist: pydantic-ai-slim[anthropic,openai]>=2.31.0
+Requires-Dist: pydantic-ai-slim[anthropic,openai]>=2.38.0
 Requires-Dist: textual>=8.2.7
 Requires-Dist: textual-serve>=1.1.3
 Requires-Dist: pyyaml>=6
+Requires-Dist: ddgs>=9
 Dynamic: license-file
 
 # Paimon
@@ -40,9 +41,13 @@ uvx paimon
 
 The first launch asks for a provider, model, API base and key. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
 
-While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
 
-`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. Paimon can open panes itself: ask for two independent things and it starts a second agent in its own tab. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. Paimon can work in parallel: ask for two independent things and it starts a second agent in the background, whose answer comes back into the conversation when it is done. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
+
+## Web search
+
+Paimon can search the web without an API key. It asks in no permission mode, because a search changes nothing on your machine. Searches go through [ddgs](https://github.com/deedy5/ddgs), a metasearch library, so a query may be sent to any of several public search engines. `--no-web-search` takes the tool away for a run.
 
 ## Skills
 
@@ -102,6 +107,7 @@ paimon log a1b2c3    # what a session did, one line per event
 ```bash
 paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
 paimon --strict                     # ask before every command, even read-only ones
+paimon --no-web-search              # take the web search tool away for this run
 paimon --web                        # the same UI in a browser (--port, default 8000)
 paimon -p "what does cli.py do?"    # one answer on stdout, no UI
 cat log.txt | paimon -p "summarize this"
@@ -111,12 +117,95 @@ paimon --profile work               # a separately configured account
 
 `-p` never stops to ask, so with the default `yolo` mode it can already write files and run commands. Add `--output-format result` for a single JSON object with the outcome, which is what a calling program should read. `paimon --help` lists the rest.
 
-## Configuration
+Inside a [Herdr](https://herdr.dev) pane the UI reports its state and resume command to Herdr on its own, with nothing to install.
 
-Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`, written by the first launch or by `paimon login`. Sessions live in `~/.local/share/paimon/sessions/`. File changes render nicer if [delta](https://github.com/dandavison/delta) is installed.
+## Configuration
 
-Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`, written by the first launch or by `paimon login`. Sessions live in `~/.local/share/paimon/sessions/`.
+
+Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. On Windows, where cmd.exe runs the commands, every command asks. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+
+## Architecture
+
+`Agent.run` is a UI-agnostic stream of events; the TUI, `--web` and headless mode are three renderers over that one stream. An agent holds the subagents and background commands it starts. A subagent is another `Agent` running as a task in the same process, and its answer is delivered to its parent as a message.
+
+```mermaid
+flowchart TD
+    subgraph entry["Entry points"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / sessions"]
+        Headless["headless.py<br/>-p, one-shot"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI widgets"]
+        Pane["pane.py<br/>SessionPane"]
+        CommandPane["commandpane.py<br/>background command pane"]
+        Tabs["tabs.py<br/>pane strip"]
+        Login["login.py<br/>provider / model / key"]
+        UIWidgets["ui.py<br/>prompt input, confirmations"]
+        Diff["diff.py<br/>side-by-side diff rendering"]
+    end
+
+    subgraph core["Agent loop"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        ModelWindows["model_windows.py<br/>context window sizes"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        Jobs["turns.py<br/>turn driver"]
+    end
+
+    subgraph support["Config & skills"]
+        Config["config.py<br/>profiles, credentials"]
+        Skills["skills.py<br/>Agent Skills discovery"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Config
+
+    Pane --> Jobs
+    Pane --> AgentLoop
+    Pane --> Diff
+    Pane --> UIWidgets
+    Pane --> LLM
+    CommandPane --> Pane
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "run_background" .-> CommandPane
+
+    PromptMod --> Skills
+    Compaction --> ModelWindows
+
+    Jobs --> AgentLoop
+
+    Skills --> Config
+    Config --> LLM
+```
 
 ## Telemetry
 
-Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.
+Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name, the language from `LC_ALL`/`LANG`, whether this is the first launch, and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

{paimon-0.2.5 → paimon-0.2.7}/README.md

@@ -26,9 +26,13 @@ uvx paimon
 
 The first launch asks for a provider, model, API base and key. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
 
-While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
 
-`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. Paimon can open panes itself: ask for two independent things and it starts a second agent in its own tab. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. Paimon can work in parallel: ask for two independent things and it starts a second agent in the background, whose answer comes back into the conversation when it is done. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
+
+## Web search
+
+Paimon can search the web without an API key. It asks in no permission mode, because a search changes nothing on your machine. Searches go through [ddgs](https://github.com/deedy5/ddgs), a metasearch library, so a query may be sent to any of several public search engines. `--no-web-search` takes the tool away for a run.
 
 ## Skills
 
@@ -88,6 +92,7 @@ paimon log a1b2c3    # what a session did, one line per event
 ```bash
 paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
 paimon --strict                     # ask before every command, even read-only ones
+paimon --no-web-search              # take the web search tool away for this run
 paimon --web                        # the same UI in a browser (--port, default 8000)
 paimon -p "what does cli.py do?"    # one answer on stdout, no UI
 cat log.txt | paimon -p "summarize this"
@@ -97,12 +102,95 @@ paimon --profile work               # a separately configured account
 
 `-p` never stops to ask, so with the default `yolo` mode it can already write files and run commands. Add `--output-format result` for a single JSON object with the outcome, which is what a calling program should read. `paimon --help` lists the rest.
 
-## Configuration
+Inside a [Herdr](https://herdr.dev) pane the UI reports its state and resume command to Herdr on its own, with nothing to install.
 
-Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`, written by the first launch or by `paimon login`. Sessions live in `~/.local/share/paimon/sessions/`. File changes render nicer if [delta](https://github.com/dandavison/delta) is installed.
+## Configuration
 
-Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`, written by the first launch or by `paimon login`. Sessions live in `~/.local/share/paimon/sessions/`.
+
+Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. On Windows, where cmd.exe runs the commands, every command asks. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+
+## Architecture
+
+`Agent.run` is a UI-agnostic stream of events; the TUI, `--web` and headless mode are three renderers over that one stream. An agent holds the subagents and background commands it starts. A subagent is another `Agent` running as a task in the same process, and its answer is delivered to its parent as a message.
+
+```mermaid
+flowchart TD
+    subgraph entry["Entry points"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / sessions"]
+        Headless["headless.py<br/>-p, one-shot"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI widgets"]
+        Pane["pane.py<br/>SessionPane"]
+        CommandPane["commandpane.py<br/>background command pane"]
+        Tabs["tabs.py<br/>pane strip"]
+        Login["login.py<br/>provider / model / key"]
+        UIWidgets["ui.py<br/>prompt input, confirmations"]
+        Diff["diff.py<br/>side-by-side diff rendering"]
+    end
+
+    subgraph core["Agent loop"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        ModelWindows["model_windows.py<br/>context window sizes"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        Jobs["turns.py<br/>turn driver"]
+    end
+
+    subgraph support["Config & skills"]
+        Config["config.py<br/>profiles, credentials"]
+        Skills["skills.py<br/>Agent Skills discovery"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Config
+
+    Pane --> Jobs
+    Pane --> AgentLoop
+    Pane --> Diff
+    Pane --> UIWidgets
+    Pane --> LLM
+    CommandPane --> Pane
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "run_background" .-> CommandPane
+
+    PromptMod --> Skills
+    Compaction --> ModelWindows
+
+    Jobs --> AgentLoop
+
+    Skills --> Config
+    Config --> LLM
+```
 
 ## Telemetry
 
-Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.
+Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name, the language from `LC_ALL`/`LANG`, whether this is the first launch, and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

{paimon-0.2.5 → paimon-0.2.7}/README.zh-CN.md

@@ -26,9 +26,13 @@ uvx paimon
 
 首次启动会询问 provider、模型、API base 和 key。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
 
-运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。
+运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。以 `!` 开头的一行不发给模型，而是直接在 shell 里执行，输出 Paimon 也能看到。`!!` 则不告诉它。
 
-`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 自己也能开 pane：让它同时做两件互不相干的事，它会在新 tab 里起第二个 agent。它也能把一条命令留在单独的 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
+`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 也能并行干活：让它同时做两件互不相干的事，它会在后台起第二个 agent，做完后结果会回到当前会话里。它也能把一条命令留在单独的 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
+
+## 网页搜索
+
+Paimon 可以搜索网页，不需要 API key。任何权限模式下都不会询问，因为搜索不会改动本机的任何东西。搜索通过元搜索库 [ddgs](https://github.com/deedy5/ddgs) 进行，所以一条 query 可能被发往多个公共搜索引擎中的任意一个。`--no-web-search` 可以在本次运行中去掉这个工具。
 
 ## Skills
 
@@ -88,6 +92,7 @@ paimon log a1b2c3    # 查看会话做了什么，每个事件一行
 ```bash
 paimon --mode read                  # 以更谨慎的权限模式启动（默认为 yolo）
 paimon --strict                     # 每条命令都先询问，包括只读命令
+paimon --no-web-search              # 本次运行不提供网页搜索工具
 paimon --web                        # 在浏览器中使用同一套 UI（--port，默认 8000）
 paimon -p "what does cli.py do?"    # 直接在 stdout 输出回答，不启动 UI
 cat log.txt | paimon -p "summarize this"
@@ -99,10 +104,91 @@ paimon --profile work               # 单独配置的另一个账号
 
 ## 配置
 
-每个 profile 的模型设置保存在 `~/.config/paimon/<name>/config.json`，由首次启动或 `paimon login` 写入。会话存放在 `~/.local/share/paimon/sessions/`。安装 [delta](https://github.com/dandavison/delta) 后文件改动的展示效果更好。
-
-read 和 edit 模式会不经询问执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。**这是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
+每个 profile 的模型设置保存在 `~/.config/paimon/<name>/config.json`，由首次启动或 `paimon login` 写入。会话存放在 `~/.local/share/paimon/sessions/`。
+
+read 和 edit 模式会不经询问执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。Windows 上命令由 cmd.exe 执行，每条命令都会询问。**这是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
+
+## 架构
+
+`Agent.run` 产出一串与 UI 无关的事件流，TUI、`--web` 和无头模式都是这条事件流的渲染器。agent 自己持有它启动的子 agent 和后台命令。子 agent 是同一进程里作为任务运行的另一个 `Agent`，它的结果会作为一条消息送回父 agent。
+
+```mermaid
+flowchart TD
+    subgraph entry["入口"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / sessions"]
+        Headless["headless.py<br/>-p，单次运行"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI 组件"]
+        Pane["pane.py<br/>SessionPane"]
+        CommandPane["commandpane.py<br/>后台命令 pane"]
+        Tabs["tabs.py<br/>pane 标签栏"]
+        Login["login.py<br/>provider / 模型 / key"]
+        UIWidgets["ui.py<br/>输入框、确认面板"]
+        Diff["diff.py<br/>并排 diff 渲染"]
+    end
+
+    subgraph core["Agent 主循环"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>工具注册表"]
+        SessionMod["session.py<br/>JSONL 持久化"]
+        Compaction["compaction.py"]
+        ModelWindows["model_windows.py<br/>各模型上下文窗口大小"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path 展开"]
+        Jobs["turns.py<br/>回合驱动"]
+    end
+
+    subgraph support["配置与 skills"]
+        Config["config.py<br/>profile、凭证"]
+        Skills["skills.py<br/>Agent Skills 发现"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Config
+
+    Pane --> Jobs
+    Pane --> AgentLoop
+    Pane --> Diff
+    Pane --> UIWidgets
+    Pane --> LLM
+    CommandPane --> Pane
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "run_background" .-> CommandPane
+
+    PromptMod --> Skills
+    Compaction --> ModelWindows
+
+    Jobs --> AgentLoop
+
+    Skills --> Config
+    Config --> LLM
+```
 
 ## 遥测
 
-每次启动会向 Google Analytics 发送一条匿名事件：随机生成的安装 id、启动方式、版本号、操作系统名称，以及配置的 provider 和模型名。会话、提示词、文件和密钥一概不上报。设置 `PAIMON_NO_TELEMETRY=1` 或 `DO_NOT_TRACK=1` 可以关闭。
+每次启动会向 Google Analytics 发送一条匿名事件：随机生成的安装 id、启动方式、版本号、操作系统名称、取自 `LC_ALL`/`LANG` 的语言、是否首次启动，以及配置的 provider 和模型名。会话、提示词、文件和密钥一概不上报。设置 `PAIMON_NO_TELEMETRY=1` 或 `DO_NOT_TRACK=1` 可以关闭。

paimon-0.2.7/paimon/_grep_worker.py

@@ -0,0 +1,16 @@
+"""Disposable process for bounded, cancellable code searches."""
+
+import json
+import sys
+from pathlib import Path
+
+from .tools import _grep
+
+
+def main() -> None:
+    args, cwd, sandboxed = json.load(sys.stdin)
+    sys.stdout.write(json.dumps(_grep(args, Path(cwd), sandboxed=sandboxed)))
+
+
+if __name__ == "__main__":
+    main()