@betterlu/agentlu 1.5.0 → 1.7.0

package/README.md

@@ -10,7 +10,7 @@ const client = new OpenAI({ baseURL: "http://localhost:8912/v1", apiKey });
 const r = await client.responses.create({ model: "fast", input: "hi" });
 ```
 
-This client adds get-or-create registration, typed `runJson`, and auto-retry on `409 thread_busy`.
+This client adds get-or-create registration, typed `runJson` / `runText`, use-case catalogs, background `wait`, client-side `timeoutMs`, and auto-retry on `409 thread_busy`.
 
 ## Install
 
@@ -75,6 +75,48 @@ const { data } = await mealEnricher.runJson<{ meal: string }>({ input: "two eggs
 
 Set a field on `run` or `runJson` to override its registered default. `strict: false` still requires parsed JSON but does not require that value to match the schema.
 
+Do **not** put `maxOutputTokens` on client defaults — the server ignores it. Pass `max_output_tokens` (or `maxOutputTokens`) on the run.
+
+Several use-cases sharing one client:
+
+```ts
+const ai = alu.useCases({
+  extract: {
+    name: "myapp-extract",
+    defaults: { agent: "api", store: false, timeoutMs: 45_000, instructions: "Parse into JSON." },
+  },
+  tag: { defaults: { agent: "api", store: false } },
+});
+await ai.ensure(); // boot
+const { data } = await ai.extract.runJson<{ items: string[] }>({ input: "two milk" });
+```
+
+Plain text (throws unless `status === "completed"` with non-empty `output_text`):
+
+```ts
+const { text } = await ai.tag.runText({ input: "summarize this" });
+```
+
+`timeoutMs` aborts the HTTP attempt and, when `timeout_ms` is omitted, is also sent as the server-side run budget. Constructor `new AgentLu({ timeoutMs: 30_000 })` is the default for calls that omit it.
+
+Upload-and-run:
+
+```ts
+await extract.runJson({
+  input: "what's in this photo",
+  files: [{ data: bytes, filename: "shelf.jpg", mime: "image/jpeg" }],
+});
+```
+
+Background poll:
+
+```ts
+const queued = await extract.run({ input, schema, background: true, store: false });
+const done = await alu.responses.wait(queued.response.id, { intervalMs: 1000, timeoutMs: 120_000 });
+```
+
+`runJson({ attempts: 2 })` re-asks once after `schema_validation_failed` / `incomplete` / `missing_output_parsed`. It never scrapes `output_text`.
+
 Env: `AGENTLU_URL` (default `http://localhost:8912/v1`), `AGENTLU_API_KEY`.
 
 ## Decisions (System One / Jev)
@@ -113,10 +155,12 @@ if (answers.team.type === "choice") return lookupOrder(answers.team.choice);
 | `choice` | `choice`, `confidence`, `probabilities` per option |
 | `score` | `score`, `confidence`, `legend`, `probabilities` per step |
 
-`decisions.ask()` is the same call returning only the answers map. Discover the
+`decisions.ask()` is the same call returning only the answers map.
+`decisions.askOrNull()` is fail-open (`null` on unconfigured/error). Discover the
 model in `GET /v1/models` (`harness: "systemone"`); it is only callable on
 `POST /v1/decisions`, sync, no streaming. A missing key surfaces as HTTP 503
-`systemone_unconfigured` (not retried by the SDK).
+`systemone_unconfigured` (not retried by the SDK). Use-case runners expose the
+same `decisions` helpers on their own key.
 
 Decision calls accept three client-side options beyond `state` / `questions` /
 `model`:

package/dist/index.d.ts

@@ -6,20 +6,36 @@
  *   new OpenAI({ baseURL: "http://localhost:8912/v1", apiKey })
  *
  * This client exists for the ergonomic bits OpenAI's SDK does not know about:
- * get-or-create registration, typed `runJson`, and auto-retry on
- * `409 thread_busy`.
+ * get-or-create registration, typed `runJson` / `runText`, use-case catalogs,
+ * background `wait`, and auto-retry on `409 thread_busy`.
  */
 export declare const DEFAULT_BASE_URL = "http://localhost:8912/v1";
+/**
+ * Accept an origin (`http://host:8912`) or a `/v1` base and normalize to the
+ * `/v1` base the API actually serves, so `new AgentLu({ baseUrl: "http://host:8912" })`
+ * works the same as the documented default.
+ */
+export declare function normalizeBaseUrl(raw: string): string;
 export type Backend = "pi";
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type ApiToolFamily = "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
+export type ApiToolChoice = "auto" | "none" | "required";
 /** Closed tool-family request accepted by `/v1/responses`. */
 export interface ApiToolSpec {
     type: ApiToolFamily;
     /** Optional family-specific operation allowlist (HubLu, BrowserLu, or AndroidLu). */
     allowed_tools?: string[];
 }
