@betterlu/agentlu 1.9.0 → 1.10.0

package/README.md

@@ -341,3 +341,21 @@ if (response.agentlu?.browser?.status === "needs_human") {
 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.
+
+### Household signals (Herald)
+
+Apps should send structured facts to Herald, not post directly to the ChatLu
+family room through notif. Herald decides whether/when/how to share them.
+
+```ts
+const alu = new AgentLu({ apiKey: "alu_your_client_key" });
+const signal = await alu.household.signal({
+  source: "mealu", kind: "milestone", title: "A household milestone",
+  facts: { count: 3 }, urgency: "today", dedupeKey: "milestone-2026-11-08",
+});
+```
+
+`WireHouseholdSignalInput` → `Promise<WireHouseholdSignalResult>` (`id`, `status`,
+`deduped`). Facts are data, never instructions; urgency `now` requests a batched
+review, not guaranteed delivery. See [Household signals](../../docs/household-signals.md)
+for limits, expiry, dedupe and editorial semantics.

package/dist/generated.d.ts

@@ -8,6 +8,21 @@
  * contract. They describe the bytes on the wire (snake_case); the SDK's own
  * types are the ergonomic view over them.
  */
+export interface WireHouseholdSignalInput {
+    "source": string;
+    "kind": string;
+    "title": string;
+    "facts": Record<string, unknown>;
+    "urgency"?: "fyi" | "today" | "now";
+    "dedupeKey": string;
+    "occurredAt"?: string;
+    "expiresAt"?: string;
+}
+export interface WireHouseholdSignalResult {
+    "id": string;
+    "status": "pending" | "held" | "posted" | "folded" | "dropped" | "expired" | "failed";
+    "deduped": boolean;
+}
 export interface WireCreateResponse {
     /** Execution backend. */
     "backend"?: "pi";
@@ -71,7 +86,7 @@ export interface WireCreateResponse {
     "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. `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";
+    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "roleplay" | "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";
@@ -149,8 +164,9 @@ 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" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "storylu" | "google-research" | "google-image" | "android" | "research";
+        "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "roleplay" | "storylu" | "google-research" | "google-image" | "android" | "research";
         "model"?: string;
+        "modelRoute"?: "chat.quick" | "chat.household" | "chat.deep" | "chat.code" | "device" | "background.digest" | "utility" | "memory.extract" | "memory.judge" | "memory.consolidate";
         "instructions"?: string;
         "temperature"?: number;
         "store"?: boolean;
@@ -200,9 +216,11 @@ export interface WireRegisterClientRequest {
 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. `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";
+    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "roleplay" | "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;
+    /** Task route whose pool order and effort apply to automatic model selection. Mutually exclusive with model. Explicit request models, builtin chat agents, and agent model pins win; app-owned and api agents inherit the client route. */
+    "modelRoute"?: "chat.quick" | "chat.household" | "chat.deep" | "chat.code" | "device" | "background.digest" | "utility" | "memory.extract" | "memory.judge" | "memory.consolidate";
     /** System prompt for every run of this client. */
     "instructions"?: string;
     "temperature"?: number;
@@ -263,7 +281,7 @@ export interface WireAppAgentDeclaration {
 }
 export interface WireCreateThreadRequest {
     "title"?: string;
-    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom" | "research" | string;
+    "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom" | "research" | string;
     "model"?: string;
     "person"?: string | null;
     "owner"?: "client" | "person";
@@ -299,7 +317,7 @@ export interface WireResponse {
     "created_at": number;
     "status": "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
     "backend": "pi";
-    "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
+    "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom";
     "model": string;
     "conversation"?: {
         "id": string;
@@ -369,6 +387,7 @@ export interface WireResponse {
         "thread_id"?: string | null;
         "retries"?: number;
         "effective_model"?: string | null;
+        "model_route"?: "chat.quick" | "chat.household" | "chat.deep" | "chat.code" | "device" | "background.digest" | "utility" | "memory.extract" | "memory.judge" | "memory.consolidate";
         "service_tier"?: "standard" | "priority";
         "execution_path"?: string | null;
         "queue_wait_ms"?: number | null;
@@ -411,6 +430,8 @@ export interface WireResponse {
         "android"?: {
             "sessionId"?: string;
             "username"?: string;
+            "device"?: string;
+            "deviceName"?: string;
             "ownerId"?: string;
             "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
             "action"?: string;
@@ -486,7 +507,7 @@ export interface WireThread {
     "created_at": number;
     "updated_at": number;
     "title": string;
-    "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
+    "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom";
     "model": string | null;
     /** "api" for threads created through /v1; "chat" when a human started it. */
     "origin": string;
@@ -525,8 +546,9 @@ export interface WireClient {
     "allow_person_threads"?: boolean;
     "defaults"?: {
         "backend"?: "pi";
-        "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";
+        "agent"?: "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom" | "direct" | string | "mealu" | "nestlu" | "kitchen" | "waterlu" | "money" | "swarm" | "stage" | "roleplay" | "storylu" | "google-research" | "google-image" | "android" | "research";
         "model"?: string;
+        "modelRoute"?: "chat.quick" | "chat.household" | "chat.deep" | "chat.code" | "device" | "background.digest" | "utility" | "memory.extract" | "memory.judge" | "memory.consolidate";
         "instructions"?: string;
         "temperature"?: number;
         "store"?: boolean;
@@ -650,7 +672,7 @@ export interface WireResponseList {
         "created_at": number;
         "status": "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
         "backend": "pi";
-        "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
+        "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom";
         "model": string;
         "conversation"?: {
             "id": string;
@@ -715,6 +737,7 @@ export interface WireResponseList {
             "thread_id"?: string | null;
             "retries"?: number;
             "effective_model"?: string | null;
+            "model_route"?: "chat.quick" | "chat.household" | "chat.deep" | "chat.code" | "device" | "background.digest" | "utility" | "memory.extract" | "memory.judge" | "memory.consolidate";
             "service_tier"?: "standard" | "priority";
             "execution_path"?: string | null;
             "queue_wait_ms"?: number | null;
@@ -757,6 +780,8 @@ export interface WireResponseList {
             "android"?: {
                 "sessionId"?: string;
                 "username"?: string;
+                "device"?: string;
+                "deviceName"?: string;
                 "ownerId"?: string;
                 "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
                 "action"?: string;
@@ -782,7 +807,7 @@ export interface WireThreadList {
         "created_at": number;
         "updated_at": number;
         "title": string;
-        "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "cradle" | "roleplay" | "custom";
+        "agent": "auto" | "fast" | "thorough" | "assistant" | "code" | "google" | "image" | "api" | "digest" | "herald" | "cradle" | "custom";
         "model": string | null;
         "origin": string;
         "end_user"?: string | null;

package/dist/index.d.ts

@@ -24,8 +24,8 @@
  * Wire types generated from the server's zod contract are re-exported here as
  * `Wire*` types (see `generated.ts`, regenerate with `npm run gen:contract`).
  */
-import type { WireAppAgentDeclaration, WireClientDefaults, WireUseCaseProfile } from "./generated.js";
-export type { WireAppAgentDeclaration, WireAgentInfo, WireChatCompletion, WireChatCompletionRequest, WireClient, WireClientDefaults, WireCreateDecision, WireCreateResponse, WireCreateThreadRequest, WireDecision, WireError, WireFile, WireModelInfo, WireRegisterClientRequest, WireResponse, WireStreamEvent, WireThread, WireThreadMessage, WireToolInfo, WireUseCaseProfile, } from "./generated.js";
+import type { WireHouseholdSignalInput, WireHouseholdSignalResult, WireAppAgentDeclaration, WireClientDefaults, WireUseCaseProfile } from "./generated.js";
+export type { WireHouseholdSignalInput, WireHouseholdSignalResult, WireAppAgentDeclaration, WireAgentInfo, WireChatCompletion, WireChatCompletionRequest, WireClient, WireClientDefaults, WireCreateDecision, WireCreateResponse, WireCreateThreadRequest, WireDecision, WireError, WireFile, WireModelInfo, WireRegisterClientRequest, WireResponse, WireStreamEvent, WireThread, WireThreadMessage, WireToolInfo, WireUseCaseProfile, } from "./generated.js";
 export declare const DEFAULT_BASE_URL = "http://localhost:8912/v1";
 /**
  * Accept an origin (`http://host:8912`) or a `/v1` base and normalize to the
@@ -86,6 +86,8 @@ export interface AndroidOperation {
 export interface AndroidActivity {
     sessionId: string;
     username: string;
+    device?: string;
+    deviceName?: string;
     ownerId?: string;
     status: AndroidStatus;
     action?: string;
@@ -183,6 +185,16 @@ export interface DecisionOptions {
     /** Caller cancellation, combined with `timeoutMs` when both are set. */
     signal?: AbortSignal;
 }
+/** Per-request transport knobs threaded through `request()` / `raw()`. */
+interface RequestOptions {
+    auth?: boolean;
+    apiKey?: string;
+    timeoutMs?: number;
+    maxAttempts?: number;
+    signal?: AbortSignal;
+    /** Extra request headers (e.g. a caller-supplied Idempotency-Key). */
+    headers?: Record<string, string>;
+}
 export interface DecisionObject {
     id: string;
     object: "decision";
@@ -656,6 +668,9 @@ export declare class AgentLu {
         delete: (id: string) => Promise<unknown>;
         messages: (id: string) => Promise<unknown>;
     };
+    readonly household: {
+        signal: (input: WireHouseholdSignalInput, opts?: RequestOptions) => Promise<WireHouseholdSignalResult>;
+    };
     /**
      * Decision model (System One / Jev): typed questions in, calibrated
      * probabilities out, ~100-500ms. Sync only - there is no stream or poll.

package/dist/index.js

@@ -728,6 +728,9 @@ export class AgentLu {
         delete: (id) => this.request("DELETE", `/threads/${encodeURIComponent(id)}`),
         messages: (id) => this.request("GET", `/threads/${encodeURIComponent(id)}/messages`),
     };
+    household = {
+        signal: (input, opts) => this.request("POST", "/household/signals", input, opts),
+    };
     /**
      * Decision model (System One / Jev): typed questions in, calibrated
      * probabilities out, ~100-500ms. Sync only - there is no stream or poll.

package/package.json

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