@betterlu/agentlu 1.4.0 → 1.6.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,30 @@ 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`:
+
+| Option | Effect |
+|---|---|
+| `timeoutMs` | Per-attempt deadline. A timeout aborts the request and is never retried. |
+| `maxAttempts` | Total attempts including the first; defaults to the shared 5-attempt policy. |
+| `signal` | Caller cancellation, combined with `timeoutMs` when both are set. |
+
+```ts
+const answers = await alu.decisions.ask({
+  state: latestMessage,
+  questions: { rename: noul("Is this a name change request?") },
+  timeoutMs: 5_000,
+  maxAttempts: 2,
+});
+```
 
 ## Browser handoff
 

package/dist/index.d.ts

@@ -6,20 +6,30 @@
  *   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";
 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 +97,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";
@@ -134,6 +152,16 @@ export interface DecisionOptions {
     questions: Record<string, DecisionQuestion>;
     /** Decision model id (default: the configured `typesafe/jev`). */
     model?: string;
+    /**
+     * 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 (or the AgentLu constructor `timeoutMs`).
+     */
+    timeoutMs?: number;
+    /** Total attempts including the first. Defaults to the shared 5-attempt policy. */
+    maxAttempts?: number;
+    /** Caller cancellation, combined with `timeoutMs` when both are set. */
+    signal?: AbortSignal;
 }
 export interface DecisionObject {
     id: string;
@@ -148,6 +176,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;
@@ -174,6 +208,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;
@@ -186,6 +226,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 {
@@ -194,18 +239,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;
@@ -213,18 +273,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. */
@@ -232,6 +306,23 @@ export interface RunOptions {
     schemaName?: string;
     /** Queue a background run instead of waiting. Returns the queued response. */
     background?: boolean;
+    /**
+     * `runJson` only: extra model attempts after `schema_validation_failed`,
+     * `missing_output_parsed`, or `incomplete`. Defaults to 1 (no extra tries).
+     */
+    attempts?: number;
+}
+export interface WaitOptions {
+    /** Delay between polls. Defaults to 1000ms. */
+    intervalMs?: number;
+    /** Overall wait deadline. The in-flight poll is aborted when it fires. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface UploadOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxAttempts?: number;
 }
 export interface ResponseObject {
     id: string;
@@ -263,10 +354,12 @@ export interface ResponseObject {
     };
     [k: string]: unknown;
 }
+export declare function isTerminalStatus(status: string): boolean;
 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. */
@@ -285,12 +378,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
@@ -306,7 +408,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;
     }>;
@@ -325,9 +427,19 @@ export declare class AgentLu {
         data: T;
         response: ResponseObject;
     }>;
+    runText(opts: RunOptions): Promise<{
+        text: string;
+        response: ResponseObject;
+    }>;
+    stream(opts: RunOptions): AsyncGenerator<Record<string, unknown>>;
     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>;
@@ -340,8 +452,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>;
@@ -361,18 +476,18 @@ export declare class AgentLu {
      *     },
      *   });
      *   if (answers.urgent.noul > 0.8) routeToHuman();
+     *
+     * `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
@@ -396,8 +511,10 @@ export declare class UseCaseRunner {
         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. */
+    ensure(): 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.
@@ -410,13 +527,23 @@ 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;
+    }>;
+    stream(opts: RunOptions): AsyncGenerator<Record<string, unknown>>;
     /**
      * 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;
 }

package/dist/index.js

@@ -6,10 +6,24 @@
  *   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";
+/** Strip client-only decision options before the body reaches `/v1/decisions`. */
+function decisionWire(body) {
+    const wire = { state: body.state, questions: body.questions };
+    if (body.model !== undefined)
+        wire.model = body.model;
+    return wire;
+}
+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) => ({
     type: "noul",
@@ -55,6 +69,9 @@ export class AgentLuResponseError extends AgentLuError {
         this.responseStatus = responseStatus;
     }
 }
+export function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "incomplete" || status === "cancelled";
+}
 function env(name) {
     return typeof process !== "undefined" ? process.env[name] : undefined;
 }
