uv-agent 0.1.0__tar.gz

uv_agent-0.1.0/.code-search/.gitignore

@@ -0,0 +1 @@
+*

uv_agent-0.1.0/.code-search/manifest.json

@@ -0,0 +1 @@
+{"files":{"src/uv_agent/tui/app.py":{"cache_key":"9e63f2478f3a2649","size":117503,"mtime_ms":1778949869118,"symbol_count":238},"src/uv_agent/tui/formatting.py":{"cache_key":"8362287575c9dc28","size":9045,"mtime_ms":1778926845642,"symbol_count":21},"src/uv_agent_runtime/files.py":{"cache_key":"ce0aaeb682bff844","size":1994,"mtime_ms":1778844906258,"symbol_count":6},"src/uv_agent_runtime/mcp.py":{"cache_key":"d6f21065bd0cf072","size":8380,"mtime_ms":1778854721771,"symbol_count":18},"src/uv_agent/agent.py":{"cache_key":"7279d8a152b81de9","size":44515,"mtime_ms":1778949815439,"symbol_count":41},"src/uv_agent/errors.py":{"cache_key":"ca17c802a9f60928","size":2287,"mtime_ms":1778857955717,"symbol_count":4},"src/uv_agent/runner/metadata.py":{"cache_key":"c6cddba28a677217","size":1889,"mtime_ms":1778834057385,"symbol_count":6},"main.py":{"cache_key":"0bb19dfda21091e2","size":70,"mtime_ms":1778833982527,"symbol_count":0},"src/uv_agent/runner/store.py":{"cache_key":"d148861e74b78132","size":6206,"mtime_ms":1778858052255,"symbol_count":11},"src/uv_agent/time.py":{"cache_key":"6ab0eb854e105f7f","size":140,"mtime_ms":1778833982529,"symbol_count":1},"src/uv_agent/project_rules.py":{"cache_key":"afbe2f722d71d50f","size":5167,"mtime_ms":1778849504735,"symbol_count":13},"tests/test_runner.py":{"cache_key":"9252e5ce62d73b31","size":5358,"mtime_ms":1778864536950,"symbol_count":7},"tests/test_config.py":{"cache_key":"39372ac99dd5247d","size":6322,"mtime_ms":1778950522169,"symbol_count":9},"tests/test_session_store.py":{"cache_key":"7985c2829c3c52c2","size":3391,"mtime_ms":1778917866600,"symbol_count":4},"src/uv_agent/jsonl.py":{"cache_key":"916fc738a0456fdb","size":899,"mtime_ms":1778833982529,"symbol_count":5},"src/uv_agent_runtime/events.py":{"cache_key":"6ade00a40c70369c","size":617,"mtime_ms":1778844923018,"symbol_count":3},"tests/fixtures/mcp_echo_server.py":{"cache_key":"6522ac861947ee16","size":1501,"mtime_ms":1778845695426,"symbol_count":2},"tests/test_tui.py":{"cache_key":"30f4a2b346000ac2","size":61520,"mtime_ms":1778950414497,"symbol_count":64},"src/uv_agent/model_client.py":{"cache_key":"173f249032d9d838","size":28274,"mtime_ms":1778858345461,"symbol_count":44},"tests/test_runtime.py":{"cache_key":"d98822f0fd0614c4","size":7457,"mtime_ms":1778899196421,"symbol_count":14},"src/uv_agent/app_factory.py":{"cache_key":"e4b5abfe23d3cf49","size":906,"mtime_ms":1778856521696,"symbol_count":1},"src/uv_agent/environment.py":{"cache_key":"eb71449149c18276","size":2671,"mtime_ms":1778857955716,"symbol_count":7},"src/uv_agent_runtime/__init__.py":{"cache_key":"20ba2e72a6b60622","size":1111,"mtime_ms":1778864387381,"symbol_count":1},"src/uv_agent/mcp_config.py":{"cache_key":"b2c178a88b7f5741","size":2296,"mtime_ms":1778845376516,"symbol_count":4},"tests/test_project_rules.py":{"cache_key":"add7322784ea1245","size":1536,"mtime_ms":1778849664712,"symbol_count":2},"src/uv_agent/ids.py":{"cache_key":"12f45ee2ed61ca20","size":131,"mtime_ms":1778833982528,"symbol_count":1},"src/uv_agent_runtime/patch.py":{"cache_key":"e6f7eb4839ad6bf3","size":2221,"mtime_ms":1778864716915,"symbol_count":5},"src/uv_agent/runner/__init__.py":{"cache_key":"e5aba670998f3a73","size":271,"mtime_ms":1778834057384,"symbol_count":1},"src/uv_agent/i18n.py":{"cache_key":"c9c216a3774c99c8","size":14040,"mtime_ms":1778949893231,"symbol_count":4},"src/uv_agent/runner/runner.py":{"cache_key":"eecbfd1ba2caa4a6","size":13733,"mtime_ms":1778914428144,"symbol_count":12},"src/uv_agent/runner/models.py":{"cache_key":"717341c48ff8721e","size":1329,"mtime_ms":1778899098182,"symbol_count":4},"src/uv_agent/cli.py":{"cache_key":"40705a33d911a690","size":4591,"mtime_ms":1778899126715,"symbol_count":2},"src/uv_agent_runtime/threads.py":{"cache_key":"f158663f029fbbd7","size":8394,"mtime_ms":1778917751092,"symbol_count":13},"src/uv_agent/session/store.py":{"cache_key":"bf739231b9cc942a","size":10919,"mtime_ms":1778917740674,"symbol_count":21},"src/uv_agent/clipboard.py":{"cache_key":"06fdade8cb2a357b","size":1284,"mtime_ms":1778909578950,"symbol_count":3},"src/uv_agent/skills.py":{"cache_key":"d92e183c90aaa441","size":4247,"mtime_ms":1778913046840,"symbol_count":5},"src/uv_agent/session/__init__.py":{"cache_key":"859784aab205bcf1","size":195,"mtime_ms":1778834216290,"symbol_count":1},"tests/test_mcp_config.py":{"cache_key":"25559c07d119d065","size":887,"mtime_ms":1778845412388,"symbol_count":1},"src/uv_agent/tui/__init__.py":{"cache_key":"f6cb99f1ef1604ef","size":90,"mtime_ms":1778834261125,"symbol_count":1},"src/uv_agent/paths.py":{"cache_key":"8f2b3f194ea29f1e","size":1495,"mtime_ms":1778867977697,"symbol_count":6},"src/uv_agent/attachments.py":{"cache_key":"4904f4b8897fe18b","size":3919,"mtime_ms":1778854575881,"symbol_count":9},"src/uv_agent/__init__.py":{"cache_key":"19d73df15641d86c","size":98,"mtime_ms":1778833982528,"symbol_count":2},"src/uv_agent_runtime/scripts.py":{"cache_key":"2715db6ea5b2fdbd","size":3378,"mtime_ms":1778858092519,"symbol_count":5},"src/uv_agent_runtime/subagent.py":{"cache_key":"c8a22d5318eca619","size":3846,"mtime_ms":1778899209139,"symbol_count":5},"src/uv_agent/context.py":{"cache_key":"49c9f8733f6113af","size":1592,"mtime_ms":1778849521392,"symbol_count":4},"src/uv_agent/config.py":{"cache_key":"00ed7e387c98d7ef","size":13987,"mtime_ms":1778950515355,"symbol_count":29},"tests/test_metadata.py":{"cache_key":"50a5e3c34c19cd22","size":1053,"mtime_ms":1778834328526,"symbol_count":3},"src/uv_agent_runtime/process.py":{"cache_key":"b150440794b53155","size":1354,"mtime_ms":1778844916303,"symbol_count":3},"src/uv_agent/session/models.py":{"cache_key":"358b77ce3308283d","size":577,"mtime_ms":1778834216290,"symbol_count":3},"src/uv_agent_runtime/vision.py":{"cache_key":"2ff0b007896e1441","size":607,"mtime_ms":1778854575881,"symbol_count":1},"tests/test_model_client.py":{"cache_key":"93b0c37eb345f50d","size":5442,"mtime_ms":1778854760658,"symbol_count":8},"tests/test_skills.py":{"cache_key":"d31d0752f2c1c334","size":1770,"mtime_ms":1778913061518,"symbol_count":3},"tests/test_agent.py":{"cache_key":"2239b4875fe0fdf8","size":51000,"mtime_ms":1778950371821,"symbol_count":30}}}

