@lionhummer/constellation 0.3.0 → 0.5.0

package/README.md

@@ -94,6 +94,10 @@ Each invocation creates a new request. For application retries, persist the comp
 | `waiting` | Handle the pending input. Tools always require a consumer; wait checkpoints do too. SSE observation does not answer inputs. |
 | `failed` | Inspect `request.reason`, `request.error`, attempts and timeline for provider, routing or deadline failure. |
 
+## Release 0.4.0
+
+Telemetry now returns metadata by default. Use `include: "content"` for full content, with the same permission/scope. Adds key-aware `discover`, explicit request timings, accurate endpoint filter types, HTTP chunk pagination, and billing/traffic methods. Deploy the matching server before using these methods.
+
 ## Release 0.3.0
 
 This pre-1.0 release breaks the earlier SDK contract. Use namespaced execution methods; flat aliases and the old drive/protocol surface are removed. Keys, credentials, users and capacity administration are internal-only. Provider-definition writes also require an internal operator. External telemetry and other registry authoring remain available. Deploy a server containing these API changes before switching clients; publishing this package does not deploy the server or upgrade any downstream application dependency.
@@ -156,3 +160,60 @@ Use the documented namespaces throughout: `requests.create`, `requests.get`,
 `requests.streamEvents`, `inputs.claim`, `inputs.respond`, `spans.start`,
 `spans.add`, and `logs.add`. Their implementation helpers are private; flat
 method aliases are not part of the client API.
+
+## Caller failures and delivery retries
+
+A failed webhook delivery is one attempt, not the final request outcome. Constellation retains failed attempts even when a later retry succeeds. Retryable delivery warnings include the input ID, attempt number, callback HTTP failure and retry delay; terminal failures remain errors. The callback drawer shows that delivery and the current request state.
+
+The SDK records checkpoint and tool exceptions in `attributes.error` on the caller span and preserves the original exception. Root-cause name, bounded message and optional code are included; SQL dumps, stack traces and arbitrary error object fields are omitted, and common credential forms are redacted. This is best-effort redaction: keep sensitive values out of exception messages. Closed error spans with these details produce one linked request error log. Keep complete diagnostics in your application's own logs. Historical spans without error attributes cannot reconstruct the original exception.
+
+## Discover available HTTP operations
+
+```ts
+const contract = await client.discover();
+console.log(contract["x-constellation-access"]);
+console.log(Object.keys(contract.paths));
+```
+
+`discover(signal?)` calls `GET /v1/discover` with the client's bearer key and returns a typed OpenAPI document filtered to that key's permissions and workspace/user scope. It works with execution, management or telemetry keys. `/v1/openapi.json` is the secondary HTTP path. This describes available operations; resource ownership, model access and request lifecycle are still validated when calling them. Discovery does not grant additional access. Requires a server with the discovery endpoint deployed.
+
+## Scoped telemetry and timing
+
+Telemetry returns metadata by default: request identity/status, timestamps, costs, token counts, attempt commitment/fallback flags and record metadata. Full request/log/HTTP content requires `include: "content"`; this uses the same telemetry permission and key scope, with no extra permission. SDK content fields are optional because the default omits them. Workspace and user scope applies to hot and archived requests, events, records, HTTP, timing and timeline navigation. Global telemetry endpoints require an unscoped key.
+
+```typescript
+const page = await client.telemetry.requests.list({ externalId: "thread-123", limit: 25 });
+for (const request of page.items) {
+  const timing = await client.telemetry.requests.getTimings(request.id);
+  console.log(request.status, timing.queueMs, timing.attempts);
+}
+const detail = await client.telemetry.requests.get(requestId, { include: "content" });
+const logs = await client.telemetry.requests.listRecords(requestId, "logs", {
+  level: "warn", offset: 0, limit: 25, include: "content",
+});
+const body = await client.telemetry.requests.getHttpBody(requestId, attemptId, {
+  direction: "response", offset: 0, limit: 16384, include: "content",
+});
+```
+
+`requests.getTimings` is also available with execution authority. Timing responses include admission, queue, worker preparation, provider attempts and caller waits. Admission and preparation have recorded child/detail spans; IDs and provenance match the console. Concurrent waits count once in `callerWaitMs`. Missing/incomplete measurements are null. Read `complete`, `truncated` and `asOf`; grouped totals can overlap and are not additive.
+
+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/index.js

