@lionhummer/constellation 0.2.0 → 0.3.0

package/README.md

@@ -6,30 +6,97 @@ 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.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 +104,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 +131,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 +149,10 @@ 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.