@astralform/js 4.0.0 → 4.2.0

package/dist/index.d.cts

@@ -120,6 +120,19 @@ interface AstralformBaseConfig {
     baseURL?: string;
     /** Supply a custom fetch (SSR, testing, custom interceptors). */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Abort a REST request — connect, headers, AND body read — after this many
+     * milliseconds. Defaults to 30_000. Does not apply to `uploadFile` (large
+     * files on slow uplinks) or to SSE streaming, which is long-lived by design
+     * and carries its own `AbortSignal`.
+     *
+     * Note that unlike axios and friends, `0` does NOT mean "no timeout": any
+     * non-positive or non-finite value falls back to the default. REST calls
+     * cannot opt out of the deadline — an unbounded REST request is the bug
+     * this exists to prevent, and it fails silently (a stalled body strands the
+     * caller forever with nothing to react to).
+     */
+    timeoutMs?: number;
 }
 interface AstralformApiKeyConfig extends AstralformBaseConfig {
     /** Agent API key (`sk_live_...` or `sk_test_...`). */
@@ -638,6 +651,12 @@ interface ChatStreamRequest {
     upload_ids?: string[];
     agent_name?: string;
     plan_mode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The backend mints
+     * an agent_goal from this text and drives the run under a budget until the
+     * objective is genuinely complete. A blank/omitted value runs a normal turn.
+     */
+    goal?: string;
     /**
      * Per-request model choice (client-side model selection), wire shape.
      * `provider` and `model` are paired; omit to reuse the thread's last model.
@@ -723,6 +742,12 @@ interface SendOptions$1 extends ModelChoiceOptions {
     uploadIds?: string[];
     agentName?: string;
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The text becomes
+     * the goal's objective; the backend keeps the agent working under a budget until
+     * it's complete. Omit for a normal turn.
+     */
+    goal?: string;
 }
 /**
  * A selectable model for one of the team's connected providers, from
@@ -761,6 +786,7 @@ interface ConversationAsset {
 declare class AstralformClient {
     private readonly baseURL;
     private readonly fetchFn;
+    private readonly timeoutMs;
     /**
      * Auth state is mutable so callers can rotate access tokens or switch
      * agent context without re-instantiating the client. API-key mode is
@@ -807,7 +833,23 @@ declare class AstralformClient {
      */
     private get authHeaders();
     private get headers();
+    /**
+     * 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.
+     */
+    private withDeadline;
     private request;
+    /** Fetch + status handling. Always called inside `withDeadline`. */
+    private send;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     private del;
@@ -1141,6 +1183,11 @@ interface SendOptions extends ModelChoiceOptions {
     agentName?: string;
     uploadIds?: string[];
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode) — the text is the
+     * goal objective the backend drives to completion. Omit for a normal turn.
+     */
+    goal?: string;
 }
 type StreamManagerEvent = {
     type: "stateChange";

package/dist/index.d.ts

@@ -120,6 +120,19 @@ interface AstralformBaseConfig {
     baseURL?: string;
     /** Supply a custom fetch (SSR, testing, custom interceptors). */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Abort a REST request — connect, headers, AND body read — after this many
+     * milliseconds. Defaults to 30_000. Does not apply to `uploadFile` (large
+     * files on slow uplinks) or to SSE streaming, which is long-lived by design
+     * and carries its own `AbortSignal`.
+     *
+     * Note that unlike axios and friends, `0` does NOT mean "no timeout": any
+     * non-positive or non-finite value falls back to the default. REST calls
+     * cannot opt out of the deadline — an unbounded REST request is the bug
+     * this exists to prevent, and it fails silently (a stalled body strands the
+     * caller forever with nothing to react to).
+     */
+    timeoutMs?: number;
 }
 interface AstralformApiKeyConfig extends AstralformBaseConfig {
     /** Agent API key (`sk_live_...` or `sk_test_...`). */
@@ -638,6 +651,12 @@ interface ChatStreamRequest {
     upload_ids?: string[];
     agent_name?: string;
     plan_mode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The backend mints
+     * an agent_goal from this text and drives the run under a budget until the
+     * objective is genuinely complete. A blank/omitted value runs a normal turn.
+     */
+    goal?: string;
     /**
      * Per-request model choice (client-side model selection), wire shape.
      * `provider` and `model` are paired; omit to reuse the thread's last model.
@@ -723,6 +742,12 @@ interface SendOptions$1 extends ModelChoiceOptions {
     uploadIds?: string[];
     agentName?: string;
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The text becomes
+     * the goal's objective; the backend keeps the agent working under a budget until
+     * it's complete. Omit for a normal turn.
+     */
+    goal?: string;
 }
 /**
  * A selectable model for one of the team's connected providers, from
@@ -761,6 +786,7 @@ interface ConversationAsset {
 declare class AstralformClient {
     private readonly baseURL;
     private readonly fetchFn;
+    private readonly timeoutMs;
     /**
      * Auth state is mutable so callers can rotate access tokens or switch
      * agent context without re-instantiating the client. API-key mode is
@@ -807,7 +833,23 @@ declare class AstralformClient {
      */
     private get authHeaders();
     private get headers();
+    /**
+     * 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.
+     */
+    private withDeadline;
     private request;
+    /** Fetch + status handling. Always called inside `withDeadline`. */
+    private send;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     private del;
@@ -1141,6 +1183,11 @@ interface SendOptions extends ModelChoiceOptions {
     agentName?: string;
     uploadIds?: string[];
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode) — the text is the
+     * goal objective the backend drives to completion. Omit for a normal turn.
+     */
+    goal?: string;
 }
 type StreamManagerEvent = {
     type: "stateChange";

package/dist/index.js

@@ -252,6 +252,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 {
@@ -302,6 +303,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.
@@ -392,11 +394,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"
@@ -405,13 +444,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);
@@ -1302,6 +1349,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,
@@ -1865,6 +1913,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,