make sure to always emit sats cost

Admin token

migrations/versions/cli_tokens_table.py

@@ -0,0 +1,34 @@
+"""add cli_tokens table
+
+Revision ID: cli_tokens_001
+Revises: e8f9a0b1c2d3
+Create Date: 2026-04-25 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "cli_tokens_001"
+down_revision = "e8f9a0b1c2d3"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "cli_tokens",
+        sa.Column("id", sa.String(), primary_key=True, nullable=False),
+        sa.Column("token", sa.String(), nullable=False, unique=True),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created_at", sa.Integer(), nullable=False),
+        sa.Column("last_used_at", sa.Integer(), nullable=True),
+        sa.Column("expires_at", sa.Integer(), nullable=True),
+    )
+    op.create_index("ix_cli_tokens_token", "cli_tokens", ["token"], unique=True)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_cli_tokens_token", table_name="cli_tokens")
+    op.drop_table("cli_tokens")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "routstr"
-version = "0.4.1"
+version = "0.4.3"
 description = "Payment proxy for your LLM endpoint using cashu and nostr."
 readme = "README.md"
 requires-python = ">=3.11"

routstr/core/admin.py

@@ -20,6 +20,7 @@ from ..wallet import (
 from .db import (
     ApiKey,
     CashuTransaction,
+    CliToken,
     ModelRow,
     UpstreamProviderRow,
     create_session,
@@ -38,12 +39,27 @@ ADMIN_SESSION_DURATION = 3600
 MAX_USAGE_ANALYTICS_HOURS = 365 * 24
 
 
-def require_admin_api(request: Request) -> None:
+async def require_admin_api(request: Request) -> None:
     auth_header = request.headers.get("Authorization")
-    if auth_header and auth_header.startswith("Bearer "):
-        token = auth_header.split(" ", 1)[1]
-        expiry = admin_sessions.get(token)
-        if expiry and expiry > int(datetime.now(timezone.utc).timestamp()):
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=403, detail="Unauthorized")
+
+    token = auth_header.split(" ", 1)[1]
+    now_ts = int(datetime.now(timezone.utc).timestamp())
+
+    # 1) Short-lived session token (in-memory)
+    expiry = admin_sessions.get(token)
+    if expiry and expiry > now_ts:
+        return
+
+    # 2) Long-lived CLI token (DB-backed)
+    async with create_session() as session:
+        result = await session.exec(select(CliToken).where(CliToken.token == token))
+        cli_token = result.first()
+        if cli_token and (cli_token.expires_at is None or cli_token.expires_at > now_ts):
+            cli_token.last_used_at = now_ts
+            session.add(cli_token)
+            await session.commit()
             return
 
     raise HTTPException(status_code=403, detail="Unauthorized")
@@ -242,6 +258,73 @@ async def admin_logout(request: Request) -> dict[str, object]:
     return {"ok": True}
 
 
+# ─── CLI Tokens (long-lived bearer tokens for CLI/agent use) ───
+
+
+class CliTokenCreate(BaseModel):
+    name: str
+    expires_in_days: int | None = None
+
+
+@admin_router.get("/api/cli-tokens", dependencies=[Depends(require_admin_api)])
+async def list_cli_tokens() -> list[dict[str, object]]:
+    async with create_session() as session:
+        result = await session.exec(select(CliToken))
+        tokens = result.all()
+    return [
+        {
+            "id": t.id,
+            "name": t.name,
+            "token_preview": f"{t.token[:8]}...{t.token[-4:]}",
+            "created_at": t.created_at,
+            "last_used_at": t.last_used_at,
+            "expires_at": t.expires_at,
+        }
+        for t in tokens
+    ]
+
+
+@admin_router.post("/api/cli-tokens", dependencies=[Depends(require_admin_api)])
+async def create_cli_token(payload: CliTokenCreate) -> dict[str, object]:
+    name = (payload.name or "").strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="Name is required")
+
+    raw_token = secrets.token_urlsafe(32)
+    expires_at: int | None = None
+    if payload.expires_in_days is not None and payload.expires_in_days > 0:
+        expires_at = int(datetime.now(timezone.utc).timestamp()) + (
+            payload.expires_in_days * 86400
+        )
+
+    async with create_session() as session:
+        cli_token = CliToken(token=raw_token, name=name, expires_at=expires_at)
+        session.add(cli_token)
+        await session.commit()
+        await session.refresh(cli_token)
+
+    return {
+        "id": cli_token.id,
+        "name": cli_token.name,
+        "token": raw_token,  # full token returned only on creation
+        "created_at": cli_token.created_at,
+        "expires_at": cli_token.expires_at,
+    }
+
+
+@admin_router.delete(
+    "/api/cli-tokens/{token_id}", dependencies=[Depends(require_admin_api)]
+)
+async def revoke_cli_token(token_id: str) -> dict[str, object]:
+    async with create_session() as session:
+        cli_token = await session.get(CliToken, token_id)
+        if not cli_token:
+            raise HTTPException(status_code=404, detail="Token not found")
+        await session.delete(cli_token)
+        await session.commit()
+    return {"ok": True, "deleted_id": token_id}
+
+
 class WithdrawRequest(BaseModel):
     amount: int
     mint_url: str | None = None

routstr/core/db.py

@@ -239,6 +239,22 @@ class RoutstrFee(SQLModel, table=True):  # type: ignore
     last_paid_at: int | None = Field(default=None)
 
 
+class CliToken(SQLModel, table=True):  # type: ignore
+    """Long-lived authorization token for CLI/agent use against admin endpoints."""
+
+    __tablename__ = "cli_tokens"
+    id: str = Field(
+        primary_key=True, default_factory=lambda: uuid.uuid4().hex
+    )
+    token: str = Field(unique=True, index=True, description="Bearer token value")
+    name: str = Field(description="Human-readable label for this token")
+    created_at: int = Field(default_factory=lambda: int(time.time()))
+    last_used_at: int | None = Field(default=None)
+    expires_at: int | None = Field(
+        default=None, description="Optional expiry unix timestamp; null = never expires"
+    )
+
+
 async def accumulate_routstr_fee(session: AsyncSession, amount_msats: int) -> None:
     stmt = (
         update(RoutstrFee)

routstr/core/main.py

@@ -36,9 +36,9 @@ setup_logging()
 logger = get_logger(__name__)
 
 if os.getenv("VERSION_SUFFIX") is not None:
-    __version__ = f"0.4.1-{os.getenv('VERSION_SUFFIX')}"
+    __version__ = f"0.4.3-{os.getenv('VERSION_SUFFIX')}"
 else:
-    __version__ = "0.4.1"
+    __version__ = "0.4.3"
 
 
 @asynccontextmanager
@@ -103,8 +103,11 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
         btc_price_task = asyncio.create_task(update_prices_periodically())
         pricing_task = asyncio.create_task(update_sats_pricing())
         if global_settings.models_refresh_interval_seconds > 0:
+            # Pass the accessor (not its current value) so the loop sees providers
+            # added/changed via reinitialize_upstreams() instead of staying pinned
+            # to the startup snapshot.
             models_refresh_task = asyncio.create_task(
-                refresh_upstreams_models_periodically(get_upstreams())
+                refresh_upstreams_models_periodically(get_upstreams)
             )
         model_maps_refresh_task = asyncio.create_task(refresh_model_maps_periodically())
         payout_task = asyncio.create_task(periodic_payout())

routstr/upstream/base.py

@@ -604,57 +604,83 @@ class BaseUpstreamProvider:
                         )
                         yield prefix + part
 
-                # Stream finished, process usage if found
-                if usage_chunk_data:
-                    async with create_session() as session:
-                        fresh_key = await session.get(key.__class__, key.hashed_key)
-                        if fresh_key:
-                            try:
-                                cost_data = await adjust_payment_for_tokens(
-                                    fresh_key,
-                                    usage_chunk_data,
-                                    session,
-                                    max_cost_for_model,
-                                )
-                                remaining_balance_msats = fresh_key.balance
-                                # Merge cost into usage
-                                usage_chunk_data["usage"]["cost"] = cost_data.get(
-                                    "total_usd", 0.0
-                                )
-                                usage_chunk_data["usage"]["cost_sats"] = (
-                                    cost_data.get("total_msats", 0) // 1000
-                                )
-                                usage_chunk_data["usage"]["remaining_balance_msats"] = (
-                                    remaining_balance_msats
-                                )
-                                # Keep detailed cost in metadata
-                                usage_chunk_data["metadata"] = usage_chunk_data.get(
-                                    "metadata", {}
-                                )
-                                usage_chunk_data["metadata"]["routstr"] = {
-                                    "cost": cost_data
+                async with create_session() as session:
+                    fresh_key = await session.get(key.__class__, key.hashed_key)
+                    if fresh_key:
+                        cost_data: dict
+                        try:
+                            adjustment_input = (
+                                usage_chunk_data
+                                if usage_chunk_data is not None
+                                else {
+                                    "model": last_model_seen or "unknown",
+                                    "usage": None,
                                 }
-                                usage_chunk_data["metadata"]["routstr"]["cost"][
-                                    "sats_cost"
-                                ] = cost_data.get("total_msats", 0) // 1000
-                                usage_chunk_data["metadata"]["routstr"]["cost"][
-                                    "remaining_balance_msats"
-                                ] = remaining_balance_msats
-                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
-                                usage_finalized = True
-                            except Exception as e:
-                                logger.exception(
-                                    "Error during usage finalization",
-                                    extra={
-                                        "key_hash": key.hashed_key[:8] + "...",
-                                        "error": str(e),
-                                    },
-                                )
-                                # Fallback: yield original usage chunk if adjustment fails
-                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
+                            )
+                            cost_data = await adjust_payment_for_tokens(
+                                fresh_key,
+                                adjustment_input,
+                                session,
+                                max_cost_for_model,
+                            )
+                            usage_finalized = True
+                        except Exception as e:
+                            logger.exception(
+                                "Error during usage finalization",
+                                extra={
+                                    "key_hash": key.hashed_key[:8] + "...",
+                                    "error": str(e),
+                                },
+                            )
 
-                if not usage_finalized:
-                    await finalize_db_only()
+                            # Fall back so we still emit a non-zero sats cost downstream.
+                            cost_data = {
+                                "base_msats": 0,
+                                "input_msats": 0,
+                                "output_msats": 0,
+                                "total_msats": 0,
+                                "total_usd": 0.0,
+                                "input_tokens": 0,
+                                "output_tokens": 0,
+                            }
+
+                        if usage_chunk_data is None:
+                            if not hasattr(self, "_current_stream_id"):
+                                self._current_stream_id = (
+                                    f"chatcmpl-{uuid.uuid4()}"
+                                )
+                            usage_chunk_data = {
+                                "id": self._current_stream_id,
+                                "object": "chat.completion.chunk",
+                                "model": last_model_seen or "unknown",
+                                "choices": [],
+                                "usage": {
+                                    "prompt_tokens": cost_data.get(
+                                        "input_tokens", 0
+                                    ),
+                                    "completion_tokens": cost_data.get(
+                                        "output_tokens", 0
+                                    ),
+                                    "total_tokens": cost_data.get(
+                                        "input_tokens", 0
+                                    )
+                                    + cost_data.get("output_tokens", 0),
+                                },
+                            }
+
+                        try:
+                            self.inject_cost_metadata(
+                                usage_chunk_data, cost_data, fresh_key
+                            )
+                        except Exception:
+                            logger.exception(
+                                "Failed to inject cost metadata into streaming chunk",
+                                extra={
+                                    "key_hash": key.hashed_key[:8] + "...",
+                                },
+                            )
+
+                        yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
 
                 if done_seen:
                     yield b"data: [DONE]\n\n"
@@ -926,65 +952,108 @@ class BaseUpstreamProvider:
                         )
                         yield prefix + part
 
-                # Stream finished, process usage if found
-                if usage_chunk_data:
-                    async with create_session() as session:
-                        fresh_key = await session.get(key.__class__, key.hashed_key)
-                        if fresh_key:
-                            try:
-                                cost_data = await adjust_payment_for_tokens(
-                                    fresh_key,
-                                    usage_chunk_data,
-                                    session,
-                                    max_cost_for_model,
-                                )
-                                remaining_balance_msats = fresh_key.balance
-                                # Merge cost into usage chunk
-                                if (
-                                    "response" in usage_chunk_data
-                                    and "usage" in usage_chunk_data["response"]
-                                ):
-                                    usage_chunk_data["response"]["usage"]["cost"] = (
-                                        cost_data.get("total_usd", 0.0)
-                                    )
-                                    usage_chunk_data["response"]["usage"][
-                                        "cost_sats"
-                                    ] = cost_data.get("total_msats", 0) // 1000
-                                    usage_chunk_data["response"]["usage"][
-                                        "remaining_balance_msats"
-                                    ] = remaining_balance_msats
-                                elif "usage" in usage_chunk_data:
-                                    usage_chunk_data["usage"]["cost"] = cost_data.get(
-                                        "total_usd", 0.0
-                                    )
-                                    usage_chunk_data["usage"]["cost_sats"] = (
-                                        cost_data.get("total_msats", 0) // 1000
-                                    )
-                                    usage_chunk_data["usage"][
-                                        "remaining_balance_msats"
-                                    ] = remaining_balance_msats
-
-                                # Keep detailed cost in metadata
-                                usage_chunk_data["metadata"] = usage_chunk_data.get(
-                                    "metadata", {}
-                                )
-                                usage_chunk_data["metadata"]["routstr"] = {
-                                    "cost": cost_data
+                # Always emit a cost-bearing data chunk
+                async with create_session() as session:
+                    fresh_key = await session.get(key.__class__, key.hashed_key)
+                    if fresh_key:
+                        cost_data: dict
+                        try:
+                            adjustment_input = (
+                                usage_chunk_data
+                                if usage_chunk_data is not None
+                                else {
+                                    "model": last_model_seen or "unknown",
+                                    "usage": None,
                                 }
-                                usage_chunk_data["metadata"]["routstr"]["cost"][
-                                    "sats_cost"
-                                ] = cost_data.get("total_msats", 0) // 1000
-                                usage_chunk_data["metadata"]["routstr"]["cost"][
-                                    "remaining_balance_msats"
-                                ] = remaining_balance_msats
-                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
-                                usage_finalized = True
-                            except Exception:
-                                # Fallback: yield original usage chunk if adjustment fails
-                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
+                            )
+                            cost_data = await adjust_payment_for_tokens(
+                                fresh_key,
+                                adjustment_input,
+                                session,
+                                max_cost_for_model,
+                            )
+                            usage_finalized = True
+                        except Exception as e:
+                            logger.exception(
+                                "Error during Responses API usage finalization",
+                                extra={
+                                    "key_hash": key.hashed_key[:8] + "...",
+                                    "error": str(e),
+                                },
+                            )
+                            cost_data = {
+                                "base_msats": 0,
+                                "input_msats": 0,
+                                "output_msats": 0,
+                                "total_msats": 0,
+                                "total_usd": 0.0,
+                                "input_tokens": 0,
+                                "output_tokens": 0,
+                            }
 
-                if not usage_finalized:
-                    await finalize_db_only()
+                        if usage_chunk_data is None:
+                            usage_chunk_data = {
+                                "type": "response.completed",
+                                "response": {
+                                    "model": last_model_seen or "unknown",
+                                    "usage": {
+                                        "input_tokens": cost_data.get(
+                                            "input_tokens", 0
+                                        ),
+                                        "output_tokens": cost_data.get(
+                                            "output_tokens", 0
+                                        ),
+                                        "total_tokens": cost_data.get(
+                                            "input_tokens", 0
+                                        )
+                                        + cost_data.get("output_tokens", 0),
+                                    },
+                                },
+                                "usage": {
+                                    "input_tokens": cost_data.get(
+                                        "input_tokens", 0
+                                    ),
+                                    "output_tokens": cost_data.get(
+                                        "output_tokens", 0
+                                    ),
+                                    "total_tokens": cost_data.get(
+                                        "input_tokens", 0
+                                    )
+                                    + cost_data.get("output_tokens", 0),
+                                },
+                            }
+
+                        remaining_balance_msats = fresh_key.balance
+                        sats_cost = cost_data.get("total_msats", 0) // 1000
+
+                        if (
+                            "response" in usage_chunk_data
+                            and isinstance(usage_chunk_data["response"], dict)
+                            and "usage" in usage_chunk_data["response"]
+                        ):
+                            usage_chunk_data["response"]["usage"]["cost"] = (
+                                cost_data.get("total_usd", 0.0)
+                            )
+                            usage_chunk_data["response"]["usage"][
+                                "cost_sats"
+                            ] = sats_cost
+                            usage_chunk_data["response"]["usage"][
+                                "remaining_balance_msats"
+                            ] = remaining_balance_msats
+
+                        try:
+                            self.inject_cost_metadata(
+                                usage_chunk_data, cost_data, fresh_key
+                            )
+                        except Exception:
+                            logger.exception(
+                                "Failed to inject cost metadata into Responses streaming chunk",
+                                extra={
+                                    "key_hash": key.hashed_key[:8] + "...",
+                                },
+                            )
+
+                        yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
 
                 if done_seen:
                     yield b"data: [DONE]\n\n"
@@ -1308,7 +1377,8 @@ class BaseUpstreamProvider:
                                 )
 
                                 usage_finalized = True
-                                yield f"event: cost\ndata: {json.dumps({'cost': cost_data})}\n\n".encode()
+                                # Emit the full combined_data as the cost
+                                yield f"event: cost\ndata: {json.dumps(combined_data)}\n\n".encode()
                             except Exception:
                                 pass
 

routstr/upstream/helpers.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import asyncio
 import os
 import re
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable
 
 if TYPE_CHECKING:
     from ..core.settings import Settings
@@ -122,12 +122,16 @@ async def get_all_models_with_overrides(
 
 
 async def refresh_upstreams_models_periodically(
-    upstreams: list[BaseUpstreamProvider],
+    upstreams_provider: (
+        Callable[[], list[BaseUpstreamProvider]] | list[BaseUpstreamProvider]
+    ),
 ) -> None:
     """Background task to periodically refresh models cache for all providers.
 
     Args:
