@betterlu/agentlu 1.2.1 → 1.4.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 `run({ schema })`, and auto-retry on `409 thread_busy`.
+This client adds get-or-create registration, typed `runJson`, and auto-retry on `409 thread_busy`.
 
 ## Install
 
@@ -33,4 +33,110 @@ const { data, response } = await alu.run({
 console.log(response.output_text);
 ```
 
+## JSON results
+
+`runJson` returns only a completed response with the server-provided `output_parsed` value. It preserves JSON `null`, `false`, `0`, and empty arrays. A missing parsed value, failed response, incomplete response, cancellation, or queued response throws an SDK error instead of parsing `output_text`. `background: true` is rejected by this helper; use raw `run` when polling is intended.
+
+```ts
+const { data, response } = await alu.runJson<{ answer: string }>({
+  input: "Answer briefly",
+  schema: { type: "object", properties: { answer: { type: "string" } } },
+  schemaName: "Answer",
+  strict: true,
+});
+```
+
+An explicit `text.format` is forwarded unchanged. In particular, `text: { format: { type: "text" } }` is not silently changed to JSON by `runJson`.
+
+## Use-case defaults
+
+Defaults are resolved by the service for every request:
+
+```text
+request field  ->  registered client default  ->  agent/profile default
+```
+
+Register a client once per use-case. The runner sends only request-level overrides, so its registered schema is not resent with every run:
+
+```ts
+const schema = { type: "object", properties: { meal: { type: "string" } } };
+const mealEnricher = alu.useCase("mealu-enrich", {
+  defaults: {
+    agent: "api",
+    store: false,
+    tools: [],
+    reasoning: { effort: "medium" },
+    text: { format: { type: "json_schema", name: "Meal", schema } },
+  },
+});
+
+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.
+
 Env: `AGENTLU_URL` (default `http://localhost:8912/v1`), `AGENTLU_API_KEY`.
+
+## Decisions (System One / Jev)
+
+`decisions` is a different primitive from `run`: Jev returns typed, calibrated
+probabilities - never text - in ~100-500ms. Use it for routing, classification,
+scoring and gating inside your own code.
+
+```ts
+import { AgentLu, noul, choice, score } from "@betterlu/agentlu";
+
+const alu = new AgentLu();
+alu.apiKey = key;
+
+const { answers } = await alu.decisions.create({
+  state: "I was charged twice and I'm losing sales. Please fix this ASAP.",
+  questions: {
+    urgent: noul("Does this need urgent attention?"),
+    team: choice("Which team should handle it?", {
+      billing: "charges and payments",
+      shipping: "delivery",
+    }),
+    frustration: score("How frustrated is the customer?", ["Calm", "Frustrated", "Very angry"]),
+  },
+});
+
+if (answers.urgent.type === "noul" && answers.urgent.noul > 0.8) routeToHuman();
+if (answers.team.type === "choice") return lookupOrder(answers.team.choice);
+```
+
+`answers.<name>` is a discriminated union on `type`:
+
+| Question | Answer fields |
+|---|---|
+| `noul` | `noul` - probability that the answer is yes (0..1) |
+| `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
+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).
+
+## Browser handoff
+
+The `browser` family reuses a persistent, headful BrowserLu session. Scope it
+to the operations the caller needs and identify the linked household person:
+
+```ts
+const { response } = await alu.run({
+  agent: "api",
+  person: "larry",
+  tools: [{ type: "browser", allowed_tools: ["browser_open", "browser_snapshot"] }],
+  input: "Read the current page and summarize it.",
+});
+
+if (response.agentlu?.browser?.status === "needs_human") {
+  // Let this request end. The human completes login/MFA in the AgentLu viewer,
+  // then send a new request with the same conversation/session context.
+}
+```
+
+Browser response metadata contains the session and page identity plus screenshot
+ids. Screenshot pixels stay in the authenticated viewer and are not copied into
+API response metadata.

package/dist/index.d.ts

@@ -6,10 +6,155 @@
  *   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 `run({ schema })`, and auto-retry on
+ * get-or-create registration, typed `runJson`, 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";
+/** 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;
+export type BrowserStatus = "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted";
+export interface BrowserScreenshot {
+    id: string;
+    createdAt: string;
+    width: number;
+    height: number;
+}
+export interface BrowserActivity {
+    sessionId: string;
+    username: "larry" | "misa";
+    ownerId?: string;
+    tabId?: string;
+    url?: string;
+    title?: string;
+    status: BrowserStatus;
+    action?: string;
+    reason?: string;
+    observationId?: string;
+    screenshots?: BrowserScreenshot[];
+}
+export type AndroidStatus = "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
+export type AndroidOperationState = "running" | "succeeded" | "failed" | "unknown";
+export interface AndroidOperation {
+    operationId: string;
+    kind: string;
+    state: AndroidOperationState;
+    dispatchedAt: string;
+    settledAt?: string;
+    outcome?: string;
+}
+export interface AndroidActivity {
+    sessionId: string;
+    username: "larry" | "misa";
+    ownerId?: string;
+    status: AndroidStatus;
+    action?: string;
+    reason?: string;
+    observationId?: string;
+    leaseId?: string;
+    readiness?: "stopped" | "booting" | "ready" | "failed";
+    control?: "idle" | "agent" | "needs_human" | "human" | "reserved" | "interrupted";
+    foregroundPackage?: string;
+    pendingOperation?: AndroidOperation;
+    lastOperation?: AndroidOperation;
+    viewerPath?: string;
+    reservationExpiresAt?: string;
+}
+export interface ReasoningOptions {
+    effort?: ThinkingLevel;
+}
+export interface ClientReasoningOptions {
+    effort: ThinkingLevel;
+}
+export interface TextFormatText {
+    type: "text";
+}
+export interface TextFormatJsonSchema {
+    type: "json_schema";
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+    description?: string;
+}
+export type TextFormat = TextFormatText | TextFormatJsonSchema;
+export interface TextConfig {
+    format?: TextFormat;
+}
+/** Yes/no, answered as the probability that the answer is yes. */
+export interface NoulQuestion {
+    type: "noul";
+    instructions: string;
+    /** Optional descriptions of the true/false poles (calibrates the answer). */
+    criteria?: {
+        true: string;
+        false: string;
+    };
+}
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    /** Option name -> description. At least two options. */
+    criteria: Record<string, string>;
+}
+export interface ScoreQuestion {
+    type: "score";
+    instructions: string;
+    /** Ordered levels, lowest first. At least two. */
+    criteria: string[];
+}
+export type DecisionQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export interface NoulAnswer {
+    type: "noul";
+    noul: number;
+}
+export interface ChoiceAnswer {
+    type: "choice";
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+}
+export interface ScoreAnswer {
+    type: "score";
+    score: number;
+    confidence: number;
+    legend?: Record<string, string>;
+    probabilities: Record<string, number>;
+}
+export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export interface DecisionOptions {
+    /** Unstructured input: a text state, or a JSON object (serialized upstream). */
+    state: string | Record<string, unknown>;
+    questions: Record<string, DecisionQuestion>;
+    /** Decision model id (default: the configured `typesafe/jev`). */
+    model?: string;
+}
+export interface DecisionObject {
+    id: string;
+    object: "decision";
+    created_at: number;
+    model: string;
+    answers: Record<string, DecisionAnswer>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    } | null;
+    [k: string]: unknown;
+}
+/** Question builders; sugar over the wire shape. */
+export declare const noul: (instructions: string, criteria?: {
+    true: string;
+    false: string;
+}) => NoulQuestion;
+export declare const choice: (instructions: string, criteria: Record<string, string>) => ChoiceQuestion;
+export declare const score: (instructions: string, levels: string[]) => ScoreQuestion;
 export declare class AgentLuError extends Error {
     readonly status: number;
     readonly code: string;
@@ -20,42 +165,57 @@ export declare class AgentLuError extends Error {
     /** Parsed Retry-After header, in milliseconds, when present. */
     retryAfterMs?: number | undefined);
 }
+export declare class AgentLuResponseError extends AgentLuError {
+    readonly response: ResponseObject;
+    readonly responseStatus: string;
+    constructor(response: ResponseObject);
+}
 export interface AgentLuOptions {
     baseUrl?: string;
     apiKey?: string;
     fetch?: typeof fetch;
 }
 export interface ClientDefaults {
+    backend?: Backend;
     agent?: string;
     model?: string;
     instructions?: string;
     temperature?: number;
-    maxOutputTokens?: number;
-    tools?: Array<string | {
-        type: string;
-        allowed_tools?: string[];
-    }>;
+    tools?: ApiToolInput[];
     timeoutMs?: number;
+    store?: boolean;
+    reasoning?: ClientReasoningOptions;
+    text?: TextConfig;
+}
+/** 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";
 }
 export interface RunOptions {
+    backend?: Backend;
     agent?: string;
     model?: string;
     input?: string;
     /**
-     * Image attachments previously uploaded via `upload()`. Prepended to the
-     * user turn as `input_image` parts; `input` becomes the accompanying text.
-     */
+      * 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">;
     /** Structured input messages (OpenAI shape) - overrides `input`. */
     inputMessages?: Array<{
         role: string;
         content: string | Array<Record<string, unknown>>;
     }>;
     instructions?: string;
-    tools?: Array<string | {
-        type: string;
-        allowed_tools?: string[];
-    }>;
+    tools?: ApiToolInput[];
+    reasoning?: ReasoningOptions;
+    text?: TextConfig;
+    strict?: boolean;
     conversation?: string;
     store?: boolean;
     person?: string | null;
@@ -76,6 +236,7 @@ export interface RunOptions {
 export interface ResponseObject {
     id: string;
     status: string;
+    backend: Backend;
     output_text: string;
     output_parsed?: unknown;
     conversation?: {
@@ -86,8 +247,19 @@ export interface ResponseObject {
         message: string;
         retryable: boolean;
     } | null;
+    incomplete_details?: {
+        reason: string;
+    } | null;
     agentlu?: {
         session_url?: string | null;
+        /** Model the runtime actually served (requested `model` may have fallen back). */
+        effective_model?: string | null;
+        /** MiniMax admission tier requested for the winning attempt, when any. */
+        service_tier?: "standard" | "priority";
+        /** Latest persistent BrowserLu activity; screenshot bytes are never in this object. */
+        browser?: BrowserActivity;
+        /** Latest persistent AndroidLu activity; screenshot bytes are never in this object. */
+        android?: AndroidActivity;
     };
     [k: string]: unknown;
 }
@@ -96,11 +268,13 @@ export declare class AgentLu {
     apiKey: string | undefined;
     private readonly fetchImpl;
     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 & {
         api_key?: string;
         name: string;
@@ -111,10 +285,11 @@ 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;
     /**
      * Register a use-case client and resolve to its api key. The key is cached
@@ -124,14 +299,18 @@ export declare class AgentLu {
     useCaseClient(name: string, opts?: {
         person?: string | null;
         defaults?: ClientDefaults;
+        use_case_profile?: UseCaseProfile;
     }): Promise<string>;
+    private registerForUseCase;
     /**
-     * Upload an image (or document) for use with `run({ fileIds })` /
-     * `input_image`. Returns the `file_id` to reference.
+     * 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<{
         id: string;
+        kind?: string;
     }>;
+    private uploadForApiKey;
     me(): Promise<unknown>;
     /**
      * One-shot helper. When `schema` is given, returns the validated object as
@@ -142,6 +321,13 @@ export declare class AgentLu {
         data?: T;
         response: ResponseObject;
     }>;
+    runJson<T = unknown>(opts: RunOptions): Promise<{
+        data: T;
+        response: ResponseObject;
+    }>;
+    private runForApiKey;
+    private runJsonForApiKey;
+    private createRunResponse;
     readonly responses: {
         create: (body: Record<string, unknown>) => Promise<ResponseObject>;
         retrieve: (id: string) => Promise<ResponseObject>;
@@ -153,8 +339,9 @@ export declare class AgentLu {
             object: string;
             data: ResponseObject[];
         }>;
-        stream: (body: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>>;
+        stream: (body: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>, any, any>;
     };
+    private streamForApiKey;
     readonly threads: {
         create: (body?: Record<string, unknown>) => Promise<unknown>;
         retrieve: (id: string) => Promise<unknown>;
@@ -162,6 +349,24 @@ export declare class AgentLu {
         delete: (id: string) => Promise<unknown>;
         messages: (id: string) => Promise<unknown>;
     };
+    /**
+     * Decision model (System One / Jev): typed questions in, calibrated
+     * probabilities out, ~100-500ms. Sync only - there is no stream or poll.
+     *
+     *   const { answers } = await alu.decisions.create({
+     *     state: "I was charged twice and I'm losing sales. Please fix this ASAP.",
+     *     questions: {
+     *       urgent: noul("Does this need urgent attention?"),
+     *       team: choice("Which team should handle it?", { billing: "charges", shipping: "delivery" }),
+     *     },
+     *   });
+     *   if (answers.urgent.noul > 0.8) routeToHuman();
+     */
+    readonly decisions: {
+        create: (body: DecisionOptions) => Promise<DecisionObject>;
+        /** Same call, returning only the answers map. */
+        ask: (body: DecisionOptions) => Promise<Record<string, DecisionAnswer>>;
+    };
     agents(): Promise<unknown>;
     models(): Promise<unknown>;
     tools(): Promise<unknown>;
@@ -181,14 +386,15 @@ export declare class AgentLu {
  *   const { data } = await enrich.run({ input: "two eggs and toast" });
  */
 export declare class UseCaseRunner {
-    private readonly parent;
     readonly name: string;
     private readonly registerOpts;
+    private readonly operations;
     private apiKey;
     private ready;
     constructor(parent: AgentLu, name: string, opts?: {
         person?: string | null;
         defaults?: ClientDefaults;
+        use_case_profile?: UseCaseProfile;
     });
     /** Idempotent get-or-create; safe to call before every run. */
     private ensure;
@@ -200,5 +406,17 @@ export declare class UseCaseRunner {
         data?: T;
         response: ResponseObject;
     }>;
+    runJson<T = unknown>(opts: RunOptions): Promise<{
+        data: T;
+        response: ResponseObject;
+    }>;
     stream(body: Record<string, unknown>): Promise<AsyncGenerator<Record<string, unknown>, any, any>>;
+    /**
+     * 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<{
+        id: string;
+        kind?: string;
+    }>;
 }

package/dist/index.js

@@ -6,10 +6,26 @@
  *   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 `run({ schema })`, and auto-retry on
+ * get-or-create registration, typed `runJson`, and auto-retry on
  * `409 thread_busy`.
  */
 export const DEFAULT_BASE_URL = "http://localhost:8912/v1";
+/** Question builders; sugar over the wire shape. */
+export const noul = (instructions, criteria) => ({
+    type: "noul",
+    instructions,
+    ...(criteria ? { criteria } : {}),
+});
+export const choice = (instructions, criteria) => ({
+    type: "choice",
+    instructions,
+    criteria,
+});
+export const score = (instructions, levels) => ({
+    type: "score",
+    instructions,
+    criteria: levels,
+});
 export class AgentLuError extends Error {
     status;
     code;
@@ -26,9 +42,23 @@ export class AgentLuError extends Error {
         this.name = "AgentLuError";
     }
 }
+export class AgentLuResponseError extends AgentLuError {
+    response;
+    responseStatus;
+    constructor(response) {
+        const responseStatus = response.status;
+        const code = response.error?.code ?? responseStatus;
+        const message = response.error?.message ?? `Response status "${responseStatus}" is not completed.`;
+        super(200, code, message, response.error?.retryable ?? false);
+        this.name = "AgentLuResponseError";
+        this.response = response;
+        this.responseStatus = responseStatus;
+    }
+}
 function env(name) {
     return typeof process !== "undefined" ? process.env[name] : undefined;
 }
+const scopedUseCaseOperations = new WeakMap();
 export class AgentLu {
     baseUrl;
     apiKey;
@@ -37,10 +67,20 @@ export class AgentLu {
         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);
+        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),
+        });
+    }
+    postClient(name, opts) {
+        return this.request("POST", "/clients", { name, ...opts }, { auth: false });
     }
     /** Get-or-create a client by name. Caches the returned key on this instance. */
     async register(name, opts) {
-        const res = await this.request("POST", "/clients", { name, ...opts }, { auth: false });
+        const res = await this.postClient(name, opts);
         if (res.api_key)
             this.apiKey = res.api_key;
         return res;
@@ -51,7 +91,7 @@ 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);
     }
@@ -61,21 +101,30 @@ export class AgentLu {
      * `responses.create` is authorized.
      */
     async useCaseClient(name, opts) {
-        const res = await this.request("POST", "/clients", { name, ...opts }, { auth: false });
+        const res = await this.postClient(name, opts);
         if (!res.api_key)
             throw new AgentLuError(500, "internal_error", "register returned no key", true);
         this.apiKey = res.api_key;
         return res.api_key;
     }
+    async registerForUseCase(name, opts) {
+        const res = await this.postClient(name, opts);
+        if (!res.api_key)
+            throw new AgentLuError(500, "internal_error", "register returned no key", true);
+        return res.api_key;
+    }
     /**
-     * Upload an image (or document) for use with `run({ fileIds })` /
-     * `input_image`. Returns the `file_id` to reference.
+     * 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 uploadForApiKey(data, filename, mime, apiKey) {
         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);
+        const res = await this.raw("POST", "/files", form, { apiKey });
         return (await res.json());
     }
     async me() {
@@ -87,13 +136,43 @@ export class AgentLu {
      * could not produce matching JSON.
      */
     async run(opts) {
+        return this.runForApiKey(this.apiKey, opts);
+    }
+    async runJson(opts) {
+        assertJsonRunOptions(opts);
+        return this.runJsonForApiKey(this.apiKey, 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);
+        }
+        return { data: response.output_parsed, response };
+    }
+    async runJsonForApiKey(apiKey, opts) {
+        const response = await this.createRunResponse(opts, apiKey);
+        if (response.status !== "completed")
+            throw new AgentLuResponseError(response);
+        if (!Object.prototype.hasOwnProperty.call(response, "output_parsed")) {
+            throw new AgentLuError(200, "missing_output_parsed", "Completed response did not include output_parsed.", false);
+        }
+        return { data: response.output_parsed, response };
+    }
+    async createRunResponse(opts, apiKey) {
         let input = opts.inputMessages ?? opts.input;
         if (opts.fileIds?.length) {
             input = [
                 {
                     role: "user",
                     content: [
-                        ...opts.fileIds.map((file_id) => ({ type: "input_image", file_id })),
+                        ...opts.fileIds.map((file_id, i) => {
+                            const kind = opts.fileKinds?.[i];
+                            if (kind === "video")
+                                return { type: "input_video", file_id };
+                            if (kind === "text" || kind === "document")
+                                return { type: "input_file", file_id };
+                            return { type: "input_image", file_id };
+                        }),
                         { type: "input_text", text: opts.input ?? "" },
                     ],
                 },
@@ -101,10 +180,12 @@ export class AgentLu {
         }
         const body = {
             input,
+            backend: opts.backend,
             agent: opts.agent,
             model: opts.model,
             instructions: opts.instructions,
             tools: opts.tools,
+            reasoning: opts.reasoning,
             conversation: opts.conversation,
             store: opts.store,
             person: opts.person,
@@ -117,21 +198,20 @@ export class AgentLu {
             background: opts.background,
             metadata: opts.metadata,
         };
-        if (opts.schema) {
+        if (opts.text !== undefined) {
+            body.text = opts.text;
+        }
+        else if (opts.schema !== undefined) {
             body.text = {
                 format: {
                     type: "json_schema",
                     name: opts.schemaName ?? "Result",
                     schema: opts.schema,
-                    strict: true,
+                    strict: opts.strict ?? true,
                 },
             };
         }
-        const response = await this.responses.create(body);
-        if (response.status === "failed" && response.error) {
-            throw new AgentLuError(200, response.error.code, response.error.message, response.error.retryable);
-        }
-        return { data: response.output_parsed, response };
+        return this.request("POST", "/responses", body, { apiKey });
     }
     responses = {
         create: (body) => this.request("POST", "/responses", body),
@@ -146,42 +226,43 @@ export class AgentLu {
             const qs = q.toString();
             return this.request("GET", `/responses${qs ? `?${qs}` : ""}`);
         },
-        stream: async function* stream(body) {
-            const res = await this.raw("POST", "/responses", { ...body, stream: true });
-            if (!res.body)
-                throw new AgentLuError(0, "internal_error", "empty stream body", true);
-            const reader = res.body.getReader();
-            const decoder = new TextDecoder();
-            let buf = "";
-            try {
-                for (;;) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    buf += decoder.decode(value, { stream: true });
-                    const lines = buf.split("\n");
-                    buf = lines.pop() ?? "";
-                    for (const line of lines) {
-                        const trimmed = line.trim();
-                        if (!trimmed.startsWith("data: "))
-                            continue;
-                        const payload = trimmed.slice(6);
-                        if (payload === "[DONE]")
-                            return;
-                        try {
-                            yield JSON.parse(payload);
-                        }
-                        catch {
-                            /* ignore malformed chunks */
-                        }
+        stream: (body) => this.streamForApiKey(body),
+    };
+    async *streamForApiKey(body, apiKey) {
+        const res = await this.raw("POST", "/responses", { ...body, stream: true }, { apiKey });
+        if (!res.body)
+            throw new AgentLuError(0, "internal_error", "empty stream body", true);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buf += decoder.decode(value, { stream: true });
+                const lines = buf.split("\n");
+                buf = lines.pop() ?? "";
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("data: "))
+                        continue;
+                    const payload = trimmed.slice(6);
+                    if (payload === "[DONE]")
+                        return;
+                    try {
+                        yield JSON.parse(payload);
+                    }
+                    catch {
+                        /* ignore malformed chunks */
                     }
                 }
             }
-            finally {
-                reader.releaseLock();
-            }
-        }.bind(this),
-    };
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
     threads = {
         create: (body = {}) => this.request("POST", "/threads", body),
         retrieve: (id) => this.request("GET", `/threads/${encodeURIComponent(id)}`),
@@ -189,6 +270,24 @@ export class AgentLu {
         delete: (id) => this.request("DELETE", `/threads/${encodeURIComponent(id)}`),
         messages: (id) => this.request("GET", `/threads/${encodeURIComponent(id)}/messages`),
     };
+    /**
+     * Decision model (System One / Jev): typed questions in, calibrated
+     * probabilities out, ~100-500ms. Sync only - there is no stream or poll.
+     *
+     *   const { answers } = await alu.decisions.create({
+     *     state: "I was charged twice and I'm losing sales. Please fix this ASAP.",
+     *     questions: {
+     *       urgent: noul("Does this need urgent attention?"),
+     *       team: choice("Which team should handle it?", { billing: "charges", shipping: "delivery" }),
+     *     },
+     *   });
+     *   if (answers.urgent.noul > 0.8) routeToHuman();
+     */
+    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,
+    };
     async agents() {
         return this.request("GET", "/agents", undefined, { auth: false });
     }
@@ -205,6 +304,9 @@ export class AgentLu {
         // `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.
+        const nonRetryable503 = new Set(["systemone_unconfigured"]);
         let last;
         for (let attempt = 0; attempt < 5; attempt++) {
             try {
@@ -216,7 +318,9 @@ export class AgentLu {
             }
             catch (e) {
                 if (e instanceof AgentLuError &&
-                    (e.code === "thread_busy" || e.code === "too_many_active_runs" || e.status === 503) &&
+                    (e.code === "thread_busy" ||
+                        e.code === "too_many_active_runs" ||
+                        (e.status === 503 && !nonRetryable503.has(e.code))) &&
                     attempt < 4) {
                     last = e;
                     await sleep(retryDelayMs(e, attempt));
@@ -233,8 +337,9 @@ export class AgentLu {
         if (body !== undefined && !isForm) {
             headers["Content-Type"] = "application/json";
         }
-        if (opts?.auth !== false && this.apiKey)
-            headers.Authorization = `Bearer ${this.apiKey}`;
+        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,
@@ -273,23 +378,22 @@ export class AgentLu {
  *   const { data } = await enrich.run({ input: "two eggs and toast" });
  */
 export class UseCaseRunner {
-    parent;
     name;
     registerOpts;
+    operations;
     apiKey = null;
     ready = null;
     constructor(parent, name, opts) {
-        this.parent = parent;
         this.name = name;
         this.registerOpts = opts ?? {};
+        this.operations = scopedUseCaseOperations.get(parent);
     }
     /** 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)
+            this.ready = this.operations.register(this.name, this.registerOpts)
                 .then((key) => {
                 this.apiKey = key;
             })
@@ -306,25 +410,29 @@ export class UseCaseRunner {
      */
     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;
-        }
+        return (await this.operations.run(this.apiKey, opts));
+    }
+    async runJson(opts) {
+        assertJsonRunOptions(opts);
+        await this.ensure();
+        return (await this.operations.runJson(this.apiKey, opts));
     }
     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;
-        }
+        return this.operations.stream(this.apiKey, body);
+    }
+    /**
+     * 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);
+    }
+}
+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 parseRetryAfter(res) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterlu/agentlu",
-  "version": "1.2.1",
+  "version": "1.4.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",
@@ -11,8 +11,12 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
-  "engines": { "node": ">=18" },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"
@@ -20,7 +24,13 @@
   "publishConfig": {
     "access": "public"
   },
-  "keywords": ["agentlu", "openai", "responses", "llm", "agent"],
+  "keywords": [
+    "agentlu",
+    "openai",
+    "responses",
+    "llm",
+    "agent"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/betterlu/agentlu.git",