thwip-cli 1.9.2__tar.gz → 1.11.0__tar.gz

thwip_cli-1.11.0/ARCHITECTURE.md

@@ -0,0 +1,222 @@
+# thwip — how it works, in plain language
+
+Written 2026-10-03 against version 1.9.2. About 8,700 lines of Python, 21 test files.
+
+## What thwip is
+
+You install one command. Inside it you can talk to seven different AI providers, swap between
+them in the middle of a conversation without losing what was said, and let them read and change
+files in your project with your approval.
+
+Nothing else does the swapping part. That is the idea the project is built around.
+
+## Status today
+
+| Thing | State |
+|---|---|
+| Published | Yes, on PyPI as `thwip-cli`, version 1.9.2 |
+| Providers | Seven: Anthropic, OpenAI, Google, DeepSeek, Groq, Ollama, OpenRouter |
+| Tools the AI can use | Four: file editing, terminal, code running, git |
+| Tests | 21 test files, all offline using fake providers |
+| Cost tracking | Yes, per provider, saved between runs |
+| Evaluation | Started 2026-10-03: `thwip/evals/` with five tasks, an offline fake adapter, and `python -m thwip.evals`. Run live against Claude Code, Antigravity and Codex the same day |
+| Compaction | Yes, since 2026-10-03: `compaction.py` summarises older turns on a provider other than the active one, keeps recent turns verbatim, and is offered automatically near the context window. Quota warnings come from the CLIs' own usage reports |
+| Retrieval | Yes, since 2026-10-03: `retrieval.py` splits `context.md` at headings and ranks sections against the current message with BM25; the head always goes, the rest by relevance, within a budget. No embeddings or vector store yet; measured by `memory-deep-recall` |
+
+## What it does today, in plain language
+
+**Finds what you already have.** On startup it scans your machine for installed AI tools and API
+keys, so you do not configure anything by hand. That is `detector.py` and `config.py`.
+
+**Talks to seven providers through one interface.** Each provider has its own adapter file that
+knows that provider's quirks. They all follow the same contract, so the rest of the program does
+not care which one is active. That is the `agents/` folder.
+
+**Switches providers mid-conversation.** When you switch, it takes everything said so far and
+re-sends it to the new provider, because the new provider has never seen any of it.
+
+**Lets the AI touch your files, with limits.** The AI can read files, write files, run commands,
+run code and inspect git. It cannot leave your project folder, and anything that changes a file
+asks you first. That is the `tools/` folder.
+
+**Keeps a project memory.** It reads a `context.md` file from your project and gives it to the AI
+as background, so the AI knows what the project is. That is `memory.py`.
+
+**Tracks what you spend.** Every request records tokens and estimated cost per provider. That is
+`limits.py` and `utils.estimate_cost`.
+
+**Warns you before an expensive switch.** It estimates how big the transfer will be and tells you
+if you are close to the new provider's limit. That is `handoff.py`.
+
+## What every file does
+
+### The starting points
+
+| File | Lines | What it does |
+|---|---|---|
+| `__main__.py` | 6 | Lets you run `python -m thwip` |
+| `cli.py` | 1,906 | The whole interactive terminal: the prompt loop, every slash command, the display. The biggest file by far |
+| `shortcuts.py` | 82 | Tab completion and keyboard shortcuts |
+| `theme.py` | 471 | All the colours, banners, tables and markdown rendering. Each provider gets its own brand colour |
+
+### Setup and discovery
+
+| File | Lines | What it does |
+|---|---|---|
+| `config.py` | 477 | Reads and writes `~/.thwip/config.toml`, finds API keys in environment variables and other tools' config files, runs first-time setup |
+| `detector.py` | 283 | Scans your machine for installed AI CLIs, npm packages, pip packages and editor extensions |
+| `endpoints.py` | 42 | Lets you point an adapter at a different server, for proxies or self-hosted models |
+
+### The provider adapters
+
+| File | Lines | What it does |
+|---|---|---|
+| `agents/base.py` | 424 | The contract every adapter must follow. Defines what a capability is, what events can come back while streaming, and what a model's limits are. Everything else inherits from this |
+| `agents/__init__.py` | 141 | The registry: finds the adapters, lists which are ready, picks a fallback when one hits a limit |
+| `agents/claude_agent.py` | 464 | Anthropic |
+| `agents/openai_agent.py` | 459 | OpenAI |
+| `agents/google_agent.py` | 437 | Google Gemini |
+| `agents/deepseek_agent.py` | 235 | DeepSeek, over an OpenAI-shaped API |
+| `agents/openrouter_agent.py` | 223 | OpenRouter, which fronts 100+ models |
+| `agents/ollama_agent.py` | 218 | Local models on your own machine. Free, private, no quota |
+| `agents/groq_agent.py` | 203 | Groq, the fast one |
+| `agents/catalog.py` | 139 | Asks each provider which models it actually offers right now, instead of trusting a hardcoded list |
+| `agents/chat_messages.py` | 20 | Converts tool arguments into the format the Chat Completions API expects |
+
+### Driving other people's CLIs
+
+These exist because some tools are signed in through their own app, and thwip should use that
+sign-in rather than ask for an API key.
+
+| File | Lines | What it does |
+|---|---|---|
+| `agents/native_print.py` | 357 | Runs the Claude Code and Antigravity CLIs one turn at a time and reads their streamed output |
+| `agents/native_agent.py` | 288 | Talks to the Codex App Server over JSON-RPC |
+| `agents/native_common.py` | 129 | Shared helpers: scrubbing output, classifying rate limits, building prompts |
+| `agents/native_rpc.py` | 86 | The transport that starts the other process and sends messages to it |
+
+### The tools the AI can use
+
+| File | Lines | What it does |
+|---|---|---|
+| `tools/__init__.py` | 265 | The registry. Also translates one tool definition into both OpenAI's and Anthropic's formats, because they disagree on the shape |
+| `tools/file_editor.py` | 127 | Read, write, edit and list files inside the project folder |
+| `tools/terminal.py` | 99 | Run shell commands, with process-tree cleanup so nothing is left running |
+| `tools/code_runner.py` | 60 | Run Python and Node snippets |
+| `tools/git_ops.py` | 44 | Status, diff and log. Read-only |
+
+### Evaluation
+
+| File | Lines | What it does |
+|---|---|---|
+| `evals/tasks.py` | ~150 | The task set. Each task says which source file it exercises and carries a deterministic check |
+| `evals/runner.py` | ~190 | Runs a task the way the REPL would (tool rounds included), records latency, tokens, cost and tool calls, applies the check, writes JSON |
+| `evals/fake_agent.py` | ~70 | A rule-based adapter that follows the event contract, so the harness runs with no network |
+| `evals/__main__.py` | ~90 | `python -m thwip.evals`: list, run offline, run live, save a report |
+
+### State, memory and accounting
+
+| File | Lines | What it does |
+|---|---|---|
+| `session.py` | 291 | Holds the conversation. Converts it to a plain provider-neutral list when switching. Saves and reloads sessions |
+| `memory.py` | ~450 | Reads and writes the project's `context.md`, chooses which sections to send for a question, and syncs an Obsidian vault of project cards. Only ever overwrites files it created itself |
+| `retrieval.py` | ~140 | Heading-based chunking and BM25 ranking for project memory. Deterministic, no model, no network |
+| `compaction.py` | ~90 | Worker selection (never the active provider), the summary request, and the split between summarised and verbatim turns |
+| `limits.py` | 112 | Records tokens and cost per provider, remembers when you hit a limit, saves it to disk |
+| `handoff.py` | 93 | Before a switch, estimates the request size, fingerprints the text, and reports which capabilities you gain or lose |
+| `utils.py` | 107 | Cost estimation, token formatting, stream collection, key masking |
+
+## How one question actually flows through the code
+
+1. You type into the prompt in `cli.py`.
+2. `session.py` adds your message to the conversation.
+3. `memory.py` reads the project's `context.md`, keeps its head, and adds the sections `retrieval.py` ranks highest for your message, within a budget.
+4. `tools/__init__.py` produces the tool definitions in the shape the active provider expects.
+5. The active adapter in `agents/` sends: the system prompt, the project memory, the whole
+   conversation so far, and the tool definitions.
+6. The reply streams back as a series of small events: text, thinking, a tool request, token counts.
+7. If the model asks for a tool, the tool runs. If it changes a file, you are asked first.
+8. The tool result goes back to the model and it continues.
+9. `limits.py` records the tokens and cost.
+10. `theme.py` renders it all.
+
+## The context cost when you switch, and how to cut it
+
+### What happens now
+
+Providers keep no memory of your conversation. Everything lives on your machine. So when you
+switch, `session.to_portable_messages()` flattens the entire conversation into a plain list and the
+new adapter sends all of it again.
+
+Read that function and notice what it does not do: there is no trimming, no summarising, no limit.
+Every user and assistant message, from the first one, goes every time.
+
+So a single switch sends:
+
+- the system prompt
+- up to 8,000 characters of project memory
+- every message in the conversation so far
+- the full tool definitions
+
+Your actual question might be twenty words. The rest is overhead, and it repeats on every switch.
+
+`handoff.py` already measures this for you. It reports `estimated_input_tokens` and a
+`context_pressure` of "below advisory budget", "near limit" or "likely over budget". The measuring
+instrument exists. Nothing acts on it yet.
+
+### Three ways to cut it, in order of payoff
+
+**1. Send the relevant part of the project memory, not the first part.**
+
+`memory.injection()` reads `context.md` and keeps the first 8,000 characters. Your thwip context
+file is about 27,700 characters, so roughly two thirds is discarded, and what survives is the top of
+the file rather than the part that answers the question.
+
+Fix: split the file into chunks by heading, convert each chunk into an embedding once, store them,
+and at question time send only the few chunks closest in meaning to what was asked. Typical result
+is a few hundred tokens instead of two thousand, and better answers because there is less noise.
+
+**2. Trim old conversation turns.** Done: `/compact` and the automatic offer at 65 percent of the window summarise older turns on another provider and keep the recent ones verbatim.
+
+**3. Send tool definitions only when they are needed.**
+
+Full tool schemas go with every request. For a conversation that is not touching files, that is
+wasted. Decide per turn whether tools are plausibly needed.
+
+### How to prove it worked
+
+Do item 1 first, and record `estimated_input_tokens` and cost per switch before and after. That
+before-and-after number is the single most interesting thing you can put on a resume about this
+project, because it is a measurement, not a claim.
+
+## What is missing to call this an AI engineering project
+
+What is already here and counts: multi-provider integration, tool calling with provider-native
+continuations, streaming, human approval before any mutation, cost and token accounting, retries
+and fallback, offline tests with fake providers.
+
+What is missing:
+
+| Missing | Why it matters |
+|---|---|
+| Evaluation harness | No way to tell whether a change made the system better or worse. Every job description asks for this |
+| Published benchmark | Seven providers wired up and never compared. The comparison is the differentiator nobody else can make cheaply |
+| Retrieval | Project memory is truncated rather than searched |
+| Structured outputs with validation | Only one adapter touches schemas. No validate-and-repair loop |
+| Tracing | Tokens and cost are counted, but there is no per-request record of latency, tool calls and errors you can query |
+| Output guardrails | Path containment and approvals protect the filesystem. Nothing checks the model's output itself |
+
+## Build order
+
+1. **Evaluation harness, about two weeks.** 30 to 50 tasks with a defined success condition. Score
+   across all seven providers. Record pass rate, latency, cost, tool-call success, malformed output.
+   Run it in CI so a regression fails the build. Writing these tasks is also how you will learn this
+   codebase properly, because you cannot test the tool layer without reading it.
+2. **Published benchmark, a few days.** Put the numbers on the thwip website with the method.
+3. **Retrieval in `memory.py`, one to two weeks.** Chunk, embed, store locally, retrieve top matches.
+   Measure it with the harness from step 1.
+4. **Structured outputs, a few days.** Schemas, validation, repair retry on malformed JSON.
+5. **Tracing, a few days.** One record per request: model, latency, tokens, cost, tools, errors.
+
+Skip fine-tuning. Skip rewriting any of this in LangChain; the hand-written adapter layer is the
+part that makes the project distinctive.

