@betterlu/agentlu 1.8.0 → 1.9.0

package/README.md

@@ -54,7 +54,7 @@ const { data } = await alu.llm.json<{ items: string[] }>(
 );
 for await (const event of alu.llm.stream("Count to three")) console.log(event.type);
 
-// Agent tier (default agent `api`; pin fast/research/… or "<app>/<name>").
+// Agent tier (default agent `api`; pin fast/thorough/… or "<app>/<name>").
 const run = await alu.agent.run({ agent: "fast", input: "what changed in node 24?" });
 const done = await alu.agent.background({ input: "research this deeply" }, { timeoutMs: 600_000 });
 ```
@@ -89,6 +89,27 @@ try {
 | `incomplete` | the run finished without a complete answer |
 | `internal` | anything else, including a cancelled run and the `systemone_unconfigured` config boundary (never retried, so it surfaces instead of degrading) |
 
+## Waiting for agentlu on boot
+
+Apps that PM2 starts alongside agentlu (reboot, `pm2 restart agentlu`) should
+wait for it before registering, in the background, so they don't warn on the
+first `ECONNREFUSED`. `waitForReady` polls `/health` with backoff while it is
+unreachable and resolves `true`, or `false` at the deadline. It never throws.
+
+```ts
+void (async () => {
+  const up = await alu.waitForReady({
+    timeoutMs: 90_000,
+    onWait: ({ attempt }) => attempt === 1 && log.info("waiting for agentlu"),
+  });
+  try {
+    await useCases.ensure();
+  } catch (err) {
+    log.warn("agentlu register failed", { err, waited: up });
+  }
+})();
+```
+
 ## Bulk uploads and background runs
 
 ```ts

package/dist/generated.d.ts

