@betterlu/agentlu 1.6.0 → 1.7.0

package/dist/index.d.ts

@@ -10,6 +10,12 @@
  * 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";
@@ -306,19 +312,32 @@ 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. The in-flight poll is aborted when it fires. */
+    /**
+     * 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;
@@ -355,6 +374,30 @@ 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;
@@ -431,7 +474,21 @@ export declare class AgentLu {
         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;
@@ -506,13 +563,26 @@ 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 on boot or before every run. */
-    ensure(): Promise<void>;
+    /**
+   * 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;
     /**
@@ -531,7 +601,15 @@ export declare class UseCaseRunner {
         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 })`.
@@ -547,3 +625,5 @@ export declare class UseCaseRunner {
     };
     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

@@ -10,6 +10,17 @@
  * 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 };
@@ -69,9 +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;
 }
@@ -82,7 +133,7 @@ export class AgentLu {
     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;
@@ -107,7 +158,10 @@ export class AgentLu {
         });
     }
     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) {
@@ -201,14 +255,47 @@ export class AgentLu {
     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) {
@@ -247,7 +334,19 @@ export class AgentLu {
     }
     async createRunResponse(opts, apiKey) {
         const body = await this.buildRunBody(opts, apiKey);
-        return this.request("POST", "/responses", body, this.transportFromRun(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);
@@ -328,9 +427,12 @@ export class AgentLu {
         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: opts.timeoutMs ?? this.defaultTimeoutMs,
+            timeoutMs: serverBudgetMs !== undefined ? serverBudgetMs + 5_000 : this.defaultTimeoutMs,
             maxAttempts: opts.maxAttempts,
             signal: opts.signal,
         };
@@ -353,6 +455,11 @@ export class AgentLu {
     };
     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) {
@@ -360,7 +467,7 @@ export class AgentLu {
                     ? opts.signal.reason
                     : new AgentLuError(0, "aborted", "wait aborted", false);
             }
-            const remaining = opts?.timeoutMs !== undefined ? Math.max(opts.timeoutMs - (Date.now() - started), 1) : undefined;
+            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,
@@ -369,7 +476,7 @@ export class AgentLu {
             });
             if (isTerminalStatus(row.status))
                 return row;
-            if (opts?.timeoutMs !== undefined && Date.now() - started + intervalMs >= opts.timeoutMs) {
+            if (deadlineMs !== undefined && Date.now() - started + intervalMs >= deadlineMs) {
                 throw new AgentLuError(408, "timeout", `Timed out waiting for response ${id}`, true);
             }
             await sleep(intervalMs);
@@ -472,13 +579,13 @@ export class AgentLu {
         return (await res.json());
     }
     async raw(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,
+        // `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;
@@ -488,11 +595,7 @@ export class AgentLu {
                 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;
@@ -511,6 +614,8 @@ export class AgentLu {
         const apiKey = opts?.apiKey ?? this.apiKey;
         if (opts?.auth !== false && apiKey)
             headers.Authorization = `Bearer ${apiKey}`;
+        if (opts?.headers)
+            Object.assign(headers, opts.headers);
         const signal = requestSignal(opts?.signal, opts?.timeoutMs ?? this.defaultTimeoutMs);
         let res;
         try {
@@ -562,22 +667,45 @@ 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 on boot or 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;
             });
         }
@@ -588,14 +716,14 @@ export class UseCaseRunner {
         this.ready = null;
     }
     async withAuthRetry(fn) {
-        await this.ensure();
+        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();
+                await this.ensure({ force: true });
                 return await fn(this.apiKey);
             }
             throw e;
@@ -615,8 +743,28 @@ export class UseCaseRunner {
     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();
+        await this.ensure({ force: true });
         try {
             yield* this.operations.stream(this.apiKey, opts);
         }
@@ -624,10 +772,14 @@ export class UseCaseRunner {
             if (!(e instanceof AgentLuError && e.status === 401))
                 throw e;
             this.invalidate();
-            await this.ensure();
+            await this.ensure({ force: true });
             yield* this.operations.stream(this.apiKey, opts);
         }
     }
+    /** 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 })`.
@@ -743,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.6.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",