@kybernesis/voice 0.1.0

package/NOTICE

@@ -0,0 +1,4 @@
+@kybernesis/voice
+Copyright 2026 Kybernesis (kybernesis.ai)
+
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,53 @@
+# @kybernesis/voice
+
+Give a KYBER Studio agent its own realtime voice. The floating orb in Studio
+speaks **as the agent** and delegates every real request back to the agent's own
+session, so the voice can do anything the text chat can — recall from memory,
+know its role and routines, create routines, run tools and connectors.
+
+Voice is a **per-agent capability**. An agent that mounts this channel is
+voice-capable; one that doesn't shows no orb. Each agent holds its **own** OpenAI
+key — never a shared one, and never in Studio.
+
+## Install
+
+```bash
+eve add @kybernesis/voice
+```
+
+Set the agent's own key in a non-generic variable so nothing else picks it up:
+
+```bash
+# in the agent's .env.local
+KYBERNESIS_VOICE_OPENAI_KEY=sk-...
+```
+
+## Mount
+
+```ts title="agent/channels/voice.ts"
+import { voiceChannel } from "@kybernesis/voice";
+
+export default voiceChannel({
+  openaiApiKey: process.env.KYBERNESIS_VOICE_OPENAI_KEY!,
+  voice: "cedar", // any OpenAI Live voice; Studio's per-agent setting overrides at mint time
+});
+```
+
+## Routes
+
+Both require the caller's control-plane grant for this agent (verified with
+`@kybernesis/enterprise`), the same identity every other door uses.
+
+- `GET /eve/v1/voice/manifest` — `{ ok, enabled, voice, displayName }`. Studio
+  calls this per agent to decide whether to show the orb.
+- `POST /eve/v1/voice/session` — body `{ sdp }` (the browser's WebRTC offer);
+  mints an OpenAI Live session with this agent's key, configured for client
+  delegation, and returns `{ ok, sdp }` (the answer). The key never leaves the
+  agent; only SDP crosses the wire.
+
+## How it fits together
+
+gpt-live-1 is the spoken voice and, under client delegation, hands every real
+turn to the client. KYBER Studio routes that delegation to this agent's own eve
+session and speaks back the result. This package is the agent's half: advertise
+the capability, and mint the session with the agent's own key.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export interface VoiceOptions {
+    /**
+     * This agent's OpenAI API key, used only to mint realtime sessions. Read it
+     * from a NON-generic env var in the mount file (e.g.
+     * `process.env.KYBERNESIS_VOICE_OPENAI_KEY`) so no other code — and no OpenAI
+     * SDK that auto-reads `OPENAI_API_KEY` — ever picks it up. It is never sent to
+     * Studio; only the short-lived realtime answer SDP is returned.
+     */
+    openaiApiKey: string;
+    /** The spoken voice (OpenAI Live voice name). Defaults to "marin". */
+    voice?: string;
+    /** How the voice refers to itself. Defaults to KYBERNESIS_AGENT. */
+    displayName?: string;
+    /** Realtime model. Defaults to gpt-live-1 (override with OPENAI_LIVE_MODEL). */
+    model?: string;
+    /** Control-plane issuer. Defaults to KYBERNESIS_ISSUER. */
+    issuer?: string;
+    /** This agent's registered name, for grant checks. Defaults to KYBERNESIS_AGENT. */
+    agent?: string;
+}
+export declare function voiceChannel(options: VoiceOptions): import("eve/channels").Channel<undefined, Record<string, unknown>, Record<string, unknown>>;

package/dist/index.js

@@ -0,0 +1,138 @@
+import { verifyKybernesisRequest } from "@kybernesis/enterprise";
+import { defineChannel, GET, POST } from "eve/channels";
+/**
+ * @kybernesis/voice — the agent side of KYBER Studio's realtime voice orb.
+ *
+ * Voice is a per-agent capability, not a Studio-global one. An agent that mounts
+ * this channel becomes voice-capable; one that doesn't has no orb in Studio. The
+ * agent holds its OWN OpenAI key (never a shared one, never in Studio), and this
+ * channel is the only thing that reads it: the key is passed into `voiceChannel`
+ * from the mount file's `process.env` and closed over here, so nothing else in
+ * the agent picks it up by name.
+ *
+ * How a call runs: gpt-live-1 is the spoken voice and delegates every real
+ * request (client delegation); Studio routes that delegation to THIS agent's own
+ * session, where the tools, connectors, and memory live. So the voice can do
+ * anything the text chat can. This channel does two things only — say the agent
+ * is voice-capable, and mint the realtime session with the agent's key — both
+ * behind the same control-plane grant that guards every other door.
+ *
+ * ```ts title="agent/channels/voice.ts"
+ * import { voiceChannel } from "@kybernesis/voice";
+ * export default voiceChannel({
+ *   openaiApiKey: process.env.KYBERNESIS_VOICE_OPENAI_KEY!,
+ *   voice: "cedar",
+ * });
+ * ```
+ */
+/** Routes mount verbatim at the server root, so they are namespaced here. */
+const PREFIX = "/eve/v1/voice";
+const LIVE_SESSIONS_URL = "https://api.openai.com/v1/live/sessions";
+const DEFAULT_MODEL = "gpt-live-1";
+const DEFAULT_VOICE = "marin";
+/**
+ * The spoken persona. The voice model is a mouth, not a mind: it holds none of
+ * the agent's knowledge and must delegate everything real back to the agent,
+ * then speak the result in the first person. This is what stops it answering
+ * "what is your role?" as a generic assistant instead of as the agent.
+ */
+function liveInstructions(displayName) {
+    return (`You are the live spoken VOICE of ${displayName}. You are only a voice: you have no knowledge, memory, opinions, tools, routines, or identity of your own. Everything the user hears must come from ${displayName}'s real mind, which you reach by delegating. ` +
+        `Delegate EVERY user message that expects an answer or an action — including who you are, your role, what you can do, your memory, your routines, creating or changing routines, any question, any task, anything factual or personal. Never answer from your own knowledge, and never describe yourself in generic terms like "a helpful assistant." ` +
+        `When the delegated result comes back, speak it in the first person as ${displayName}, naturally and concisely, as if you had known it all along. ` +
+        `The only things you may say without delegating are pure conversational sounds that carry no request: a brief greeting, "one moment", an acknowledgement, or confirming you can hear the user. When in doubt, delegate.`);
+}
+/**
+ * Verify the SAME control-plane identity the user already signed in with — the
+ * bearer token plus policy bundle — and require a grant for this agent. Custom
+ * channels do not run the eve channel's authenticator, so each route checks
+ * here, exactly as @kybernesis/manage does. No separate shared secret.
+ */
+async function authorize(req, options) {
+    const issuer = options.issuer ?? process.env.KYBERNESIS_ISSUER ?? "https://agent.kybernesis.ai";
+    const agent = options.agent ?? process.env.KYBERNESIS_AGENT;
+    if (!agent) {
+        return Response.json({ ok: false, error: "This agent has no KYBERNESIS_AGENT set, so it cannot check grants." }, { status: 500 });
+    }
+    const result = await verifyKybernesisRequest(req, { issuer, agent });
+    if (result.ok)
+        return null;
+    return Response.json({ ok: false, error: result.error }, { status: result.status });
+}
+export function voiceChannel(options) {
+    const voice = options.voice ?? DEFAULT_VOICE;
+    const model = options.model ?? process.env.OPENAI_LIVE_MODEL ?? DEFAULT_MODEL;
+    const displayName = options.displayName ?? options.agent ?? process.env.KYBERNESIS_AGENT ?? "the agent";
+    return defineChannel({
+        routes: [
+            /**
+             * Say this agent is voice-capable, and how it should sound. Studio calls
+             * this per agent to decide whether to show the orb at all.
+             */
+            GET(PREFIX + "/manifest", async (req) => {
+                const denied = await authorize(req, options);
+                if (denied)
+                    return denied;
+                return Response.json({ ok: true, enabled: true, voice, displayName });
+            }),
+            /**
+             * Mint a realtime session for the browser's WebRTC offer, using THIS
+             * agent's own OpenAI key, and return the answer SDP. The key never leaves
+             * the agent; Studio relays only SDP. The session is configured for client
+             * delegation, so the voice hands real work back to the agent's session.
+             */
+            POST(PREFIX + "/session", async (req) => {
+                const denied = await authorize(req, options);
+                if (denied)
+                    return denied;
+                if (!options.openaiApiKey) {
+                    return Response.json({ ok: false, error: "This agent has no voice key set (KYBERNESIS_VOICE_OPENAI_KEY)." }, { status: 500 });
+                }
+                let sdp;
+                let requestedVoice;
+                try {
+                    const body = (await req.json());
+                    if (typeof body.sdp !== "string" || !body.sdp)
+                        throw new Error("missing sdp");
+                    sdp = body.sdp;
+                    if (typeof body.voice === "string" && body.voice)
+                        requestedVoice = body.voice;
+                }
+                catch {
+                    return Response.json({ ok: false, error: "Expected a JSON body with an SDP offer." }, { status: 400 });
+                }
+                const upstream = await fetch(LIVE_SESSIONS_URL, {
+                    method: "POST",
+                    headers: { authorization: `Bearer ${options.openaiApiKey}`, "content-type": "application/json" },
+                    body: JSON.stringify({
+                        session: {
+                            model,
+                            instructions: liveInstructions(displayName),
+                            audio: { output: { voice: requestedVoice ?? voice } },
+                            delegation: { type: "client" },
+                        },
+                        transport: { type: "webrtc", sdp },
+                    }),
+                }).catch((err) => {
+                    return { ok: false, status: 502, text: async () => String(err) };
+                });
+                const text = await upstream.text();
+                if (!upstream.ok) {
+                    return Response.json({ ok: false, error: `OpenAI Live session ${upstream.status}: ${text.slice(0, 400)}` }, { status: 502 });
+                }
+                let data;
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    return Response.json({ ok: false, error: "OpenAI returned a non-JSON session." }, { status: 502 });
+                }
+                const answer = data.transport?.sdp ?? data.sdp;
+                if (!answer) {
+                    return Response.json({ ok: false, error: "OpenAI session had no answer SDP." }, { status: 502 });
+                }
+                return Response.json({ ok: true, sdp: answer });
+            }),
+        ],
+    });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kybernesis/voice",
+  "version": "0.1.0",
+  "description": "Give a KYBER Studio agent its own realtime voice: the floating orb speaks as the agent and delegates every real request back to the agent's own session. The agent holds its own OpenAI key.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish.mjs",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "peerDependencies": {
+    "@kybernesis/enterprise": ">=0.3.0",
+    "eve": ">=0.51.0 <0.52.0",
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@kybernesis/enterprise": "^0.8.0",
+    "@types/node": "^22.10.2",
+    "eve": "^0.51.1",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "homepage": "https://kybernesis.ai",
+  "keywords": [
+    "eve",
+    "eve-channel",
+    "voice",
+    "realtime",
+    "kybernesis",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KybernesisAI/platform.git",
+    "directory": "packages/voice"
+  }
+}