@betterlu/agentlu 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,878 @@
1
+ /**
2
+ * AUTO-GENERATED by scripts/gen-contract.ts - do not edit.
3
+ * Source of truth: src/shared/api-schema.ts (+ src/server/api/schema.ts).
4
+ * Regenerate: `npm run gen:contract`; CI drift check: `npm run check:contract`.
5
+ */
6
+ /**
7
+ * Wire types for the agentlu `/v1` service API, generated from the zod
8
+ * contract. They describe the bytes on the wire (snake_case); the SDK's own
9
+ * types are the ergonomic view over them.
10
+ */
11
+ export interface WireCreateResponse {
12
+ /** Execution backend. */
13
+ "backend"?: "pi";
14
+ /** 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. */
15
+ "model"?: string;
16
+ "input"?: string | Array<{
17
+ "role": "user" | "assistant" | "system" | "developer";
18
+ "content": string | Array<{
19
+ "type": "input_text";
20
+ "text": string;
21
+ } | {
22
+ "type": "input_image";
23
+ "file_id"?: string;
24
+ "image_url"?: string;
25
+ "detail"?: "auto" | "low" | "high";
26
+ } | {
27
+ "type": "input_video";
28
+ "file_id"?: string;
29
+ "video_url"?: string;
30
+ } | {
31
+ "type": "input_file";
32
+ "file_id"?: string;
33
+ "filename"?: string;
34
+ }>;
35
+ }>;
36
+ /** System message for this run. */
37
+ "instructions"?: string;
38
+ "stream"?: boolean;
39
+ /** `false` requests ephemeral execution. Eligible text-only, tool-less Pi and Google runs avoid a Session; attachments, tools, and continuations still use a Session when required. The ApiResponse remains available to the console, but its request/output bodies are purged after 24 hours (rows created with an `Idempotency-Key` keep them, so a retry can still replay the answer). */
40
+ "store"?: boolean;
41
+ "background"?: boolean;
42
+ /** Continue the thread that produced this response. */
43
+ "previous_response_id"?: string;
44
+ "conversation"?: string | {
45
+ "id": string;
46
+ };
47
+ /** Optional and discouraged. Omit it to use the model's own output limit; values here are applied verbatim. If the limit is reached, the HTTP 200 Response has status `incomplete`, reason `max_output_tokens`, and may retain partial output. */
48
+ "max_output_tokens"?: number;
49
+ "temperature"?: number;
50
+ "text"?: {
51
+ "format"?: {
52
+ "type": "text";
53
+ } | {
54
+ "type": "json_schema";
55
+ "name": string;
56
+ "schema": Record<string, unknown>;
57
+ "strict"?: boolean;
58
+ "description"?: string;
59
+ };
60
+ };
61
+ /** Closed tool-family allowlist (`web_search`, `fetch_content`, `hublu`, `memory`, `image`, `browser`, `android`), intersected with what the selected agent supports. Function schemas are rejected; the machine-only `api` agent also accepts `{ type: "mcp", url }`. */
62
+ "tools"?: Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android" | {
63
+ "type": "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
64
+ "allowed_tools"?: string[];
65
+ } | {
66
+ "type": "mcp";
67
+ "url": string;
68
+ "allowed_tools"?: string[];
69
+ }>;
70
+ "tool_choice"?: "auto" | "none" | "required";
71
+ "metadata"?: Record<string, string>;
72
+ "include"?: Array<"reasoning" | "rounds" | "subagents" | "artifacts">;
73
+ /** 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. */
74
+ "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;
75
+ /** 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. */
76
+ "reasoning"?: {
77
+ "effort"?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
78
+ };
79
+ /** Wall clock for this run. Default: the use-case tier's (45s instant / 180s standard / 600s deep). */
80
+ "timeout_ms"?: number;
81
+ /** Provider attempts for this run (1 = none). Bounds model-chain fallbacks. Default: the use-case tier's (instant 1, standard 2, deep 3) when the client declares a profile; without one the run keeps the pre-tier budget (the direct tier walks its whole chain, the agent tier does not fall back). */
82
+ "attempts"?: number;
83
+ "title"?: string;
84
+ "person"?: string | null;
85
+ /** 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. */
86
+ "owner"?: "client" | "person";
87
+ "project"?: string;
88
+ /** Opaque caller-side identity (one of your users or devices). Stored on the response and, for stored runs, its thread; filter with `?end_user=`. */
89
+ "end_user"?: string;
90
+ }
91
+ export interface WireChatCompletionRequest {
92
+ /** An agentlu model id (GET /v1/models) or `direct`. Omit it to let the model chain pick. An unknown id is HTTP 400 `unknown_model`. */
93
+ "model"?: string;
94
+ /** system/developer messages become the run's instructions; the rest is folded into the prompt with role tags. Tool messages are rejected (unsupported_tool): the direct tier runs no tools. */
95
+ "messages": Array<{
96
+ "role": "system" | "developer" | "user" | "assistant" | "tool";
97
+ "content"?: string | Array<{
98
+ "type": "text";
99
+ "text": string;
100
+ } | {
101
+ "type": "image_url";
102
+ "image_url": string | {
103
+ "url": string;
104
+ "detail"?: "auto" | "low" | "high";
105
+ };
106
+ }> | null;
107
+ "name"?: string;
108
+ }>;
109
+ "temperature"?: number;
110
+ "max_tokens"?: number;
111
+ /** Wins over `max_tokens`. */
112
+ "max_completion_tokens"?: number;
113
+ "response_format"?: {
114
+ "type": "text";
115
+ } | {
116
+ "type": "json_object";
117
+ } | {
118
+ "type": "json_schema";
119
+ "json_schema": {
120
+ "name": string;
121
+ "schema": Record<string, unknown>;
122
+ "strict"?: boolean;
123
+ "description"?: string;
124
+ };
125
+ };
126
+ "stream"?: boolean;
127
+ "stream_options"?: {
128
+ "include_usage"?: boolean;
129
+ };
130
+ /** Stored as `end_user`. */
131
+ "user"?: string;
132
+ "n"?: number;
133
+ "seed"?: number;
134
+ "stop"?: string | string[];
135
+ "presence_penalty"?: number;
136
+ "frequency_penalty"?: number;
137
+ "attempts"?: number;
138
+ }
139
+ export interface WireRegisterClientRequest {
140
+ /** Lowercase slug, 2-64 chars */
141
+ "name": string;
142
+ /** Household member for hublu tool calls (larry|misa). Optional. */
143
+ "person"?: string | null;
144
+ /** Persistent system-prompt addition for this client. */
145
+ "instructions"?: string | null;
146
+ /** App this client belongs to, for grouping in the console and `/stats`, and the namespace of its app-owned agents. Slugified to the address grammar (`NestLu` -> `nestlu`, `my app` -> `my-app`); must contain at least one letter or digit. Defaults to the part of `name` before the first `-` (`mealu-enrich` -> `mealu`). */
147
+ "app"?: string;
148
+ /** Allow this client to send `owner: "person"` threads, which appear in a human's sidebar. Default false; the request is otherwise rejected with HTTP 403 `person_threads_not_allowed`. */
149
+ "allow_person_threads"?: boolean;
150
+ /** 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. */
151
+ "defaults"?: {
152
+ "backend"?: "pi";
153
+ "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;
154
+ "model"?: string;
155
+ "instructions"?: string;
156
+ "temperature"?: number;
157
+ "store"?: boolean;
158
+ "reasoning"?: {
159
+ "effort": "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
160
+ };
161
+ "text"?: {
162
+ "format"?: {
163
+ "type": "text";
164
+ } | {
165
+ "type": "json_schema";
166
+ "name": string;
167
+ "schema": Record<string, unknown>;
168
+ "strict"?: boolean;
169
+ "description"?: string;
170
+ };
171
+ };
172
+ "tools"?: Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android" | {
173
+ "type": "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
174
+ "allowed_tools"?: string[];
175
+ } | {
176
+ "type": "mcp";
177
+ "url": string;
178
+ "allowed_tools"?: string[];
179
+ }>;
180
+ "timeoutMs"?: number;
181
+ "maxOutputTokens"?: number;
182
+ "attempts"?: number;
183
+ };
184
+ /** High-level declaration of what this client is for. The model-chain router uses it to pick (and fall back between) models when a request omits `model`, to decide when MiniMax's paid priority admission tier is acceptable, and to seed the tier defaults (timeout, output cap, attempts, reasoning). All fields optional; an explicitly pinned `model` bypasses routing entirely. Tier defaults apply only when `priority` is declared - an unset profile keeps the pre-tier run envelope. */
185
+ "use_case_profile"?: {
186
+ "inputModalities"?: Array<"text" | "image" | "video">;
187
+ "outputKind"?: "text" | "json_schema";
188
+ "priorityTier"?: "never" | "retry" | "first" | "always";
189
+ "priority"?: "instant" | "standard" | "deep";
190
+ };
191
+ /** App-owned agents for this client's app. Sending the field replaces the agents this client previously declared; `[]` clears them; omitting it leaves them untouched. Callable as `agent: "<app>/<name>"` by every client of the same app. A client may declare agents for its own app namespace only (`<app>` or `<app>-<use-case>` by name convention); anything else is refused with a `warnings` entry on the response and the registration still succeeds. */
192
+ "agents"?: Array<{
193
+ "name": string;
194
+ "instructions": string;
195
+ "tools"?: Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android">;
196
+ "model"?: string;
197
+ "temperature"?: number;
198
+ }>;
199
+ }
200
+ /** 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. */
201
+ export interface WireClientDefaults {
202
+ "backend"?: "pi";
203
+ /** 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. */
204
+ "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;
205
+ /** ModelConfig id (GET /v1/models). Stock clients may also use an agent name here; prefer explicit `agent` for machine calls. */
206
+ "model"?: string;
207
+ /** System prompt for every run of this client. */
208
+ "instructions"?: string;
209
+ "temperature"?: number;
210
+ /** Whether runs are stored. `false` is sessionless only for eligible text-only, tool-less runs; attachments, tools, and continuations still use a Session when required. */
211
+ "store"?: boolean;
212
+ /** Default thinking level. */
213
+ "reasoning"?: {
214
+ "effort": "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
215
+ };
216
+ /** Whole-field text-format default. A request-level `text` replaces this value rather than deep-merging it. */
217
+ "text"?: {
218
+ "format"?: {
219
+ "type": "text";
220
+ } | {
221
+ "type": "json_schema";
222
+ "name": string;
223
+ "schema": Record<string, unknown>;
224
+ "strict"?: boolean;
225
+ "description"?: string;
226
+ };
227
+ };
228
+ /** Closed-allowlist tool specs, same shape as the request `tools` field. A registered default never vetoes a tier/agent incompatibility: the direct tier drops it, and an incompatible agent drops it with a warning. */
229
+ "tools"?: Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android" | {
230
+ "type": "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
231
+ "allowed_tools"?: string[];
232
+ } | {
233
+ "type": "mcp";
234
+ "url": string;
235
+ "allowed_tools"?: string[];
236
+ }>;
237
+ "timeoutMs"?: number;
238
+ /** Default output cap when the request omits `max_output_tokens`. The use-case tier supplies one when this is unset (instant 2048, deep 8192, standard none); requests always win. Honored for defaults written after this release: a value stored earlier stays inert until the app re-declares its defaults (or the console edits them), so a re-enable can never silently cap runs that used to complete. */
239
+ "maxOutputTokens"?: number;
240
+ /** Provider attempts per run (1 = none). Bounds model-chain fallbacks, and is the background queue's retry budget. Defaults to the tier's (instant 1, standard 2, deep 3) when `use_case_profile.priority` is declared; without one the run keeps the pre-tier budget. */
241
+ "attempts"?: number;
242
+ }
243
+ /** High-level declaration of what this client is for. The model-chain router uses it to pick (and fall back between) models when a request omits `model`, to decide when MiniMax's paid priority admission tier is acceptable, and to seed the tier defaults (timeout, output cap, attempts, reasoning). All fields optional; an explicitly pinned `model` bypasses routing entirely. Tier defaults apply only when `priority` is declared - an unset profile keeps the pre-tier run envelope. */
244
+ export interface WireUseCaseProfile {
245
+ /** Input types the use case may send. Default ["text"]. */
246
+ "inputModalities"?: Array<"text" | "image" | "video">;
247
+ /** Expected output kind. Default "text". */
248
+ "outputKind"?: "text" | "json_schema";
249
+ /** MiniMax priority admission consent (priority costs 1.5x standard): never | retry (standard first, priority only on a transient-failure retry) | first (priority on the first attempt) | always. */
250
+ "priorityTier"?: "never" | "retry" | "first" | "always";
251
+ /** Latency/thoroughness tier: instant (fast-class models first, 45s, 2k output, 1 attempt, thinking off for structured output), standard (3 minutes, no output cap, 2 attempts), deep (strongest models first, 10 minutes, 8k output, 3 attempts). Every value is a default; request fields win. Declaring it is what applies the tier: omit it and the client keeps the pre-tier envelope. */
252
+ "priority"?: "instant" | "standard" | "deep";
253
+ }
254
+ export interface WireAppAgentDeclaration {
255
+ /** Agent name; the callable id is `<app>/<name>`. */
256
+ "name": string;
257
+ /** Profile body for this agent (the app's system prompt). */
258
+ "instructions": string;
259
+ /** Tool families this agent may use. Must be families the machine `api` agent supports; the request can narrow but never widen them. */
260
+ "tools"?: Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android">;
261
+ /** Default model for this agent; a request-level `model` wins. */
262
+ "model"?: string;
263
+ "temperature"?: number;
264
+ }
265
+ export interface WireCreateThreadRequest {
266
+ "title"?: string;
267
+ "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";
268
+ "model"?: string;
269
+ "person"?: string | null;
270
+ "owner"?: "client" | "person";
271
+ "end_user"?: string;
272
+ "metadata"?: Record<string, string>;
273
+ }
274
+ export interface WireCreateDecision {
275
+ /** Unstructured input for the decision: a text state, or a JSON object (serialized upstream). Context is 32K tokens including the longest question. */
276
+ "state": string | Record<string, unknown>;
277
+ /** Named questions, answered in parallel in one pass. */
278
+ "questions": Record<string, {
279
+ "type": "noul";
280
+ "instructions": string;
281
+ "criteria"?: {
282
+ "true": string;
283
+ "false": string;
284
+ };
285
+ } | {
286
+ "type": "choice";
287
+ "instructions": string;
288
+ "criteria": Record<string, string>;
289
+ } | {
290
+ "type": "score";
291
+ "instructions": string;
292
+ "criteria": string[];
293
+ }>;
294
+ /** Decision model id (default: the configured `typesafe/jev`). */
295
+ "model"?: string;
296
+ }
297
+ export interface WireResponse {
298
+ "id": string;
299
+ "object": "response";
300
+ "created_at": number;
301
+ "status": "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
302
+ "backend": "pi";
303
+ "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";
304
+ "model": string;
305
+ "conversation"?: {
306
+ "id": string;
307
+ } | null;
308
+ "previous_response_id"?: string | null;
309
+ "output": Array<{
310
+ "type": "reasoning";
311
+ "id": string;
312
+ "summary": Array<{
313
+ "type": "summary_text";
314
+ "text": string;
315
+ }>;
316
+ } | {
317
+ "type": "function_call";
318
+ "id": string;
319
+ "call_id": string;
320
+ "name": string;
321
+ "arguments": string;
322
+ "status"?: "completed" | "incomplete";
323
+ "output"?: string;
324
+ [key: string]: unknown;
325
+ } | {
326
+ "type": "message";
327
+ "id": string;
328
+ "role": "assistant";
329
+ "status"?: "completed" | "incomplete";
330
+ "content": Array<{
331
+ "type": "output_text";
332
+ "text": string;
333
+ "annotations"?: Array<{
334
+ "type": "url_citation";
335
+ "url": string;
336
+ "title"?: string;
337
+ }>;
338
+ }>;
339
+ }>;
340
+ /** Concatenated candidate text. For structured calls, use `output_parsed` after checking `status` instead of parsing this field. */
341
+ "output_text": string;
342
+ /** Present when text.format was json_schema and a JSON value was extracted; strict mode also requires the final candidate to validate against the schema. */
343
+ "output_parsed"?: unknown;
344
+ /** Caller-side identity this run was sent for, when given. */
345
+ "end_user"?: string | null;
346
+ "usage"?: {
347
+ "input_tokens"?: number;
348
+ "output_tokens"?: number;
349
+ "total_tokens"?: number;
350
+ "thinking_tokens"?: number;
351
+ "cache_read_tokens"?: number;
352
+ "cache_write_tokens"?: number;
353
+ "input_tokens_details"?: {
354
+ "cached_tokens"?: number;
355
+ };
356
+ } | null;
357
+ /** Execution error body on an HTTP 200 failed/incomplete/cancelled Response. */
358
+ "error"?: {
359
+ "code": string;
360
+ "message": string;
361
+ "retryable": boolean;
362
+ } | null;
363
+ "incomplete_details"?: {
364
+ "reason": "max_output_tokens" | "timeout";
365
+ } | null;
366
+ "metadata"?: Record<string, string> | null;
367
+ /** agentlu extensions. `session_url` opens stored runs in the chat UI and is null when no Session was created; `effective_model` is the model that actually served the run when it differs from `model`; `service_tier` is the MiniMax admission tier actually requested for the winning attempt (absent when none); `browser` is the latest persistent BrowserLu activity; `android` is the latest persistent AndroidLu activity. */
368
+ "agentlu"?: {
369
+ "session_url"?: string | null;
370
+ "thread_id"?: string | null;
371
+ "retries"?: number;
372
+ "effective_model"?: string | null;
373
+ "service_tier"?: "standard" | "priority";
374
+ "execution_path"?: string | null;
375
+ "queue_wait_ms"?: number | null;
376
+ "execution_duration_ms"?: number | null;
377
+ "repair_attempts"?: number;
378
+ "provider_retries"?: number;
379
+ "usage_known"?: boolean;
380
+ "warnings"?: string[];
381
+ "rounds"?: unknown[];
382
+ "subagents"?: Array<{
383
+ "id": string;
384
+ "type": string;
385
+ "task"?: string;
386
+ "status"?: string;
387
+ }>;
388
+ "artifacts"?: Array<{
389
+ "id": string;
390
+ "name": string;
391
+ "type": string;
392
+ "url": string;
393
+ }>;
394
+ "browser"?: {
395
+ "sessionId"?: string;
396
+ "username"?: "larry" | "misa";
397
+ "ownerId"?: string;
398
+ "tabId"?: string;
399
+ "url"?: string;
400
+ "title"?: string;
401
+ "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted";
402
+ "action"?: string;
403
+ "reason"?: string;
404
+ "observationId"?: string;
405
+ "screenshots"?: Array<{
406
+ "id": string;
407
+ "createdAt": string;
408
+ "width": number;
409
+ "height": number;
410
+ }>;
411
+ };
412
+ "android"?: {
413
+ "sessionId"?: string;
414
+ "username"?: "larry" | "misa";
415
+ "ownerId"?: string;
416
+ "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
417
+ "action"?: string;
418
+ "reason"?: string;
419
+ "observationId"?: string;
420
+ "leaseId"?: string;
421
+ "readiness"?: "stopped" | "booting" | "ready" | "failed";
422
+ "control"?: "idle" | "agent" | "needs_human" | "human" | "reserved" | "interrupted";
423
+ "foregroundPackage"?: string;
424
+ "viewerPath"?: string;
425
+ "reservationExpiresAt"?: string;
426
+ };
427
+ };
428
+ }
429
+ export interface WireChatCompletion {
430
+ /** `chatcmpl-<id>` */
431
+ "id": string;
432
+ "object": "chat.completion";
433
+ "created": number;
434
+ "model": string;
435
+ "choices": Array<{
436
+ "index": number;
437
+ "message": {
438
+ "role": "assistant";
439
+ "content": string;
440
+ };
441
+ "finish_reason"?: "stop" | "length";
442
+ }>;
443
+ "usage"?: {
444
+ "prompt_tokens": number;
445
+ "completion_tokens": number;
446
+ "total_tokens": number;
447
+ [key: string]: unknown;
448
+ };
449
+ /** agentlu extension: `response_id` is the /v1/responses id for this run, `output_parsed` is the validated JSON for a structured `response_format`, `warnings` carries non-fatal degradations. */
450
+ "agentlu"?: {
451
+ "response_id"?: string;
452
+ "tier"?: "direct" | "agent";
453
+ "output_parsed"?: unknown;
454
+ "warnings"?: string[];
455
+ };
456
+ }
457
+ export interface WireDecision {
458
+ /** `dec_...` */
459
+ "id": string;
460
+ "object": "decision";
461
+ "created_at": number;
462
+ "model": string;
463
+ "answers": Record<string, {
464
+ "type": "noul";
465
+ "noul": number;
466
+ } | {
467
+ "type": "choice";
468
+ "choice": string;
469
+ "confidence": number;
470
+ "probabilities": Record<string, number>;
471
+ } | {
472
+ "type": "score";
473
+ "score": number;
474
+ "confidence": number;
475
+ "legend"?: Record<string, string>;
476
+ "probabilities": Record<string, number>;
477
+ }>;
478
+ "usage": {
479
+ "input_tokens": number;
480
+ "output_tokens": number;
481
+ "total_tokens": number;
482
+ } | null;
483
+ }
484
+ export interface WireThread {
485
+ "id": string;
486
+ "object": "thread";
487
+ "created_at": number;
488
+ "updated_at": number;
489
+ "title": string;
490
+ "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";
491
+ "model": string | null;
492
+ /** "api" for threads created through /v1; "chat" when a human started it. */
493
+ "origin": string;
494
+ "end_user"?: string | null;
495
+ "message_count"?: number;
496
+ "url": string;
497
+ }
498
+ export interface WireThreadMessage {
499
+ "id": string;
500
+ "role": string;
501
+ "content": string;
502
+ "created_at": number;
503
+ "reasoning"?: string | null;
504
+ "error"?: string | null;
505
+ "usage"?: {
506
+ "input_tokens"?: number;
507
+ "output_tokens"?: number;
508
+ "total_tokens"?: number;
509
+ "thinking_tokens"?: number;
510
+ "cache_read_tokens"?: number;
511
+ "cache_write_tokens"?: number;
512
+ "input_tokens_details"?: {
513
+ "cached_tokens"?: number;
514
+ };
515
+ } | null;
516
+ }
517
+ export interface WireClient {
518
+ "id": string;
519
+ "object": "client";
520
+ "name": string;
521
+ /** Plaintext key. Returned by register/rotate and shown in the console. */
522
+ "api_key"?: string;
523
+ "person"?: string | null;
524
+ "instructions"?: string | null;
525
+ "app"?: string | null;
526
+ "allow_person_threads"?: boolean;
527
+ "defaults"?: {
528
+ "backend"?: "pi";
529
+ "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;
530
+ "model"?: string;
531
+ "instructions"?: string;
532
+ "temperature"?: number;
533
+ "store"?: boolean;
534
+ "reasoning"?: {
535
+ "effort": "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
536
+ };
537
+ "text"?: {
538
+ "format"?: {
539
+ "type": "text";
540
+ } | {
541
+ "type": "json_schema";
542
+ "name": string;
543
+ "schema": Record<string, unknown>;
544
+ "strict"?: boolean;
545
+ "description"?: string;
546
+ };
547
+ };
548
+ "tools"?: Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android" | {
549
+ "type": "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
550
+ "allowed_tools"?: string[];
551
+ } | {
552
+ "type": "mcp";
553
+ "url": string;
554
+ "allowed_tools"?: string[];
555
+ }>;
556
+ "timeoutMs"?: number;
557
+ "maxOutputTokens"?: number;
558
+ "attempts"?: number;
559
+ } | null;
560
+ "use_case_profile"?: {
561
+ "inputModalities"?: Array<"text" | "image" | "video">;
562
+ "outputKind"?: "text" | "json_schema";
563
+ "priorityTier"?: "never" | "retry" | "first" | "always";
564
+ "priority"?: "instant" | "standard" | "deep";
565
+ } | null;
566
+ /** App-owned agent ids (`<app>/<name>`) this client declared. The stored set belongs to the client's app. */
567
+ "agents"?: string[];
568
+ /** Declared values the server refused without failing the registration: an `agents` declaration outside the client's own app namespace (a client owns `<app>` or `<app>-*` by name convention), or one whose address can never parse. The stored agents are left untouched. */
569
+ "warnings"?: string[];
570
+ "kind": string;
571
+ "created_at": number;
572
+ "last_seen_at"?: number | null;
573
+ }
574
+ export interface WireFile {
575
+ "id": string;
576
+ "object": "file";
577
+ "filename": string;
578
+ "bytes": number;
579
+ "mime_type": string;
580
+ "kind": string;
581
+ "width"?: number;
582
+ "height"?: number;
583
+ "created_at": number;
584
+ /** True once a run has claimed the file (it belongs to a thread). */
585
+ "attached": boolean;
586
+ }
587
+ export interface WireError {
588
+ "error": {
589
+ "code": string;
590
+ "message": string;
591
+ "retryable": boolean;
592
+ };
593
+ }
594
+ export interface WireAgentInfo {
595
+ "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";
596
+ "object": "agent";
597
+ "profile": string;
598
+ "description": string;
599
+ "tools": string[];
600
+ /** Tool families a /v1 caller may request for this agent. */
601
+ "available_tools": Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android">;
602
+ "supports_images": boolean;
603
+ /** Long-running agents are best used with `background: true`. */
604
+ "long_running": boolean;
605
+ /** Runtime that serves this agent. */
606
+ "harness": "pi" | "google";
607
+ }
608
+ export interface WireModelInfo {
609
+ "id": string;
610
+ "object": "model";
611
+ "owned_by": string;
612
+ "label": string;
613
+ "input": Array<"text" | "image" | "video">;
614
+ "available": boolean;
615
+ /** True for the default entry within this model's harness. */
616
+ "default": boolean;
617
+ /** Runtime that serves this model. */
618
+ "harness": "pi" | "google" | "systemone";
619
+ /** Present on decision models: how to call them. */
620
+ "decision"?: {
621
+ "endpoint": "/v1/decisions";
622
+ "question_types": Array<"noul" | "choice" | "score">;
623
+ };
624
+ }
625
+ export interface WireToolInfo {
626
+ "type": "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
627
+ "object": "tool";
628
+ "description": string;
629
+ /** Concrete tool names this family expands to. */
630
+ "expands_to": string[];
631
+ /** False when the backing service (e.g. hublu) is unreachable right now. */
632
+ "available": boolean;
633
+ }
634
+ export interface WireStreamEvent {
635
+ "type": string;
636
+ "sequence_number"?: number;
637
+ /** Incremental text on `response.output_text.delta`. */
638
+ "delta"?: string;
639
+ [key: string]: unknown;
640
+ }
641
+ export interface WireResponseList {
642
+ "object": "list";
643
+ "data": Array<{
644
+ "id": string;
645
+ "object": "response";
646
+ "created_at": number;
647
+ "status": "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "cancelled";
648
+ "backend": "pi";
649
+ "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";
650
+ "model": string;
651
+ "conversation"?: {
652
+ "id": string;
653
+ } | null;
654
+ "previous_response_id"?: string | null;
655
+ "output": Array<{
656
+ "type": "reasoning";
657
+ "id": string;
658
+ "summary": Array<{
659
+ "type": "summary_text";
660
+ "text": string;
661
+ }>;
662
+ } | {
663
+ "type": "function_call";
664
+ "id": string;
665
+ "call_id": string;
666
+ "name": string;
667
+ "arguments": string;
668
+ "status"?: "completed" | "incomplete";
669
+ "output"?: string;
670
+ [key: string]: unknown;
671
+ } | {
672
+ "type": "message";
673
+ "id": string;
674
+ "role": "assistant";
675
+ "status"?: "completed" | "incomplete";
676
+ "content": Array<{
677
+ "type": "output_text";
678
+ "text": string;
679
+ "annotations"?: Array<{
680
+ "type": "url_citation";
681
+ "url": string;
682
+ "title"?: string;
683
+ }>;
684
+ }>;
685
+ }>;
686
+ "output_text": string;
687
+ "output_parsed"?: unknown;
688
+ "end_user"?: string | null;
689
+ "usage"?: {
690
+ "input_tokens"?: number;
691
+ "output_tokens"?: number;
692
+ "total_tokens"?: number;
693
+ "thinking_tokens"?: number;
694
+ "cache_read_tokens"?: number;
695
+ "cache_write_tokens"?: number;
696
+ "input_tokens_details"?: {
697
+ "cached_tokens"?: number;
698
+ };
699
+ } | null;
700
+ "error"?: {
701
+ "code": string;
702
+ "message": string;
703
+ "retryable": boolean;
704
+ } | null;
705
+ "incomplete_details"?: {
706
+ "reason": "max_output_tokens" | "timeout";
707
+ } | null;
708
+ "metadata"?: Record<string, string> | null;
709
+ "agentlu"?: {
710
+ "session_url"?: string | null;
711
+ "thread_id"?: string | null;
712
+ "retries"?: number;
713
+ "effective_model"?: string | null;
714
+ "service_tier"?: "standard" | "priority";
715
+ "execution_path"?: string | null;
716
+ "queue_wait_ms"?: number | null;
717
+ "execution_duration_ms"?: number | null;
718
+ "repair_attempts"?: number;
719
+ "provider_retries"?: number;
720
+ "usage_known"?: boolean;
721
+ "warnings"?: string[];
722
+ "rounds"?: unknown[];
723
+ "subagents"?: Array<{
724
+ "id": string;
725
+ "type": string;
726
+ "task"?: string;
727
+ "status"?: string;
728
+ }>;
729
+ "artifacts"?: Array<{
730
+ "id": string;
731
+ "name": string;
732
+ "type": string;
733
+ "url": string;
734
+ }>;
735
+ "browser"?: {
736
+ "sessionId"?: string;
737
+ "username"?: "larry" | "misa";
738
+ "ownerId"?: string;
739
+ "tabId"?: string;
740
+ "url"?: string;
741
+ "title"?: string;
742
+ "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted";
743
+ "action"?: string;
744
+ "reason"?: string;
745
+ "observationId"?: string;
746
+ "screenshots"?: Array<{
747
+ "id": string;
748
+ "createdAt": string;
749
+ "width": number;
750
+ "height": number;
751
+ }>;
752
+ };
753
+ "android"?: {
754
+ "sessionId"?: string;
755
+ "username"?: "larry" | "misa";
756
+ "ownerId"?: string;
757
+ "status": "active" | "needs_human" | "human_control" | "idle" | "closed" | "interrupted" | "reserved";
758
+ "action"?: string;
759
+ "reason"?: string;
760
+ "observationId"?: string;
761
+ "leaseId"?: string;
762
+ "readiness"?: "stopped" | "booting" | "ready" | "failed";
763
+ "control"?: "idle" | "agent" | "needs_human" | "human" | "reserved" | "interrupted";
764
+ "foregroundPackage"?: string;
765
+ "viewerPath"?: string;
766
+ "reservationExpiresAt"?: string;
767
+ };
768
+ };
769
+ }>;
770
+ /** Opaque keyset cursor; null on the last page. */
771
+ "next_cursor": string | null;
772
+ }
773
+ export interface WireThreadList {
774
+ "object": "list";
775
+ "data": Array<{
776
+ "id": string;
777
+ "object": "thread";
778
+ "created_at": number;
779
+ "updated_at": number;
780
+ "title": string;
781
+ "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";
782
+ "model": string | null;
783
+ "origin": string;
784
+ "end_user"?: string | null;
785
+ "message_count"?: number;
786
+ "url": string;
787
+ }>;
788
+ /** Opaque keyset cursor; null on the last page. */
789
+ "next_cursor": string | null;
790
+ }
791
+ export interface WireThreadMessageList {
792
+ "object": "list";
793
+ "data": Array<{
794
+ "id": string;
795
+ "role": string;
796
+ "content": string;
797
+ "created_at": number;
798
+ "reasoning"?: string | null;
799
+ "error"?: string | null;
800
+ "usage"?: {
801
+ "input_tokens"?: number;
802
+ "output_tokens"?: number;
803
+ "total_tokens"?: number;
804
+ "thinking_tokens"?: number;
805
+ "cache_read_tokens"?: number;
806
+ "cache_write_tokens"?: number;
807
+ "input_tokens_details"?: {
808
+ "cached_tokens"?: number;
809
+ };
810
+ } | null;
811
+ }>;
812
+ /** Opaque keyset cursor; null on the last page. */
813
+ "next_cursor": string | null;
814
+ }
815
+ export interface WireFileList {
816
+ "object": "list";
817
+ "data": Array<{
818
+ "id": string;
819
+ "object": "file";
820
+ "filename": string;
821
+ "bytes": number;
822
+ "mime_type": string;
823
+ "kind": string;
824
+ "width"?: number;
825
+ "height"?: number;
826
+ "created_at": number;
827
+ "attached": boolean;
828
+ }>;
829
+ /** Opaque keyset cursor; null on the last page. */
830
+ "next_cursor": string | null;
831
+ }
832
+ export interface WireAgentList {
833
+ "object": "list";
834
+ "data": Array<{
835
+ "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";
836
+ "object": "agent";
837
+ "profile": string;
838
+ "description": string;
839
+ "tools": string[];
840
+ "available_tools": Array<"web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android">;
841
+ "supports_images": boolean;
842
+ "long_running": boolean;
843
+ "harness": "pi" | "google";
844
+ }>;
845
+ /** Opaque keyset cursor; null on the last page. */
846
+ "next_cursor": string | null;
847
+ }
848
+ export interface WireModelList {
849
+ "object": "list";
850
+ "data": Array<{
851
+ "id": string;
852
+ "object": "model";
853
+ "owned_by": string;
854
+ "label": string;
855
+ "input": Array<"text" | "image" | "video">;
856
+ "available": boolean;
857
+ "default": boolean;
858
+ "harness": "pi" | "google" | "systemone";
859
+ "decision"?: {
860
+ "endpoint": "/v1/decisions";
861
+ "question_types": Array<"noul" | "choice" | "score">;
862
+ };
863
+ }>;
864
+ /** Opaque keyset cursor; null on the last page. */
865
+ "next_cursor": string | null;
866
+ }
867
+ export interface WireToolList {
868
+ "object": "list";
869
+ "data": Array<{
870
+ "type": "web_search" | "fetch_content" | "hublu" | "memory" | "image" | "browser" | "android";
871
+ "object": "tool";
872
+ "description": string;
873
+ "expands_to": string[];
874
+ "available": boolean;
875
+ }>;
876
+ /** Opaque keyset cursor; null on the last page. */
877
+ "next_cursor": string | null;
878
+ }