lemma-sdk 0.2.46 → 0.3.0

package/dist/browser.d.ts

@@ -2,12 +2,20 @@
  * Browser bundle entry point.
  * Exposes LemmaClient as globalThis.LemmaClient.LemmaClient
  *
- * Usage in HTML:
- *   <script src="/lemma-client.js"></script>
+ * Usage in HTML (the host injects window.__LEMMA_CONFIG__ — construct with NO
+ * args so the desk validator doesn't flag a hardcoded podId):
+ *   <script src="/public/sdk/lemma-client.js"></script>
  *   <script>
- *     const client = new window.LemmaClient.LemmaClient({ podId: "...", apiUrl: "..." });
+ *     const client = new window.LemmaClient.LemmaClient(); // reads window.__LEMMA_CONFIG__
  *   </script>
+ *
+ * Canonical paths for this one bundle (kept in sync by the CI bundle-freshness
+ * gate) — don't let these drift:
+ *   - served URL:        /public/sdk/lemma-client.js  (backend public_sdk_controller)
+ *   - committed on disk: lemma-typescript/public/lemma-client.js
+ *   - package export:    dist/browser/lemma-client.js  (unpkg / "./browser-bundle")
  */
-export { LemmaClient } from "./client.js";
-export { AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, } from "./auth.js";
-export { ApiError } from "./http.js";
+import { LemmaClient } from "./client.js";
+import { AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken } from "./auth.js";
+import { ApiError } from "./http.js";
+export { LemmaClient, AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, ApiError, };

package/dist/browser.js

@@ -2,12 +2,41 @@
  * Browser bundle entry point.
  * Exposes LemmaClient as globalThis.LemmaClient.LemmaClient
  *
- * Usage in HTML:
- *   <script src="/lemma-client.js"></script>
+ * Usage in HTML (the host injects window.__LEMMA_CONFIG__ — construct with NO
+ * args so the desk validator doesn't flag a hardcoded podId):
+ *   <script src="/public/sdk/lemma-client.js"></script>
  *   <script>
- *     const client = new window.LemmaClient.LemmaClient({ podId: "...", apiUrl: "..." });
+ *     const client = new window.LemmaClient.LemmaClient(); // reads window.__LEMMA_CONFIG__
  *   </script>
+ *
+ * Canonical paths for this one bundle (kept in sync by the CI bundle-freshness
+ * gate) — don't let these drift:
+ *   - served URL:        /public/sdk/lemma-client.js  (backend public_sdk_controller)
+ *   - committed on disk: lemma-typescript/public/lemma-client.js
+ *   - package export:    dist/browser/lemma-client.js  (unpkg / "./browser-bundle")
  */
-export { LemmaClient } from "./client.js";
-export { AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, } from "./auth.js";
-export { ApiError } from "./http.js";
+import { LemmaClient } from "./client.js";
+import { AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, } from "./auth.js";
+import { ApiError } from "./http.js";
+export { LemmaClient, AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, ApiError, };
+// Back-compat alias: conversation widgets historically loaded this bundle as
+// `window.Lemma` (`new Lemma.LemmaClient(...)`). We standardize on
+// `window.LemmaClient`; keep `window.Lemma` pointing at the same surface during
+// migration so existing widget HTML keeps working. See
+// docs/desk-widget-unification.md.
+if (typeof globalThis !== "undefined") {
+    const scope = globalThis;
+    if (!scope.Lemma) {
+        scope.Lemma = {
+            LemmaClient,
+            AuthManager,
+            buildAuthUrl,
+            buildFederatedLogoutUrl,
+            clearTestingToken,
+            getTestingToken,
+            resolveSafeRedirectUri,
+            setTestingToken,
+            ApiError,
+        };
+    }
+}

package/dist/client.d.ts

@@ -22,6 +22,7 @@ import { SchedulesNamespace } from "./namespaces/schedules.js";
 import { TablesNamespace } from "./namespaces/tables.js";
 import { UsersNamespace } from "./namespaces/users.js";
 import { WorkflowsNamespace } from "./namespaces/workflows.js";
+import { WidgetsNamespace } from "./namespaces/widgets.js";
 import { DatastoreNamespace } from "./namespaces/datastore.js";
 export type { LemmaConfig };
 export { AuthManager };
@@ -46,11 +47,14 @@ export declare class LemmaClient {
     readonly conversations: ConversationsNamespace;
     readonly workflows: WorkflowsNamespace;
     readonly desks: DesksNamespace;
+    readonly widgets: WidgetsNamespace;
     readonly integrations: IntegrationsNamespace;
     readonly resources: ResourcesNamespace;
     readonly resourceAccess: ResourceAccessNamespace;
     readonly schedules: SchedulesNamespace;
     readonly datastore: DatastoreNamespace;
+    /** Alias of {@link datastore}, matching the Python SDK's `pod.queries`. */
+    readonly queries: DatastoreNamespace;
     readonly users: UsersNamespace;
     readonly icons: IconsNamespace;
     readonly pods: PodsNamespace;

package/dist/client.js

@@ -24,6 +24,7 @@ import { SchedulesNamespace } from "./namespaces/schedules.js";
 import { TablesNamespace } from "./namespaces/tables.js";
 import { UsersNamespace } from "./namespaces/users.js";
 import { WorkflowsNamespace } from "./namespaces/workflows.js";
+import { WidgetsNamespace } from "./namespaces/widgets.js";
 import { DatastoreNamespace } from "./namespaces/datastore.js";
 export { AuthManager };
 export class LemmaClient {
@@ -44,11 +45,14 @@ export class LemmaClient {
     conversations;
     workflows;
     desks;
+    widgets;
     integrations;
     resources;
     resourceAccess;
     schedules;
     datastore;
+    /** Alias of {@link datastore}, matching the Python SDK's `pod.queries`. */
+    queries;
     users;
     icons;
     pods;
@@ -63,8 +67,14 @@ export class LemmaClient {
         this._currentPodId = this._config.podId;
         this._podId = this._config.podId;
         this.auth = internalOptions.authManager ?? new AuthManager(this._config.apiUrl, this._config.authUrl);
-        this._http = new HttpClient(this._config.apiUrl, this.auth);
-        this._generated = new GeneratedClientAdapter(this._config.apiUrl, this.auth);
+        this._http = new HttpClient(this._config.apiUrl, this.auth, {
+            timeoutMs: this._config.timeoutMs,
+            maxRetries: this._config.maxRetries,
+        });
+        this._generated = new GeneratedClientAdapter(this._config.apiUrl, this.auth, {
+            maxRetries: this._config.maxRetries,
+            timeoutMs: this._config.timeoutMs,
+        });
         const podIdFn = () => {
             if (!this._currentPodId) {
                 throw new Error("pod_id is required. Pass podId in the constructor or call client.setPodId(id).");
@@ -75,16 +85,18 @@ export class LemmaClient {
         this.records = new RecordsNamespace(this._generated, podIdFn);
         this.files = new FilesNamespace(this._generated, this._http, podIdFn);
         this.functions = new FunctionsNamespace(this._generated, podIdFn);
-        this.agents = new AgentsNamespace(this._generated, podIdFn);
+        this.agents = new AgentsNamespace(this._generated, podIdFn, () => this.conversations);
         this.agentRuntime = new AgentRuntimeNamespace(this._generated);
         this.conversations = new ConversationsNamespace(this._http, podIdFn);
         this.workflows = new WorkflowsNamespace(this._generated, this._http, podIdFn);
         this.desks = new DesksNamespace(this._generated, this._http, podIdFn);
+        this.widgets = new WidgetsNamespace(this._http, podIdFn);
         this.integrations = new IntegrationsNamespace(this._generated, this._http);
         this.resources = new ResourcesNamespace(this._http);
         this.resourceAccess = new ResourceAccessNamespace(this._generated, podIdFn);
         this.schedules = new SchedulesNamespace(this._generated, podIdFn);
         this.datastore = new DatastoreNamespace(this._generated, podIdFn);
+        this.queries = this.datastore;
         this.users = new UsersNamespace(this._generated);
         this.icons = new IconsNamespace(this._generated);
         this.pods = new PodsNamespace(this._generated, this._http);

package/dist/config.d.ts

@@ -5,6 +5,10 @@ export interface LemmaConfig {
     authUrl: string;
     /** Pod ID to scope all pod-level API calls */
     podId?: string;
+    /** Per-request timeout in ms (default 30000). */
+    timeoutMs?: number;
+    /** Max automatic retries on 429/502/503/504 (default 2). */
+    maxRetries?: number;
 }
 declare global {
     interface Window {

package/dist/config.js

@@ -45,5 +45,11 @@ export function resolveConfig(overrides = {}) {
     const podId = overrides.podId ??
         win.podId ??
         fromEnv("POD_ID");
-    return { apiUrl: apiUrl.replace(/\/$/, ""), authUrl: authUrl.replace(/\/$/, ""), podId };
+    return {
+        apiUrl: apiUrl.replace(/\/$/, ""),
+        authUrl: authUrl.replace(/\/$/, ""),
+        podId,
+        timeoutMs: overrides.timeoutMs ?? win.timeoutMs,
+        maxRetries: overrides.maxRetries ?? win.maxRetries,
+    };
 }

package/dist/generated.d.ts

@@ -2,7 +2,20 @@ import type { AuthManager } from "./auth.js";
 export declare class GeneratedClientAdapter {
     private readonly apiUrl;
     private readonly auth;
-    constructor(apiUrl: string, auth: AuthManager);
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    constructor(apiUrl: string, auth: AuthManager, options?: {
+        maxRetries?: number;
+        timeoutMs?: number;
+    });
     private configure;
     request<T>(operation: () => PromiseLike<T>): Promise<T>;
+    /**
+     * Enforce a per-attempt timeout on the generated client (which exposes no
+     * timeout of its own). The generated operation returns a CancelablePromise;
+     * on timeout we cancel it (aborting the underlying fetch) and surface a
+     * NetworkError, matching HttpClient.fetchWithTimeout. Non-cancelable or
+     * disabled-timeout cases fall through untouched.
+     */
+    private runWithTimeout;
 }

package/dist/generated.js

@@ -1,6 +1,11 @@
-import { ApiError } from "./http.js";
+import { NetworkError, apiErrorFromStatus } from "./http.js";
 import { ApiError as GeneratedApiError } from "./openapi_client/core/ApiError.js";
+import { CancelablePromise } from "./openapi_client/core/CancelablePromise.js";
 import { OpenAPI } from "./openapi_client/core/OpenAPI.js";
+import { retryDelayForStatus, sleep } from "./run-utils.js";
+import { CLIENT_HEADER_NAME, CLIENT_HEADER_VALUE } from "./version.js";
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_TIMEOUT_MS = 30_000;
 function extractMessage(body, fallback) {
     if (body && typeof body === "object" && typeof body.message === "string") {
         return body.message;
@@ -22,30 +27,76 @@ function extractDetails(body) {
 export class GeneratedClientAdapter {
     apiUrl;
     auth;
-    constructor(apiUrl, auth) {
+    maxRetries;
+    timeoutMs;
+    constructor(apiUrl, auth, options = {}) {
         this.apiUrl = apiUrl;
         this.auth = auth;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     }
     configure() {
         OpenAPI.BASE = this.apiUrl;
         OpenAPI.WITH_CREDENTIALS = true;
         OpenAPI.CREDENTIALS = this.auth.isTokenMode ? "omit" : "include";
         OpenAPI.TOKEN = this.auth.getBearerToken() ?? undefined;
-        OpenAPI.HEADERS = undefined;
+        OpenAPI.HEADERS = { [CLIENT_HEADER_NAME]: CLIENT_HEADER_VALUE };
     }
     async request(operation) {
         this.configure();
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.runWithTimeout(operation);
+            }
+            catch (error) {
+                if (error instanceof GeneratedApiError) {
+                    if (error.status === 401) {
+                        this.auth.markUnauthenticated();
+                    }
+                    // Retry transient gateway/rate-limit statuses. The generated client
+                    // doesn't expose response headers, so there's no Retry-After to honor
+                    // (retryDelayForStatus falls back to jittered backoff).
+                    const retryDelay = retryDelayForStatus(error.status, attempt, this.maxRetries, null);
+                    if (retryDelay !== null) {
+                        await sleep(retryDelay);
+                        continue;
+                    }
+                    throw apiErrorFromStatus(error.status, extractMessage(error.body, error.message), extractCode(error.body), extractDetails(error.body), error.body);
+                }
+                // Not an HTTP error (timeout/cancellation, programming error, raw
+                // transport failure) — preserve it untouched.
+                throw error;
+            }
+        }
+    }
+    /**
+     * Enforce a per-attempt timeout on the generated client (which exposes no
+     * timeout of its own). The generated operation returns a CancelablePromise;
+     * on timeout we cancel it (aborting the underlying fetch) and surface a
+     * NetworkError, matching HttpClient.fetchWithTimeout. Non-cancelable or
+     * disabled-timeout cases fall through untouched.
+     */
+    async runWithTimeout(operation) {
+        const op = operation();
+        if (this.timeoutMs <= 0 || !(op instanceof CancelablePromise)) {
+            return op;
+        }
+        let timer;
         try {
-            return await operation();
+            return await Promise.race([
+                op,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        op.cancel();
+                        reject(new NetworkError(`Request timed out after ${this.timeoutMs}ms`));
+                    }, this.timeoutMs);
+                }),
+            ]);
         }
-        catch (error) {
-            if (error instanceof GeneratedApiError) {
-                if (error.status === 401) {
-                    this.auth.markUnauthenticated();
-                }
-                throw new ApiError(error.status, extractMessage(error.body, error.message), extractCode(error.body), extractDetails(error.body), error.body);
+        finally {
+            if (timer) {
+                clearTimeout(timer);
             }
-            throw error;
         }
     }
 }

package/dist/http.d.ts

@@ -11,18 +11,64 @@ interface RequestOptions {
     headers?: HeadersInit;
     signal?: AbortSignal;
 }
+export interface HttpClientOptions {
+    /** Per-request timeout in ms (default 30000). Streaming requests are exempt. */
+    timeoutMs?: number;
+    /** Max automatic retries on 429/502/503/504 (default 2). */
+    maxRetries?: number;
+}
 export declare class ApiError extends Error {
     readonly statusCode: number;
     readonly code?: string | undefined;
     readonly details?: unknown | undefined;
     readonly rawResponse?: unknown | undefined;
+    /** Server correlation id (X-Request-Id) when present — quote it in bug reports. */
+    requestId?: string;
     constructor(statusCode: number, message: string, code?: string | undefined, details?: unknown | undefined, rawResponse?: unknown | undefined);
 }
+/** 401 — session missing/expired. */
+export declare class UnauthorizedError extends ApiError {
+    name: string;
+}
+/** 403 — authenticated but not permitted (often an RLS/grant denial). */
+export declare class ForbiddenError extends ApiError {
+    name: string;
+}
+/** 404 — resource not found. */
+export declare class NotFoundError extends ApiError {
+    name: string;
+}
+/** 409 — conflict (e.g. duplicate name). */
+export declare class ConflictError extends ApiError {
+    name: string;
+}
+/** 429 — rate limited; `retryAfterMs` is the server-advised wait if provided. */
+export declare class RateLimitError extends ApiError {
+    readonly retryAfterMs?: number | undefined;
+    name: string;
+    constructor(message: string, code?: string, details?: unknown, rawResponse?: unknown, retryAfterMs?: number | undefined);
+}
+/** 5xx — server-side error. */
+export declare class ServerError extends ApiError {
+    name: string;
+}
+/** Transport-level failure (DNS, connection refused, timeout) — no HTTP status. */
+export declare class NetworkError extends Error {
+    readonly cause?: unknown | undefined;
+    name: string;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Map an HTTP status to the most specific ApiError subclass. */
+export declare function apiErrorFromStatus(status: number, message: string, code?: string, details?: unknown, rawResponse?: unknown, retryAfterMsValue?: number): ApiError;
 export declare class HttpClient {
     private readonly apiUrl;
     private readonly auth;
-    constructor(apiUrl: string, auth: AuthManager);
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(apiUrl: string, auth: AuthManager, options?: HttpClientOptions);
     getBaseUrl(): string;
+    /** fetch with a default timeout, normalizing transport failures into NetworkError. */
+    private fetchWithTimeout;
     private buildUrl;
     private mergeHeaders;
     private parseError;

package/dist/http.js

@@ -2,11 +2,17 @@
  * Thin HTTP layer that wraps fetch with auth injection, error handling,
  * and automatic 401→unauthenticated state propagation.
  */
+import { retryDelayForStatus, serverRetryAfterMs, sleep } from "./run-utils.js";
+import { CLIENT_HEADER_NAME, CLIENT_HEADER_VALUE } from "./version.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
 export class ApiError extends Error {
     statusCode;
     code;
     details;
     rawResponse;
+    /** Server correlation id (X-Request-Id) when present — quote it in bug reports. */
+    requestId;
     constructor(statusCode, message, code, details, rawResponse) {
         super(message);
         this.statusCode = statusCode;
@@ -16,16 +22,104 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
+/** 401 — session missing/expired. */
+export class UnauthorizedError extends ApiError {
+    name = "UnauthorizedError";
+}
+/** 403 — authenticated but not permitted (often an RLS/grant denial). */
+export class ForbiddenError extends ApiError {
+    name = "ForbiddenError";
+}
+/** 404 — resource not found. */
+export class NotFoundError extends ApiError {
+    name = "NotFoundError";
+}
+/** 409 — conflict (e.g. duplicate name). */
+export class ConflictError extends ApiError {
+    name = "ConflictError";
+}
+/** 429 — rate limited; `retryAfterMs` is the server-advised wait if provided. */
+export class RateLimitError extends ApiError {
+    retryAfterMs;
+    name = "RateLimitError";
+    constructor(message, code, details, rawResponse, retryAfterMs) {
+        super(429, message, code, details, rawResponse);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** 5xx — server-side error. */
+export class ServerError extends ApiError {
+    name = "ServerError";
+}
+/** Transport-level failure (DNS, connection refused, timeout) — no HTTP status. */
+export class NetworkError extends Error {
+    cause;
+    name = "NetworkError";
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+}
+/** Map an HTTP status to the most specific ApiError subclass. */
+export function apiErrorFromStatus(status, message, code, details, rawResponse, retryAfterMsValue) {
+    switch (status) {
+        case 401: return new UnauthorizedError(status, message, code, details, rawResponse);
+        case 403: return new ForbiddenError(status, message, code, details, rawResponse);
+        case 404: return new NotFoundError(status, message, code, details, rawResponse);
+        case 409: return new ConflictError(status, message, code, details, rawResponse);
+        case 429: return new RateLimitError(message, code, details, rawResponse, retryAfterMsValue);
+        default:
+            return status >= 500
+                ? new ServerError(status, message, code, details, rawResponse)
+                : new ApiError(status, message, code, details, rawResponse);
+    }
+}
 export class HttpClient {
     apiUrl;
     auth;
-    constructor(apiUrl, auth) {
+    timeoutMs;
+    maxRetries;
+    constructor(apiUrl, auth, options = {}) {
         this.apiUrl = apiUrl;
         this.auth = auth;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     }
     getBaseUrl() {
         return this.apiUrl;
     }
+    /** fetch with a default timeout, normalizing transport failures into NetworkError. */
+    async fetchWithTimeout(url, init, userSignal) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.timeoutMs);
+        const onAbort = () => controller.abort();
+        if (userSignal) {
+            if (userSignal.aborted)
+                controller.abort();
+            else
+                userSignal.addEventListener("abort", onAbort, { once: true });
+        }
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (error) {
+            if (timedOut) {
+                throw new NetworkError(`Request timed out after ${this.timeoutMs}ms`, error);
+            }
+            if (userSignal?.aborted) {
+                throw error; // caller-initiated abort — propagate the original AbortError
+            }
+            throw new NetworkError(`Network request failed: ${String(error?.message ?? error)}`, error);
+        }
+        finally {
+            clearTimeout(timer);
+            userSignal?.removeEventListener("abort", onAbort);
+        }
+    }
     buildUrl(path, params) {
         let url = `${this.apiUrl}${path}`;
         if (!params) {
@@ -74,7 +168,12 @@ export class HttpClient {
         catch {
             // non-JSON error body
         }
-        return new ApiError(response.status, message, code, details, raw);
+        const retryMs = response.status === 429
+            ? serverRetryAfterMs(response.headers.get("retry-after")) ?? undefined
+            : undefined;
+        const error = apiErrorFromStatus(response.status, message, code, details, raw, retryMs);
+        error.requestId = response.headers.get("x-request-id") ?? undefined;
+        return error;
     }
     getRequestBody(options) {
         if (options.body === undefined) {
@@ -98,36 +197,56 @@ export class HttpClient {
                 headers: Object.fromEntries(Object.entries(this.auth.getRequestInit(initBase).headers ?? {}).filter(([key]) => key.toLowerCase() !== "content-type")),
             }
             : this.auth.getRequestInit(initBase);
-        return this.mergeHeaders(withAuth, options.headers);
+        const withClient = this.mergeHeaders(withAuth, { [CLIENT_HEADER_NAME]: CLIENT_HEADER_VALUE });
+        return this.mergeHeaders(withClient, options.headers);
     }
     async request(method, path, options = {}) {
         const url = this.buildUrl(path, options.params);
         const init = this.buildRequestInit(method, options);
-        const response = await fetch(url, init);
-        // Only 401 means the session is gone — 403 is a permission/RLS error, not an auth failure
-        if (response.status === 401) {
-            this.auth.markUnauthenticated();
-        }
-        if (!response.ok) {
-            throw await this.parseError(response);
-        }
-        if (response.status === 204) {
-            return undefined;
-        }
-        const contentType = response.headers.get("content-type") ?? "";
-        if (contentType.includes("application/json")) {
-            return response.json();
+        for (let attempt = 0;; attempt++) {
+            const response = await this.fetchWithTimeout(url, init, options.signal);
+            // Only 401 means the session is gone — 403 is a permission/RLS error, not an auth failure
+            if (response.status === 401) {
+                this.auth.markUnauthenticated();
+            }
+            const retryDelay = retryDelayForStatus(response.status, attempt, this.maxRetries, response.headers.get("retry-after"));
+            if (retryDelay !== null) {
+                await sleep(retryDelay, options.signal);
+                continue;
+            }
+            if (!response.ok) {
+                throw await this.parseError(response);
+            }
+            if (response.status === 204) {
+                return undefined;
+            }
+            const contentType = response.headers.get("content-type") ?? "";
+            if (contentType.includes("application/json")) {
+                return response.json();
+            }
+            return response.text();
         }
-        return response.text();
     }
     async stream(path, options = {}) {
-        const response = await fetch(this.buildUrl(path, options.params), this.buildRequestInit(options.method ?? "GET", {
-            ...options,
-            headers: {
-                Accept: "text/event-stream",
-                ...options.headers,
-            },
-        }));
+        // Streams are deliberately timeout-exempt (they're long-lived), but we still
+        // normalize transport failures into NetworkError so the typed-error contract
+        // holds on the SSE path too.
+        let response;
+        try {
+            response = await fetch(this.buildUrl(path, options.params), this.buildRequestInit(options.method ?? "GET", {
+                ...options,
+                headers: {
+                    Accept: "text/event-stream",
+                    ...options.headers,
+                },
+            }));
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                throw error; // caller-initiated abort — propagate the original AbortError
+            }
+            throw new NetworkError(`Network request failed: ${String(error?.message ?? error)}`, error);
+        }
         if (response.status === 401) {
             this.auth.markUnauthenticated();
         }
@@ -141,7 +260,7 @@ export class HttpClient {
     }
     async requestBytes(method, path) {
         const url = `${this.apiUrl}${path}`;
-        const response = await fetch(url, this.auth.getRequestInit({ method }));
+        const response = await this.fetchWithTimeout(url, this.auth.getRequestInit({ method }));
         if (response.status === 401) {
             this.auth.markUnauthenticated();
         }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { LemmaClient } from "./client.js";
 export type { LemmaConfig } from "./client.js";
 export { AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, } from "./auth.js";
 export type { AuthState, AuthListener, AuthStatus, UserInfo, AuthRedirectMode, BuildAuthUrlOptions, BuildFederatedLogoutUrlOptions, RedirectToFederatedLogoutOptions, ResolveSafeRedirectUriOptions, } from "./auth.js";
-export { ApiError } from "./http.js";
+export { ApiError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, RateLimitError, ServerError, NetworkError, apiErrorFromStatus, } from "./http.js";
 export * from "./types.js";
 export { readSSE, parseSSEJson } from "./streams.js";
 export type { SseRawEvent } from "./streams.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { LemmaClient } from "./client.js";
 export { AuthManager, buildAuthUrl, buildFederatedLogoutUrl, clearTestingToken, getTestingToken, resolveSafeRedirectUri, setTestingToken, } from "./auth.js";
-export { ApiError } from "./http.js";
+export { ApiError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, RateLimitError, ServerError, NetworkError, apiErrorFromStatus, } from "./http.js";
 export * from "./types.js";
 export { readSSE, parseSSEJson } from "./streams.js";
 export { normalizeRunStatus, isTerminalFunctionStatus, isTerminalFlowStatus, sleep, nextBackoffDelay, } from "./run-utils.js";

package/dist/namespaces/agents.d.ts

@@ -2,14 +2,33 @@ import type { GeneratedClientAdapter } from "../generated.js";
 import type { CreateAgentRequest } from "../openapi_client/models/CreateAgentRequest.js";
 import type { AgentPermissionsReplaceRequest } from "../openapi_client/models/AgentPermissionsReplaceRequest.js";
 import type { UpdateAgentRequest } from "../openapi_client/models/UpdateAgentRequest.js";
+import type { ConversationsNamespace } from "./conversations.js";
+export interface RunAgentOptions {
+    title?: string;
+    metadata?: Record<string, unknown>;
+    /** Stream tokens instead of awaiting the full reply. */
+    stream?: boolean;
+    signal?: AbortSignal;
+}
 export declare class AgentsNamespace {
     private readonly client;
     private readonly podId;
-    constructor(client: GeneratedClientAdapter, podId: () => string);
+    private readonly conversations?;
+    constructor(client: GeneratedClientAdapter, podId: () => string, conversations?: (() => ConversationsNamespace) | undefined);
     list(options?: {
         limit?: number;
         pageToken?: string;
     }): Promise<import("../types.js").AgentListResponse>;
+    /**
+     * Run an agent on a single message (the `.run` verb, alongside
+     * `functions.run` / `datastore.query`). Note the return contract differs:
+     * those return the result directly, whereas an agent reply is asynchronous —
+     * this opens a fresh conversation, sends `message`, and returns the created
+     * conversation (read the reply via `client.conversations.messages.list(conv.id)`).
+     * With `stream: true` it returns the SSE stream so you can consume tokens as
+     * they arrive.
+     */
+    run(agentName: string, message: string, options?: RunAgentOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>> | import("../types.js").Conversation>;
     create(payload: CreateAgentRequest): Promise<import("../types.js").AgentActionResponse>;
     get(agentName: string): Promise<import("../types.js").AgentDetailResponse>;
     update(agentName: string, payload: UpdateAgentRequest): Promise<import("../types.js").AgentActionResponse>;