@lionhummer/constellation 0.9.1 → 0.9.4

package/README.md

@@ -341,8 +341,67 @@ tools: {
 },
 ```
 
+Work you do before the first model step, such as loading context and building the prompt, can travel with the request that starts the run: pass `telemetry: { spans, logs }` to `requests.submit`. Those spans belong to the request rather than a step: they sit at the top of the timeline at their own timestamps, before the first step (set `stepId` or `parentSpanId` to nest them elsewhere).
+
 The SDK records `client.processing` and one span per tool automatically. A response carries at most 512 spans, 128 logs and 1 MiB of telemetry; the SDK trims larger batches and records what it omitted. Do not put secrets or personal data in span names, attributes or log messages.
 
+## Opening lines
+
+Show a one-sentence opener while the real step is prepared. The operator configures its model and prompt in Constellation.
+
+```ts
+const opener = await client.openers.create({
+  idempotencyKey: `${turnId}`,
+  workspaceId, userId, externalId: threadId,
+  message,
+  history: recentTurns, // [{ role: "user" | "assistant", text }], oldest first
+})
+if (opener) void client.openers.sentence(opener.id).then((sentence) => {
+  if (sentence && !realOutputStarted) show(sentence)
+})
+```
+
+Start the real request without waiting for the opener. `parseOpenerSentence(text)` applies the same checks to text you already have.
+
+## Telemetry queries
+
+Ask aggregate questions without SQL. Fields, filters and metrics are typed per dataset.
+
+```ts
+// How many fireworks-direct attempts failed yesterday, and why?
+const failures = await client.telemetry.query({
+  dataset: "attempts",
+  from: "2026-10-15T00:00:00Z", to: "2026-10-16T00:00:00Z",
+  where: { offeringId: { startsWith: "fireworks-direct:" }, status: "failed" },
+  groupBy: ["errorCode", "httpStatus"],
+  metrics: ["count", "uniq:requestId"],
+})
+
+// How often did a provider say "Response too long", per day?
+const mentions = await client.telemetry.query({
+  dataset: "attempts",
+  from: "2026-10-01T00:00:00Z", to: "2026-10-16T00:00:00Z",
+  where: { errorMessage: { contains: "Response too long" } },
+  groupBy: ["day"],
+})
+```
+
+Usage and costs come from the permanent billing record (`usage`, one row per settled request, or `usageAttempts`, one row per provider attempt for provider/model splits). Any range works:
+
+```ts
+// Customer charges, supplier cost and margin per workspace and provider last month, without QA
+const byProvider = await client.telemetry.query({
+  dataset: "usageAttempts",
+  from: "2026-09-01T00:00:00Z", to: "2026-10-01T00:00:00Z",
+  where: { workspaceId: { notIn: ["qa"] } },
+  groupBy: ["workspaceId", "providerId"],
+  metrics: ["uniq:requestId", "sum:customerCost", "sum:supplierCost", "sum:margin"],
+  limit: 10000,
+})
+```
+
+A scoped key only ever sees its workspace and user. Logs and usage need an unscoped key. Telemetry ranges are at most 92 days and results at most 1,000 rows; usage allows any range and 10,000 rows. Group by `minute`, `hour`, `day`, `week` or `month` for time series.
+
 ## Limits and timeouts
 
 | Setting | Default | Notes |
@@ -367,6 +426,7 @@ A failed provider call falls back to the next provider only before any output ha
 | `requests.submit(input)` | Start a request, continue it (`inReplyTo`), or stop it (`action: "observe"`). |
 | `requests.preview(input)` | Validate a complete input and show routing, without calling a provider. |
 | `requests.cancel(id)` | Cancel a request. |
+| `openers.create(input)`, `openers.sentence(id)` | Start an opening line for a just-sent message (null when openers are turned off), then wait for its sentence (null when skipped or failed). |
 | `requests.getState(id)` | Committed state: status, steps, attempt outcomes, usage and cost. |
 | `requests.getSummary(id)`, `requests.get(id)` | Request detail, without or with spans and logs. |
 | `requests.list(query)` | Page through requests, e.g. by `externalId` or `status`. |
@@ -375,6 +435,7 @@ A failed provider call falls back to the next provider only before any output ha
 | `requests.getTimeline(id)`, `requests.getTimings(id)` | Trace and timing breakdown. |
 | `requests.getHttpExchange(id, attemptId)`, `requests.getHttpBody(...)` | The provider HTTP call captured for one attempt. |
 | `webhooks.verify(request, token)` | Authenticate and parse an incoming webhook. |
+| `telemetry.query(query)` | Count, group and aggregate attempts, requests, logs or permanent usage, e.g. failed attempts per offering and error code, or cost per workspace and provider. Needs telemetry permission; the key's scope always applies. |
 | `telemetry.*` | Read-only reporting. Returns metadata only unless you pass `include: "content"`. Needs telemetry permission. |
 | `management.registry.*` | Edit the model registry. Needs management permission. |
 | `discover()` | The OpenAPI document for exactly what this key may call. |

package/dist/index.js

@@ -1,4 +1,15 @@
 // ../client-core/src/index.ts
+function parseOpenerSentence(raw, maxWords = 25) {
+  const text = raw.trim();
+  if (!text || /^SKIP\b/i.test(text))
+    return null;
+  const sentence = (text.match(/^.+?[.!](?=\s|[A-Z]|$)/)?.[0] ?? text).trim();
+  if (sentence.includes("`") || sentence.includes(`
+`) || sentence.split(/\s+/).length > maxWords)
+    return null;
+  return sentence;
+}
+
 class ConstellationError extends Error {
   status;
   code;
@@ -300,6 +311,30 @@ class RequestClient {
       resolve: (input, signal) => this.#call("/v1/registry/resolve", "POST", input, signal)
     };
   }
+  get openers() {
+    return {
+      create: async (input, signal) => await this.#call("/v1/openers", "POST", input, signal) ?? null,
+      sentence: async (id, options = {}) => {
+        let text = "";
+        for await (const event of this.#events(id, { signal: options.signal })) {
+          if (event.type === "model.completed") {
+            const message = event.data.message;
+            text = message?.text ?? text;
+            break;
+          }
+          if (event.type === "model.failed" || event.type === "model.cancelled")
+            return null;
+          if (event.type === "model.delta") {
+            for (const entry of event.data.events ?? []) {
+              if (entry.event?.type === "text_delta")
+                text += entry.event.delta ?? "";
+            }
+          }
+        }
+        return parseOpenerSentence(text, options.maxWords);
+      }
+    };
+  }
   get requests() {
     return {
       submit: (input, signal) => this.#submit(input, signal),
@@ -729,6 +764,10 @@ class Constellation extends RequestClient {
         get: (id, query = {}, signal) => this.#call(`/v1/telemetry/notifications/${encodeURIComponent(id)}${queryString2(query)}`, "GET", undefined, signal),
         listEvents: (query = {}, signal) => this.#call(`/v1/telemetry/notifications/events${queryString2(query)}`, "GET", undefined, signal)
       },
+      query: (query, signal) => {
+        const iso = (value) => value instanceof Date ? value.toISOString() : value;
+        return this.#call("/v1/telemetry/query", "POST", { ...query, from: iso(query.from), to: iso(query.to) }, signal);
+      },
       logs: {
         searchSystem: (query = {}, signal) => this.#call(`/v1/telemetry/logs/system${queryString2(query)}`, "GET", undefined, signal),
         searchRequests: (query = {}, signal) => this.#call(`/v1/telemetry/logs/requests${queryString2(query)}`, "GET", undefined, signal),
@@ -770,6 +809,7 @@ export {
   uuid7,
   processEvent,
   prepareResponse,
+  parseOpenerSentence,
   normalizeTimestamp,
   PermanentEventError,
   PERMANENT_RESPONSE_CODES,

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

@@ -304,6 +304,24 @@ export type ModelDeltaEvent = {
     };
 };
 export type RequestEvent = WebhookEvent | ModelDeltaEvent;
+export type OpenerTurn = {
+    role: "user" | "assistant";
+    text: string;
+};
+export type OpenerInput = {
+    /** Stable per turn, so a retry never admits a second opener. */
+    idempotencyKey: string;
+    workspaceId: string;
+    userId?: string;
+    externalId?: string;
+    planId?: string;
+    /** The message the user just sent. */
+    message: string;
+    /** Earlier turns, oldest first; operator settings decide how many are used. */
+    history?: OpenerTurn[];
+};
+/** The opener line to show: one sentence, no code, within `maxWords`; null for SKIP or anything else. */
+export declare function parseOpenerSentence(raw: string, maxWords?: number): string | null;
 export type Page<T> = {
     items: T[];
     total: number;
@@ -503,6 +521,22 @@ export declare class RequestClient {
         list: (scope: ModelScope, signal?: AbortSignal) => Promise<Json>;
         resolve: (input: ModelResolution, signal?: AbortSignal) => Promise<Json>;
     };
+    /**
+     * Opening lines: an operator-configured short model call, made when the user
+     * sends, naming what the assistant does first. create admits it as an
+     * ordinary request; sentence waits for it to end and returns the line to
+     * show, or null for SKIP, a failure, or an answer that breaks the format.
+     */
+    get openers(): {
+        /** The opener request, or null when the operator has turned openers off. */
+        create: (input: OpenerInput, signal?: AbortSignal) => Promise<{
+            id: string;
+        } | null>;
+        sentence: (id: string, options?: {
+            signal?: AbortSignal;
+            maxWords?: number;
+        }) => Promise<string | null>;
+    };
     /** Durable requests. create returns an ID; execution continues independently. */
     get requests(): {
         submit: (input: Admission, signal?: AbortSignal) => Promise<AdmissionReceipt>;

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, normalizeTimestamp } from "../../client-core/src/index";
-export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, Admission, AdmissionReceipt, ResponseOutcome, ObservationResponse, Observations, EventReference, ModelCompletedEvent, ModelDeltaEvent, ModelStreamFrame, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery } from "../../client-core/src/index";
+export { ConstellationError, uuid7, normalizeTimestamp, parseOpenerSentence } from "../../client-core/src/index";
+export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, Admission, AdmissionReceipt, ResponseOutcome, ObservationResponse, Observations, EventReference, ModelCompletedEvent, ModelDeltaEvent, ModelStreamFrame, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, OpenerInput, OpenerTurn } from "../../client-core/src/index";
 /** OpenAPI contract filtered to this key's permissions and scope. */
 export type DiscoveryDocument = {
     openapi: string;
@@ -28,6 +28,63 @@ export type TelemetryPage<T> = Page<T> & {
 export type TelemetryQuery = {
     include?: "content";
 };
+/** Fields of each aggregate dataset, as POST /v1/telemetry/query accepts them. */
+export type AttemptField = "workspaceId" | "userId" | "externalId" | "requestId" | "providerId" | "offeringId" | "model" | "requestedModel" | "status" | "fallback" | "dispatched" | "errorCode" | "faultClass" | "httpStatus" | "errorMessage";
+export type AttemptNumber = "ttftMs" | "latencyMs" | "outputTokens" | "supplierCost" | "customerCost" | "httpStatus";
+export type RequestField = "workspaceId" | "userId" | "externalId" | "requestId" | "requestedModel" | "status";
+export type RequestNumber = "durationMs" | "supplierCost" | "customerCost";
+export type LogField = "level" | "name" | "status" | "requestId" | "message";
+/** Permanent billing record per settled request (unscoped telemetry keys only). */
+export type UsageField = "workspaceId" | "userId" | "externalId" | "requestId" | "requestedModel" | "planId" | "status";
+type UsageTotals = "supplierCost" | "customerCost" | "margin" | "inputTokens" | "cacheReadTokens" | "cacheWriteTokens" | "cacheWriteOneHourTokens" | "outputTokens" | "reasoningTokens";
+export type UsageNumber = UsageTotals | "durationMs";
+/** Permanent billing record per provider attempt; `status` is the attempt's, `requestStatus` the request's. */
+export type UsageAttemptField = Exclude<UsageField, "status"> | "requestStatus" | "providerId" | "model" | "providerModel" | "status";
+export type UsageAttemptNumber = UsageTotals;
+export type AggregateTimeGroup = "minute" | "hour" | "day" | "week" | "month";
+export type AggregateScalar = string | number | boolean;
+/** A value, any of several values, or operators combined with AND. `contains` is case-insensitive. */
+export type AggregateFilter = AggregateScalar | AggregateScalar[] | {
+    eq?: AggregateScalar;
+    in?: AggregateScalar[];
+    not?: AggregateScalar;
+    notIn?: AggregateScalar[];
+    contains?: string;
+    startsWith?: string;
+    gte?: number;
+    gt?: number;
+    lte?: number;
+    lt?: number;
+    /** true: the field has a value; false: it is empty. */
+    exists?: boolean;
+};
+export type AggregateMetric<N extends string, F extends string> = "count" | `uniq:${F}` | `${"sum" | "avg" | "min" | "max" | "p50" | "p90" | "p95" | "p99"}:${N}`;
+type AggregateShape<D extends string, F extends string, N extends string> = {
+    dataset: D;
+    /** Inclusive start and exclusive end; at most 92 days apart (usage datasets: any range). */
+    from: string | Date;
+    to: string | Date;
+    where?: Partial<Record<F | N, AggregateFilter>>;
+    /** At most four. Numeric fields other than httpStatus are aggregated, not grouped. */
+    groupBy?: (F | AggregateTimeGroup)[];
+    /** One to eight; default ["count"]. */
+    metrics?: AggregateMetric<N, F>[];
+    orderBy?: {
+        by: string;
+        descending?: boolean;
+    };
+    /** Default 100, at most 1,000 rows (usage datasets: 10,000). */
+    limit?: number;
+};
+/** A structured aggregate over telemetry facts or permanent usage. The key's workspace/user scope always applies; logs and usage need an unscoped key. */
+export type AggregateQuery = AggregateShape<"attempts", AttemptField, AttemptNumber> | AggregateShape<"requests", RequestField, RequestNumber> | AggregateShape<"logs", LogField, never> | AggregateShape<"usage", UsageField, UsageNumber> | AggregateShape<"usageAttempts", UsageAttemptField, UsageAttemptNumber>;
+export type AggregateResult = {
+    /** Groupings first, then metrics, in request order. */
+    columns: string[];
+    rows: Record<string, Json>[];
+    /** More groups matched than `limit`. */
+    truncated: boolean;
+};
 export type TelemetryReadOptions = TelemetryQuery & {
     signal?: AbortSignal;
 };
@@ -191,6 +248,8 @@ export declare class Constellation extends RequestClient {
                 after?: number;
             }, signal?: AbortSignal) => Promise<Json>;
         };
+        /** Count, group and aggregate attempts, requests or logs, e.g. failed attempts per offering and error code. */
+        query: (query: AggregateQuery, signal?: AbortSignal) => Promise<AggregateResult>;
         logs: {
             searchSystem: (query?: LogSearchQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
             searchRequests: (query?: Omit<LogSearchQuery, "level" | "levelNot" | "target" | "targetNot"> & {

package/package.json

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