Model services and plan billing

Core 0.9.0 provides an optional model billing gateway, paired with Agent Client SDK and DSH 0.7.0. Operators manage services and allowance; hosts own local conversations, tool selection and persistent original requests. Business permissions and approvals remain independent.

From a service to an available plan

1. Configure the actual provider credentials, URL and model; choose a conversation model or model tool.
2. Explicitly bind an OpenRouter reference model and endpoint. Verify that the reference metering matches the actual service; reference prices are not provider invoices.
3. Create a USD plan with a service set, one multiplier, validity and, for periodic plans, both sale price and period allowance.
4. 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

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

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

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.

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.

Upgrade public 0.8.0 through the official migrator with unapplied migrations 063 and 064; do not purge data. Billing-preview installations separately verify period snapshots. See the upgrade guide and full billing contract.