@betterlu/agentlu 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -14,13 +14,29 @@ export declare class AgentLuError extends Error {
     readonly status: number;
     readonly code: string;
     readonly retryable: boolean;
-    constructor(status: number, code: string, message: string, retryable: boolean);
+    /** Parsed Retry-After header, in milliseconds, when present. */
+    readonly retryAfterMs?: number | undefined;
+    constructor(status: number, code: string, message: string, retryable: boolean, 
+    /** Parsed Retry-After header, in milliseconds, when present. */
+    retryAfterMs?: number | undefined);
 }
 export interface AgentLuOptions {
     baseUrl?: string;
     apiKey?: string;
     fetch?: typeof fetch;
 }
+export interface ClientDefaults {
+    agent?: string;
+    model?: string;
+    instructions?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    tools?: Array<string | {
+        type: string;
+        allowed_tools?: string[];
+    }>;
+    timeoutMs?: number;
+}
 export interface RunOptions {
     agent?: string;
     model?: string;
@@ -33,11 +49,17 @@ export interface RunOptions {
     conversation?: string;
     store?: boolean;
     person?: string | null;
+    owner?: "client" | "person";
+    title?: string;
     timeout_ms?: number;
     include?: string[];
+    temperature?: number;
+    max_output_tokens?: number;
     /** JSON Schema. When set, `data` on the result is the validated object. */
     schema?: Record<string, unknown>;
     schemaName?: string;
+    /** Queue a background run instead of waiting. Returns the queued response. */
+    background?: boolean;
 }
 export interface ResponseObject {
     id: string;
@@ -66,10 +88,27 @@ export declare class AgentLu {
     register(name: string, opts?: {
         person?: string | null;
         instructions?: string | null;
+        defaults?: ClientDefaults;
     }): Promise<ResponseObject & {
         api_key?: string;
         name: string;
     }>;
+    /**
+     * A runner bound to one registered use-case client.
+     *
+     * 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;
+    }): UseCaseRunner;
+    /** Register a use-case client and resolve to its api key. */
+    useCaseClient(name: string, opts?: {
+        person?: string | null;
+        defaults?: ClientDefaults;
+    }): Promise<string>;
     me(): Promise<unknown>;
     /**
      * One-shot helper. When `schema` is given, returns the validated object as
@@ -107,3 +146,36 @@ export declare class AgentLu {
     private request;
     private raw;
 }
+/**
+ * A runner bound to one registered use-case (one service client + its
+ * server-side defaults). Holds its own key so multiple use-cases can share
+ * one parent AgentLu without clobbering each other.
+ *
+ *   const alu = new AgentLu();
+ *   const enrich = alu.useCase("mealu-enrich", {
+ *     defaults: { instructions: "Parse meals...", temperature: 0.2 },
+ *   });
+ *   const { data } = await enrich.run({ input: "two eggs and toast" });
+ */
+export declare class UseCaseRunner {
+    private readonly parent;
+    readonly name: string;
+    private readonly registerOpts;
+    private apiKey;
+    private ready;
+    constructor(parent: AgentLu, name: string, opts?: {
+        person?: string | null;
+        defaults?: ClientDefaults;
+    });
+    /** Idempotent get-or-create; safe to call before every run. */
+    private ensure;
+    /**
+     * 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.
+     */
+    run<T = unknown>(opts: RunOptions): Promise<{
+        data?: T;
+        response: ResponseObject;
+    }>;
+    stream(body: Record<string, unknown>): Promise<AsyncGenerator<Record<string, unknown>, any, any>>;
+}

package/dist/index.js

@@ -14,11 +14,15 @@ export class AgentLuError extends Error {
     status;
     code;
     retryable;
-    constructor(status, code, message, retryable) {
+    retryAfterMs;
+    constructor(status, code, message, retryable, 
+    /** Parsed Retry-After header, in milliseconds, when present. */
+    retryAfterMs) {
         super(message);
         this.status = status;
         this.code = code;
         this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
         this.name = "AgentLuError";
     }
 }
@@ -41,6 +45,23 @@ export class AgentLu {
             this.apiKey = res.api_key;
         return res;
     }
+    /**
+     * A runner bound to one registered use-case client.
+     *
+     * 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);
+    }
+    /** Register a use-case client and resolve to its api key. */
+    async useCaseClient(name, opts) {
+        const res = await this.request("POST", "/clients", { name, ...opts }, { auth: false });
+        if (!res.api_key)
+            throw new AgentLuError(500, "internal_error", "register returned no key", true);
+        return res.api_key;
+    }
     async me() {
         return this.request("GET", "/me");
     }
@@ -59,8 +80,13 @@ export class AgentLu {
             conversation: opts.conversation,
             store: opts.store,
             person: opts.person,
+            owner: opts.owner,
+            title: opts.title,
             timeout_ms: opts.timeout_ms,
             include: opts.include,
+            temperature: opts.temperature,
+            max_output_tokens: opts.max_output_tokens,
+            background: opts.background,
         };
         if (opts.schema) {
             body.text = {
@@ -147,10 +173,11 @@ export class AgentLu {
         return this.request("GET", "/health", undefined, { auth: false });
     }
     async request(method, path, body, opts) {
-        // `409 thread_busy` is a correctness bound, not a rate limit. Retrying with
-        // a short backoff is almost always the right thing, so the SDK does it.
+        // `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.
         let last;
-        for (let attempt = 0; attempt < 4; attempt++) {
+        for (let attempt = 0; attempt < 5; attempt++) {
             try {
                 const res = await this.raw(method, path, body, opts);
                 if (res.status === 204)
@@ -159,15 +186,17 @@ export class AgentLu {
                 return json;
             }
             catch (e) {
-                if (e instanceof AgentLuError && e.code === "thread_busy" && attempt < 3) {
+                if (e instanceof AgentLuError &&
+                    (e.code === "thread_busy" || e.code === "too_many_active_runs" || e.status === 503) &&
+                    attempt < 4) {
                     last = e;
-                    await sleep(500 * 2 ** attempt);
+                    await sleep(retryDelayMs(e, attempt));
                     continue;
                 }
                 throw e;
             }
         }
-        throw last ?? new AgentLuError(409, "thread_busy", "thread busy", true);
+        throw last ?? new AgentLuError(503, "too_many_active_runs", "too many retries", true);
     }
     async raw(method, path, body, opts) {
         const headers = {};
@@ -196,11 +225,90 @@ export class AgentLu {
             catch {
                 /* keep defaults */
             }
-            throw new AgentLuError(res.status, code, message, retryable);
+            throw new AgentLuError(res.status, code, message, retryable, parseRetryAfter(res));
         }
         return res;
     }
 }
+/**
+ * A runner bound to one registered use-case (one service client + its
+ * server-side defaults). Holds its own key so multiple use-cases can share
+ * one parent AgentLu without clobbering each other.
+ *
+ *   const alu = new AgentLu();
+ *   const enrich = alu.useCase("mealu-enrich", {
+ *     defaults: { instructions: "Parse meals...", temperature: 0.2 },
+ *   });
+ *   const { data } = await enrich.run({ input: "two eggs and toast" });
+ */
+export class UseCaseRunner {
+    parent;
+    name;
+    registerOpts;
+    apiKey = null;
+    ready = null;
+    constructor(parent, name, opts) {
+        this.parent = parent;
+        this.name = name;
+        this.registerOpts = opts ?? {};
+    }
+    /** Idempotent get-or-create; safe to call before every run. */
+    ensure() {
+        if (this.apiKey)
+            return Promise.resolve();
+        if (!this.ready) {
+            this.ready = this.parent
+                .useCaseClient(this.name, this.registerOpts)
+                .then((key) => {
+                this.apiKey = key;
+            })
+                .catch((e) => {
+                this.ready = null;
+                throw e;
+            });
+        }
+        return this.ready;
+    }
+    /**
+     * 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();
+        const parentKey = this.parent.apiKey;
+        this.parent.apiKey = this.apiKey ?? undefined;
+        try {
+            return await this.parent.run(opts);
+        }
+        finally {
+            this.parent.apiKey = parentKey;
+        }
+    }
+    async stream(body) {
+        await this.ensure();
+        const parentKey = this.parent.apiKey;
+        this.parent.apiKey = this.apiKey ?? undefined;
+        try {
+            return await this.parent.responses.stream(body);
+        }
+        finally {
+            this.parent.apiKey = parentKey;
+        }
+    }
+}
+function parseRetryAfter(res) {
+    const header = res.headers.get("retry-after");
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    return Number.isFinite(seconds) ? seconds * 1000 : undefined;
+}
+function retryDelayMs(err, attempt) {
+    if (err.retryAfterMs !== undefined) {
+        return Math.min(10_000, Math.max(250, err.retryAfterMs));
+    }
+    return Math.min(10_000, 500 * 2 ** attempt);
+}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }

package/package.json

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