@lionhummer/constellation 0.4.0 → 0.5.0

package/README.md

@@ -201,3 +201,19 @@ const body = await client.telemetry.requests.getHttpBody(requestId, attemptId, {
 Request lists accept `RequestListQuery`, including exact `externalId` and requested-model filters, exclusions and substring matches. Record lists accept `RequestRecordsQuery` (`id`, `q`, log-only `level`, `offset`, `limit`). `PageQuery.filters` belongs only to registry list rows. Every other method has its endpoint's exact query type. See the [HTTP filter matrix](../../docs/api.md#filter-audit-and-exact-query-support) for search semantics, caps, cursor behavior and capabilities not currently provided.
 
 Unscoped telemetry also exposes `observability.getBilling`, `getTraffic`, `getTiming`, dashboard and measurement series. Use `providerId` for local series and `upstream` for gateway series. `system.getComponent(component, { status, statusNot, q, offset })` and `jobs.listHistory` page matching operational records; notifications use fixed 25-item pages and status/offset, not generic filters.
+
+### Supplier cost, customer basis and margin
+
+Each provider attempt records immutable `attributes.billing` on its Constellation `provider.call` span. The `step.usage_ready` event carries the same `billing` facts. Both are included in default telemetry metadata. `supplierPrice`/`supplierCost` record the selected supplier rates and usage cost. `customerPricing` identifies the model or offering basis, plan, scoped rule and adjustment; `customerBasisPrice`/`customerBasisCost` record the customer calculation before adjustment. `customerPrice`/`customerCost` record the final rates and charge. `grossMarginAmount` is charge minus supplier cost; `grossMarginPercent` divides it by charge. Unknown costs leave margins null, and a zero charge has a null margin percentage. These costs use provider-reported usage and captured schedules, not reconciled supplier invoices. Prices are USD per million tokens; costs are decimal USD strings.
+
+Provider cost capture is optional: `billing.amountPointer` locates a provider-reported amount in response JSON and `unitsPerUsd` converts it to USD. `reportedSupplierCost` is retained only for analysis; it never changes supplier cost, customer basis, charges or margin. Supplier cost is calculated from reported token usage and captured supplier rates. `supplierCostDifference` is reported minus calculated cost when both are known. The offering selects `customerPriceBasis:model|offering`; plans apply the customer adjustment.
+
+### Standard settings and headers
+
+Use `parameters.reasoningEffort` for reasoning effort across providers. The model discovery schema defines its allowed values and other supported settings. Constellation translates fields and values for the selected offering. Required unsupported settings reject; `optionalParameters` permits declared omissions with warnings.
+
+The standard Reasoning Effort vocabulary is `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`; Verbosity is `low`, `medium`, or `high`; Service Tier is `auto`, `default`, `flex`, or `priority`. Discovery lists the values accessible to your key and eligible routes. A model’s standard definitions cannot be renamed or given additional values; custom parameters have separately authored definitions. Provider wire names and values are translated internally.
+
+For cache diagnostics, send `cache: { mode: "automatic", diagnostics: true }` on the first step. `providerResponseId` appears on attempts and in the `afterModel` checkpoint payload. Use that upstream ID as a later step’s `cache.comparisonId`, which also enables diagnostics. A successful cache hit may return no diagnostic payload. Telemetry exposes the response ID by default; raw `cacheDiagnostics` requires `include: "content"`. Diagnostics and prewarm are offering capabilities: discover support before requesting them. Invalid TTLs or unsupported required cache settings fail rather than being silently dropped.
+
+Send beta tokens as `headers: { "anthropic-beta": "your-beta-token" }`, not inside `parameters`. The provider connection must allow the header name. Unapproved, protected or malformed headers are dropped with warnings. A permitted header can still contain an upstream-unsupported beta token; the provider's own error remains visible. Cache diagnostics can add their required beta separately. Obvious may choose provider-specific prompt placement and cache boundaries while using Constellation's standard cache request.

package/dist/types/client-core/src/index.d.ts

@@ -29,6 +29,20 @@ export type Message = {
         isError?: boolean;
     }[];
 };
+/** Standard settings. The model discovery schema describes supported values and extensions. */
+export type InferenceParameters = Record<string, Json> & {
+    reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    verbosity?: "low" | "medium" | "high";
+    temperature?: number;
+    topP?: number;
+    thinking?: Json;
+    toolChoice?: Json;
+    parallelToolCalls?: boolean;
+    toolStrict?: boolean;
+    responseFormat?: Json;
+    stopSequences?: string[];
+    serviceTier?: "auto" | "default" | "flex" | "priority";
+};
 type RequestFields = {
     idempotencyKey: string;
     externalId?: string;
@@ -39,12 +53,21 @@ type RequestFields = {
     instructions?: string;
     messages: Message[];
     tools?: Tool[];
-    parameters?: Record<string, Json>;
+    parameters?: InferenceParameters;
+    optionalParameters?: string[];
+    /** Only headers approved by the selected provider are forwarded; others produce warnings. */
+    headers?: Record<string, string>;
+    nativeContentPolicy?: "require" | "omitCompleted";
     maxSteps?: number;
     timeoutMs?: number;
     maxOutputTokens?: number;
     cache?: {
         mode: "automatic" | "explicit";
+        ttl?: string;
+        prewarm?: boolean;
+        comparisonId?: string;
+        /** Request cache diagnostics, including a first-turn baseline without a comparison ID. */
+        diagnostics?: boolean;
         points?: ({
             target: "tools" | "instructions";
         } | {
@@ -126,6 +149,8 @@ export type Attempt = {
     providerId: string;
     offeringId: string;
     providerModel: string;
+    providerResponseId?: string | null;
+    cacheDiagnostics?: Json | null;
     connectionKind: string;
     endpoint: string;
     fallback: boolean;
@@ -154,7 +179,11 @@ export type PreparedStep = {
     instructions: string;
     messages: Message[];
     tools: Tool[];
-    parameters: Record<string, Json>;
+    parameters: InferenceParameters;
+    optionalParameters?: string[];
+    /** Only headers approved by the selected provider are forwarded; others produce warnings. */
+    headers?: Record<string, string>;
+    nativeContentPolicy?: "require" | "omitCompleted";
     maxOutputTokens: number;
     cache: RequestInput["cache"] | null;
 };
@@ -174,6 +203,8 @@ export type PendingInput = {
         customerCost?: string | null;
         supplierCost?: string | null;
         customerPrice?: Json;
+        customerPricing?: CustomerPricing;
+        billing?: BillingFacts;
         output?: Json;
     };
     claimId: string | null;
@@ -307,7 +338,11 @@ export type ModelResolution = ModelScope & {
     targetId: string;
     inputTokens?: number;
     outputTokens?: number;
-    parameters?: Record<string, Json>;
+    parameters?: InferenceParameters;
+    optionalParameters?: string[];
+    /** Only headers approved by the selected provider are forwarded; others produce warnings. */
+    headers?: Record<string, string>;
+    nativeContentPolicy?: "require" | "omitCompleted";
 };
 export type WebhookEvent = {
     requestId: string;
@@ -336,9 +371,51 @@ export type TokenUsage = {
     outputTokens?: number;
     cacheReadTokens?: number;
     cacheWriteTokens?: number;
+    cacheWriteOneHourTokens?: number;
     reasoningTokens?: number;
     partial?: boolean;
 };
+/** USD per million tokens. The selected rates apply to the whole call. */
+export type TokenPrice = {
+    input: string;
+    output: string;
+    cacheRead?: string | null;
+    cacheWrite?: string | null;
+    cacheWriteOneHour?: string | null;
+    tiers?: {
+        aboveInputTokens: number;
+        price: TokenPrice;
+    }[];
+};
+export type CustomerPricing = {
+    basis: "model" | "offering";
+    basisTargetId: string;
+    basisPrice?: TokenPrice;
+    planId: string | null;
+    pricingRuleId: string | null;
+    adjustment: {
+        mode: "margin" | "markup" | "discount";
+        percent: string;
+    };
+};
+/** Costs use captured rates; provider-reported amounts are analysis-only. */
+export type BillingFacts = {
+    totalInputTokens: number | null;
+    supplierPrice: TokenPrice | null;
+    supplierCost: string | null;
+    calculatedSupplierCost: string | null;
+    reportedSupplierCost: string | null;
+    supplierCostSource: "calculated" | "unknown";
+    supplierCostDifference: string | null;
+    customerPricing: CustomerPricing;
+    customerBasisPrice: TokenPrice | null;
+    customerBasisCost: string | null;
+    customerBasisSource: "calculated" | "unknown" | "model_schedule";
+    customerPrice: TokenPrice | null;
+    customerCost: string | null;
+    grossMarginAmount: string | null;
+    grossMarginPercent: string | null;
+};
 export type TimingInterval = {
     id: string;
     requestId: string;

package/dist/types/sdk/src/index.d.ts

@@ -1,7 +1,7 @@
 /** External server SDK. Operator APIs and cookie sessions are internal-only clients. */
 import { RequestClient, type WebhookEvent, type Json, type Page, type PageQuery, type ModelResolution, type RequestRecord, type RequestEvent, type RecordTypes, type Timeline, type TimelineRow, type RequestListQuery, type RequestRecordsQuery, type RequestTimings, type TokenUsage } from "../../client-core/src/index";
 export { ConstellationError, uuid7 } from "../../client-core/src/index";
-export type { Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, RequestTimings, TimingInterval, TokenUsage, Status, RequestRecord, Step, Attempt, PreparedStep, PendingInput, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, InputResponse, InputHandlers, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, StartSpanOptions } from "../../client-core/src/index";
+export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, PreparedStep, PendingInput, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, InputResponse, InputHandlers, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, StartSpanOptions } from "../../client-core/src/index";
 /** OpenAPI contract filtered to this key's permissions and scope. */
 export type DiscoveryDocument = {
     openapi: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionhummer/constellation",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript client for durable model requests and caller events",
   "type": "module",
   "license": "UNLICENSED",