@lionhummer/constellation 0.9.0 → 0.9.1

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
 
@@ -348,6 +348,7 @@ The SDK records `client.processing` and one span per tool automatically. A respo
 | 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). |

package/dist/index.js

@@ -102,6 +102,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 +124,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)
@@ -637,6 +645,7 @@ class Constellation extends RequestClient {
     super({
       baseUrl: options.baseUrl,
       timeoutMs: options.timeoutMs,
+      compressRequests: options.compressRequests,
       fetch: authenticatedFetch
     });
     this.#baseUrl = options.baseUrl.replace(/\/$/, "");

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

@@ -492,6 +492,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;

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

@@ -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.1",
   "description": "TypeScript client for durable model requests and model events",
   "type": "module",
   "license": "UNLICENSED",