thwip-cli 1.6.2__tar.gz → 1.7.0__tar.gz

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thwip-cli
-Version: 1.6.2
+Version: 1.7.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
@@ -85,6 +85,8 @@ Start the interactive terminal in your current project directory:
 thwip
 thwip --project ~/code/my-app   # open a specific project
 thwip --version
+thwip man                       # read the manual page
+thwip install-man               # then `man thwip` works
 ```
 
 ---
@@ -142,6 +144,16 @@ not in the catalog is passed to the CLI for validation instead of being rejected
 a bundled list. A model available in a desktop app may still be absent from the
 installed CLI's catalog or account access.
 
+Each provider keeps a warm native session. The first message to a provider sends the
+portable conversation once; after that only new messages are sent. Codex keeps one
+`app-server` process running and resumes its thread; Claude Code uses `--session-id`
+and `--resume`; Antigravity uses `--conversation`. When you come back to a provider after
+chatting with another one, it receives a short catch-up block containing only what it
+missed. The native session IDs are stored in the thwip session file next to the
+transcript, validated on load, shown by `/status`, and cleared by `/new`, `/clear`,
+`/compact`, and a project change. If a CLI can no longer continue a session, thwip says
+so and resends the full conversation to a fresh one.
+
 Native connections are read-only by default. Codex starts with a read-only sandbox
 and asks before operations outside it; approval requests appear in Thwip with the
 command or file list and default to denial. Claude Code and the Antigravity CLI run

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/README.md

@@ -48,6 +48,8 @@ Start the interactive terminal in your current project directory:
 thwip
 thwip --project ~/code/my-app   # open a specific project
 thwip --version
+thwip man                       # read the manual page
+thwip install-man               # then `man thwip` works
 ```
 
 ---
@@ -105,6 +107,16 @@ not in the catalog is passed to the CLI for validation instead of being rejected
 a bundled list. A model available in a desktop app may still be absent from the
 installed CLI's catalog or account access.
 
+Each provider keeps a warm native session. The first message to a provider sends the
+portable conversation once; after that only new messages are sent. Codex keeps one
+`app-server` process running and resumes its thread; Claude Code uses `--session-id`
+and `--resume`; Antigravity uses `--conversation`. When you come back to a provider after
+chatting with another one, it receives a short catch-up block containing only what it
+missed. The native session IDs are stored in the thwip session file next to the
+transcript, validated on load, shown by `/status`, and cleared by `/new`, `/clear`,
+`/compact`, and a project change. If a CLI can no longer continue a session, thwip says
+so and resends the full conversation to a fresh one.
+
 Native connections are read-only by default. Codex starts with a read-only sandbox
 and asks before operations outside it; approval requests appear in Thwip with the
 command or file list and default to denial. Claude Code and the Antigravity CLI run

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/docs/verification.md

@@ -1,7 +1,7 @@
 # Verification status
 
-Verified locally on 2026-09-24 for v1.6.2. The Python suite
-passes 265 offline tests on Python 3.11, 3.12, and 3.13. Exhaustive behavior across every provider and
+Verified locally on 2026-09-24 for v1.7.0. The Python suite
+passes 273 offline tests on Python 3.11, 3.12, and 3.13. Exhaustive behavior across every provider and
 configuration has not been established.
 
 ## Native CLI connections (2026-09-24)
@@ -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 |
+| Warm native sessions (v1.7.0) | Live: Claude Code recalled a code word on its second turn through `--resume`; Codex received the full transcript on first switch and answered from it; returning to Claude delivered a catch-up block; a second Codex turn reused the running app-server; `/status` showed each CLI session ID and synced count; `/new` cleared them; no leftover processes. Offline: resume, catch-up, and fallback paths for Codex, Claude Code, and Antigravity; session record validation and persistence |
+| Manual page (v1.7.0) | `thwip install-man` then `man -w thwip` and `man thwip` resolve from `~/.local/share/man` |
 | Terminal hygiene (v1.6.2) | Cursor-position queries disabled, keyboard echo off during turns, stray input flushed before each prompt; fixes `^[`/`^R` noise and phantom empty prompts seen in a real Ghostty session during a slow Antigravity reply. Permission prompt and chat re-verified live afterwards |
 | Ollama adapter (v1.6.1) | End to end against the fake Ollama routes: model list, streamed text with usage, tool call, HTTP 500 and unreachable server now raise clear errors instead of ending the turn silently |
 | Dependency audits (v1.6.1) | pip-audit reports no known vulnerabilities; npm audit reports zero |

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/pyproject.toml

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

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/tests/test_native_agents.py

@@ -1,6 +1,7 @@
 """Native protocol behavior without credentials or model requests."""
 
 import asyncio
+from types import SimpleNamespace
 
 import pytest
 
@@ -16,6 +17,8 @@ class FakeRPC:
         self.closed = False
         self.provider = provider
         self.failure = failure
+        self.process = SimpleNamespace(returncode=None)  # looks alive, like a running app-server
+        self.resume_fails = False
 
     async def request(self, method, params, **kwargs):
         self.requests.append((method, params))
@@ -28,6 +31,10 @@ class FakeRPC:
                     'availableModels': [{'modelId': 'future-model', 'name': 'Future'}]}}
         if method == 'thread/start':
             return {'thread': {'id': 't'}}
