feat(billing): /credits command — balance + portal top-up handoff (#44776)

* feat(billing): /usage → portal top-up browser handoff Add the terminal side of the billing slice (phase 2a): start a top-up by throwing the user to the portal billing page with the top-up modal open. The terminal does not confirm, poll, or track payment — checkout completes in the browser and the next /usage shows the new balance. - nous_account.py: parse organisation.slug/name from /api/oauth/account into NousPortalAccountInfo; add nous_portal_topup_url() building the org-pinned {base}/orgs/{slug}/billing?topup=open with a null-slug fallback to the legacy {base}/billing?topup=open (never /orgs/None/...). - portal_cli.py: 'hermes portal topup' — fresh account fetch, identity line (Topping up as <email> / org <name>), browser open with printed-URL fallback, no-wait closing copy. No polling/confirmation (deferred to 2b). - account_usage.py: the shared /usage credits block now links the org-pinned top-up URL (auto-opens the modal) + points to the command. Depends on NAS #409 (organisation.slug/name + ?topup=open). Do not merge until that is live on the target env; until then /api/oauth/account returns organisation: { id } only and the URL falls back to legacy. * feat(billing): /credits command for balance + top-up handoff Replace the standalone `hermes portal topup` subcommand with an in-session /credits slash command — a focused money surface (balance in, top-up out) that works in the CLI, TUI, and every messaging platform from one registry entry. - commands.py: register /credits (Info category). Slack is at its 50-slash cap, so /credits is routed via /hermes credits on Slack only (new _SLACK_VIA_HERMES_ONLY set) to avoid clamping a canonical command off the native list and breaking Telegram parity; native everywhere else. - account_usage.py: build_credits_view() — one portal fetch → balance lines + identity line + org-pinned top-up URL + depleted flag, consumed by all surfaces. Reuses the same snapshot/URL builder as /usage so numbers match. - cli.py: _show_credits() — balance block + identity line + 3-button panel (Open top-up / Copy link / Cancel) via the existing prompt_toolkit modal. ASK, never auto-launch; headless falls back to printing the URL. - gateway/slash_commands.py: _handle_credits_command() — renders the block + tappable top-up URL + no-wait copy; works on button and plain-text platforms. - /usage credits line now points to /credits. - Retire `hermes portal topup` (portal_cli.py back to baseline); the engine (slug/name parse + nous_portal_topup_url) stays as the shared core. No polling, no payment confirmation (billing phase 2a). Depends on NAS #409. * fix(credits): /credits works in the TUI slash-worker (non-interactive) In the TUI, /credits runs in the slash-worker subprocess where there is no live prompt_toolkit app and stdin is the JSON-RPC pipe. _show_credits called the 3-button modal unconditionally, which fell back to reading stdin → exception → slash.exec rejected → the command produced no output (only the pre-existing 'Credit access paused' banner showed). - _show_credits: when self._app is None (TUI worker / piped / non-interactive), render the text variant — balance block + tappable top-up URL + no-wait line, same affordance as the messaging surfaces — and skip the modal entirely. The 3-button panel still renders in the interactive CLI. - Depleted banner copy: 'run /usage for balance' → 'run /credits to top up' now that /credits is the dedicated money surface (+ tests). - Regression tests: _show_credits with self._app=None renders text and never invokes the modal; logged-out path. * feat(tui): credits.view RPC for the /credits tappable top-up button Add a credits.view JSON-RPC method returning the structured CreditsView (logged_in, balance_lines, identity_line, topup_url, depleted) so the TUI can render a clickable <Link> top-up button instead of plain text. Account- independent (portal fetch gated on a logged-in Nous account), fail-open to {logged_in: false} on any hiccup. Mirrors session.usage's credits-block pattern. Frontend (TUI-local /credits command + Ink component) lands separately. * feat(tui): /credits command with keyboard-driven top-up confirm TUI-local /credits: fetches the structured balance via the credits.view RPC, prints the balance + identity + top-up URL, then arms the EXISTING confirm overlay (Enter = open top-up in browser via openExternalUrl, Esc = cancel). Reuses ConfirmReq — no new overlay component/state/input handler. Headless (openExternalUrl returns false) falls back to printing the URL. - gatewayTypes.ts: CreditsViewResponse. - commands/credits.ts: the command (mirrors /status's rpc+guarded pattern). - registry.ts: register creditsCommands. - test: balance+overlay armed, headless fallback, no-url, logged-out (4 cases). Matches the CLI /credits 'Enter to open' affordance. Phase 2a: no polling.
2026-06-12 08:51:10 +00:00
parent 4474873d2c
commit 7ba5df0d52
36 changed files with 944 additions and 172 deletions
@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { creditsCommands } from '../app/slash/commands/credits.js'
+import { getOverlayState, resetOverlayState } from '../app/overlayStore.js'
+import type { CreditsViewResponse } from '../gatewayTypes.js'
+
+// The command opens the top-up URL through this helper on confirm. Mock it so
+// the test never shells out to a real browser/`xdg-open` and we can assert the
+// success/failure messaging deterministically.
+vi.mock('../lib/openExternalUrl.js', () => ({
+  openExternalUrl: vi.fn(() => true)
+}))
+
+import { openExternalUrl } from '../lib/openExternalUrl.js'
+
+const openExternalUrlMock = vi.mocked(openExternalUrl)
+
+const creditsCommand = creditsCommands.find(cmd => cmd.name === 'credits')!
+
+const buildView = (overrides: Partial<CreditsViewResponse> = {}): CreditsViewResponse => ({
+  balance_lines: ['Grant: $9.50 left', 'Top-up: $25.00'],
+  depleted: false,
+  identity_line: 'Signed in as ada@example.com',
+  logged_in: true,
+  topup_url: 'https://portal.nousresearch.com/billing/topup',
+  ...overrides
+})
+
+// Mirror createSlashHandler's real `guarded` wrapper: skip the handler when the
+// command is stale OR the response is falsy. Tests stay non-stale, so this is a
+// straightforward "run the handler when we got a response" shim.
+const guarded =
+  <T,>(fn: (r: T) => void) =>
+  (r: null | T) => {
+    if (r) {
+      fn(r)
+    }
+  }
+
+const buildCtx = (rpcResult: CreditsViewResponse) => {
+  const sys = vi.fn()
+  const rpc = vi.fn(() => Promise.resolve(rpcResult))
+  const guardedErr = vi.fn()
+
+  const ctx = {
+    gateway: { rpc },
+    guarded,
+    guardedErr,
+    sid: 'sid-abc',
+    stale: () => false,
+    transcript: { page: vi.fn(), panel: vi.fn(), sys }
+  }
+
+  // Run the command, then await the rpc promise so the .then() handler has
+  // flushed before assertions — deterministic, no polling/timeouts.
+  const run = async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    creditsCommand.run('', ctx as any, 'credits')
+    await rpc.mock.results[0]?.value
+    // Allow the chained .then() microtask to settle.
+    await Promise.resolve()
+  }
+
+  return { ctx, rpc, run, sys }
+}
+
+describe('/credits slash command', () => {
+  beforeEach(() => {
+    resetOverlayState()
+    openExternalUrlMock.mockClear()
+    openExternalUrlMock.mockReturnValue(true)
+  })
+
+  it('renders the balance (including top-up URL) and arms the confirm overlay', async () => {
+    const view = buildView()
+    const { rpc, run, sys } = buildCtx(view)
+
+    await run()
+
+    expect(rpc).toHaveBeenCalledWith('credits.view', { session_id: 'sid-abc' })
+
+    // (a) sys received the balance text including the topup_url
+    const printed = sys.mock.calls.map(call => call[0]).join('\n')
+    expect(printed).toContain('💳 Nous credits')
+    expect(printed).toContain('Grant: $9.50 left')
+    expect(printed).toContain('Signed in as ada@example.com')
+    expect(printed).toContain(view.topup_url)
+
+    // (b) confirm overlay set with the expected label + detail
+    const confirm = getOverlayState().confirm
+    expect(confirm).toBeTruthy()
+    expect(confirm?.confirmLabel).toBe('Open top-up in browser')
+    expect(confirm?.cancelLabel).toBe('Cancel')
+    expect(confirm?.title).toBe('Add credits?')
+    expect(confirm?.detail).toBe(view.topup_url)
+
+    // onConfirm opens the URL and reports success back to the transcript
+    confirm?.onConfirm()
+    expect(openExternalUrlMock).toHaveBeenCalledWith(view.topup_url)
+    expect(sys).toHaveBeenCalledWith(
+      'Complete your top-up in the browser — credits will appear in /credits shortly.'
+    )
+  })
+
+  it('falls back to printing the URL when the browser open is rejected', async () => {
+    openExternalUrlMock.mockReturnValue(false)
+    const view = buildView()
+    const { run, sys } = buildCtx(view)
+
+    await run()
+
+    const confirm = getOverlayState().confirm
+    expect(confirm).toBeTruthy()
+    confirm?.onConfirm()
+    expect(sys).toHaveBeenCalledWith(`Open this URL to top up: ${view.topup_url}`)
+  })
+
+  it('does not arm the confirm overlay when there is no top-up URL', async () => {
+    const view = buildView({ topup_url: null })
+    const { run, sys } = buildCtx(view)
+
+    await run()
+
+    const printed = sys.mock.calls.map(call => call[0]).join('\n')
+    expect(printed).toContain('💳 Nous credits')
+    expect(getOverlayState().confirm).toBeNull()
+  })
+
+  it('shows the not-logged-in message and does NOT arm the confirm overlay', async () => {
+    const view = buildView({
+      balance_lines: [],
+      identity_line: null,
+      logged_in: false,
+      topup_url: null
+    })
+    const { run, sys } = buildCtx(view)
+
+    await run()
+
+    expect(sys).toHaveBeenCalledWith('💳 Not logged into Nous Portal — run /portal to log in.')
+    expect(getOverlayState().confirm).toBeNull()
+    expect(openExternalUrlMock).not.toHaveBeenCalled()
+  })
+})
@@ -35,7 +35,7 @@ describe('turnController.startMessage — flash-and-yield notices clear on next

  it('leaves a sticky credits.depleted notice across a new turn', () => {
    patchUiState({
-      notice: { key: 'credits.depleted', kind: 'sticky', level: 'error', text: '✕ Credit access paused · run /usage for balance' }
+      notice: { key: 'credits.depleted', kind: 'sticky', level: 'error', text: '✕ Credit access paused · run /credits to top up' }
    })
    turnController.startMessage()
    expect(getUiState().notice?.key).toBe('credits.depleted')
@@ -0,0 +1,57 @@
+import type { CreditsViewResponse } from '../../../gatewayTypes.js'
+import { openExternalUrl } from '../../../lib/openExternalUrl.js'
+import { patchOverlayState } from '../../overlayStore.js'
+import type { SlashCommand } from '../types.js'
+
+export const creditsCommands: SlashCommand[] = [
+  {
+    help: 'Show Nous credit balance and top up',
+    name: 'credits',
+    run: (_arg, ctx) => {
+      ctx.gateway
+        .rpc<CreditsViewResponse>('credits.view', { session_id: ctx.sid })
+        .then(
+          ctx.guarded<CreditsViewResponse>(view => {
+            if (!view.logged_in) {
+              ctx.transcript.sys('💳 Not logged into Nous Portal — run /portal to log in.')
+              return
+            }
+
+            const lines = ['💳 Nous credits', ...view.balance_lines]
+
+            if (view.identity_line) {
+              lines.push('', view.identity_line)
+            }
+
+            if (view.topup_url) {
+              lines.push('', `Top up: ${view.topup_url}`)
+            }
+
+            ctx.transcript.sys(lines.join('\n'))
+
+            const url = view.topup_url
+
+            if (url) {
+              patchOverlayState({
+                confirm: {
+                  cancelLabel: 'Cancel',
+                  confirmLabel: 'Open top-up in browser',
+                  detail: url,
+                  onConfirm: () => {
+                    const ok = openExternalUrl(url)
+                    ctx.transcript.sys(
+                      ok
+                        ? 'Complete your top-up in the browser — credits will appear in /credits shortly.'
+                        : `Open this URL to top up: ${url}`
+                    )
+                  },
+                  title: 'Add credits?'
+                }
+              })
+            }
+          })
+        )
+        .catch(ctx.guardedErr)
+    }
+  }
+]
@@ -1,4 +1,5 @@
 import { coreCommands } from './commands/core.js'
+import { creditsCommands } from './commands/credits.js'
 import { debugCommands } from './commands/debug.js'
 import { opsCommands } from './commands/ops.js'
 import { sessionCommands } from './commands/session.js'
@@ -7,6 +8,7 @@ import type { SlashCommand } from './types.js'

 export const SLASH_COMMANDS: SlashCommand[] = [
  ...coreCommands,
+  ...creditsCommands,
  ...sessionCommands,
  ...opsCommands,
  ...setupCommands,
@@ -43,6 +43,16 @@ export interface SlashExecResponse {
  warning?: string
 }

+// ── Credits / top-up ─────────────────────────────────────────────────
+
+export interface CreditsViewResponse {
+  balance_lines: string[]
+  depleted: boolean
+  identity_line: string | null
+  logged_in: boolean
+  topup_url: string | null
+}
+
 export type CommandDispatchResponse =
  | { output?: string; type: 'exec' | 'plugin' }
  | { target: string; type: 'alias' }