@lionhummer/constellation 0.9.0 → 0.9.2

package/README.md

@@ -273,13 +273,13 @@ async function handle(event: WebhookEvent) {
   }
 }
 
-// Resume unfinished events after a restart or a failure.
-setInterval(async () => {
-  for (const event of await store.pending()) await handle(event);
-}, 60_000);
+// Optional: resume unfinished events right after a restart.
+for (const event of await store.pending()) void handle(event);
 ```
 
-You can also process inside the webhook and return `204` when `processEvent` finishes. That only works when your tools are fast: Constellation waits 5 seconds for the webhook response by default, then retries delivery. A retry is safe, because `prepare` serializes the work, but slow handlers turn into repeated deliveries.
+Don't run tools inside the webhook call. Constellation waits 5 seconds for the acknowledgement by default, and nothing in Constellation waits for your tools.
+
+If your process dies while handling an event, you don't need a poller to recover it. Constellation sends an unanswered `model.completed` event again after the response window (10 minutes by default), up to 3 times, and stops as soon as your response arrives. A re-sent event has the same `id`, so `store.accept` and `store.prepare` resume it from your saved checkpoint. If the event is still being processed when the re-send arrives, acknowledge it anyway. Keep your processing lease shorter than the response window and renew it while work continues, so a re-send after a crash can take the event over.
 
 ## What `processEvent` does
 
@@ -343,11 +343,30 @@ tools: {
 
 The SDK records `client.processing` and one span per tool automatically. A response carries at most 512 spans, 128 logs and 1 MiB of telemetry; the SDK trims larger batches and records what it omitted. Do not put secrets or personal data in span names, attributes or log messages.
 
+## Opening lines
+
+Show a one-sentence opener while the real step is prepared. The operator configures its model and prompt in Constellation.
+
+```ts
+const opener = await client.openers.create({
+  idempotencyKey: `${turnId}`,
+  workspaceId, userId, externalId: threadId,
+  message,
+  history: recentTurns, // [{ role: "user" | "assistant", text }], oldest first
+})
+if (opener) void client.openers.sentence(opener.id).then((sentence) => {
+  if (sentence && !realOutputStarted) show(sentence)
+})
+```
+
+Start the real request without waiting for the opener. `parseOpenerSentence(text)` applies the same checks to text you already have.
+
 ## Limits and timeouts
 
 | Setting | Default | Notes |
 | --- | --- | --- |
 | `timeoutMs` | 30 minutes | Deadline for the whole request, including your processing between steps. |
+| `compressRequests` client option | `true` | Request bodies of 16 KiB or more are sent gzip-compressed. Every step resends the full conversation, so this cuts upload time several-fold. |
 | `attemptTimeoutMs`, `firstByteTimeoutMs`, `idleTimeoutMs` | not set | Optional per-provider-call limits. Operators also run stall watchdogs: by default 120 s to the first response byte and 300 s with no data. Keepalives count as data. |
 | `maxProviderAttempts` | 32 | Provider attempts per step, including fallbacks (1–256). |
 | `toolConcurrency` hook option | 8 | Parallel tool calls per event (1–128). |
@@ -366,6 +385,7 @@ A failed provider call falls back to the next provider only before any output ha
 | `requests.submit(input)` | Start a request, continue it (`inReplyTo`), or stop it (`action: "observe"`). |
 | `requests.preview(input)` | Validate a complete input and show routing, without calling a provider. |
 | `requests.cancel(id)` | Cancel a request. |
+| `openers.create(input)`, `openers.sentence(id)` | Start an opening line for a just-sent message (null when openers are turned off), then wait for its sentence (null when skipped or failed). |
 | `requests.getState(id)` | Committed state: status, steps, attempt outcomes, usage and cost. |
 | `requests.getSummary(id)`, `requests.get(id)` | Request detail, without or with spans and logs. |
 | `requests.list(query)` | Page through requests, e.g. by `externalId` or `status`. |

package/dist/index.js

@@ -1,4 +1,15 @@
 // ../client-core/src/index.ts
+function parseOpenerSentence(raw, maxWords = 25) {
+  const text = raw.trim();
+  if (!text || /^SKIP\b/i.test(text))
+    return null;
+  const sentence = (text.match(/^.+?[.!](?=\s|[A-Z]|$)/)?.[0] ?? text).trim();
+  if (sentence.includes("`") || sentence.includes(`
+`) || sentence.split(/\s+/).length > maxWords)
+    return null;
+  return sentence;
+}
+
 class ConstellationError extends Error {
   status;
   code;
@@ -102,6 +113,15 @@ async function pause(ms, signal) {
     signal?.addEventListener("abort", abort, { once: true });
   });
 }
+var COMPRESS_FROM_BYTES = 16 * 1024;
+async function encodeBody(body, compress) {
+  const json = JSON.stringify(body);
+  if (!compress || json.length < COMPRESS_FROM_BYTES || typeof CompressionStream === "undefined") {
+    return { body: json, headers: { "Content-Type": "application/json" } };
+  }
+  const gzipped = await new Response(new Blob([json]).stream().pipeThrough(new CompressionStream("gzip"))).arrayBuffer();
+  return { body: gzipped, headers: { "Content-Type": "application/json", "Content-Encoding": "gzip" } };
+}
 
 class RequestClient {
   #fetcher;
@@ -115,12 +135,11 @@ class RequestClient {
     return `${this.#options.baseUrl.replace(/\/$/, "")}${route}`;
   }
   async#call(path, method = "GET", body, signal) {