+        if method == 'thread/resume':
+            if self.resume_fails:
+                raise RuntimeError('Native CLI rejected thread/resume (code -32600): unknown thread')
+            return {'thread': {'id': params['threadId']}}
         if method == 'turn/start':
             await self.events.put({'id': 99, 'method': 'item/commandExecution/requestApproval',
                                    'params': {'command': 'touch example'}})
@@ -52,6 +59,7 @@ class FakeRPC:
 
     async def close(self):
         self.closed = True
+        self.process = SimpleNamespace(returncode=0)
 
 
 @pytest.mark.asyncio
@@ -88,9 +96,11 @@ async def test_native_permission_response_and_completion(provider, approve, monk
         if isinstance(event, NativePermission):
             event.approved = approve
     assert any(isinstance(event, TextDelta) and event.content == 'done' for event in events)
-    assert isinstance(events[-1], AgentDone)
+    assert isinstance(events[-1], AgentDone) and events[-1].native_session == {'id': 't'}
     response = rpc.sent[0]['result']
     assert response['decision'] == ('accept' if approve else 'decline')
+    assert not rpc.closed, 'the app-server stays alive between turns'
+    await agent.close()
     assert rpc.closed
 
 
@@ -150,6 +160,7 @@ async def test_codex_usage_limit_failure_becomes_limit_hit(monkeypatch):
     monkeypatch.setattr(agent, '_connect', connect)
     events = [event async for event in agent.chat([{'role': 'user', 'content': 'hi'}], model='future-model')]
     assert isinstance(events[-1], LimitHit) and events[-1].error_type == LimitStatus.QUOTA_EXHAUSTED
+    await agent.close()
     assert rpc.closed
 
 
@@ -198,3 +209,64 @@ async def test_codex_rate_limit_notification_is_recorded(monkeypatch):
     assert agent.limit_windows == [
         {'label': '5h', 'used_percent': 2, 'resets_at': 1790212672},
         {'label': '7d', 'used_percent': 23, 'resets_at': None}]
+
+
+def _turn_prompt(rpc):
+    return next(params for method, params in rpc.requests if method == 'turn/start')['input'][0]['text']
+
+
+@pytest.mark.asyncio
+async def test_codex_resumes_thread_and_sends_only_new_messages(monkeypatch):
+    agent = NativeAgent('openai', '.')
+    rpc = FakeRPC('openai')
+    async def connect():
+        return rpc
+    monkeypatch.setattr(agent, '_connect', connect)
+    history = [{'role': 'user', 'content': 'first'}, {'role': 'assistant', 'content': 'one'},
+               {'role': 'user', 'content': 'second'}]
+    events = [e async for e in agent.chat(history, model='future-model', resume={'id': 'thread-9', 'synced': 2})]
+    assert isinstance(events[-1], AgentDone) and events[-1].native_session == {'id': 'thread-9'}
+    methods = [m for m, _ in rpc.requests]
+    assert 'thread/resume' in methods and 'thread/start' not in methods
+    assert _turn_prompt(rpc) == 'second', 'only the new message is sent to a resumed thread'
+    # Same process, same thread: no second resume request.
+    rpc.requests.clear()
+    history += [{'role': 'assistant', 'content': 'two'}, {'role': 'user', 'content': 'third'}]
+    [e async for e in agent.chat(history, model='future-model', resume={'id': 'thread-9', 'synced': 4})]
+    assert 'thread/resume' not in [m for m, _ in rpc.requests] and _turn_prompt(rpc) == 'third'
+
+
+@pytest.mark.asyncio
+async def test_codex_catch_up_block_after_other_providers_answered(monkeypatch):
+    agent = NativeAgent('openai', '.')
+    rpc = FakeRPC('openai')
+    async def connect():
+        return rpc
+    monkeypatch.setattr(agent, '_connect', connect)
+    history = [{'role': 'user', 'content': 'a'}, {'role': 'assistant', 'content': 'b'},
+               {'role': 'user', 'content': 'c'}, {'role': 'assistant', 'content': 'd by claude'},
+               {'role': 'user', 'content': 'e'}]
+    [e async for e in agent.chat(history, model='future-model', resume={'id': 'thread-9', 'synced': 2})]
+    prompt = _turn_prompt(rpc)
+    assert 'Missed conversation' in prompt and 'd by claude' in prompt and prompt.endswith('Final user message:\ne')
+    assert '[User]\na' not in prompt, 'messages the thread already saw are not resent'
+
+
+@pytest.mark.asyncio
+async def test_codex_falls_back_to_new_thread_when_resume_fails(monkeypatch):
+    from thwip.agents.base import NativeActivity
+
+    agent = NativeAgent('openai', '.')
+    rpc = FakeRPC('openai')
+    rpc.resume_fails = True
+    async def connect():
+        return rpc
+    monkeypatch.setattr(agent, '_connect', connect)
+    history = [{'role': 'user', 'content': 'first'}, {'role': 'assistant', 'content': 'one'},
+               {'role': 'user', 'content': 'second'}]
+    events = [e async for e in agent.chat(history, model='future-model', resume={'id': 'gone', 'synced': 2})]
+    assert any(isinstance(e, NativeActivity) and 'unavailable' in e.description for e in events)
+    start = next(params for method, params in rpc.requests if method == 'thread/start')
+    assert start['ephemeral'] is False
+    assert '[User]\nfirst' in _turn_prompt(rpc), 'full transcript goes to the new thread'
+    assert events[-1].native_session == {'id': 't'}

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/tests/test_native_print.py

@@ -233,3 +233,53 @@ async def test_antigravity_network_reset_gets_a_network_hint(monkeypatch):
         "API error (attempt 1): request failed: Post \"https://example.googleapis.com\": read tcp 10.0.0.2:5->1.2.3.4:443: read: connection reset by peer"}}])
     with pytest.raises(RuntimeError, match="connection reset by peer.*network or a firewall"):
         await collect(agent, model="gemini-3.8-flash-high")
