Model services and plan billing
Core 0.10.1 provides an optional model billing gateway, paired with Agent Client SDK and DSH 0.8.0. Operators manage services and allowance; hosts own local conversations, tool selection and persistent original requests. Business permissions and approvals remain independent.
Separate default budgets from service ceilings
Section titled “Separate default budgets from service ceilings”Core 0.10.1 can declare a new-request default, an allowed output ceiling, and the meaning of the supplier’s max_tokens or max_completion_tokens parameter per chat service. completion_total includes reasoning and the final answer; final_answer limits the answer only. Do not infer semantics from model names. Legacy services keep their behavior, and a policy change does not rewrite prepared or admitted operations. Hosts build new requests from the catalog and retain original finish reasons. Image tools, context windows, input size and timeouts remain separate bounds.
The host controls bounded continuation after generation is truncated. Completed tools must not run again with the text. See output budgets and continuation and recovery.
From a service to an available plan
Section titled “From a service to an available plan”- Configure the actual provider credentials, URL and model; choose a conversation model or model tool.
- Explicitly bind an OpenRouter reference model and endpoint. Verify that the reference metering matches the actual service; reference prices are not provider invoices.
- Create a USD plan with a service set, one multiplier, validity and, for periodic plans, both sale price and period allowance.
- Grant it to a personal or shared organization account. The host reads capabilities before displaying ready models, tools and allowance for that account.
Unready services stay out of callable items. unavailable_items explains why; hosts direct users to an administrator. After correction, refresh the catalog without switching models or replaying old requests automatically.
Sale price, allowance and customer display
Section titled “Sale price, allowance and customer display”| Plan | Configuration | Customer display |
|---|---|---|
| Periodic | priceUsd is the sale price; periodAllowanceUsd is the allowance per periodUnit day/week/month |
Remaining percentage, using the period allowance as denominator |
| Credit pack | priceUsd is the one-time USD allowance; omit periodAllowanceUsd |
Credits at 1000 Credits per USD |
Models and tools in one plan share an allowance and one multiplier. Each request settles actual metering against its original reference-price and multiplier snapshot. duration controls validity independently of reset periods. Template price changes affect future grants; the current model set and multiplier continue to come from the plan.
Use summary presentation for customer display. Raw Token counts remain usage evidence, not the percentage denominator. Payments, currency conversion and refunds belong to the business application.
Identity and SDK responsibilities
Section titled “Identity and SDK responsibilities”A trusted business login exchanges a short-lived credential. model_access: service limits it to one model; explicit token_gateway permits the intersection of its plan and issuer scope without widening business-tool permissions. Keep the separate issuer credential on the server.
Core’s Node UsageIssuerClient and PHP7 UsageClient expose these backend methods:
| Method | Purpose |
|---|---|
exchangeSession / revokeUser |
Exchange short-lived identity / revoke the original business user |
listBillingPlans |
List plans this issuer may grant |
grantBillingPlan |
Grant using original request_key, plan_id and expected_revision |
controlBillingPlan |
Suspend or activate a grant with its current revision |
getBillingSummary |
Read USD billing summary and customer presentation |
Plan methods use /usage/v1/external/billing/. Mutations never retry automatically. Persist the original input before sending and inspect with the same key and parameters after an uncertain response; do not recalculate the revision or issue another key. Node types are exported at @bailinghub/connect/usage.
The independent bailinghub-mcp-server Agent Client SDK and DSH handle host-side integration, separately from the Core business SDKs above. Installing a package does not intercept model traffic. Hosts opt into catalogs, model requests, tools, summaries and recovery.
Images, unknown outcomes and late settlement
Section titled “Images, unknown outcomes and late settlement”Initial executable adapters cover text-to-image through Aliyun’s OpenAI Images-compatible API, native DashScope and OpenRouter Images. Video, voice and custom tools may be declared but remain uncallable without an adapter.
Persist the original operation_id for every model or tool request. Reopened sessions query that request rather than generating again under a new ID. A result_state=complete image is usable while billing_state=pending awaits reliable metering. Settlement does not block results. Confirmed failures and unknown outcomes remain distinct; late results or costs after cancellation do not revive the turn.
Positive balances admit requests. Late concurrent settlement may create an overage; depleted balances block new requests. Hosts may reuse their existing attachment space for image URLs/Base64. Successful generation never writes to a business system automatically.
0.9.2: automatic settlement of saved usage
Section titled “0.9.2: automatic settlement of saved usage”standalone schedules maintenance after startup and every minute. Managed Kernels use their existing tick, which the Host must still call. HTTP is a fallback to the same maintenance port; saved usage recovery no longer requires incoming traffic.
Pages contain at most 50 rows, advance by (updated_at, id) and wrap at the end. Unpriceable or individually corrupt rows do not block later records. Maintenance only reads original metering, reference prices and the multiplier. It does not read result bodies, contact providers or redispatch models. Missing authoritative metering remains pending/unknown. Close stops new maintenance and drains started evidence writes, preserving the original instance for retry on timeout.
Explicitly apply outstanding migrations 065 and 066 before using 0.9.2; startup does not migrate automatically. See the 0.9.2 upgrade guide, reliability mechanisms, and 0.9.2 billing contract.
Administration and upgrade
Section titled “Administration and upgrade”Plan removal and account archival/restoration preserve original identifiers and ledgers. Restoring an account neither restores old credentials nor replenishes allowance. Authorized manual resets apply to effective Hub-managed allowance, retain the original expiry, and leave in-flight settlement on the original pool.
Upgrading public 0.9.4 to 0.10.1 adds no SQL migration. Earlier versions must apply all outstanding migrations, including 068, through the official migrator; startup does not migrate automatically. State and configuration databases are verified separately. Preserve existing identifiers, ledgers and in-flight requests; do not rerun applied migrations or purge data. See the upgrade guide and full billing contract.