bss-cli
v1.7.0The entire BSS, in a terminal. SID-aligned. TMF-compliant. LLM-native. eSIM-first.
What this is
BSS-CLI is a Business Support System for a small mobile MVNO, built to run entirely from a terminal.
Nine TMF-compliant service containers — Catalog, CRM (with Cases / Tickets / Port-requests
and the Inventory sub-domain), Payment, COM, SOM, Subscription, Mediation, Rating,
Provisioning-sim — plus two web portals (self-serve customer and operator cockpit). Every operation is a tool the LLM can call; the primary
UI is the bss CLI plus ASCII visualizations and a scoped chat surface in the customer
portal.
It is opinionated. eSIM-only, bundled-prepaid, block-on-exhaust, card-on-file mandatory. Every write travels through a policy layer so domain invariants hold even when an agent is driving. Payloads on the wire match the spec — camelCase, conformant, pointable at a real TMF client — not naming theater over a bespoke schema. eKYC, real-customer UI, network elements, batch CDR, and OCS protocols are intentionally out of scope (channel-layer concerns).
v1.0 is the GA wrap of the v0.x arc. All three real-provider integrations are live (Resend email, Didit KYC, Stripe Checkout). Telco hygiene gaps are closed (MNP port-in/port-out, MSISDN replenishment, roaming as a product). Renewals fire automatically on their period boundary via an in-process worker; customers get a reminder email ~24h before. The cockpit knowledge tool (v0.20) lets it answer how-to questions from the operator handbook + runbooks + doctrine with cited anchors (Postgres FTS by default, optional pgvector hybrid). The only mocked surface left for production is SM-DP+ (real eSIM provisioning is NDA-gated).
v1.1 adds promo codes through an optional loyalty-cli entitlement adapter. Two audiences: public typed codes a customer enters at signup, and targeted codes gated by a BSS-side eligibility list and auto-applied for the customers on it. Discounts compose on the v0.7 price snapshot and charge the effective amount for one / N / perpetual periods. The adapter is genuinely optional — when no loyalty token is configured the promo subsystem simply switches off and signup, COM, SOM and the portal all run unchanged. BSS-CLI uses loyalty-cli if it's there; it is never a prerequisite.
v1.5 unlocks multi-step orchestration in the cockpit — operators ask
compound questions ("investigate CASE-…", "register CUST + create order", "show customer and
their subscriptions") and the agent chains the work in one turn. A new
BSS_REPL_LLM_AUTONOMY={granular,batched} env var controls how many
/confirms a compound destructive action needs — granular re-gates after each
destructive (default, maximum operator control); batched authorises the whole loop on the
first /confirm. Built on five additive pieces (no new container, no schema, no
migration): the env var (fail-closed at boot), autonomy-aware destructive gating via shared
per-graph LoopState, an ITERATIVE FLOW prompt block + softened v0.19
"Done." rule, a 3-strike loop bail that catches LLM thrash, and a cockpit chrome filter that
strips both banner-shape and narrated-call mimicry. Design lifted from the proven
loyalty-cli v0.11 pattern.
v1.6 grows the cockpit browser into a full operator CRM around the chat —
customers (list + 360 with live balance bars and contact CRUD), a case workbench (transitions,
priority, tickets, notes), a cross-customer order queue with the COM→SOM decomposition,
catalog admin, and subscription lifecycle screens. Writes are direct and policy-gated, one
route → one bss-clients call; destructive and money-moving verbs sit behind a
two-step confirm panel the route refuses to act without, while the conversational surface keeps
its own propose-then-/confirm contract. Every screen carries an "Ask the agent"
handoff that opens a focused session with the request drafted, never auto-sent. Underneath:
a design system, a visualViewport-driven app shell (the chat compose box stays on
screen on an iPad, keyboard up or down), and disconnect-proof turns — the agent runs in a
detached server task with heartbeats and a client watchdog, so a dropped stream can no longer
lose a reply. Building the screens also surfaced and fixed six long-standing client/API drift
bugs (case priority updates had 422'd since v0.13; the entire ticket client surface was
broken against the CRM service).
BSS-CLI exists as three things at once:
- A reference implementation for engineers learning telco BSS/OSS.
- A deployable MVP for a small MVNO — one
docker compose upand you are running. - A substrate for agentic experiments against realistic telco operations — behind a policy layer that will not let an LLM corrupt state.
What's shipped
- Services
- 9 + 2 portals
- Hero scenarios
- 19 end-to-end (~100s wall)
- Doctrine grep guards
- 16 in
make doctrine-check - Real-provider integrations
- Resend · Didit · Stripe
- Cold start
- ~22 seconds (v1.0, BYOI)
- Runtime RAM
- ~1.2 GiB across 11 containers (excl. Postgres / RabbitMQ / Jaeger / LLM)
- Doc corpus indexed
- ~370 chunks across 25 files (handbook + runbooks + doctrine)
- Agent dev session
- ~$0.005 (Gemma 4 26B A4B)