+
+
+@pytest.mark.asyncio
+async def test_claude_new_session_id_then_resume_flag(monkeypatch):
+    agent = PrintAgent("claude", ".")
+    calls = install_fake(monkeypatch, agent, [{"type": "system", "subtype": "init", "session_id": "abc-123"},
+                                              {"type": "result", "subtype": "success", "result": "hi", "usage": {}}])
+    events = await collect(agent)
+    assert events[-1].native_session == {"id": "abc-123"}
+    command, stdin_text = calls[0]
+    assert "--session-id" in command and "--resume" not in command and "--append-system-prompt" in command
+    assert stdin_text == "hello"
+    # Resume: only the new message, no system prompt re-sent, --resume flag used.
+    calls.clear()
+    history = [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "hi"}, {"role": "user", "content": "next"}]
+    events = [e async for e in agent.chat(history, model="fable", system_prompt="Be brief.", resume={"id": "abc-123", "synced": 2})]
+    command, stdin_text = calls[0]
+    assert command[command.index("--resume") + 1] == "abc-123" and "--append-system-prompt" not in command
+    assert stdin_text == "next" and events[-1].native_session == {"id": "abc-123"}
+
+
+@pytest.mark.asyncio
+async def test_antigravity_conversation_resume_and_fallback(monkeypatch):
+    agent = PrintAgent("google", ".")
+    ok = [{"event": "init", "conversation_id": "conv-1", "init": {}},
+          {"event": "result", "result": {"status": "SUCCESS", "response": "hi", "usage": {}}}]
+    calls = install_fake(monkeypatch, agent, ok)
+    events = await collect(agent, model="gemini-3.8-flash-high")
+    assert events[-1].native_session == {"id": "conv-1"} and "--conversation" not in calls[0][0]
+
+    # Resumed turn passes --conversation and only the new text.
+    calls.clear()
+    history = [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "hi"}, {"role": "user", "content": "next"}]
+    events = [e async for e in agent.chat(history, model="gemini-3.8-flash-high", resume={"id": "conv-1", "synced": 2})]
+    command = calls[0][0]
+    assert command[command.index("--conversation") + 1] == "conv-1" and command[command.index("--print") + 1] == "next"
+
+    # If the resumed process fails, a fresh conversation gets the full transcript.
+    attempts = []
+    async def start(command, stdin_text=None):
+        attempts.append(command)
+        if "--conversation" in command:
+            return FakeProcess([{"event": "result", "result": {"status": "ERROR", "error": "conversation not found"}}])
+        return FakeProcess(ok)
+    monkeypatch.setattr(agent, "_start_process", start)
+    events = [e async for e in agent.chat(history, model="gemini-3.8-flash-high", resume={"id": "conv-1", "synced": 2})]
+    assert len(attempts) == 2 and "--conversation" not in attempts[1]
+    assert "[User]\nhello" in attempts[1][attempts[1].index("--print") + 1]
+    assert any(isinstance(e, NativeActivity) and "unavailable" in e.description for e in events)
+    assert events[-1].native_session == {"id": "conv-1"}

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/tests/test_parity_commands.py

@@ -171,3 +171,30 @@ def test_mentions_attach_project_files_only(cli, tmp_path):
     assert "secret plan" in expanded and "[Attached file: notes.md]" in expanded
     assert "missing.txt]" not in expanded and "passwd]" not in expanded
     assert cli._expand_mentions("email me at user@example.com") == "email me at user@example.com"
+
+
+def test_incremental_prompt_builder():
+    from thwip.agents.native_common import build_incremental_prompt
+
+    history = [{"role": "user", "content": "a"}, {"role": "assistant", "content": "b"}, {"role": "user", "content": "c"}]
+    full, is_full = build_incremental_prompt(history, "sys", 0)
+    assert is_full and "[User]\na" in full and full.endswith("c")
+    only_new, is_full = build_incremental_prompt(history, "sys", 2)
+    assert (only_new, is_full) == ("c", False)
+    _bad, is_full = build_incremental_prompt(history, None, 7)
+    assert is_full, "a synced count beyond the history falls back to the full transcript"
+
+
+def test_man_page_commands(tmp_path, monkeypatch, capsys):
+    from thwip import cli as cli_module
+
+    monkeypatch.setenv("THWIP_MAN_DIR", str(tmp_path / "man1"))
+    assert cli_module.MAN_PAGE.is_file() and cli_module.MAN_PAGE.read_text().startswith(".TH THWIP 1")
+    assert cli_module.run_man_command("install-man") == 0
+    assert (tmp_path / "man1" / "thwip.1").read_text() == cli_module.MAN_PAGE.read_text()
+    monkeypatch.setattr("thwip.cli.shutil.which", lambda name: None)
+    assert cli_module.run_man_command("man") == 0
+    assert "universal coding agent multiplexer" in capsys.readouterr().out
+    with pytest.raises(SystemExit) as info:
+        cli_module.main(["install-man"])
+    assert info.value.code == 0

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/tests/test_session.py

