@lionhummer/constellation 0.1.3 → 0.3.0

package/README.md

@@ -1,172 +1,158 @@
-# Constellation TypeScript SDK
+# @lionhummer/constellation
 
-`@lionhummer/constellation` is a server-side client for durable model execution. A request keeps running after `requests.create()` returns its ID. Constellation owns admission, routing, provider calls, waits and the execution trace. Your application supplies conversation state, tools and any policy or billing decisions.
+TypeScript client for Constellation's durable request API. Run it on a trusted server with an execution key. Constellation routes model calls and stores the execution trace; your application supplies messages, tool implementations, optional policy decisions, and billing.
 
-```sh
+```bash
 npm install @lionhummer/constellation
 ```
 
-```ts
-import { Constellation, uuid7, type InputHandlers } from "@lionhummer/constellation";
+## First request (Node.js 22+)
 
-const client = new Constellation({
-  baseUrl: "https://your-constellation-host.example",
-  apiKey: process.env.CONSTELLATION_EXECUTION_KEY!,
-});
-```
+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`.
 
-Keep keys on a trusted server. One key may have execution, management and telemetry permissions; the method namespaces below map to those API permissions. An `AbortSignal` stops the current SDK operation, not the durable request. Use `requests.cancel(id)` to cancel execution.
+Set these variables privately in your server environment:
 
-## Choose an execution kind
+- `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.
 
-| Kind | Model steps | Caller participation |
-| --- | --- | --- |
-| `generate` | Exactly one. Tools are not accepted. | Observe the result. |
-| `run` | Continues through model steps and caller tools. | Implement tools; there is no review gate before tool dispatch. |
-| `agent` | First step executes from the complete submitted input; later steps use fresh complete inputs. | Review model output and usage before tools, review after tools, and decide whether to continue. |
+Run the included example to discover accessible models. This does not dispatch a provider:
 
-All three use `client.requests.create(input)` and return `{ id }`. Persist the UUIDv7 `idempotencyKey` before submitting. If the POST outcome is uncertain, retry with that same key **and identical input**. `externalId` groups separate requests and can hint at prior-provider affinity; it does not retrieve conversation history.
+```sh
+node node_modules/@lionhummer/constellation/examples/quickstart.mjs
+```
 
-### One-step generation
+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.
 
-```ts
-const { id } = await client.requests.create({
-  kind: "generate",
-  idempotencyKey: uuid7(),
-  workspaceId: "workspace-123",
-  model: "catalog/example-model",
-  messages: [{ role: "user", text: "Explain this result." }],
+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: required("CONSTELLATION_BASE_URL"),
+  apiKey: required("CONSTELLATION_EXECUTION_KEY"),
 });
 
-for await (const event of client.requests.streamEvents(id)) {
-  // Store event.seq to resume after a disconnect.
-  if (["request.completed", "request.failed", "request.cancelled"].includes(event.type)) break;
+// 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"}`);
+  }
 }
-const final = await client.requests.get(id);
 ```
 
-`requests.preview(input)` applies access, pricing and routing rules without creating or dispatching a request. `models.list({ workspaceId })` discovers accessible models; `models.resolve({ workspaceId, targetId })` previews one model's candidates.
+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.
 
-### Tool-capable run
+## Troubleshooting
 
-Use `run` when tools should execute without an application review gate after each model response. Each tool call becomes a durable caller input. The same handlers work with webhook delivery and explicit polling:
+| 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. |
 
-```ts
-const handlers = {
-  consumerId: "stable-worker-id",
-  tools: {
-    lookup: async (args, { inputId, signal }) => {
-      // Deduplicate external effects by inputId: callbacks can be delivered again.
-      return lookupOnce(args, inputId, signal);
-    },
-  },
-} satisfies InputHandlers;
+## Release 0.3.0
 
-// From one verified input webhook:
-await client.inputs.handle(requestId, inputId, handlers);
+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.
 
