@lionhummer/constellation 0.2.0 → 0.3.0

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;
 };
@@ -327,106 +327,53 @@ 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>;
+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 +393,7 @@ 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<{
+        list: (query?: RequestListQuery, signal?: AbortSignal) => Promise<{
             items: RequestRecord[];
             total: number;
             offset: number;
@@ -460,7 +407,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;
@@ -485,7 +432,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 +445,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,96 @@
+/** 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";
+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 declare class Constellation extends RequestClient {
+    #private;
+    constructor(options: {
+        baseUrl: string;
+        apiKey: string;
+        fetch?: typeof fetch;
+        timeoutMs?: number;
+    });
+    /** 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?: 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>;
+        };
+    };
+    /** 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 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"}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionhummer/constellation",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript client for durable model requests and caller events",
   "type": "module",
   "license": "UNLICENSED",
@@ -9,23 +9,33 @@
     "url": "git+https://github.com/FlatFilers/constellation.git",
     "directory": "packages/sdk"
   },
-  "files": ["dist", "README.md"],
-  "publishConfig": { "access": "public" },
-  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/index.js",
+    "dist/types/**/*.d.ts",
+    "examples/quickstart.mjs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/types/sdk/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/types/sdk/src/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && bun build ./src/index.ts --target node --format esm --outdir ./dist",
     "prepack": "bun run build",
     "test": "bun test",
     "typecheck": "tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution Bundler --lib ES2022,DOM src/index.ts"
   },
   "devDependencies": {
     "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }