link

type AIClientUpstream ¶

type AIClientUpstream struct{ AI types.AIClient }

AIClientUpstream adapts a platform types.AIClient into an Upstream. It threads the resolved credential + account to the client through the request context (WithCredential / WithAccount) — never a header, body, or log — so an ACCOUNT-AWARE client (the in-process ai egress that reads CredentialFrom at dial time) authenticates with the caller's OWN credential. The request Payload must be a *types.ChatRequest.

func (u AIClientUpstream) Call(ctx context.Context, cred Credential, a Account, req Request) (Result, error)

type Account ¶

type Account struct {
	Provider string
	Profile  string
}

Account is the identity of ONE linked provider account: a provider and a profile within it. It is the openclaw `@anthropic:work` selector — provider "anthropic", profile "work" — and a NON-SECRET identifier: it NAMES an account, never carries its credential. An empty Profile denotes the provider's default account.

func AccountFrom(ctx context.Context) (Account, bool)

func ParseAccountRef(s string) (Account, bool)

func (a Account) String() string

type AccountsTotal ¶

type AccountsTotal struct {
	Accounts         int   `json:"accounts"`
	Requests         int64 `json:"requests"`
	PromptTokens     int64 `json:"promptTokens"`
	CompletionTokens int64 `json:"completionTokens"`
	TotalTokens      int64 `json:"totalTokens"`
	CostCents        int64 `json:"costCents"`
}

AccountsTotal is the summed usage across a caller's linked accounts.

type AccountsUsage ¶

type AccountsUsage struct {
	Scope    string        `json:"scope"`  // user
	Source   string        `json:"source"` // routed
	Total    AccountsTotal `json:"total"`
	Accounts []RoutedUsage `json:"accounts"`
}

AccountsUsage is the per-account breakdown response. Source is always "routed" — this is the gateway's own routed ledger, distinct from the device collector's plan snapshots (/v1/links/usage/summary) and from the org money ledger (/v1/billing/usage). Scope is always "user": the caller's own linked accounts.

func RoutedBreakdown(ctx context.Context, org, subject string) (AccountsUsage, bool)

type Config ¶

type Config struct {
	Links    Links
	Resolver Resolver
	Upstream Upstream
	Meter    Meter
	Logger   luxlog.Logger
	Policy   Policy
	Cooldown time.Duration
	Now      func() time.Time
}

Config constructs a Router. Links, Resolver, and Upstream are required; Meter and Logger are optional; Now defaults to time.Now; Cooldown defaults to 60s.

type Credential ¶

type Credential struct {
	Token  string            // bearer / api-key / OAuth access token — the secret
	Header string            // auth header to carry it; "" ⟹ Authorization
	Scheme string            // "Bearer" | "" (raw); how Token is presented
	Extra  map[string]string // multi-field providers (region, project, sign-key)
	Expiry time.Time         // token expiry; zero ⟹ non-expiring (a raw api key)
}

Credential is a resolved upstream provider credential, held in memory for the life of ONE request and then discarded. It is NEVER persisted, and it never appears in a log line, a response, an error, or an argv: String and GoString redact, so even an accidental %v / %+v / %#v of a Credential — or of any struct that embeds one — cannot leak the token. The router treats it as opaque: it hands the value to Upstream.Call and retains nothing.

func CredentialFrom(ctx context.Context) (Credential, bool)

func (Credential) GoString() string

func (Credential) String() string

type Link ¶

type Link struct {
	ID       string
	Org      string
	User     string // the owning subject (validated principal); a user sees only their own
	Machine  string // stable machine id (the device key)
	Host     string // hostname (device label)
	OS       string // platform label (darwin|linux|windows|…)
	Provider string // matches @hanzo/usage providerRegistry id (claude|codex|hanzo|openai|…)
	Account  string // the subscription/account id or label (e.g. an account email)
	Plan     string // the plan name from the provider identity (e.g. "Claude Max"); display only
	Kind     string // subscription | apikey
	Status   string // linked | revoked
	LastSeen int64  // unix; bumped on every usage report
	Usage    string // JSON of the latest Usage projection ("" until first report)

	CreatedAt int64
	UpdatedAt int64
}

Link is one (user, device, provider, account) binding. Tenant isolation is the (org, user) pair, enforced on every query. It never stores a secret.

type Links ¶

type Links interface {
	ListLinked(ctx context.Context, org, subject string) ([]Link, error)
}

Links is the read seam over the linked-account registry the router routes across. *Store satisfies it; a unit test supplies a fake. The router depends on THIS, not the concrete SQLite store, so its selection + cycling policy is proven without a database or KMS — and the isolation guarantee is a deterministic assertion.

type Meter ¶