-// Or run a polling consumer until terminal:
-await client.inputs.poll(requestId, handlers);
-```
+## Events and caller work
 
-`inputs.handle()` processes only the named input and returns. `inputs.poll()` repeatedly inspects and handles inputs until the request is terminal. Neither silently switches delivery modes. For custom consumers, `inputs.claim()` and `inputs.respond()` expose the underlying claim and response operations.
+All event modes default to `off`. `beforeModel`, `afterModel`, and `afterStep` accept `off`, `notify`, or `wait`. `outputDelta` and `terminal` accept `off` or `notify`. Notifications are delivered to the execution key's configured webhook. A wait creates a durable input that your application must claim and answer. Tool calls always create durable inputs, including parallel calls.
 
-### Caller-controlled agent
+`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.
 
-An agent submission contains the **complete first step**. Do not submit a placeholder message expecting an initial preparation callback. The SDK sets the server's `prepareStep` protocol flag for `agent` requests.
+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 { id } = await client.requests.create({
-  kind: "agent",
-  idempotencyKey: uuid7(),
-  workspaceId: "workspace-123",
-  externalId: "conversation-456",
-  model: "catalog/example-model",
-  instructions: "Work carefully and use tools when needed.",
-  messages: fullFirstStepHistory,
-  tools: toolDefinitions,
-  parameters: {},
-  maxOutputTokens: 4096,
-});
-```
-
-After each model step, Constellation issues `caller_review` with output, usage, customer cost, supplier cost and pending tools. Your application can settle usage and decide whether to allow tools. After tools, another review can finish or request the next step. Before a later model step, `prepare_step` asks for the **whole next input**: model, instructions, messages, tools, parameters, output limit and cache policy.
+import type { InputHandlers } from "@lionhummer/constellation"
 
-```ts
-const handlers = {
+const handlers: InputHandlers = {
   consumerId: "stable-worker-id",
-  callerReview: async (review, state, { inputId }) => ({
-    action: await settleAndDecideOnce(review, state, inputId),
-  }),
   tools: {
     lookup: async (args, { inputId, signal }) => lookupOnce(args, inputId, signal),
   },
-  prepareStep: async (state, { signal, parentSpanId }) => ({
-    stepInput: await buildCompleteNextStep(state, { signal, parentSpanId }),
-  }),
-} satisfies InputHandlers;
+  checkpoints: {
+    afterStep: async (payload, state, { inputId, parentSpanId, signal }) => {
+      await settleOnce(inputId, payload, { parentSpanId, signal })
+      return shouldContinue(state)
+        ? { action: "continue", stepInput: await buildCompleteNextStep(state) }
+        : { action: "complete" }
+    },
+  },
+}
+
+await client.inputs.handle(id, inputId, handlers)
 ```
 
-Deduplicate billing and tool side effects by input ID. The SDK claims an input, renews an agent claim while its handler runs, adds parent spans for review/preparation/tool callbacks, and responds. If handling fails transiently, return a non-2xx webhook response so delivery retries. A terminal request rejects new caller spans and logs.
+`inputs.handle` processes one named input, which suits webhook delivery. `inputs.poll` continuously inspects and handles inputs until terminal and must be started explicitly. Both claim and renew inputs while handlers run. Side effects should be deduplicated by input ID because delivery and responses can be retried. Low-level `inputs.claim` and `inputs.respond` are available when you manage the lifecycle yourself.
 
-## Webhooks and events
+## Webhook
 
-Configure the execution key's HTTPS `inputWebhook` URL and random token when creating the key, or later with `management.keys.setInputWebhook()`. The SDK can verify the token and parse the three callback shapes:
+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, process.env.CONSTELLATION_WEBHOOK_TOKEN!);
+const event = await client.webhooks.verify(request, webhookToken)
 if ("inputId" in event) {
-  await client.inputs.handle(event.requestId, event.inputId, handlers);
-} else if (event.kind === "request.model_events") {
-  await storeDeltaBatchOnce(event.requestId, event.afterSeq, event.events);
+  await client.inputs.handle(event.requestId, event.inputId, handlers)
+} else if (event.kind === "request.events") {
+  await storeEventBatchOnce(event.requestId, event.afterSeq, event.events)
 } else {
-  const state = await client.requests.getSummary(event.requestId);
-  await finalizeOnce(event.requestId, event.eventSeq, state);
+  await finalizeOnce(event.requestId, event.eventSeq,
+    await client.requests.getSummary(event.requestId))
 }
-// Return 2xx after your input response or other effects are durable.
 ```
 