@@ -128,3 +128,24 @@ def test_config_file_permissions_and_source_are_preserved(tmp_path, monkeypatch)
 
     assert loaded.key_sources["openai"] == "config.toml"
     assert get_config_path().stat().st_mode & 0o777 == 0o600
+
+
+def test_native_sessions_are_tracked_validated_and_persisted(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")
+    assert session.native_session("openai") is None
+    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"}
+    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"}
+    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"

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/__init__.py

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

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/agents/base.py

@@ -144,6 +144,8 @@ class AgentDone:
     usage: TokenUsage = field(default_factory=TokenUsage)
     stop_reason: str = "end_turn"
     native_state: dict[str, Any] = field(default_factory=dict)
+    # Identifier of the native CLI session that produced this turn, so it can be resumed next time.
+    native_session: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/agents/native_agent.py

@@ -22,7 +22,7 @@ from thwip.agents.base import (
     ThinkingDelta,
     TokenUsage,
 )
-from thwip.agents.native_common import build_native_prompt, classify_limit, scrub, window_label
+from thwip.agents.native_common import build_incremental_prompt, classify_limit, scrub, window_label
 from thwip.agents.native_rpc import NativeRPC
 
 
@@ -69,6 +69,9 @@ class NativeAgent(BaseAgent):
         self.discovery_error = "Not connected yet"
         # Usage windows the CLI reports for its own account; informational only.
         self.limit_windows: list[dict] = []
+        # One long-lived app-server process per Thwip run; threads are resumed across turns.
+        self._rpc = None
+        self._thread_id: str | None = None
 
     def is_installed(self):
         return shutil.which(self.binary) is not None
@@ -146,20 +149,60 @@ class NativeAgent(BaseAgent):
             if rpc:
                 await rpc.close()
 
-    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True):
-        rpc = await self._connect()
+    async def _live_rpc(self):
+        """Reuse the running app-server when it is still alive; otherwise start a new one."""
+        rpc = self._rpc
+        if rpc is not None and rpc.process is not None and rpc.process.returncode is None:
+            return rpc
+        self._rpc = None
+        self._thread_id = None
+        self._rpc = await self._connect()
+        return self._rpc
+
+    async def close(self):
+        """Stop the app-server process (on exit). Threads stay resumable on disk."""
+        rpc, self._rpc, self._thread_id = self._rpc, None, None
+        if rpc is not None:
+            await rpc.close()
+
+    async def _open_thread(self, rpc, model, system_prompt, resume_id):
+        """Resume the recorded Codex thread when possible; otherwise start a fresh persistent one.
+
+        Returns (thread_id, resumed).
+        """
+        common = {"cwd": self.project, "sandbox": "read-only", "approvalPolicy": "on-request",
+                  **({"developerInstructions": system_prompt} if system_prompt else {})}
+        if resume_id:
+            if self._thread_id == resume_id:
+                return resume_id, True
+            try:
+                await rpc.request("thread/resume", {"threadId": resume_id, "model": model, **common})
+                self._thread_id = resume_id
+                return resume_id, True
+            except (RuntimeError, TimeoutError, KeyError, TypeError):
+                pass
+        session = await rpc.request("thread/start", {"model": model, "ephemeral": False, **common})
+        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):
+        rpc = await self._live_rpc()
         event_task = None
+        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
         try:
-            # A fresh native session receives only portable text; tool state stays native within the turn.
-            prompt = build_native_prompt(messages, None)
-            # Codex App Server sandbox modes are kebab-case; camelCase is rejected as an invalid request.
-            session = await rpc.request("thread/start", {
-                "cwd": self.project, "model": model or self.get_default_model(), "sandbox": "read-only",
-                "approvalPolicy": "on-request", "ephemeral": True,
-                **({"developerInstructions": system_prompt} if system_prompt else {}),
-            })
-            thread_id = session["thread"]["id"]
-            await rpc.request("turn/start", {"threadId": thread_id, "input": [{"type": "text", "text": prompt}]})
+            thread_id, resumed = await self._open_thread(rpc, chosen, system_prompt, resume_id)
+            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)
+            # Drop notifications left over from an earlier turn on this process.
+            while not rpc.events.empty():
+                stale = rpc.events.get_nowait()
+                if stale.get("method") == "_closed":
+                    raise RuntimeError("Native CLI exited before the turn started.")
+            await rpc.request("turn/start", {"threadId": thread_id, "model": chosen,
+                                             "input": [{"type": "text", "text": prompt}]})
             usage = TokenUsage()
             started_items = {}
             text_items = set()
@@ -174,6 +217,7 @@ class NativeAgent(BaseAgent):
                 event = event_task.result()
                 method, params = event.get("method", ""), event.get("params", {})
                 if method == "_closed":
+                    self._rpc = None
                     raise RuntimeError("Native CLI exited before completing the response.")
                 if "id" in event:
                     if method in {"item/commandExecution/requestApproval", "item/fileChange/requestApproval"}:
@@ -190,7 +234,8 @@ class NativeAgent(BaseAgent):
                 elif method in {"item/reasoning/summaryTextDelta", "item/reasoning/textDelta"}:
                     yield ThinkingDelta(content=params.get("delta", ""))
                 elif method == "error":