uv_agent-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# uv-agent runtime data
+.uv-agent/

uv_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

uv_agent-0.1.0/AGENTS.md

@@ -0,0 +1,57 @@
+# uv-agent Project Rules
+
+This repository builds `uv-agent`, an experimental coding agent with a Textual TUI. The product goal is documented in `docs/design.md`; this file records the repository rules an agent should follow while editing the project.
+
+## Project Shape
+
+- `src/uv_agent/`: host application, configuration, model clients, session store, Python runner, project rules, skills/MCP discovery, and TUI.
+- `src/uv_agent_runtime/`: helper package injected into managed Python scripts so scripts can access file helpers, subprocess helpers, structured events, image attachment, saved script summaries, subagent launch helpers, and MCP clients.
+- `tests/`: pytest coverage for runner, runtime, model clients, project rules, sessions, config, and Textual UI behavior.
+- `docs/design.md`: product semantics and longer design notes. Keep it aligned when changing architecture or user-visible behavior.
+
+## Hard Boundaries
+
+- The agent has exactly one external action surface: `run_python`.
+- `run_python` executes Python through the managed runner. Do not add direct shell, filesystem, browser, network, or MCP model tools.
+- Python scripts may call `subprocess`; that capability must stay inside the Python runner boundary.
+- Managed scripts declare third-party dependencies with PEP 723 inline metadata. Do not add a separate dependency argument to the tool API.
+- `uv_agent_runtime` must work as a package dependency for managed scripts; scripts must not rely on the repository checkout, current `.venv`, or implicit import paths.
+- MCP and skills are progressively disclosed context. MCP calls happen through Python runtime helpers, not direct model tool calls.
+
+## Prompt And Context
+
+- Keep the stable system prompt concise and structured with explicit XML-style sections and closing tags.
+- Include stable host metadata and detected user language in the system prompt.
+- Keep AGENTS rules, skills summaries, and MCP declarations out of the stable prompt. Append them as dynamic workspace context only when first seen, changed, removed, or after compaction.
+- If dynamic context is removed, the next update must explicitly tell the agent not to rely on older appended context.
+- Compression must use the latest system prompt, model config, runner config, and dynamic workspace context after a thread resumes.
+
+## TUI Rules
+
+- TUI uses Textual and should remain a Codex-style single transcript with a bottom composer.
+- Composer is multi-line: Enter inserts a newline; Ctrl+Enter or Ctrl+J sends.
+- Typing `/` from an empty composer opens the full-screen command picker. Editing or deleting an existing slash command must not reopen it.
+- Full-screen pickers must support keyboard and mouse: type to filter, arrows/PageUp/PageDown to move, Enter to select, Esc to close.
+- TUI displays model reasoning, tool starts/results, compaction, image attachment, and errors as compact transcript events.
+- TUI should not implement model protocol, runner execution, JSONL persistence, compression, or configuration rules directly; consume events from `AgentEngine` and formatting helpers instead.
+
+## Config And State
+
+- User config lives at `~/.uv-agent/config.json`; project overrides may live in `.uv-agent/config.json`.
+- Project runtime state lives under user-level `~/.uv-agent/projects/<project-id>/` by default.
+- `.uv-agent/` in this repository is ignored local state. Do not commit debug screenshots, local config, scripts, runs, or thread state.
+- Never commit API keys, tokens, provider secrets, or redacted copies that still reveal secret material.
+
+## Development
+
+- Use `uv` for project commands, especially `uv run pytest`.
+- Follow normal Python `src/` layout conventions. Keep library code importable without starting the TUI.
+- Use typed dataclasses or structured dictionaries for persisted and cross-module data shapes when practical.
+- Prefer focused tests with each behavior change. Update existing tests when changing prompt structure, runner semantics, context management, or TUI keyboard behavior.
+- Keep comments sparse and useful. Use comments for non-obvious compatibility, caching, or protocol decisions; do not narrate ordinary control flow.
+
+## Verification
+
+- Run `uv run pytest` before committing meaningful behavior changes.
+- For TUI interaction changes, add or update Textual `run_test` coverage. Manual screenshots can be exported with `App.export_screenshot()` into `.uv-agent/screenshots/`.
+- Before committing, check `git status --short` and ensure no secrets or ignored local artifacts are staged.

