@astralform/js 4.0.0 → 4.2.0

package/README.md

@@ -61,9 +61,15 @@ const session = new ChatSession({
   userId: "user-123",       // Required — identifies the end user
   baseURL: "http://localhost:8000", // Optional — defaults to https://api.astralform.ai
   fetch: customFetch,       // Optional — custom fetch implementation
+  timeoutMs: 30_000,        // Optional — REST request deadline, defaults to 30s
 });
 ```
 
+`timeoutMs` bounds each REST request end to end — connect, headers, and the
+body read — rejecting with `ConnectionError` when it expires. File uploads and
+the SSE stream are exempt: both are long-running by design, and the stream
+carries its own `AbortSignal`.
+
 ## Events
 
 Subscribe to events with `.on()`, which returns an unsubscribe function. The SDK forwards a typed `ChatEvent` for every wire event — consumers build their own block / message state from the stream.

package/dist/index.cjs

@@ -298,6 +298,7 @@ async function* streamJobSSE(options) {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.astralform.ai";
+var DEFAULT_TIMEOUT_MS = 3e4;
 function validateBaseURL(url) {
   const cleaned = url.replace(/\/+$/, "");
   try {
@@ -348,6 +349,7 @@ var AstralformClient = class {
     }
     this.baseURL = validateBaseURL(config.baseURL ?? DEFAULT_BASE_URL);
     this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
   }
   /**
    * Replace the current OIDC access token without reconstructing the client.
@@ -438,11 +440,48 @@ var AstralformClient = class {
       "Content-Type": "application/json"
     };
   }
+  /**
+   * Run one REST exchange under a single deadline covering connect, headers,
+   * AND the body read. The body read is the part that matters: `json()` used
+   * to sit outside every guard, so a response whose headers arrived but whose
+   * body stalled hung forever — silently stranding callers that await it
+   * (a stalled `getMessages` used to leave `StreamManager.restore()` parked
+   * before it ever fetched the events it renders from).
+   *
+   * The controller is created per request and is deliberately NOT the
+   * session's — that one means "the user cancelled this turn" and is null
+   * outside a live turn. Aborting frees the socket; the race guarantees a
+   * rejection even when an injected `fetch` ignores the signal.
+   */
+  async withDeadline(run) {
+    const controller = new AbortController();
+    const timedOut = () => new ConnectionError(`Request timed out after ${this.timeoutMs}ms`);
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(timedOut());
+      }, this.timeoutMs);
+    });
+    try {
+      return await Promise.race([run(controller.signal), deadline]);
+    } catch (err) {
+      if (controller.signal.aborted) throw timedOut();
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   async request(method, path, body) {
+    return this.withDeadline((signal) => this.send(method, path, body, signal));
+  }
+  /** Fetch + status handling. Always called inside `withDeadline`. */
+  async send(method, path, body, signal) {
     const response = await this.fetchFn(`${this.baseURL}${path}`, {
       method,
       headers: this.headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal
     }).catch((err) => {
       throw new ConnectionError(
         err instanceof Error ? err.message : "Failed to connect"
@@ -451,13 +490,21 @@ var AstralformClient = class {
     await this.handleError(response);
     return response;
   }
+  // DO NOT refactor these back into `request()` + `.json()`. Parsing the body
+  // INSIDE the raced callback is the entire fix: `json()` outside the deadline
+  // is the original bug (headers arrive, body stalls, caller hangs forever).
+  // `request()` survives for `del()`, which never reads the body.
   async get(path) {
-    const response = await this.request("GET", path);
-    return response.json();
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("GET", path, void 0, signal);
+      return await response.json();
+    });
   }
   async post(path, body) {
-    const response = await this.request("POST", path, body);
-    return response.json();
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("POST", path, body, signal);
+      return await response.json();
+    });
   }
   async del(path) {
     await this.request("DELETE", path);
@@ -1348,6 +1395,7 @@ var ChatSession = class {
       upload_ids: options?.uploadIds,
       agent_name: options?.agentName,
       plan_mode: options?.planMode,
+      goal: options?.goal,
       // Per-request model choice (client-side model selection).
       provider: options?.provider,
       model: options?.model,
@@ -1911,6 +1959,7 @@ var StreamManager = class {
         agentName: options?.agentName,
         uploadIds: options?.uploadIds,
         planMode: options?.planMode,
+        goal: options?.goal,
         provider: options?.provider,
         model: options?.model,
         reasoningEffort: options?.reasoningEffort,