-                    message = scrub(params.get("error", params).get("message", "") if isinstance(params.get("error", params), dict) else params)
+                    detail = params.get("error", params)
+                    message = scrub(detail.get("message", "") if isinstance(detail, dict) else detail)
                     limit = classify_limit(message)
                     if limit:
                         yield LimitHit(error_type=limit, message=message)
@@ -231,19 +276,13 @@ class NativeAgent(BaseAgent):
                         detail = f" Codex said: {message}" if message else ""
                         raise RuntimeError("Codex could not complete the turn. Check its login, model access, "
                                            f"or usage limit.{detail}")
-                    yield AgentDone(usage=usage)
+                    yield AgentDone(usage=usage, native_session={"id": thread_id})
                     return
-                elif method == "session/update":
-                    update = params.get("update", {})
-                    kind = update.get("sessionUpdate")
-                    if kind == "agent_message_chunk" and update.get("content", {}).get("type") == "text":
-                        yield TextDelta(content=update["content"].get("text", ""))
-                    elif kind in {"tool_call", "tool_call_update"}:
-                        yield NativeActivity(description=update.get("title", "Native tool activity"))
-        finally:
+        except BaseException:
+            # Any failure or interruption abandons the process; the thread itself remains resumable.
             if event_task and not event_task.done():
                 event_task.cancel()
-            if event_task:
                 with contextlib.suppress(asyncio.CancelledError, Exception):
                     await event_task
-            await rpc.close()
+            await self.close()
+            raise

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/agents/native_common.py

@@ -102,3 +102,28 @@ def network_hint(text: str) -> str:
         return (" The CLI could not reach its backend. This is usually the local network or a firewall "
                 "resetting the connection; try again, or switch to another network or a VPN.")
     return ""
+
+
+def build_incremental_prompt(messages: list[dict], system_prompt: str | None, synced: int) -> tuple[str, bool]:
+    """Return (prompt, is_full).
+
+    With no usable native session (synced == 0) the full transcript is sent. When the
+    native session already saw `synced` portable messages, only the messages after that
+    point are sent: just the new request, or a short catch-up block when other providers
+    answered in between.
+    """
+    portable = [m for m in messages if m.get("role") in {"user", "assistant"} and isinstance(m.get("content"), str)]
+    if synced <= 0 or synced >= len(portable):
+        return build_native_prompt(messages, system_prompt), True
+    missed = portable[synced:]
+    latest = missed[-1]
+    earlier = missed[:-1]
+    if not earlier:
+        return latest["content"].strip(), False
+    lines = [("While you were away, the conversation continued with another assistant. "
+             "Read it as context, then respond to the final user message."), "", "Missed conversation:"]
+    for message in earlier:
+        speaker = "User" if message["role"] == "user" else "Assistant"
+        lines += [f"[{speaker}]", message["content"].strip(), ""]
+    lines += ["Final user message:", latest["content"].strip()]
+    return "\n".join(lines), False

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/agents/native_print.py

@@ -13,6 +13,7 @@ import contextlib
 import json
 import os
 import shutil
+import uuid
 from pathlib import Path
 
 from thwip.agents.base import (
@@ -28,7 +29,7 @@ from thwip.agents.base import (
     ThinkingDelta,
     TokenUsage,
 )
-from thwip.agents.native_common import build_native_prompt, classify_limit, network_hint, scrub
+from thwip.agents.native_common import build_incremental_prompt, classify_limit, network_hint, scrub
 from thwip.tools.terminal import terminate_process_tree
 
 TURN_TIMEOUT = 600
@@ -181,27 +182,53 @@ class PrintAgent(BaseAgent):
 
     # --- Chat ---
 
-    def _turn_command(self, prompt: str, model: str, system_prompt: str | None) -> tuple[list[str], str | None]:
+    def _turn_command(self, prompt: str, model: str, system_prompt: str | None,
+                      resume_id: str | None, new_id: str | None) -> tuple[list[str], str | None]:
         if self.name == "claude":
             command = ["-p", "--output-format", "stream-json", "--verbose", "--include-partial-messages",
                        "--model", model, "--allowedTools", "Read,Glob,Grep,LS,WebFetch,WebSearch"]
-            if system_prompt:
+            command += ["--resume", resume_id] if resume_id else ["--session-id", new_id]
+            if system_prompt and not resume_id:
                 command += ["--append-system-prompt", system_prompt]
             return command, prompt
-        return ["--print", prompt, "--output-format", "stream-json", "--model", model,
-                "--print-timeout", f"{TURN_TIMEOUT}s"], None
+        command = ["--print", prompt, "--output-format", "stream-json", "--model", model,
+                   "--print-timeout", f"{TURN_TIMEOUT}s"]
+        if resume_id:
+            command += ["--conversation", resume_id]
+        return command, None
 
-    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True):
+    async def chat(self, messages, model=None, system_prompt=None, tools=None, stream=True, resume=None):
         chosen = model or self.get_default_model()
-        prompt = build_native_prompt(messages, None if self.name == "claude" else system_prompt)
-        command, stdin_text = self._turn_command(prompt, chosen, system_prompt)
+        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)
+            try:
+                async for event in self._turn(prompt, chosen, system_prompt, resume_id=resume_id, new_id=None):
+                    yield event
+                return
+            except RuntimeError as exc:
+                # The CLI could not continue that session (deleted, different machine, expired).
+                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)
+        async for event in self._turn(prompt, chosen, system_prompt, resume_id=None, new_id=str(uuid.uuid4())):
+            yield event
+
+    async def _turn(self, prompt, model, system_prompt, resume_id, new_id):
+        command, stdin_text = self._turn_command(prompt, model, system_prompt, resume_id, new_id)
         process = await self._start_process(command, stdin_text)
         usage = TokenUsage()
         streamed_text = False
         finished = False
+        session_id = resume_id or (new_id if self.name == "claude" else None)
         try:
             async for event in self._iterate(process):
                 kind = event.get("type") or event.get("event")
+                if kind == "system" and event.get("session_id"):
+                    session_id = event["session_id"]
+                elif kind == "init" and isinstance(event.get("init"), dict) or kind == "init":
+                    session_id = event.get("conversation_id") or session_id
                 if self.name == "claude":
                     result = self._claude_event(event, kind)
                 else:
@@ -214,7 +241,7 @@ class PrintAgent(BaseAgent):
                             yield TextDelta(content=item)
                     elif isinstance(item, AgentDone):
                         finished = True
-                        yield AgentDone(usage=usage)
+                        yield AgentDone(usage=usage, native_session={"id": session_id} if session_id else {})
                         return
                     else:
                         if isinstance(item, TextDelta):

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/cli.py

@@ -258,6 +258,14 @@ class ThwipCLI:
                 break
             except Exception as e:
                 print_error(f"Unexpected error: {e}")
