@lionhummer/constellation 0.2.0 → 0.4.0

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/{index.d.ts → types/client-core/src/index.d.ts}

@@ -1,4 +1,4 @@
-/** Durable request client. No provider credentials or application policy live here. */
+/** Shared execution wire types and client mechanics. Authentication belongs to each client. */
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -91,6 +91,9 @@ export type RequestRecord = {
     resolution: Json;
     rules: Json;
     createdAt: string;
+    receivedAt: string | null;
+    queuedAt: string | null;
+    claimedAt: string | null;
     endedAt: string | null;
     deadline: string;
 };
@@ -194,7 +197,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;
@@ -327,106 +330,102 @@ export declare class ConstellationError extends Error {
     constructor(status: number, code: string, message: string);
 }
 export declare function uuid7(): string;
-export declare class Constellation {
-    private options;
-    private fetcher;
-    constructor(options: {
-        baseUrl: string;
-        apiKey?: string;
-        apiPrefix?: "/v1" | "/internal";
-        fetch?: typeof fetch;
-        timeoutMs?: number;
-    });
-    private url;
-    private call;
-    submit(input: RequestInput, signal?: AbortSignal): Promise<{
-        id: string;
-    }>;
-    inspect(id: string, signal?: AbortSignal): Promise<Inspection>;
-    /** Canonical API timeline shared with the console. Derived rows disclose their timestamp basis. */
-    timeline(id: string, options?: {
-        requestId?: string;
-        signal?: AbortSignal;
-    }): Promise<Timeline>;
-    /** Request context without loading historical telemetry. Fetch records by page. */
-    inspectSummary(id: string, signal?: AbortSignal): Promise<Inspection>;
-    records<K extends keyof RecordTypes>(id: string, kind: K, query?: {
-        id?: string;
-        q?: string;
-        level?: Log["level"];
-        offset?: number;
-        limit?: number;
-    }, signal?: AbortSignal): Promise<{
-        items: RecordTypes[K][];
-        total: number;
-        offset: number;
-        limit: number;
-    }>;
-    resolve(input: RequestInput, signal?: AbortSignal): Promise<{
-        revision: number;
-        resolution: Record<string, Json>;
-        rules: Record<string, Json>;
-        allowed: boolean;
-        dispatched: false;
-    }>;
-    list(query?: {
-        q?: string;
-        requestId?: string;
-        requestIdNot?: string;
-        externalId?: string;
-        externalIdNot?: string;
-        externalIdContains?: string;
-        externalIdNotContains?: string;
-        workspaceId?: string;
-        workspaceIdNot?: string;
-        userId?: string;
-        userIdNot?: string;
-        status?: Status;
-        statusNot?: Status;
-        requestedModel?: string;
-        requestedModelNot?: string;
-        requestedModelContains?: string;
-        requestedModelNotContains?: string;
-        limit?: number;
-        offset?: number;
-    }, signal?: AbortSignal): Promise<{
-        items: RequestRecord[];
-        total: number;
-        offset: number;
-        limit: number;
-    }>;
-    cancel(id: string, signal?: AbortSignal): Promise<void>;
-    claim(id: string, inputId: string, claimId: string, signal?: AbortSignal): Promise<void>;
+/** Provider-reported token counts. Missing usage is unknown, not zero. */
+export type TokenUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    partial?: boolean;
+};
+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;
+    level?: Log["level"];
+    offset?: number;
+    limit?: number;
+};
+export type RequestListQuery = {
+    q?: string;
+    requestId?: string;
+    requestIdNot?: string;
+    externalId?: string;
+    externalIdNot?: string;
+    externalIdContains?: string;
+    externalIdNotContains?: string;
+    workspaceId?: string;
+    workspaceIdNot?: string;
+    userId?: string;
+    userIdNot?: string;
+    status?: Status;
+    statusNot?: Status;
+    requestedModel?: string;
+    requestedModelNot?: string;
+    requestedModelContains?: string;
+    requestedModelNotContains?: string;
+    limit?: number;
+    offset?: number;
+};
+export type StartSpanOptions = {
+    stepId?: string;
+    attemptId?: string;
+    inputId?: string;
+    parentSpanId?: string;
+    startedAt?: string;
+    attributes?: Record<string, Json>;
+};
+type ClientOptions = {
+    baseUrl: string;
+    apiPrefix?: "/v1" | "/internal";
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+export declare class RequestClient {
+    #private;
+    constructor(options: ClientOptions);
     /** Agent claims are leases. Keep one alive while a caller handler is running. */
     private maintainClaim;
-    private whileClaimed;
-    respond(id: string, inputId: string, response: InputResponse, signal?: AbortSignal): Promise<void>;
-    addSpans(id: string, spans: Span[], signal?: AbortSignal): Promise<void>;
-    addLogs(id: string, logs: Log[], signal?: AbortSignal): Promise<void>;
-    startSpan(id: string, name: string, options?: {
-        stepId?: string;
-        attemptId?: string;
-        inputId?: string;
-        parentSpanId?: string;
-        startedAt?: string;
-        attributes?: Record<string, Json>;
-    }, signal?: AbortSignal): Promise<{
-        id: string;
-        end: (options?: {
-            endedAt?: string;
-            status?: "ok" | "error" | "cancelled";
-            attributes?: Record<string, Json>;
-        }, signal?: AbortSignal) => Promise<void>;
-    }>;
-    /** Live SSE delivery with durable cursor replay after disconnects. */
-    events(id: string, options?: {
-        after?: number;
-        signal?: AbortSignal;
-    }): AsyncGenerator<RequestEvent>;
-    /** Process one delivered input and exit. An input notification can be retried safely. */
-    private handleInput;
-    /** Handle pending inputs until the request ends. */
-    private processInputs;
     /** Client-safe discovery with an execution key. */
     get models(): {
         list: (scope: ModelScope, signal?: AbortSignal) => Promise<Json>;
@@ -446,7 +445,8 @@ export declare class Constellation {
         }>;
         get: (id: string, signal?: AbortSignal) => Promise<Inspection>;
         getSummary: (id: string, signal?: AbortSignal) => Promise<Inspection>;
-        list: (query?: Parameters<Constellation["list"]>[0], signal?: AbortSignal) => Promise<{
+        getTimings: (id: string, signal?: AbortSignal) => Promise<RequestTimings>;
+        list: (query?: RequestListQuery, signal?: AbortSignal) => Promise<{
             items: RequestRecord[];
             total: number;
             offset: number;
@@ -460,7 +460,7 @@ export declare class Constellation {
             after?: number;
             signal?: AbortSignal;
         }) => AsyncGenerator<RequestEvent, any, any>;
-        listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: Parameters<Constellation["records"]>[2], signal?: AbortSignal) => Promise<{
+        listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: RequestRecordsQuery, signal?: AbortSignal) => Promise<{
             items: RecordTypes[K][];
             total: number;
             offset: number;
@@ -470,7 +470,10 @@ export declare class Constellation {
             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;
@@ -485,7 +488,7 @@ export declare class Constellation {
         respond: (requestId: string, inputId: string, response: InputResponse, signal?: AbortSignal) => Promise<void>;
     };
     get spans(): {
-        start: (requestId: string, name: string, options?: Parameters<Constellation["startSpan"]>[2], signal?: AbortSignal) => Promise<{
+        start: (requestId: string, name: string, options?: StartSpanOptions, signal?: AbortSignal) => Promise<{
             id: string;
             end: (options?: {
                 endedAt?: string;
@@ -498,114 +501,5 @@ export declare class Constellation {
     get logs(): {
         add: (requestId: string, logs: Log[], signal?: AbortSignal) => Promise<void>;
     };
-    /** Configuration endpoints require a management key. */
-    get management(): {
-        registry: {
-            get: (signal?: AbortSignal) => Promise<Json>;
-            listRows: (kind: "models" | "providers" | "plans" | "rules", query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            update: (input: {
-                expectedRevision: number;
-                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>>;
-            rollback: (kind: string, id: string, input: {
-                toVersion: number;
-                expectedVersion: number;
-            }, signal?: AbortSignal) => Promise<Json>;
-            preview: (input: ModelResolution, signal?: AbortSignal) => Promise<Json>;
-            testRules: (scope: {
-                workspaceId: string;
-                userId?: string;
-            }, signal?: AbortSignal) => Promise<Json>;
-        };
-        keys: {
-            list: (signal?: AbortSignal) => Promise<Json>;
-            listPage: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            create: (input: Json, signal?: AbortSignal) => Promise<Json>;
-            revoke: (id: string, signal?: AbortSignal) => Promise<void>;
-            setInputWebhook: (id: string, input: {
-                url: string | null;
-                token?: string;
-            }, signal?: AbortSignal) => Promise<Json>;
-        };
-        credentials: {
-            list: (signal?: AbortSignal) => Promise<Json>;
-            listPage: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-            create: (input: Json, signal?: AbortSignal) => Promise<Json>;
-            update: (ref: string, input: Json, signal?: AbortSignal) => Promise<void>;
-            delete: (ref: string, signal?: AbortSignal) => Promise<void>;
-        };
-        executionSettings: {
-            get: (signal?: AbortSignal) => Promise<Json>;
-            update: (input: Json, signal?: AbortSignal) => Promise<Json>;
-            listHistory: (signal?: AbortSignal) => Promise<Json>;
-        };
-    };
-    /** Read-only operational endpoints require a telemetry key. */
-    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<{
-                items: RequestEvent[];
-            }>;
-            listRecords: <K extends keyof RecordTypes>(id: string, kind: K, query?: PageQuery, signal?: AbortSignal) => Promise<Page<RecordTypes[K]>>;
-            getTimeline: (id: string, options?: {
-                requestId?: string;
-                signal?: AbortSignal;
-            }) => Promise<Timeline>;
-            getHttpExchange: (id: string, attemptId: string, signal?: AbortSignal) => Promise<Json>;
-            getHttpBody: (id: string, attemptId: string, query: {
-                direction: "request" | "response";
-                offset?: number;
-                limit?: number;
-            }, signal?: AbortSignal) => Promise<Json>;
-        };
-        system: {
-            get: (signal?: AbortSignal) => Promise<Json>;
-            listHistory: (query?: {
-                hours?: 1 | 24 | 168;
-            }, signal?: AbortSignal) => Promise<Json>;
-            getComponent: (component: string, signal?: AbortSignal) => Promise<Json>;
-        };
-        observability: {
-            get: (query?: PageQuery, signal?: AbortSignal) => Promise<Json>;
-            getSeries: (query: {
-                source: "local" | "gateway";
-                hours?: 1 | 24 | 168;
-                providerId?: string;
-                modelId?: string;
-            }, signal?: AbortSignal) => Promise<Json>;
-            getTiming: (query?: {
-                hours?: 1 | 24 | 168;
-            }, signal?: AbortSignal) => Promise<Json>;
-        };
-        jobs: {
-            listHistory: (query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
-        };
-        notifications: {
-            list: (query?: PageQuery & {
-                status?: "active" | "resolved";
-            }, signal?: AbortSignal) => Promise<Page<Json>>;
-            get: (id: string, query?: PageQuery, signal?: AbortSignal) => Promise<Json>;
-            listEvents: (query?: {
-                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>>;
-        };
-    };
-    get health(): {
-        live: (signal?: AbortSignal) => Promise<Json>;
-        ready: (signal?: AbortSignal) => Promise<Json>;
-    };
-    get webhooks(): {
-        verify: (request: Request, expectedToken: string) => Promise<WebhookEvent>;
-    };
 }
 export {};

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

@@ -0,0 +1,210 @@
+/** 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";
+/** 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: {
+        baseUrl: string;
+        apiKey: string;
+        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: {
+            get: (signal?: AbortSignal) => Promise<Json>;
+            listRows: (kind: "models" | "providers" | "plans" | "rules", query?: PageQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            update: (input: {
+                expectedRevision: number;
+                catalog: Json;
+            }, signal?: AbortSignal) => Promise<Json>;
+            applyChanges: (changes: Json[], signal?: AbortSignal) => Promise<Json>;
+            listHistory: (kind: string, id: string, query?: PaginationQuery, signal?: AbortSignal) => Promise<Page<Json>>;
+            rollback: (kind: string, id: string, input: {
+                toVersion: number;
+                expectedVersion: number;
+            }, signal?: AbortSignal) => Promise<Json>;
+            preview: (input: ModelResolution, signal?: AbortSignal) => Promise<Json>;
+            testRules: (scope: {
+                workspaceId: string;
+                userId?: string;
+            }, signal?: AbortSignal) => Promise<Json>;
+        };
+    };
+    /** Request reads enforce key scope; global operational reads require an unscoped telemetry key. Metadata is the default. */
+    get telemetry(): {
+        requests: {
+            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?: RequestRecordsQuery & TelemetryQuery, signal?: AbortSignal) => Promise<TelemetryPage<TelemetryRecords[K]>>;
+            getTimeline: (id: string, options?: TelemetryReadOptions & {
+                requestId?: string;
+            }) => 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: (options?: TelemetryReadOptions) => Promise<Json>;
+            listHistory: (query?: TelemetryQuery & {
+                hours?: 1 | 24 | 168;
+            }, signal?: AbortSignal) => Promise<Json>;
+            getComponent: (component: string, options?: TelemetryReadOptions & OperationsQuery) => Promise<Json>;
+        };
+        observability: {
+            get: (query?: ObservabilityQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Json>;
+            getSeries: (query: TelemetryQuery & {
+                hours?: 1 | 24 | 168;
+                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>;
+            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?: OperationsQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Json>;
+        };
+        notifications: {
+            list: (query?: TelemetryQuery & {
+                offset?: number;
+                status?: "active" | "resolved";
+            }, 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?: 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(): {
+        verify: (request: Request, expectedToken: string) => Promise<WebhookEvent>;
+    };
+}

package/examples/quickstart.mjs

@@ -0,0 +1,48 @@
+import { Constellation, uuid7 } from "@lionhummer/constellation";
+
+function required(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`Set ${name} in your server environment.`);
+  return value;
+}
+
+const workspaceId = required("CONSTELLATION_WORKSPACE_ID");
+const userId = process.env.CONSTELLATION_USER_ID || undefined;
+const planId = process.env.CONSTELLATION_PLAN_ID || undefined;
+const client = new Constellation({
+  baseUrl: required("CONSTELLATION_BASE_URL"),
+  apiKey: required("CONSTELLATION_EXECUTION_KEY"),
+});
+
+// Discovery uses the same scope as execution. It does not call a provider.
+const catalog = await client.models.list({ workspaceId, userId, planId });
+console.log("Available models:", JSON.stringify(catalog, null, 2));
+const model = process.env.CONSTELLATION_MODEL;
+if (!model) {
+  console.log("Set CONSTELLATION_MODEL to one of the returned models[].id values, then rerun.");
+} else {
+  const input = {
+    idempotencyKey: uuid7(), // Save this input/key if submission needs retrying.
+    workspaceId,
+    userId,
+    planId,
+    model,
+    messages: [{ role: "user", text: "Say hello in one short sentence." }],
+    maxOutputTokens: 256,
+    timeoutMs: 120_000,
+    // No tools or wait checkpoints: no webhook or input consumer is needed.
+  };
+  const { id } = await client.requests.create(input);
+  console.log("Request ID:", id);
+  for await (const event of client.requests.streamEvents(id, {
+    signal: AbortSignal.timeout(150_000),
+  })) {
+    console.log(event.seq, event.type);
+  }
+  const { request } = await client.requests.getSummary(id);
+  console.log("Final status:", request.status);
+  console.log("Output:", request.output?.text ?? "");
+  if (request.status !== "completed") {
+    throw new Error(`Request ${id} ended as ${request.status}: ${request.reason ?? "inspect the request error and attempts"}`);
+  }
+}