proxyagent 0.1.0__tar.gz → 0.2.1__tar.gz

{proxyagent-0.1.0 → proxyagent-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyagent
-Version: 0.1.0
+Version: 0.2.1
 Summary: Run any agent (Claude, Codex, custom) on any machine — with no API key on the machine. A secure, self-hosted proxy for models and tools.
 Project-URL: Homepage, https://github.com/teddyoweh/proxyagent
 Author-email: Spawn Labs <teddy@spawnlabs.ai>
@@ -18,9 +18,16 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.12
 Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: all
+Requires-Dist: cryptography>=42.0; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: secure
+Requires-Dist: cryptography>=42.0; extra == 'secure'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -54,6 +61,15 @@ proxy and use the **machine token** as the "api key." The proxy authenticates th
 checks its scope, **swaps in the real key**, forwards upstream, and logs the call. The
 machine never sees a real credential.
 
+## Try it with zero keys (local)
+```bash
+pip install proxyagent && proxyagent serve        # prints an admin token
+proxyagent token new local --admin pa_admin_…     # mint a token
+# call the built-in `mock` model — full pipeline (auth, scope, usage, cost, log), no real key:
+curl -s localhost:8080/anthropic/v1/messages -H "x-api-key: pa_…" \
+  -d '{"model":"mock","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'
+```
+
 ## Quickstart
 
 **1. Run the proxy** (on a box you control — it holds the real keys):
@@ -98,6 +114,31 @@ export PROXYAGENT_TOOLS='[{"name":"crm","url":"https://hooks.you.com/crm","heade
 # the proxy executes calls to managed tools server-side (keys stay here).
 ```
 
+## Credentials, storage & cost
+
+By default provider keys come from the **environment** and stay local. Or **add** them
+once and they're stored **encrypted** (`proxy_agent_keys`) — locally in SQLite, or in
+**Postgres** if you point at one. Either way the machine never sees them.
+
+```bash
+export PROXYAGENT_SECRET_KEY=…                 # enables at-rest encryption (Fernet)
+proxyagent provider add anthropic --key sk-ant-…          # stored, encrypted
+proxyagent provider add openai --key sk-…  --kind api_key
+# OAuth: store an access token →  proxyagent provider add anthropic --key <oauth-token> --kind oauth
+proxyagent provider ls
+
+# Postgres-backed (shared, multi-instance): tables proxy_agent_keys / _tokens / _calls
+export PROXYAGENT_DATABASE_URL=postgresql://user:pass@host/db    # pip install 'proxyagent[postgres]'
+```
+
+Every call is traced in `proxy_agent_calls` with **token usage, latency, and computed
+cost** (per-model pricing, override via `PROXYAGENT_PRICING`). See it live:
+
+```bash
+proxyagent usage          # totals: requests · tokens · $ cost
+proxyagent logs           # per-request trace incl. cost
+```
+
 ## Security model
 - **Real keys never leave the proxy** — read from env, never persisted, never logged, never returned.
 - **Machine tokens are stored hashed** (SHA-256); plaintext shown once. A stolen DB yields nothing usable.

{proxyagent-0.1.0 → proxyagent-0.2.1}/README.md

@@ -29,6 +29,15 @@ proxy and use the **machine token** as the "api key." The proxy authenticates th
 checks its scope, **swaps in the real key**, forwards upstream, and logs the call. The
 machine never sees a real credential.
 
+## Try it with zero keys (local)
+```bash
+pip install proxyagent && proxyagent serve        # prints an admin token
+proxyagent token new local --admin pa_admin_…     # mint a token
+# call the built-in `mock` model — full pipeline (auth, scope, usage, cost, log), no real key:
+curl -s localhost:8080/anthropic/v1/messages -H "x-api-key: pa_…" \
+  -d '{"model":"mock","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'
+```
+
 ## Quickstart
 
 **1. Run the proxy** (on a box you control — it holds the real keys):
@@ -73,6 +82,31 @@ export PROXYAGENT_TOOLS='[{"name":"crm","url":"https://hooks.you.com/crm","heade
 # the proxy executes calls to managed tools server-side (keys stay here).
 ```
 
+## Credentials, storage & cost
+
+By default provider keys come from the **environment** and stay local. Or **add** them
+once and they're stored **encrypted** (`proxy_agent_keys`) — locally in SQLite, or in
+**Postgres** if you point at one. Either way the machine never sees them.
+
+```bash
+export PROXYAGENT_SECRET_KEY=…                 # enables at-rest encryption (Fernet)
+proxyagent provider add anthropic --key sk-ant-…          # stored, encrypted
+proxyagent provider add openai --key sk-…  --kind api_key
+# OAuth: store an access token →  proxyagent provider add anthropic --key <oauth-token> --kind oauth
+proxyagent provider ls
+
+# Postgres-backed (shared, multi-instance): tables proxy_agent_keys / _tokens / _calls
+export PROXYAGENT_DATABASE_URL=postgresql://user:pass@host/db    # pip install 'proxyagent[postgres]'
+```
+
+Every call is traced in `proxy_agent_calls` with **token usage, latency, and computed
+cost** (per-model pricing, override via `PROXYAGENT_PRICING`). See it live:
+
+```bash
+proxyagent usage          # totals: requests · tokens · $ cost
+proxyagent logs           # per-request trace incl. cost
+```
+
 ## Security model
 - **Real keys never leave the proxy** — read from env, never persisted, never logged, never returned.
 - **Machine tokens are stored hashed** (SHA-256); plaintext shown once. A stolen DB yields nothing usable.

{proxyagent-0.1.0 → proxyagent-0.2.1}/proxyagent/__init__.py

@@ -16,7 +16,7 @@ from typing import Optional
 
 from .harness import run  # noqa: F401  (the headline SDK call)
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 __all__ = ["run", "serve", "create_app", "Config", "Admin", "__version__"]
 
 
@@ -61,5 +61,21 @@ class Admin:
     def revoke(self, token_id: str) -> None:
         self._c.delete(f"/admin/tokens/{token_id}").raise_for_status()
 
+    def add_provider(self, provider: str, secret: str, kind: str = "api_key",
+                     label: Optional[str] = None) -> str:
+        r = self._c.post("/admin/providers", json={
+            "provider": provider, "secret": secret, "kind": kind, "label": label})
+        r.raise_for_status()
+        return r.json()["id"]
+
+    def providers(self) -> dict:
+        return self._c.get("/admin/providers").json()
+
+    def remove_provider(self, cred_id: str) -> None:
+        self._c.delete(f"/admin/providers/{cred_id}").raise_for_status()
+
     def logs(self, limit: int = 100) -> list:
         return self._c.get("/admin/logs", params={"limit": limit}).json()["logs"]
+
+    def usage(self) -> dict:
+        return self._c.get("/admin/usage").json()

{proxyagent-0.1.0 → proxyagent-0.2.1}/proxyagent/cli.py

@@ -68,6 +68,58 @@ def run_harness(
 
 token_app = typer.Typer(help="Mint / list / revoke machine tokens.")
 app.add_typer(token_app, name="token")
+provider_app = typer.Typer(help="Add / list / remove provider credentials (stored, encrypted).")
+app.add_typer(provider_app, name="provider")
+
+
+@provider_app.command("add")
+def provider_add(
+    provider: str = typer.Argument(..., help="anthropic | openai"),
+    key: str = typer.Option(..., "--key", "--secret", help="API key, or OAuth access token with --kind oauth."),
+    kind: str = typer.Option("api_key", "--kind", help="api_key | oauth"),
+    label: str = typer.Option(None, "--label"),
+    proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+    admin: str = typer.Option(None, "--admin"),
+):
+    """Store a provider credential (encrypted if PROXYAGENT_SECRET_KEY is set)."""
+    with _admin_client(proxy, admin) as c:
+        r = c.post("/admin/providers", json={"provider": provider, "secret": key,
+                                             "kind": kind, "label": label})
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    d = r.json()
+    note = "[green]encrypted[/green]" if d["stored"] == "encrypted" else "[yellow]plaintext — set PROXYAGENT_SECRET_KEY[/yellow]"
+    console.print(f"[green]✓[/green] stored [cyan]{provider}[/cyan] ({kind}) · {note}")
+
+
+@provider_app.command("ls")
+def provider_ls(proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+                admin: str = typer.Option(None, "--admin")):
+    """List stored provider credentials (secrets never shown)."""
+    with _admin_client(proxy, admin) as c:
+        r = c.get("/admin/providers")
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    d = r.json()
+    t = Table(title=f"Provider credentials  ·  encryption {'on' if d['encryption'] else 'OFF'}")
+    for col in ("ID", "Provider", "Kind", "Label", "Active"):
+        t.add_column(col)
+    for k in d["credentials"]:
+        t.add_row(k["id"], k["provider"], k["kind"], k.get("label") or "",
+                  "[green]yes[/green]" if k["active"] else "no")
+    console.print(t)
+    console.print(f"[dim]configured (env+stored): {', '.join(d['configured']) or 'none'}[/dim]")
+
+
+@provider_app.command("rm")
+def provider_rm(cred_id: str, proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+                admin: str = typer.Option(None, "--admin")):
+    """Remove a stored credential."""
+    with _admin_client(proxy, admin) as c:
+        r = c.delete(f"/admin/providers/{cred_id}")
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    console.print(f"[green]✓[/green] removed {cred_id}")
 
 
 @token_app.command("new")
@@ -132,14 +184,35 @@ def logs(limit: int = 50, proxy: str = typer.Option("http://127.0.0.1:8080", "--
         err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
     rows = r.json()["logs"]
     t = Table(title="Requests")
-    for col in ("Token", "Provider", "Model", "Status", "In", "Out", "ms"):
+    for col in ("Token", "Provider", "Model", "Status", "In", "Out", "Cost", "ms"):
         t.add_column(col)
     for g in rows:
+        cost = g.get("cost_usd")
         t.add_row(g.get("token_label") or "", g.get("provider") or "", (g.get("model") or "")[:28],
                   str(g.get("status") or ""), str(g.get("prompt_tokens") or "-"),
-                  str(g.get("completion_tokens") or "-"), str(g.get("latency_ms") or ""))
+                  str(g.get("completion_tokens") or "-"),
+                  f"${cost:.4f}" if cost else "-", str(g.get("latency_ms") or ""))
     console.print(t)
 
 
+@app.command()
+def usage(proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+          admin: str = typer.Option(None, "--admin")):
+    """Totals: requests, tokens, and cost across all proxied calls."""
+    with _admin_client(proxy, admin) as c:
+        r = c.get("/admin/usage")
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    d = r.json()
+    u = d["usage"]
+    console.print(Panel.fit(
+        f"[bold]{u['requests']}[/bold] requests   "
+        f"[bold]{u['prompt_tokens']:,}[/bold] in · [bold]{u['completion_tokens']:,}[/bold] out   "
+        f"[green]${u.get('cost_usd', 0):.4f}[/green]\n"
+        f"[dim]backend: {d.get('backend')} · providers: {', '.join(d['providers']) or 'none'} · "
+        f"encryption: {'on' if d.get('encryption') else 'off'}[/dim]",
+        title="usage", border_style="green"))
+
+
 if __name__ == "__main__":
     app()

proxyagent-0.2.1/proxyagent/crypto.py

@@ -0,0 +1,44 @@
+"""At-rest encryption for stored provider credentials.
+
+If `PROXYAGENT_SECRET_KEY` is set (and `cryptography` is installed), provider secrets
+are encrypted with Fernet before they touch the database. Without a key, secrets are
+stored as-is and we warn loudly — fine for a laptop, not for a shared Postgres.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+
+_PREFIX = "enc:"
+
+
+def _fernet():
+    key = os.environ.get("PROXYAGENT_SECRET_KEY")
+    if not key:
+        return None
+    try:
+        from cryptography.fernet import Fernet
+    except ImportError:
+        return None
+    derived = base64.urlsafe_b64encode(hashlib.sha256(key.encode()).digest())
+    return Fernet(derived)
+
+
+def encryption_available() -> bool:
+    return _fernet() is not None
+
+
+def encrypt(value: str) -> str:
+    f = _fernet()
+    return _PREFIX + f.encrypt(value.encode()).decode() if f else value
+
+
+def decrypt(value: str) -> str:
+    if value and value.startswith(_PREFIX):
+        f = _fernet()
+        if not f:
+            raise RuntimeError("PROXYAGENT_SECRET_KEY required to decrypt a stored credential")
+        return f.decrypt(value[len(_PREFIX):].encode()).decode()
+    return value

proxyagent-0.2.1/proxyagent/db.py

@@ -0,0 +1,87 @@
+"""Storage backend — SQLite by default (local), or Postgres when a URL is given.
+
+Set `PROXYAGENT_DATABASE_URL=postgresql://…` (or pass `database_url=`) and everything
+lands in Postgres; otherwise it's a local SQLite file. Tables are prefixed
+`proxy_agent_` so they sit cleanly in a shared database.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+
+
+def database_url() -> str | None:
+    return os.environ.get("PROXYAGENT_DATABASE_URL") or os.environ.get("DATABASE_URL")
+
+
+def is_postgres(url: str | None) -> bool:
+    return bool(url) and url.startswith(("postgres://", "postgresql://"))
+
+
+class DB:
+    """Tiny cross-backend wrapper. Use `?` placeholders everywhere; we translate for
+    Postgres. Thread-safe via a lock (fine for a proxy's scale)."""
+
+    def __init__(self, sqlite_path: str = ":memory:", url: str | None = None):
+        self._lock = threading.RLock()
+        self.url = url if url is not None else database_url()
+        self.pg = is_postgres(self.url)
+        if self.pg:
+            import psycopg  # type: ignore
+            self._conn = psycopg.connect(self.url, autocommit=True)
+        else:
+            self._conn = sqlite3.connect(sqlite_path, check_same_thread=False)
+            self._conn.row_factory = sqlite3.Row
+
+    def _q(self, sql: str) -> str:
+        return sql.replace("?", "%s") if self.pg else sql
+
+    def execute(self, sql: str, params: tuple = ()):  # returns rowcount-ish handle
+        with self._lock:
+            if self.pg:
+                cur = self._conn.cursor()
+                cur.execute(self._q(sql), params)
+                return cur
+            cur = self._conn.execute(sql, params)
+            self._conn.commit()
+            return cur
+
+    def fetchone(self, sql: str, params: tuple = ()) -> dict | None:
+        with self._lock:
+            if self.pg:
+                cur = self._conn.cursor()
+                cur.execute(self._q(sql), params)
+                row = cur.fetchone()
+                if not row:
+                    return None
+                cols = [d[0] for d in cur.description]
+                return dict(zip(cols, row))
+            r = self._conn.execute(sql, params).fetchone()
+            return dict(r) if r else None
+
+    def fetchall(self, sql: str, params: tuple = ()) -> list[dict]:
+        with self._lock:
+            if self.pg:
+                cur = self._conn.cursor()
+                cur.execute(self._q(sql), params)
+                rows = cur.fetchall()
+                cols = [d[0] for d in cur.description]
+                return [dict(zip(cols, r)) for r in rows]
+            rows = self._conn.execute(sql, params).fetchall()
+            return [dict(r) for r in rows]
+
+    def executescript(self, script: str) -> None:
+        with self._lock:
+            if self.pg:
+                cur = self._conn.cursor()
+                for stmt in [s for s in script.split(";") if s.strip()]:
+                    cur.execute(stmt)
+            else:
+                self._conn.executescript(script)
+                self._conn.commit()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()

proxyagent-0.2.1/proxyagent/pricing.py

@@ -0,0 +1,64 @@
+"""Cost tracking — turn token usage into dollars.
+
+Prices are USD per 1M tokens (input, output). Matched by a prefix of the model name,
+so "claude-sonnet-4-5-2025…" picks up "claude-sonnet". Override / extend via
+`PROXYAGENT_PRICING` (JSON: {"model-prefix": [in_per_mtok, out_per_mtok]}).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+# Indicative list prices (USD / 1M tokens). Tune freely.
+DEFAULT_PRICES: dict[str, tuple[float, float]] = {
+    # Anthropic
+    "claude-opus": (15.0, 75.0),
+    "claude-sonnet": (3.0, 15.0),
+    "claude-haiku": (0.80, 4.0),
+    "claude-3-opus": (15.0, 75.0),
+    "claude-3-5-sonnet": (3.0, 15.0),
+    "claude-3-5-haiku": (0.80, 4.0),
+    # OpenAI
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4o": (2.50, 10.0),
+    "gpt-4.1-mini": (0.40, 1.60),
+    "gpt-4.1": (2.0, 8.0),
+    "o3-mini": (1.10, 4.40),
+    "o3": (2.0, 8.0),
+    "gpt-5": (1.25, 10.0),
+    # offline test provider — free
+    "mock": (0.0, 0.0),
+}
+
+
+def _prices() -> dict[str, tuple[float, float]]:
+    prices = dict(DEFAULT_PRICES)
+    raw = os.environ.get("PROXYAGENT_PRICING")
+    if raw:
+        try:
+            for k, v in json.loads(raw).items():
+                prices[k] = (float(v[0]), float(v[1]))
+        except Exception:
+            pass
+    return prices
+
+
+def price_for(model: str) -> tuple[float, float] | None:
+    if not model:
+        return None
+    prices = _prices()
+    # longest matching prefix wins (so gpt-4o-mini beats gpt-4o)
+    best = None
+    for prefix, p in prices.items():
+        if model.startswith(prefix) and (best is None or len(prefix) > len(best[0])):
+            best = (prefix, p)
+    return best[1] if best else None
+
+
+def cost_usd(model: str, input_tokens: int | None, output_tokens: int | None) -> float | None:
+    p = price_for(model or "")
+    if p is None:
+        return None
+    cin, cout = p
+    return round((input_tokens or 0) / 1e6 * cin + (output_tokens or 0) / 1e6 * cout, 6)

proxyagent-0.2.1/proxyagent/providers.py

@@ -0,0 +1,180 @@
+"""Upstream forwarding + scope enforcement.
+
+The proxy receives a request authed by a machine token, swaps in the REAL provider
+key, and forwards it upstream — streaming straight through. The machine never sees
+the real key; the proxy logs usage for every call.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+
+import httpx
+
+from . import pricing
+from .config import Config, PROVIDERS
+from .store import Store, now_ms
+
+# Map our public path → (provider, upstream path).
+ROUTES = {
+    "anthropic": ("anthropic", "/v1/messages"),
+    "openai": ("openai", "/v1/chat/completions"),
+}
+
+
+def resolve_auth(provider, store: Store | None) -> tuple[dict, bool]:
+    """Auth headers for an upstream call. A stored credential (proxy_agent_keys) wins
+    over the env key; returns ({}, False) when nothing is configured."""
+    cred = store.get_credential(provider.name) if store else None
+    if cred:
+        secret, kind = cred["secret"], cred["kind"]
+        if kind == "oauth":
+            return {"Authorization": f"Bearer {secret}", **provider.extra_headers}, True
+        if provider.auth_style == "x-api-key":
+            return {"x-api-key": secret, **provider.extra_headers}, True
+        return {"Authorization": f"Bearer {secret}", **provider.extra_headers}, True
+    headers = provider.auth_headers()
+    return headers, bool(headers)
+
+
+def scope_allows(scope: list[str], provider: str, model: str) -> bool:
+    """A scope entry is a glob over 'provider:model', e.g. 'anthropic:claude-*', or '*'."""
+    target = f"{provider}:{model or '*'}"
+    for entry in scope:
+        if entry == "*" or fnmatch.fnmatch(target, entry) or fnmatch.fnmatch(provider, entry):
+            return True
+    return False
+
+
+def _extract_usage(provider: str, payload: dict) -> tuple[int | None, int | None]:
+    u = payload.get("usage") or {}
+    if provider == "anthropic":
+        return u.get("input_tokens"), u.get("output_tokens")
+    return u.get("prompt_tokens"), u.get("completion_tokens")
+
+
+async def forward(
+    config: Config, provider_name: str, upstream_path: str, body: dict,
+    *, streaming: bool, token: dict, store: Store, tools_used: list[str] | None = None,
+):
+    """Forward a request upstream. Returns (status, headers, body_iter_or_dict, log_after)."""
+    provider = PROVIDERS[provider_name]
+    model = body.get("model", "")
+    t0 = now_ms()
+
+    # Offline mock — exercise the full pipeline (auth, scope, log, cost) with NO real
+    # key. Use model "mock" (or "mock-…") anywhere a real model would go.
+    if model.startswith("mock"):
+        payload, (ptok, ctok) = _mock_payload(provider_name, body)
+        store.log_request(
+            token_id=token["id"], token_label=token.get("label"), provider=provider_name,
+            model=model, status=200, prompt_tokens=ptok, completion_tokens=ctok,
+            latency_ms=now_ms() - t0, streamed=1 if streaming else 0,
+            tools_used=json.dumps(tools_used or []), cost_usd=pricing.cost_usd(model, ptok, ctok),
+            error=None)
+        if streaming:
+            return 200, {"content-type": "text/event-stream"}, _mock_stream(provider_name, payload), None
+        return 200, {"content-type": "application/json"}, payload, None
+
+    auth, ok = resolve_auth(provider, store)
+    if not ok:
+        return 502, {}, {"error": f"provider '{provider_name}' not configured on the proxy "
+                                  f"(set {provider.key_env} or `proxyagent provider add {provider_name}`)"}, None
+
+    url = provider.base_url + upstream_path
+    headers = {"content-type": "application/json", **auth}
+
+    def _log(status, ptok, ctok, err=None):
+        store.log_request(
+            token_id=token["id"], token_label=token.get("label"), provider=provider_name,
+            model=model, status=status, prompt_tokens=ptok, completion_tokens=ctok,
+            latency_ms=now_ms() - t0, streamed=1 if streaming else 0,
+            tools_used=json.dumps(tools_used or []), cost_usd=pricing.cost_usd(model, ptok, ctok),
+            error=err,
+        )
+
+    if streaming:
+        async def _gen():
+            ptok = ctok = None
+            status = 200
+            try:
+                async with httpx.AsyncClient(timeout=config.request_timeout) as client:
+                    async with client.stream("POST", url, headers=headers, json=body) as resp:
+                        status = resp.status_code
+                        async for chunk in resp.aiter_raw():
+                            # Best-effort usage capture from the final SSE event.
+                            text = chunk.decode("utf-8", "ignore")
+                            if '"output_tokens"' in text or '"completion_tokens"' in text:
+                                try:
+                                    for line in text.splitlines():
+                                        if line.startswith("data:"):
+                                            d = json.loads(line[5:].strip())
+                                            usage = d.get("usage") or (d.get("message") or {}).get("usage") or {}
+                                            ptok = usage.get("input_tokens") or usage.get("prompt_tokens") or ptok
+                                            ctok = usage.get("output_tokens") or usage.get("completion_tokens") or ctok
+                                except Exception:
+                                    pass
+                            yield chunk
+            finally:
+                _log(status, ptok, ctok)
+        return 200, {"content-type": "text/event-stream"}, _gen(), None
+
+    # Non-streaming.
+    async with httpx.AsyncClient(timeout=config.request_timeout) as client:
+        resp = await client.post(url, headers=headers, json=body)
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = {"error": resp.text}
+    ptok, ctok = _extract_usage(provider_name, payload if isinstance(payload, dict) else {})
+    _log(resp.status_code, ptok, ctok, None if resp.is_success else str(payload)[:300])
+    return resp.status_code, {"content-type": "application/json"}, payload, None
+
+
+# ------------------------------------------------------------------ #
+# Offline mock — provider-shaped canned responses for local testing.
+# ------------------------------------------------------------------ #
+
+def _last_user_text(body: dict) -> str:
+    for m in reversed(body.get("messages", [])):
+        if m.get("role") == "user":
+            c = m.get("content")
+            if isinstance(c, str):
+                return c
+            if isinstance(c, list):
+                return " ".join(p.get("text", "") for p in c if isinstance(p, dict))
+    return ""
+
+
+def _mock_payload(provider: str, body: dict):
+    prompt = _last_user_text(body)[:200]
+    text = f"[proxyagent mock] received: {prompt!r}. No real key used — the pipeline works."
+    ptok, ctok = max(1, len(prompt) // 4), max(1, len(text) // 4)
+    if provider == "anthropic":
+        return ({
+            "id": "msg_mock", "type": "message", "role": "assistant", "model": body.get("model"),
+            "content": [{"type": "text", "text": text}], "stop_reason": "end_turn",
+            "usage": {"input_tokens": ptok, "output_tokens": ctok},
+        }, (ptok, ctok))
+    return ({
+        "id": "chatcmpl-mock", "object": "chat.completion", "model": body.get("model"),
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": text},
+                     "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": ptok, "completion_tokens": ctok, "total_tokens": ptok + ctok},
+    }, (ptok, ctok))
+
+
+async def _mock_stream(provider: str, payload: dict):
+    import json as _j
+    if provider == "anthropic":
+        text = payload["content"][0]["text"]
+        yield f"event: message_start\ndata: {_j.dumps({'type':'message_start','message':payload})}\n\n".encode()
+        yield (f"event: content_block_delta\ndata: "
+               f"{_j.dumps({'type':'content_block_delta','delta':{'type':'text_delta','text':text}})}\n\n").encode()
+        yield b"event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+    else:
+        text = payload["choices"][0]["message"]["content"]
+        chunk = {"choices": [{"delta": {"content": text}, "index": 0}]}
+        yield f"data: {_j.dumps(chunk)}\n\n".encode()
+        yield b"data: [DONE]\n\n"