feat(tui+cli): change your Nous plan from the terminal (/subscription, /topup, terminal-billing UX)

agent/subscription_view.py

@@ -0,0 +1,205 @@
+"""Surface-agnostic core for the ``/subscription`` TUI screen.
+
+Companion to :mod:`agent.billing_view` — same fail-open philosophy: when not
+logged in or the portal is unreachable, return a struct with ``logged_in=False``
+and let the surface degrade gracefully (never crash). Money is decimal end-to-end
+(server emits decimal strings); we only format for display.
+
+The TUI ``SubscriptionOverlay`` is **deep-link only** — it never charges
+in-terminal. The manage URL is built locally on the TUI side from the
+``portal_url`` and ``org_id`` fields in the subscription state.
+
+WS1 dependency: ``GET /api/billing/subscription`` is a NAS endpoint (WS1 Phase A).
+Until it ships, the fail-open contract handles 404s — the builder returns
+``logged_in=False`` and the surface degrades gracefully.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any, Optional
+
+from agent.billing_view import parse_money
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Parsed sub-structures
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class SubscriptionTier:
+    """A plan tier in the catalog."""
+
+    tier_id: str
+    name: str
+    tier_order: int
+    dollars_per_month: Optional[Decimal] = None
+    monthly_credits: Optional[Decimal] = None
+    is_current: bool = False
+    is_enabled: bool = True
+
+
+@dataclass(frozen=True)
+class CurrentSubscription:
+    """The user's active subscription (None fields = free / no active sub)."""
+
+    tier_id: Optional[str] = None
+    tier_name: Optional[str] = None
+    monthly_credits: Optional[Decimal] = None
+    credits_remaining: Optional[Decimal] = None
+    cycle_ends_at: Optional[str] = None  # ISO
+    pending_downgrade_tier_name: Optional[str] = None
+    pending_downgrade_at: Optional[str] = None  # ISO
+    is_past_due: bool = False
+    cancel_at_period_end: bool = False
+    cancellation_effective_at: Optional[str] = None  # ISO
+
+
+@dataclass(frozen=True)
+class SubscriptionState:
+    """Parsed ``GET /api/billing/subscription`` — the overview screen's data.
+
+    Fail-open: ``logged_in=False`` (and empty fields) when not logged in or the
+    portal is unreachable.
+    """
+
+    logged_in: bool
+    org_name: Optional[str] = None
+    org_id: Optional[str] = None  # org.id from the NAS response
+    role: Optional[str] = None  # "OWNER" | "ADMIN" | "MEMBER"
+    context: str = "personal"  # "personal" | "team"
+    current: Optional[CurrentSubscription] = None
+    tiers: tuple[SubscriptionTier, ...] = ()
+    portal_url: Optional[str] = None
+    # When the fetch failed (vs cleanly not-logged-in), the message for the surface.
+    error: Optional[str] = None
+
+    @property
+    def is_admin(self) -> bool:
+        """True for OWNER/ADMIN — the roles that can change plans."""
+        return (self.role or "").upper() in ("OWNER", "ADMIN")
+
+    @property
+    def can_change_plan(self) -> bool:
+        """True when the UI should offer plan-change actions (role gate from NAS)."""
+        return self.is_admin
+
+
+# =============================================================================
+# Payload parsing
+# =============================================================================
+
+
+def _parse_tier(raw: Any) -> Optional[SubscriptionTier]:
+    if not isinstance(raw, dict):
+        return None
+    tier_id = raw.get("tierId") or raw.get("id")
+    name = raw.get("name")
+    if not (isinstance(tier_id, str) and isinstance(name, str)):
+        return None
+    return SubscriptionTier(
+        tier_id=tier_id,
+        name=name,
+        tier_order=int(raw.get("tierOrder") or raw.get("order") or 0),
+        dollars_per_month=parse_money(raw.get("dollarsPerMonth") or raw.get("priceUsd")),
+        monthly_credits=parse_money(raw.get("monthlyCredits")),
+        is_current=bool(raw.get("isCurrent")),
+        is_enabled=bool(raw.get("isEnabled", True)),
+    )
+
+
+def _parse_current(raw: Any) -> Optional[CurrentSubscription]:
+    if not isinstance(raw, dict):
+        return None
+    return CurrentSubscription(
+        tier_id=raw.get("tierId") or raw.get("id"),
+        tier_name=raw.get("tierName") or raw.get("name"),
+        monthly_credits=parse_money(raw.get("monthlyCredits")),
+        credits_remaining=parse_money(raw.get("creditsRemaining")),
+        cycle_ends_at=raw.get("cycleEndsAt"),
+        pending_downgrade_tier_name=raw.get("pendingDowngradeTierName"),
+        pending_downgrade_at=raw.get("pendingDowngradeAt"),
+        is_past_due=bool(raw.get("isPastDue")),
+        cancel_at_period_end=bool(raw.get("cancelAtPeriodEnd")),
+        cancellation_effective_at=raw.get("cancellationEffectiveAt") or None,
+    )
+
+
+def subscription_state_from_payload(
+    payload: dict[str, Any], *, portal_url: Optional[str] = None
+) -> SubscriptionState:
+    """Map a raw ``/api/billing/subscription`` JSON dict into :class:`SubscriptionState`."""
+    raw_org = payload.get("org")
+    org: dict[str, Any] = raw_org if isinstance(raw_org, dict) else {}
+
+    tiers: list[SubscriptionTier] = []
+    for item in payload.get("tiers") or ():
+        parsed = _parse_tier(item)
+        if parsed is not None:
+            tiers.append(parsed)
+
+    raw_context = payload.get("context")
+    context = raw_context if raw_context in ("personal", "team") else "personal"
+
+    return SubscriptionState(
+        logged_in=True,
+        org_name=org.get("name"),
+        org_id=org.get("id") or None,
+        role=org.get("role"),
+        context=context,
+        current=_parse_current(payload.get("current")),
+        tiers=tuple(tiers),
+        portal_url=portal_url,
+    )
+
+
+# =============================================================================
+# Fail-open builders (the surface front doors)
+# =============================================================================
+
+
+def build_subscription_state(*, timeout: float = 15.0) -> SubscriptionState:
+    """Fetch + parse ``GET /api/billing/subscription``. Fail-open.
+
+    Returns ``SubscriptionState(logged_in=False)`` when not logged in. On a
+    portal/HTTP failure, returns ``logged_in=False`` with ``error`` set so the
+    surface can show a clear message rather than crashing.
+    """
+    try:
+        from hermes_cli.nous_billing import (
+            BillingAuthError,
+            BillingError,
+            _absolutize_portal_url,
+            get_subscription_state,
+            resolve_portal_base_url,
+        )
+    except Exception:
+        return SubscriptionState(logged_in=False, error="billing client unavailable")
+
+    try:
+        payload = get_subscription_state(timeout=timeout)
+    except BillingAuthError:
+        return SubscriptionState(logged_in=False)
+    except BillingError as exc:
+        logger.debug("subscription ▸ /state fetch failed (fail-open)", exc_info=True)
+        return SubscriptionState(logged_in=False, error=str(exc))
+    except Exception:
+        logger.debug("subscription ▸ /state unexpected error (fail-open)", exc_info=True)
+        return SubscriptionState(logged_in=False, error="could not load subscription state")
+
+    raw_portal = payload.get("portalUrl") if isinstance(payload, dict) else None
+    portal_url = _absolutize_portal_url(raw_portal) if raw_portal else None
+    if not portal_url:
+        try:
+            portal_url = resolve_portal_base_url()
+        except Exception:
+            portal_url = None
+
+    return subscription_state_from_payload(payload, portal_url=portal_url)
+
+

hermes_cli/nous_billing.py

@@ -404,3 +404,15 @@ def get_charge_status(
     # guard against a stray slash that would change the path shape.
     safe_id = urllib.parse.quote(charge_id.strip(), safe="")
     return _request("GET", f"/api/billing/charge/{safe_id}", timeout=timeout)
+
+
+def get_subscription_state(*, timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """``GET /api/billing/subscription`` — current plan, tiers, usage (no scope).
+
+    Returns the raw JSON dict from NAS (WS1 Phase A). Read-only — no
+    ``billing:manage`` scope required. Raises :class:`BillingAuthError`
+    on 401 and :class:`BillingError` on other non-2xx.
+    """
+    return _request("GET", "/api/billing/subscription", timeout=timeout)
+
+

tui_gateway/server.py

@@ -5580,6 +5580,72 @@ def _(rid, params: dict) -> dict:
         return _ok(rid, {"ok": True, "logged_in": False, "error": "could not load billing state"})
 
 
+def _serialize_subscription_state(state) -> dict:
+    """Serialize a SubscriptionState for the wire (Decimals → strings)."""
+    from agent.billing_view import format_money
+
+    def _s(value):
+        return None if value is None else str(value)
+
+    current = None
+    if state.current is not None:
+        c = state.current
+        current = {
+            "tier_id": c.tier_id,
+            "tier_name": c.tier_name,
+            "monthly_credits": _s(c.monthly_credits),
+            "credits_remaining": _s(c.credits_remaining),
+            "cycle_ends_at": c.cycle_ends_at,
+            "pending_downgrade_tier_name": c.pending_downgrade_tier_name,
+            "pending_downgrade_at": c.pending_downgrade_at,
+            "is_past_due": c.is_past_due,
+            "cancel_at_period_end": c.cancel_at_period_end,
+            "cancellation_effective_at": c.cancellation_effective_at,
+        }
+    tiers = []
+    for t in state.tiers:
+        tiers.append({
+            "tier_id": t.tier_id,
+            "name": t.name,
+            "tier_order": t.tier_order,
+            "dollars_per_month_display": format_money(t.dollars_per_month),
+            "monthly_credits": _s(t.monthly_credits),
+            "is_current": t.is_current,
+            "is_enabled": t.is_enabled,
+        })
+    return {
+        "ok": True,
+        "logged_in": state.logged_in,
+        "is_admin": state.is_admin,
+        "can_change_plan": state.can_change_plan,
+        "org_name": state.org_name,
+        "org_id": state.org_id,
+        "role": state.role,
+        "context": state.context,
+        "current": current,
+        "tiers": tiers,
+        "portal_url": state.portal_url,
+        "error": state.error,
+    }
+
+
+@method("subscription.state")
+def _(rid, params: dict) -> dict:
+    """GET /api/billing/subscription → serialized SubscriptionState.
+
+    Fail-open like billing.state: logged-out / unreachable portal →
+    {ok:true, logged_in:false}. No scope required (read-only).
+    """
+    try:
+        from agent.subscription_view import build_subscription_state
+
+        state = build_subscription_state()
+        return _ok(rid, _serialize_subscription_state(state))
+    except Exception:
+        return _ok(rid, {"ok": True, "logged_in": False, "error": "could not load subscription state"})
+
+
+
 @method("billing.charge")
 def _(rid, params: dict) -> dict:
     """POST /api/billing/charge → {ok, chargeId} or a typed error envelope.

ui-tui/src/__tests__/subscriptionCommand.test.ts

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getOverlayState, resetOverlayState } from '../app/overlayStore.js'
+import { subscriptionCommands } from '../app/slash/commands/subscription.js'
+import { findSlashCommand } from '../app/slash/registry.js'
+import type { SubscriptionStateResponse } from '../gatewayTypes.js'
+
+vi.mock('../lib/openExternalUrl.js', () => ({
+  openExternalUrl: vi.fn(() => true)
+}))
+
+const subscriptionCommand = subscriptionCommands.find(cmd => cmd.name === 'subscription')!
+
+const loggedInState = (overrides: Partial<SubscriptionStateResponse> = {}): SubscriptionStateResponse => ({
+  ok: true,
+  logged_in: true,
+  is_admin: true,
+  can_change_plan: true,
+  org_name: 'Acme',
+  role: 'OWNER',
+  current: null,
+  tiers: [],
+  portal_url: 'https://portal.nousresearch.com/billing',
+  ...overrides
+})
+
+const guarded =
+  <T>(fn: (r: T) => void) =>
+  (r: null | T) => {
+    if (r) {
+      fn(r)
+    }
+  }
+
+/** Build a ctx whose rpc routes by method name to a supplied map of results. */
+const buildCtx = (results: Record<string, unknown>) => {
+  const sys = vi.fn()
+  const calls: Array<{ method: string; params: unknown }> = []
+
+  const rpc = vi.fn((method: string, params: unknown) => {
+    calls.push({ method, params })
+
+    return Promise.resolve(results[method])
+  })
+
+  const ctx = {
+    gateway: { rpc },
+    guarded,
+    guardedErr: vi.fn(),
+    sid: 'sid-1',
+    stale: () => false,
+    transcript: { page: vi.fn(), panel: vi.fn(), sys }
+  }
+
+  const run = async (arg: string) => {
+    subscriptionCommand.run(arg, ctx as any, 'subscription')
+    await rpc.mock.results[0]?.value
+    await Promise.resolve()
+    await Promise.resolve()
+  }
+
+  return { calls, ctx, rpc, run, sys }
+}
+
+const printed = (sys: ReturnType<typeof vi.fn>) => sys.mock.calls.map(c => c[0]).join('\n')
+
+describe('/subscription slash command', () => {
+  beforeEach(() => {
+    resetOverlayState()
+  })
+
+  it('fetches subscription.state and opens the overlay', async () => {
+    const { run } = buildCtx({
+      'subscription.state': loggedInState({ tiers: [{ tier_id: 'pro', name: 'Pro', tier_order: 1, dollars_per_month_display: '$20', monthly_credits: '1000', is_current: false, is_enabled: true }] })
+    })
+
+    await run('')
+
+    const overlay = getOverlayState().subscription
+
+    expect(overlay).not.toBeNull()
+    expect(overlay?.screen).toBe('overview')
+    expect(overlay?.state.tiers).toHaveLength(1)
+  })
+
+  it('shows portal-login sys line when not logged in', async () => {
+    const { run, sys } = buildCtx({
+      'subscription.state': loggedInState({ logged_in: false })
+    })
+
+    await run('')
+
+    expect(printed(sys)).toContain('Not logged into Nous Portal')
+    expect(getOverlayState().subscription).toBeNull()
+  })
+
+  it('/upgrade alias resolves to the same command', () => {
+    expect(findSlashCommand('upgrade')).toBe(subscriptionCommand)
+  })
+
+  it('/subscription resolves to the same command', () => {
+    expect(findSlashCommand('subscription')).toBe(subscriptionCommand)
+  })
+})