premanmcp 1.1.13 → 1.1.15

package/bin/tool_proxy.py

@@ -0,0 +1,828 @@
+"""PreMan's recording proxy for agents run as another process (Node, Go, Rust, any CLI).
+
+The wrapper points the agent's OPENAI_BASE_URL / ANTHROPIC_BASE_URL here. Every
+request and reply is forwarded unchanged to the address the agent would have
+used; a copy is read for tool calls. A call is recorded only when both halves
+were seen: the model asking for it, and its result going back to the model.
+
+Shipped with the CLI and imported by generated wrappers (design spec §6.0).
+Standard library only: the interpreter running those wrappers has no
+guaranteed openai or anthropic package.
+"""
+from __future__ import annotations
+
+import gzip
+import http.client
+import http.server
+import json
+import os
+import secrets
+import threading
+import urllib.error
+import urllib.request
+import zlib
+from pathlib import Path
+
+MAX_BODY = 2 * 1024 * 1024
+
+
+def kind_of(provider: str, path: str) -> str:
+    """Which model API a request path is, or "" for one that carries no turn
+    (model lists, embeddings, token counting)."""
+    tail = path.split("?", 1)[0].rstrip("/")
+    if provider == "openai":
+        if tail.endswith("/chat/completions"):
+            return "openai_chat"
+        if tail.endswith("/responses"):
+            return "openai_responses"
+    if provider == "anthropic" and tail.endswith("/messages"):
+        return "anthropic"
+    return ""
+
+
+def _args(raw):
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str):
+        try:
+            value = json.loads(raw) if raw.strip() else {}
+        except ValueError:
+            return {"raw": raw}
+        return value if isinstance(value, dict) else {"raw": value}
+    return {}
+
+
+def _text(content) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [
+            block["text"] if isinstance(block, dict) else block
+            for block in content
+            if (isinstance(block, dict) and isinstance(block.get("text"), str)) or isinstance(block, str)
+        ]
+        if parts:
+            return "".join(parts)
+    return json.dumps(content, ensure_ascii=False, default=str)
+
+
+class _Unreadable(Exception):
+    pass
+
+
+_NO_ID = "a tool call or tool result carried no id, so PreMan cannot pair them"
+_NO_TRAFFIC = (
+    "no model request reached PreMan; the agent may set its model address in code "
+    "instead of reading OPENAI_BASE_URL or ANTHROPIC_BASE_URL"
+)
+_CHANNEL_CLOSED = "the turn's proxy channel was closed before the turn ended"
+# The only outcomes where the proxy saw nothing of the turn, so the agent's own
+# report is the better account. Any other "not visible" is something the proxy
+# saw and could not trust, and a report cannot undo that.
+_NO_TOOLS_OFFERED = (
+    "the agent offered the model no tools in its requests, so PreMan cannot tell whether it ran any "
+    "(for example, tools named in plain text)"
+)
+_UNSEEN = (_NO_TRAFFIC, _CHANNEL_CLOSED, _NO_TOOLS_OFFERED)
+
+
+def _call(out, cid, name, args):
+    # A call with no id cannot be paired with its result, so it may run unseen.
+    # One with no function name (a custom tool) is kept with name None: in a
+    # reply it makes the turn not visible; in history it is skipped, so its
+    # result has no readable request and the orphan rule decides.
+    if not cid:
+        raise _Unreadable(_NO_ID)
+    out.append((cid, name or None, _args(args)))
+
+
+def _requests_in_reply(kind, reply):
+    """(id, name, args) for each tool the model asked for in one reply."""
+    out = []
+    if kind == "openai_chat":
+        for choice in reply.get("choices") or []:
+            message = (choice or {}).get("message") or {}
+            for call in message.get("tool_calls") or []:
+                fn = (call or {}).get("function") or {}
+                _call(out, (call or {}).get("id"), fn.get("name"), fn.get("arguments"))
+    elif kind == "openai_responses":
+        for item in reply.get("output") or []:
+            if isinstance(item, dict) and item.get("type") == "function_call":
+                _call(out, item.get("call_id"), item.get("name"), item.get("arguments"))
+    elif kind == "anthropic":
+        for block in reply.get("content") or []:
+            if isinstance(block, dict) and block.get("type") == "tool_use":
+                _call(out, block.get("id"), block.get("name"), block.get("input"))
+    return out
+
+
+# Tool types PreMan cannot record: local ones whose shape it does not read, and
+# ones the provider runs itself, so no result ever passes through the agent.
+_UNREAD_TYPES = {
+    "openai_responses": {"computer_call", "local_shell_call", "shell_call", "apply_patch_call", "custom_tool_call"},
+}
+_HOSTED_TYPES = {
+    "openai_responses": {"web_search_call", "file_search_call", "mcp_call", "code_interpreter_call", "image_generation_call"},
+    "anthropic": {"server_tool_use", "mcp_tool_use", "web_search_tool_result"},
+}
+
+
+def _unrecorded(kind, items):
+    """(key, reason) for each item that is a tool PreMan cannot record. The key
+    is the item's id, or "" when it has none."""
+    out = []
+    for item in items if isinstance(items, list) else []:
+        kind_of_item = item.get("type") if isinstance(item, dict) else None
+        if not isinstance(kind_of_item, str):
+            continue
+        key = str(item.get("call_id") or item.get("id") or item.get("tool_use_id") or "")
+        if kind_of_item in _UNREAD_TYPES.get(kind, ()):
+            out.append((key, "the agent ran a tool type PreMan cannot read (%s)" % kind_of_item))
+        elif kind_of_item in _HOSTED_TYPES.get(kind, ()) or (
+            kind == "anthropic" and kind_of_item.endswith("_tool_result") and kind_of_item != "tool_result"
+        ):
+            out.append((key, "the model used a tool that runs on the provider's side (%s), which PreMan does not record" % kind_of_item))
+    return out
+
+
+def _unrecorded_in_history(kind, request):
+    if kind == "openai_responses":
+        return _unrecorded(kind, request.get("input"))
+    if kind == "anthropic":
+        out = []
+        for message in request.get("messages") or []:
+            if isinstance(message, dict):
+                out += _unrecorded(kind, message.get("content"))
+        return out
+    return []
+
+
+def _unrecorded_in_reply(kind, reply):
+    if kind == "openai_responses":
+        return _unrecorded(kind, reply.get("output"))
+    if kind == "anthropic":
+        return _unrecorded(kind, reply.get("content"))
+    return []
+
+
+def _requests_in_history(kind, request):
+    """(id, name, args) for each tool request the agent re-sent as history."""
+    out = []
+    if kind == "openai_chat":
+        for message in request.get("messages") or []:
+            if isinstance(message, dict) and message.get("role") == "assistant":
+                out += _requests_in_reply("openai_chat", {"choices": [{"message": message}]})
+    elif kind == "openai_responses":
+        items = request.get("input")
+        out += _requests_in_reply("openai_responses", {"output": items if isinstance(items, list) else []})
+    elif kind == "anthropic":
+        for message in request.get("messages") or []:
+            if isinstance(message, dict) and message.get("role") == "assistant" and isinstance(message.get("content"), list):
+                out += _requests_in_reply("anthropic", {"content": message["content"]})
+    return out
+
+
+def _results_in_request(kind, request):
+    """(id, content) for each tool result the agent sent back to the model."""
+    out = []
+    if kind == "openai_chat":
+        for idx, message in enumerate(request.get("messages") or []):
+            if isinstance(message, dict):
+                if message.get("role") == "tool":
+                    if not message.get("tool_call_id"):
+                        raise _Unreadable(_NO_ID)
+                    out.append((message["tool_call_id"], _text(message.get("content"))))
+                elif message.get("role") == "function":
+                    name = message.get("name", "function")
+                    out.append(("function:%s:%d" % (name, idx), _text(message.get("content"))))
+    elif kind == "openai_responses":
+        items = request.get("input")
+        for idx, item in enumerate(items if isinstance(items, list) else []):
+            if not isinstance(item, dict) or not isinstance(item.get("type"), str):
+                continue
+            if item["type"] == "function_call_output":
+                if not item.get("call_id"):
+                    raise _Unreadable(_NO_ID)
+                out.append((item["call_id"], _text(item.get("output"))))
+            elif item["type"].endswith("_call_output"):
+                # The result of a tool type PreMan cannot read (custom, shell,
+                # computer...). Keyed so it never pairs with a request: it is an
+                # orphan, and the orphan rule makes the turn not visible.
+                key = item.get("call_id") or item.get("id") or "%s:%d" % (item["type"], idx)
+                out.append(("unreadable:%s" % key, _text(item.get("output"))))
+    elif kind == "anthropic":
+        for message in request.get("messages") or []:
+            content = message.get("content") if isinstance(message, dict) else None
+            for block in content if isinstance(content, list) else []:
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    if not block.get("tool_use_id"):
+                        raise _Unreadable(_NO_ID)
+                    out.append((block["tool_use_id"], _text(block.get("content"))))
+    return out
+
+
+def _sse(raw: bytes):
+    """The JSON payloads of a server-sent-events body, in order."""
+    for block in raw.decode("utf-8", "replace").replace("\r\n", "\n").split("\n\n"):
+        data = "\n".join(line[5:].lstrip() for line in block.split("\n") if line.startswith("data:"))
+        if not data or data == "[DONE]":
+            continue
+        try:
+            yield json.loads(data)
+        except ValueError:
+            raise _Unreadable("a streamed reply held a chunk that is not JSON")
+
+
+def _requests_in_stream(kind, raw: bytes):
+    if kind == "openai_chat":
+        slots = {}
+        for event in _sse(raw):
+            for choice in event.get("choices") or []:
+                delta = (choice or {}).get("delta") or {}
+                for part in delta.get("tool_calls") or []:
+                    slot = slots.setdefault((choice.get("index", 0), part.get("index", 0)), {"id": "", "name": "", "arguments": ""})
+                    if part.get("id"):
+                        slot["id"] = part["id"]
+                    fn = part.get("function") or {}
+                    slot["name"] += fn.get("name") or ""
+                    slot["arguments"] += fn.get("arguments") or ""
+        out = []
+        for s in slots.values():
+            _call(out, s["id"], s["name"], s["arguments"])
+        return out
+    if kind == "openai_responses":
+        done = []
+        for event in _sse(raw):
+            if event.get("type") == "response.completed" and isinstance(event.get("response"), dict):
+                return _requests_in_reply(kind, event["response"])
+            if event.get("type") == "response.output_item.done" and isinstance(event.get("item"), dict):
+                done.append(event["item"])
+        return _requests_in_reply(kind, {"output": done})
+    if kind == "anthropic":
+        slots = {}
+        for event in _sse(raw):
+            if event.get("type") == "content_block_start":
+                block = event.get("content_block") or {}
+                if block.get("type") == "tool_use":
+                    slots[event.get("index")] = {"id": block.get("id"), "name": block.get("name"), "input": block.get("input"), "json": ""}
+            elif event.get("type") == "content_block_delta":
+                delta = event.get("delta") or {}
+                if delta.get("type") == "input_json_delta" and event.get("index") in slots:
+                    slots[event["index"]]["json"] += delta.get("partial_json") or ""
+        out = []
+        for s in slots.values():
+            _call(out, s["id"], s["name"], s["json"] if s["json"] else s["input"])
+        return out
+    return []
+
+
+def _unrecorded_in_stream(kind, raw: bytes):
+    items = []
+    for event in _sse(raw):
+        if kind == "openai_responses":
+            if event.get("type") == "response.completed" and isinstance(event.get("response"), dict):
+                items += event["response"].get("output") or []
+            elif event.get("type") in ("response.output_item.added", "response.output_item.done"):
+                items.append(event.get("item"))
+        elif kind == "anthropic" and event.get("type") == "content_block_start":
+            items.append(event.get("content_block"))
+    return _unrecorded(kind, items)
+
+
+def _decoded(body: bytes, encoding: str) -> bytes:
+    encoding = (encoding or "").strip().lower()
+    if encoding in ("", "identity"):
+        return body
+    if encoding == "gzip":
+        return gzip.decompress(body)
+    if encoding == "deflate":
+        return zlib.decompress(body)
+    raise _Unreadable("a model reply was compressed with %s" % encoding)
+
+
+def _not_visible(reason):
+    return {"state": "not_visible", "source": "proxy", "watched": [], "missing": [], "reason": reason}
+
+
+class _Turn:
+    """What one turn's model traffic showed. One per turn, discarded after it."""
+
+    def __init__(self, already=None, waiting=None):
+        self.requested = {}  # id -> (name, args), history overrides
+        self.order = []      # ids in the order they were first seen
+        self.results = {}    # id -> content
+        self.asked = []      # ids the model asked for in a reply during this turn
+        self.model_requests = 0
+        self.problem = ""
+        self.reused_id = False  # a reply asked for an id an earlier turn already reported
+        self.reused_in_turn = False  # a reply asked for an id already seen in this turn
+        self.offered_tools = False  # some model request in the turn offered the model tools
+        self.last_reply_failed = False  # the most recent model reply was an HTTP error
+        self.unrecorded = []  # keys of tool items PreMan cannot record, filed as reported at the end
+        self.already = already if already is not None else set()
+        # Ids asked for in an earlier turn of this channel whose result never
+        # went back, with their (name, args): a result for one arriving now
+        # counts in this turn, even when the agent does not re-send the call.
+        self.waiting = waiting if waiting is not None else {}
+        # The trace (design spec §7.5): each model reply that asks for a named
+        # call is one step; each call belongs to a conversation -- None for the
+        # top level, else the call a sub-agent ran inside.
+        self.step = 0
+        self.step_of = {}
+        self.conv_of = {}
+        self.parent_unknown = ""
+        self._counted = []
+        self._lock = threading.RLock()  # the proxy serves one turn from several threads
+
+    def _note(self, cid, name, args, override=False):
+        if cid not in self.requested:
+            self.requested[cid] = (name, args)
+            self.order.append(cid)
+        elif override:
+            self.requested[cid] = (name, args)
+
+    def _fail(self, reason):
+        with self._lock:
+            self.problem = self.problem or reason
+
+    def saw_request(self, kind, body):
+        with self._lock:
+            return self._saw_request(kind, body)
+
+    def saw_reply(self, kind, status, content_type, content_encoding, body, truncated, conv=None):
+        with self._lock:
+            return self._saw_reply(kind, status, content_type, content_encoding, body, truncated, conv)
+
+    def outcome(self):
+        with self._lock:
+            events, capture = self._outcome()
+            capture["trace"] = self._trace(self._counted)
+            return events, capture
+
+    def _conversation(self, referenced):
+        """Which conversation a model request belongs to. One that re-sends or
+        answers a call continues that call's conversation; one that references
+        none, made while exactly one call is waiting, is a sub-agent running
+        inside that call. Anything less certain leaves parent unknown."""
+        seen = {self.conv_of[c] for c in referenced if c in self.conv_of}
+        if len(seen) == 1:
+            return seen.pop()
+        if len(seen) > 1:
+            self.parent_unknown = self.parent_unknown or "a model request mixed calls from two conversations"
+            return None
+        waiting = [c for c in self.asked if c not in self.results]
+        if len(waiting) > 1:
+            self.parent_unknown = self.parent_unknown or (
+                "a model request began while several tool calls were waiting, "
+                "so which one it ran inside is unclear"
+            )
+            return None
+        return waiting[0] if waiting else None
+
+    def _trace(self, counted):
+        """step and parent for the calls this turn counted, numbered in the order asked."""
+        at = {cid: i for i, cid in enumerate(counted)}
+        unknown = {}
+        if any(cid not in self.asked for cid in counted):
+            unknown["step"] = unknown["parent"] = "a call asked for in an earlier turn finished in this one"
+        if self.parent_unknown:
+            unknown.setdefault("parent", self.parent_unknown)
+        if any(self.conv_of.get(c) is not None and self.conv_of[c] not in at for c in counted):
+            unknown.setdefault("parent", "a call ran inside a tool call that was not counted")
+        steps = {}
+        calls = []
+        for i, cid in enumerate(counted):
+            call = {"id": "c%d" % (i + 1), "tool": self.requested[cid][0], "event": i}
+            if "step" not in unknown:
+                call["step"] = steps.setdefault(self.step_of.get(cid), len(steps) + 1)
+            if "parent" not in unknown:
+                parent = self.conv_of.get(cid)
+                call["parent"] = None if parent is None else "c%d" % (at[parent] + 1)
+            calls.append(call)
+        return {
+            "links": "full",
+            "known": [f for f in ("step", "parent") if f not in unknown],
+            "unknown": unknown,
+            "calls": calls,
+        }
+
+    def _saw_request(self, kind, body):
+        self.model_requests += 1
+        if len(body) > MAX_BODY:
+            return self._fail("a model request was larger than 2 MB, so it was forwarded without being read")
+        try:
+            request = json.loads(body or b"{}")
+        except ValueError:
+            return self._fail("a model request was not JSON")
+        if not isinstance(request, dict):
+            return self._fail("a model request was not a JSON object")
+        if request.get("tools") or request.get("functions"):
+            self.offered_tools = True
+        try:
+            history = _requests_in_history(kind, request)
+            results = _results_in_request(kind, request)
+            unrecorded = _unrecorded_in_history(kind, request)
+        except _Unreadable as exc:
+            return self._fail(str(exc))
+        self._saw_unrecorded(unrecorded)
+        for cid, name, args in history:
+            if name is None:
+                continue  # its result has no readable request: the orphan rule decides
+            self._note(cid, name, args, override=True)
+        ids = [cid for cid, _ in results]
+        if len(ids) != len(set(ids)):
+            return self._fail("two tool results shared one id, so they cannot be told apart")
+        for cid, content in results:
+            if cid in self.waiting and cid not in self.requested:
+                self._note(cid, *self.waiting[cid])
+            self.results.setdefault(cid, content)
+        return self._conversation([cid for cid, _, _ in history] + ids)
+
+    def _saw_unrecorded(self, items):
+        for key, reason in items:
+            # Re-sent history from an earlier turn was already filed there.
+            if key and "item:" + key in self.already:
+                continue
+            if key:
+                self.unrecorded.append("item:" + key)
+            self._fail(reason)
+
+    def _saw_reply(self, kind, status, content_type, content_encoding, body, truncated, conv=None):
+        if status >= 400:
+            self.last_reply_failed = True  # asks for no tool; cleared if a retry succeeds
+            return
+        self.last_reply_failed = False
+        if truncated:
+            return self._fail("a model reply was larger than 2 MB, so it was forwarded without being read")
+        try:
+            raw = _decoded(body, content_encoding)
+            if "text/event-stream" in (content_type or ""):
+                calls = _requests_in_stream(kind, raw)
+                unrecorded = _unrecorded_in_stream(kind, raw)
+            else:
+                reply = json.loads(raw or b"{}")
+                calls = _requests_in_reply(kind, reply) if isinstance(reply, dict) else []
+                unrecorded = _unrecorded_in_reply(kind, reply) if isinstance(reply, dict) else []
+        except _Unreadable as exc:
+            return self._fail(str(exc))
+        except (ValueError, OSError, zlib.error):
+            return self._fail("a model reply could not be read")
+        self._saw_unrecorded(unrecorded)
+        if any(name for _, name, _ in calls):
+            self.step += 1
+        for cid, name, args in calls:
+            if name is None:
+                self._fail("the model asked for a tool call with no tool name, which PreMan cannot read")
+                continue
+            # A reply never re-sends history, so an id seen before is a new call
+            # sharing an old id: its result could pair with the wrong call.
+            # Compared with earlier replies only, not with history: the agent can
+            # re-send this very reply as history before the proxy finishes
+            # reading the stream, so history may already hold it.
+            if cid in self.already:
+                self.reused_id = True
+            elif cid in self.asked:
+                self.reused_in_turn = True
+            self._note(cid, name, args)
+            self.asked.append(cid)
+            self.step_of.setdefault(cid, self.step)
+            self.conv_of.setdefault(cid, conv)
+
+    def _outcome(self):
+        # Compute events, orphans, and unanswered first
+        events = []
+        # Only ids the model asked for in a reply this turn: a call and result
+        # the agent wrote into its first request (examples) never ran.
+        for cid in self.order:
+            if cid in self.results and (cid in self.asked or cid in self.waiting) and cid not in self.already:
+                name, args = self.requested[cid]
+                events.append({"role": "tool_result", "tool_name": name, "tool_args": args, "content": self.results[cid]})
+        orphan_results = [cid for cid in self.results if cid not in self.requested and cid not in self.already]
+        unanswered = [self.requested[cid][0] for cid in self.asked if cid not in self.results and cid not in self.already]
+
+        # Update already with event ids and orphan ids (NOT unanswered)
+        event_cids = [
+            cid for cid in self.order
+            if cid in self.results and (cid in self.asked or cid in self.waiting) and cid not in self.already
+        ]
+        self._counted = list(event_cids)
+        self.waiting.update({cid: self.requested[cid] for cid in self.asked if cid not in self.results})
+        for cid in event_cids:
+            self.waiting.pop(cid, None)
+        self.already.update(event_cids)
+        self.already.update(orphan_results)
+        self.already.update(self.unrecorded)
+
+        # Choose the capture based on problems/conditions
+        if self.problem:
+            return events, _not_visible(self.problem)
+        if self.reused_id:
+            return events, _not_visible(
+                "the model reused a tool-call id from an earlier turn, "
+                "so this turn's calls cannot be told apart from earlier ones"
+            )
+        if self.reused_in_turn:
+            return events, _not_visible(
+                "the model asked for two tool calls with the same id in this turn, "
+                "so their results cannot be told apart"
+            )
+        if orphan_results:
+            return events, _not_visible("a tool result went back to the model for a call PreMan could not read")
+        if not self.model_requests:
+            return events, _not_visible(_NO_TRAFFIC)
+        if self.last_reply_failed:
+            return events, _not_visible(
+                "the model's last reply in this turn was an HTTP error, so the agent may have answered "
+                "without the tools it meant to call"
+            )
+        if unanswered:
+            return events, _not_visible(
+                "the model asked for %s, and the result never went back to the model, so whether it ran is unknown"
+                % ", ".join(sorted(set(unanswered)))
+            )
+        if not events and not self.offered_tools:
+            return events, _not_visible(_NO_TOOLS_OFFERED)
+        return events, {"state": "recorded", "source": "proxy", "watched": [], "missing": [], "reason": ""}
+
+
+DEFAULT_UPSTREAM = {"openai": "https://api.openai.com/v1", "anthropic": "https://api.anthropic.com"}
+ENV_VAR = {"openai": "OPENAI_BASE_URL", "anthropic": "ANTHROPIC_BASE_URL"}
+TIMEOUT = float(os.environ.get("PREMAN_AGENT_TIMEOUT", "600"))
+_HOP = {
+    "connection", "keep-alive", "proxy-connection", "proxy-authorization", "transfer-encoding",
+    "te", "trailer", "upgrade", "host", "content-length", "accept-encoding",
+}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None  # a 3xx goes back to the agent unchanged; credentials never follow it elsewhere
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+class _Server(http.server.ThreadingHTTPServer):
+    daemon_threads = True
+
+    def handle_error(self, request, client_address):
+        pass  # nothing is ever printed: a traceback can carry a header or a token
+
+
+def version() -> str:
+    """The CLI version this proxy shipped with, recorded on every turn (spec §6.0.3)."""
+    try:
+        return str(json.loads((Path(__file__).resolve().parent.parent / "package.json").read_text())["version"])
+    except Exception:
+        return "unknown"
+
+
+class Proxy:
+    def __init__(self, upstream=None):
+        self.upstream = upstream or {
+            provider: (os.environ.get(var) or DEFAULT_UPSTREAM[provider]).rstrip("/")
+            for provider, var in ENV_VAR.items()
+        }
+        self._channels = {}
+        self._lock = threading.Lock()
+        self._server = _Server(("127.0.0.1", 0), _handler(self))
+        self._server.daemon_threads = True
+        self.port = self._server.server_address[1]
+        threading.Thread(target=self._server.serve_forever, name="preman-tool-proxy", daemon=True).start()
+
+    def channel(self) -> str:
+        token = secrets.token_hex(16)
+        with self._lock:
+            self._channels[token] = {"turn": None, "between": False, "reported": set(), "waiting": {}}
+        return token
+
+    def env(self, token: str) -> dict:
+        env = {var: "http://127.0.0.1:%d/%s/%s" % (self.port, token, provider) for provider, var in ENV_VAR.items()}
+        # An agent behind HTTP(S)_PROXY must still reach this local proxy directly.
+        hosts = [h.strip() for h in (os.environ.get("NO_PROXY") or os.environ.get("no_proxy") or "").split(",") if h.strip()]
+        hosts += [h for h in ("127.0.0.1", "localhost") if h not in hosts]
+        env["NO_PROXY"] = env["no_proxy"] = ",".join(hosts)
+        return env
+
+    def begin(self, token: str) -> None:
+        with self._lock:
+            channel = self._channels.get(token)
+            if channel is not None:
+                channel["turn"] = _Turn(already=channel["reported"], waiting=channel["waiting"])
+
+    def end(self, token: str):
+        with self._lock:
+            channel = self._channels.get(token)
+            if channel is None:
+                capture = _not_visible(_CHANNEL_CLOSED)
+                capture["trace"] = {"links": "order_only", "reason": _CHANNEL_CLOSED, "known": [], "unknown": {}, "calls": []}
+                capture["proxy_version"] = version()
+                return [], capture
+            turn, channel["turn"] = channel["turn"], None
+            between, channel["between"] = channel["between"], False
+        events, capture = (turn or _Turn(already=channel["reported"], waiting=channel["waiting"])).outcome()
+        if between and capture["state"] == "recorded":
+            capture = dict(
+                _not_visible("a model request arrived between turns, so it was not filed under any of them"),
+                trace=capture.get("trace"),
+            )
+        capture["proxy_version"] = version()
+        return events, capture
+
+    def drop(self, token: str) -> None:
+        with self._lock:
+            self._channels.pop(token, None)
+
+    def close(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+
+    def _turn_for(self, token, kind):
+        with self._lock:
+            channel = self._channels.get(token)
+            if channel is None:
+                return None, False
+            if channel["turn"] is None and kind:
+                # Only a model request counts: a model list or a token count
+                # between turns carries no tool call.
+                channel["between"] = True
+            return channel["turn"], True
+
+
+def _handler(proxy):
+    class Handler(http.server.BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, *args):
+            pass  # the request line carries the channel token; nothing is logged
+
+        def _body(self):
+            if "chunked" in (self.headers.get("Transfer-Encoding") or "").lower():
+                data = bytearray()
+                while True:
+                    size = int(self.rfile.readline().split(b";")[0].strip() or b"0", 16)
+                    if size < 0:
+                        raise ValueError("negative chunk size")
+                    if not size:
+                        self.rfile.readline()
+                        return bytes(data)
+                    data += self.rfile.read(size)
+                    self.rfile.readline()
+            length = int(self.headers.get("Content-Length") or 0)
+            if length < 0:
+                raise ValueError("negative content length")
+            return self.rfile.read(length) if length else b""
+
+        def _refuse(self, status, text):
+            payload = json.dumps({"error": text}).encode()
+            self.send_response_only(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("Connection", "close")  # the request body may be unread
+            self.end_headers()
+            self.wfile.write(payload)
+            self.close_connection = True
+
+        def _forward(self):
+            parts = self.path.split("/", 3)  # ["", token, provider, rest]
+            if len(parts) < 3 or parts[2] not in ENV_VAR:
+                return self._refuse(404, "not a PreMan proxy address")
+            token, provider = parts[1], parts[2]
+            rest = "/" + parts[3] if len(parts) > 3 else ""
+            kind = kind_of(provider, rest)
+            turn, known = proxy._turn_for(token, kind)
+            if not known:
+                return self._refuse(404, "not a PreMan proxy address")
+            try:
+                body = self._body()
+            except ValueError:
+                return self._refuse(400, "malformed request body")
+            conv = None
+            if turn is not None and kind:
+                try:
+                    conv = turn.saw_request(kind, body)
+                except Exception:
+                    turn._fail("a model request could not be read")
+
+            headers = {k: v for k, v in self.headers.items() if k.lower() not in _HOP}
+            request = urllib.request.Request(
+                proxy.upstream[provider] + rest,
+                data=body if body or self.command in ("POST", "PUT", "PATCH") else None,
+                headers=headers,
+                method=self.command,
+            )
+            try:
+                reply = _opener.open(request, timeout=TIMEOUT)
+            except urllib.error.HTTPError as exc:
+                reply = exc  # a 4xx/5xx reply still goes back to the agent unchanged
+            except OSError:
+                self.close_connection = True  # unreachable: the agent sees a dropped connection
+                return
+
+            bodyless = reply.status < 200 or reply.status in (204, 304)
+            self.send_response_only(reply.status, reply.reason)
+            for name, value in reply.headers.items():
+                if name.lower() not in _HOP:
+                    self.send_header(name, value)
+            if not bodyless:
+                self.send_header("Transfer-Encoding", "chunked")
+            self.end_headers()
+            copy = bytearray()
+            cut = False
+
+            def send(chunk):
+                self.wfile.write(b"%x\r\n%s\r\n" % (len(chunk), chunk))
+                self.wfile.flush()
+
+            # One chunk behind: the reply's last chunk reaches the agent only
+            # after the proxy has read the whole reply. Otherwise an SDK that
+            # acts on "[DONE]" can start the next request -- a sub-agent's, or
+            # the turn's end -- before the proxy knows what this reply asked for.
+            held = b""
+            try:
+                while not bodyless:
+                    chunk = reply.read1(65536) if hasattr(reply, "read1") else reply.read(65536)
+                    if not chunk:
+                        break
+                    if held:
+                        send(held)
+                    held = chunk
+                    if len(copy) <= MAX_BODY:
+                        copy += chunk
+            except (OSError, http.client.HTTPException):
+                cut = True
+                self.close_connection = True  # the reply broke off, from either end
+            finally:
+                reply.close()
+            if turn is not None and kind:
+                try:
+                    if cut:
+                        turn._fail("a model reply was cut off before it ended")
+                    turn.saw_reply(
+                        kind,
+                        reply.status,
+                        reply.headers.get("Content-Type", ""),
+                        reply.headers.get("Content-Encoding", ""),
+                        bytes(copy),
+                        len(copy) > MAX_BODY,
+                        conv,
+                    )
+                except Exception:
+                    turn._fail("a model reply could not be read")
+            try:
+                if held:
+                    send(held)
+                if not bodyless and not cut:
+                    self.wfile.write(b"0\r\n\r\n")
+            except (OSError, http.client.HTTPException):
+                self.close_connection = True  # the agent hung up
+
+        do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _forward
+
+    return Handler
+
+
+_shared = None
+_shared_lock = threading.Lock()
+
+
+def shared() -> Proxy:
+    """The one proxy for this process, started on first use."""
+    global _shared
+    with _shared_lock:
+        if _shared is None:
+            _shared = Proxy()
+        return _shared
+
+
+def choose(proxied, reported=None):
+    """The proxy's account when it saw the turn; otherwise (it saw no traffic, its
+    channel closed, or no tools were offered) the agent's own report if that one
+    was recorded. One source per
+    turn, never both, so a call seen both ways is counted once."""
+    if reported is not None and proxied[1].get("state") == "recorded" and reported[1].get("state") == "recorded":
+        def calls(events):
+            return sum(
+                1 for e in events or []
+                if isinstance(e, dict) and (e.get("role") == "tool_result" or (not e.get("role") and e.get("tool_name")))
+            )
+        if calls(reported[0]) > calls(proxied[0]):
+            capture = _not_visible("the agent reported more tool calls than PreMan's proxy saw")
+            capture["proxy_version"] = proxied[1].get("proxy_version", version())
+            if "trace" in proxied[1]:
+                capture["trace"] = proxied[1]["trace"]
+            return proxied[0], capture
+    if proxied[1].get("state") == "recorded" or reported is None:
+        return proxied
+    if reported[1].get("state") == "recorded" and proxied[1].get("reason") in _UNSEEN:
+        capture = dict(reported[1])
+        capture["proxy_version"] = proxied[1].get("proxy_version", version())
+        return reported[0], capture
+    # Neither recorded: keep the agent's own diagnostic next to the proxy's.
+    proxied_reason = proxied[1].get("reason") or ""
+    reported_reason = (reported[1].get("reason") or "") if reported else ""
+    if reported_reason and reported_reason != proxied_reason:
+        capture = dict(proxied[1])
+        capture["reason"] = "%s; %s" % (proxied_reason, reported_reason) if proxied_reason else reported_reason
+        return proxied[0], capture
+    return proxied