@@ -1,4 +1,22 @@
-// ../../packages/client-core/src/index.ts
+// ../client-core/src/error-details.ts
+function callerErrorDetails(error) {
+  let cause = error;
+  const seen = new Set;
+  for (let depth = 0;depth < 8 && cause instanceof Error && !seen.has(cause); depth++) {
+    seen.add(cause);
+    if (!(cause.cause instanceof Error))
+      break;
+    cause = cause.cause;
+  }
+  const record = cause && typeof cause === "object" ? cause : {};
+  const name = cause instanceof Error ? cause.name.slice(0, 80) : "CallerError";
+  const code = typeof record.code === "string" && /^[a-zA-Z0-9_-]{1,80}$/.test(record.code) ? record.code : undefined;
+  const raw = cause instanceof Error ? cause.message : "Caller handler threw a non-Error value";
+  const message = (/Failed query:|\bparams:/i.test(raw) ? "Caller database operation failed; see caller logs" : raw).replace(/\b(?:Bearer\s+)[^\s,;]+/gi, "Bearer [redacted]").replace(/((?:password|token|secret|api[_-]?key)\s*[=:]\s*)[^\s,;]+/gi, "$1[redacted]").replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@").slice(0, 512);
+  return { name, message, ...code ? { code } : {} };
+}
+
+// ../client-core/src/index.ts
 class ConstellationError extends Error {
   status;
   code;
@@ -306,7 +324,7 @@ class RequestClient {
               await this.#respond(id, pending.id, { ...response, claimId: consumerId }, activeSignal);
             } catch (error) {
               if (!activeSignal?.aborted && !closed)
-                await span.end({ status: "error" }, activeSignal).catch(() => {});
+                await span.end({ status: "error", attributes: { error: callerErrorDetails(error) } }, activeSignal).catch(() => {});
               throw error;
             }
           }, options.signal);