@@ -11,7 +11,7 @@
 export interface WireCreateResponse {
     /** Execution backend. */
     "backend"?: "pi";
-    /** Model id, or an agent name (stock OpenAI clients can only set `model`). Harness-qualified ids run other runtimes: `google/<id>` selects an Antigravity model (defaults to the read-only `google-research` agent unless `agent` names another Google mode). See GET /v1/models and GET /v1/models?harness=google. */
+    /** Model id, or an agent name (stock OpenAI clients can only set `model`). Harness-qualified ids run other runtimes: `google/<id>` selects an Antigravity model on the Google agent. See GET /v1/models and GET /v1/models?harness=google. */
     "model"?: string;
     "input"?: string | Array<{
         "role": "user" | "assistant" | "system" | "developer";
@@ -70,8 +70,8 @@ export interface WireCreateResponse {
     "tool_choice"?: "auto" | "none" | "required";
     "metadata"?: Record<string, string>;
     "include"?: Array<"reasoning" | "rounds" | "subagents" | "artifacts">;
-    /** Which agent runs the request. The recommended general machine agent is `api`, which has no persona: `instructions` replace its system prompt. Pin `fast` for the chat-tuned version. Use `android` for the shared Android phone. `direct` selects the direct tier: the profile-free `api` agent with no tools and no session (see the Tiers section). An `<app>/<name>` id runs an agent the caller's app declared at registration. */
-    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom" | "direct" | string;
+    /** Which agent runs the request. The recommended general machine agent is `api`, which has no persona: `instructions` replace its system prompt. Pin `fast` for the chat-tuned version. `direct` selects the direct tier: the profile-free `api` agent with no tools and no session (see the Tiers section). `household/<slug>` runs a household agent built in the Agents studio (list them at GET /v1/agents). An `<app>/<name>` id runs an agent the caller's app declared at registration. `research` is an alias for `thorough` with Report output (a sourced report artifact). Retired ids (`mealu`, `nestlu`, `kitchen`, `waterlu`, `money`, `swarm`, `storylu`, `google-research`, `google-image`, `android`) return HTTP 400 `unknown_agent` with a pointer to their successor; the Android phone is now the `android` tool family on `assistant`. */
+    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "storylu" | "google-research" | "google-image" | "android" | "research";
     /** Thinking level. Explicit `effort: "off"` is honored; other requests are clamped to the selected model's supported capabilities. The SDK does not promise provider benchmark parity. */
     "reasoning"?: {
         "effort"?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -84,7 +84,6 @@ export interface WireCreateResponse {
     "person"?: string | null;
     /** person = attribute the thread to the human matching `person` (shows in their sidebar). Requires the client flag `allow_person_threads`; without it a stored/threaded request is rejected with HTTP 403 `person_threads_not_allowed`. A sessionless `store: false` run creates no thread, so there is nothing to attribute and the flag is not consulted. */
     "owner"?: "client" | "person";
-    "project"?: string;
     /** Opaque caller-side identity (one of your users or devices). Stored on the response and, for stored runs, its thread; filter with `?end_user=`. */
     "end_user"?: string;
 }
@@ -150,7 +149,7 @@ export interface WireRegisterClientRequest {
     /** Run defaults applied when a request omits the field: request > registered client default > use-case tier > agent/profile default. The built-in `store` default is true. Register one client per use-case (e.g. mealu-enrich) with its system prompt and tools baked in. */
     "defaults"?: {
         "backend"?: "pi";
-        "agent"?: "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom" | "direct" | string;
+        "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "storylu" | "google-research" | "google-image" | "android" | "research";
         "model"?: string;
         "instructions"?: string;
         "temperature"?: number;
@@ -200,8 +199,8 @@ export interface WireRegisterClientRequest {
 /** Run defaults applied when a request omits the field: request > registered client default > use-case tier > agent/profile default. The built-in `store` default is true. Register one client per use-case (e.g. mealu-enrich) with its system prompt and tools baked in. */
 export interface WireClientDefaults {
     "backend"?: "pi";
-    /** Which agent runs the request. The recommended general machine agent is `api`, which has no persona: `instructions` replace its system prompt. Pin `fast` for the chat-tuned version. Use `android` for the shared Android phone. `direct` selects the direct tier: the profile-free `api` agent with no tools and no session (see the Tiers section). An `<app>/<name>` id runs an agent the caller's app declared at registration. */
-    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom" | "direct" | string;
+    /** Which agent runs the request. The recommended general machine agent is `api`, which has no persona: `instructions` replace its system prompt. Pin `fast` for the chat-tuned version. `direct` selects the direct tier: the profile-free `api` agent with no tools and no session (see the Tiers section). `household/<slug>` runs a household agent built in the Agents studio (list them at GET /v1/agents). An `<app>/<name>` id runs an agent the caller's app declared at registration. `research` is an alias for `thorough` with Report output (a sourced report artifact). Retired ids (`mealu`, `nestlu`, `kitchen`, `waterlu`, `money`, `swarm`, `storylu`, `google-research`, `google-image`, `android`) return HTTP 400 `unknown_agent` with a pointer to their successor; the Android phone is now the `android` tool family on `assistant`. */
+    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "storylu" | "google-research" | "google-image" | "android" | "research";
     /** ModelConfig id (GET /v1/models). Stock clients may also use an agent name here; prefer explicit `agent` for machine calls. */
     "model"?: string;
     /** System prompt for every run of this client. */
@@ -264,7 +263,7 @@ export interface WireAppAgentDeclaration {
 }
 export interface WireCreateThreadRequest {
     "title"?: string;
-    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "research" | string;
     "model"?: string;
     "person"?: string | null;
     "owner"?: "client" | "person";
@@ -300,7 +299,7 @@ export interface WireResponse {
     "created_at": number;
     "status": "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
     "backend": "pi";
-    "agent": "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+    "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
     "model": string;
     "conversation"?: {
         "id": string;
@@ -411,7 +410,7 @@ export interface WireResponse {
         };
         "android"?: {
             "sessionId"?: string;
-            "username"?: "larry" | "misa";
+            "username"?: string;
             "ownerId"?: string;
             "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
             "action"?: string;
@@ -487,7 +486,7 @@ export interface WireThread {
     "created_at": number;
     "updated_at": number;
     "title": string;
-    "agent": "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+    "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
     "model": string | null;
     /** "api" for threads created through /v1; "chat" when a human started it. */
     "origin": string;
@@ -526,7 +525,7 @@ export interface WireClient {
     "allow_person_threads"?: boolean;
     "defaults"?: {
         "backend"?: "pi";
-        "agent"?: "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom" | "direct" | string;
+        "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "storylu" | "google-research" | "google-image" | "android" | "research";
         "model"?: string;
         "instructions"?: string;
         "temperature"?: number;
@@ -592,7 +591,8 @@ export interface WireError {
     };
 }
 export interface WireAgentInfo {
-    "id": "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+    /** A builtin agent id, or `household/<slug>` for an agent built in the household studio. */
+    "id": string;
     "object": "agent";
     "profile": string;
     "description": string;
@@ -604,6 +604,8 @@ export interface WireAgentInfo {
     "long_running": boolean;
     /** Runtime that serves this agent. */
     "harness": "pi" | "google";
+    /** Household agents only: the capability ids the agent was built with. */
+    "capabilities"?: string[];
 }
 export interface WireModelInfo {
     "id": string;
@@ -616,6 +618,8 @@ export interface WireModelInfo {
     "default": boolean;
     /** Runtime that serves this model. */
     "harness": "pi" | "google" | "systemone";
+    /** Reasoning levels the model accepts (google models: the values the ACP thought_level option advertises). */
+    "efforts"?: Array<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
     /** Present on decision models: how to call them. */
     "decision"?: {
         "endpoint": "/v1/decisions";
@@ -646,7 +650,7 @@ export interface WireResponseList {
         "created_at": number;
         "status": "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
         "backend": "pi";
-        "agent": "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+        "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
         "model": string;
         "conversation"?: {
             "id": string;
@@ -752,7 +756,7 @@ export interface WireResponseList {
             };
             "android"?: {
                 "sessionId"?: string;
-                "username"?: "larry" | "misa";
+                "username"?: string;
                 "ownerId"?: string;
                 "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
                 "action"?: string;
@@ -778,7 +782,7 @@ export interface WireThreadList {
         "created_at": number;
         "updated_at": number;
         "title": string;
-        "agent": "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+        "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
         "model": string | null;
         "origin": string;
         "end_user"?: string | null;
@@ -832,7 +836,7 @@ export interface WireFileList {
 export interface WireAgentList {
     "object": "list";
     "data": Array<{
-        "id": "auto" | "fast" | "thorough" | "assistant" | "research" | "swarm" | "code" | "google" | "google-research" | "google-image" | "image" | "mealu" | "kitchen" | "waterlu" | "money" | "storylu" | "nestlu" | "android" | "api" | "digest" | "cradle" | "roleplay" | "stage" | "custom";
+        "id": string;
         "object": "agent";
         "profile": string;
         "description": string;
@@ -841,6 +845,7 @@ export interface WireAgentList {
         "supports_images": boolean;
         "long_running": boolean;
         "harness": "pi" | "google";
+        "capabilities"?: string[];
     }>;
     /** Opaque keyset cursor; null on the last page. */
     "next_cursor": string | null;
@@ -856,6 +861,7 @@ export interface WireModelList {
         "available": boolean;
         "default": boolean;
         "harness": "pi" | "google" | "systemone";
+        "efforts"?: Array<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
         "decision"?: {
             "endpoint": "/v1/decisions";
             "question_types": Array<"noul" | "choice" | "score">;

package/dist/index.d.ts

@@ -85,7 +85,7 @@ export interface AndroidOperation {
 }
 export interface AndroidActivity {
     sessionId: string;
-    username: "larry" | "misa";
+    username: string;
     ownerId?: string;
     status: AndroidStatus;
     action?: string;
@@ -313,6 +313,17 @@ export type UseCaseCatalog<T extends Record<string, UseCaseDeclaration>> = {
     /** Idempotent get-or-create for every use-case. Safe to call on boot. */
     ensure: () => Promise<void>;
 };
+export interface WaitForReadyOptions {
+    /** Give up after this long. Default 90 s. */
+    timeoutMs?: number;
+    /** Called before each backoff while the service is unreachable (log at info). */
+    onWait?: (info: {
+        attempt: number;
+        elapsedMs: number;
+        error: AgentLuError;
+    }) => void;
+    signal?: AbortSignal;
+}
 export interface RunOptions {
     backend?: Backend;
     agent?: string;
@@ -590,7 +601,7 @@ export declare class AgentLu {
     /**
      * Agent tier: a profile, tool families, threads and background runs. The
      * default agent is `api` (no persona - `instructions` are the system prompt);
-     * pin `fast`/`research`/... or an app-owned `<app>/<name>` id when needed.
+     * pin `fast`/`thorough`/... or an app-owned `<app>/<name>` id when needed.
      */
     readonly agent: AgentTierApi;
     /** Build a direct-tier run body from a short-form `llm.*` request. */
@@ -666,6 +677,14 @@ export declare class AgentLu {
     models(): Promise<unknown>;
     tools(): Promise<unknown>;
     health(): Promise<unknown>;
+    /**
+     * Wait until the service answers `/health`, retrying while it is unreachable
+     * (offline, 502/503/504, timeout) with jittered backoff. Resolves `true` once
+     * it answers and `false` at the deadline or on abort; never throws. Call it
+     * on boot before `ensure()`/`register()` so an app started alongside agentlu
+     * waits quietly instead of warning on the first ECONNREFUSED.
+     */
+    waitForReady(opts?: WaitForReadyOptions): Promise<boolean>;
     private request;
     private raw;
     private rawOnce;

package/dist/index.js

@@ -431,7 +431,7 @@ export class AgentLu {
     /**
      * Agent tier: a profile, tool families, threads and background runs. The
      * default agent is `api` (no persona - `instructions` are the system prompt);
-     * pin `fast`/`research`/... or an app-owned `<app>/<name>` id when needed.
+     * pin `fast`/`thorough`/... or an app-owned `<app>/<name>` id when needed.
      */
     agent = {
         run: (opts) => this.run(withAgentTierDefault(opts)),
@@ -768,6 +768,44 @@ export class AgentLu {
     async health() {
         return this.request("GET", "/health", undefined, { auth: false });
     }
+    /**
+     * Wait until the service answers `/health`, retrying while it is unreachable
+     * (offline, 502/503/504, timeout) with jittered backoff. Resolves `true` once
+     * it answers and `false` at the deadline or on abort; never throws. Call it
+     * on boot before `ensure()`/`register()` so an app started alongside agentlu
+     * waits quietly instead of warning on the first ECONNREFUSED.
+     */
+    async waitForReady(opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 90_000;
+        const start = Date.now();
+        for (let attempt = 1;; attempt++) {
+            if (opts.signal?.aborted)
+                return false;
+            try {
+                await this.request("GET", "/health", undefined, {
+                    auth: false,
+                    maxAttempts: 1,
+                    timeoutMs: 5_000,
+                    signal: opts.signal,
+                });
+                return true;
+            }
+            catch (e) {
+                if (opts.signal?.aborted)
+                    return false;
+                const err = e instanceof AgentLuError ? e : null;
+                // Any other answer (401, 404, ...) means the server is up.
+                if (!err || (err.kind !== "unavailable" && err.kind !== "timeout"))
+                    return true;
+                const elapsedMs = Date.now() - start;
+                if (elapsedMs >= timeoutMs)
+                    return false;
+                opts.onWait?.({ attempt, elapsedMs, error: err });
+                const delay = Math.min(5_000, 500 * 2 ** (attempt - 1)) * (0.75 + Math.random() * 0.5);
+                await sleep(Math.min(delay, timeoutMs - elapsedMs));
+            }
+        }
+    }
     async request(method, path, body, opts) {
         const res = await this.raw(method, path, body, opts);
         if (res.status === 204)

package/package.json

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