The answer to one question, in the shape of its type.

type Answer = {
    type: "noul";
    noul: number;
} | {
    type: "choice";
    choice: string;
    probabilities: Record<string, number>;
    confidence?: number;
} | {
    type: "score";
    score: number;
    legend: Record<string, string>;
    probabilities: Record<string, number>;
    confidence?: number;
};

One candidate the call considered: skipped before sending, sent and failed, or the one that answered.

interface Attempt

• provider: string
• model: string
• outcome: "skipped" | "failed" | "ok"
• code?: HubErrorCode
• reason?: string

Options for batch().

interface BatchOptions

• concurrency?: number

  Calls running at once (default 4).

• stopOnOvercharge?: boolean

  Stop the batch when a call is billed well above its listed price (default true).

• maxSpendUsd?: number

  Stop the batch once this much has been spent, in US dollars.

• signal?: AbortSignal

  Stops the whole batch.

• onProgress?: (p: BatchProgress) => void

  Called after each item finishes or fails.

How far a batch has got.

interface BatchProgress

• done: number

  Items finished, failures included.

• total: number
• failed: number

  Items whose call rejected.

• spentUsd: number

  Spent so far: each call's billed cost, or its listed cost when the provider reports none.

What batch() resolves to. It doesn't reject when calls fail: each failure is in results.

interface BatchResult<R>

• results: (R | HubError | undefined)[]

  One entry per item, in order: the result, the error, or undefined when the batch stopped before it.

• progress: BatchProgress

  The final count and spend.

• stopped?: { reason: "overcharge" | "spend-limit" | "aborted"; index: number; message: string; }

  Why the batch stopped early, if it did.

How a provider charges: per token, nothing (local), or a flat subscription.

type BillingKind = "metered" | "local" | "subscription";

One monthly budget that applies to a call, and how much of it is spent.

interface BudgetStatus

• scope: "role" | "tier"

  Whether the budget is the role's own or its tier's.

• spentUsd: number

  Spent this calendar month, before this call.

• limitUsd: number
• warn: boolean

  Spent at least 80% of the limit.

The id of one of the seven built-in tiers.

type BuiltinTierName = (typeof BUILTIN_TIERS)[number];

interface CallOptionsBase

• tier?: TierName

  Use this tier's models and limits for one run instead of the role's (roles that allow any model).

• routing?: Record<string, unknown>

  Routing merged into every candidate's own routing for this call (OpenRouter: pin or exclude providers, a price cap…). Recorded in the ledger.

• candidates?: Candidate[]

  This call's own ordered candidates (roles that allow any model). Limits still apply.

• model?: { provider: string; model: string; }

  Use this model for one run instead of the role's candidates (no fallback). It must be one of the role's candidates, or the role must allow any model.

• for?: string

  What the call is about, for the ledger.

• signal?: AbortSignal

  Stops the call; it then rejects with aborted.

What every finished call reports: who served it, the usage, the cost, and how it got there.

interface CallReport

• provider: string
• billing: LedgerRow["billing"]

  How the provider charges: per token, nothing (local) or a subscription.

• askedModel: string
• servedModel?: string
• servedProvider?: string
• usage: Usage
• listedUsd: number | null

  US dollars at listed prices (for a subscription: the API-price equivalent); null when unknown.

• billedUsd?: number
• overcharged: boolean
• durationMs: number
• ledgerId: string
• tier: TierName
• attempts: Attempt[]

  Every candidate considered, in order.

• fellBack: boolean

  True when the answer didn't come from the first candidate.

• budgets: BudgetStatus[]

  Monthly budgets that apply, with this month's spend before this call.

One model to try: a provider, a model, and how to call it.

interface Candidate

• provider: string
• model: string
• routing?: Record<string, unknown>

  Provider-specific routing (OpenRouter: order, ignore, max_price, data policy, fallbackModels…).

