@lionhummer/constellation 0.2.0 → 0.4.0

package/README.md

@@ -6,30 +6,101 @@ TypeScript client for Constellation's durable request API. Run it on a trusted s
 npm install @lionhummer/constellation
 ```
 
-```ts
-import { Constellation, uuid7 } from "@lionhummer/constellation"
+## First request (Node.js 22+)
+
+An operator must first configure an enabled provider, its credential reference, a model/offering, and access rules for your workspace. Ask them for the API base URL and an **execution** key. A console login is not an SDK credential. The base URL is the host root, without `/v1` or `/internal`.
+
+Set these variables privately in your server environment:
+
+- `CONSTELLATION_BASE_URL`: your server's URL (local API: `http://127.0.0.1:8080`).
+- `CONSTELLATION_EXECUTION_KEY`: the secret copied when the operator creates your key.
+- `CONSTELLATION_WORKSPACE_ID`: the exact workspace allowed by the key and access rules.
+- `CONSTELLATION_USER_ID`: required when the key is user-scoped; otherwise optional.
+- `CONSTELLATION_PLAN_ID`: optional pricing plan ID, when your operator supplies one.
+
+Run the included example to discover accessible models. This does not dispatch a provider:
+
+```sh
+node node_modules/@lionhummer/constellation/examples/quickstart.mjs
+```
+
+Set `CONSTELLATION_MODEL` to a returned `models[].id` and rerun the command. The second run submits a real provider request, prints its ID/events, then shows `completed` and the output text. Provider usage can incur charges. It needs no webhook, tool handler or wait checkpoint.
+
+The complete example is included in the package:
+
+```js
+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: "https://your-constellation-host.example",
-  apiKey: process.env.CONSTELLATION_EXECUTION_KEY!,
-})
-
-const { id } = await client.requests.create({
-  idempotencyKey: uuid7(),
-  workspaceId: "workspace-123",
-  externalId: "conversation-456",
-  model: "catalog/example-model",
-  instructions: "Answer accurately.",
-  messages: [{ role: "user", text: "Look this up." }],
-  tools: [{
-    name: "lookup",
-    inputSchema: { type: "object", properties: { key: { type: "string" } } },
-  }],
-  events: { afterStep: "wait", outputDelta: "notify", terminal: "notify" },
-})
+  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"}`);
+  }
+}
 ```
 
-The first model step uses the submitted input. Keep the idempotency key for retries; reusing it with different input is rejected. `externalId` connects independent requests and may supply a routing affinity hint; it does not load conversation history.
+Each invocation creates a new request. For application retries, persist the complete input and its UUIDv7 idempotency key **before** submission and reuse both after an uncertain POST; do not generate a fresh key on each retry. `externalId` groups independent requests and may supply a routing-affinity hint; it does not load conversation history. The observer's abort only stops observing; use `requests.cancel(id)` to cancel execution.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| 401 | Correct host and execution key; the key may have been revoked. Browser cookies do not authenticate the SDK. |
+| 403 | Execution permission, matching workspace/user scope and model access rules. Management/telemetry permissions do not imply execution. |
+| No models | Operator has enabled a provider, model and offering with an eligible route/access rule. Discovery uses your workspace/user scope. |
+| 409 | Read the error code/message. Reuse the exact original input for an idempotency retry; renew an expired input claim before answering. |
+| 429 / 503 | Respect `Retry-After`. Retry uncertain admission with the saved input/key. |
+| `queued` | A worker must be running and connected to the same PostgreSQL/Redis environment. |
+| `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.
 
 ## Events and caller work
 
@@ -37,8 +108,12 @@ All event modes default to `off`. `beforeModel`, `afterModel`, and `afterStep` a
 
 `afterStep` happens after the model when it has no tool calls, or after all tool results. It includes output, usage, cost, and tool results. Use it to settle billing once and decide whether to complete or continue. Continuing requires a complete next `stepInput`, including model, messages, instructions, tools, parameters, output limit, and cache policy. Constellation routes each later step separately.
 
+The following integration sketches contain application-owned functions such as `lookupOnce`, `settleOnce` and `buildCompleteNextStep`; implement those before enabling tools or wait checkpoints. Type handlers explicitly so TypeScript checks their callback arguments:
+
 ```ts
-const handlers = {
+import type { InputHandlers } from "@lionhummer/constellation"
+
+const handlers: InputHandlers = {
   consumerId: "stable-worker-id",
   tools: {
     lookup: async (args, { inputId, signal }) => lookupOnce(args, inputId, signal),
@@ -60,7 +135,7 @@ await client.inputs.handle(id, inputId, handlers)
 
 ## Webhook
 
-Configure an HTTPS callback URL and token on the execution key. Verify `x-constellation-webhook-token`; return 2xx after your effects are durable. A non-2xx response is retried. Model text/reasoning chunks arrive as `request.events` when `outputDelta` is `notify`; terminal notification carries a request ID and event sequence.
+Configure an HTTPS callback URL and token on the execution key. Verify `x-constellation-webhook-token`; return 2xx after your effects are durable. Transient non-2xx responses are retried. A permanent input rejection can use HTTP 422 with the documented `constellation_input_rejected` body; repeated 401/403 stops delivery. Return 2xx only after durable effects. Model text/reasoning chunks arrive as `request.events` when `outputDelta` is `notify`; terminal notification carries a request ID and event sequence.
 
 ```ts
 const event = await client.webhooks.verify(request, webhookToken)
@@ -78,4 +153,51 @@ if ("inputId" in event) {
 
 `requests.get` returns the request and its records. For long executions, use `requests.getSummary`, `requests.listRecords`, `requests.getTimeline`, and the paginated request list. `requests.listEvents` reads the durable event journal; `requests.streamEvents` reconnects SSE from a cursor. Stopping an observer does not cancel execution; use `requests.cancel` explicitly.
 
-Execution methods are top-level (`models`, `requests`, `inputs`, `spans`, `logs`). Configuration lives under `management`; read-only operational data lives under `telemetry`. The same API timeline is shown in the console. Caller spans can attach to a wait using `inputId` and nest beneath a span using `parentSpanId`.
+Execution methods are top-level (`models`, `requests`, `inputs`, `spans`, `logs`). Registry authoring lives under `management.registry`; read-only operational data lives under `telemetry`. API-key administration, provider credentials, users and capacity controls are internal operator APIs and are absent from this external SDK. The SDK requires a bearer key, omits browser cookies, and has no `/internal` routing option. Provider definitions are readable externally; imports, changes and rollback that modify providers require internal operator access because endpoints and credential references control where stored secrets are sent. The same API timeline is shown in the console. Caller spans can attach to a wait using `inputId` and nest beneath a span using `parentSpanId`.
+
+Use the documented namespaces throughout: `requests.create`, `requests.get`,
+`requests.getSummary`, `requests.preview`, `requests.listRecords`,
+`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.