-export type ApiToolInput = ApiToolFamily | ApiToolSpec;
+/**
+ * Native MCP server for the machine-only `api` agent. Mounted per run;
+ * `allowed_tools` pre-scopes the names the server lists.
+ */
+export interface ApiMcpServerSpec {
+    type: "mcp";
+    url: string;
+    allowed_tools?: string[];
+}
+export type ApiToolInput = ApiToolFamily | ApiToolSpec | ApiMcpServerSpec;
 export type BrowserStatus = "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted";
 export interface BrowserScreenshot {
     id: string;
@@ -87,6 +103,14 @@ export type TextFormat = TextFormatText | TextFormatJsonSchema;
 export interface TextConfig {
     format?: TextFormat;
 }
+export type FileKind = "image" | "video" | "text" | "document";
+/** Local file to upload and attach on the same `run` / `stream`. */
+export interface RunFile {
+    data: Uint8Array | Blob;
+    filename: string;
+    mime?: string;
+    kind?: FileKind;
+}
 /** Yes/no, answered as the probability that the answer is yes. */
 export interface NoulQuestion {
     type: "noul";
@@ -137,7 +161,7 @@ export interface DecisionOptions {
     /**
      * Per-attempt client deadline in milliseconds. A timeout aborts the request
      * and is never retried; without it the request is bounded only by the
-     * caller's fetch implementation.
+     * caller's fetch implementation (or the AgentLu constructor `timeoutMs`).
      */
     timeoutMs?: number;
     /** Total attempts including the first. Defaults to the shared 5-attempt policy. */
@@ -158,6 +182,12 @@ export interface DecisionObject {
     } | null;
     [k: string]: unknown;
 }
+export interface DecisionApi {
+    create: (body: DecisionOptions) => Promise<DecisionObject>;
+    ask: (body: DecisionOptions) => Promise<Record<string, DecisionAnswer>>;
+    /** Fail-open: returns `null` when the model is unconfigured or the call fails. */
+    askOrNull: (body: DecisionOptions) => Promise<Record<string, DecisionAnswer> | null>;
+}
 /** Question builders; sugar over the wire shape. */
 export declare const noul: (instructions: string, criteria?: {
     true: string;
@@ -184,6 +214,12 @@ export interface AgentLuOptions {
     baseUrl?: string;
     apiKey?: string;
     fetch?: typeof fetch;
+    /**
+     * Default per-attempt client deadline for `run` / `stream` / `upload` /
+     * `decisions` when the call omits `timeoutMs`. Also fills `timeout_ms` on
+     * `/v1/responses` when the call omits that field.
+     */
+    timeoutMs?: number;
 }
 export interface ClientDefaults {
     backend?: Backend;
@@ -196,6 +232,11 @@ export interface ClientDefaults {
     store?: boolean;
     reasoning?: ClientReasoningOptions;
     text?: TextConfig;
+    /**
+     * Retired on client defaults (server ignores it). Pass `max_output_tokens`
+     * or `maxOutputTokens` on `run` / `runJson` / `stream` instead.
+     */
+    maxOutputTokens?: never;
 }
 /** High-level use-case declaration for model routing and priority tier. */
 export interface UseCaseProfile {
@@ -204,18 +245,33 @@ export interface UseCaseProfile {
     /** MiniMax priority admission consent (priority costs 1.5x standard). */
     priorityTier?: "never" | "retry" | "first" | "always";
 }
+export interface UseCaseDeclaration {
+    /** Registered client name. Defaults to the catalog key. */
+    name?: string;
+    person?: string | null;
+    defaults?: ClientDefaults;
+    use_case_profile?: UseCaseProfile;
+}
+export type UseCaseCatalog<T extends Record<string, UseCaseDeclaration>> = {
+    [K in keyof T]: UseCaseRunner;
+} & {
+    /** Idempotent get-or-create for every use-case. Safe to call on boot. */
+    ensure: () => Promise<void>;
+};
 export interface RunOptions {
     backend?: Backend;
     agent?: string;
     model?: string;
     input?: string;
     /**
-      * Attachments previously uploaded via `upload()`. Prepended to the user
-      * turn using each file's `kind` (`input_image` / `input_video` / `input_file`).
-      */
+     * Attachments previously uploaded via `upload()`. Prepended to the user
+     * turn using each file's `kind` (`input_image` / `input_video` / `input_file`).
+     */
     fileIds?: string[];
     /** Optional kinds aligned with `fileIds` (from `upload()`). Defaults to image. */
-    fileKinds?: Array<"image" | "video" | "text" | "document">;
+    fileKinds?: FileKind[];
+    /** Upload-and-attach in one call. Combined with `fileIds` when both are set. */
+    files?: RunFile[];
     /** Structured input messages (OpenAI shape) - overrides `input`. */
     inputMessages?: Array<{
         role: string;
@@ -223,18 +279,32 @@ export interface RunOptions {
     }>;
     instructions?: string;
     tools?: ApiToolInput[];
+    tool_choice?: ApiToolChoice;
     reasoning?: ReasoningOptions;
     text?: TextConfig;
     strict?: boolean;
     conversation?: string;
+    previous_response_id?: string;
     store?: boolean;
     person?: string | null;
     owner?: "client" | "person";
     title?: string;
+    /** Server-side run budget (wire name). */
     timeout_ms?: number;
+    /**
+     * Per-attempt client deadline. When `timeout_ms` is omitted, the same value
+     * is also sent as the server-side budget.
+     */
+    timeoutMs?: number;
+    /** Caller cancellation, combined with `timeoutMs` when both are set. */
+    signal?: AbortSignal;
+    /** Total HTTP attempts including the first. Defaults to the shared 5-attempt policy. */
+    maxAttempts?: number;
     include?: string[];
     temperature?: number;
     max_output_tokens?: number;
+    /** Alias for `max_output_tokens` on this run (not a client default). */
+    maxOutputTokens?: number;
     /** Caller metadata stored on the response row (console visibility). */
     metadata?: Record<string, string>;
     /** JSON Schema. When set, `data` on the result is the validated object. */
@@ -242,6 +312,36 @@ export interface RunOptions {
     schemaName?: string;
     /** Queue a background run instead of waiting. Returns the queued response. */
     background?: boolean;
+    /**
+     * Explicit idempotency key. Non-streaming runs always send one (generated
+     * when omitted) so SDK-level retries cannot double-run; set it yourself to
+     * make two separate `run` calls idempotent.
+     */
+    idempotencyKey?: string;
+    /**
+     * `runJson` only: extra model attempts after `schema_validation_failed`,
+     * `missing_output_parsed`, or `incomplete`. Defaults to 1 (no extra tries).
+     */
+    attempts?: number;
+    /** `run`/`runJson`/`runText` only: throw instead of returning when the run is `incomplete`. */
+    throwOnIncomplete?: boolean;
+}
+export interface WaitOptions {
+    /** Delay between polls. Defaults to 1000ms. */
+    intervalMs?: number;
+    /**
+     * Overall wait deadline (default 10 minutes). The in-flight poll is aborted
+     * when it fires. Pass `0` to wait indefinitely.
+     */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** Default overall deadline for `responses.wait`. */
+export declare const DEFAULT_WAIT_TIMEOUT_MS: number;
+export interface UploadOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxAttempts?: number;
 }
 export interface ResponseObject {
     id: string;
@@ -273,10 +373,36 @@ export interface ResponseObject {
     };
     [k: string]: unknown;
 }
+export declare function isTerminalStatus(status: string): boolean;
+/**
+ * One SSE event from `/v1/responses` with `stream: true`. The event names and
+ * shapes mirror the OpenAI Responses stream; `delta` is the incremental text
+ * for `response.output_text.delta`.
+ */
+export interface StreamEvent {
+    type: string;
+    sequence_number?: number;
+    /** Incremental text on `response.output_text.delta`. */
+    delta?: string;
+    [k: string]: unknown;
+}
+/**
+ * Accumulate a raw stream into typed events and the final text. `events()`
+ * yields every event; `finalText()` resolves after the stream ends with the
+ * concatenated `response.output_text.delta` payloads.
+ *
+ *   const stream = alu.typedStream({ input: "hi" });
+ *   for await (const ev of stream) { ... }
+ *   const text = stream.finalText();
+ */
+export declare function typedStream(source: AsyncIterable<Record<string, unknown>>): AsyncIterable<StreamEvent> & {
+    finalText: () => Promise<string>;
+};
 export declare class AgentLu {
     readonly baseUrl: string;
     apiKey: string | undefined;
     private readonly fetchImpl;
+    private readonly defaultTimeoutMs;
     constructor(opts?: AgentLuOptions);
     private postClient;
     /** Get-or-create a client by name. Caches the returned key on this instance. */
@@ -295,12 +421,21 @@ export declare class AgentLu {
      * The use-case's defaults (system prompt, tools, temperature, ...) live
      * server-side on the client, so `run()` only needs the input. Registering a
      * use-case is registering a client - `alu.useCase("mealu-enrich", {...})`.
-    */
+     */
     useCase(name: string, opts?: {
         person?: string | null;
         defaults?: ClientDefaults;
         use_case_profile?: UseCaseProfile;
     }): UseCaseRunner;
+    /**
+     * Several named use-case runners that share this client. Call `ensure()` on
+     * boot, then `catalog.extract.runJson({ input })`.
+     *
+     *   const ai = alu.useCases({
+     *     extract: { name: "deallu-extract", defaults: { agent: "api", store: false } },
+     *   });
+     */
+    useCases<T extends Record<string, UseCaseDeclaration>>(specs: T): UseCaseCatalog<T>;
     /**
      * Register a use-case client and resolve to its api key. The key is cached
      * on this instance (same semantics as `register`), so a following
@@ -316,7 +451,7 @@ export declare class AgentLu {
      * Upload an image, video, or document for use with `run({ fileIds })`.
      * Returns the `file_id` and stored `kind`.
      */
-    upload(data: Uint8Array | Blob, filename: string, mime?: string): Promise<{
+    upload(data: Uint8Array | Blob, filename: string, mime?: string, opts?: UploadOptions): Promise<{
         id: string;
         kind?: string;
     }>;
@@ -335,9 +470,33 @@ export declare class AgentLu {
         data: T;
         response: ResponseObject;
     }>;
+    runText(opts: RunOptions): Promise<{
+        text: string;
+        response: ResponseObject;
+    }>;
+    /**
+     * `runJson` that returns `null` instead of throwing on any failure. For
+     * best-effort enrichment where a missing result is a normal outcome.
+     */
+    runJsonOrNull<T = unknown>(opts: RunOptions): Promise<T | null>;
+    /** `runText` that returns `null` instead of throwing on any failure. */
+    runTextOrNull(opts: RunOptions): Promise<string | null>;
+    stream(opts: RunOptions): AsyncGenerator<Record<string, unknown>>;
+    /**
+     * Typed stream: yields `StreamEvent`s and exposes `finalText()` with the
+     * concatenated output text after the stream ends.
+     */
+    typedStream(opts: RunOptions): AsyncIterable<StreamEvent> & {
+        finalText: () => Promise<string>;
+    };
     private runForApiKey;
     private runJsonForApiKey;
+    private runJsonOnce;
+    private runTextForApiKey;
     private createRunResponse;
+    private buildRunBody;
+    private uploadRunFiles;
+    private transportFromRun;
     readonly responses: {
         create: (body: Record<string, unknown>) => Promise<ResponseObject>;
         retrieve: (id: string) => Promise<ResponseObject>;
@@ -350,8 +509,11 @@ export declare class AgentLu {
             data: ResponseObject[];
         }>;
         stream: (body: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>, any, any>;
+        wait: (id: string, opts?: WaitOptions) => Promise<ResponseObject>;
     };
-    private streamForApiKey;
+    private waitForApiKey;
+    private streamRunForApiKey;
+    private streamRawForApiKey;
     readonly threads: {
         create: (body?: Record<string, unknown>) => Promise<unknown>;
         retrieve: (id: string) => Promise<unknown>;
@@ -375,17 +537,14 @@ export declare class AgentLu {
      * `timeoutMs` bounds each attempt (timeouts are never retried), `maxAttempts`
      * overrides the shared 5-attempt policy, and `signal` cancels the call.
      */
-    readonly decisions: {
-        create: (body: DecisionOptions) => Promise<DecisionObject>;
-        /** Same call, returning only the answers map. */
-        ask: (body: DecisionOptions) => Promise<Record<string, DecisionAnswer>>;
-    };
+    readonly decisions: DecisionApi;
     agents(): Promise<unknown>;
     models(): Promise<unknown>;
     tools(): Promise<unknown>;
     health(): Promise<unknown>;
     private request;
     private raw;
+    private rawOnce;
 }
 /**
  * A runner bound to one registered use-case (one service client + its
@@ -404,13 +563,28 @@ export declare class UseCaseRunner {
     private readonly operations;
     private apiKey;
     private ready;
+    /** In-flight/short-lived guard so a burst of runs does not stampede registration. */
+    private registerFailures;
+    private lastRegisterError;
+    private registerFailedAt;
+    /** Cooldown is short and only suppresses *repeated* failures in one burst. */
+    private static readonly REGISTER_COOLDOWN_MS;
     constructor(parent: AgentLu, name: string, opts?: {
         person?: string | null;
         defaults?: ClientDefaults;
         use_case_profile?: UseCaseProfile;
     });
-    /** Idempotent get-or-create; safe to call before every run. */
-    private ensure;
+    /**
+   * Idempotent get-or-create; safe to call on boot or before every run.
+   * A failed registration is remembered for a short cooldown so an app that
+   * calls `ensure()` in a loop does not hammer the server; runs always retry
+   * registration transparently (pass `force`).
+   */
+    ensure(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    private invalidate;
+    private withAuthRetry;
     /**
      * Run with this use-case's key. Request fields that are set override the
      * use-case's registered defaults; unset fields inherit them server-side.
@@ -423,13 +597,33 @@ export declare class UseCaseRunner {
         data: T;
         response: ResponseObject;
     }>;
-    stream(body: Record<string, unknown>): Promise<AsyncGenerator<Record<string, unknown>, any, any>>;
+    runText(opts: RunOptions): Promise<{
+        text: string;
+        response: ResponseObject;
+    }>;
+    /** `runJson` that returns `null` instead of throwing on any failure. */
+    runJsonOrNull<T = unknown>(opts: RunOptions): Promise<T | null>;
+    /** `runText` that returns `null` instead of throwing on any failure. */
+    runTextOrNull(opts: RunOptions): Promise<string | null>;
+    stream(opts: RunOptions): AsyncGenerator<Record<string, unknown>>;
+    /** Typed stream for this use-case: events + `finalText()`. */
+    typedStream(opts: RunOptions): AsyncIterable<StreamEvent> & {
+        finalText: () => Promise<string>;
+    };
     /**
      * Upload with this use-case's key, so the file is owned by the same
      * service client that will reference it via `run({ fileIds })`.
      */
-    upload(data: Uint8Array | Blob, filename: string, mime?: string): Promise<{
+    upload(data: Uint8Array | Blob, filename: string, mime?: string, opts?: UploadOptions): Promise<{
         id: string;
         kind?: string;
     }>;
+    readonly responses: {
+        retrieve: (id: string) => Promise<ResponseObject>;
+        cancel: (id: string) => Promise<ResponseObject>;
+        wait: (id: string, opts?: WaitOptions) => Promise<ResponseObject>;
+    };
+    readonly decisions: DecisionApi;
 }
+/** True when an error should be retried by the shared policy. */
+export declare function isRetryableError(err: unknown): boolean;

package/dist/index.js

@@ -6,10 +6,21 @@
  *   new OpenAI({ baseURL: "http://localhost:8912/v1", apiKey })
  *
  * This client exists for the ergonomic bits OpenAI's SDK does not know about:
- * get-or-create registration, typed `runJson`, and auto-retry on
- * `409 thread_busy`.
+ * get-or-create registration, typed `runJson` / `runText`, use-case catalogs,
+ * background `wait`, and auto-retry on `409 thread_busy`.
  */
 export const DEFAULT_BASE_URL = "http://localhost:8912/v1";
+/**
+ * Accept an origin (`http://host:8912`) or a `/v1` base and normalize to the
+ * `/v1` base the API actually serves, so `new AgentLu({ baseUrl: "http://host:8912" })`
+ * works the same as the documented default.
+ */
+export function normalizeBaseUrl(raw) {
+    const trimmed = raw.replace(/\/+$/, "");
+    if (/\/v1$/.test(trimmed))
+        return trimmed;
+    return `${trimmed}/v1`;
+}
 /** Strip client-only decision options before the body reaches `/v1/decisions`. */
 function decisionWire(body) {
     const wire = { state: body.state, questions: body.questions };
@@ -17,8 +28,12 @@ function decisionWire(body) {
         wire.model = body.model;
     return wire;
 }
-function decisionRequestOptions(body) {
-    return { timeoutMs: body.timeoutMs, maxAttempts: body.maxAttempts, signal: body.signal };
+function decisionRequestOptions(body, defaultTimeoutMs) {
+    return {
+        timeoutMs: body.timeoutMs ?? defaultTimeoutMs,
+        maxAttempts: body.maxAttempts,
+        signal: body.signal,
+    };
 }
 /** Question builders; sugar over the wire shape. */
 export const noul = (instructions, criteria) => ({
@@ -65,6 +80,49 @@ export class AgentLuResponseError extends AgentLuError {
         this.responseStatus = responseStatus;
     }
 }
+/** Default overall deadline for `responses.wait`. */
+export const DEFAULT_WAIT_TIMEOUT_MS = 10 * 60_000;
+export function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "incomplete" || status === "cancelled";
+}
+/**
+ * Accumulate a raw stream into typed events and the final text. `events()`
+ * yields every event; `finalText()` resolves after the stream ends with the
+ * concatenated `response.output_text.delta` payloads.
+ *
+ *   const stream = alu.typedStream({ input: "hi" });
+ *   for await (const ev of stream) { ... }
+ *   const text = stream.finalText();
+ */
+export function typedStream(source) {
+    let text = "";
+    let done = false;
+    const it = (async function* () {
+        try {
+            for await (const raw of source) {
+                const ev = raw;
+                if (ev.type === "response.output_text.delta" && typeof ev.delta === "string") {
+                    text += ev.delta;
+                }
+                yield ev;
+            }
+        }
+        finally {
+            done = true;
+        }
+    })();
+    return Object.assign(it, {
+        finalText: async () => {
+            // Drain if the caller never iterated to the end.
+            if (!done) {
+                for await (const _ of it) {
+                    void _;
+                }
+            }
+            return text;
+        },
+    });
+}
 function env(name) {
     return typeof process !== "undefined" ? process.env[name] : undefined;
 }
@@ -73,20 +131,37 @@ export class AgentLu {
     baseUrl;
     apiKey;
     fetchImpl;
+    defaultTimeoutMs;
     constructor(opts = {}) {
-        this.baseUrl = (opts.baseUrl ?? env("AGENTLU_URL") ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.baseUrl = normalizeBaseUrl(opts.baseUrl ?? env("AGENTLU_URL") ?? DEFAULT_BASE_URL);
         this.apiKey = opts.apiKey ?? env("AGENTLU_API_KEY");
         this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.defaultTimeoutMs = opts.timeoutMs;
         scopedUseCaseOperations.set(this, {
             register: (name, registerOpts) => this.registerForUseCase(name, registerOpts),
             run: (apiKey, runOpts) => this.runForApiKey(apiKey, runOpts),
             runJson: (apiKey, runOpts) => this.runJsonForApiKey(apiKey, runOpts),
-            stream: (apiKey, body) => this.streamForApiKey(body, apiKey),
-            upload: (apiKey, data, filename, mime) => this.uploadForApiKey(data, filename, mime, apiKey),
+            runText: (apiKey, runOpts) => this.runTextForApiKey(apiKey, runOpts),
+            stream: (apiKey, runOpts) => this.streamRunForApiKey(runOpts, apiKey),
+            upload: (apiKey, data, filename, mime, uploadOpts) => this.uploadForApiKey(data, filename, mime, apiKey, uploadOpts),
+            wait: (apiKey, id, waitOpts) => this.waitForApiKey(id, apiKey, waitOpts),
+            retrieve: (apiKey, id, reqOpts) => this.request("GET", `/responses/${encodeURIComponent(id)}`, undefined, {
+                ...reqOpts,
+                apiKey,
+            }),
+            cancel: (apiKey, id, reqOpts) => this.request("POST", `/responses/${encodeURIComponent(id)}/cancel`, undefined, {
+                ...reqOpts,
+                apiKey,
+            }),
+            decideCreate: (apiKey, body) => this.request("POST", "/decisions", decisionWire(body), { ...decisionRequestOptions(body, this.defaultTimeoutMs), apiKey }),
+            decideAsk: async (apiKey, body) => (await this.request("POST", "/decisions", decisionWire(body), { ...decisionRequestOptions(body, this.defaultTimeoutMs), apiKey })).answers,
         });
     }
     postClient(name, opts) {
-        return this.request("POST", "/clients", { name, ...opts }, { auth: false });
+        // Registration is get-or-create and callers gate it behind `ensure()`'s
+        // cooldown; two attempts smooth a blip without stacking long backoffs
+        // before the cooldown can do its job.
+        return this.request("POST", "/clients", { name, ...opts }, { auth: false, maxAttempts: 2 });
     }
     /** Get-or-create a client by name. Caches the returned key on this instance. */
     async register(name, opts) {
@@ -101,10 +176,30 @@ export class AgentLu {
      * The use-case's defaults (system prompt, tools, temperature, ...) live
      * server-side on the client, so `run()` only needs the input. Registering a
      * use-case is registering a client - `alu.useCase("mealu-enrich", {...})`.
-    */
+     */
     useCase(name, opts) {
         return new UseCaseRunner(this, name, opts);
     }
+    /**
+     * Several named use-case runners that share this client. Call `ensure()` on
+     * boot, then `catalog.extract.runJson({ input })`.
+     *
+     *   const ai = alu.useCases({
+     *     extract: { name: "deallu-extract", defaults: { agent: "api", store: false } },
+     *   });
+     */
+    useCases(specs) {
+        const runners = {};
+        for (const key of Object.keys(specs)) {
+            const spec = specs[key];
+            runners[key] = this.useCase(spec.name ?? String(key), spec);
+        }
+        const catalog = { ...runners };
+        catalog.ensure = async () => {
+            await Promise.all(Object.values(runners).map((runner) => runner.ensure()));
+        };
+        return catalog;
+    }
     /**
      * Register a use-case client and resolve to its api key. The key is cached
      * on this instance (same semantics as `register`), so a following
@@ -127,14 +222,19 @@ export class AgentLu {
      * Upload an image, video, or document for use with `run({ fileIds })`.
      * Returns the `file_id` and stored `kind`.
      */
-    async upload(data, filename, mime) {
-        return this.uploadForApiKey(data, filename, mime, this.apiKey);
+    async upload(data, filename, mime, opts) {
+        return this.uploadForApiKey(data, filename, mime, this.apiKey, opts);
     }
-    async uploadForApiKey(data, filename, mime, apiKey) {
+    async uploadForApiKey(data, filename, mime, apiKey, opts) {
         const form = new FormData();
         const blob = data instanceof Blob ? data : new Blob([new Uint8Array(data)], { type: mime ?? "application/octet-stream" });
         form.append("file", blob, filename);
-        const res = await this.raw("POST", "/files", form, { apiKey });
+        const res = await this.raw("POST", "/files", form, {
+            apiKey,
+            timeoutMs: opts?.timeoutMs,
+            signal: opts?.signal,
+            maxAttempts: opts?.maxAttempts,
+        });
         return (await res.json());
     }
     async me() {
@@ -152,14 +252,68 @@ export class AgentLu {
         assertJsonRunOptions(opts);
         return this.runJsonForApiKey(this.apiKey, opts);
     }
+    async runText(opts) {
+        return this.runTextForApiKey(this.apiKey, opts);
+    }
+    /**
+     * `runJson` that returns `null` instead of throwing on any failure. For
+     * best-effort enrichment where a missing result is a normal outcome.
+     */
+    async runJsonOrNull(opts) {
+        try {
+            const { data } = await this.runJson(opts);
+            return data;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** `runText` that returns `null` instead of throwing on any failure. */
+    async runTextOrNull(opts) {
+        try {
+            const { text } = await this.runText(opts);
+            return text;
+        }
+        catch {
+            return null;
+        }
+    }
+    async *stream(opts) {
+        yield* this.streamRunForApiKey(opts, this.apiKey);
+    }
+    /**
+     * Typed stream: yields `StreamEvent`s and exposes `finalText()` with the
+     * concatenated output text after the stream ends.
+     */
+    typedStream(opts) {
+        return typedStream(this.stream(opts));
+    }
     async runForApiKey(apiKey, opts) {
         const response = await this.createRunResponse(opts, apiKey);
         if (response.status === "failed" && response.error) {
             throw new AgentLuError(200, response.error.code, response.error.message, response.error.retryable);
         }
+        if (opts.throwOnIncomplete && response.status === "incomplete") {
+            throw new AgentLuResponseError(response);
+        }
         return { data: response.output_parsed, response };
     }
     async runJsonForApiKey(apiKey, opts) {
+        const attempts = jsonAttempts(opts);
+        let last;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            try {
+                return await this.runJsonOnce(apiKey, opts);
+            }
+            catch (e) {
+                last = e;
+                if (!isJsonRetryable(e) || attempt >= attempts - 1)
+                    throw e;
+            }
+        }
+        throw last;
+    }
+    async runJsonOnce(apiKey, opts) {
         const response = await this.createRunResponse(opts, apiKey);
         if (response.status !== "completed")
             throw new AgentLuResponseError(response);
@@ -168,15 +322,44 @@ export class AgentLu {
         }
         return { data: response.output_parsed, response };
     }
+    async runTextForApiKey(apiKey, opts) {
+        const response = await this.createRunResponse(opts, apiKey);
+        if (response.status !== "completed")
+            throw new AgentLuResponseError(response);
+        const text = response.output_text ?? "";
+        if (!text.trim()) {
+            throw new AgentLuError(200, "empty_output", "Completed response did not include output_text.", false);
+        }
+        return { text, response };
+    }
     async createRunResponse(opts, apiKey) {
+        const body = await this.buildRunBody(opts, apiKey);
+        const transport = this.transportFromRun(opts, apiKey);
+        // A non-streaming run is retried on transient faults; an auto key makes
+        // those retries safe (the server replays the first outcome instead of
+        // starting a second run). `createRunResponse` is only used by the sync
+        // paths; streaming has its own method and never sends this header.
+        const headers = {};
+        if (opts.idempotencyKey) {
+            headers["Idempotency-Key"] = opts.idempotencyKey;
+        }
+        else {
+            headers["Idempotency-Key"] = randomIdempotencyKey();
+        }
+        return this.request("POST", "/responses", body, { ...transport, headers });
+    }
+    async buildRunBody(opts, apiKey) {
+        const uploaded = await this.uploadRunFiles(opts, apiKey);
+        const fileIds = [...uploaded.fileIds, ...(opts.fileIds ?? [])];
+        const fileKinds = [...uploaded.fileKinds, ...(opts.fileKinds ?? [])];
         let input = opts.inputMessages ?? opts.input;
-        if (opts.fileIds?.length) {
+        if (fileIds.length) {
             input = [
                 {
                     role: "user",
                     content: [
-                        ...opts.fileIds.map((file_id, i) => {
-                            const kind = opts.fileKinds?.[i];
+                        ...fileIds.map((file_id, i) => {
+                            const kind = fileKinds[i];
                             if (kind === "video")
                                 return { type: "input_video", file_id };
                             if (kind === "text" || kind === "document")
@@ -195,16 +378,18 @@ export class AgentLu {
             model: opts.model,
             instructions: opts.instructions,
             tools: opts.tools,
+            tool_choice: opts.tool_choice,
             reasoning: opts.reasoning,
             conversation: opts.conversation,
+            previous_response_id: opts.previous_response_id,
             store: opts.store,
             person: opts.person,
             owner: opts.owner,
             title: opts.title,
-            timeout_ms: opts.timeout_ms,
+            timeout_ms: opts.timeout_ms ?? opts.timeoutMs ?? this.defaultTimeoutMs,
             include: opts.include,
             temperature: opts.temperature,
-            max_output_tokens: opts.max_output_tokens,
+            max_output_tokens: opts.max_output_tokens ?? opts.maxOutputTokens,
             background: opts.background,
             metadata: opts.metadata,
         };
@@ -221,7 +406,36 @@ export class AgentLu {
                 },
             };
         }
-        return this.request("POST", "/responses", body, { apiKey });
+        return body;
+    }
+    async uploadRunFiles(opts, apiKey) {
+        const files = opts.files ?? [];
+        if (!files.length)
+            return { fileIds: [], fileKinds: [] };
+        const transport = this.transportFromRun(opts, apiKey);
+        const fileIds = [];
+        const fileKinds = [];
+        for (const file of files) {
+            const uploaded = await this.uploadForApiKey(file.data, file.filename, file.mime, apiKey, {
+                timeoutMs: transport.timeoutMs,
+                signal: transport.signal,
+                maxAttempts: transport.maxAttempts,
+            });
+            fileIds.push(uploaded.id);
+            fileKinds.push(file.kind ?? kindFromMime(file.mime, uploaded.kind));
+        }
+        return { fileIds, fileKinds };
+    }
+    transportFromRun(opts, apiKey) {
+        // The server budget and the client deadline must not race: give the client
+        // 5s of slack so the server's own timeout/error envelope arrives first.
+        const serverBudgetMs = opts.timeout_ms ?? opts.timeoutMs ?? this.defaultTimeoutMs;
+        return {
+            apiKey,
+            timeoutMs: serverBudgetMs !== undefined ? serverBudgetMs + 5_000 : this.defaultTimeoutMs,
+            maxAttempts: opts.maxAttempts,
+            signal: opts.signal,
+        };
     }
     responses = {
         create: (body) => this.request("POST", "/responses", body),
@@ -236,10 +450,47 @@ export class AgentLu {
             const qs = q.toString();
             return this.request("GET", `/responses${qs ? `?${qs}` : ""}`);
         },
-        stream: (body) => this.streamForApiKey(body),
+        stream: (body) => this.streamRawForApiKey(body, this.apiKey),
+        wait: (id, opts) => this.waitForApiKey(id, this.apiKey, opts),
     };
-    async *streamForApiKey(body, apiKey) {
-        const res = await this.raw("POST", "/responses", { ...body, stream: true }, { apiKey });
+    async waitForApiKey(id, apiKey, opts) {
+        const intervalMs = Math.max(opts?.intervalMs ?? 1_000, 50);
+        // A background run may sit behind a queue; without a default deadline a
+        // caller that forgets timeoutMs polls forever.
+        const deadlineMs = opts?.timeoutMs === 0
+            ? undefined
+            : (opts?.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS);
+        const started = Date.now();
+        for (;;) {
+            if (opts?.signal?.aborted) {
+                throw opts.signal.reason instanceof Error
+                    ? opts.signal.reason
+                    : new AgentLuError(0, "aborted", "wait aborted", false);
+            }
+            const remaining = deadlineMs !== undefined ? Math.max(deadlineMs - (Date.now() - started), 1) : undefined;
+            const row = await this.request("GET", `/responses/${encodeURIComponent(id)}`, undefined, {
+                apiKey,
+                signal: opts?.signal,
+                timeoutMs: remaining ?? this.defaultTimeoutMs,
+                maxAttempts: 1,
+            });
+            if (isTerminalStatus(row.status))
+                return row;
+            if (deadlineMs !== undefined && Date.now() - started + intervalMs >= deadlineMs) {
+                throw new AgentLuError(408, "timeout", `Timed out waiting for response ${id}`, true);
+            }
+            await sleep(intervalMs);
+        }
+    }
+    async *streamRunForApiKey(opts, apiKey) {
+        if (opts.background === true) {
+            throw new AgentLuError(400, "background_not_supported", "stream cannot use background.", false);
+        }
+        const body = await this.buildRunBody(opts, apiKey);
+        yield* this.streamRawForApiKey(body, apiKey, this.transportFromRun(opts, apiKey));
+    }
+    async *streamRawForApiKey(body, apiKey, transport) {
+        const res = await this.raw("POST", "/responses", { ...body, stream: true }, { ...transport, apiKey: transport?.apiKey ?? apiKey });
         if (!res.body)
             throw new AgentLuError(0, "internal_error", "empty stream body", true);
         const reader = res.body.getReader();
@@ -251,13 +502,13 @@ export class AgentLu {
                 if (done)
                     break;
                 buf += decoder.decode(value, { stream: true });
-                const lines = buf.split("\n");
+                const lines = buf.split(/\r?\n/);
                 buf = lines.pop() ?? "";
                 for (const line of lines) {
                     const trimmed = line.trim();
-                    if (!trimmed.startsWith("data: "))
+                    if (!trimmed.startsWith("data:"))
                         continue;
-                    const payload = trimmed.slice(6);
+                    const payload = trimmed.slice(5).trim();
                     if (payload === "[DONE]")
                         return;
                     try {
@@ -270,6 +521,7 @@ export class AgentLu {
             }
         }
         finally {
+            await reader.cancel().catch(() => { });
             reader.releaseLock();
         }
     }
@@ -297,9 +549,16 @@ export class AgentLu {
      * overrides the shared 5-attempt policy, and `signal` cancels the call.
      */
     decisions = {
-        create: (body) => this.request("POST", "/decisions", decisionWire(body), decisionRequestOptions(body)),
-        /** Same call, returning only the answers map. */
-        ask: async (body) => (await this.request("POST", "/decisions", decisionWire(body), decisionRequestOptions(body))).answers,
+        create: (body) => this.request("POST", "/decisions", decisionWire(body), decisionRequestOptions(body, this.defaultTimeoutMs)),
+        ask: async (body) => (await this.request("POST", "/decisions", decisionWire(body), decisionRequestOptions(body, this.defaultTimeoutMs))).answers,
+        askOrNull: async (body) => {
+            try {
+                return await this.decisions.ask(body);
+            }
+            catch {
+                return null;
+            }
+        },
     };
     async agents() {
         return this.request("GET", "/agents", undefined, { auth: false });
@@ -314,31 +573,29 @@ export class AgentLu {
         return this.request("GET", "/health", undefined, { auth: false });
     }
     async request(method, path, body, opts) {
-        // `409 thread_busy` and `503 too_many_active_runs` are correctness bounds,
-        // not rate limits. Retrying with backoff is almost always the right thing,
+        const res = await this.raw(method, path, body, opts);
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    async raw(method, path, body, opts) {
+        // `409 thread_busy`, `503 too_many_active_runs`, network faults, 502/504
+        // and any server-marked retryable error are correctness/transient bounds,
+        // not rate limits. Retrying with jittered backoff is almost always right,
         // so the SDK does it - honoring Retry-After when the server sends one.
         // A 503 can also signal a config boundary (no decision model key); those
         // are not retryable and must surface immediately. Callers can cap attempts
         // per request (`maxAttempts`); a timeout/caller abort is never retried.
-        const nonRetryable503 = new Set(["systemone_unconfigured"]);
         const maxAttempts = opts?.maxAttempts !== undefined && Number.isFinite(opts.maxAttempts) && opts.maxAttempts >= 1
             ? Math.floor(opts.maxAttempts)
             : 5;
         let last;
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             try {
-                const res = await this.raw(method, path, body, opts);
-                if (res.status === 204)
-                    return undefined;
-                const json = (await res.json());
-                return json;
+                return await this.rawOnce(method, path, body, opts);
             }
             catch (e) {
-                if (e instanceof AgentLuError &&
-                    (e.code === "thread_busy" ||
-                        e.code === "too_many_active_runs" ||
-                        (e.status === 503 && !nonRetryable503.has(e.code))) &&
-                    attempt < maxAttempts - 1) {
+                if (isRetryableError(e) && attempt < maxAttempts - 1) {
                     last = e;
                     await sleep(retryDelayMs(e, attempt));
                     continue;
@@ -348,7 +605,7 @@ export class AgentLu {
         }
         throw last ?? new AgentLuError(503, "too_many_active_runs", "too many retries", true);
     }
-    async raw(method, path, body, opts) {
+    async rawOnce(method, path, body, opts) {
         const headers = {};
         const isForm = typeof FormData !== "undefined" && body instanceof FormData;
         if (body !== undefined && !isForm) {
@@ -357,13 +614,21 @@ export class AgentLu {
         const apiKey = opts?.apiKey ?? this.apiKey;
         if (opts?.auth !== false && apiKey)
             headers.Authorization = `Bearer ${apiKey}`;
-        const signal = requestSignal(opts?.signal, opts?.timeoutMs);
-        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-            method,
-            headers,
-            ...(signal ? { signal } : {}),
-            body: body === undefined ? undefined : isForm ? body : JSON.stringify(body),
-        });
+        if (opts?.headers)
+            Object.assign(headers, opts.headers);
+        const signal = requestSignal(opts?.signal, opts?.timeoutMs ?? this.defaultTimeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                ...(signal ? { signal } : {}),
+                body: body === undefined ? undefined : isForm ? body : JSON.stringify(body),
+            });
+        }
+        catch (e) {
+            throw mapFetchError(e, opts?.signal);
+        }
         if (!res.ok) {
             let code = `http_${res.status}`;
             let message = `HTTP ${res.status}`;
@@ -402,58 +667,191 @@ export class UseCaseRunner {
     operations;
     apiKey = null;
     ready = null;
+    /** In-flight/short-lived guard so a burst of runs does not stampede registration. */
+    registerFailures = 0;
+    lastRegisterError = null;
+    registerFailedAt = null;
+    /** Cooldown is short and only suppresses *repeated* failures in one burst. */
+    static REGISTER_COOLDOWN_MS = 1_000;
     constructor(parent, name, opts) {
         this.name = name;
         this.registerOpts = opts ?? {};
         this.operations = scopedUseCaseOperations.get(parent);
     }
-    /** Idempotent get-or-create; safe to call before every run. */
-    ensure() {
+    /**
+   * Idempotent get-or-create; safe to call on boot or before every run.
+   * A failed registration is remembered for a short cooldown so an app that
+   * calls `ensure()` in a loop does not hammer the server; runs always retry
+   * registration transparently (pass `force`).
+   */
+    ensure(opts) {
         if (this.apiKey)
             return Promise.resolve();
         if (!this.ready) {
+            if (!opts?.force &&
+                this.registerFailedAt !== null &&
+                Date.now() - this.registerFailedAt < UseCaseRunner.REGISTER_COOLDOWN_MS) {
+                return Promise.reject(this.lastRegisterError ??
+                    new AgentLuError(503, "register_cooldown", "use-case registration is cooling down", true));
+            }
             this.ready = this.operations.register(this.name, this.registerOpts)
                 .then((key) => {
                 this.apiKey = key;
+                this.registerFailedAt = null;
+                this.registerFailures = 0;
+                this.lastRegisterError = null;
             })
                 .catch((e) => {
                 this.ready = null;
+                this.registerFailedAt = Date.now();
+                this.registerFailures += 1;
+                this.lastRegisterError = e;
                 throw e;
             });
         }
         return this.ready;
     }
+    invalidate() {
+        this.apiKey = null;
+        this.ready = null;
+    }
+    async withAuthRetry(fn) {
+        await this.ensure({ force: true });
+        try {
+            return await fn(this.apiKey);
+        }
+        catch (e) {
+            if (e instanceof AgentLuError && e.status === 401) {
+                this.invalidate();
+                await this.ensure({ force: true });
+                return await fn(this.apiKey);
+            }
+            throw e;
+        }
+    }
     /**
      * Run with this use-case's key. Request fields that are set override the
      * use-case's registered defaults; unset fields inherit them server-side.
      */
     async run(opts) {
-        await this.ensure();
-        return (await this.operations.run(this.apiKey, opts));
+        return (await this.withAuthRetry((apiKey) => this.operations.run(apiKey, opts)));
     }
     async runJson(opts) {
         assertJsonRunOptions(opts);
-        await this.ensure();
-        return (await this.operations.runJson(this.apiKey, opts));
+        return (await this.withAuthRetry((apiKey) => this.operations.runJson(apiKey, opts)));
+    }
+    async runText(opts) {
+        return this.withAuthRetry((apiKey) => this.operations.runText(apiKey, opts));
+    }
+    /** `runJson` that returns `null` instead of throwing on any failure. */
+    async runJsonOrNull(opts) {
+        try {
+            const { data } = await this.runJson(opts);
+            return data;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** `runText` that returns `null` instead of throwing on any failure. */
+    async runTextOrNull(opts) {
+        try {
+            const { text } = await this.runText(opts);
+            return text;
+        }
+        catch {
+            return null;
+        }
+    }
+    async *stream(opts) {
+        await this.ensure({ force: true });
+        try {
+            yield* this.operations.stream(this.apiKey, opts);
+        }
+        catch (e) {
+            if (!(e instanceof AgentLuError && e.status === 401))
+                throw e;
+            this.invalidate();
+            await this.ensure({ force: true });
+            yield* this.operations.stream(this.apiKey, opts);
+        }
     }
-    async stream(body) {
-        await this.ensure();
-        return this.operations.stream(this.apiKey, body);
+    /** Typed stream for this use-case: events + `finalText()`. */
+    typedStream(opts) {
+        return typedStream(this.stream(opts));
     }
     /**
      * Upload with this use-case's key, so the file is owned by the same
      * service client that will reference it via `run({ fileIds })`.
      */
-    async upload(data, filename, mime) {
-        await this.ensure();
-        return this.operations.upload(this.apiKey, data, filename, mime);
+    async upload(data, filename, mime, opts) {
+        return this.withAuthRetry((apiKey) => this.operations.upload(apiKey, data, filename, mime, opts));
     }
+    responses = {
+        retrieve: (id) => this.withAuthRetry((apiKey) => this.operations.retrieve(apiKey, id)),
+        cancel: (id) => this.withAuthRetry((apiKey) => this.operations.cancel(apiKey, id)),
+        wait: (id, opts) => this.withAuthRetry((apiKey) => this.operations.wait(apiKey, id, opts)),
+    };
+    decisions = {
+        create: (body) => this.withAuthRetry((apiKey) => this.operations.decideCreate(apiKey, body)),
+        ask: (body) => this.withAuthRetry((apiKey) => this.operations.decideAsk(apiKey, body)),
+        askOrNull: async (body) => {
+            try {
+                return await this.decisions.ask(body);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
 }
 function assertJsonRunOptions(opts) {
     if (opts.background === true) {
         throw new AgentLuError(400, "background_not_supported", "runJson requires a completed response and cannot use background.", false);
     }
 }
+function jsonAttempts(opts) {
+    if (opts.attempts !== undefined && Number.isFinite(opts.attempts) && opts.attempts >= 1) {
+        return Math.floor(opts.attempts);
+    }
+    return 1;
+}
+function isJsonRetryable(error) {
+    if (error instanceof AgentLuError && error.code === "missing_output_parsed")
+        return true;
+    if (error instanceof AgentLuResponseError) {
+        return error.code === "schema_validation_failed" || error.responseStatus === "incomplete";
+    }
+    return false;
+}
+function kindFromMime(mime, stored) {
+    if (stored === "video" || stored === "text" || stored === "document" || stored === "image")
+        return stored;
+    if (mime?.startsWith("video/"))
+        return "video";
+    if (mime?.startsWith("text/"))
+        return "text";
+    if (mime === "application/pdf")
+        return "document";
+    return "image";
+}
+function mapFetchError(error, callerSignal) {
+    if (error instanceof AgentLuError)
+        return error;
+    if (callerSignal?.aborted) {
+        const reason = callerSignal.reason;
+        if (reason instanceof AgentLuError)
+            return reason;
+        const message = reason instanceof Error ? reason.message : "Request aborted";
+        return new AgentLuError(0, "aborted", message, false);
+    }
+    const name = error instanceof Error ? error.name : "";
+    const message = error instanceof Error ? error.message : String(error);
+    if (name === "TimeoutError" || name === "AbortError" || /timed out/i.test(message)) {
+        return new AgentLuError(408, "timeout", message || "Request timed out", true);
+    }
+    return new AgentLuError(0, "network_error", message || "fetch failed", true);
+}
 function parseRetryAfter(res) {
     const header = res.headers.get("retry-after");
     if (!header)
@@ -497,11 +895,43 @@ function requestSignal(signal, timeoutMs) {
     return signals.length ? mergeSignals(signals) : undefined;
 }
 function retryDelayMs(err, attempt) {
+    // Jitter keeps a fleet of clients from retrying in lockstep after a blip.
+    const jitter = 0.75 + Math.random() * 0.5;
     if (err.retryAfterMs !== undefined) {
-        return Math.min(10_000, Math.max(250, err.retryAfterMs));
+        return Math.min(10_000, Math.max(250, err.retryAfterMs * jitter));
     }
-    return Math.min(10_000, 500 * 2 ** attempt);
+    return Math.min(10_000, 500 * 2 ** attempt * jitter);
+}
+/** Statuses worth a retry even without a server `retryable` flag. */
+const RETRYABLE_STATUSES = new Set([502, 503, 504]);
+/** True when an error should be retried by the shared policy. */
+export function isRetryableError(err) {
+    if (!(err instanceof AgentLuError))
+        return false;
+    if (err.code === "systemone_unconfigured")
+        return false;
+    if (err.code === "thread_busy" || err.code === "too_many_active_runs")
+        return true;
+    // Network faults are retried; a client timeout is not (the deadline was hit
+    // and a retry would start a second run past the caller's budget).
+    if (err.code === "network_error")
+        return true;
+    if (RETRYABLE_STATUSES.has(err.status))
+        return true;
+    // The server marks quota exhaustion retryable:false; anything it marks
+    // retryable:true is safe to retry even on an otherwise-unremarkable status.
+    return err.retryable === true && err.status >= 500;
 }
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * Unique-enough idempotency key without assuming `crypto.randomUUID` exists
+ * (browser SDK consumers on older runtimes).
+ */
+function randomIdempotencyKey() {
+    const g = globalThis;
+    if (g.crypto?.randomUUID)
+        return `sdk_${g.crypto.randomUUID()}`;
+    return `sdk_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterlu/agentlu",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Client for the agentlu service API (/v1). Or just use the openai SDK pointed at http://localhost:8912/v1.",
   "type": "module",
   "main": "./dist/index.js",