@@ -347,6 +365,7 @@ class RequestClient {
           const span = await this.#startSpan(id, `tool.${pending.payload.name}`, { stepId: pending.stepId ?? undefined, inputId: pending.id }, activeSignal);
           let result;
           let isError = false;
+          let errorDetails;
           try {
             if (pending.payload.validationError)
               throw new Error(pending.payload.validationError);
@@ -361,9 +380,10 @@ class RequestClient {
           } catch (error) {
             activeSignal?.throwIfAborted();
             isError = true;
+            errorDetails = callerErrorDetails(error);
             result = { error: error instanceof Error ? error.message : "Tool failed" };
           }
-          await span.end({ status: isError ? "error" : "ok" }, activeSignal);
+          await span.end({ status: isError ? "error" : "ok", ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
           await this.#claim(id, pending.id, consumerId, activeSignal);
           await this.#respond(id, pending.id, { result, isError, claimId: consumerId }, activeSignal);
         }, options.signal);
@@ -389,13 +409,16 @@ class RequestClient {
       preview: (input, signal) => this.#resolve(input, signal),
       get: (id, signal) => this.#inspect(id, signal),
       getSummary: (id, signal) => this.#inspectSummary(id, signal),
+      getTimings: (id, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/timings`, "GET", undefined, signal),
       list: (query = {}, signal) => this.#list(query, signal),
       cancel: (id, signal) => this.#cancel(id, signal),
       listEvents: (id, after = 0, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/events${queryString({ after })}`, "GET", undefined, signal),
       streamEvents: (id, options = {}) => this.#events(id, options),
       listRecords: (id, kind, query = {}, signal) => this.#records(id, kind, query, signal),
       getTimeline: (id, options = {}) => this.#timeline(id, options),
-      getHttpExchange: (id, attemptId, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}`, "GET", undefined, signal),
+      getHttpExchange: (id, attemptId, query = {}, signal) => {
+        return this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}${queryString(query)}`, "GET", undefined, signal);
+      },
       getHttpBody: (id, attemptId, query, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}/body${queryString(query)}`, "GET", undefined, signal)
     };
   }
@@ -418,7 +441,7 @@ class RequestClient {
   }
 }
 
-// ../../packages/sdk/src/index.ts
+// src/index.ts
 function queryString2(values) {
   const params = new URLSearchParams;
   for (const [key, value] of Object.entries(values))
@@ -462,6 +485,9 @@ class Constellation extends RequestClient {
     }
     return response.status === 204 ? undefined : response.json();
   }
+  discover(signal) {
+    return this.#call("/v1/discover", "GET", undefined, signal);
+  }
   get management() {
     return {
       registry: {
@@ -478,26 +504,39 @@ class Constellation extends RequestClient {
   }
   get telemetry() {
     const requestPath = (id) => `/v1/telemetry/requests/${encodeURIComponent(id)}`;
+    const read = (path, options = {}, extra = {}) => {
+      const value = options;
+      return this.#call(`${path}${queryString2({ ...extra, include: value.include })}`, "GET", undefined, value.signal);
+    };
     return {
       requests: {
         list: (query = {}, signal) => this.#call(`/v1/telemetry/requests${queryString2(query)}`, "GET", undefined, signal),
-        get: (id, signal) => this.#call(requestPath(id), "GET", undefined, signal),
-        getSummary: (id, signal) => this.#call(`${requestPath(id)}?summary=true`, "GET", undefined, signal),
-        listEvents: (id, after = 0, signal) => this.#call(`${requestPath(id)}/events${queryString2({ after })}`, "GET", undefined, signal),
+        get: (id, options = {}) => read(requestPath(id), options),
+        getSummary: (id, options = {}) => read(requestPath(id), options, { summary: "true" }),
+        getTimings: (id, signal) => this.#call(`${requestPath(id)}/timings`, "GET", undefined, signal),
+        listEvents: (id, after = 0, options = {}) => read(`${requestPath(id)}/events`, options, { after }),
         listRecords: (id, kind, query = {}, signal) => this.#call(`${requestPath(id)}/records/${kind}${queryString2(query)}`, "GET", undefined, signal),
-        getTimeline: (id, options = {}) => this.#call(`${requestPath(id)}/timeline${queryString2({ requestId: options.requestId })}`, "GET", undefined, options.signal),
-        getHttpExchange: (id, attemptId, signal) => this.#call(`${requestPath(id)}/http/${encodeURIComponent(attemptId)}`, "GET", undefined, signal),
+        getTimeline: (id, options = {}) => read(`${requestPath(id)}/timeline`, options, { requestId: options.requestId }),
+        getHttpExchange: (id, attemptId, options = {}) => {
+          const value = options;
+          return read(`${requestPath(id)}/http/${encodeURIComponent(attemptId)}`, value, { offset: value.offset, limit: value.limit });
+        },
         getHttpBody: (id, attemptId, query, signal) => this.#call(`${requestPath(id)}/http/${encodeURIComponent(attemptId)}/body${queryString2(query)}`, "GET", undefined, signal)
       },
       system: {
-        get: (signal) => this.#call("/v1/telemetry/system", "GET", undefined, signal),
+        get: (options = {}) => read("/v1/telemetry/system", options),
         listHistory: (query = {}, signal) => this.#call(`/v1/telemetry/system/history${queryString2(query)}`, "GET", undefined, signal),
-        getComponent: (component, signal) => this.#call(`/v1/telemetry/system/${encodeURIComponent(component)}`, "GET", undefined, signal)
+        getComponent: (component, options = {}) => {
+          const value = options;
+          return read(`/v1/telemetry/system/${encodeURIComponent(component)}`, value, { offset: value.offset, status: value.status, statusNot: value.statusNot, q: value.q });
+        }
       },
       observability: {
         get: (query = {}, signal) => this.#call(`/v1/telemetry/observability${queryString2(query)}`, "GET", undefined, signal),
         getSeries: (query, signal) => this.#call(`/v1/telemetry/observability/series${queryString2(query)}`, "GET", undefined, signal),
-        getTiming: (query = {}, signal) => this.#call(`/v1/telemetry/observability/timing${queryString2(query)}`, "GET", undefined, signal)
+        getTiming: (query = {}, signal) => this.#call(`/v1/telemetry/observability/timing${queryString2(query)}`, "GET", undefined, signal),
+        getTraffic: (query = {}, signal) => this.#call(`/v1/telemetry/observability/traffic${queryString2(query)}`, "GET", undefined, signal),
+        getBilling: (query = {}, signal) => this.#call(`/v1/telemetry/observability/billing${queryString2(query)}`, "GET", undefined, signal)
       },
       jobs: {
         listHistory: (query = {}, signal) => this.#call(`/v1/telemetry/jobs/history${queryString2(query)}`, "GET", undefined, signal)

package/dist/types/client-core/src/error-details.d.ts

@@ -0,0 +1,6 @@
+/** Error telemetry deliberately omits stack traces and arbitrary object fields. */
+export declare function callerErrorDetails(error: unknown): {
+    name: string;
+    message: string;
+    code?: string;
+};

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";
         } | {
@@ -91,6 +114,9 @@ export type RequestRecord = {
     resolution: Json;
     rules: Json;
     createdAt: string;
+    receivedAt: string | null;
+    queuedAt: string | null;
+    claimedAt: string | null;
     endedAt: string | null;
     deadline: string;
 };
@@ -123,6 +149,8 @@ export type Attempt = {
     providerId: string;
     offeringId: string;
     providerModel: string;
+    providerResponseId?: string | null;
+    cacheDiagnostics?: Json | null;
     connectionKind: string;
     endpoint: string;
     fallback: boolean;
@@ -151,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;
 };
@@ -171,6 +203,8 @@ export type PendingInput = {
         customerCost?: string | null;
         supplierCost?: string | null;
         customerPrice?: Json;
+        customerPricing?: CustomerPricing;
+        billing?: BillingFacts;
         output?: Json;
     };
     claimId: string | null;
@@ -194,7 +228,7 @@ export type TimelineRow = {
     id: string;
     requestId: string;
     parentId: string | null;
-    kind: "request" | "step" | "attempt" | "input" | "span" | "phase" | "http_phase";
+    kind: "request" | "step" | "attempt" | "input" | "span" | "phase" | "http_phase" | "delivery";
     label: string;
     status: string;
     start: string;
@@ -304,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;
@@ -327,6 +365,97 @@ export declare class ConstellationError extends Error {
     constructor(status: number, code: string, message: string);
 }
 export declare function uuid7(): string;
+/** Provider-reported token counts. Missing usage is unknown, not zero. */
+export type TokenUsage = {
+    inputTokens?: number;
+    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;
+    parentId?: string | null;
+    start: string;
+    end: string | null;
+    durationMs: number | null;
+    kind?: string;
+    name?: string;
+    source?: string;
+    label?: string;
+    origin?: "recorded" | "derived";
+    derivedFrom?: string[];
+    providerId?: string;
+    actualModel?: string;
+    offeringId?: string;
+    committed?: boolean;
+    fallback?: boolean;
+    status?: string;
+    ttftMs?: number | null;
+    ttfbMs?: number | null;
+    reasoningMs?: number | null;
+    outputMs?: number | null;
+    httpStatus?: number | null;
+};
+export type RequestTimings = {
+    requestId: string;
+    totalMs: number | null;
+    admissionMs: number | null;
+    queueMs: number | null;
+    workerPreparationMs: number | null;
+    attemptMs: number | null;
+    callerWaitMs: number | null;
+    phases: TimingInterval[];
+    attempts: TimingInterval[];
+    callerWaits: TimingInterval[];
+    asOf: string;
+    complete: boolean;
+    truncated: boolean;
+};
 export type RequestRecordsQuery = {
     id?: string;
     q?: string;
@@ -393,6 +522,7 @@ export declare class RequestClient {
         }>;
         get: (id: string, signal?: AbortSignal) => Promise<Inspection>;
         getSummary: (id: string, signal?: AbortSignal) => Promise<Inspection>;
+        getTimings: (id: string, signal?: AbortSignal) => Promise<RequestTimings>;
         list: (query?: RequestListQuery, signal?: AbortSignal) => Promise<{
             items: RequestRecord[];
             total: number;
@@ -417,7 +547,10 @@ export declare class RequestClient {
             requestId?: string;
             signal?: AbortSignal;
         }) => Promise<Timeline>;
-        getHttpExchange: (id: string, attemptId: string, signal?: AbortSignal) => Promise<Json>;
+        getHttpExchange: (id: string, attemptId: string, query?: {
+            offset?: number;
+            limit?: number;
+        }, signal?: AbortSignal) => Promise<Json>;
         getHttpBody: (id: string, attemptId: string, query: {
             direction: "request" | "response";
             offset?: number;

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

@@ -1,7 +1,97 @@
 /** 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 Inspection, type RequestEvent, type RecordTypes, type Timeline } from "../../client-core/src/index";
+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, 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;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    paths: Record<string, Record<string, Json>>;
+    components: {
+        schemas: Record<string, Json>;
+        securitySchemes: Record<string, Json>;
+    };
+    "x-constellation-access": {
+        permissions: string[];
+        workspaceId: string | null;
+        userId: string | null;
+    };
+};
+/** Telemetry excludes request/log/HTTP content unless explicitly requested. No additional permission is required. */
+export type TelemetryPage<T> = Page<T> & {
+    metadataOnly?: true;
+};
+export type TelemetryQuery = {
+    include?: "content";
+};
+export type TelemetryReadOptions = TelemetryQuery & {
+    signal?: AbortSignal;
+};
+export type PaginationQuery = {
+    offset?: number;
+    limit?: number;
+};
+export type OperationsQuery = {
+    offset?: number;
+    status?: string;
+    statusNot?: string;
+    q?: string;
+};
+export type ObservabilityQuery = PaginationQuery & {
+    hours?: 1 | 24 | 168;
+    providerId?: string;
+    modelId?: string;
+    upstream?: string;
+    q?: string;
+};
+export type LogSearchQuery = PaginationQuery & {
+    q?: string;
+    level?: "trace" | "debug" | "info" | "warn" | "error";
+    levelNot?: "trace" | "debug" | "info" | "warn" | "error";
+    target?: string;
+    targetNot?: string;
+    requestId?: string;
+    requestIdNot?: string;
+    from?: string;
+    to?: string;
+};
+type OptionalContent<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type TelemetryRequest = OptionalContent<RequestRecord, "output" | "error" | "reason" | "resolution" | "rules">;
+export type TelemetryRecords = {
+    steps: OptionalContent<RecordTypes["steps"], "input" | "output" | "resolution" | "rules" | "customerPrice">;
+    attempts: OptionalContent<RecordTypes["attempts"], "endpoint" | "parameters" | "supplierPrice" | "customerPrice" | "error">;
+    inputs: Partial<RecordTypes["inputs"]> & {
+        id: string;
+        requestId: string;
+    };
+    spans: Partial<RecordTypes["spans"]> & {
+        id: string;
+        requestId: string;
+    };
+    logs: OptionalContent<RecordTypes["logs"], "message" | "attributes">;
+};
+export type TelemetryTimeline = Omit<Timeline, "rows"> & {
+    metadataOnly?: true;
+    rows: (Omit<TimelineRow, "label"> & {
+        label?: string;
+    })[];
+};
+export type TelemetryInspection = {
+    metadataOnly?: true;
+    request: TelemetryRequest;
+    usage?: TokenUsage;
+    input?: Json;
+    effectiveInput?: Json;
+    steps: TelemetryRecords["steps"][];
+    attempts: TelemetryRecords["attempts"][];
+    inputs: TelemetryRecords["inputs"][];
+    spans: TelemetryRecords["spans"][];
+    logs: TelemetryRecords["logs"][];
+};
 export declare class Constellation extends RequestClient {
     #private;
     constructor(options: {
@@ -10,6 +100,8 @@ export declare class Constellation extends RequestClient {
         fetch?: typeof fetch;
         timeoutMs?: number;
     });
+    /** Discover HTTP operations available to this bearer key. */
+    discover(signal?: AbortSignal): Promise<DiscoveryDocument>;
     /** Registry authoring only; keys, credentials and capacity controls are internal. */
     get management(): {
         registry: {
@@ -20,7 +112,7 @@ export declare class Constellation extends RequestClient {
                 catalog: Json;
             }, signal?: AbortSignal) => Promise<Json>;
             applyChanges: (changes: Json[], signal?: AbortSignal) => Promise<Json>;
-            listHistory: (kind: string, id: string, query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            listHistory: (kind: string, id: string, query?: PaginationQuery, signal?: AbortSignal) => Promise<Page<Json>>;
             rollback: (kind: string, id: string, input: {
                 toVersion: number;
                 expectedVersion: number;
@@ -32,62 +124,84 @@ export declare class Constellation extends RequestClient {
             }, signal?: AbortSignal) => Promise<Json>;
         };
     };
-    /** Read-only operational endpoints require a telemetry key. */
+    /** Request reads enforce key scope; global operational reads require an unscoped telemetry key. Metadata is the default. */
     get telemetry(): {
         requests: {
-            list: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<RequestRecord>>;
-            get: (id: string, signal?: AbortSignal) => Promise<Inspection>;
-            getSummary: (id: string, signal?: AbortSignal) => Promise<Inspection>;
-            listEvents: (id: string, after?: number, signal?: AbortSignal) => Promise<{
+            list: (query?: RequestListQuery & TelemetryQuery, signal?: AbortSignal) => Promise<TelemetryPage<TelemetryRequest>>;
+            get: (id: string, options?: TelemetryReadOptions) => Promise<TelemetryInspection>;
+            getSummary: (id: string, options?: TelemetryReadOptions) => Promise<TelemetryInspection>;
+            getTimings: (id: string, signal?: AbortSignal) => Promise<RequestTimings>;
+            listEvents: (id: string, after?: number, options?: TelemetryReadOptions) => Promise<{
                 items: RequestEvent[];
+                metadataOnly?: true;
             }>;
-            listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: PageQuery, signal?: AbortSignal) => Promise<Page<RecordTypes[K]>>;
-            getTimeline: (id: string, options?: {
+            listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: RequestRecordsQuery & TelemetryQuery, signal?: AbortSignal) => Promise<TelemetryPage<TelemetryRecords[K]>>;
+            getTimeline: (id: string, options?: TelemetryReadOptions & {
                 requestId?: string;
-                signal?: AbortSignal;
-            }) => Promise<Timeline>;
-            getHttpExchange: (id: string, attemptId: string, signal?: AbortSignal) => Promise<Json>;
-            getHttpBody: (id: string, attemptId: string, query: {
+            }) => Promise<TelemetryTimeline>;
+            getHttpExchange: (id: string, attemptId: string, options?: TelemetryReadOptions & PaginationQuery) => Promise<Json>;
+            getHttpBody: (id: string, attemptId: string, query: TelemetryQuery & {
                 direction: "request" | "response";
                 offset?: number;
                 limit?: number;
             }, signal?: AbortSignal) => Promise<Json>;
         };
         system: {
-            get: (signal?: AbortSignal) => Promise<Json>;
-            listHistory: (query?: {
+            get: (options?: TelemetryReadOptions) => Promise<Json>;
+            listHistory: (query?: TelemetryQuery & {
                 hours?: 1 | 24 | 168;
             }, signal?: AbortSignal) => Promise<Json>;
-            getComponent: (component: string, signal?: AbortSignal) => Promise<Json>;
+            getComponent: (component: string, options?: TelemetryReadOptions & OperationsQuery) => Promise<Json>;
         };
         observability: {
-            get: (query?: PageQuery, signal?: AbortSignal) => Promise<Json>;
-            getSeries: (query: {
-                source: "local" | "gateway";
+            get: (query?: ObservabilityQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Json>;
+            getSeries: (query: TelemetryQuery & {
                 hours?: 1 | 24 | 168;
-                providerId?: string;
                 modelId?: string;
+            } & ({
+                source: "local";
+                providerId?: string;
+                upstream?: never;
+            } | {
+                source: "gateway";
+                upstream?: string;
+                providerId?: never;
+            }), signal?: AbortSignal) => Promise<Json>;
+            getTiming: (query?: TelemetryQuery & {
+                hours?: 1 | 24 | 168;
             }, signal?: AbortSignal) => Promise<Json>;
-            getTiming: (query?: {
+            getTraffic: (query?: TelemetryQuery & {
                 hours?: 1 | 24 | 168;
             }, signal?: AbortSignal) => Promise<Json>;
+            getBilling: (query?: PaginationQuery & TelemetryQuery & {
+                hours?: 1 | 24 | 168 | 720;
+                providerId?: string;
+                modelId?: string;
+                groupBy?: "provider" | "model";
+            }, signal?: AbortSignal) => Promise<Json>;
         };
         jobs: {
-            listHistory: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            listHistory: (query?: OperationsQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Json>;
         };
         notifications: {
-            list: (query?: PageQuery & {
+            list: (query?: TelemetryQuery & {
+                offset?: number;
                 status?: "active" | "resolved";
-            }, signal?: AbortSignal) => Promise<Page<Json>>;
-            get: (id: string, query?: PageQuery, signal?: AbortSignal) => Promise<Json>;
-            listEvents: (query?: {
+            }, signal?: AbortSignal) => Promise<Json>;
+            get: (id: string, query?: TelemetryQuery & {
+                offset?: number;
+            }, signal?: AbortSignal) => Promise<Json>;
+            listEvents: (query?: TelemetryQuery & {
                 after?: number;
             }, signal?: AbortSignal) => Promise<Json>;
         };
         logs: {
-            searchSystem: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            searchRequests: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            searchAudit: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            searchSystem: (query?: LogSearchQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            searchRequests: (query?: Omit<LogSearchQuery, "level" | "levelNot" | "target" | "targetNot"> & {
+                level?: "debug" | "info" | "warn" | "error";
+                levelNot?: "debug" | "info" | "warn" | "error";
+            } & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            searchAudit: (query?: Omit<LogSearchQuery, "requestId" | "requestIdNot"> & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
         };
     };
     get webhooks(): {

package/package.json

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