+        await self._close_native_agents()
+
+    async def _close_native_agents(self) -> None:
+        for agent in self.registry.list_agents():
+            closer = getattr(agent, "close", None)
+            if callable(closer):
+                with contextlib.suppress(Exception):
+                    await closer()
 
     async def _ask_text(self, question: str) -> str:
         """Ask a one-line question without blocking the event loop.
@@ -1145,6 +1153,11 @@ class ThwipCLI:
         if getattr(self.current_agent, "native_tools", False):
             content.append("Connection:  Existing CLI sign-in; billing and tool accounting managed by native CLI\n", style="dim")
             content.append(f"Usage:       {describe_limit_windows(getattr(self.current_agent, 'limit_windows', []))}\n", style="dim")
+            record = self.session.native_session(self.current_agent.name)
+            if record:
+                content.append(f"CLI session: {record['id']} (has seen {record['synced']} messages; only new ones are sent)\n", style="dim")
+            else:
+                content.append("CLI session: none yet; the first message sends the full conversation\n", style="dim")
         content.append(f"Config Key:  {self.config.key_sources.get(self.current_agent.name, 'None')}\n", style="dim")
 
         console.print(Panel(content, title="Current Status", box=box.ROUNDED))
@@ -1231,10 +1244,11 @@ class ThwipCLI:
             p = Path(new_path).expanduser().resolve()
             if p.is_dir():
                 self.session.project_path = str(p)
+                self.session.native_sessions.clear()
                 self.tool_manager = ToolManager(str(p))
                 self.config.project = str(p)
                 self.config.save()
-                print_success(f"Project path changed to {p}")
+                print_success(f"Project path changed to {p}. Native CLI sessions will start fresh here.")
             else:
                 print_error(f"Directory '{new_path}' does not exist.")
         else:
@@ -1338,6 +1352,7 @@ class ThwipCLI:
         collected_text = ""
         total_tokens = 0
         limit_hit = False
+        native_session_id = ""
         if hasattr(self.current_agent, "get_handoff_models"):
             report = build_handoff_report(self.session, self.current_agent, self.current_agent,
                                           self.session.current_model, tools)
@@ -1356,13 +1371,12 @@ class ThwipCLI:
 
             with Live(console=console, refresh_per_second=12) as live:
                 try:
-                    response_stream = self.current_agent.chat(
-                        messages=working_messages,
-                        model=self.session.current_model,
-                        system_prompt=self.session.system_prompt,
-                        tools=tools,
-                        stream=self.config.stream if tools is None else False,
-                    )
+                    chat_kwargs = {"messages": working_messages, "model": self.session.current_model,
+                                   "system_prompt": self.session.system_prompt, "tools": tools,
+                                   "stream": self.config.stream if tools is None else False}
+                    if native:
+                        chat_kwargs["resume"] = self.session.native_session(self.current_agent.name)
+                    response_stream = self.current_agent.chat(**chat_kwargs)
                     # Close the adapter generator deterministically on interruption so child processes stop.
                     closer = contextlib.aclosing(response_stream) if hasattr(response_stream, "aclose") else contextlib.nullcontext(response_stream)
                     async with closer as response_stream:
@@ -1393,6 +1407,7 @@ class ThwipCLI:
                                 live.start()
                             elif isinstance(event, AgentDone):
                                 native_state = event.native_state
+                                native_session_id = str(event.native_session.get("id") or "") or native_session_id
                                 used = event.usage.input_tokens + event.usage.output_tokens
                                 total_tokens += used
                                 self.usage_tracker.record_usage(
@@ -1478,6 +1493,9 @@ class ThwipCLI:
                 company=self.current_agent.company,
                 tokens=total_tokens,
             )
+            if native and native_session_id:
+                # The native session now holds every portable message; next turn sends only what is new.
+                self.session.set_native_session(self.current_agent.name, native_session_id, self.session.current_model)
             if getattr(self.config, "auto_save", False):
                 if self.session.name == "new-session":
                     self.session.name = f"session-{self.session.id}"
@@ -1549,6 +1567,35 @@ class ThwipCLI:
                     break
 
 
+MAN_PAGE = Path(__file__).parent / "data" / "thwip.1"
+
+
+def run_man_command(command: str) -> int:
+    """Show or install the bundled manual page. pip cannot install man pages, so thwip does it on request."""
+    import subprocess
+
+    if not MAN_PAGE.is_file():
+        print("The manual page is missing from this installation.", file=sys.stderr)
+        return 1
+    if command == "man":
+        if shutil.which("man"):
+            return subprocess.call(["man", "-l", str(MAN_PAGE)])
+        print(MAN_PAGE.read_text(encoding="utf-8"))
+        return 0
+    target_dir = Path(os.environ.get("THWIP_MAN_DIR") or Path.home() / ".local" / "share" / "man" / "man1")
+    try:
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target = target_dir / "thwip.1"
+        target.write_text(MAN_PAGE.read_text(encoding="utf-8"), encoding="utf-8")
+    except OSError as exc:
+        print(f"Could not install the manual page: {exc}", file=sys.stderr)
+        return 1
+    print(f"Installed {target}")
+    print("Run `man thwip`. If it is not found, add this to your shell profile:")
+    print(f'  export MANPATH="{target_dir.parent}:$MANPATH"')
+    return 0
+
+
 def main(argv: list[str] | None = None) -> None:
     """Entry point for the thwip CLI command."""
     import argparse
@@ -1562,7 +1609,11 @@ def main(argv: list[str] | None = None) -> None:
     parser.add_argument("--version", action="version", version=f"thwip {__version__}")
     parser.add_argument("-p", "--project", metavar="PATH",
                         help="Project directory for this session (defaults to the saved project or the current directory).")
+    parser.add_argument("command", nargs="?", choices=["man", "install-man"],
+                        help="'man' shows the manual page; 'install-man' installs it so that `man thwip` works.")
     args = parser.parse_args(argv)
+    if args.command:
+        raise SystemExit(run_man_command(args.command))
     project = None
     if args.project:
         candidate = Path(args.project).expanduser()

thwip_cli-1.7.0/thwip/data/thwip.1

@@ -0,0 +1,122 @@
+.TH THWIP 1 "September 2026" "thwip" "User Commands"
+.SH NAME
+thwip \- universal coding agent multiplexer for the terminal
+.SH SYNOPSIS
+.B thwip
+.RI [ \-\-project " PATH" ]
+.br
+.B thwip man
+.br
+.B thwip install-man
+.br
+.B thwip \-\-version
+.SH DESCRIPTION
+.B thwip
+finds the AI coding agents already installed and signed in on this machine
+(Codex, Claude Code, and the Antigravity CLI), connects to each through its own
+supported protocol, and lets you chat with any of them from one REPL. You can
+switch provider or model mid-conversation, keep the text history, and fail over
+to another provider when one reports an exhausted usage limit. Direct API keys
+for Anthropic, Google, OpenAI, DeepSeek, Groq, OpenRouter, and a local Ollama
+server are also supported.
+.PP
+No credential is copied. Installed CLIs hold their own login, enforce their own
+sandbox and approvals, and bill their own plan. Native connections are read-only
+by default; Codex asks before operations outside its sandbox.
+.SH OPTIONS
+.TP
+.BI \-p ", " \-\-project " PATH"
+Open the REPL for the given project directory instead of the saved or current one.
+.TP
+.B \-\-version
+Print the version and exit.
+.TP
+.B \-h ", " \-\-help
+Print usage and exit.
+.SH SUBCOMMANDS
+.TP
+.B man
+Show this manual page.
+.TP
+.B install-man
+Copy this manual page to
+.I ~/.local/share/man/man1
+so that
+.B man thwip
+works.
+.SH REPL COMMANDS
+.TP
+.B /switch [agent] [model]
+Switch provider (and optionally model). A handoff preview is shown first. Alias:
+.BR /sw ", " /s .
+.TP
+.B /model [id]
+Pick a model for the current provider from a numbered list or by ID.
+.TP
+.B /handoff [agent] [model]
+Preview what transfers, what is lost, and the context fit without switching.
+.TP
+.B /agents ", " /models [agent|tier] ", " /detect
+List detected agents, list models (live from the CLI or provider), rescan.
+.TP
+.B /compact
+Ask the current model for a plain-text summary and replace the history with it.
+.TP
+.B /new ", " /resume [name] ", " /session save|load|list|clear [name]
+Start a fresh conversation, resume a saved one, or manage saved sessions.
+.TP
+.B /diff [staged] ", " /copy ", " /export [path]
+Show the project git diff, copy the last response, export the conversation as
+Markdown with model attribution.
+.TP
+.B /limits ", " /usage ", " /cost ", " /status ", " /history
+Usage windows reported by each CLI account, API cost estimates, session status,
+and the conversation with model badges.
+.TP
+.B /key [provider]
+Enter a direct API key with hidden input.
+.TP
+.B /native codex
+Save the session and replace thwip with the Codex CLI itself.
+.TP
+.B !command
+Run a shell command in the project without involving a model.
+.TP
+.B @path
+Attach a project file's content to your message.
+.TP
+.B /help ", " /about ", " /quit
+.SH KEYS
+.TP
+.B Ctrl+S
+Open the switcher.
+.TP
+.B Ctrl+T
+Show status.
+.TP
+.B Ctrl+C
+Interrupt the current response, command, or prompt. At the main prompt, exit.
+.SH ENVIRONMENT
+.TP
+.B THWIP_CONFIG_DIR
+Configuration directory (default
+.IR ~/.thwip ).
+.TP
+.B THWIP_OPENAI_BASE_URL ", " THWIP_ANTHROPIC_BASE_URL ", " THWIP_GOOGLE_BASE_URL ", " THWIP_DEEPSEEK_BASE_URL ", " THWIP_GROQ_BASE_URL ", " THWIP_OPENROUTER_BASE_URL
+Point a direct adapter at a proxy, gateway, or OpenAI-compatible server.
+.TP
+.B ANTHROPIC_API_KEY ", " GEMINI_API_KEY ", " OPENAI_API_KEY ", " DEEPSEEK_API_KEY ", " GROQ_API_KEY ", " OPENROUTER_API_KEY
+Direct API keys. A key takes precedence over the native CLI connection for that provider.
+.SH FILES
+.TP
+.I ~/.thwip/config.toml
+Defaults, keys entered with /key, endpoint overrides, fallback chain, display settings.
+.TP
+.I ~/.thwip/sessions/
+Saved sessions, including the native CLI session IDs used to resume each provider.
+.SH SEE ALSO
+.BR codex (1),
+.BR claude (1),
+.BR agy (1)
+.PP
+https://github.com/tanmayhutt/thwip-cli

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/thwip/session.py

@@ -66,14 +66,37 @@ class Session:
     messages: list[Message] = field(default_factory=list)
     observed_tool_results: int = 0
     tool_tracking_complete: bool = True
+    # Per-provider native CLI sessions: {"openai": {"id": "...", "synced": 4, "model": "..."}}.
+    # `synced` is how many portable messages that native session has already seen, so a provider
+    # you return to receives only what it missed. Cleared whenever the text history is replaced.
+    native_sessions: dict[str, dict[str, Any]] = field(default_factory=dict)
 
     def clear_context(self) -> None:
-        """Clear text and its associated handoff accounting together."""
+        """Clear text, handoff accounting, and native session bookkeeping together."""
         self.messages.clear()
         self.observed_tool_results = 0
         self.tool_tracking_complete = True
+        self.native_sessions.clear()
         self.updated_at = time.time()
 
+    def native_session(self, provider: str) -> dict[str, Any] | None:
+        """Return a consistent native session record for the provider, or None."""
+        record = self.native_sessions.get(provider)
+        if not isinstance(record, dict) or not isinstance(record.get("id"), str) or not record["id"]:
+            return None
+        synced = record.get("synced", 0)
+        if type(synced) is not int or synced < 0 or synced > len(self.to_portable_messages()):
+            return None
+        return record
+
+    def set_native_session(self, provider: str, session_id: str, model: str = "") -> None:
+        """Record that the provider's native session has seen every portable message so far."""
+        self.native_sessions[provider] = {"id": session_id, "synced": len(self.to_portable_messages()), "model": model}
+        self.updated_at = time.time()
+
+    def forget_native_session(self, provider: str) -> None:
+        self.native_sessions.pop(provider, None)
+
     def record_tool_result(self) -> None:
         """Count transient results without persisting potentially sensitive outputs."""
         self.observed_tool_results += 1
