@betterlu/agentlu 1.7.0 → 1.8.0

package/dist/generated.js

@@ -0,0 +1,11 @@
+/**
+ * AUTO-GENERATED by scripts/gen-contract.ts - do not edit.
+ * Source of truth: src/shared/api-schema.ts (+ src/server/api/schema.ts).
+ * Regenerate: `npm run gen:contract`; CI drift check: `npm run check:contract`.
+ */
+/**
+ * Wire types for the agentlu `/v1` service API, generated from the zod
+ * contract. They describe the bytes on the wire (snake_case); the SDK's own
+ * types are the ergonomic view over them.
+ */
+export {};

package/dist/index.d.ts

@@ -8,7 +8,24 @@
  * This client exists for the ergonomic bits OpenAI's SDK does not know about:
  * get-or-create registration, typed `runJson` / `runText`, use-case catalogs,
  * background `wait`, and auto-retry on `409 thread_busy`.
+ *
+ * Two tiers, two namespaces (1.8):
+ *
+ *   - `alu.llm.text/json/stream(...)` - the direct tier: one profile-free
+ *     provider call, no tools, no session.
+ *   - `alu.agent.run/stream/background(...)` - the agent tier: a profile,
+ *     tool families, threads and background runs.
+ *   - `alu.run/runJson/runText/stream` stay as aliases of the agent tier.
+ *
+ * Errors carry a coarse `kind` (`unavailable | timeout | rate_limited |
+ * invalid_request | schema | incomplete | internal`) and `isUnavailable(err)`
+ * is the fail-open predicate for "the service could not answer right now".
+ *
+ * Wire types generated from the server's zod contract are re-exported here as
+ * `Wire*` types (see `generated.ts`, regenerate with `npm run gen:contract`).
  */
+import type { WireAppAgentDeclaration, WireClientDefaults, WireUseCaseProfile } from "./generated.js";
+export type { WireAppAgentDeclaration, WireAgentInfo, WireChatCompletion, WireChatCompletionRequest, WireClient, WireClientDefaults, WireCreateDecision, WireCreateResponse, WireCreateThreadRequest, WireDecision, WireError, WireFile, WireModelInfo, WireRegisterClientRequest, WireResponse, WireStreamEvent, WireThread, WireThreadMessage, WireToolInfo, WireUseCaseProfile, } from "./generated.js";
 export declare const DEFAULT_BASE_URL = "http://localhost:8912/v1";
 /**
  * Accept an origin (`http://host:8912`) or a `/v1` base and normalize to the
@@ -86,9 +103,6 @@ export interface AndroidActivity {
 export interface ReasoningOptions {
     effort?: ThinkingLevel;
 }
-export interface ClientReasoningOptions {
-    effort: ThinkingLevel;
-}
 export interface TextFormatText {
     type: "text";
 }
@@ -195,6 +209,21 @@ export declare const noul: (instructions: string, criteria?: {
 }) => NoulQuestion;
 export declare const choice: (instructions: string, criteria: Record<string, string>) => ChoiceQuestion;
 export declare const score: (instructions: string, levels: string[]) => ScoreQuestion;
+/**
+ * Coarse, stable classification of an SDK error, for retry/degrade decisions:
+ *
+ *   - `unavailable`     the service could not answer (offline, 5xx, saturated)
+ *   - `timeout`         the run or the request hit its deadline
+ *   - `rate_limited`    HTTP 429, or a retryable 409 (`thread_busy`) - back off
+ *                       and retry; the SDK already does, with jitter
+ *   - `invalid_request` the caller must fix the request (4xx)
+ *   - `schema`          structured output failed or never validated
+ *   - `incomplete`      the run finished without a complete answer
+ *   - `internal`        anything else, including a cancelled run and the
+ *                       `systemone_unconfigured` config boundary (never
+ *                       retried, never treated as an outage)
+ */
+export type AgentLuErrorKind = "unavailable" | "timeout" | "rate_limited" | "invalid_request" | "schema" | "incomplete" | "internal";
 export declare class AgentLuError extends Error {
     readonly status: number;
     readonly code: string;
@@ -204,7 +233,18 @@ export declare class AgentLuError extends Error {
     constructor(status: number, code: string, message: string, retryable: boolean, 
     /** Parsed Retry-After header, in milliseconds, when present. */
     retryAfterMs?: number | undefined);
+    /** Coarse classification; see `AgentLuErrorKind` and `isUnavailable`. */
+    get kind(): AgentLuErrorKind;
 }
+/** Classify an error into an `AgentLuErrorKind` (never throws). */
+export declare function classifyAgentLuError(err: AgentLuError): AgentLuErrorKind;
+/**
+ * Fail-open predicate: true when the service could not answer right now -
+ * offline/network, an upstream 5xx, saturation, or a deadline. An app that
+ * degrades gracefully (skip an enrichment, fall back to a local heuristic)
+ * treats this as "no answer available", not as a bug in the request.
+ */
+export declare function isUnavailable(err: unknown): boolean;
 export declare class AgentLuResponseError extends AgentLuError {
     readonly response: ResponseObject;
     readonly responseStatus: string;
@@ -221,36 +261,51 @@ export interface AgentLuOptions {
      */
     timeoutMs?: number;
 }
-export interface ClientDefaults {
-    backend?: Backend;
-    agent?: string;
-    model?: string;
-    instructions?: string;
-    temperature?: number;
-    tools?: ApiToolInput[];
-    timeoutMs?: number;
-    store?: boolean;
-    reasoning?: ClientReasoningOptions;
-    text?: TextConfig;
+/**
+ * Registration defaults (`defaults` on `POST /v1/clients`), derived from the
+ * server's generated wire contract so the two cannot drift: the server honors
+ * `maxOutputTokens` and `attempts` (the latter bounds model-chain fallbacks and
+ * the background queue's retry budget). A `maxOutputTokens` stored before the
+ * tier contract stays inert until the app re-declares its defaults or the
+ * console edits them - see the service API docs.
+ */
+export type ClientDefaults = WireClientDefaults;
+/**
+ * High-level use-case declaration for model routing and priority tier.
+ * Generated from the server's zod contract, so it carries `priority`
+ * (`instant | standard | deep`) - the knob that opts a client into the tier
+ * defaults (timeout, output cap, attempts, reasoning).
+ */
+export type UseCaseProfile = WireUseCaseProfile;
+/** Latency/thoroughness tier declared by a client. */
+export type UseCasePriority = "instant" | "standard" | "deep";
+/**
+ * Registration options shared by `register`, `useCase` and `useCaseClient`.
+ * Registration is get-or-create, so an app can declare its client(s) on boot.
+ */
+export interface ClientRegistrationOptions {
+    person?: string | null;
+    instructions?: string | null;
+    defaults?: ClientDefaults;
+    use_case_profile?: UseCaseProfile;
+    /** Use-case tier; sugar for `use_case_profile.priority`. */
+    priority?: UseCasePriority;
     /**
-     * Retired on client defaults (server ignores it). Pass `max_output_tokens`
-     * or `maxOutputTokens` on `run` / `runJson` / `stream` instead.
+     * App this client belongs to (console `/stats` grouping and the namespace of
+     * app-owned agents). Defaults server-side to the part of `name` before the
+     * first "-" (`mealu-extract` -> `mealu`).
      */
-    maxOutputTokens?: never;
-}
-/** High-level use-case declaration for model routing and priority tier. */
-export interface UseCaseProfile {
-    inputModalities?: Array<"text" | "image" | "video">;
-    outputKind?: "text" | "json_schema";
-    /** MiniMax priority admission consent (priority costs 1.5x standard). */
-    priorityTier?: "never" | "retry" | "first" | "always";
+    app?: string;
+    /**
+     * App-owned agents this client declares, callable as `agent: "<app>/<name>"`
+     * by every client of the same app. Sending the array replaces the agents this
+     * client previously declared (`[]` clears them).
+     */
+    agents?: WireAppAgentDeclaration[];
 }
-export interface UseCaseDeclaration {
+export interface UseCaseDeclaration extends ClientRegistrationOptions {
     /** 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;
@@ -343,6 +398,53 @@ export interface UploadOptions {
     signal?: AbortSignal;
     maxAttempts?: number;
 }
+export interface UploadManyOptions extends UploadOptions {
+    /** Parallel uploads. Default 3. */
+    concurrency?: number;
+}
+/**
+ * Direct-tier request (`llm.text` / `llm.json` / `llm.stream`): one
+ * profile-free provider call, no tools, no session. `instructions` is the
+ * whole system prompt.
+ */
+export interface LlmRequest {
+    input: string;
+    instructions?: string;
+    model?: string;
+    temperature?: number;
+    timeoutMs?: number;
+    maxOutputTokens?: number;
+    metadata?: Record<string, string>;
+    signal?: AbortSignal;
+    maxAttempts?: number;
+    idempotencyKey?: string;
+}
+export interface LlmJsonRequest extends LlmRequest {
+    /** Format name sent to the provider (default "Result"). */
+    schemaName?: string;
+}
+export interface LlmApi {
+    text: (request: string | LlmRequest) => Promise<{
+        text: string;
+        response: ResponseObject;
+    }>;
+    json: <T = unknown>(schema: Record<string, unknown>, request: string | LlmJsonRequest) => Promise<{
+        data: T;
+        response: ResponseObject;
+    }>;
+    stream: (request: string | LlmRequest) => AsyncIterable<StreamEvent> & {
+        finalText: () => Promise<string>;
+    };
+}
+/** Agent-tier entry points (`alu.agent.*`). */
+export interface AgentTierApi {
+    run: (opts: RunOptions) => Promise<{
+        data?: unknown;
+        response: ResponseObject;
+    }>;
+    stream: (opts: RunOptions) => AsyncGenerator<Record<string, unknown>>;
+    background: (opts: RunOptions, wait?: WaitOptions) => Promise<ResponseObject>;
+}
 export interface ResponseObject {
     id: string;
     status: string;
@@ -406,12 +508,7 @@ export declare class AgentLu {
     constructor(opts?: AgentLuOptions);
     private postClient;
     /** Get-or-create a client by name. Caches the returned key on this instance. */
-    register(name: string, opts?: {
-        person?: string | null;
-        instructions?: string | null;
-        defaults?: ClientDefaults;
-        use_case_profile?: UseCaseProfile;
-    }): Promise<ResponseObject & {
+    register(name: string, opts?: ClientRegistrationOptions): Promise<ResponseObject & {
         api_key?: string;
         name: string;
     }>;
@@ -422,11 +519,7 @@ export declare class AgentLu {
      * 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;
+    useCase(name: string, opts?: ClientRegistrationOptions): UseCaseRunner;
     /**
      * Several named use-case runners that share this client. Call `ensure()` on
      * boot, then `catalog.extract.runJson({ input })`.
@@ -441,11 +534,7 @@ export declare class AgentLu {
      * on this instance (same semantics as `register`), so a following
      * `responses.create` is authorized.
      */
-    useCaseClient(name: string, opts?: {
-        person?: string | null;
-        defaults?: ClientDefaults;
-        use_case_profile?: UseCaseProfile;
-    }): Promise<string>;
+    useCaseClient(name: string, opts?: ClientRegistrationOptions): Promise<string>;
     private registerForUseCase;
     /**
      * Upload an image, video, or document for use with `run({ fileIds })`.
@@ -489,7 +578,42 @@ export declare class AgentLu {
     typedStream(opts: RunOptions): AsyncIterable<StreamEvent> & {
         finalText: () => Promise<string>;
     };
+    /**
+     * Direct tier (`agent: "direct"`): one profile-free provider call - no
+     * profile, no tools, no session. Use it for extraction, classification and
+     * short answers; use `agent.*` when the run needs tools or a thread.
+     *
+     *   const { text } = await alu.llm.text("Name three colours.");
+     *   const { data } = await alu.llm.json(schema, { input, schemaName: "Items" });
+     */
+    readonly llm: LlmApi;
+    /**
+     * Agent tier: a profile, tool families, threads and background runs. The
+     * default agent is `api` (no persona - `instructions` are the system prompt);
+     * pin `fast`/`research`/... or an app-owned `<app>/<name>` id when needed.
+     */
+    readonly agent: AgentTierApi;
+    /** Build a direct-tier run body from a short-form `llm.*` request. */
+    private llmOptions;
+    /**
+     * Enqueue a background run (`background: true`) and poll it to a terminal
+     * status with `responses.wait`. Resolves with the terminal Response row -
+     * check `status` (and `output_parsed`); a failed run is not an exception
+     * here, but `wait` still times out after `wait.timeoutMs` (default 10min).
+     */
+    runBackground(opts: RunOptions, wait?: WaitOptions): Promise<ResponseObject>;
+    /**
+     * Upload several files with bounded concurrency (default 3), preserving the
+     * input order. Returns the uploaded ids for `run({ fileIds })` - pair with
+     * `fileKinds` when the files are not images.
+     */
+    uploadMany(files: RunFile[], opts?: UploadManyOptions): Promise<Array<{
+        id: string;
+        kind?: string;
+    }>>;
     private runForApiKey;
+    /** Attempts for a run: the caller's `maxAttempts` or the shared default. */
+    private runAttempts;
     private runJsonForApiKey;
     private runJsonOnce;
     private runTextForApiKey;
@@ -569,11 +693,7 @@ export declare class UseCaseRunner {
     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;
-    });
+    constructor(parent: AgentLu, name: string, opts?: ClientRegistrationOptions);
     /**
    * 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
@@ -618,6 +738,20 @@ export declare class UseCaseRunner {
         id: string;
         kind?: string;
     }>;
+    /**
+     * Background run with this use-case's key: enqueue, then poll to a terminal
+     * status (`responses.wait`). Resolves with the terminal Response row.
+     */
+    runBackground(opts: RunOptions, wait?: WaitOptions): Promise<ResponseObject>;
+    /**
+     * Upload several files with bounded concurrency (default 3), preserving the
+     * input order. Files are owned by this use-case's client, so the same
+     * `run({ fileIds })` can reference them.
+     */
+    uploadMany(files: RunFile[], opts?: UploadManyOptions): Promise<Array<{
+        id: string;
+        kind?: string;
+    }>>;
     readonly responses: {
         retrieve: (id: string) => Promise<ResponseObject>;
         cancel: (id: string) => Promise<ResponseObject>;

package/dist/index.js

@@ -1,15 +1,8 @@
-/**
- * @betterlu/agentlu - client for the agentlu service API.
- *
- * You can also skip this package entirely:
- *
- *   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` / `runText`, use-case catalogs,
- * background `wait`, and auto-retry on `409 thread_busy`.
- */
 export const DEFAULT_BASE_URL = "http://localhost:8912/v1";
+/** Wire agent id for the direct tier (not a chat mode). */
+const DIRECT_AGENT_ID = "direct";
+/** Default agent for the agent tier: the profile-free machine agent. */
+const AGENT_TIER_AGENT = "api";
 /**
  * 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" })`
@@ -66,6 +59,88 @@ export class AgentLuError extends Error {
         this.retryAfterMs = retryAfterMs;
         this.name = "AgentLuError";
     }
+    /** Coarse classification; see `AgentLuErrorKind` and `isUnavailable`. */
+    get kind() {
+        return classifyAgentLuError(this);
+    }
+}
+const SCHEMA_ERROR_CODES = new Set(["schema_validation_failed", "missing_output_parsed"]);
+const INCOMPLETE_ERROR_CODES = new Set(["incomplete", "empty_output"]);
+const UNAVAILABLE_ERROR_CODES = new Set([
+    "network_error",
+    "upstream_error",
+    "empty_completion",
+    "too_many_active_runs",
+    "systemone_unavailable",
+    "harness_unavailable",
+    "quota_exhausted",
+    "provider_unavailable",
+]);
+const INVALID_REQUEST_ERROR_CODES = new Set([
+    "invalid_request",
+    "unsupported_tool",
+    "unsupported_backend_field",
+    "unknown_agent",
+    "unknown_model",
+    "missing_api_key",
+    "invalid_api_key",
+    "model_no_vision",
+    "model_no_video",
+    "reserved_username",
+    "person_threads_not_allowed",
+    "app_agent_not_allowed",
+    "idempotency_conflict",
+    "not_found",
+    "background_not_supported",
+]);
+const INVALID_REQUEST_STATUSES = new Set([400, 401, 403, 404, 405, 409, 413, 415, 422]);
+/** Classify an error into an `AgentLuErrorKind` (never throws). */
+export function classifyAgentLuError(err) {
+    if (SCHEMA_ERROR_CODES.has(err.code))
+        return "schema";
+    if (INCOMPLETE_ERROR_CODES.has(err.code))
+        return "incomplete";
+    if (err instanceof AgentLuResponseError && err.responseStatus === "incomplete")
+        return "incomplete";
+    // A cancelled run is an outcome, not a request the caller must fix and not a
+    // service outage: HTTP 499 and a 200 body with status "cancelled" classify
+    // the same way.
+    if (err.code === "cancelled" || err.status === 499)
+        return "internal";
+    if (err instanceof AgentLuResponseError && err.responseStatus === "cancelled")
+        return "internal";
+    if (err.code === "timeout")
+        return "timeout";
+    if (err.status === 429 || err.code === "rate_limited")
+        return "rate_limited";
+    // A retryable 409 (`thread_busy`: another turn is in flight) is saturation:
+    // back off and retry, never "the caller must fix the request".
+    if (err.code === "thread_busy" || (err.status === 409 && err.retryable))
+        return "rate_limited";
+    // A config boundary wearing a 503 (`systemone_unconfigured`) must surface:
+    // it is not transient and is never retried.
+    if (err.code === "systemone_unconfigured")
+        return "internal";
+    if (err.status === 0 || err.status === 502 || err.status === 503 || err.status === 504)
+        return "unavailable";
+    if (UNAVAILABLE_ERROR_CODES.has(err.code))
+        return "unavailable";
+    if (INVALID_REQUEST_STATUSES.has(err.status) || INVALID_REQUEST_ERROR_CODES.has(err.code)) {
+        return "invalid_request";
+    }
+    return "internal";
+}
+/**
+ * Fail-open predicate: true when the service could not answer right now -
+ * offline/network, an upstream 5xx, saturation, or a deadline. An app that
+ * degrades gracefully (skip an enrichment, fall back to a local heuristic)
+ * treats this as "no answer available", not as a bug in the request.
+ */
+export function isUnavailable(err) {
+    if (!(err instanceof AgentLuError))
+        return false;
+    const kind = err.kind;
+    return kind === "unavailable" || kind === "timeout" || kind === "rate_limited";
 }
 export class AgentLuResponseError extends AgentLuError {
     response;
@@ -82,6 +157,39 @@ export class AgentLuResponseError extends AgentLuError {
 }
 /** Default overall deadline for `responses.wait`. */
 export const DEFAULT_WAIT_TIMEOUT_MS = 10 * 60_000;
+/** The agent tier's default agent: the profile-free machine agent. */
+function withAgentTierDefault(opts) {
+    return opts.agent === undefined ? { ...opts, agent: AGENT_TIER_AGENT } : opts;
+}
+/**
+ * Worker count for `uploadMany`: the caller's concurrency when it is a real
+ * number >= 1. A `NaN` (plausible as `Number(process.env.X)`) or a value below
+ * 1 would otherwise start no workers and silently upload nothing.
+ */
+function uploadConcurrency(value) {
+    const n = Number(value ?? 3);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 3;
+}
+/** Bounded-concurrency uploads that preserve the input order. */
+async function uploadManyWith(files, opts, upload) {
+    const concurrency = uploadConcurrency(opts?.concurrency);
+    const results = new Array(files.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(concurrency, files.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= files.length)
+                return;
+            const file = files[index];
+            results[index] = await upload(file);
+        }
+    });
+    const settled = await Promise.allSettled(workers);
+    const failed = settled.find((result) => result.status === "rejected");
+    if (failed && failed.status === "rejected")
+        throw failed.reason;
+    return results;
+}
 export function isTerminalStatus(status) {
     return status === "completed" || status === "failed" || status === "incomplete" || status === "cancelled";
 }
@@ -158,10 +266,26 @@ export class AgentLu {
         });
     }
     postClient(name, opts) {
+        // `priority` is sugar for the profile field, and `agents` rides the same
+        // registration, so the declared body is built explicitly (no stray keys).
+        const profile = opts?.priority !== undefined ? { ...opts.use_case_profile, priority: opts.priority } : opts?.use_case_profile;
+        const body = { name };
+        if (opts?.person !== undefined)
+            body.person = opts.person;
+        if (opts?.instructions !== undefined)
+            body.instructions = opts.instructions;
+        if (opts?.defaults !== undefined)
+            body.defaults = opts.defaults;
+        if (opts?.app !== undefined)
+            body.app = opts.app;
+        if (opts?.agents !== undefined)
+            body.agents = opts.agents;
+        if (profile !== undefined)
+            body.use_case_profile = profile;
         // 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 });
+        return this.request("POST", "/clients", body, { auth: false, maxAttempts: 2 });
     }
     /** Get-or-create a client by name. Caches the returned key on this instance. */
     async register(name, opts) {
@@ -288,15 +412,87 @@ export class AgentLu {
     typedStream(opts) {
         return typedStream(this.stream(opts));
     }
+    /**
+     * Direct tier (`agent: "direct"`): one profile-free provider call - no
+     * profile, no tools, no session. Use it for extraction, classification and
+     * short answers; use `agent.*` when the run needs tools or a thread.
+     *
+     *   const { text } = await alu.llm.text("Name three colours.");
+     *   const { data } = await alu.llm.json(schema, { input, schemaName: "Items" });
+     */
+    llm = {
+        text: (request) => this.runText(this.llmOptions(request)),
+        json: (schema, request) => {
+            const schemaName = typeof request === "string" ? undefined : request.schemaName;
+            return this.runJson({ ...this.llmOptions(request), schema, schemaName: schemaName ?? "Result" });
+        },
+        stream: (request) => this.typedStream(this.llmOptions(request)),
+    };
+    /**
+     * Agent tier: a profile, tool families, threads and background runs. The
+     * default agent is `api` (no persona - `instructions` are the system prompt);
+     * pin `fast`/`research`/... or an app-owned `<app>/<name>` id when needed.
+     */
+    agent = {
+        run: (opts) => this.run(withAgentTierDefault(opts)),
+        stream: (opts) => this.stream(withAgentTierDefault(opts)),
+        background: (opts, wait) => this.runBackground(withAgentTierDefault(opts), wait),
+    };
+    /** Build a direct-tier run body from a short-form `llm.*` request. */
+    llmOptions(request) {
+        const opts = typeof request === "string" ? { input: request } : request;
+        return { ...opts, agent: DIRECT_AGENT_ID, store: false, tools: [] };
+    }
+    /**
+     * Enqueue a background run (`background: true`) and poll it to a terminal
+     * status with `responses.wait`. Resolves with the terminal Response row -
+     * check `status` (and `output_parsed`); a failed run is not an exception
+     * here, but `wait` still times out after `wait.timeoutMs` (default 10min).
+     */
+    async runBackground(opts, wait) {
+        const queued = await this.run({ ...opts, background: true });
+        return this.responses.wait(queued.response.id, wait);
+    }
+    /**
+     * Upload several files with bounded concurrency (default 3), preserving the
+     * input order. Returns the uploaded ids for `run({ fileIds })` - pair with
+     * `fileKinds` when the files are not images.
+     */
+    async uploadMany(files, opts) {
+        return uploadManyWith(files, opts, (file) => this.upload(file.data, file.filename, file.mime, 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);
+        // A failed run is an HTTP 200 with `error.retryable` in the body, which the
+        // transport retry never sees. Retry those here (idempotency keys make it
+        // safe), honoring `maxAttempts` like the transport does. The key is minted
+        // once per logical run so every attempt replays the same server-side run.
+        const maxAttempts = this.runAttempts(opts);
+        const idempotencyKey = opts.idempotencyKey ?? randomIdempotencyKey();
+        let last;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const response = await this.createRunResponse({ ...opts, idempotencyKey }, apiKey);
+            if (response.status === "failed" && response.error) {
+                const err = new AgentLuError(200, response.error.code, response.error.message, response.error.retryable);
+                // A retryable failed run is a transient provider fault; retry it.
+                if (response.error.retryable && attempt < maxAttempts - 1) {
+                    last = err;
+                    await sleep(retryDelayMs(err, attempt));
+                    continue;
+                }
+                throw err;
+            }
+            if (opts.throwOnIncomplete && response.status === "incomplete") {
+                throw new AgentLuResponseError(response);
+            }
+            return { data: response.output_parsed, response };
         }
-        return { data: response.output_parsed, response };
+        throw last ?? new AgentLuError(200, "upstream_error", "run failed after retries", false);
+    }
+    /** Attempts for a run: the caller's `maxAttempts` or the shared default. */
+    runAttempts(opts) {
+        return opts.maxAttempts !== undefined && Number.isFinite(opts.maxAttempts) && opts.maxAttempts >= 1
+            ? Math.floor(opts.maxAttempts)
+            : 5;
     }
     async runJsonForApiKey(apiKey, opts) {
         const attempts = jsonAttempts(opts);
@@ -787,6 +983,22 @@ export class UseCaseRunner {
     async upload(data, filename, mime, opts) {
         return this.withAuthRetry((apiKey) => this.operations.upload(apiKey, data, filename, mime, opts));
     }
+    /**
+     * Background run with this use-case's key: enqueue, then poll to a terminal
+     * status (`responses.wait`). Resolves with the terminal Response row.
+     */
+    async runBackground(opts, wait) {
+        const queued = await this.run({ ...opts, background: true });
+        return this.responses.wait(queued.response.id, wait);
+    }
+    /**
+     * Upload several files with bounded concurrency (default 3), preserving the
+     * input order. Files are owned by this use-case's client, so the same
+     * `run({ fileIds })` can reference them.
+     */
+    async uploadMany(files, opts) {
+        return uploadManyWith(files, opts, (file) => this.upload(file.data, file.filename, file.mime, opts));
+    }
     responses = {
         retrieve: (id) => this.withAuthRetry((apiKey) => this.operations.retrieve(apiKey, id)),
         cancel: (id) => this.withAuthRetry((apiKey) => this.operations.cancel(apiKey, id)),
@@ -910,6 +1122,10 @@ export function isRetryableError(err) {
         return false;
     if (err.code === "systemone_unconfigured")
         return false;
+    // Deterministic exhaustion: the provider keeps refusing until quota is
+    // topped up, however 502-ish the status looks.
+    if (err.code === "quota_exhausted")
+        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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterlu/agentlu",
-  "version": "1.7.0",
+  "version": "1.8.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",