-Input callbacks include `{requestId,inputId,kind,payload}` and `x-constellation-input-id`. Model-event callbacks contain `{requestId,kind:"request.model_events",afterSeq,events}`. Terminal callbacks contain `{requestId,eventSeq,kind}`. All carry `x-constellation-webhook-token`. Delivery is at least once. Model deltas may arrive late; use the final inspection as authority after terminal.
-
-`requests.streamEvents(id, { after, signal })` is SSE with durable sequence replay. `requests.listEvents(id, after)` reads a bounded event page. SSE observes output; it does not process caller inputs. A dropped stream reconnects by cursor and does not cancel the request.
+## Inspection and other APIs
 
-## Inspect and instrument
+`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.
 
-```ts
-const summary = await client.requests.getSummary(id);
-const steps = await client.requests.listRecords(id, "steps", { limit: 25, offset: 0 });
-const timeline = await client.requests.getTimeline(id);
-
-const span = await client.spans.start(id, "application.context", { inputId });
-try {
-  await rebuildContext();
-  await span.end();
-} catch (error) {
-  await span.end({ status: "error" });
-  throw error;
-}
-```
+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`.
 
-`requests.get(id)` loads full inspection. For long runs, use `getSummary()` and `listRecords()` for steps, attempts, inputs, spans or logs. `getTimeline()` returns the same recorded and derived rows as the console. `getHttpExchange()` and `getHttpBody()` inspect a provider attempt. Caller spans may link to an `inputId`, `stepId`, `attemptId` or `parentSpanId`; `client.spans.add()` and `client.logs.add()` write batches.
-
-User messages may contain HTTPS image or PDF URL parts. Constellation stores URL references, not media bytes. Provider adapters forward supported URLs or download within limits immediately before dispatch. Keep signed URLs valid until the provider fetches them; refresh URLs in a later agent `prepareStep` callback.
-
-## Other namespaces
-
-| Namespace | Methods |
-| --- | --- |
-| `management.registry` | `get`, `listRows`, `update`, `applyChanges`, `listHistory`, `rollback`, `preview`, `testRules` |
-| `management.keys` | `list`, `listPage`, `create`, `revoke`, `setInputWebhook` |
-| `management.credentials` | `list`, `listPage`, `create`, `update`, `delete` |
-| `management.executionSettings` | `get`, `update`, `listHistory` |
-| `telemetry.requests` | `list`, `get`, `getSummary`, `listEvents`, `listRecords`, `getTimeline`, `getHttpExchange`, `getHttpBody` |
-| `telemetry.system` | `get`, `listHistory`, `getComponent` |
-| `telemetry.observability` | `get`, `getSeries`, `getTiming` |
-| `telemetry.jobs` | `listHistory` |
-| `telemetry.notifications` | `list`, `get`, `listEvents` |
-| `telemetry.logs` | `searchSystem`, `searchRequests`, `searchAudit` |
-| `health` | `live`, `ready` (public probes) |
-
-Top-level `logs.add()` writes caller logs on an execution key. `telemetry.logs` searches operational logs with a telemetry key. The API's exact parameter and response schemas are served at `/v1/openapi.json` and shown inline in the console's API reference.
-
-The client defaults to a 30-second HTTP timeout; configure `timeoutMs` or pass an `AbortSignal`. `ConstellationError` carries HTTP status, server code and message. Older flat method names remain as temporary aliases for existing callers; new integrations should use the names above.
+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.