• reasoning?: boolean
• maxOutputTokens?: number
• contextTokens?: number

  Context length to ask a local model for (Ollama's num_ctx).

declare const CAPABILITIES: readonly [
    "streaming",
    "tools",
    "structuredOutput",
    "reasoning",
    "webSearch",
    "imageInput",
    "pdfInput",
    "embeddings",
    "promptCaching",
    "decisions"
];

One thing a model can do. A call that needs a capability its model lacks is refused (capability-missing).

type Capability = (typeof CAPABILITIES)[number];

Options for complete().

interface CompleteOptions extends CallOptionsBase

• system?: string

  The system prompt. Skills' text goes before it.

• maxOutputTokens?: number

  The longest reply allowed (default 4096). The per-call ceiling is checked against the cost of a reply this long.

• tools?: ToolSet

  Tools the model may call. They are returned, not run: v1 is single-turn.

• output?: FlexibleSchema<unknown>

  A schema (zod or JSON Schema) the reply must match.

• webSearch?: boolean

  Let the provider search the web; the model must have webSearch. Sources come back in sources.

• needs?: Capability[]

  Capabilities the caller needs beyond what the options imply.

• skills?: string[]

  Skills to apply, by name. When given (even empty), the always-on skills join them; their text goes before system, and what they require of the model is checked like any other capability.

What complete() resolves to: the reply, and the call's report.

interface CompleteResult extends CallReport

• text: string

  The reply's text.

• object?: unknown

  The reply as data, when the call gave an output schema.

• toolCalls: { toolName: string; input: unknown; }[]

  Tools the model asked to call. The Hub returns them; it doesn't run them.

• sources: { url: string; title?: string; }[]

  Web pages the reply drew on, when the call searched the web.

• finishReason: string

  Why the model stopped, as the provider reports it (stop, length, tool-calls…).

• skills?: { included: string[]; dropped: string[]; }

  Skills that went into the request, and any left out for size.

Options for decide().

type DecideOptions = CallOptionsBase;

What decide() resolves to: the answers, whether they are calibrated, and the call's report.

interface DecideResult extends CallReport, Pick<DecisionAnswers, "answers" | "calibrated">

interface DecisionAnswers

• answers: Record<string, Answer>

  One answer per question, under the question's id.

• calibrated: boolean

  True when the probabilities come from a calibrated decision model (e.g. Jev), not a text model's single answer.

• usage: { inputTokens: number; outputTokens: number; }
• model?: string

  The model that answered, when the provider says.

Text, or structured data the question can refer to by field name in backticks.

type DecisionInput = string | Record<string, unknown> | unknown[];

What decide() takes: the thing being judged, and the questions to answer about it.

interface DecisionRequest

• state: DecisionInput

  What the questions are about: text, or structured data.

• questions: Record<string, Question>

  The questions, each under an id of your choosing; the answers come back under the same ids.

Options for embed().

type EmbedOptions = CallOptionsBase;

What embed() resolves to.

interface EmbedResult extends CallReport

• embeddings: number[][]

  One vector per input text, in order.

What getHub returns: the Hub, or why there isn't one, with a message to show the user.

type GetHubResult = {
    hub: HubApi;
} | {
    hub: null;
    reason: "missing" | "incompatible";
    message: string;
    version?: string;
};

class HubError extends Error

• readonly code: HubErrorCode

  Why the call was refused or failed.

• readonly details: Record<string, unknown>

  Facts behind the refusal, by code: the role, the tier, the estimate and ceiling, what the model lacks (missing)…

Why the Hub refused or failed a call. Every refusal names its cause; nothing falls back silently.

type HubErrorCode = "invalid-role-name" | "invalid-skill" | "skill-taken" | "unknown-role" | "role-taken" | "unknown-tier" | "invalid-tier-name" | "unknown-provider" | "unknown-model" | "model-not-allowed" | "capability-missing" | "unpriced-model" | "over-ceiling" | "over-budget" | "no-models" | "invalid-request" | "provider-unavailable" | "provider-error" | "aborted";

Which ledger rows usage() returns. Every field given must match; none returns every row.

interface LedgerFilter

• plugin?: string

  Calls made through this plugin's roles.

• role?: string

  Calls through this role.

• since?: string

  Calls at or after this time (ISO 8601).

• until?: string

  Calls before this time (ISO 8601).

One call, as the ledger records it. Refusals and failures are recorded too, at cost 0.

interface LedgerRow

• id: string
• time: string
• plugin: string
• role: string
• tier?: string

  The id of the tier the role resolved to.

• tierName?: string

  That tier's name at the time of the call.

• attempt?: number

  Which try this was, when the call fell back along its candidates (1 = the first candidate sent to).

• routing?: Record<string, unknown>

  Routing the caller added for this call, if any.

• for?: string

  What the call was about, as the calling plugin describes it.

• operation: "complete" | "stream" | "embed" | "decide"
• provider: string
• billing: BillingKind
• askedModel: string
• servedModel?: string
• servedProvider?: string
• usage: Usage
• listedUsd: number | null

  US dollars at listed prices; null when the model has no listed price.

• billedUsd?: number

  US dollars the provider says it billed, when it says.

• overcharged: boolean
• durationMs: number
• outcome: "ok" | "refused" | "failed"
• errorCode?: HubErrorCode
• errorMessage?: string

A model as the Hub knows it, from its provider's own listing. models() returns these for pickers.

interface ModelInfo

• provider: string

  The provider's id in the Hub, such as openrouter or ollama.

• id: string

  The model's id at that provider, as a candidate names it.

• label?: string

  A name to show; fall back to id.

• contextLength?: number

  Context window in tokens, when the provider says.

• pricing: Pricing
• capabilities: Capability[]

The models to try and the spending limits: what a tier holds, and what a role may carry of its own.

interface ModelPolicy

• candidates: Candidate[]

  Priority order: the first that can serve the call is used; a failed call moves to the next.

• ceilingUsd?: number

  Most a single call may cost, in US dollars.

• monthlyBudgetUsd?: number

  Most this may spend in a calendar month, in US dollars (metered calls only).

US dollars per token. null means the price is unknown.

interface Pricing

• input: number | null
• output: number | null
• cacheRead?: number | null
• cacheWrite?: number | null

One question about the state: yes/no (noul), pick one (choice) or rate on levels (score).

type Question = {
    type: "noul";
    instructions: DecisionInput;
    criteria?: {
        true?: DecisionInput;
        false?: DecisionInput;
    };
} | {
    type: "choice";
    instructions: DecisionInput;
    criteria: Record<string, DecisionInput | null>;
} | {
    type: "score";
    instructions: DecisionInput;
    criteria: DecisionInput[];
};

What a call through a role uses: the candidates to try, and every limit that applies.

interface ResolvedRole extends RoleSpec

• effective: Candidate[]

  The candidates to try, in order (the role's own, else the tier's).

• ceilings: number[]

  Every per-call ceiling that applies (role and tier); a call must fit all of them.

• budgets: { scope: "role" | "tier"; limitUsd: number; }[]

  Every monthly budget that applies.

• tierName: string

  The display name of the tier tier is the id of.

• tierMissing?: true

  Set when the role names a tier that doesn't exist (a deleted or not-yet-made custom tier): it runs on balanced.

• missingTier?: TierName

  The tier the role names (as it names it) but that doesn't exist.

A role as a plugin registers it: a name, a description, and its model policy — a tier and/or its own ordered candidates, a per-call ceiling and a monthly budget. The same schema as a tier.

The one-model form (provider + model, API 0.1) still works and becomes a one-candidate list.

interface RoleDefinition extends Partial<ModelPolicy>

• name: string
• description?: string
• tier?: TierName

  The tier this role uses, built in or the user's own, by id or by name; balanced when it names none. A tier that doesn't exist (yet) is kept as named: the role runs on balanced, flagged tierMissing, until it is made. Store the id createTier returns; a name keeps working across renames (old names stay as aliases).

• allowAnyModel?: boolean

  Any model in the catalog may be picked for one run (interactive roles such as the chat panel's). Limits still apply.

• provider?: string

  API 0.1: one provider and model.

• model?: string
• reasoning?: boolean
• maxOutputTokens?: number
• contextTokens?: number
• routing?: Record<string, unknown>
• allowedModels?: { provider: string; model: string; }[]

  API 0.1: models a caller may pick for one run.

The user's setting for a role: any of a tier, own candidates and limits. null fields clear back to the plugin's default.

interface RoleOverride

• tier?: TierName
• candidates?: Candidate[]
• ceilingUsd?: number | null
• monthlyBudgetUsd?: number | null

A role's settings after the plugin's default and the user's override are combined.

interface RoleSpec

• name: string
• owner: string
• description?: string
• tier: TierName
• candidates: Candidate[]

  The role's own candidates; empty means "the tier's".

• ceilingUsd?: number
• monthlyBudgetUsd?: number
• allowAnyModel: boolean
• allowedModels: { provider: string; model: string; }[]
• overridden: boolean

  True when the user has changed anything.

A skill a plugin registers: its folder's text files, by relative path, SKILL.md among them.

interface SkillRegistration

• files: Record<string, string>

A skill as skills() lists it.

interface SkillSummary

• name: string

  The name a call puts in skills.

• description: string

  What the skill is for, from its SKILL.md.

• mode: "always" | "chosen"

  always skills join every call that asks for skills. Only the user's vault skills may be always.

• requires: Capability[]

  What a model must be able to do for this skill to be used.

• origin: "builtin" | "vault"

  builtin: shipped with the Hub or registered by a plugin (see plugin); vault: in the user's skills folder.

• plugin?: string since 0.4

  The plugin that registered this skill with registerSkills. (Since 0.4.)

• extends?: string

  A skill this one layers on; its instructions are included before this one's.

• extendsMissing?: boolean since 0.4

  extends names a skill that isn't loaded (for example, the plugin that registers it is off). (Since 0.4.)

• files(): Promise<Record<string, string>> since 0.4

  The skill's own text files, by path relative to its folder (reader.yml, prompts/extract.md), recursive, without SKILL.md. A vault skill's are read from the vault at each call, so edits show at once. Only this skill's files: a parent's (extends) are the parent's files(); merging them is up to you. (Since 0.4.)

Options for stream(): those of complete(), without structured output.

type StreamOptions = Omit<CompleteOptions, "output">;

What stream() returns at once: the text as it arrives, and a promise of the full result.

interface StreamResult

• textStream: AsyncIterable<string>

  Text as it arrives. Ends with a HubError if the call fails or is stopped.

• result: Promise<CompleteResult>

  Resolves when the stream ends, with the full result; rejects with a HubError.

A tier as listed: its policy, its stable id (a built-in tier's is its name; a custom tier's never changes, even when it is renamed), its display name, and whether the user made it.

type Tier = ModelPolicy & {
    id: string;
    name: TierName;
    custom: boolean;
};

A tier's id (a built-in tier's name, or a custom tier's id such as clusters-bulk); lookups also accept its name.

type TierName = string;

Tokens a call used, as the provider reported them.

interface Usage

• inputTokens: number

  All input tokens, cached ones included.

• outputTokens: number

  All output tokens, reasoning included.

• cacheReadTokens: number

  Input tokens read from the provider's prompt cache.

• cacheWriteTokens: number

  Input tokens written to the provider's prompt cache.

• reasoningTokens: number

  Output tokens spent on reasoning.