type Meter interface {
	RecordRouted(ctx context.Context, org, subject string, a Account, kind string, res Result)
}

Meter records a served routed call to the per-account usage ledger. A nil Meter disables metering (routing still works). It is a separate seam so the router's policy is tested without a warehouse or a billing client.

func NewMeter(store *Store, billing *metering.Client, price Pricer, log luxlog.Logger) Meter

type Policy ¶

type Policy int

Policy is the cycle order over a caller's candidate accounts.

const (
	// PolicyPlan is route.go's redundancy order: subscription accounts first (the
	// flat-rate pool, most-headroom first), then api-key accounts (the metered
	// backstop). The sensible default; it reuses the ONE ordering Plan already owns.
	PolicyPlan Policy = iota
	// PolicyMostRemaining orders purely by remaining rate-limit headroom, highest
	// first — "route to whichever account has the most quota left", regardless of kind.
	PolicyMostRemaining
	// PolicyRoundRobin spreads load evenly across a provider's accounts by rotating
	// the Plan order per (org, subject) on each request.
	PolicyRoundRobin
)

type Pricer ¶

type Pricer func(res Result) int64

Pricer returns the retail charge, in whole USD cents, for one served routed call. It is injected so the router never fabricates a price: the operator sets the BYO platform-fee policy, and the default (ZeroPrice) charges nothing — usage is still metered, but no money is invented.

type QuotaError ¶

type QuotaError struct {
	Provider string
	Status   int
	Err      error
}

QuotaError marks an upstream outcome as a quota / rate-limit / 429 the router should CYCLE on. Upstream adapters wrap their 429s in it (or return HTTP 429, which IsQuota also recognises). It carries the provider + status for the audit trail, never any credential.

func (e *QuotaError) Error() string

func (e *QuotaError) Unwrap() error

type Request ¶

type Request struct {
	Model   string
	Payload any
}

Request is the provider-agnostic inference the Upstream executes. The router owns SELECTION and CYCLING, not prompt shaping, so Payload is opaque: it is never inspected, mutated, or logged here.

type Resolver ¶

type Resolver interface {
	Resolve(ctx context.Context, org, subject string, a Account) (Credential, error)
}

Resolver is the credential-fetch contract this package CONSUMES. Given an account it returns the KMS-stored credential, refreshed if the connector keeps it fresh. It is scoped to (org, subject): the key is bound HERE from the validated principal the router passes, never taken from a request, so a foreign org's or user's account is unreachable — resolving across the tenant boundary is unrepresentable, not merely refused.

func NewKMSResolver(kms cloud.KMSClient) Resolver

type Result ¶

type Result struct {
	Model            string
	PromptTokens     int64
	CompletionTokens int64
	TotalTokens      int64
	Response         any
}

Result is a served call's outcome the meter records. A routed call's usage is EXACT — the upstream returns real token counts — unlike a plan-percent snapshot.

type RouteCandidate ¶

type RouteCandidate struct {
	Provider    string  `json:"provider"`
	Account     string  `json:"account,omitempty"`
	Plan        string  `json:"plan,omitempty"`
	Kind        string  `json:"kind"`    // subscription | apikey
	Billing     string  `json:"billing"` // plan | commerce (BillingMode(Kind))
	Available   bool    `json:"available"`
	HeadroomPct float64 `json:"headroomPct"` // remaining capacity 0..100
	Machine     string  `json:"machine,omitempty"`
	Host        string  `json:"host,omitempty"`
	LinkID      string  `json:"linkId"`
	Reason      string  `json:"reason,omitempty"` // why unavailable, when Available=false
}

RouteCandidate is one account the policy would route to, in preference order, annotated with how it bills and whether it currently has rate-limit headroom.

type RoutePlan ¶

type RoutePlan struct {
	Candidates  []RouteCandidate `json:"candidates"`
	Primary     *RouteCandidate  `json:"primary,omitempty"`
	GeneratedAt string           `json:"generatedAt"`
}

RoutePlan is the ordered redundancy plan for a user's accounts: the candidates in preference order plus the primary the caller would try first.

func Plan(links []Link, now time.Time) RoutePlan

type RoutedUsage ¶

type RoutedUsage struct {
	Provider         string `json:"provider"`
	Account          string `json:"account,omitempty"`
	Kind             string `json:"kind"`
	Billing          string `json:"billing"` // BillingMode(Kind): plan | commerce
	Requests         int64  `json:"requests"`
	PromptTokens     int64  `json:"promptTokens"`
	CompletionTokens int64  `json:"completionTokens"`
	TotalTokens      int64  `json:"totalTokens"`
	CostCents        int64  `json:"costCents"`
	FirstAt          int64  `json:"-"`
	LastAt           int64  `json:"-"`
}

