@betterlu/agentlu 1.4.0 → 1.5.0

package/README.md

@@ -118,6 +118,24 @@ 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).
 
+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
 
 The `browser` family reuses a persistent, headful BrowserLu session. Scope it

package/dist/index.d.ts

@@ -134,6 +134,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.
+     */
+    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;
@@ -361,6 +371,9 @@ 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>;

package/dist/index.js

@@ -10,6 +10,16 @@
  * `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) {
+    return { timeoutMs: body.timeoutMs, maxAttempts: body.maxAttempts, signal: body.signal };
+}
 /** Question builders; sugar over the wire shape. */
 export const noul = (instructions, criteria) => ({
     type: "noul",
@@ -282,11 +292,14 @@ 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),
+        create: (body) => this.request("POST", "/decisions", decisionWire(body), decisionRequestOptions(body)),
         /** Same call, returning only the answers map. */
-        ask: async (body) => (await this.request("POST", "/decisions", body)).answers,
+        ask: async (body) => (await this.request("POST", "/decisions", decisionWire(body), decisionRequestOptions(body))).answers,
     };
     async agents() {
         return this.request("GET", "/agents", undefined, { auth: false });
@@ -305,10 +318,14 @@ export class AgentLu {
         // 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)
@@ -321,7 +338,7 @@ export class AgentLu {
                     (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;
@@ -340,9 +357,11 @@ export class AgentLu {
         const apiKey = opts?.apiKey ?? this.apiKey;
         if (opts?.auth !== false && apiKey)
             headers.Authorization = `Bearer ${apiKey}`;
+        const signal = requestSignal(opts?.signal, opts?.timeoutMs);
         const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,
             headers,
+            ...(signal ? { signal } : {}),
             body: body === undefined ? undefined : isForm ? body : JSON.stringify(body),
         });
         if (!res.ok) {
@@ -442,6 +461,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.5.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",