@@ -63,16 +80,30 @@ export class AgentLu {
     baseUrl;
     apiKey;
     fetchImpl;
+    defaultTimeoutMs;
     constructor(opts = {}) {
         this.baseUrl = (opts.baseUrl ?? env("AGENTLU_URL") ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         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) {
@@ -91,10 +122,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
@@ -117,14 +168,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() {
@@ -142,6 +198,12 @@ export class AgentLu {
         assertJsonRunOptions(opts);
         return this.runJsonForApiKey(this.apiKey, opts);
     }
+    async runText(opts) {
+        return this.runTextForApiKey(this.apiKey, opts);
+    }
+    async *stream(opts) {
+        yield* this.streamRunForApiKey(opts, this.apiKey);
+    }
     async runForApiKey(apiKey, opts) {
         const response = await this.createRunResponse(opts, apiKey);
         if (response.status === "failed" && response.error) {
@@ -150,6 +212,21 @@ export class AgentLu {
         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);
@@ -158,15 +235,32 @@ 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);
+        return this.request("POST", "/responses", body, this.transportFromRun(opts, apiKey));
+    }
+    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")
@@ -185,16 +279,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,
         };
@@ -211,7 +307,33 @@ 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) {
+        return {
+            apiKey,
+            timeoutMs: opts.timeoutMs ?? this.defaultTimeoutMs,
+            maxAttempts: opts.maxAttempts,
+            signal: opts.signal,
+        };
     }
     responses = {
         create: (body) => this.request("POST", "/responses", body),
@@ -226,10 +348,42 @@ 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);
+        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 = opts?.timeoutMs !== undefined ? Math.max(opts.timeoutMs - (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 (opts?.timeoutMs !== undefined && Date.now() - started + intervalMs >= opts.timeoutMs) {
+                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();
@@ -241,13 +395,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 {
@@ -260,6 +414,7 @@ export class AgentLu {
             }
         }
         finally {
+            await reader.cancel().catch(() => { });
             reader.releaseLock();
         }
     }
@@ -282,11 +437,21 @@ export class AgentLu {
      *     },
      *   });
      *   if (answers.urgent.noul > 0.8) routeToHuman();
+     *
+     * `timeoutMs` bounds each attempt (timeouts are never retried), `maxAttempts`
+     * overrides the shared 5-attempt policy, and `signal` cancels the call.
      */
     decisions = {
-        create: (body) => this.request("POST", "/decisions", body),
-        /** Same call, returning only the answers map. */
-        ask: async (body) => (await this.request("POST", "/decisions", 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 });
@@ -301,27 +466,33 @@ export class AgentLu {
         return this.request("GET", "/health", undefined, { auth: false });
     }
     async request(method, path, body, opts) {
+        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` and `503 too_many_active_runs` are correctness bounds,
         // not rate limits. Retrying with backoff is almost always the right thing,
         // 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.
+        // 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 < 5; attempt++) {
+        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 < 4) {
+                    attempt < maxAttempts - 1) {
                     last = e;
                     await sleep(retryDelayMs(e, attempt));
                     continue;
@@ -331,7 +502,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) {
@@ -340,11 +511,19 @@ export class AgentLu {
         const apiKey = opts?.apiKey ?? this.apiKey;
         if (opts?.auth !== false && apiKey)
             headers.Authorization = `Bearer ${apiKey}`;
-        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-            method,
-            headers,
-            body: body === undefined ? undefined : isForm ? body : JSON.stringify(body),
-        });
+        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}`;
@@ -388,7 +567,7 @@ export class UseCaseRunner {
         this.registerOpts = opts ?? {};
         this.operations = scopedUseCaseOperations.get(parent);
     }
-    /** Idempotent get-or-create; safe to call before every run. */
+    /** Idempotent get-or-create; safe to call on boot or before every run. */
     ensure() {
         if (this.apiKey)
             return Promise.resolve();
@@ -404,37 +583,123 @@ export class UseCaseRunner {
         }
         return this.ready;
     }
+    invalidate() {
+        this.apiKey = null;
+        this.ready = null;
+    }
+    async withAuthRetry(fn) {
+        await this.ensure();
+        try {
+            return await fn(this.apiKey);
+        }
+        catch (e) {
+            if (e instanceof AgentLuError && e.status === 401) {
+                this.invalidate();
+                await this.ensure();
+                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));
     }
-    async stream(body) {
+    async *stream(opts) {
         await this.ensure();
-        return this.operations.stream(this.apiKey, body);
+        try {
+            yield* this.operations.stream(this.apiKey, opts);
+        }
+        catch (e) {
+            if (!(e instanceof AgentLuError && e.status === 401))
+                throw e;
+            this.invalidate();
+            await this.ensure();
+            yield* this.operations.stream(this.apiKey, 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)
@@ -442,6 +707,41 @@ function parseRetryAfter(res) {
     const seconds = Number(header);
     return Number.isFinite(seconds) ? seconds * 1000 : undefined;
 }
+/** AbortSignal.timeout with a bare fallback (Node 18, older browsers). */
+function timeoutSignal(timeoutMs) {
+    if (typeof AbortSignal.timeout === "function")
+        return AbortSignal.timeout(timeoutMs);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`Request timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer.unref?.();
+    return controller.signal;
+}
+/** AbortSignal.any with a bare fallback (Node 18, older browsers). */
+function mergeSignals(signals) {
+    if (signals.length === 1)
+        return signals[0];
+    if (typeof AbortSignal.any === "function")
+        return AbortSignal.any(signals);
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+    }
+    return controller.signal;
+}
+/** Combined deadline/cancellation signal; undefined when neither applies. */
+function requestSignal(signal, timeoutMs) {
+    const signals = [];
+    if (signal)
+        signals.push(signal);
+    if (timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        signals.push(timeoutSignal(timeoutMs));
+    }
+    return signals.length ? mergeSignals(signals) : undefined;
+}
 function retryDelayMs(err, attempt) {
     if (err.retryAfterMs !== undefined) {
         return Math.min(10_000, Math.max(250, err.retryAfterMs));

package/package.json

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