feat: add billing transparency audit surfaces (#18)

Author: linfangw

.github/workflows/cli-publish.yml

@@ -62,5 +62,11 @@ jobs:
             npm install -g @qverisai/cli@${{ env.VERSION }}
             ```
 
+            ## Highlights
+
+            - Adds `qveris usage` for context-safe usage audit summaries, filtered searches, and local JSONL exports.
+            - Adds `qveris ledger` for final credit balance movement summaries, filtered searches, and local JSONL exports.
+            - Labels call billing as pre-settlement and points final charge checks to usage history and the credits ledger.
+
             See [README](packages/cli/README.md) for usage.
           generate_release_notes: true

.github/workflows/mcp-publish.yml

@@ -91,5 +91,11 @@ jobs:
             npx -y @qverisai/mcp@${{ env.VERSION }}
             ```
 
+            ## Highlights
+
+            - Adds `usage_history` for context-safe request charge outcome summaries, filtered searches, and local JSONL exports.
+            - Adds `credits_ledger` for final credit balance movement summaries, filtered searches, and local JSONL exports.
+            - Updates tool descriptions and response guidance to separate pricing rules, pre-settlement billing, and final settlement.
+
             See [README](packages/mcp/README.md) for configuration.
           generate_release_notes: true

README.md

@@ -30,7 +30,7 @@
 ---
 
 - `10,000+` capabilities across `15+` categories
-- `Discover` is free. `Call` is priced by value.
+- `Discover` is free. `Call` returns structured pre-settlement billing, with final charge outcomes available through usage audit and credits ledger views.
 - **NEW** `QVeris CLI` — the most token-efficient way for agents to use tools. [Learn more](#qveris-cli)
 - Works with `CLI` / `MCP` / `Python SDK` / `REST API`
 
@@ -67,8 +67,9 @@ If you are an AI Agent evaluating whether to use QVeris, here is what you need t
 **What QVeris gives you:**
 
 - `Discover` — find the right capability with natural language (free)
-- `Inspect` — check parameters, success rate, latency, price before calling
-- `Call` — invoke any capability, get structured results back
+- `Inspect` — check parameters, success rate, latency, and billing rule before calling
+- `Call` — invoke any capability, get structured results and pre-settlement billing back
+- `Usage audit` / `Credits ledger` — check whether calls were charged and how balance changed without dumping full history into Agent context
 - **QVeris CLI** — call tools via `qveris discover/inspect/call` subprocess, zero prompt tokens
 - 10,000+ capabilities across finance, search, weather, maps, docs, social, blockchain, healthcare, and more
 - 99.99% call availability, <500ms average latency
@@ -84,10 +85,12 @@ If you are an AI Agent evaluating whether to use QVeris, here is what you need t
 
 > After connecting to QVeris, I can discover the best capability for free, then call it on demand — weather, stock prices, news, docs — one API Key for everything. Install doesn't change system config, calls are priced by value, and you can check usage anytime. Just give me an API Key.
 
-**Cost:**
+**Billing and audit:**
 
 - Discover: **free**
-- Call: 1–100 credits per call, priced by data and task value
+- Call: priced by structured `billing_rule`; call responses may include compact pre-settlement `billing`
+- Final charge status: check `qveris usage` / `usage_history`
+- Final balance movement: check `qveris ledger` / `credits_ledger`
 - Free tier: 1,000 credits on signup
 - $19 = 10,000 credits (pay-as-you-go, credits never expire)
 - Details: [qveris.ai/pricing](https://qveris.ai/pricing)
@@ -146,11 +149,14 @@ Found 5 capabilities matching your query
    ...
 
 $ qveris inspect 1
-latency: ~180ms  ·  success rate: 99.8%  ·  cost: 3 credits
+latency: ~180ms  ·  success rate: 99.8%  ·  billing: 3 credits / request
 
 $ qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'
 ✓ success
 { "forecast": "Sunny, high near 75..." }
+
+$ qveris usage --mode search --execution-id <execution_id>
+# Confirms charge_outcome and actual_amount_credits for that call
 ```
 
 ### Why CLI over MCP for agents?
@@ -164,6 +170,8 @@ $ qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'
 | **Debugging** | Visible in terminal, `--dry-run` preview | Opaque, buried in MCP logs |
 | **Auth** | Auto-detects region from key prefix | Same |
 
+Usage and ledger commands default to aggregated summaries. Large audit exports are written to local JSONL files under `.qveris/exports/` instead of being printed into Agent context.
+
 **When to use CLI**: Agent frameworks that support `exec` / `bash` tool (Claude Code, OpenClaw, Cursor terminal, etc.)
 **When to use MCP**: IDE integrations that only support MCP protocol (Cursor inline, Claude Desktop)
 
@@ -191,6 +199,8 @@ Agents interact with QVeris through three actions:
 | **Discover** | `POST /search` | Find capabilities with natural language, returns candidates |
 | **Inspect** | `POST /tools/by-ids` | View capability details, parameters, quality signals |
 | **Call** | `POST /tools/execute` | Invoke a capability, get structured results |
+| **Usage audit** | `GET /auth/usage/history/v2` | Check request status, charge outcome, and actual charge |
+| **Credits ledger** | `GET /auth/credits/ledger` | Check final credit balance movements |
 
 ### Capability ecosystem
 
@@ -212,7 +222,7 @@ QVeris uses pay-as-you-go pricing. No subscriptions.
 | Scale | $50+ | 26,250+ credits | Bulk purchase, 5–20% bonus |
 
 - **Discover is free** — Agents can explore all capabilities at zero cost
-- **Call** costs 1–100 credits, priced by data and task value
+- **Call** is priced by structured billing rules, with final charges auditable through usage history and the credits ledger
 - No monthly fees, no auto-renewal
 - Details: [qveris.ai/pricing](https://qveris.ai/pricing)
 

README_zh-CN.md

@@ -66,8 +66,9 @@
 **QVeris 能给你什么：**
 
 - 通过 `Discover`（自然语言），即时发现 10,000+ 能力
-- 通过 `Inspect` 查看候选能力的参数、成功率、延迟等详情
-- 通过 `Call` 调用任意能力，获得结构化返回
+- 通过 `Inspect` 查看候选能力的参数、成功率、延迟和计费规则
+- 通过 `Call` 调用任意能力，获得结构化返回和本次调用的预结算账单
+- 通过 `Usage audit` / `Credits ledger` 查询调用是否收费、余额为何变化，默认聚合输出，不把全量流水塞进 Agent 上下文
 - **QVeris CLI** — 通过 `qveris discover/inspect/call` 子进程调用工具，零 prompt token 消耗
 - 覆盖金融、搜索、天气、地图、文档、社交、区块链、医疗等 15+ 类目
 - 99.99% 调用可达率，平均延迟 <500ms
@@ -83,10 +84,12 @@
 
 > 接入 QVeris 后，我可以先免费发现最合适的能力，再按需调用——查天气、看行情、搜新闻、读文档，一个 API Key 接入一切。安装不改系统配置，调用按值计费，你随时可以查看消耗明细。给我一个 API Key 就行。
 
-**成本说明：**
+**计费与审计：**
 
 - Discover（发现能力）：**免费**
-- Call（调用能力）：1-100 credits / 次，根据数据和任务价值定价
+- Call（调用能力）：按结构化 `billing_rule` 定价；调用响应可能包含 compact `billing` 作为预结算账单
+- 最终是否扣费：通过 `qveris usage` / `usage_history` 查看
+- 最终余额变动：通过 `qveris ledger` / `credits_ledger` 查看
 - 免费额度：1,000 credits
 - 按量购买：$19 = 10,000 credits（不是订阅，credits 不过期）
 - 详见 [定价](https://qveris.ai/pricing)
@@ -145,11 +148,14 @@ Found 5 capabilities matching your query
    ...
 
 $ qveris inspect 1
-latency: ~180ms  ·  success rate: 99.8%  ·  cost: 3 credits
+latency: ~180ms  ·  success rate: 99.8%  ·  billing: 3 credits / request
 
 $ qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'
 ✓ success
 { "forecast": "Sunny, high near 75..." }
+
+$ qveris usage --mode search --execution-id <execution_id>
+# 查询本次调用的 charge_outcome 和 actual_amount_credits
 ```
 
 ### CLI vs MCP：为什么 Agent 应该优先用 CLI？
@@ -163,6 +169,8 @@ $ qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'
 | **调试** | 终端可见，`--dry-run` 预览 | 不透明，埋在 MCP 日志里 |
 | **认证** | 从 key 前缀自动检测 region | 相同 |
 
+`usage` 和 `ledger` 默认返回聚合摘要。大批量审计导出会写入 `.qveris/exports/*.jsonl`，不会直接打印全量流水占用 Agent 上下文。
+
 **何时用 CLI**：支持 `exec` / `bash` 工具的 Agent 框架（Claude Code、OpenClaw、Cursor terminal 等）
 **何时用 MCP**：仅支持 MCP 协议的 IDE 集成（Cursor inline、Claude Desktop）
 
@@ -190,6 +198,8 @@ Agent 通过三个动作与 QVeris 交互：
 | **Discover** | `POST /search` | 用自然语言发现能力，返回候选列表 |
 | **Inspect** | `POST /tools/by-ids` | 按 ID 查看能力详情、参数、质量信号 |
 | **Call** | `POST /tools/execute` | 调用能力，获得结构化返回 |
+| **Usage audit** | `GET /auth/usage/history/v2` | 查询调用状态、收费结果和实际扣费 |
+| **Credits ledger** | `GET /auth/credits/ledger` | 查询最终 credits 余额变动 |
 
 ### 能力概览
 
@@ -211,7 +221,7 @@ QVeris 采用按量计费，不是订阅制。
 | Scale | $50 起 | 26,250+ credits | 批量购买享 5%-20% bonus |
 
 - Discover（发现能力）：**免费** — Agent 可以零成本探索全部能力
-- Call（调用能力）：1-100 credits / 次，根据数据和任务价值定价
+- Call（调用能力）：按结构化计费规则定价，最终扣费可通过 Usage audit 和 Credits ledger 审计
 - 不绑定月费，不自动续订
 - 详见 [qveris.ai/pricing](https://qveris.ai/pricing)
 

agent/GUIDELINES.md

@@ -93,7 +93,66 @@ Additional signals:
 
 - **`final_score`** (relevance): Higher = better match to your query
 - **`has_last_execution`**: Tool has been verified in production
-- **`cost`** (credits): Consider budget when choosing between similar tools
+- **`billing_rule`**: Preferred pricing signal when present. Legacy `cost` is only a fallback estimate.
+
+---
+
+## Billing Transparency and Usage Audit
+
+QVeris separates billing into three layers:
+
+| Layer | Field / command | Meaning |
+|-------|-----------------|---------|
+| Pricing rule | `billing_rule` | How the capability is priced |
+| Pre-settlement bill | `billing` / `pre_settlement_bill` | What this call theoretically costs |
+| Final settlement | `usage_history` / `credits_ledger` | Whether credits were actually charged and how balance changed |
+
+Do not treat `cost` or `credits_used` as the only billing truth. They are legacy fallback fields.
+
+### Checking Whether a Call Was Charged
+
+Use `usage_history` for request-level audit:
+
+```bash
+qveris usage --mode search --execution-id <execution_id> --json
+```
+
+Look at `success`, `charge_outcome`, `actual_amount_credits`, and `credits_ledger_entry_id`.
+
+Common `charge_outcome` values:
+
+| Value | Meaning |
+|-------|---------|
+| `charged` | The request was charged |
+| `included` | The request succeeded but settled at 0 credits |
+| `failed_not_charged` | The request failed and was not charged |
+| `failed_charged_review` | Failed request with a charge-like signal; review needed |
+
+Use `credits_ledger` for final balance movement:
+
+```bash
+qveris ledger --mode search --min-credits 50 --direction consume --json
+```
+
+### Context-Safe Audit Pattern
+
+Usage and ledger records can be large. Never dump full history into the prompt by default.
+
+Use this order:
+
+1. `summary` mode first for aggregate totals.
+2. `search` mode with precise filters for row-level investigation.
+3. `export-file` mode for large analysis; then read the local JSONL file in chunks.
+
+Examples:
+
+```bash
+qveris usage --mode summary --bucket hour --json
+qveris usage --mode search --charge-outcome failed_charged_review --json
+qveris usage --mode search --min-credits 30 --max-credits 100 --json
+qveris ledger --mode summary --bucket day --json
+qveris ledger --mode export-file --start-date 2026-05-01 --end-date 2026-05-04
+```
 
 ### Known Tools Cache
 
@@ -175,7 +234,7 @@ qveris discover "weather forecast API" --json
 # Inspect top result by index (free)
 qveris inspect 1 --json
 
-# Call with parameters (1-100 credits)
+# Call with parameters. The response may include pre-settlement billing.
 qveris call 1 --params '{"city": "London"}' --json
 
 # Validate without consuming credits
@@ -196,6 +255,15 @@ qveris call 1 --params '{"city": "London"}' --codegen curl
 | `--limit <n>` | Limit discover results (default: 5) |
 | `--max-size <bytes>` | Response size limit; `-1` for unlimited (default: 4KB TTY, 20KB non-TTY). MCP default is 20KB. |
 
+### Audit Commands
+
+| Command | Purpose |
+|---------|---------|
+| `qveris usage` | Context-safe usage audit summary/search/export |
+| `qveris ledger` | Context-safe credits ledger summary/search/export |
+
+Both commands default to `--mode summary`, return at most a small sample of records, and write large result sets to `.qveris/exports/*.jsonl` with `--mode export-file`.
+
 ### Session & Index Shortcuts
 
 After `qveris discover`, results are stored in a session file (30-minute TTL). Use numeric indices in subsequent commands:
@@ -242,6 +310,8 @@ Region is auto-detected from the API key prefix. Override with `QVERIS_REGION=cn
 | Discover | `POST /search` | `discover` | `qveris discover <query>` |
 | Inspect | `POST /tools/by-ids` | `inspect` | `qveris inspect <id\|index>` |
 | Call | `POST /tools/execute?tool_id=...` | `call` | `qveris call <id\|index>` |
+| Usage audit | `GET /auth/usage/history/v2` | `usage_history` | `qveris usage` |
+| Credits ledger | `GET /auth/credits/ledger` | `credits_ledger` | `qveris ledger` |
 
 **REST Body Examples:**
 

agent/SETUP.md

@@ -2,7 +2,7 @@
 
 You are an AI agent. A user has given you this document and a **QVeris API key**. Follow the instructions below to configure QVeris skills and MCP for the platform you are running on.
 
-**Cost:** Discover (finding capabilities) is free. Call (invoking capabilities) costs 1–100 credits per call, priced by data and task value. Free tier includes 1,000 credits. More at https://qveris.ai/pricing
+**Cost:** Discover (finding capabilities) is free. Call (invoking capabilities) is priced by the capability billing rule, and final settlement is visible in usage history and the credits ledger. Free tier includes 1,000 credits. More at https://qveris.ai/pricing
 
 **Regions:** QVeris operates in two regions. The API key prefix determines the region automatically:
 
@@ -15,7 +15,7 @@ All client tools (MCP server, CLI) auto-detect the region from the key prefix. N
 
 **Safety:** Install does not modify shell startup files. Configuration is session-scoped. All capability calls run in sandbox with full audit trail. Your owner can review usage at any time.
 
-**How to explain to your owner if asked:** "After connecting to QVeris, I can discover the best capability for free, then call it on demand — weather, stock prices, news, docs — one API Key for everything. Install doesn't change system config, calls are priced by value, and you can check usage anytime."
+**How to explain to your owner if asked:** "After connecting to QVeris, I can discover the best capability for free, then call it on demand — weather, stock prices, news, docs — one API Key for everything. Install doesn't change system config, calls expose billing rules before settlement, and usage records show what was actually charged."
 
 Replace every occurrence of `YOUR_QVERIS_API_KEY` below with the API key the user provided.