Agent Billing Pack v1.0

An autonomous billing agent you deploy on a Debian VM in one command. It runs a reliable deterministic core out of the box, and gets smart when you connect your existing coding-agent subscription - Claude Code, Kimi Code, or Codex - with no API key.

Architecture

-----------------------------------------------------------------------------
|                        AGENT BILLING v1.0                                  |
|----------------------------------------------------------------------------|
|  +-------------+   +-------------+   +-------------+   +----------+       |
|  |  Producer   |-->|   Queue     |-->| Dispatcher  |-->| Executor |       |
|  | (cron/CLI)  |   |  (SQLite)   |   | (OODA loop) |   | (LLM/.)  |       |
|  +-------------+   +------+------+   +-------------+   +-----+----+       |
|                           |                                  |             |
|                    +------+------+                    +------+-----+       |
|                    | Dead Letter |<-------------------|   Retry    |       |
|                    |   Queue     |   (max 3 attempts) |  Policy    |       |
|                    +------+------+                    +----------+       |
|                           ^                                              |
|                           |                                              |
|  +---------------------------------------------------------------------+  |
|  |                         Monitor                                      |  |
|  |  (queue depth / dead-letter / overdue invoices / backpressure)      |  |
|  +---------------------------------------------------------------------+  |
-----------------------------------------------------------------------------

• Producer : cron, CLI (agent.py enqueue), ou API externe
• Queue : SQLite locale par defaut, zero-config, zero-deps
• Dispatcher : boucle OODA - observe, oriente, decide, agit
• Executor : mode deterministe (.) par defaut, mode LLM si CLI connectee
• Retry Policy : backoff exponentiel 10s -> 60s -> 600s
• Dead Letter : taches en echec conservees, replayables
• Monitor : sondes integrees, alertes configurables

One-shot install (Debian/Ubuntu)

unzip agent-billing-v1.zip && cd agent-billing-v1
sudo bash install.sh          # system deps + venv + systemd service (enabled)

That's it. The agent starts as a systemd service (agent-billing-v1), survives reboots, and restarts on failure. Logs: journalctl -u agent-billing-v1 -f.

No root / no systemd? bash install.sh --no-service sets up the venv, then run venv/bin/python agent.py run.

Connect your LLM (optional, no API key)

install.sh auto-detects the first CLI it finds. Install & log in to one:

Force a specific one with PACK_LLM=claude|kimi|codex. If none is connected, the agent still runs - see the honesty table below.

What's LLM vs deterministic (honest by design)

If a CLI is installed but not logged in, the agent logs a warning and falls back to the deterministic handler for that task - it never gets stuck.

Business-state integrity (no hallucinated invoices)

The LLM reasons, but business ids come from the system, never from the model. A real invoice_id may only come from (a) your input data, (b) a deterministic generator, or (c) the billing system's response after a real creation. The agent enforces this on every LLM output before a task can complete (validate_no_fabricated_invoice_ids in agent.py):

• An invoice you plan to create is emitted with invoice_id: null ("to_be_generated") — never an invented INV-2026-0004.
• A payment without a real invoice_id is never invoice_marked_paid; it is parked as awaiting_invoice_creation / candidate_match_pending_creation / manual_review / ignored_duplicate.
• Reconciling a payment to an invoice is a separate step that runs only after the invoice has really been created and its id returned.
• Any output that invents an id, or marks paid a non-existing invoice, is rejected: the task fails and goes to the dead-letter / human-review channel. Nothing fabricated is ever silently accepted.

Correct cycle: plan invoice → create it via the deterministic system/API → get the real invoice_id back → reconcile the payment → log the result.

The reconcile_billing task does this deterministically (no LLM needed):

python agent.py enqueue --type reconcile_billing --payload '{
  "existing_invoices":[{"invoice_id":"INV-2026-0003","customer":"Acme","amount":1200}],
  "invoices_to_create":[{"customer":"Globex","amount":900}],
  "payments":[{"customer":"Globex","amount":900,"status":"settled"}]
}'

Quick commands

python agent.py status
python agent.py enqueue --type generate_invoice --payload '{"customer":"Acme","amount":1200,"due_date":"2026-06-30"}'
python agent.py enqueue --type send_reminder --payload '{"customer":"Acme","invoice_id":"INV-001"}'
python agent.py enqueue --type record_payment --payload '{"customer":"Acme","invoice_id":"INV-001","amount_paid":1200}'
python agent.py enqueue --type cleanup --idempotency-key nightly-2026-06-07
python agent.py run --once                   # one OODA cycle
python agent.py run --deterministic          # force the no-LLM core
python agent.py replay --task t-ab12cd34     # requeue a dead/blocked task
bash smoke_test.sh                           # offline test suite (no keys)
python EXAMPLE.py                            # runnable end-to-end demo

Contents