+    const encoded = body === undefined ? undefined : await encodeBody(body, this.#options.compressRequests ?? true);
     const response = await this.#fetcher(this.#url(path), {
       method,
-      headers: {
-        ...body !== undefined ? { "Content-Type": "application/json" } : {}
-      },
-      body: body === undefined ? undefined : JSON.stringify(body),
+      headers: encoded?.headers ?? {},
+      body: encoded?.body,
       signal: signal ? AbortSignal.any([
         signal,
         AbortSignal.timeout(this.#options.timeoutMs ?? 30000)
@@ -292,6 +311,30 @@ class RequestClient {
       resolve: (input, signal) => this.#call("/v1/registry/resolve", "POST", input, signal)
     };
   }
+  get openers() {
+    return {
+      create: async (input, signal) => await this.#call("/v1/openers", "POST", input, signal) ?? null,
+      sentence: async (id, options = {}) => {
+        let text = "";
+        for await (const event of this.#events(id, { signal: options.signal })) {
+          if (event.type === "model.completed") {
+            const message = event.data.message;
+            text = message?.text ?? text;
+            break;
+          }
+          if (event.type === "model.failed" || event.type === "model.cancelled")
+            return null;
+          if (event.type === "model.delta") {
+            for (const entry of event.data.events ?? []) {
+              if (entry.event?.type === "text_delta")
+                text += entry.event.delta ?? "";
+            }
+          }
+        }
+        return parseOpenerSentence(text, options.maxWords);
+      }
+    };
+  }
   get requests() {
     return {
       submit: (input, signal) => this.#submit(input, signal),
@@ -637,6 +680,7 @@ class Constellation extends RequestClient {
     super({
       baseUrl: options.baseUrl,
       timeoutMs: options.timeoutMs,
+      compressRequests: options.compressRequests,
       fetch: authenticatedFetch
     });
     this.#baseUrl = options.baseUrl.replace(/\/$/, "");
@@ -761,6 +805,7 @@ export {
   uuid7,
   processEvent,
   prepareResponse,
+  parseOpenerSentence,
   normalizeTimestamp,
   PermanentEventError,
   PERMANENT_RESPONSE_CODES,

package/dist/types/client-core/src/index.d.ts

@@ -304,6 +304,24 @@ export type ModelDeltaEvent = {
     };
 };
 export type RequestEvent = WebhookEvent | ModelDeltaEvent;
+export type OpenerTurn = {
+    role: "user" | "assistant";
+    text: string;
+};
+export type OpenerInput = {
+    /** Stable per turn, so a retry never admits a second opener. */
+    idempotencyKey: string;
+    workspaceId: string;
+    userId?: string;
+    externalId?: string;
+    planId?: string;
+    /** The message the user just sent. */
+    message: string;
+    /** Earlier turns, oldest first; operator settings decide how many are used. */
+    history?: OpenerTurn[];
+};
+/** The opener line to show: one sentence, no code, within `maxWords`; null for SKIP or anything else. */
+export declare function parseOpenerSentence(raw: string, maxWords?: number): string | null;
 export type Page<T> = {
     items: T[];
     total: number;
@@ -492,6 +510,8 @@ type ClientOptions = {
     apiPrefix?: "/v1" | "/internal";
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /** gzip JSON bodies of at least 16 KiB (default true). */
+    compressRequests?: boolean;
 };
 export declare class RequestClient {
     #private;
@@ -501,6 +521,22 @@ export declare class RequestClient {
         list: (scope: ModelScope, signal?: AbortSignal) => Promise<Json>;
         resolve: (input: ModelResolution, signal?: AbortSignal) => Promise<Json>;
     };
+    /**
+     * Opening lines: an operator-configured short model call, made when the user
+     * sends, naming what the assistant does first. create admits it as an
+     * ordinary request; sentence waits for it to end and returns the line to
+     * show, or null for SKIP, a failure, or an answer that breaks the format.
+     */
+    get openers(): {
+        /** The opener request, or null when the operator has turned openers off. */
+        create: (input: OpenerInput, signal?: AbortSignal) => Promise<{
+            id: string;
+        } | null>;
+        sentence: (id: string, options?: {
+            signal?: AbortSignal;
+            maxWords?: number;
+        }) => Promise<string | null>;
+    };
     /** Durable requests. create returns an ID; execution continues independently. */
     get requests(): {
         submit: (input: Admission, signal?: AbortSignal) => Promise<AdmissionReceipt>;

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

@@ -1,7 +1,7 @@
 /** 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, normalizeTimestamp } from "../../client-core/src/index";
-export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, Admission, AdmissionReceipt, ResponseOutcome, ObservationResponse, Observations, EventReference, ModelCompletedEvent, ModelDeltaEvent, ModelStreamFrame, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery } from "../../client-core/src/index";
+export { ConstellationError, uuid7, normalizeTimestamp, parseOpenerSentence } from "../../client-core/src/index";
+export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, Admission, AdmissionReceipt, ResponseOutcome, ObservationResponse, Observations, EventReference, ModelCompletedEvent, ModelDeltaEvent, ModelStreamFrame, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, OpenerInput, OpenerTurn } from "../../client-core/src/index";
 /** OpenAPI contract filtered to this key's permissions and scope. */
 export type DiscoveryDocument = {
     openapi: string;
@@ -94,6 +94,7 @@ export declare class Constellation extends RequestClient {
         apiKey: string;
         fetch?: typeof fetch;
         timeoutMs?: number;
+        compressRequests?: boolean;
     });
     /** Discover HTTP operations available to this bearer key. */
     discover(signal?: AbortSignal): Promise<DiscoveryDocument>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionhummer/constellation",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "TypeScript client for durable model requests and model events",
   "type": "module",
   "license": "UNLICENSED",