-        upstreams: List of upstream provider instances
+        upstreams_provider: Either a callable returning the live upstream list
+            (preferred — picks up providers added/changed via reinitialize_upstreams),
+            or a static list (legacy, will go stale after reinitialize_upstreams).
     """
     import asyncio
     import random
@@ -139,9 +143,14 @@ async def refresh_upstreams_models_periodically(
         logger.info("Provider models refresh disabled (interval <= 0)")
         return
 
+    def _resolve_upstreams() -> list[BaseUpstreamProvider]:
+        if callable(upstreams_provider):
+            return upstreams_provider()
+        return upstreams_provider
+
     while True:
         try:
-            for upstream in upstreams:
+            for upstream in _resolve_upstreams():
                 try:
                     await upstream.refresh_models_cache()
                 except Exception as e:

tests/integration/test_cli_tokens.py

@@ -0,0 +1,302 @@
+"""Integration tests for CLI token management (/admin/api/cli-tokens).
+
+Covers:
+- GET    /admin/api/cli-tokens           — list (preview only, no full token)
+- POST   /admin/api/cli-tokens           — create (returns full token once)
+- DELETE /admin/api/cli-tokens/{id}      — revoke
+- Using a CLI token as Bearer auth against admin endpoints
+- Expiry enforcement (expired tokens are rejected by require_admin_api)
+- last_used_at bump on successful use
+- Auth failures: missing token, wrong token, revoked token
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import AsyncGenerator
+
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+from sqlmodel import select
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import AsyncSession, CliToken
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Fixtures
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest_asyncio.fixture
+async def admin_session_token() -> AsyncGenerator[str, None]:
+    """Inject a short-lived admin session token into admin_sessions."""
+    token = secrets.token_urlsafe(24)
+    admin_sessions[token] = int(time.time()) + 3600
+    yield token
+    admin_sessions.pop(token, None)
+
+
+@pytest_asyncio.fixture
+async def admin_client(
+    integration_client: AsyncClient, admin_session_token: str
+) -> AsyncClient:
+    """An integration_client pre-authenticated with an admin session token."""
+    integration_client.headers["Authorization"] = f"Bearer {admin_session_token}"
+    return integration_client
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Creation
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_returns_full_token_once(
+    admin_client: AsyncClient,
+) -> None:
+    """POST /admin/api/cli-tokens returns the raw token only on creation."""
+    resp = await admin_client.post(
+        "/admin/api/cli-tokens",
+        json={"name": "my-laptop"},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+
+    assert body["name"] == "my-laptop"
+    assert isinstance(body["id"], str) and body["id"]
+    assert isinstance(body["token"], str) and len(body["token"]) >= 32
+    assert body["expires_at"] is None
+    assert isinstance(body["created_at"], int)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_with_expiry(admin_client: AsyncClient) -> None:
+    """expires_in_days sets expires_at ~= now + days * 86400."""
+    before = int(time.time())
+    resp = await admin_client.post(
+        "/admin/api/cli-tokens",
+        json={"name": "ci-runner", "expires_in_days": 7},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+
+    assert body["expires_at"] is not None
+    delta = body["expires_at"] - before
+    # Allow 10s jitter around 7 * 86400
+    assert 7 * 86400 - 10 <= delta <= 7 * 86400 + 10
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_rejects_empty_name(
+    admin_client: AsyncClient,
+) -> None:
+    resp = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "   "}
+    )
+    assert resp.status_code == 400
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_requires_admin(
+    integration_client: AsyncClient,
+) -> None:
+    """No admin token / no bearer → 403."""
+    resp = await integration_client.post(
+        "/admin/api/cli-tokens", json={"name": "no-auth"}
+    )
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Listing
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_list_cli_tokens_returns_preview_not_full_token(
+    admin_client: AsyncClient,
+) -> None:
+    """Listing never leaks the raw token."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "secret-keeper"}
+    )
+    assert create.status_code == 200
+    full_token = create.json()["token"]
+
+    resp = await admin_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 200
+    items = resp.json()
+    assert any(t["name"] == "secret-keeper" for t in items)
+
+    for t in items:
+        # No 'token' field, only 'token_preview'
+        assert "token" not in t
+        assert "token_preview" in t
+        assert full_token not in t["token_preview"]
+        assert "..." in t["token_preview"]
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_list_cli_tokens_requires_admin(
+    integration_client: AsyncClient,
+) -> None:
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Using a CLI token as admin auth
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_cli_token_authorizes_admin_endpoints(
+    admin_client: AsyncClient,
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """A freshly-created CLI token can be used as Bearer on admin endpoints."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "cli-auth"}
+    )
+    assert create.status_code == 200
+    cli_token = create.json()["token"]
+    token_id = create.json()["id"]
+
+    # Use a NEW client to isolate the header from admin_session_token
+    integration_client.headers["Authorization"] = f"Bearer {cli_token}"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 200
+
+    # last_used_at should be populated after use
+    row = await integration_session.get(CliToken, token_id)
+    assert row is not None
+    assert row.last_used_at is not None
+    assert row.last_used_at >= row.created_at
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_expired_cli_token_is_rejected(
+    admin_client: AsyncClient,
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """A CLI token with expires_at in the past → 403."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens",
+        json={"name": "will-expire", "expires_in_days": 1},
+    )
+    assert create.status_code == 200
+    cli_token = create.json()["token"]
+    token_id = create.json()["id"]
+
+    # Force-expire it in the DB
+    row = await integration_session.get(CliToken, token_id)
+    assert row is not None
+    row.expires_at = int(time.time()) - 1
+    integration_session.add(row)
+    await integration_session.commit()
+
+    integration_client.headers["Authorization"] = f"Bearer {cli_token}"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_invalid_bearer_token_is_rejected(
+    integration_client: AsyncClient,
+) -> None:
+    integration_client.headers["Authorization"] = "Bearer not-a-real-token"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Revocation
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_revoke_cli_token_removes_auth(
+    admin_client: AsyncClient,
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """After DELETE, the token no longer authorizes."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "to-revoke"}
+    )
+    token_id = create.json()["id"]
+    cli_token = create.json()["token"]
+
+    revoke = await admin_client.delete(f"/admin/api/cli-tokens/{token_id}")
+    assert revoke.status_code == 200
+    assert revoke.json() == {"ok": True, "deleted_id": token_id}
+
+    # Row is gone
+    row = await integration_session.get(CliToken, token_id)
+    assert row is None
+
+    # Can no longer be used for auth
+    integration_client.headers["Authorization"] = f"Bearer {cli_token}"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_revoke_unknown_cli_token_returns_404(
+    admin_client: AsyncClient,
+) -> None:
+    resp = await admin_client.delete("/admin/api/cli-tokens/does-not-exist")
+    assert resp.status_code == 404
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_revoke_cli_token_requires_admin(
+    integration_client: AsyncClient,
+) -> None:
+    resp = await integration_client.delete("/admin/api/cli-tokens/anything")
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Lifecycle / uniqueness
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_multiple_tokens_are_independent(
+    admin_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """Creating N tokens yields N unique tokens that all live in DB."""
+    names = ["dev-a", "dev-b", "dev-c"]
+    raw_tokens: list[str] = []
+    ids: list[str] = []
+    for name in names:
+        r = await admin_client.post(
+            "/admin/api/cli-tokens", json={"name": name}
+        )
+        assert r.status_code == 200
+        raw_tokens.append(r.json()["token"])
+        ids.append(r.json()["id"])
+
+    # All unique
+    assert len(set(raw_tokens)) == len(raw_tokens)
+    assert len(set(ids)) == len(ids)
+
+    # All in DB
+    result = await integration_session.exec(
+        select(CliToken).where(CliToken.name.in_(names))  # type: ignore[attr-defined]
+    )
+    rows = result.all()
+    assert {r.name for r in rows} == set(names)

tests/unit/test_models_refresh_loop.py

@@ -0,0 +1,117 @@
+"""Regression tests for the periodic upstream models refresh loop."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import cast
+from unittest.mock import AsyncMock
+
+import pytest
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+
+from routstr.upstream.base import BaseUpstreamProvider  # noqa: E402
+
+
+class _FakeUpstream:
+    """Minimal stand-in for BaseUpstreamProvider used by the refresh loop.
+
+    Only ``base_url`` (for error logging) and ``refresh_models_cache`` (the call
+    under test) are exercised; everything else stays unused.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.base_url = f"http://{name}"
+        self.refresh_models_cache = AsyncMock()
+
+
+def _make_fake_upstream(name: str) -> BaseUpstreamProvider:
+    # The loop only uses duck-typed attributes — cast keeps the test type-clean
+    # without dragging in BaseUpstreamProvider's full constructor.
+    return cast(BaseUpstreamProvider, _FakeUpstream(name))
+
+
+@pytest.mark.asyncio
+async def test_refresh_loop_picks_up_providers_added_after_startup(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """If a provider is added after the loop starts (e.g. via reinitialize_upstreams),
+    the next loop iteration must refresh it. Previously the loop captured the upstream
+    list at startup and missed any later additions."""
+    from routstr.core.settings import settings as global_settings
+    from routstr.upstream.helpers import refresh_upstreams_models_periodically
+
+    # Tight interval so the test finishes quickly.
+    monkeypatch.setattr(
+        global_settings, "models_refresh_interval_seconds", 1, raising=False
+    )
+
+    initial_upstream = _make_fake_upstream("initial")
+    live_list: list[BaseUpstreamProvider] = [initial_upstream]
+
+    # Stub out the post-iteration sats-pricing refresh so the loop body has no DB deps.
+    async def _noop_pricing_refresh() -> None:  # pragma: no cover - trivial stub
+        return None
+
+    monkeypatch.setattr(
+        "routstr.payment.models._update_sats_pricing_once",
+        _noop_pricing_refresh,
+    )
+
+    task = asyncio.create_task(
+        refresh_upstreams_models_periodically(lambda: live_list)
+    )
+
+    try:
+        # Wait for the first iteration to refresh the initial upstream.
+        for _ in range(40):
+            if initial_upstream.refresh_models_cache.await_count >= 1:  # type: ignore[attr-defined]
+                break
+            await asyncio.sleep(0.05)
+        assert initial_upstream.refresh_models_cache.await_count >= 1, (  # type: ignore[attr-defined]
+            "loop did not refresh the initial upstream within the timeout"
+        )
+
+        # Simulate reinitialize_upstreams: replace the live list contents with new
+        # provider instances. The loop must observe the swap on its next tick.
+        new_upstream = _make_fake_upstream("added-after-startup")
+        live_list[:] = [new_upstream]
+
+        for _ in range(60):
+            if new_upstream.refresh_models_cache.await_count >= 1:  # type: ignore[attr-defined]
+                break
+            await asyncio.sleep(0.05)
+
+        assert new_upstream.refresh_models_cache.await_count >= 1, (  # type: ignore[attr-defined]
+            "loop did not refresh the upstream added after startup — "
+            "regression: list snapshot captured at startup"
+        )
+    finally:
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+
+@pytest.mark.asyncio
+async def test_refresh_loop_disabled_when_interval_non_positive(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from routstr.core.settings import settings as global_settings
+    from routstr.upstream.helpers import refresh_upstreams_models_periodically
+
+    monkeypatch.setattr(
+        global_settings, "models_refresh_interval_seconds", 0, raising=False
+    )
+
+    upstream = _make_fake_upstream("never-refreshed")
+
+    # Loop must return immediately without ever touching the upstream.
+    await asyncio.wait_for(
+        refresh_upstreams_models_periodically(lambda: [upstream]),
+        timeout=1.0,
+    )
+    upstream.refresh_models_cache.assert_not_awaited()  # type: ignore[attr-defined]

tests/unit/test_stream_id_injection.py

@@ -51,7 +51,15 @@ async def test_stream_with_id_injection() -> None:
         base.adjust_payment_for_tokens = AsyncMock(
             return_value={"total_usd": 0.1, "total_msats": 100}
         )
-        base.create_session = MagicMock()
+        # create_session() is used as an async context manager whose entered
+        # value exposes an awaitable .get(). Build a mock that behaves that
+        # way so the post-stream cost-chunk emission can run.
+        mock_session = MagicMock()
+        mock_session.get = AsyncMock(return_value=key)
+        mock_ctx = MagicMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        base.create_session = MagicMock(return_value=mock_ctx)
 
         streaming_response = await provider.handle_streaming_chat_completion(
             response=mock_response,

ui/app/settings/page.tsx

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { ServerConfigSettings } from '@/components/settings/server-config-settings';
 import { AdminSettings } from '@/components/settings/admin-settings';
+import { CliTokensSettings } from '@/components/settings/cli-tokens-settings';
 import { AppPageShell } from '@/components/app-page-shell';
 import { PageHeader } from '@/components/page-header';
 
@@ -19,6 +20,7 @@ export default function SettingsPage() {
           <TabsList variant='line' className='mb-4 w-full'>
             <TabsTrigger value='admin'>Admin Settings</TabsTrigger>
             <TabsTrigger value='server'>Server Config</TabsTrigger>
+            <TabsTrigger value='cli-tokens'>CLI Tokens</TabsTrigger>
           </TabsList>
           <TabsContent value='server'>
             <ServerConfigSettings />
@@ -26,6 +28,9 @@ export default function SettingsPage() {
           <TabsContent value='admin'>
             <AdminSettings />
           </TabsContent>
+          <TabsContent value='cli-tokens'>
+            <CliTokensSettings />
+          </TabsContent>
         </Tabs>
       </div>
     </AppPageShell>

ui/components/add-provider-model-dialog.tsx

@@ -540,7 +540,7 @@ export function AddProviderModelDialog({
                   };
                   return (
                     <FormItem>
-                      <FormLabel>Upstream Model ID</FormLabel>
+                      <FormLabel>Client Alias ID</FormLabel>
                       <FormControl>
                         <div className='flex gap-2'>
                           <Input
@@ -565,8 +565,8 @@ export function AddProviderModelDialog({
                         </div>
                       </FormControl>
                       <FormDescription>
-                        Model ID sent to the upstream provider. Defaults to the
-                        model&apos;s own ID.
+                        Alternate ID that clients can use to reference this
+                        model. Defaults to the model&apos;s own ID.
                       </FormDescription>
                       <FormMessage />
                     </FormItem>

ui/components/settings/cli-tokens-settings.tsx

@@ -0,0 +1,265 @@
+'use client';
+
+import * as React from 'react';
+import { useState, useEffect, useCallback } from 'react';
+import {
+  AdminService,
+  type CliTokenListItem,
+  type CliTokenCreated,
+} from '@/lib/api/services/admin';
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+} from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { AlertCircle, Copy, Trash2, Check } from 'lucide-react';
+import { toast } from 'sonner';
+
+function formatTs(ts: number | null): string {
+  if (!ts) return '—';
+  return new Date(ts * 1000).toLocaleString();
+}
+
+export function CliTokensSettings(): React.ReactElement {
+  const [tokens, setTokens] = useState<CliTokenListItem[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [name, setName] = useState('');
+  const [expiresInDays, setExpiresInDays] = useState<string>('');
+  const [creating, setCreating] = useState(false);
+  const [newToken, setNewToken] = useState<CliTokenCreated | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  const loadTokens = useCallback(async (): Promise<void> => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await AdminService.listCliTokens();
+      setTokens(data);
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : 'Failed to load tokens';
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadTokens();
+  }, [loadTokens]);
+
+  async function handleCreate(): Promise<void> {
+    const trimmed = name.trim();
+    if (!trimmed) {
+      toast.error('Name is required');
+      return;
+    }
+    const days = expiresInDays.trim()
+      ? Number.parseInt(expiresInDays.trim(), 10)
+      : undefined;
+    if (days !== undefined && (Number.isNaN(days) || days <= 0)) {
+      toast.error('Expiry must be a positive number of days');
+      return;
+    }
+
+    setCreating(true);
+    try {
+      const created = await AdminService.createCliToken(trimmed, days);
+      setNewToken(created);
+      setName('');
+      setExpiresInDays('');
+      await loadTokens();
+      toast.success('Token created. Copy it now — it will not be shown again.');
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : 'Failed to create token';
+      toast.error(message);
+    } finally {
+      setCreating(false);
+    }
+  }
+
+  async function handleRevoke(id: string): Promise<void> {
+    if (
+      !confirm('Revoke this token? Any CLI/agent using it will lose access.')
+    ) {
+      return;
+    }
+    try {
+      await AdminService.revokeCliToken(id);
+      await loadTokens();
+      toast.success('Token revoked');
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : 'Failed to revoke token';
+      toast.error(message);
+    }
+  }
+
+  async function handleCopy(): Promise<void> {
+    if (!newToken) return;
+    await navigator.clipboard.writeText(newToken.token);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  }
+
+  return (
+    <div className='space-y-6'>
+      <Card>
+        <CardHeader>
+          <CardTitle>Create CLI Token</CardTitle>
+          <CardDescription>
+            Generate a long-lived bearer token for the Routstr CLI or AI agents.
+            Use this token in <code>~/.routstr/config.json</code> or with{' '}
+            <code>routstr init --token &lt;token&gt;</code>.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className='space-y-4'>
+          {newToken && (
+            <Alert className='border-green-500/50 bg-green-500/10'>
+              <AlertDescription className='space-y-3'>
+                <div className='font-medium text-green-700 dark:text-green-400'>
+                  Token created. Copy it now — it will not be shown again.
+                </div>
+                <div className='flex items-center gap-2'>
+                  <code className='bg-muted flex-1 rounded px-3 py-2 text-xs break-all'>
+                    {newToken.token}
+                  </code>
+                  <Button
+                    type='button'
+                    variant='outline'
+                    size='sm'
+                    onClick={handleCopy}
+                  >
+                    {copied ? (
+                      <Check className='h-4 w-4' />
+                    ) : (
+                      <Copy className='h-4 w-4' />
+                    )}
+                  </Button>
+                </div>
+                <Button
+                  type='button'
+                  variant='ghost'
+                  size='sm'
+                  onClick={() => setNewToken(null)}
+                >
+                  Dismiss
+                </Button>
+              </AlertDescription>
+            </Alert>
+          )}
+          <div className='grid grid-cols-1 gap-4 md:grid-cols-2'>
+            <div className='space-y-2'>
+              <Label htmlFor='cli-token-name'>Name</Label>
+              <Input
+                id='cli-token-name'
+                placeholder='e.g. dev-laptop, ci-runner'
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                disabled={creating}
+              />
+            </div>
+            <div className='space-y-2'>
+              <Label htmlFor='cli-token-expiry'>
+                Expires in days (optional)
+              </Label>
+              <Input
+                id='cli-token-expiry'
+                type='number'
+                min='1'
+                placeholder='Never expires if blank'
+                value={expiresInDays}
+                onChange={(e) => setExpiresInDays(e.target.value)}
+                disabled={creating}
+              />
+            </div>
+          </div>
+          <Button onClick={handleCreate} disabled={creating || !name.trim()}>
+            {creating ? 'Creating…' : 'Create Token'}
+          </Button>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Active Tokens</CardTitle>
+          <CardDescription>
+            Tokens authorize CLI/agent calls to admin endpoints. Revoke any
+            token that may have been exposed.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {error && (
+            <Alert variant='destructive' className='mb-4'>
+              <AlertCircle className='h-4 w-4' />
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
+          )}
+          {loading ? (
+            <div className='space-y-2'>
+              <Skeleton className='h-12 w-full' />
+              <Skeleton className='h-12 w-full' />
+            </div>
+          ) : tokens.length === 0 ? (
+            <p className='text-muted-foreground text-sm'>
+              No tokens yet. Create one above.
+            </p>
+          ) : (
+            <div className='overflow-x-auto'>
+              <table className='w-full text-sm'>
+                <thead>
+                  <tr className='text-muted-foreground border-b text-left'>
+                    <th className='py-2 pr-4 font-medium'>Name</th>
+                    <th className='py-2 pr-4 font-medium'>Token</th>
+                    <th className='py-2 pr-4 font-medium'>Created</th>
+                    <th className='py-2 pr-4 font-medium'>Last used</th>
+                    <th className='py-2 pr-4 font-medium'>Expires</th>
+                    <th className='py-2 font-medium'></th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {tokens.map((t) => (
+                    <tr key={t.id} className='border-b last:border-0'>
+                      <td className='py-2 pr-4'>{t.name}</td>
+                      <td className='py-2 pr-4 font-mono text-xs'>
+                        {t.token_preview}
+                      </td>
+                      <td className='text-muted-foreground py-2 pr-4'>
+                        {formatTs(t.created_at)}
+                      </td>
+                      <td className='text-muted-foreground py-2 pr-4'>
+                        {formatTs(t.last_used_at)}
+                      </td>
+                      <td className='text-muted-foreground py-2 pr-4'>
+                        {t.expires_at ? formatTs(t.expires_at) : 'Never'}
+                      </td>
+                      <td className='py-2'>
+                        <Button
+                          type='button'
+                          variant='ghost'
+                          size='sm'
+                          onClick={() => void handleRevoke(t.id)}
+                        >
+                          <Trash2 className='h-4 w-4' />
+                        </Button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

ui/lib/api/services/admin.ts

@@ -966,6 +966,45 @@ export class AdminService {
       balance_data: number | null | Record<string, unknown>;
     }>(`/admin/api/upstream-providers/${providerId}/balance`);
   }
+
+  // ── CLI Tokens ──
+
+  static async listCliTokens(): Promise<CliTokenListItem[]> {
+    return await apiClient.get<CliTokenListItem[]>('/admin/api/cli-tokens');
+  }
+
+  static async createCliToken(
+    name: string,
+    expiresInDays?: number
+  ): Promise<CliTokenCreated> {
+    return await apiClient.post<CliTokenCreated>('/admin/api/cli-tokens', {
+      name,
+      expires_in_days: expiresInDays ?? null,
+    });
+  }
+
+  static async revokeCliToken(tokenId: string): Promise<{ ok: boolean }> {
+    return await apiClient.delete<{ ok: boolean }>(
+      `/admin/api/cli-tokens/${encodeURIComponent(tokenId)}`
+    );
+  }
+}
+
+export interface CliTokenListItem {
+  id: string;
+  name: string;
+  token_preview: string;
+  created_at: number;
+  last_used_at: number | null;
+  expires_at: number | null;
+}
+
+export interface CliTokenCreated {
+  id: string;
+  name: string;
+  token: string;
+  created_at: number;
+  expires_at: number | null;
 }
 
 export const TemporaryBalanceSchema = z.object({

uv.lock

@@ -1878,7 +1878,7 @@ wheels = [
 
 [[package]]
 name = "routstr"
-version = "0.4.1"
+version = "0.4.3"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },