limbo-code 0.1.1__tar.gz → 0.1.10__tar.gz

{limbo_code-0.1.1 → limbo_code-0.1.10}/.github/workflows/test.yml

@@ -17,14 +17,24 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
 
+      # grep hard-depends on ripgrep (no Python fallback since LIM-24).
+      - name: Install ripgrep
+        run: sudo apt-get install -y ripgrep
+
+      # Install from uv.lock so CI renders snapshots with the exact same
+      # textual/rich/syrupy versions the baselines were generated with.
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: uv sync --frozen --extra dev
+        env:
+          UV_PYTHON: ${{ matrix.python-version }}
 
       - name: Run tests
-        run: python -m pytest -v
+        run: uv run python -m pytest -v

{limbo_code-0.1.1 → limbo_code-0.1.10}/.gitignore

@@ -11,3 +11,4 @@ venv/
 dist/
 build/
 .pi-subagents/
+snapshot_report.html

limbo_code-0.1.10/AGENTS.md

@@ -0,0 +1,94 @@
+# Limbo — Agent Guide
+
+**Limbo** is a minimal terminal AI coding agent (Python 3.11+, Textual). Users converse with an LLM in a TUI to explore, read, edit, and write code via 7 tools.
+
+**Tools execute immediately — no confirmation flow.** Convenience guardrails (not a security boundary): a workdir scope on file tools (+ session-scoped grants from user-mentioned paths), a sensitive-file skip list shared by `read`/`grep`/`find`, and a heuristic dangerous-command filter on `bash` (best-effort, rejects matches outright; `bash` is otherwise not covered by any guardrail).
+
+## Quick Start
+
+```bash
+pip install -e .
+limbo --workdir /path/to/project   # config: ~/.limbo/config.toml
+```
+
+## Architecture
+
+```
+src/limbo/
+├── app.py            # CLI entry: args, config, launch
+├── config.py         # Pydantic config: llm/ui/safety/tools/compaction/providers
+├── models.py         # Message, Attachment, ToolResult, LLMEvent
+├── agent.py          # Conversation loop (see below)
+├── attachments.py    # Attachment policy: vision gate, inline vs path-reference degrade
+├── compaction.py     # Context compaction decision/prompt logic (LIM-14)
+├── history.py        # tool_call↔result pairing + resume repair
+├── model_switch.py   # /model domain logic: validate, swap client, persist (UI is an adapter)
+├── prompt.py         # System-prompt assembly (tools section derived from the registry)
+├── steer.py          # Mid-turn steer queue (LIM-20): queueing semantics, cancel boundary
+├── sessions.py       # Session JSONL save/load/list/export
+├── trace.py          # Append-only JSONL run log (sessions/traces/)
+├── skills.py         # SKILL.md discovery (user + project dirs)
+├── user_paths.py     # Fence grants from paths in user messages
+├── llm/              # catalog.py (provider/model specs), factory.py (dialect→client),
+│                     # openai_client.py, anthropic_client.py, responses_client.py, retry.py, sse.py,
+│                     # usage.py (token accounting: usage normalization + prompt-size estimation),
+│                     # scaffold.py (plumbing shared by dialect clients: credentials, retry, images)
+├── tools/            # base.py (BaseTool + path guardrail + truncation), registry.py (dispatch, grants),
+│                     # mutation_queue.py (per-file locks), ignore.py (.gitignore),
+│                     # read/bash/edit/write/grep/find/ls.py
+└── ui/               # app.py + app.tcss (ALL styles here; theme vars only, no bare hex),
+                      # theme.py (limbo-dark/-light, RFC LIM-16), commands.py (slash registry),
+                      # screens/ (main, session_picker, model_picker, game2048),
+                      # widgets/ (chat, input, status_bar, tool_card, command_menu)
+```
+
+## Agent Loop
+
+- `Agent.run()` yields `AgentEvent`: `TextDelta`, `ThinkingDelta`, `ToolCallRequest`, `ToolResultEvent`, `ErrorEvent`, `CompactionEvent`, `UsageUpdate`, `SteerEvent`
+- Loop top: auto-compaction check → steer drain → LLM call. Turn ends on a tool-call-free response; `max_iterations` (default 50) cancels pending calls with placeholder results
+- Tool calls in one turn run **concurrently** (`[tools] parallel`); results stream in completion order, recorded in source order; same-file mutations serialized by `mutation_queue`
+- `finish_reason` `length`/`max_tokens` → whole batch failed without execution, model re-issues
+- Mid-turn user input queues as *steer* (LIM-20): injected at loop top, or as turn-end follow-up
+- Reasoning is stored on assistant messages and replayed per dialect (Anthropic thinking signatures, Kimi `reasoning_content`, Responses encrypted items)
+- Usage counters normalize in `llm/usage.py` (`input_tokens`+`cache_read`, `prompt_tokens`, DeepSeek cache hits) and feed the compaction trigger via `PromptSizeEstimator`
+
+## LLM & Config
+
+Providers/models live in `llm/catalog.py`; unknown models get generic OpenAI-compatible defaults. Resolution: `[providers.<id>]` overrides → explicit `[llm]` values → catalog defaults → env-var API keys.
+
+```toml
+[llm]        # model, api_key, base_url, temperature, max_iterations,
+             # max_tokens, thinking_effort, max_retries, timeout, ...
+[tools]      # bash_enabled = true, parallel = true
+[compaction] # enabled, reserve_tokens = 16384, keep_recent_tokens = 20000
+[safety]     # dangerous_commands, sensitive_files, auto_grant_user_paths
+[ui]         # theme, show_banner
+[providers.<id>]  # base_url / api_key / api_key_env / headers
+```
+
+`/model` rebuilds the client mid-session (refused while busy) and persists via tomlkit. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls and restores grants. Trace events: `session_start`, `user_message`, `llm_request` (full body), `llm_response`, `tool_call`, `tool_result`, `compaction*`, `error`, `turn_end`. `/export [path]` merges meta + trace + message snapshot (Markdown if `.md`).
+
+Skills: `~/.limbo/skills/<name>/SKILL.md` (user) and `<workdir>/.agents/skills/<name>/SKILL.md` (project, wins collisions) — injected as a `<available_skills>` catalog in the system prompt and invocable via `/<name> [args]`.
+
+## UI
+
+Single column: status bar (state/elapsed/tokens/model/workdir/queued) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /export /compact /model /help /2048` + skill commands. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
+
+## Key Decisions
+
+- Async agent, sync tools via `asyncio.to_thread()`
+- System prompt = hardcoded tool guidelines + `<workdir>/AGENTS.md` & `~/.limbo/AGENTS.md` (XML-wrapped) + skills catalog. **This file is injected into every request — keep it accurate and lean.**
+- Session files fully rewritten per save (atomic, 0600); trace holds full-fidelity record
+
+## Testing
+
+```bash
+pytest tests/ -v                  # pytest-asyncio, respx HTTP mocks, pytest-textual-snapshot
+ruff check src tests && mypy src  # lint + type check
+pytest --snapshot-update          # after intentional visual changes; review the SVG diff
+```
+
+## Adding Things
+
+- **Tool**: subclass `BaseTool` in `tools/<name>.py` (`name`/`description`/`parameters` + `run()`; use `resolve_existing()`/`resolve_creatable()`, raise `ToolError`), register in `ToolRegistry.__init__()`, wrap mutations in `mutation_lock_for(path)`, add `tests/tools/test_<name>.py`
+- **Provider/model**: add specs in `llm/catalog.py`; new wire format → implement `LLMClient` + `register_client()` in `llm/factory.py`. User-specific endpoint/key tweaks belong in `[providers.<id>]` config, not the catalog

limbo_code-0.1.10/CONTEXT.md

@@ -0,0 +1,43 @@
+# Context — Limbo domain glossary
+
+Domain language for Limbo's concepts. Architecture reviews and refactor
+proposals should name modules with these terms.
+
+## Token accounting
+
+- **Usage** — the provider-reported token counters on one completion. Each
+  dialect reports them differently (OpenAI `prompt_tokens`, Anthropic
+  `input_tokens` + cache counters, DeepSeek `prompt_cache_hit_tokens`,
+  Responses `input_tokens_details`). Normalized by `llm/usage.py` into
+  `UsageTotals` (prompt / cached / total); the agent loop and compaction
+  never read provider field names.
+- **Prompt-size estimation** — predicting the *next* request's prompt size:
+  the last real usage figure plus the chars/4 estimate of everything
+  appended since (the **watermark**). Owned by `PromptSizeEstimator` in
+  `llm/usage.py`; invalidated (reset) when compaction rewrites history.
+
+## Conversation
+
+- **Turn** — one user input through the agent loop until a tool-call-free
+  response (or max_iterations). Turns are the save/trace unit.
+- **Steer** — a user message queued mid-turn, injected at consistency
+  points (loop top, turn end, run head). The `SteerQueue` (`steer.py`) owns
+  queueing semantics — id generation, FIFO, and the cancel boundary (an
+  item can be cancelled by id only until drained); the Agent owns drain
+  timing.
+- **Compaction** — summarizing the old region of history into a synthetic
+  summary message, keeping the recent tail. Triggered automatically
+  (loop-top, before context overflow) or manually (`/compact`).
+- **Attachment policy** — how a submitted attachment reaches the model
+  (`attachments.py`): images become multimodal blocks for vision models
+  (encoded per dialect, `llm/scaffold.py`), everything else degrades to
+  text — small files inline (≤50KB), the rest as path references.
+- **Model switch** — `/model` mid-session (`model_switch.py`): validate the
+  target (API key, thinking-effort compatibility), swap the client
+  (converging on the latest config model), persist to config.toml. The UI
+  screen is an adapter translating verdicts into chat messages.
+
+## Safety
+
+- **Fence** — the workdir boundary on file tools, widened by session-scoped
+  **grants** (paths a real user mentions in a submitted message).

limbo_code-0.1.10/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: limbo-code
+Version: 0.1.10
+Summary: A minimal terminal AI coding agent
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pygments>=2.17
+Requires-Dist: textual>=8.0
+Requires-Dist: toml>=0.10
+Requires-Dist: tomlkit>=0.13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pygments>=2.17; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Limbo
+
+A minimal terminal AI coding agent.
+
+## Install
+
+Requires Python 3.11 or later.
+
+```bash
+pip install -e .
+```
+
+## Configure
+
+Create `~/.limbo/config.toml`:
+
+```toml
+[llm]
+api_key = "your-api-key"
+model = "deepseek-chat"
+base_url = "https://api.deepseek.com/v1"
+```
+
+Limbo speaks to LLMs through a **provider/model catalog**
+(`src/limbo/llm/catalog.py`). Each provider declares its API dialect,
+endpoint, and credential env var; each model carries its own context window,
+max output tokens, and thinking/reasoning behavior. A client factory
+(`src/limbo/llm/factory.py`) picks the client implementation from the
+provider's API dialect, so non-OpenAI dialects can be added without touching
+call sites. Models not in the catalog fall back to generic
+OpenAI-compatible defaults driven by `base_url` + `model` + `api_key`.
+
+Built-in providers:
+
+| Provider | API dialect | Endpoint | Key env var |
+|----------|-------------|----------|-------------|
+| `deepseek` | openai-completions | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |
+| `moonshotai` (Kimi) | openai-completions | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
+| `kimi-coding` (Kimi For Coding) | anthropic-messages | `https://api.kimi.com/coding` | `KIMI_API_KEY` |
+| `glm` (GLM Coding Plan) | openai-completions | `https://open.bigmodel.cn/api/coding/paas/v4` | `ZHIPUAI_API_KEY` |
+| `codex` (OpenAI Codex) | openai-responses | `https://api.openai.com/v1` (override with your relay) | `CODEX_API_KEY` |
+
+Built-in Codex models include `gpt-5.5`, `gpt-5.6-sol`/`terra`/`luna`,
+`gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`. **`gpt-5.5` is
+verified by live test against the target relay** (its 1M context is
+relay-reported); the other entries mirror pi's built-in catalog and are
+unverified — availability depends on the relay in use, and unknown or
+unsupported models fall back to the generic OpenAI-compatible defaults.
+Codex speaks the
+OpenAI **Responses API** (`POST {base_url}/responses`), served by a
+dedicated client (`src/limbo/llm/responses_client.py`, plain httpx SSE):
+system messages become `instructions`, tool definitions are flattened, and
+reasoning models stream `reasoning` summaries and replay encrypted
+reasoning items across turns. Limbo targets **API-key relays**, not the
+ChatGPT subscription backend (OAuth) — point the provider at your relay
+and make sure its model IDs match the catalog:
+
+```toml
+[llm]
+model = "gpt-5.5"
+
+[providers.codex]
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"
+```
+
+Built-in GLM Coding Plan models: `glm-4.7`, `glm-5.1`, `glm-5.2` (1M
+context), `glm-5-turbo`, `glm-5v-turbo` (vision), and `glm-4.5-air`. The
+Coding Plan is a subscription with its own endpoint and keys — a coding-plan
+key only works on the `/api/coding/paas/v4` endpoints (not the pay-per-token
+`/api/paas/v4` ones) and vice versa. For the international endpoint set
+`[providers.glm] base_url = "https://api.z.ai/api/coding/paas/v4"` (see
+below).
+
+Built-in Kimi models include `kimi-k3` (1M context, pay-per-token), and for
+Kimi For Coding subscriptions: `k3` (1M context), `kimi-for-coding`, and
+`kimi-for-coding-highspeed` (256K context). The two use different endpoints
+and keys — a `sk-kimi-*` Kimi For Coding key only works with the
+`kimi-coding` models (`k3`, ...) and vice versa.
+
+Switching to a catalog model only requires changing `model` — the provider's
+endpoint and key env var are picked up automatically:
+
+```toml
+[llm]
+model = "k3"             # Kimi For Coding; base_url/api_key resolve from the catalog
+```
+
+The `anthropic-messages` dialect is served by a dedicated client
+(`src/limbo/llm/anthropic_client.py`, plain httpx SSE) selected by the
+client factory. It converts OpenAI-style tool definitions to Anthropic's
+shape, merges consecutive tool results into a single user turn, and replays
+assistant thinking blocks with their signature.
+
+For the mainland-China Moonshot endpoint, set `base_url =
+"https://api.moonshot.cn/v1"` explicitly (a configured `base_url` always
+wins over the catalog — unless a `[providers.<id>]` override says otherwise,
+see below).
+
+### Per-provider overrides
+
+An optional `[providers.<id>]` section overrides a single catalog provider
+without touching the global `[llm]` settings — e.g. pointing a provider at a
+relay, renaming its credential env var, or adding extra headers:
+
+```toml
+[providers.glm]
+base_url = "https://api.z.ai/api/coding/paas/v4"  # international endpoint
+
+[providers.codex]
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"     # rename the env var read for the key
+headers = { x-relay = "on" }       # extra headers on every request
+```
+
+All fields are optional; unset fields fall back to the catalog. Resolution
+order for `base_url` (first hit wins):
+
+1. `[providers.<id>] base_url`
+2. `[llm] base_url` (when changed from the DeepSeek default)
+3. the catalog provider's built-in endpoint
+
+and for the API key: `[providers.<id>] api_key` → `[llm] api_key` → the
+environment variable (`[providers.<id>] api_key_env` rename, else the
+catalog's default env var).
+
+> **Note:** rule 1 is the single exception to the long-standing "an explicit
+> `[llm] base_url` always wins" behavior — a per-provider override is more
+> specific than the global setting. If you configure both, the
+> `[providers.<id>]` value is used for that provider's models.
+
+### Optional LLM settings
+
+```toml
+[llm]
+temperature = 0.2        # 0.0 - 2.0, default 0.2
+max_iterations = 50      # safety limit on tool-turn loops, default 50
+max_tokens = 8192        # output cap; default = the model's catalog value
+thinking_effort = "high" # reasoning control; default = provider behavior
+```
+
+`thinking_effort` is interpreted per model dialect:
+
+- `k3`, `kimi-for-coding*` (Anthropic adaptive thinking): `low` | `high` |
+  `max` → `thinking: {type: adaptive}` + `output_config.effort`. Thinking
+  cannot be disabled; temperature is omitted while thinking is enabled.
+- `kimi-k3` (moonshotai, OpenAI-style): `low` | `high` | `max` → sent as
+  `reasoning_effort`. Thinking cannot be disabled on K3.
+- `kimi-k2-thinking`, `kimi-k2.5`+ (DeepSeek-style): any non-`off` value →
+  `thinking: {type: enabled}`; `"off"` → `thinking: {type: disabled}`
+  (except `kimi-k2.7-code*`, where thinking is always on).
+- `glm-*` (z.ai-style): like DeepSeek-style but with `clear_thinking: false`
+  so thinking is preserved across turns; `glm-5.2` additionally maps
+  `low`/`high`/`max` to `reasoning_effort` (`low` clamps to `high`).
+- `gpt-5.*` codex models (Responses API): `low` | `medium` | `high` |
+  `xhigh` → `reasoning: {effort, summary: auto}`; 5.6-generation models
+  (`gpt-5.6-*`) also accept `max`. Temperature is omitted for reasoning
+  models.
+- Non-reasoning models: ignored.
+
+Reasoning output streams into the chat as muted thinking blocks and is
+stored on the assistant message so it can be replayed to APIs that require
+it (Kimi K3 rejects tool-call replays without `reasoning_content`).
+
+Optional tool settings:
+
+```toml
+[tools]
+bash_enabled = true
+```
+
+### Session storage
+
+Conversations are saved as JSONL files in `~/.limbo/sessions/` so you can
+review or debug them later. Use the `--session-dir` argument to redirect them
+to another location.
+
+Old session files are not automatically cleaned up; remove them manually when
+you no longer need them.
+
+## Run
+
+```bash
+limbo --workdir /path/to/project
+limbo --model glm-4.7        # override the configured model for this run
+```
+
+### Switching models at runtime
+
+Use `/model` in the TUI: without an argument it opens a picker that lists
+catalog models grouped by provider (context window, reasoning capability,
+and the current model are annotated; providers without a resolvable API key
+are dimmed with a hint). `/model <name>` switches directly — unknown names
+fall back to generic OpenAI-compatible defaults. The picker re-reads
+`config.toml` every time it opens, so edits (e.g. a newly added
+`[providers.<id>]`) apply without a restart.
+
+A switch takes effect immediately (no restart): the LLM client is rebuilt,
+and the new model is written back to `config.toml` (comments preserved via
+tomlkit) so the next launch keeps it. If the write fails, the switch still
+applies for the current session. Switching is refused while a turn is in
+flight.
+
+## Safety
+
+Limbo executes every tool call immediately, without asking for confirmation.
+
+File tools (`read`, `edit`, `write`, `grep`, `find`, `ls`) are scoped to the
+current working directory plus any session grants (paths the user mentions in
+a message), and `read`/`grep`/`find` skip a small blocklist of sensitive files
+(`.env`, SSH keys) to avoid leaking secrets into the model context by accident.
+**These are convenience guardrails against accidents, not a security boundary.**
+The path check resolves the path before each operation, so a symlink swapped
+between the check and the operation (a time-of-check-to-time-of-use race) could
+escape it.
+
+Bash is an exception: it is started in the working directory but is **not**
+covered by any of these guardrails. Commands can `cd ..`, use absolute paths,
+and read or write outside the workdir. Commands that match dangerous patterns
+such as `rm` or `git reset --hard` are **rejected outright** by a best-effort
+heuristic filter — ordinary shell constructs can bypass it, so it only
+protects against accidents. The pattern list is configurable but cannot be
+disabled from the UI. Only run Limbo with trusted commands and in
+repositories you can afford to modify or lose.
+
+If you need to work with untrusted projects, disable the bash tool entirely:
+
+```toml
+[tools]
+bash_enabled = false
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest tests/ -v
+```
+
+Run linting and type checks:
+
+```bash
+ruff check src tests
+mypy src
+```