RoutedUsage is one account's summed server-routed usage — a row of the per-account breakdown the dashboard reads.

type Router ¶

type Router struct {
	// contains filtered or unexported fields
}

Router runs the failover: it selects a caller's OWN linked accounts, orders them by policy, and tries each — resolving its credential and dialing the upstream — cycling on a live quota error until one serves or all are spent.

func NewRouter(cfg Config) (*Router, error)

func NewRouterFromDeps(deps cloud.Deps, up Upstream) (*Router, bool, error)

func (r *Router) Route(ctx context.Context, org, subject string, sel Selection, req Request) (Result, Account, error)

type Sample ¶

type Sample struct {
	Provider string // matches Link.Provider / @hanzo/usage providerRegistry id
	Account  string // the account label (an identifier, never a secret)
	Plan     string // the plan name from the provider identity; display only
	Kind     string // subscription | apikey (validKind) — mirrors Link.Kind
	Machine  string // the machine that OBSERVED this (an attribute, not a key)

	Lane          string    // the meter's lane id (five_hour|seven_day_opus|…) — the identity
	Window        string    // the canonical class (6h|day|week|month)
	WindowMinutes int32     // the duration the meter reported (300 for Claude's 5h)
	WindowStart   time.Time // WHICH instance of the window this measures — the dedup key
	ResetsAt      time.Time // when the window resets (RateWindow.resetsAt); zero = unknown

	// UsedPct is the lane's used percent, 0..100 — RateWindow.usedPercent. For a
	// subscription account this is THE quota signal and often the ONLY one.
	//
	// QUOTA GAP (deliberate, reported, not faked): there is NO absolute
	// used/limit token quota column, because nothing can populate one. The meter
	// reports a percent, not a limit (Claude: dataConfidence `percentOnly`). The
	// hanzoai/plans catalog expresses `ai.requests_per_min` / `ai.tokens_per_min`
	// — per-MINUTE rate limits, a different concept from a window quota — and in
	// any case it is HANZO's own plan catalog, which cannot know what Anthropic
	// grants a subscription plan. An always-zero quota_limit would read as "the
	// limit is zero"; absent is honest. It lands as an additive column when a
	// source for it exists.
	UsedPct    float64
	Confidence string // exact|estimated|percentOnly|unknown — see the const block
	// Synthetic marks a lane the meter FABRICATED (RateWindow.isSyntheticPlaceholder
	// — set when a provider returned null for a lane and the adapter filled it in).
	// Carried so a made-up lane is never rendered as observed truth.
	Synthetic bool

	// Absolute counters — UsageTotals. Present only when the source really reports
	// them (`exact`); zero otherwise, which Confidence disambiguates.
	Requests          int64
	InputTokens       int64
	OutputTokens      int64
	TotalTokens       int64
	CachedInputTokens int64

	// Money — ProviderCostSnapshot, in minor units (cents). CostCents is what the
	// PROVIDER says this account spent (Claude's extra_usage overage; 0 for a flat
	// subscription — the plan is the charge). CostLimitCents is that meter's budget
	// (ProviderCostSnapshot.limit) — a MONEY cap, never a token quota. Neither is a
	// Hanzo charge: this plane holds no metering client.
	CostCents      int64
	CostLimitCents int64
	Currency       string // ProviderCostSnapshot.currencyCode; "" = unknown
}

Sample is one metering lane's consumption of one provider account at one observation.

TENANCY IS NOT ON THE VALUE. Org and subject are bound by the server from the validated principal at the boundary, so a client cannot assert whose usage this is — the shape makes cross-tenant writes unrepresentable rather than merely refused.

func (s Sample) Sanitize(now time.Time) Sample

type Selection ¶

type Selection struct {
	Account Account
	Pinned  bool
}

Selection is the per-request account choice. A zero Account means "route across ALL of my linked accounts" (auto-failover); a set Account with Pinned=true means "use THIS account (and, for cycling, its provider's other profiles)".

func ParseModelRef(ref string) (model string, sel Selection)

"gpt-4o"              ⟹ model "gpt-4o",  no pin
"Opus@anthropic:work" ⟹ model "Opus",   pin anthropic:work
"Opus@anthropic"      ⟹ model "Opus",   pin anthropic (default profile)
"Opus@"               ⟹ model "Opus",   no pin (empty account is not a pin)

func SelectionFrom(header, modelRef, sessionPin string) (model string, sel Selection)

type SessionMatch ¶

type SessionMatch struct {
	Subject  string
	Host     string
	Provider string
	Account  string
}

SessionMatch selects the live sessions a revoke stops. Fields are ANDed with the org; an empty field is "any". A link revoke matches {Host,Provider,Account} (the device+account the sessions ran under); a device revoke matches {Host}. Subject is the REVOKING user; the adapter turns it into the session Actor so a stop only ever reaches that user's OWN sessions — Host/Provider/Account (attacker-set at link upsert) can then only narrow WITHIN them, never widen to a co-tenant's.

type Sessions ¶

type Sessions interface {
	Stop(ctx context.Context, org string, m SessionMatch) (int, error)
	CountActive(ctx context.Context, org string, m SessionMatch) (int, error)
}

Sessions is the seam to the agent-session control plane (clients/agents, in-process). Revoke stops the sessions that ran under a revoked account/device; the device view counts a machine's active sessions. A nil seam (unit test / no agents mounted) makes revoke skip the stop and the count report 0 — the registry truth (the revoked row) is unaffected.

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store is the login-manager database. ONE SQLite file — the deployment's own "link" — holds every org's Links; tenancy is the (org, subject) pair. It holds NO metering client — it is structurally incapable of charging commerce.

It also owns the account-usage SERIES in the datastore (datastore.go): the Link row is an account's latest state, the series is its history. Both are the same (org, subject) tenancy, so they live behind one store rather than two seams that could drift apart on isolation. dsReady latches the idempotent warehouse DDL — on success only, so a datastore still connecting at boot is retried, not permanently written off.

func (s *Store) AccountTotals(ctx context.Context, org, subject string, from, to time.Time) ([]Total, bool)

func (s *Store) AddRouted(ctx context.Context, org, subject string, a Account, kind string, res Result, costCents, now int64) error

func (s *Store) Close() error

func (s *Store) Get(ctx context.Context, org, subject, id string) (Link, error)

func (s *Store) HanzoTotals(ctx context.Context, org string, from, to time.Time) ([]Total, bool)

func (s *Store) List(ctx context.Context, org, subject string) ([]Link, error)

func (s *Store) ListDevice(ctx context.Context, org, subject, machine string) ([]Link, error)

func (s *Store) ListLinked(ctx context.Context, org, subject string) ([]Link, error)

func (s *Store) Revoke(ctx context.Context, org, subject, id string, now int64) (Link, bool, error)

func (s *Store) RevokeDevice(ctx context.Context, org, subject, machine string, now int64) ([]Link, error)

func (s *Store) RoutedTotals(ctx context.Context, org, subject string) ([]RoutedUsage, error)

func (s *Store) Series(ctx context.Context, org, subject, provider, account, window string, from, to time.Time) ([]Sample, bool)

func (s *Store) Upsert(ctx context.Context, x Link) (Link, error)

func (s *Store) WriteSamples(ctx context.Context, org, subject string, samples []Sample, now time.Time) error

type Total ¶

type Total struct {
	Source     string
	Scope      string
	Provider   string
	Window     string
	Requests   int64
	Tokens     int64
	CostCents  int64
	UsedPct    float64
	Confidence string
	Windows    int64
}

Total is one provider's usage in the global view, from ONE source at ONE scope.

type Upstream ¶

type Upstream interface {
	Call(ctx context.Context, cred Credential, a Account, req Request) (Result, error)
}

Upstream dials ONE provider account with its resolved credential and returns the served usage, or a classified error. A quota / rate-limit / 429 outcome MUST be returned as an error satisfying IsQuota, so the router knows to CYCLE; any other error is terminal for the request (cycling cannot fix a bad request and might double-serve). cred is for this one call — the Upstream must not retain or log it.

type Usage ¶

type Usage struct {
	SessionPct   float64 `json:"sessionPct"`             // primary window used %, 0..100
	WeeklyPct    float64 `json:"weeklyPct"`              // secondary window used %, 0..100
	ResetsAt     string  `json:"resetsAt,omitempty"`     // primary window reset, RFC3339
	Tokens       int64   `json:"tokens"`                 // absolute token total when known
	InputTokens  int64   `json:"inputTokens,omitempty"`  //
	OutputTokens int64   `json:"outputTokens,omitempty"` //
	SpendCents   int64   `json:"spendCents"`             // provider spend (0 for a subscription)
	Currency     string  `json:"currency,omitempty"`     //
	Confidence   string  `json:"confidence,omitempty"`   // exact|estimated|percentOnly|unknown
	UpdatedAt    string  `json:"updatedAt,omitempty"`    // snapshot time, RFC3339
}

Usage is the projection of a provider's @hanzo/usage UsageSnapshot the collector pushes and the dashboard renders: the rate-limit windows, token totals, and spend. It is stored as JSON on the Link and parsed for the route policy's headroom. Money is USD cents end-to-end. Spend is always 0 for a pure subscription account (there is no per-call charge — the plan is flat).