uv_agent-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: uv-agent
+Version: 0.1.0
+Summary: Experimental Python-runner coding agent with a Textual TUI
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: openai>=2.36.0
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: textual>=6.5.0
+Description-Content-Type: text/markdown
+
+# uv-agent
+
+Experimental coding agent with a Textual TUI. The agent has one external action surface: it submits Python scripts to a managed `uv run` runner.
+
+## Run
+
+```powershell
+uv run uv-agent
+```
+
+Run the published package without installing it first:
+
+```powershell
+uvx uv-agent
+```
+
+Single prompt smoke test:
+
+```powershell
+uv run uv-agent ask "Reply with exactly: ok"
+```
+
+Resume a thread without opening the TUI:
+
+```powershell
+uv run uv-agent ask --thread thr_xxx "Continue from here"
+```
+
+## Local Config
+
+User-level provider config lives at `~/.uv-agent/config.json` by default. A project can override it with `.uv-agent/config.json`; that project-local directory is ignored by git.
+
+The config supports providers, models, levels, runtime options, and runner options. Secrets such as `api_key` must stay in ignored local config or environment variables.
+
+Minimal shape:
+
+```json
+{
+  "providers": {
+    "local": {
+      "base_url": "https://api.example.com",
+      "api_key_env": "UV_AGENT_API_KEY",
+      "responses": { "path": "/responses" },
+      "chat_completions": { "path": "/chat/completions" }
+    }
+  },
+  "models": {
+    "main": {
+      "provider": "local",
+      "model": "gpt-5.5",
+      "api": "responses",
+      "context_window_tokens": 258000
+    },
+    "chat": {
+      "provider": "local",
+      "model": "gpt-5.4-mini",
+      "api": "chat_completions",
+      "context_window_tokens": 258000
+    }
+  },
+  "levels": {
+    "medium": { "model": "main" },
+    "chat": { "model": "chat" }
+  },
+  "ui": {
+    "language": "auto"
+  },
+  "runner": {
+    "max_saved_scripts": 32
+  }
+}
+```
+
+Supported model APIs:
+
+- `responses`
+- `chat_completions`
+- `anthropic_messages`
+
+Streaming uses SSE when the provider supports it.
+
+Compression can be tuned under `runtime.compression` with `trigger_ratio`,
+`target_ratio`, and `min_tokens`. The TUI reads provider `usage` when available
+and falls back to a local estimate for the context meter.
+
+## Runtime Scripts
+
+Agent scripts declare dependencies with PEP 723 inline metadata. The runner records managed script artifacts, run JSONL, and thread JSONL under `~/.uv-agent/projects/<project-id>/`, injects the configured runtime dependency into inline metadata when needed, and supports rerunning saved scripts.
+
+The PyPI package currently ships both `uv_agent` and `uv_agent_runtime`, so the
+default injected runtime dependency is the installed `uv-agent` version. This
+lets `uvx uv-agent` run the host app while managed scripts install the same
+package and import `uv_agent_runtime`.
+
+For local source development, override the runtime dependency in
+`.uv-agent/config.json`:
+
+```json
+{
+  "runner": {
+    "runtime_dependency": "uv-agent @ file:///C:/path/to/uv-agent"
+  }
+}
+```
+
+Each project keeps the 32 most recently used managed scripts by default
+(`runner.max_saved_scripts`). Run logs are still kept separately. Scripts can
+inspect recent saved scripts with `uv_agent_runtime.saved_scripts()`.
+
+`uv_agent_runtime` exposes convenience helpers for text/JSON files, unified-diff patches, subprocesses, structured events, nested `uv-agent ask` calls by model level, image context, saved script summaries, compact thread digests, and MCP stdio servers declared in `.agents/mcp.json`.
+
+Image context is added from a script with `look_at`:
+
+```python
+from uv_agent_runtime import look_at
+
+look_at("screenshot.png", note="inspect the failed layout")
+```
+
+The host copies the image into the project state attachments directory and
+appends it to later model input. Large image bytes are not stored directly in
+thread JSONL.
+
+Saved scripts can be rerun by passing `script_id` or `run_id` to `run_python`;
+`rerun_mode="replay"` inherits a previous run's arguments when a `run_id` is
+available.
+
+Nested agents are launched from Python with level names rather than concrete
+models:
+
+```python
+from uv_agent_runtime import ask
+
+result = ask("inspect the test failure", check=True)
+print(result.text)
+```
+
+Pass `level` only when intentionally selecting one of the level names defined in
+the config; omit it to use the default level.
+
+MCP remains a Python-triggered runtime capability, not a direct model tool:
+
+```python
+from uv_agent_runtime import connect_named
+
+with connect_named("filesystem") as client:
+    client.initialize()
+    print(client.list_tools())
+```
+
+## Workspace Rules
+
+`AGENTS.md` context is loaded from `~/.agents/AGENTS.md` and from the current
+git root down to the startup directory, including `AGENTS.*.md` variants.
+Rules, discovered skills, and MCP declarations are kept out of the stable system
+prompt. The engine appends a compact workspace-context update only when that
+context is first seen, changed, removed, or when a thread continues after
+compaction. Removal updates explicitly tell the agent not to rely on older
+appended rule/capability context unless it appears again. Context update events
+are stored in thread JSONL for change tracking, but they are not reconstructed as
+ordinary conversation items or included in compression input.
+
+## TUI
+
+The default TUI follows a Codex-style shape: a single transcript, inline Python runner events, full-screen focus panels, and a bottom composer with a bordered input box plus a compact status line.
+
+- `Enter`: insert a newline in the composer
+- `Ctrl+Enter` or `Ctrl+J`: send the composer text
+- `Esc`: clear the composer or close the open panel
+- `Ctrl+S` or `/status`: open detailed runtime status
+- `Ctrl+O` or `/threads`: open a searchable thread picker and resume history
+- `Ctrl+P`: open a full-screen command palette
+- Selecting composer text copies it after a short delay and shows a notification
+- `Ctrl+C`: press twice to interrupt a running turn; when idle, press twice to quit
+- `/quit`: quit after a second confirmation
+- `?` + `Ctrl+Enter` or `/help`: show local commands
+- `/context`: show context budget and loaded workspace rules
+- `/rules`: inspect loaded `AGENTS.md` files
+- `/new [title]`, `/threads`, and `/clear`: light thread controls
+- `/config`: edit user-facing settings (`default_level`, `language`, `auto_compress`) and show config sources / redacted merged config
+- `/models`: read-only view of configured models. Add or modify models in the config file; this command never writes
+- `/level [name]`: the only runtime model switch. Picks one of the levels defined in the config for this session
+- `/mcp`: show MCP declarations from `.agents/mcp.json`
+- `/skills` and `/skill [name]`: inspect `.agents/skills` entries
+- `/runs`: show the latest Python run summary from this TUI session
+- `/scripts`: show recent managed script summaries
+- `/panel`: reminder that panels close with `Esc`
+- Python runs appear inline with script/run ids, exit status, stdout/stderr summaries, and truncation markers
+- Reasoning/tool/runtime events appear as compact timeline entries; detailed run output remains available in `/runs`.
+- Typing `/` opens the full-screen command picker; `Ctrl+P` opens the same picker. Type to filter, use arrows/PageUp/PageDown to move, and Enter to select.
+- Temporary panels open as full-screen overlays with search/scroll/select behavior.
+
+For manual UI checks, Textual's `App.export_screenshot()` works in headless
+tests and writes SVG snapshots. Local debug captures belong under `.uv-agent/`
+so they stay out of git.

uv_agent-0.1.0/README.md

@@ -0,0 +1,195 @@
+# uv-agent
+
+Experimental coding agent with a Textual TUI. The agent has one external action surface: it submits Python scripts to a managed `uv run` runner.
+
+## Run
+
+```powershell
+uv run uv-agent
+```
+
+Run the published package without installing it first:
+
+```powershell
+uvx uv-agent
+```
+
+Single prompt smoke test:
+
+```powershell
+uv run uv-agent ask "Reply with exactly: ok"
+```
+
+Resume a thread without opening the TUI:
+
+```powershell
+uv run uv-agent ask --thread thr_xxx "Continue from here"
+```
+
+## Local Config
+
+User-level provider config lives at `~/.uv-agent/config.json` by default. A project can override it with `.uv-agent/config.json`; that project-local directory is ignored by git.
+
+The config supports providers, models, levels, runtime options, and runner options. Secrets such as `api_key` must stay in ignored local config or environment variables.
+
+Minimal shape:
+
+```json
+{
+  "providers": {
+    "local": {
+      "base_url": "https://api.example.com",
+      "api_key_env": "UV_AGENT_API_KEY",
+      "responses": { "path": "/responses" },
+      "chat_completions": { "path": "/chat/completions" }
+    }
+  },
+  "models": {
+    "main": {
+      "provider": "local",
+      "model": "gpt-5.5",
+      "api": "responses",
+      "context_window_tokens": 258000
+    },
+    "chat": {
+      "provider": "local",
+      "model": "gpt-5.4-mini",
+      "api": "chat_completions",
+      "context_window_tokens": 258000
+    }
+  },
+  "levels": {
+    "medium": { "model": "main" },
+    "chat": { "model": "chat" }
+  },
+  "ui": {
+    "language": "auto"
+  },
+  "runner": {
+    "max_saved_scripts": 32
+  }
+}
+```
+
+Supported model APIs:
+
+- `responses`
+- `chat_completions`
+- `anthropic_messages`
+
+Streaming uses SSE when the provider supports it.
+
+Compression can be tuned under `runtime.compression` with `trigger_ratio`,
+`target_ratio`, and `min_tokens`. The TUI reads provider `usage` when available
+and falls back to a local estimate for the context meter.
+
+## Runtime Scripts
+
+Agent scripts declare dependencies with PEP 723 inline metadata. The runner records managed script artifacts, run JSONL, and thread JSONL under `~/.uv-agent/projects/<project-id>/`, injects the configured runtime dependency into inline metadata when needed, and supports rerunning saved scripts.
+
+The PyPI package currently ships both `uv_agent` and `uv_agent_runtime`, so the
+default injected runtime dependency is the installed `uv-agent` version. This
+lets `uvx uv-agent` run the host app while managed scripts install the same
+package and import `uv_agent_runtime`.
+
+For local source development, override the runtime dependency in
+`.uv-agent/config.json`:
+
+```json
+{
+  "runner": {
+    "runtime_dependency": "uv-agent @ file:///C:/path/to/uv-agent"
+  }
+}
+```
+
+Each project keeps the 32 most recently used managed scripts by default
+(`runner.max_saved_scripts`). Run logs are still kept separately. Scripts can
+inspect recent saved scripts with `uv_agent_runtime.saved_scripts()`.
+
+`uv_agent_runtime` exposes convenience helpers for text/JSON files, unified-diff patches, subprocesses, structured events, nested `uv-agent ask` calls by model level, image context, saved script summaries, compact thread digests, and MCP stdio servers declared in `.agents/mcp.json`.
+
+Image context is added from a script with `look_at`:
+
+```python
+from uv_agent_runtime import look_at
+
+look_at("screenshot.png", note="inspect the failed layout")
+```
+
+The host copies the image into the project state attachments directory and
+appends it to later model input. Large image bytes are not stored directly in
+thread JSONL.
+
+Saved scripts can be rerun by passing `script_id` or `run_id` to `run_python`;
+`rerun_mode="replay"` inherits a previous run's arguments when a `run_id` is
+available.
+
+Nested agents are launched from Python with level names rather than concrete
+models:
+
+```python
+from uv_agent_runtime import ask
+
+result = ask("inspect the test failure", check=True)
+print(result.text)
+```
+
+Pass `level` only when intentionally selecting one of the level names defined in
+the config; omit it to use the default level.
+
+MCP remains a Python-triggered runtime capability, not a direct model tool:
+
+```python
+from uv_agent_runtime import connect_named
+
+with connect_named("filesystem") as client:
+    client.initialize()
+    print(client.list_tools())
+```
+
+## Workspace Rules
+
+`AGENTS.md` context is loaded from `~/.agents/AGENTS.md` and from the current
+git root down to the startup directory, including `AGENTS.*.md` variants.
+Rules, discovered skills, and MCP declarations are kept out of the stable system
+prompt. The engine appends a compact workspace-context update only when that
+context is first seen, changed, removed, or when a thread continues after
+compaction. Removal updates explicitly tell the agent not to rely on older
+appended rule/capability context unless it appears again. Context update events
+are stored in thread JSONL for change tracking, but they are not reconstructed as
+ordinary conversation items or included in compression input.
+
+## TUI
+
+The default TUI follows a Codex-style shape: a single transcript, inline Python runner events, full-screen focus panels, and a bottom composer with a bordered input box plus a compact status line.
+
+- `Enter`: insert a newline in the composer
+- `Ctrl+Enter` or `Ctrl+J`: send the composer text
+- `Esc`: clear the composer or close the open panel
+- `Ctrl+S` or `/status`: open detailed runtime status
+- `Ctrl+O` or `/threads`: open a searchable thread picker and resume history
+- `Ctrl+P`: open a full-screen command palette
+- Selecting composer text copies it after a short delay and shows a notification
+- `Ctrl+C`: press twice to interrupt a running turn; when idle, press twice to quit
+- `/quit`: quit after a second confirmation
+- `?` + `Ctrl+Enter` or `/help`: show local commands
+- `/context`: show context budget and loaded workspace rules
+- `/rules`: inspect loaded `AGENTS.md` files
+- `/new [title]`, `/threads`, and `/clear`: light thread controls
+- `/config`: edit user-facing settings (`default_level`, `language`, `auto_compress`) and show config sources / redacted merged config
+- `/models`: read-only view of configured models. Add or modify models in the config file; this command never writes
+- `/level [name]`: the only runtime model switch. Picks one of the levels defined in the config for this session
+- `/mcp`: show MCP declarations from `.agents/mcp.json`
+- `/skills` and `/skill [name]`: inspect `.agents/skills` entries
+- `/runs`: show the latest Python run summary from this TUI session
+- `/scripts`: show recent managed script summaries
+- `/panel`: reminder that panels close with `Esc`
+- Python runs appear inline with script/run ids, exit status, stdout/stderr summaries, and truncation markers
+- Reasoning/tool/runtime events appear as compact timeline entries; detailed run output remains available in `/runs`.
+- Typing `/` opens the full-screen command picker; `Ctrl+P` opens the same picker. Type to filter, use arrows/PageUp/PageDown to move, and Enter to select.
+- Temporary panels open as full-screen overlays with search/scroll/select behavior.
+
+For manual UI checks, Textual's `App.export_screenshot()` works in headless
+tests and writes SVG snapshots. Local debug captures belong under `.uv-agent/`
+so they stay out of git.