@lionhummer/constellation 0.4.0 → 0.6.0

package/README.md

@@ -201,3 +201,31 @@ 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.
+
+## Reasoning history and model handoffs
+
+Retain the complete `nativeContent` artifact from assistant output alongside canonical text, tool calls and results. Reasoning summaries alone cannot reconstruct signed/encrypted state. Use `nativeContentPolicy: "omitIncompatible"` on submitted or prepared steps to permit cross-family handoffs, including active tool continuations. Constellation omits only incompatible native state in the outbound attempt and records a warning; the original history remains intact. `require` excludes incompatible routes; `omitCompleted` permits omission only from completed turns.
+
+Same-protocol Claude/Responses model switches let providers verify native readability. Responses account scopes must be verified; Gemini also requires the model replay group. Preserve the exact prompt prefix for signed thinking. Provider-reported thinking drops and allowed prefix mismatches appear in provider span `attributes.reasoningTransformations`; a successful response does not prove retention. See [the HTTP contract](../../docs/api.md#provider-protocols).
+
+### Tool timing
+
+`inputs.handle` and `inputs.poll` record tool-input inspection, claim and response POST phases. A tool handler receives `context.parentSpanId` and `context.recordSpan(span)`; use the latter to attach closed preparation/execution spans without an HTTP call per phase. Child spans are batched with the tool-span close. Keep spans linked to the current input and omit arguments, results and secrets from attributes. The result POST observation is best effort: a request that has already ended rejects late telemetry, without replaying the committed response.
+
+Callback round trips include your handler's processing time. Compare the input wait, tool span and child execution phases rather than adding their overlapping durations. Monotonic `elapsedMs` values are retained in metadata-only telemetry; timestamps across hosts assume aligned clocks.

package/dist/index.js

@@ -202,7 +202,7 @@ class RequestClient {
           status: options2.status ?? closed?.status ?? "ok",
           attributes: options2.attributes ?? closed?.attributes ?? span.attributes
         };
-        return this.#addSpans(id, [closed], signal2);
+        return this.#addSpans(id, [closed, ...options2.spans ?? []], signal2);
       }
     };
   }
@@ -285,7 +285,11 @@ class RequestClient {
   async#processInputs(id, options = {}) {
     const consumerId = options.consumerId ?? uuid7();
     while (true) {
+      const inspectStarted = new Date().toISOString();
+      const inspectClock = performance.now();
       const state = await this.#inspect(id, options.signal);
+      const inspectEnded = new Date().toISOString();
+      const inspectMs = performance.now() - inspectClock;
       options.onUpdate?.(state);
       if (terminal(state.request.status))
         return state;
@@ -351,6 +355,8 @@ class RequestClient {
         }
         if (pending.kind !== "tool")
           continue;
+        const claimStarted = new Date().toISOString();
+        const claimClock = performance.now();
         const tool = options.tools?.[pending.payload.name ?? ""];
         if (!tool && !pending.payload.validationError)
           continue;
@@ -361,8 +367,14 @@ class RequestClient {
             continue;
           throw error;
         }
+        const claimEnded = new Date().toISOString();
+        const claimMs = performance.now() - claimClock;
         await this.#whileClaimed(id, pending.id, consumerId, true, async (activeSignal) => {
           const span = await this.#startSpan(id, `tool.${pending.payload.name}`, { stepId: pending.stepId ?? undefined, inputId: pending.id }, activeSignal);
+          const phases = [
+            { id: uuid7(), inputId: pending.id, name: "caller.input.inspect", startedAt: inspectStarted, endedAt: inspectEnded, status: "ok", attributes: { elapsedMs: inspectMs } },
+            { id: uuid7(), inputId: pending.id, name: "caller.input.claim", startedAt: claimStarted, endedAt: claimEnded, status: "ok", attributes: { elapsedMs: claimMs } }
+          ];
           let result;
           let isError = false;
           let errorDetails;
@@ -375,6 +387,8 @@ class RequestClient {
             result = await bounded(tool(pending.payload.arguments ?? {}, {
               inputId: pending.id,
               requestId: id,
+              parentSpanId: span.id,
+              recordSpan: (phase) => phases.push({ ...phase, inputId: pending.id, parentSpanId: span.id }),
               signal: toolSignal
             }), toolSignal);
           } catch (error) {
@@ -383,9 +397,23 @@ class RequestClient {
             errorDetails = callerErrorDetails(error);
             result = { error: error instanceof Error ? error.message : "Tool failed" };
           }
-          await span.end({ status: isError ? "error" : "ok", ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
+          await span.end({ status: isError ? "error" : "ok", spans: phases, ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
           await this.#claim(id, pending.id, consumerId, activeSignal);
-          await this.#respond(id, pending.id, { result, isError, claimId: consumerId }, activeSignal);
+          const responseStarted = new Date().toISOString();
+          const responseClock = performance.now();
+          let responseStatus = "ok";
+          try {
+            await this.#respond(id, pending.id, { result, isError, claimId: consumerId }, activeSignal);
+          } catch (error) {
+            responseStatus = "error";
+            throw error;
+          } finally {
+            const responseSpan = { id: uuid7(), inputId: pending.id, name: "caller.input.respond", startedAt: responseStarted, endedAt: new Date().toISOString(), status: responseStatus, attributes: { elapsedMs: performance.now() - responseClock } };
+            await this.#addSpans(id, [responseSpan], activeSignal ? AbortSignal.any([activeSignal, AbortSignal.timeout(2000)]) : AbortSignal.timeout(2000)).catch((error) => {
+              if (!(error instanceof ConstellationError && (error.status === 409 || error.status === 404)))
+                console.warn("Constellation input-response timing could not be recorded");
+            });
+          }
         }, options.signal);
         handled = true;
       }

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" | "omitIncompatible";
     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" | "omitIncompatible";
     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;
@@ -269,6 +300,8 @@ export type InputHandlers = {
     tools?: Record<string, (args: Json, context: {
         inputId: string;
         requestId: string;
+        parentSpanId: string;
+        recordSpan: (span: Span) => void;
         signal?: AbortSignal;
     }) => Promise<Json>>;
     userInput?: (state: Inspection, context: {
@@ -307,7 +340,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" | "omitIncompatible";
 };
 export type WebhookEvent = {
     requestId: string;
@@ -336,9 +373,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;
@@ -494,6 +573,7 @@ export declare class RequestClient {
                 endedAt?: string;
                 status?: "ok" | "error" | "cancelled";
                 attributes?: Record<string, Json>;
+                spans?: Span[];
             }, signal?: AbortSignal) => Promise<void>;
         }>;
         add: (requestId: string, spans: Span[], signal?: AbortSignal) => Promise<void>;

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.6.0",
   "description": "TypeScript client for durable model requests and caller events",
   "type": "module",
   "license": "UNLICENSED",