@klex/agent-admin-api 0.9.0 → 0.11.0

package/README.md

@@ -34,6 +34,16 @@ returned by the API are redacted and must never contain resolved environment
 secrets. Model selection uses separate `providerId` and opaque `modelId` fields;
 clients must not split model IDs on colons.
 
+## Realtime voice client contract
+
+- `GET /v1/providers/{id}/voices?modelId=...&refresh=false` returns `selectionSupported`, optional `defaultVoiceId`, and compatible entries with opaque `voiceId`, display metadata, provenance and preview availability. Provider capabilities advertise discovery/preview hooks; model-scoped support determines whether a selector is available. Listing does not generate audio. Encode the complete model ID in the query, including slashes/colons.
+- `POST /v1/providers/{id}/voices/preview` takes `{ modelId, voiceId }`. It can trigger billable same-model Live generation and returns binary `audio/wav`, not JSON/base64 or a public URL. `X-Voice-Preview-Model` is URI-encoded and `X-Voice-Preview-Mode` is `live`. On failure parse the JSON error contract; 429 means quota, 502 means upstream generation failure. Arbitrary text/URLs/model overrides are not accepted.
+- `PATCH /v1/settings/model-selection` saves `voice.sts` references with optional `voiceId`. Preserve both `voice.tts` and `voice.stt` because the voice object is replaced. Omit `voiceId` in the replacement STS reference to reset. Other selection purposes reject it. New calls use changes; active calls do not switch voices.
+
+Existing omitted defaults remain: OpenAI Realtime/GPT-Live `marin`, Gemini's provider default. Unknown/custom model profiles remain usable with defaults, but have no selectable catalog. Catalog provenance distinguishes maintained/discovered data, with explicit fallback/stale flags. Samples improvise a short introduction from the current agent name and full soul. Realtime/Gemini generate it directly; GPT-Live uses the first configured chat model to write commentary before speaking it with the selected Live voice. That extra text call is potentially billable and requires a chat selection. GPT-Live may paraphrase commentary. Name/soul changes bypass old cached samples; different voices may use different wording. Browser clients fetch over their existing authorized Cloud path, check `response.ok`, then use `response.blob()` and an object URL for playback (revoke it afterward). Headless/TUI clients use `arrayBuffer()` and an external WAV player; the backend does not implement playback.
+
+Local admin access remains unauthenticated and loopback-only; Cloud access remains authorized through the existing tunnel. Responses use private/no-store headers, while the agent caches successful samples in bounded memory for reuse. Previewing never starts a production call or supplies history, tools, or credentials as prompt context. It intentionally supplies the full soul to the speech provider or, for GPT-Live, the configured chat provider. Prompts instruct models not to speak private details, but generated output still depends on provider behavior. No UI selector is included in this contract change.
+
 ## MCP OAuth authorization
 
 Version 0.2 adds the consolidated MCP authorization contract. Authorization is

package/dist/index.d.ts

@@ -15,15 +15,6 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
 } & {
     "/v1/cloud/status": {
         $get: {
-            output: {
-                error: string;
-                code: string;
-                remediation?: string | undefined;
-            };
-            outputFormat: "json";
-            status: 500;
-            input: {};
-        } | {
             output: {
                 cloudEnabled: boolean;
                 enrolled: boolean;
@@ -35,6 +26,15 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             outputFormat: "json";
             status: 200;
             input: {};
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {};
         };
     };
 } & {
@@ -207,6 +207,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                                 [x: string]: import("hono/utils/types").JSONValue;
                             };
                         } | undefined;
+                        voiceId?: string | undefined;
                     }[];
                     tts: {
                         providerId: string;
@@ -280,6 +281,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                             providerId: string;
                             modelId: string;
                             providerOptions?: Record<string, Record<string, unknown>> | undefined;
+                            voiceId?: string | undefined;
                         }[];
                         tts: {
                             providerId: string;
@@ -339,6 +341,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                             providerId: string;
                             modelId: string;
                             providerOptions?: Record<string, Record<string, unknown>> | undefined;
+                            voiceId?: string | undefined;
                         }[];
                         tts: {
                             providerId: string;
@@ -418,6 +421,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                                 [x: string]: import("hono/utils/types").JSONValue;
                             };
                         } | undefined;
+                        voiceId?: string | undefined;
                     }[];
                     tts: {
                         providerId: string;
@@ -482,6 +486,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                             providerId: string;
                             modelId: string;
                             providerOptions?: Record<string, Record<string, unknown>> | undefined;
+                            voiceId?: string | undefined;
                         }[];
                         tts: {
                             providerId: string;
@@ -512,6 +517,15 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
 } & {
     "/v1/introspect": {
         $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {};
+        } | {
             output: {
                 path: string[];
                 state: {
@@ -526,15 +540,6 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             outputFormat: "json";
             status: 200;
             input: {};
-        } | {
-            output: {
-                error: string;
-                code: string;
-                remediation?: string | undefined;
-            };
-            outputFormat: "json";
-            status: 500;
-            input: {};
         };
     };
 } & {
@@ -1814,6 +1819,105 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             };
         };
     };
+} & {
+    "/v1/skills": {
+        $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {};
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 503;
+            input: {};
+        } | {
+            output: {
+                skills: {
+                    name: string;
+                    description: string;
+                    origin: "learned";
+                    createdAt?: string | undefined;
+                    updatedAt?: string | undefined;
+                    lastReadAt?: string | null | undefined;
+                    readCount?: number | undefined;
+                }[];
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {};
+        };
+    };
+} & {
+    "/v1/skills/:name": {
+        $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 404;
+            input: {
+                param: {
+                    name: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {
+                param: {
+                    name: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 503;
+            input: {
+                param: {
+                    name: string;
+                };
+            };
+        } | {
+            output: {
+                name: string;
+                description: string;
+                origin: "learned";
+                createdAt?: string | undefined;
+                updatedAt?: string | undefined;
+                lastReadAt?: string | null | undefined;
+                readCount?: number | undefined;
+                body: string;
+                sourceEpisodes?: string[] | undefined;
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                param: {
+                    name: string;
+                };
+            };
+        };
+    };
 } & {
     "/v1/provider-types": {
         $get: {
@@ -1825,6 +1929,8 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                     documentationUrl?: string | undefined;
                     capabilities: {
                         modelDiscovery: boolean;
+                        voiceDiscovery: boolean;
+                        voicePreview: boolean;
                         connectivityTest: boolean;
                         customModels: boolean;
                     };
@@ -1890,6 +1996,8 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                         documentationUrl?: string | undefined;
                         capabilities: {
                             modelDiscovery: boolean;
+                            voiceDiscovery: boolean;
+                            voicePreview: boolean;
                             connectivityTest: boolean;
                             customModels: boolean;
                         };
@@ -1940,6 +2048,8 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                         documentationUrl?: string | undefined;
                         capabilities: {
                             modelDiscovery: boolean;
+                            voiceDiscovery: boolean;
+                            voicePreview: boolean;
                             connectivityTest: boolean;
                             customModels: boolean;
                         };
@@ -2030,6 +2140,8 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                         documentationUrl?: string | undefined;
                         capabilities: {
                             modelDiscovery: boolean;
+                            voiceDiscovery: boolean;
+                            voicePreview: boolean;
                             connectivityTest: boolean;
                             customModels: boolean;
                         };
@@ -2132,6 +2244,8 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                         documentationUrl?: string | undefined;
                         capabilities: {
                             modelDiscovery: boolean;
+                            voiceDiscovery: boolean;
+                            voicePreview: boolean;
                             connectivityTest: boolean;
                             customModels: boolean;
                         };
@@ -2237,6 +2351,8 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                         documentationUrl?: string | undefined;
                         capabilities: {
                             modelDiscovery: boolean;
+                            voiceDiscovery: boolean;
+                            voicePreview: boolean;
                             connectivityTest: boolean;
                             customModels: boolean;
                         };
@@ -2429,6 +2545,243 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             };
         };
     };
+} & {
+    "/v1/providers/:id/voices": {
+        $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                query: {
+                    modelId: string;
+                    refresh?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 404;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                query: {
+                    modelId: string;
+                    refresh?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 429;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                query: {
+                    modelId: string;
+                    refresh?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                query: {
+                    modelId: string;
+                    refresh?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 502;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                query: {
+                    modelId: string;
+                    refresh?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                selectionSupported: boolean;
+                defaultVoiceId?: string | undefined;
+                fallback?: boolean | undefined;
+                stale?: boolean | undefined;
+                voices: {
+                    voiceId: string;
+                    displayName: string;
+                    description?: string | undefined;
+                    language?: string | undefined;
+                    region?: string | undefined;
+                    provenance: {
+                        source: "discovered" | "maintained";
+                        documentationUrl: string;
+                        reviewedAt?: string | undefined;
+                    };
+                    preview: {
+                        available: boolean;
+                        mode?: "live" | undefined;
+                    };
+                }[];
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                query: {
+                    modelId: string;
+                    refresh?: "false" | "true" | undefined;
+                };
+            };
+        };
+    };
+} & {
+    "/v1/providers/:id/voices/preview": {
+        $post: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                json: {
+                    modelId: string;
+                    voiceId: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 404;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                json: {
+                    modelId: string;
+                    voiceId: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 429;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                json: {
+                    modelId: string;
+                    voiceId: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                json: {
+                    modelId: string;
+                    voiceId: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 502;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                json: {
+                    modelId: string;
+                    voiceId: string;
+                };
+            };
+        } | {
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+            input: {
+                param: {
+                    id: string;
+                };
+            } & {
+                json: {
+                    modelId: string;
+                    voiceId: string;
+                };
+            };
+        };
+    };
 } & {
     "/v1/providers/:id/models": {
         $post: {
@@ -3001,18 +3354,12 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
     "/v1/introspect/:path": {
         $get: {
             output: {
-                path: string[];
-                state: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | null;
-                children: {
-                    id: string;
-                    hasState: boolean;
-                    hasChildren: boolean;
-                }[];
+                error: string;
+                code: string;
+                remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 200;
+            status: 400;
             input: {
                 param: {
                     path: string;
@@ -3025,7 +3372,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 400;
+            status: 404;
             input: {
                 param: {
                     path: string;
@@ -3038,7 +3385,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 404;
+            status: 500;
             input: {
                 param: {
                     path: string;
@@ -3046,12 +3393,18 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             };
         } | {
             output: {
-                error: string;
-                code: string;
-                remediation?: string | undefined;
+                path: string[];
+                state: {
+                    [x: string]: import("hono/utils/types").JSONValue;
+                } | null;
+                children: {
+                    id: string;
+                    hasState: boolean;
+                    hasChildren: boolean;
+                }[];
             };
             outputFormat: "json";
-            status: 500;
+            status: 200;
             input: {
                 param: {
                     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klex/agent-admin-api",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "sideEffects": false,
   "description": "Shared types for the Klex Bot Admin API",