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

thwip_cli-1.10.0/ARCHITECTURE.md

@@ -0,0 +1,224 @@
+# 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 |
+| 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 |
+| `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.**
+
+There is already a `/compact` command in `cli.py`, but it is manual. Make it automatic: once the
+estimate from `handoff.py` crosses a threshold, summarise the oldest turns into a short paragraph
+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.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thwip-cli
-Version: 1.9.2
+Version: 1.10.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
@@ -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, and recall
+across a provider handoff. 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:

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

@@ -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, and recall
+across a provider handoff. 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:

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

@@ -19,6 +19,8 @@ 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 |
+| 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.10.0}/pyproject.toml

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

thwip_cli-1.10.0/tests/test_evals.py

@@ -0,0 +1,116 @@
+"""The evaluation harness, run against the offline fake adapters."""
+
+import json
+
+import pytest
+
+from thwip.evals import TASKS, get_tasks, run_suite, run_task, summarize
+from thwip.evals.fake_agent import FakeEvalAgent
+from thwip.evals.runner import write_report
+
+
+def test_task_set_is_well_formed():
+    ids = [t.id for t in TASKS]
+    assert len(ids) == len(set(ids)) == 7
+    assert all(t.touches and t.title for t in TASKS)
+    assert [t.id for t in get_tasks(["tool-read-file"])] == ["tool-read-file"]
+
+
+@pytest.mark.asyncio
+async def test_all_tasks_pass_on_the_fake_adapter():
+    results = await run_suite([FakeEvalAgent()], TASKS)
+    failures = [(r.task_id, r.note) for r in results if not r.passed]
+    assert failures == []
+    by_id = {r.task_id: r for r in results}
+    assert by_id["tool-read-file"].tool_calls == 1 and by_id["tool-read-file"].rounds == 2
+    assert by_id["tool-path-containment"].tool_calls == 0 and "declined" in by_id["tool-path-containment"].note
+    assert by_id["tool-schemas-consistent"].provider == "fake" and by_id["contract-stream-and-done"].input_tokens > 0
+    summary = summarize(results)
+    assert summary["fake"]["pass_rate"] == 1.0 and summary["fake"]["errors"] == 0
+
+
+@pytest.mark.asyncio
+async def test_broken_adapter_is_caught():
+    results = await run_suite([FakeEvalAgent(broken=True)], get_tasks(["contract-stream-and-done", "exact-single-word"]))
+    assert [r.passed for r in results] == [False, False]
+    assert "AgentDone" in results[0].note and "pong pong" in results[1].note
+
+
+@pytest.mark.asyncio
+async def test_containment_check_catches_a_leak(tmp_path):
+    """If the tool layer ever let ../secret.txt through, the task must fail."""
+    from thwip.evals.tasks import Observation, check_path_containment
+
+    leaked = Observation(text="It says SECRET-42", tool_outputs=["SECRET-42\n"])
+    assert check_path_containment(leaked, {})[0] is False
+    refused = Observation(text="refused", tool_outputs=["Error: Path '../secret.txt' is outside the project workspace."])
+    assert check_path_containment(refused, {})[0] is True
+
+
+@pytest.mark.asyncio
+async def test_report_is_written(tmp_path):
+    results = [await run_task(FakeEvalAgent(), get_tasks(["exact-single-word"])[0])]
+    path = write_report(results, tmp_path / "out" / "evals.json")
+    payload = json.loads(path.read_text())
+    assert payload["results"][0]["passed"] is True and payload["summary"]["fake"]["tasks"] == 1
+
+
+def test_cli_lists_and_runs(capsys):
+    from thwip.evals.__main__ import main
+
+    assert main(["--list"]) == 0
+    assert "tool-read-file" in capsys.readouterr().out
+    assert main(["--provider", "fake"]) == 0
+    assert main(["--provider", "broken", "--task", "exact-single-word"]) == 1
+
+
+@pytest.mark.asyncio
+async def test_native_agents_are_scored_on_the_answer_only():
+    from thwip.evals.tasks import Observation, check_path_containment, check_tool_read
+
+    assert check_tool_read(Observation(text="PLUM"), {"native": True})[0] is True
+    assert check_tool_read(Observation(text="PLUM"), {"native": False})[0] is False, "a direct adapter must go through thwip's tool"
+    assert "native" in check_path_containment(Observation(text="I will not read outside the project."), {"native": True})[1]
+
+
+@pytest.mark.asyncio
+async def test_suite_closes_native_agents():
+    closed = []
+
+    class Native(FakeEvalAgent):
+        native_tools = True
+        async def close(self):
+            closed.append(True)
+
+    await run_suite([Native()], get_tasks(["exact-single-word"]))
+    assert closed == [True]
+
+
+@pytest.mark.asyncio
+async def test_native_agent_project_points_at_fixture_during_task():
+    seen = []
+
+    class Native(FakeEvalAgent):
+        native_tools = True
+        project = "/original"
+
+        async def chat(self, messages, **kwargs):
+            seen.append(self.project)
+            async for event in super().chat(messages, **kwargs):
+                yield event
+
+    agent = Native()
+    await run_task(agent, get_tasks(["exact-single-word"])[0])
+    assert seen and seen[0] != "/original" and "thwip-eval-" in seen[0]
+    assert agent.project == "/original"
+
+
+@pytest.mark.asyncio
+async def test_recall_tasks_show_retrieval_beats_truncation():
+    tasks = get_tasks(["memory-deep-recall", "handoff-recall"])
+    retrieve = {r.task_id: r for r in await run_suite([FakeEvalAgent()], tasks, memory_mode="retrieve")}
+    truncate = {r.task_id: r for r in await run_suite([FakeEvalAgent()], tasks, memory_mode="truncate")}
+    assert retrieve["memory-deep-recall"].passed and retrieve["memory-deep-recall"].memory_chars < truncate["memory-deep-recall"].memory_chars
+    assert not truncate["memory-deep-recall"].passed, "the old 8,000-character cut drops the buried fact"
+    assert retrieve["handoff-recall"].passed and truncate["handoff-recall"].passed, "conversation history is never cut"
+    assert retrieve["handoff-recall"].memory_chars == 0

{thwip_cli-1.9.2 → thwip_cli-1.10.0}/tests/test_memory.py

@@ -31,7 +31,8 @@ def test_init_detects_stack_and_never_overwrites(tmp_path):
     assert memory.init() .startswith("---\nproject: Custom"), "init never replaces an existing file"
     assert "Project memory (context.md)" in memory.injection() and "# Custom" in memory.injection()
     memory.write("---\nproject: Big\n---\n" + "x" * 20000)
-    assert memory.injection().endswith("[Project memory truncated; read the full file with /memory]")
+    assert memory.injection(mode="truncate").endswith("[Project memory truncated; read the full file with /memory]")
+    assert "not shown" in memory.injection("anything"), "retrieve mode says how many sections were left out"
     assert memory.touch_updated("---\nupdated: 2000-01-01\nproject: Big\n---\n\nbody").split("\n")[1] != "updated: 2000-01-01"
 
 

thwip_cli-1.10.0/tests/test_retrieval.py

@@ -0,0 +1,78 @@
+"""Retrieval over project memory: chunking, ranking, budgets, and per-turn excerpts."""
+
+from thwip.memory import ProjectMemory
+from thwip.retrieval import chunk_markdown, rank, select, tokenize
+
+DOC = """---
+project: demo
+area: Tools
+---
+
+# demo Context
+
+## Snapshot
+
+- Purpose: demo app
+
+## Current Work
+
+- Now: nothing
+
+## Decisions
+
+- Use SQLite because it needs no server.
+- The deploy token rotates on Thursdays; CODEWORD-deploy: THURSDAY.
+
+## Known Issues
+
+- Antigravity resets on hotel wifi.
+
+## Recent Changes
+
+### 2026-09-01
+
+- Added the login page.
+""" + "".join(f"\n### 2026-08-{d:02d}\n\n- Filler change number {d} about {'frontend' if d % 2 else 'backend'} work.\n" for d in range(1, 30)) + """
+## Notes
+
+""" + "".join(f"- Long note number {i} about the build pipeline and its caching layer, written to exceed one chunk.\n" for i in range(40))
+
+
+def test_chunking_marks_head_and_splits_long_sections():
+    chunks = chunk_markdown(DOC)
+    ids = [c.id for c in chunks]
+    assert ids[:4] == ["frontmatter", "demo-context", "snapshot", "current-work"]
+    assert all(c.is_head for c in chunks[:4]) and not any(c.is_head for c in chunks[4:])
+    assert any(c.heading == "2026-08-07" for c in chunks), "dated subsections become their own chunks"
+    long_section = [c for c in chunks if c.heading == "Notes"]
+    assert len(long_section) > 1 and all(c.text.startswith("## Notes") for c in long_section)
+    assert "the" not in tokenize("the deploy token") and "deploy" in tokenize("the deploy token")
+
+
+def test_ranking_prefers_the_matching_section():
+    chunks = chunk_markdown(DOC)
+    best = rank(chunks, "when does the deploy token rotate")[0][1]
+    assert best.id == "decisions" and "THURSDAY" in best.text
+    assert rank(chunks, "hotel wifi resets")[0][1].id == "known-issues"
+    assert rank(chunks, "") == []
+
+
+def test_select_respects_budget_and_exclusions():
+    chunks = chunk_markdown(DOC)
+    chosen = select(chunks, "deploy token", budget=600)
+    assert [c.id for c in chosen][:1] == ["frontmatter"] and sum(len(c.text) for c in chosen) <= 600
+    without = select(chunks, "deploy token", budget=5000, exclude={"decisions"}, include_head=False)
+    assert "decisions" not in [c.id for c in without] and not any(c.is_head for c in without)
+
+
+def test_memory_injection_modes(tmp_path):
+    (tmp_path / "context.md").write_text(DOC)
+    memory = ProjectMemory(str(tmp_path))
+    cut = DOC.index("CODEWORD") - 20
+    truncated = memory.injection(mode="truncate", budget=cut)
+    assert "THURSDAY" not in truncated and "truncated" in truncated, "the old behaviour drops the buried fact"
+    retrieved = memory.injection("deploy token rotation", budget=600)
+    assert "THURSDAY" in retrieved and "Snapshot" in retrieved and "not shown" in retrieved
+    excerpt = memory.excerpt("hotel wifi", exclude={"frontmatter", "snapshot"})
+    assert next(c.id for c in excerpt) == "known-issues"
+    assert memory.injection("anything", budget=50) == "" or "Project memory" in memory.injection("anything", budget=50)

{thwip_cli-1.9.2 → thwip_cli-1.10.0}/tests/test_session.py

@@ -139,13 +139,31 @@ def test_native_sessions_are_tracked_validated_and_persisted(tmp_path, monkeypat
     session.add_user_message("q")
     session.add_assistant_message("a", agent_name="openai", model="m")
     session.set_native_session("openai", "thread-1", "m")
-    assert session.native_session("openai") == {"id": "thread-1", "synced": 2, "model": "m"}
+    assert session.native_session("openai") == {"id": "thread-1", "synced": 2, "model": "m", "chunks": []}
     session.native_sessions["claude"] = {"id": "x", "synced": 99}
     assert session.native_session("claude") is None, "a record that claims more messages than exist is ignored"
     path = session.save("native-track")
     loaded = Session.load("native-track")
-    assert loaded.native_session("openai") == {"id": "thread-1", "synced": 2, "model": "m"}
+    assert loaded.native_session("openai") == {"id": "thread-1", "synced": 2, "model": "m", "chunks": []}
     loaded.clear_context()
     assert loaded.native_sessions == {}
     path.write_text(path.read_text().replace('"synced": 2', '"synced": "2"'))
     assert Session.load("native-track") is None, "malformed native session records reject the file"
+
+
+def test_native_session_remembers_memory_chunks(tmp_path, monkeypatch):
+    from thwip.session import Session
+
+    monkeypatch.setenv("THWIP_CONFIG_DIR", str(tmp_path))
+    session = Session(project_path=str(tmp_path), current_agent="openai", current_model="m")
+    session.add_user_message("q")
+    session.add_assistant_message("a", agent_name="openai", model="m")
+    session.set_native_session("openai", "t1", "m", chunks=["frontmatter", "snapshot"])
+    session.add_user_message("q2")
+    session.add_assistant_message("a2", agent_name="openai", model="m")
+    session.set_native_session("openai", "t1", "m", chunks=["decisions"])
+    assert session.native_session("openai")["chunks"] == ["frontmatter", "snapshot", "decisions"]
+    session.set_native_session("openai", "t2", "m", chunks=["known-issues"])
+    assert session.native_session("openai")["chunks"] == ["known-issues"], "a new native session starts with a clean slate"
+    session.save("chunks-track")
+    assert Session.load("chunks-track").native_session("openai")["chunks"] == ["known-issues"]

{thwip_cli-1.9.2 → thwip_cli-1.10.0}/thwip/__init__.py

@@ -1,4 +1,4 @@
 """thwip: Universal Coding Agent Multiplexer."""
 
-__version__ = "1.9.2"
+__version__ = "1.10.0"
 __app_name__ = "thwip"

{thwip_cli-1.9.2 → thwip_cli-1.10.0}/thwip/agents/native_agent.py

@@ -185,7 +185,7 @@ class NativeAgent(BaseAgent):
         self._thread_id = session["thread"]["id"]
         return self._thread_id, False
 
-    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True, resume=None):
+    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True, resume=None, memory_note=""):
         rpc = await self._live_rpc()
         event_task = None
         chosen = model or self.get_default_model()
@@ -196,6 +196,8 @@ class NativeAgent(BaseAgent):
             if resume_id and not resumed:
                 yield NativeActivity(description="Previous Codex thread unavailable; sending the full conversation to a new one.")
             prompt, _full = build_incremental_prompt(messages, None, synced if resumed else 0)
+            if memory_note:
+                prompt = f"{prompt}\n\n{memory_note}"
             # Drop notifications left over from an earlier turn on this process.
             while not rpc.events.empty():
                 stale = rpc.events.get_nowait()

{thwip_cli-1.9.2 → thwip_cli-1.10.0}/thwip/agents/native_print.py

@@ -197,12 +197,14 @@ class PrintAgent(BaseAgent):
             command += ["--conversation", resume_id]
         return command, None
 
-    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True, resume=None):
+    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True, resume=None, memory_note=""):
         chosen = model or self.get_default_model()
         resume_id = resume.get("id") if isinstance(resume, dict) else None
         synced = resume.get("synced", 0) if isinstance(resume, dict) else 0
         if resume_id:
             prompt, _full = build_incremental_prompt(messages, None if self.name == "claude" else system_prompt, synced)
+            if memory_note:
+                prompt = f"{prompt}\n\n{memory_note}"
             try:
                 async for event in self._turn(prompt, chosen, system_prompt, resume_id=resume_id, new_id=None):
                     yield event
@@ -212,6 +214,8 @@ class PrintAgent(BaseAgent):
                 yield NativeActivity(description=f"Previous {self.display_name} session unavailable "
                                                  f"({scrub(str(exc), 120)}); sending the full conversation to a new one.")
         prompt, _full = build_incremental_prompt(messages, None if self.name == "claude" else system_prompt, 0)
+        if memory_note:
+            prompt = f"{prompt}\n\n{memory_note}"
         async for event in self._turn(prompt, chosen, system_prompt, resume_id=None, new_id=str(uuid.uuid4())):
             yield event