@@ -145,6 +168,7 @@ class Session:
             "messages": [m.to_dict() for m in self.messages],
             "observed_tool_results": self.observed_tool_results,
             "tool_tracking_complete": self.tool_tracking_complete,
+            "native_sessions": self.native_sessions,
         }
         temporary_path: Path | None = None
         try:
@@ -214,6 +238,16 @@ class Session:
                     return None
                 if any(not isinstance(raw.get(key, ""), str) for key in ("agent_name", "model", "company")):
                     return None
+            native_sessions = data.get("native_sessions", {})
+            if not isinstance(native_sessions, dict):
+                return None
+            for provider, record in native_sessions.items():
+                if not isinstance(provider, str) or not isinstance(record, dict):
+                    return None
+                if not isinstance(record.get("id"), str) or type(record.get("synced", 0)) is not int or record.get("synced", 0) < 0:
+                    return None
+                if not isinstance(record.get("model", ""), str):
+                    return None
             session = cls(
                 id=data.get("id", ""),
                 name=data.get("name", "saved-session"),
@@ -226,6 +260,8 @@ class Session:
                 messages=[Message.from_dict(m) for m in data.get("messages", [])],
                 observed_tool_results=data.get("observed_tool_results", 0),
                 tool_tracking_complete=data.get("tool_tracking_complete", False),
+                native_sessions={k: {"id": v["id"], "synced": v.get("synced", 0), "model": v.get("model", "")}
+                                 for k, v in native_sessions.items()},
             )
             return session
         except Exception:

{thwip_cli-1.6.2 → thwip_cli-1.7.0}/uv.lock

@@ -1022,7 +1022,7 @@ wheels = [
 
 [[package]]
 name = "thwip-cli"
-version = "1.6.2"
+version = "1.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },