paimon 0.2.7__tar.gz → 0.2.8__tar.gz

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

@@ -1,15 +1,18 @@
 Metadata-Version: 2.4
 Name: paimon
-Version: 0.2.7
+Version: 0.2.8
 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.38.0
+Requires-Dist: genai-prices>=0.1.6
+Requires-Dist: pydantic-ai-slim[anthropic,google,openai]>=2.54.0
 Requires-Dist: textual>=8.2.7
 Requires-Dist: textual-serve>=1.1.3
 Requires-Dist: pyyaml>=6
+Requires-Dist: pydantic>=2.10
+Requires-Dist: typing-extensions>=4.12
 Requires-Dist: ddgs>=9
 Dynamic: license-file
 
@@ -39,11 +42,11 @@ Or run it without installing anything:
 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.
+The first launch asks for a provider, its API base and key, then a model. 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. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** only reads, **auto** edits inside the working directory and has a second model call approve everything else, **yolo** checks nothing 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 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.
+`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 a tab of its own, where you can watch it work and answer what it asks, and whose answer comes back into the conversation when it is done. Closing the tab stops it. It can also leave a command running in a tab, a dev server or a watcher, instead of holding up a turn.
 
 ## Web search
 
@@ -55,11 +58,11 @@ Paimon loads [Agent Skills](https://agentskills.io) from `~/.config/paimon/skill
 
 ## Using Paimon as a subagent
 
-Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. A profile keeps that model's account separate:
+Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. Log in to that model's provider once, then name the model on each run:
 
 ```bash
-paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
-paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+paimon login zai --api-key-env ZAI_API_KEY
+paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result
 ```
 
 The bundled skill teaches the calling agent this workflow:
@@ -80,7 +83,7 @@ import asyncio
 from paimon.agent import Agent, TextDelta
 
 async def main():
-    agent = Agent.open(mode="edit")
+    agent = Agent.open(mode="auto")
     async for event in agent.run("summarize the tests in this directory"):
         if isinstance(event, TextDelta):
             print(event.text, end="", flush=True)
@@ -88,7 +91,7 @@ async def main():
 asyncio.run(main())
 ```
 
-`Agent.open()` also takes a working directory, an async `confirm` callback for permission prompts, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
+`Agent.open()` also takes a working directory, an async `confirm` callback for the permission prompts that are left, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
 
 ## Sessions
 
@@ -106,43 +109,55 @@ 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 --strict                     # hold 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"
 paimon --model zai:glm-4.7          # this model for this run only
-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.
 
 Inside a [Herdr](https://herdr.dev) pane the UI reports its state and resume command to Herdr on its own, with nothing to install.
 
+### Debugging the Textual UI
+
+Start with `paimon --textual-debug` (also works with `--web`) when Paimon needs to diagnose its own layout or styling. It is off by default. When enabled, the model receives five tools scoped to the live UI process:
+
+- `textual_inspect` queries the DOM by CSS selector and reports geometry, pseudo-classes, focus and computed CSS;
+- `textual_eval` / `textual_exec` run Python in the UI process, including private APIs, persistent variables and top-level `await`;
+- `textual_apply_css` layers on CSS and relayouts immediately;
+- `textual_screenshot` exports the current render to SVG.
+
+You can ask it, for example, to “find why `#prompt` is narrower than expected, try a live fix, and take a screenshot.” `textual_exec` deliberately provides unrestricted in-process Python and can change any Textual or Paimon state. Use this development option only with trusted prompts. Live changes last only until exit; after confirming a fix, ask Paimon to edit the source.
+
 ## Configuration
 
-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/`.
+Model settings are kept in `~/.config/paimon/config.json`, written by the first launch or by `paimon login`. Each provider keeps its own credentials, and `paimon model provider:name` or Switch model in the command palette picks the model to run on. A ChatGPT plan works in place of an API key: `paimon login chatgpt` signs in through the browser. `paimon login antigravity` does the same for an Antigravity plan, which Google does not support outside Antigravity: Paimon signs in as the Antigravity client and calls an internal endpoint, so the account may be limited or closed, and the risk is yours. 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.
+Read and auto modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) on their own; `--strict` turns that off, and on Windows, where cmd.exe runs the commands, none are recognized. Read mode refuses everything else. Auto mode asks a reviewer model, which sees your messages and the agent's tool calls but not its reasoning or any tool output, and answers allow or block. It asks you instead when the reviewer cannot be reached or has blocked three calls in a row, and under `-p` those are refusals. Current models review with their provider's fast tier by default (GPT with Luna, Claude with Haiku, GLM with Flash) and the rest review with themselves; set `"review_model": "provider:name"` in the config to choose. **All of 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.
+`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. A UI that wants to show a job hooks `Agent.open_job`, which is how the TUI gives each one a pane.
 
 ```mermaid
 flowchart TD
     subgraph entry["Entry points"]
         CLI["cli.py"]
-        Commands["commands.py<br/>status / login / sessions"]
+        Commands["commands.py<br/>status / login / model / 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"]
+        AgentPane["agentpane.py<br/>subagent pane"]
         CommandPane["commandpane.py<br/>background command pane"]
+        Transcript["transcript.py<br/>conversation log, event renderer"]
         Tabs["tabs.py<br/>pane strip"]
-        Login["login.py<br/>provider / model / key"]
+        Login["login.py<br/>provider / key"]
         UIWidgets["ui.py<br/>prompt input, confirmations"]
         Diff["diff.py<br/>side-by-side diff rendering"]
     end
@@ -154,14 +169,13 @@ flowchart TD
         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"]
+        Config["config.py<br/>settings, credentials"]
         Skills["skills.py<br/>Agent Skills discovery"]
     end
 
@@ -174,6 +188,7 @@ flowchart TD
     Headless --> Mentions
 
     App --> Pane
+    App --> AgentPane
     App --> CommandPane
     App --> Tabs
     App --> Login
@@ -182,9 +197,13 @@ flowchart TD
     Pane --> Jobs
     Pane --> AgentLoop
     Pane --> Diff
+    Pane --> Transcript
     Pane --> UIWidgets
     Pane --> LLM
+    AgentPane --> Pane
+    AgentPane --> Transcript
     CommandPane --> Pane
+    Transcript --> UIWidgets
     UIWidgets --> Diff
 
     AgentLoop --> LLM
@@ -195,10 +214,10 @@ flowchart TD
     AgentLoop --> Retry
     AgentLoop --> Mentions
     AgentLoop -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "spawn_agent" .-> AgentPane
     AgentLoop -. "run_background" .-> CommandPane
 
     PromptMod --> Skills
-    Compaction --> ModelWindows
 
     Jobs --> AgentLoop
 

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

@@ -24,11 +24,11 @@ Or run it without installing anything:
 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.
+The first launch asks for a provider, its API base and key, then a model. 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. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** only reads, **auto** edits inside the working directory and has a second model call approve everything else, **yolo** checks nothing 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 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.
+`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 a tab of its own, where you can watch it work and answer what it asks, and whose answer comes back into the conversation when it is done. Closing the tab stops it. It can also leave a command running in a tab, a dev server or a watcher, instead of holding up a turn.
 
 ## Web search
 