{thwip_cli-1.9.2 → thwip_cli-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thwip-cli
-Version: 1.9.2
+Version: 1.11.0
 Summary: Universal coding agent multiplexer: detect, switch, and route between AI coding agents seamlessly
 Project-URL: Homepage, https://github.com/tanmayhutt/thwip-cli
 Project-URL: Repository, https://github.com/tanmayhutt/thwip-cli
@@ -108,7 +108,7 @@ thwip install-man               # then `man thwip` works
 | `/model [id]` | Pick a model for the current agent from a numbered list or by ID |
 | `/new` | Start a fresh conversation; the current one is saved first |
 | `/resume [name]` | Resume a saved session from a numbered list |
-| `/compact` | Summarize the conversation with the current model to free context; the summary is plain text and travels across providers |
+| `/compact` | Summarize older turns on another provider and keep recent turns verbatim; the summary is plain text and travels across providers |
 | `/diff [staged]` | Show the project's git diff |
 | `/copy` | Copy the last response to the clipboard |
 | `/export [path]` | Write the conversation to Markdown with per-message model attribution |
@@ -203,6 +203,16 @@ notes are never touched.
 | `/memory link` | Add a pointer to `AGENTS.md` and `CLAUDE.md` so the CLIs read it outside thwip too |
 | `/memory sync all` | File every project found under the configured `scan` folders and rebuild all cross-project links at once |
 
+**How the memory reaches the model.** The file is split into sections at its headings. The head
+(frontmatter, Snapshot, Current Work) always goes. The rest is ranked against your current message
+with BM25, the keyword-ranking formula used by search engines, and the best-matching sections are
+added within a character budget. A warm native session is only sent sections it has not already
+seen, as an excerpt attached to the message. Nothing is truncated from the top any more; a note
+says how many sections were left out so the model can ask. No embeddings, no vector database:
+at a few dozen sections per project that would add a dependency without adding recall. The
+`memory-deep-recall` evaluation task measures this against the old first-8,000-characters behaviour
+(`python -m thwip.evals --memory truncate`).
+
 When you `/quit` after a real conversation, thwip offers the update once. Settings live under
 `[memory]` in `~/.thwip/config.toml`:
 
@@ -220,6 +230,26 @@ If your vault already has hand-written project notes under `Projects/`, set `car
 subfolder such as `Projects/thwip`. thwip's cards, hubs, and dashboard then live inside that
 folder and link among themselves, and your own notes stay untouched.
 
+## Evaluation harness
+
+`thwip.evals` runs a fixed set of tasks against any adapter and scores them deterministically:
+pass or fail, latency, tokens, estimated cost, tool calls, malformed tool calls. The same tasks run
+against an in-process fake adapter, so the scoring code is itself tested offline and in CI.
+
+```bash
+python -m thwip.evals --list                 # the task set and the source file each task exercises
+python -m thwip.evals                        # offline, against the fake adapter; exit code 1 on any failure
+python -m thwip.evals --provider broken      # a deliberately bad adapter, to see failures reported
+python -m thwip.evals --provider all --out evals.json   # every ready provider, results saved as JSON
+python -m thwip.evals --provider openai --task tool-read-file
+```
+
+Each task names the file it tests: the streaming event contract in `agents/base.py`, exact
+instruction following, a tool round trip and the path guard in `tools/`, the consistency of
+the OpenAI and Anthropic tool schemas, deep recall from a long project memory file, recall
+across a provider handoff, recall after compaction, and the compaction worker rule. Native CLIs bring their own tools, so for them the tool
+tasks score the final answer only and say so in the note.
+
 ## Live model lists
 
 Model lists are not hardcoded. Each connected source supplies its own list:
@@ -253,6 +283,35 @@ The repository uses this to run every direct adapter end to end against a local
 provider in `tests/fake_providers.py`, so streaming, tool rounds, live catalogs, and
 HTTP 429 handling are verified through the real SDKs without spending on real keys.
 
+## Compaction and early warnings
+
+Two different limits, two different protections.
+
+**Context window.** When the conversation's estimated size reaches `compact_at_percent` of the
+active model's window (65 percent by default; models that publish no window are assumed to have
+`assumed_context_tokens`, 200,000), thwip offers to compact. Compaction summarises the older turns
+and keeps the last `keep_recent_messages` (4) word for word. The summary is written by a ready
+provider other than the active one, because the provider that is running out of room or quota is
+the one that cannot be trusted with one more request; the active provider is used only when nothing
+else is connected, with a warning. `/compact` does the same on demand. The transcript on disk is
+never deleted. Every provider's warm session restarts from the compact history on its next turn.
+
+**Usage quota.** Codex and Claude Code report their 5-hour and 7-day usage after each turn. When a
+window reaches `quota_warn_percent` (85 percent by default) thwip warns once per window and names
+the ready alternatives, so you can switch before the limit hits rather than after. Antigravity
+reports no windows, so for it the first signal is still the limit error, which failover handles.
+
+```toml
+[limits]
+quota_warn_percent = 85
+compact_at_percent = 65
+assumed_context_tokens = 200000
+keep_recent_messages = 4
+```
+
+The evaluation harness covers both: `compaction-recall` checks a fact from early in a long
+conversation survives summarisation, and `compaction-worker-never-active` checks the worker rule.
+
 ## Usage-limit failover
 
 When the active provider reports an exhausted limit (Codex "You've hit your usage

{thwip_cli-1.9.2 → thwip_cli-1.11.0}/README.md

@@ -71,7 +71,7 @@ thwip install-man               # then `man thwip` works
 | `/model [id]` | Pick a model for the current agent from a numbered list or by ID |
 | `/new` | Start a fresh conversation; the current one is saved first |
 | `/resume [name]` | Resume a saved session from a numbered list |
-| `/compact` | Summarize the conversation with the current model to free context; the summary is plain text and travels across providers |
+| `/compact` | Summarize older turns on another provider and keep recent turns verbatim; the summary is plain text and travels across providers |
 | `/diff [staged]` | Show the project's git diff |
 | `/copy` | Copy the last response to the clipboard |
 | `/export [path]` | Write the conversation to Markdown with per-message model attribution |
@@ -166,6 +166,16 @@ notes are never touched.
 | `/memory link` | Add a pointer to `AGENTS.md` and `CLAUDE.md` so the CLIs read it outside thwip too |
 | `/memory sync all` | File every project found under the configured `scan` folders and rebuild all cross-project links at once |
 
+**How the memory reaches the model.** The file is split into sections at its headings. The head
+(frontmatter, Snapshot, Current Work) always goes. The rest is ranked against your current message
+with BM25, the keyword-ranking formula used by search engines, and the best-matching sections are
+added within a character budget. A warm native session is only sent sections it has not already
+seen, as an excerpt attached to the message. Nothing is truncated from the top any more; a note
+says how many sections were left out so the model can ask. No embeddings, no vector database:
+at a few dozen sections per project that would add a dependency without adding recall. The
+`memory-deep-recall` evaluation task measures this against the old first-8,000-characters behaviour
+(`python -m thwip.evals --memory truncate`).
+
 When you `/quit` after a real conversation, thwip offers the update once. Settings live under
 `[memory]` in `~/.thwip/config.toml`:
 
@@ -183,6 +193,26 @@ If your vault already has hand-written project notes under `Projects/`, set `car
 subfolder such as `Projects/thwip`. thwip's cards, hubs, and dashboard then live inside that
 folder and link among themselves, and your own notes stay untouched.
 
+## Evaluation harness
+
+`thwip.evals` runs a fixed set of tasks against any adapter and scores them deterministically:
+pass or fail, latency, tokens, estimated cost, tool calls, malformed tool calls. The same tasks run
+against an in-process fake adapter, so the scoring code is itself tested offline and in CI.
+
+```bash
+python -m thwip.evals --list                 # the task set and the source file each task exercises
+python -m thwip.evals                        # offline, against the fake adapter; exit code 1 on any failure
+python -m thwip.evals --provider broken      # a deliberately bad adapter, to see failures reported
+python -m thwip.evals --provider all --out evals.json   # every ready provider, results saved as JSON
+python -m thwip.evals --provider openai --task tool-read-file
+```
+
+Each task names the file it tests: the streaming event contract in `agents/base.py`, exact
+instruction following, a tool round trip and the path guard in `tools/`, the consistency of
+the OpenAI and Anthropic tool schemas, deep recall from a long project memory file, recall
+across a provider handoff, recall after compaction, and the compaction worker rule. Native CLIs bring their own tools, so for them the tool
+tasks score the final answer only and say so in the note.
+
 ## Live model lists
 
 Model lists are not hardcoded. Each connected source supplies its own list:
@@ -216,6 +246,35 @@ The repository uses this to run every direct adapter end to end against a local
 provider in `tests/fake_providers.py`, so streaming, tool rounds, live catalogs, and
 HTTP 429 handling are verified through the real SDKs without spending on real keys.
 
+## Compaction and early warnings
+
+Two different limits, two different protections.
+
+**Context window.** When the conversation's estimated size reaches `compact_at_percent` of the
+active model's window (65 percent by default; models that publish no window are assumed to have
+`assumed_context_tokens`, 200,000), thwip offers to compact. Compaction summarises the older turns
+and keeps the last `keep_recent_messages` (4) word for word. The summary is written by a ready
+provider other than the active one, because the provider that is running out of room or quota is
+the one that cannot be trusted with one more request; the active provider is used only when nothing
+else is connected, with a warning. `/compact` does the same on demand. The transcript on disk is
+never deleted. Every provider's warm session restarts from the compact history on its next turn.
+
+**Usage quota.** Codex and Claude Code report their 5-hour and 7-day usage after each turn. When a
+window reaches `quota_warn_percent` (85 percent by default) thwip warns once per window and names
+the ready alternatives, so you can switch before the limit hits rather than after. Antigravity
+reports no windows, so for it the first signal is still the limit error, which failover handles.
+
+```toml
+[limits]
+quota_warn_percent = 85
+compact_at_percent = 65
+assumed_context_tokens = 200000
+keep_recent_messages = 4
+```
+
+The evaluation harness covers both: `compaction-recall` checks a fact from early in a long
+conversation survives summarisation, and `compaction-worker-never-active` checks the worker rule.
+
 ## Usage-limit failover
 
 When the active provider reports an exhausted limit (Codex "You've hit your usage

{thwip_cli-1.9.2 → thwip_cli-1.11.0}/docs/verification.md

@@ -19,6 +19,9 @@ each using its existing sign-in. No API keys were configured.
 | Ctrl+C during a response | Turn cancelled, child process terminated, REPL continued, unanswered message removed |
 | Ctrl+C at a Codex permission prompt | Turn cancelled, no file created, no leftover process, REPL continued |
 | Usage-limit failover | With a test-only shim making Codex report "You've hit your usage limit", the real REPL showed the alternatives, switched to Claude Code on `1`, retried the message, and answered; history held one clean pair |
+| Compaction and quota warnings (2026-10-03) | Live with lowered thresholds: Codex received per-window quota warnings naming Claude Code and Antigravity as ready; the compaction offer appeared as the conversation grew; on `y` Claude Code wrote the summary while Codex was active; Codex then recalled the early code word from the compacted history; no leftover processes. Offline: worker never the active provider, recent turns kept starting at a user message, limit and empty-summary errors, offer fires once per size, warning once per window |
+| Retrieval for project memory (2026-10-03) | Offline: `memory-deep-recall` fails in truncate mode and passes in retrieve mode with fewer memory characters; `handoff-recall` passes in both because conversation history is never cut. Live numbers recorded in context.md |
+| Evaluation harness (2026-10-03) | Five tasks pass on the offline fake; the broken fake fails the contract and exact-word tasks as intended. Live run over Claude Code, Antigravity and Codex: all three pass the contract, exact-word and containment tasks; the read-file task scores native CLIs on the answer only because their tool calls are not observable. Latency per task: Claude Code 4 to 14 s, Codex 5 to 37 s, Antigravity 40 to 45 s on this network |
 | First-run and returning-user walkthrough (v1.9.2) | Driven as a brand-new user from an empty config: onboarding, chat, `/memory init`, compact `/switch`, `/status`, `/memory update` with diff, quit offer; then restart, `/resume`, `/history`, `/memory`, Ctrl+C exit with the memory offer. Fixed on the way: `/switch` printed four blocks (now one line unless a capability is lost), long paths wrapped every panel (now shown relative to home), the template wrote an empty `tags: []`, `/status` showed an API-key field for native agents, sessions stored the project as `.` so `/resume` from another directory pointed at the wrong project, `/resume <number>` was not accepted, and Ctrl+C at the prompt skipped the memory offer |
 | Config sections (v1.9.0) | Found and fixed: the loader's section whitelist dropped `[memory]` and `[endpoints]`, so onboarding repeated and file-based endpoint overrides were ignored. Round-trip regression test added |
 | Vault sync all (v1.9.0) | `/memory sync all` over the three project collections filed 26 cards under `Projects/thwip/` with Stack, Areas, and Tags hubs and a dashboard inside that folder, and left every hand-written note untouched |

{thwip_cli-1.9.2 → thwip_cli-1.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thwip-cli"
-version = "1.9.2"
+version = "1.11.0"
 description = "Universal coding agent multiplexer: detect, switch, and route between AI coding agents seamlessly"
 readme = "README.md"
 license = "MIT"

thwip_cli-1.11.0/tests/test_compaction.py

@@ -0,0 +1,139 @@
+"""Compaction on a different provider, proactive offers, and quota warnings."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from thwip.agents.base import AgentDone, LimitHit, LimitStatus, TextDelta
+from thwip.compaction import choose_worker, compacted_messages, split_for_compaction, summarize, transcript
+
+
+class Agent:
+    capabilities = set()
+
+    def __init__(self, name, reply="summary text", limit=False):
+        self.name = name
+        self.display_name = name
+        self.company = name
+        self.reply = reply
+        self.limit = limit
+        self.calls = 0
+
+    def is_configured(self):
+        return True
+
+    def get_default_model(self):
+        return f"{self.name}-model"
+
+    def get_handoff_models(self):
+        from thwip.agents.base import ModelInfo
+        return [ModelInfo(id=f"{self.name}-model", name=self.name)]
+
+    def get_model_info(self, model_id):
+        return next((m for m in self.get_handoff_models() if m.id == model_id), None)
+
+    async def chat(self, **kwargs):
+        self.calls += 1
+        if self.limit:
+            yield LimitHit(error_type=LimitStatus.QUOTA_EXHAUSTED, message="usage limit")
+            return
+        yield TextDelta(content=self.reply)
+        yield AgentDone()
+
+
+def test_worker_is_never_the_active_provider_when_another_is_ready():
+    a, b, c = Agent("a"), Agent("b"), Agent("c")
+    assert choose_worker(a, [a, b, c]) is b
+    assert choose_worker(a, [a, b, c], chain=["c/m", "b/m"]) is c
+    assert choose_worker(a, [a]) is a, "last resort: the active provider when nothing else exists"
+    assert choose_worker(a, []) is a, "a connected active provider is still a last resort"
+    assert choose_worker(SimpleNamespace(name="z", is_configured=lambda: False), []) is None
+
+
+def test_split_keeps_recent_turns_starting_at_a_user_message():
+    history = [{"role": "user", "content": f"q{i}"} if i % 2 == 0 else {"role": "assistant", "content": f"a{i}"} for i in range(10)]
+    older, recent = split_for_compaction(history, 3)
+    assert [m["content"] for m in recent] == ["q8", "a9"], "an odd cut moves forward to the next user message"
+    assert len(older) == 8
+    assert split_for_compaction(history, 0) == (history, [])
+    assert split_for_compaction(history[:2], 4) == (history[:2], [])
+    assert "[User]\nq0" in transcript(history)
+
+
+@pytest.mark.asyncio
+async def test_summarize_uses_the_worker_and_reports_limits():
+    worker = Agent("b", reply="  Context\n- things  ")
+    assert await summarize(worker, [{"role": "user", "content": "x"}]) == "Context\n- things"
+    with pytest.raises(RuntimeError, match="hit a limit"):
+        await summarize(Agent("c", limit=True), [{"role": "user", "content": "x"}])
+    with pytest.raises(RuntimeError, match="empty summary"):
+        await summarize(Agent("d", reply="   "), [{"role": "user", "content": "x"}])
+    compact = compacted_messages("S", [{"role": "user", "content": "recent"}])
+    assert compact[0]["content"].endswith("S") and compact[-1]["content"] == "recent" and len(compact) == 3
+
+
+@pytest.fixture
+def cli(tmp_path, monkeypatch):
+    from thwip.cli import ThwipCLI
+    from thwip.config import ThwipConfig
+    from thwip.session import Session
+    from thwip.tools import ToolManager
+
+    monkeypatch.setenv("THWIP_CONFIG_DIR", str(tmp_path / "cfg"))
+    cli = ThwipCLI.__new__(ThwipCLI)
+    cli.config = ThwipConfig(project=str(tmp_path), auto_save=False)
+    cli.tool_manager = ToolManager(str(tmp_path))
+    cli.session = Session(project_path=str(tmp_path), current_agent="a", current_model="a-model")
+    active, other = Agent("a"), Agent("b", reply="Context\n- CODEWORD is OLIVE")
+    cli.current_agent = active
+    cli.registry = SimpleNamespace(get_ready_agents=lambda: [active, other], get_agent=lambda n: active)
+    for i in range(6):
+        cli.session.add_user_message(f"question {i}")
+        cli.session.add_assistant_message(f"answer {i}", agent_name="a", model="a-model")
+    cli.session.set_native_session("a", "thread-1", "a-model")
+    return cli, active, other
+
+
+@pytest.mark.asyncio
+async def test_cmd_compact_uses_other_provider_and_keeps_recent_turns(cli):
+    cli, active, other = cli
+    assert await cli.cmd_compact() is True
+    assert other.calls == 1 and active.calls == 0, "the active provider never writes its own summary"
+    contents = [m.content for m in cli.session.messages]
+    assert contents[0].startswith("Summary of the conversation so far") and "OLIVE" in contents[0]
+    assert contents[-4:] == ["question 4", "answer 4", "question 5", "answer 5"]
+    assert cli.session.native_sessions == {}, "native sessions restart from the compact history"
+
+
+@pytest.mark.asyncio
+async def test_compaction_offer_fires_once_near_the_window(cli, monkeypatch):
+    cli, _active, _other = cli
+    cli.config.limits.assumed_context_tokens = 300
+    cli.config.limits.compact_at_percent = 50
+    asked = []
+
+    async def ask(question):
+        asked.append(question)
+        return "n"
+    monkeypatch.setattr(cli, "_ask_text", ask)
+    await cli._maybe_offer_compaction()
+    await cli._maybe_offer_compaction()
+    assert len(asked) == 1 and "using b" in asked[0] and asked[0].startswith("Compact")
+    cli.config.limits.assumed_context_tokens = 10_000_000
+    cli._compaction_offered_at = 0
+    await cli._maybe_offer_compaction()
+    assert len(asked) == 1, "no offer when the conversation is small"
+
+
+def test_quota_warning_recommends_a_ready_alternative(cli, monkeypatch):
+    cli, active, _other = cli
+    printed = []
+    monkeypatch.setattr("thwip.cli.print_warning", lambda message: printed.append(message))
+    active.limit_windows = [{"label": "5h", "used_percent": 91, "resets_at": 1790000000},
+                            {"label": "7d", "used_percent": 20, "resets_at": None}]
+    cli._quota_warning()
+    cli._quota_warning()
+    assert len(printed) == 1 and "91%" in printed[0] and "/switch b" in printed[0]
+    active.limit_windows[0]["resets_at"] = 1790009999
+    cli._quota_warning()
+    assert len(printed) == 2, "a new window (new reset time) warns again"