@@ -40,11 +40,11 @@ Paimon loads [Agent Skills](https://agentskills.io) from `~/.config/paimon/skill
 
 ## Using Paimon as a subagent
 
-Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. A profile keeps that model's account separate:
+Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. Log in to that model's provider once, then name the model on each run:
 
 ```bash
-paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
-paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+paimon login zai --api-key-env ZAI_API_KEY
+paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result
 ```
 
 The bundled skill teaches the calling agent this workflow:
@@ -65,7 +65,7 @@ import asyncio
 from paimon.agent import Agent, TextDelta
 
 async def main():
-    agent = Agent.open(mode="edit")
+    agent = Agent.open(mode="auto")
     async for event in agent.run("summarize the tests in this directory"):
         if isinstance(event, TextDelta):
             print(event.text, end="", flush=True)
@@ -73,7 +73,7 @@ async def main():
 asyncio.run(main())
 ```
 
-`Agent.open()` also takes a working directory, an async `confirm` callback for permission prompts, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
+`Agent.open()` also takes a working directory, an async `confirm` callback for the permission prompts that are left, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
 
 ## Sessions
 
@@ -91,43 +91,55 @@ 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 --strict                     # hold 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"
 paimon --model zai:glm-4.7          # this model for this run only
-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.
 
 Inside a [Herdr](https://herdr.dev) pane the UI reports its state and resume command to Herdr on its own, with nothing to install.
 
+### Debugging the Textual UI
+
+Start with `paimon --textual-debug` (also works with `--web`) when Paimon needs to diagnose its own layout or styling. It is off by default. When enabled, the model receives five tools scoped to the live UI process:
+
+- `textual_inspect` queries the DOM by CSS selector and reports geometry, pseudo-classes, focus and computed CSS;
+- `textual_eval` / `textual_exec` run Python in the UI process, including private APIs, persistent variables and top-level `await`;
+- `textual_apply_css` layers on CSS and relayouts immediately;
+- `textual_screenshot` exports the current render to SVG.
+
+You can ask it, for example, to “find why `#prompt` is narrower than expected, try a live fix, and take a screenshot.” `textual_exec` deliberately provides unrestricted in-process Python and can change any Textual or Paimon state. Use this development option only with trusted prompts. Live changes last only until exit; after confirming a fix, ask Paimon to edit the source.
+
 ## Configuration
 
-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/`.
+Model settings are kept in `~/.config/paimon/config.json`, written by the first launch or by `paimon login`. Each provider keeps its own credentials, and `paimon model provider:name` or Switch model in the command palette picks the model to run on. A ChatGPT plan works in place of an API key: `paimon login chatgpt` signs in through the browser. `paimon login antigravity` does the same for an Antigravity plan, which Google does not support outside Antigravity: Paimon signs in as the Antigravity client and calls an internal endpoint, so the account may be limited or closed, and the risk is yours. 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.
+Read and auto modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) on their own; `--strict` turns that off, and on Windows, where cmd.exe runs the commands, none are recognized. Read mode refuses everything else. Auto mode asks a reviewer model, which sees your messages and the agent's tool calls but not its reasoning or any tool output, and answers allow or block. It asks you instead when the reviewer cannot be reached or has blocked three calls in a row, and under `-p` those are refusals. Current models review with their provider's fast tier by default (GPT with Luna, Claude with Haiku, GLM with Flash) and the rest review with themselves; set `"review_model": "provider:name"` in the config to choose. **All of 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.
+`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. A UI that wants to show a job hooks `Agent.open_job`, which is how the TUI gives each one a pane.
 
 ```mermaid
 flowchart TD
     subgraph entry["Entry points"]
         CLI["cli.py"]
-        Commands["commands.py<br/>status / login / sessions"]
+        Commands["commands.py<br/>status / login / model / 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"]
+        AgentPane["agentpane.py<br/>subagent pane"]
         CommandPane["commandpane.py<br/>background command pane"]
+        Transcript["transcript.py<br/>conversation log, event renderer"]
         Tabs["tabs.py<br/>pane strip"]
-        Login["login.py<br/>provider / model / key"]
+        Login["login.py<br/>provider / key"]
         UIWidgets["ui.py<br/>prompt input, confirmations"]
         Diff["diff.py<br/>side-by-side diff rendering"]
     end
@@ -139,14 +151,13 @@ flowchart TD
         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"]
+        Config["config.py<br/>settings, credentials"]
         Skills["skills.py<br/>Agent Skills discovery"]
     end
 
@@ -159,6 +170,7 @@ flowchart TD
     Headless --> Mentions
 
     App --> Pane
+    App --> AgentPane
     App --> CommandPane
     App --> Tabs
     App --> Login
@@ -167,9 +179,13 @@ flowchart TD
     Pane --> Jobs
     Pane --> AgentLoop
     Pane --> Diff
+    Pane --> Transcript
     Pane --> UIWidgets
     Pane --> LLM
+    AgentPane --> Pane
+    AgentPane --> Transcript
     CommandPane --> Pane
+    Transcript --> UIWidgets
     UIWidgets --> Diff
 
     AgentLoop --> LLM
@@ -180,10 +196,10 @@ flowchart TD
     AgentLoop --> Retry
     AgentLoop --> Mentions
     AgentLoop -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "spawn_agent" .-> AgentPane
     AgentLoop -. "run_background" .-> CommandPane
 
     PromptMod --> Skills
-    Compaction --> ModelWindows
 
     Jobs --> AgentLoop
 

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

@@ -24,11 +24,11 @@ paimon
 uvx paimon
 ```
 
-首次启动会询问 provider、模型、API base 和 key。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
+首次启动会询问 provider 及其 API base 和 key，然后选择模型。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
 
-运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。以 `!` 开头的一行不发给模型，而是直接在 shell 里执行，输出 Paimon 也能看到。`!!` 则不告诉它。
+运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 只读，**auto** 放行工作目录内的编辑，其余操作交给另一次模型调用审批，**yolo** 不做任何检查，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。以 `!` 开头的一行不发给模型，而是直接在 shell 里执行，输出 Paimon 也能看到。`!!` 则不告诉它。
 
-`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 也能并行干活：让它同时做两件互不相干的事，它会在后台起第二个 agent，做完后结果会回到当前会话里。它也能把一条命令留在单独的 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
+`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 也能并行干活：让它同时做两件互不相干的事，它会在单独的 tab 里起第二个 agent，你可以在那里看它干活、回答它的授权请求，做完后结果会回到当前会话里，关掉 tab 就是停掉它。它也能把一条命令留在 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
 
 ## 网页搜索
 
@@ -40,11 +40,11 @@ Paimon 会从 `~/.config/paimon/skills`、`~/.agents/skills` 以及工作目录
 
 ## 当作 subagent 使用
 
-前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。用一个 profile 单独保存该模型的账号：
+前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。先登录该模型的 provider，之后每次运行时指定模型：
 
 ```bash
-paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
-paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+paimon login zai --api-key-env ZAI_API_KEY
+paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result
 ```
 
 自带的 skill 会向调用方 agent 说明这套流程：
@@ -65,7 +65,7 @@ import asyncio
 from paimon.agent import Agent, TextDelta
 
 async def main():
-    agent = Agent.open(mode="edit")
+    agent = Agent.open(mode="auto")
     async for event in agent.run("summarize the tests in this directory"):
         if isinstance(event, TextDelta):
             print(event.text, end="", flush=True)
@@ -73,7 +73,7 @@ async def main():
 asyncio.run(main())
 ```
 
-`Agent.open()` 还接受工作目录、用于权限确认的异步 `confirm` 回调，以及 `toolset`，可以只给模型一部分工具，或者换成你自己的工具。agent 被回收时会交还会话，想在确定的时刻交还就调 `close()`，或者把它当上下文管理器用。它写的会话文件和 CLI 一样，所以代码里跑出来的会话之后可以用 `paimon -r` 恢复。
+`Agent.open()` 还接受工作目录、用于剩余权限确认的异步 `confirm` 回调，以及 `toolset`，可以只给模型一部分工具，或者换成你自己的工具。agent 被回收时会交还会话，想在确定的时刻交还就调 `close()`，或者把它当上下文管理器用。它写的会话文件和 CLI 一样，所以代码里跑出来的会话之后可以用 `paimon -r` 恢复。
 
 ## 会话
 
@@ -91,41 +91,53 @@ paimon log a1b2c3    # 查看会话做了什么，每个事件一行
 
 ```bash
 paimon --mode read                  # 以更谨慎的权限模式启动（默认为 yolo）
-paimon --strict                     # 每条命令都先询问，包括只读命令
+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"
 paimon --model zai:glm-4.7          # 仅本次运行使用该模型
-paimon --profile work               # 单独配置的另一个账号
 ```
 
 `-p` 不会停下来询问，配合默认的 `yolo` 模式，它已经可以修改文件和执行命令。加 `--output-format result` 会输出一个包含结果的 JSON 对象，调用方程序读这个就够了。其余选项见 `paimon --help`。
 
+### 调试 Textual UI
+
+需要让 Paimon 排查自己的布局或样式时，用 `paimon --textual-debug` 启动（也可与 `--web` 一起使用）。默认不启用；开启后模型会多出五个只作用于当前 UI 进程的工具：
+
+- `textual_inspect`：按 CSS selector 查看 DOM、geometry、pseudo-classes、焦点和 computed CSS；
+- `textual_eval` / `textual_exec`：在 UI 进程里运行 Python，支持 private API、持久变量和 top-level `await`；
+- `textual_apply_css`：动态叠加 CSS 并立即重新布局；
+- `textual_screenshot`：把当前渲染结果导出成 SVG。
+
+例如可以直接让它“检查 `#prompt` 为什么比预期窄，动态试一个修复并截图”。`textual_exec` 有意提供完整的进程内 Python 能力，能修改任意 Textual/Paimon 状态；这个选项只适合开发调试，不应对不受信任的 prompt 开启。动态修改只保留到进程退出，确定修复后仍需让 Paimon编辑源码。
+
 ## 配置
 
-每个 profile 的模型设置保存在 `~/.config/paimon/<name>/config.json`，由首次启动或 `paimon login` 写入。会话存放在 `~/.local/share/paimon/sessions/`。
+模型设置保存在 `~/.config/paimon/config.json`，由首次启动或 `paimon login` 写入。每个 provider 各自保存凭据，用 `paimon model provider:name` 或命令面板里的 Switch model 选择要用的模型。也可以用 ChatGPT 订阅代替 API key，`paimon login chatgpt` 会通过浏览器登录。会话存放在 `~/.local/share/paimon/sessions/`。
 
-read 和 edit 模式会不经询问执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。Windows 上命令由 cmd.exe 执行，每条命令都会询问。**这是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
+read 和 auto 模式会直接执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉，Windows 上命令由 cmd.exe 执行，一条也不识别。read 模式拒绝其余所有操作。auto 模式把它们交给审批模型，它能看到你的消息和 agent 的工具调用，看不到 agent 的推理和工具输出，只回答放行或拦截。审批模型不可用或者连续拦截三次时改为询问你，`-p` 下则直接拒绝。当前的模型默认用同一家里快速档的那个来审批（GPT 用 Luna，Claude 用 Haiku，GLM 用 Flash），其余模型自己审自己，在配置里写 `"review_model": "provider:name"` 可以自行指定。**这些都是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
 
 ## 架构
 
-`Agent.run` 产出一串与 UI 无关的事件流，TUI、`--web` 和无头模式都是这条事件流的渲染器。agent 自己持有它启动的子 agent 和后台命令。子 agent 是同一进程里作为任务运行的另一个 `Agent`，它的结果会作为一条消息送回父 agent。
+`Agent.run` 产出一串与 UI 无关的事件流，TUI、`--web` 和无头模式都是这条事件流的渲染器。agent 自己持有它启动的子 agent 和后台命令。子 agent 是同一进程里作为任务运行的另一个 `Agent`，它的结果会作为一条消息送回父 agent。想把 job 显示出来的 UI 挂上 `Agent.open_job` 即可，TUI 就是这样给每个 job 开 pane 的。
 
 ```mermaid
 flowchart TD
     subgraph entry["入口"]
         CLI["cli.py"]
-        Commands["commands.py<br/>status / login / sessions"]
+        Commands["commands.py<br/>status / login / model / sessions"]
         Headless["headless.py<br/>-p，单次运行"]
         App["app.py<br/>Textual TUI / --web"]
     end
 
     subgraph tui["TUI 组件"]
         Pane["pane.py<br/>SessionPane"]
+        AgentPane["agentpane.py<br/>子 agent pane"]
         CommandPane["commandpane.py<br/>后台命令 pane"]
+        Transcript["transcript.py<br/>对话记录与事件渲染"]
         Tabs["tabs.py<br/>pane 标签栏"]
-        Login["login.py<br/>provider / 模型 / key"]
+        Login["login.py<br/>provider / key"]
         UIWidgets["ui.py<br/>输入框、确认面板"]
         Diff["diff.py<br/>并排 diff 渲染"]
     end
@@ -137,14 +149,13 @@ flowchart TD
         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、凭证"]
+        Config["config.py<br/>设置、凭证"]
         Skills["skills.py<br/>Agent Skills 发现"]
     end
 
@@ -157,6 +168,7 @@ flowchart TD
     Headless --> Mentions
 
     App --> Pane
+    App --> AgentPane
     App --> CommandPane
     App --> Tabs
     App --> Login
@@ -165,9 +177,13 @@ flowchart TD
     Pane --> Jobs
     Pane --> AgentLoop
     Pane --> Diff
+    Pane --> Transcript
     Pane --> UIWidgets
     Pane --> LLM
+    AgentPane --> Pane
+    AgentPane --> Transcript
     CommandPane --> Pane
+    Transcript --> UIWidgets
     UIWidgets --> Diff
 
     AgentLoop --> LLM
@@ -178,10 +194,10 @@ flowchart TD
     AgentLoop --> Retry
     AgentLoop --> Mentions
     AgentLoop -. "spawn_agent" .-> AgentLoop
+    AgentLoop -. "spawn_agent" .-> AgentPane
     AgentLoop -. "run_background" .-> CommandPane
 
     PromptMod --> Skills
-    Compaction --> ModelWindows
 
     Jobs --> AgentLoop