@perkos/perkos-voice 0.1.0

package/dist/bragiDelivery.js

@@ -0,0 +1,263 @@
+import { constants as cryptoConstants, createHash, createHmac, createPrivateKey, createPublicKey, generateKeyPairSync, privateDecrypt, randomUUID, sign, } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { chmod, mkdir, open, realpath, rename, rmdir, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export const BRAGI_DELIVERY_AUDIENCE = "perkos-voice-gateway-grant:v1";
+export const BRAGI_DELIVERY_ALGORITHM = "RSA-OAEP-256";
+const MAX_RESPONSE_BYTES = 32_768;
+const MAX_CREDENTIAL_BYTES = 8_192;
+function fingerprint(publicKeyPem) {
+    const der = createPublicKey(publicKeyPem).export({ type: "spki", format: "der" });
+    return createHash("sha256").update(der).digest("hex");
+}
+function assertSafeId(value, name) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(value))
+        throw new Error(`${name} is invalid`);
+}
+function assertUuid(value, name) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+        throw new Error(`${name} is invalid`);
+    }
+}
+function assertRoot(requireRoot = true) {
+    if (requireRoot && process.geteuid?.() !== 0)
+        throw new Error("Bragi delivery receiver must run as root");
+}
+async function readRootFile(path, maximumBytes = 65_536) {
+    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || (info.mode & 0o777) !== 0o600 || info.size > maximumBytes) {
+            throw new Error("protected file must be regular, mode 0600, and size-bounded");
+        }
+        if (process.geteuid?.() === 0 && info.uid !== 0)
+            throw new Error("protected file must be root-owned");
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeProtectedAtomic(path, content) {
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (await realpath(directory) !== resolve(directory))
+        throw new Error("protected directory must not be a symlink");
+    await chmod(directory, 0o700);
+    const temporary = join(directory, `.${process.pid}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+    const directoryHandle = await open(directory, fsConstants.O_RDONLY);
+    try {
+        await directoryHandle.sync();
+    }
+    finally {
+        await directoryHandle.close();
+    }
+}
+export async function prepareBragiDelivery(stateDirectory, options = {}) {
+    assertRoot(options.requireRoot);
+    const absoluteDirectory = resolve(stateDirectory);
+    await mkdir(absoluteDirectory, { recursive: false, mode: 0o700 });
+    await chmod(absoluteDirectory, 0o700);
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 3072,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+    const now = options.now ?? new Date();
+    const state = {
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + 5 * 60_000).toISOString(),
+        agentId: "Bragi",
+        audience: BRAGI_DELIVERY_AUDIENCE,
+        publicKeyFingerprint: fingerprint(publicKey),
+    };
+    try {
+        await writeProtectedAtomic(join(absoluteDirectory, "private.der"), privateKey);
+        await writeProtectedAtomic(join(absoluteDirectory, "public.pem"), publicKey);
+        await writeProtectedAtomic(join(absoluteDirectory, "state.json"), JSON.stringify(state));
+        return state;
+    }
+    catch (error) {
+        for (const name of ["private.der", "public.pem", "state.json"]) {
+            try {
+                await unlink(join(absoluteDirectory, name));
+            }
+            catch { /* absent */ }
+        }
+        try {
+            await rmdir(absoluteDirectory);
+        }
+        catch { /* preserve unexpected contents */ }
+        throw error;
+    }
+    finally {
+        privateKey.fill(0);
+    }
+}
+export function canonicalClaim(path, claimId, timestamp) {
+    assertUuid(claimId, "claimId");
+    const body = JSON.stringify({ claimId, timestamp });
+    const bodyHash = createHash("sha256").update(body).digest("hex");
+    return { body, canonical: `POST\n${path}\n${timestamp}\n${claimId}\n${bodyHash}` };
+}
+export function canonicalDiscovery(path, publicKeyFingerprint, audience, timestamp, nonce) {
+    if (!/^[a-f0-9]{64}$/.test(publicKeyFingerprint))
+        throw new Error("publicKeyFingerprint is invalid");
+    assertUuid(nonce, "nonce");
+    const body = JSON.stringify({ publicKeyFingerprint, audience, timestamp, nonce });
+    const bodyHash = createHash("sha256").update(body).digest("hex");
+    return {
+        body,
+        canonical: `POST\n${path}\n${timestamp}\n${nonce}\n${audience}\n${publicKeyFingerprint}\n${bodyHash}`,
+    };
+}
+async function boundedJson(response) {
+    const declared = Number(response.headers.get("content-length") ?? 0);
+    if (declared > MAX_RESPONSE_BYTES)
+        throw new Error("delivery response is oversized");
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.byteLength > MAX_RESPONSE_BYTES)
+        throw new Error("delivery response is oversized");
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+export async function claimBragiDelivery(options) {
+    assertRoot(options.requireRoot);
+    assertSafeId(options.enrollmentAgentId, "enrollmentAgentId");
+    const stateDirectory = resolve(options.stateDirectory);
+    const stateBuffer = await readRootFile(join(stateDirectory, "state.json"));
+    const privateKeyBuffer = await readRootFile(join(stateDirectory, "private.der"), 16_384);
+    const publicKeyBuffer = await readRootFile(join(stateDirectory, "public.pem"), 16_384);
+    let credential;
+    try {
+        const state = JSON.parse(stateBuffer.toString("utf8"));
+        if (state.agentId !== "Bragi" || state.audience !== BRAGI_DELIVERY_AUDIENCE)
+            throw new Error("delivery state binding is invalid");
+        if (Date.parse(state.expiresAt) <= (options.now ?? new Date()).getTime())
+            throw new Error("delivery state expired");
+        if (fingerprint(publicKeyBuffer.toString("utf8")) !== state.publicKeyFingerprint)
+            throw new Error("public key fingerprint mismatch");
+        const privateKey = createPrivateKey({ key: privateKeyBuffer, type: "pkcs8", format: "der" });
+        if (createPublicKey(privateKey).export({ type: "spki", format: "pem" }).toString() !== publicKeyBuffer.toString("utf8")) {
+            throw new Error("ephemeral key pair mismatch");
+        }
+        const endpoint = new URL(options.endpoint);
+        if (endpoint.protocol !== "https:" && !["localhost", "127.0.0.1", "::1"].includes(endpoint.hostname))
+            throw new Error("delivery endpoint must use HTTPS");
+        const basePath = endpoint.pathname.replace(/\/$/, "");
+        const timestamp = (options.now ?? new Date()).toISOString();
+        const nonce = randomUUID();
+        const discoveryPath = `${basePath}/deliveries/discover`;
+        const discovery = canonicalDiscovery(discoveryPath, state.publicKeyFingerprint, BRAGI_DELIVERY_AUDIENCE, timestamp, nonce);
+        const discoverySignature = sign("sha256", Buffer.from(discovery.canonical), {
+            key: privateKey,
+            padding: cryptoConstants.RSA_PKCS1_PSS_PADDING,
+            saltLength: 32,
+        }).toString("base64");
+        const discoveryResponse = await (options.fetcher ?? fetch)(new URL(discoveryPath, endpoint.origin), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...JSON.parse(discovery.body), signature: discoverySignature }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!discoveryResponse.ok)
+            throw new Error(`encrypted delivery discovery failed (${discoveryResponse.status})`);
+        const discovered = await boundedJson(discoveryResponse);
+        const metadata = discovered.delivery;
+        if (discovered.ok !== true || typeof metadata?.id !== "string" || typeof metadata.claimId !== "string" ||
+            typeof metadata.expiresAt !== "string" || Date.parse(metadata.expiresAt) <= (options.now ?? new Date()).getTime()) {
+            throw new Error("encrypted delivery discovery response is invalid");
+        }
+        const deliveryId = metadata.id;
+        const claimId = metadata.claimId;
+        assertUuid(deliveryId, "deliveryId");
+        assertUuid(claimId, "claimId");
+        const path = `${basePath}/deliveries/${encodeURIComponent(deliveryId)}/claim`;
+        const { body: unsignedBody, canonical } = canonicalClaim(path, claimId, timestamp);
+        const signature = sign("sha256", Buffer.from(canonical), {
+            key: privateKey,
+            padding: cryptoConstants.RSA_PKCS1_PSS_PADDING,
+            saltLength: 32,
+        }).toString("base64");
+        const claimResponse = await (options.fetcher ?? fetch)(new URL(path, endpoint.origin), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...JSON.parse(unsignedBody), signature }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!claimResponse.ok)
+            throw new Error(`encrypted delivery claim failed (${claimResponse.status})`);
+        const claim = await boundedJson(claimResponse);
+        const delivery = claim.delivery;
+        if (claim.ok !== true || delivery?.id !== deliveryId || delivery.algorithm !== BRAGI_DELIVERY_ALGORITHM ||
+            delivery.audience !== BRAGI_DELIVERY_AUDIENCE || delivery.publicKeyFingerprint !== state.publicKeyFingerprint ||
+            typeof delivery.expiresAt !== "string" || Date.parse(delivery.expiresAt) <= (options.now ?? new Date()).getTime() ||
+            typeof delivery.ciphertext !== "string")
+            throw new Error("encrypted delivery response binding is invalid");
+        const ciphertext = Buffer.from(delivery.ciphertext, "base64");
+        if (!ciphertext.length || ciphertext.toString("base64") !== delivery.ciphertext)
+            throw new Error("encrypted delivery ciphertext is invalid");
+        try {
+            credential = privateDecrypt({ key: privateKey, oaepHash: "sha256", padding: cryptoConstants.RSA_PKCS1_OAEP_PADDING }, ciphertext);
+        }
+        finally {
+            ciphertext.fill(0);
+        }
+        if (!credential.length || credential.length > MAX_CREDENTIAL_BYTES || credential.includes(0))
+            throw new Error("decrypted credential is invalid");
+        let currentBuffer;
+        try {
+            currentBuffer = await readRootFile(resolve(options.gatewaySecretFile));
+            const current = JSON.parse(currentBuffer.toString("utf8"));
+            current.grantCredential = credential.toString("utf8");
+            current.capabilityPublishCredential = credential.toString("utf8");
+            await writeProtectedAtomic(resolve(options.gatewaySecretFile), JSON.stringify(current));
+            try {
+                const credentialProof = createHmac("sha256", credential)
+                    .update(`receipt\n${options.enrollmentAgentId}\n${deliveryId}\n${claimId}`)
+                    .digest("base64url");
+                const receiptResponse = await (options.fetcher ?? fetch)(new URL(`${basePath}/deliveries/${encodeURIComponent(deliveryId)}/receipt`, endpoint.origin), {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ claimId, credentialProof }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!receiptResponse.ok)
+                    throw new Error(`encrypted delivery receipt failed (${receiptResponse.status})`);
+                const receipt = await boundedJson(receiptResponse);
+                if (receipt.ok !== true || receipt.status !== "received")
+                    throw new Error("encrypted delivery receipt is invalid");
+            }
+            catch (error) {
+                await writeProtectedAtomic(resolve(options.gatewaySecretFile), currentBuffer);
+                throw error;
+            }
+        }
+        finally {
+            currentBuffer?.fill(0);
+        }
+        for (const name of ["private.der", "public.pem", "state.json"])
+            await unlink(join(stateDirectory, name));
+        await rmdir(stateDirectory);
+    }
+    finally {
+        stateBuffer.fill(0);
+        privateKeyBuffer.fill(0);
+        publicKeyBuffer.fill(0);
+        credential?.fill(0);
+    }
+}

package/dist/bragiDeliveryCli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bragiDeliveryCli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { claimBragiDelivery, prepareBragiDelivery } from "./bragiDelivery.js";
+function option(name) {
+    const index = process.argv.indexOf(name);
+    const value = index >= 0 ? process.argv[index + 1] : undefined;
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} is required`);
+    return value;
+}
+async function main() {
+    const command = process.argv[2];
+    if (command === "prepare") {
+        await prepareBragiDelivery(option("--state-dir"));
+        process.stdout.write("Bragi encrypted delivery receiver prepared.\n");
+        return;
+    }
+    if (command === "claim") {
+        await claimBragiDelivery({
+            endpoint: option("--endpoint"),
+            enrollmentAgentId: option("--enrollment-agent-id"),
+            stateDirectory: option("--state-dir"),
+            gatewaySecretFile: option("--gateway-secret-file"),
+        });
+        process.stdout.write("Bragi encrypted delivery received and acknowledged.\n");
+        return;
+    }
+    throw new Error("usage: bragi-delivery prepare|claim [options]");
+}
+main().catch(() => {
+    process.stderr.write("Bragi encrypted delivery failed closed.\n");
+    process.exitCode = 1;
+});

package/dist/capability.d.ts

@@ -0,0 +1,15 @@
+import type { TranscriptPolicy, VoiceAvailabilityDecision, VoiceCapabilityHandshake, VoiceMode, VoiceProviderOwnership } from "./types.js";
+export declare class CapabilityValidationError extends Error {
+    readonly code = "INVALID_CAPABILITY_HANDSHAKE";
+}
+/** Strictly parses the public handshake; unknown/private fields are rejected. */
+export declare function validateCapabilityHandshake(value: unknown): VoiceCapabilityHandshake;
+export interface AvailabilityRequirements {
+    agentId: string;
+    mode: VoiceMode;
+    transcriptPolicy: TranscriptPolicy;
+    requireInterrupt?: boolean;
+    allowedOwnership?: readonly VoiceProviderOwnership[];
+    now?: Date;
+}
+export declare function reasonVoiceAvailability(rawHandshake: unknown, requirements: AvailabilityRequirements): VoiceAvailabilityDecision;

package/dist/capability.js

@@ -0,0 +1,84 @@
+const OWNERSHIP = [
+    "external_owner",
+    "perkos_managed",
+    "organization_byok",
+];
+const MODES = ["turn_based", "realtime"];
+const AVAILABILITY = ["available", "unavailable", "degraded"];
+const CAPABILITY_KEYS = new Set([
+    "agentId", "availability", "supportedModes", "ownership", "supportsInterrupt",
+    "supportsEphemeralTranscript", "supportsSavedTranscript", "checkedAt", "expiresAt",
+]);
+const HANDSHAKE_KEYS = new Set(["protocolVersion", "capability"]);
+export class CapabilityValidationError extends Error {
+    code = "INVALID_CAPABILITY_HANDSHAKE";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isoDate(value) {
+    return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+/** Strictly parses the public handshake; unknown/private fields are rejected. */
+export function validateCapabilityHandshake(value) {
+    if (!isRecord(value) || Object.keys(value).some((key) => !HANDSHAKE_KEYS.has(key))) {
+        throw new CapabilityValidationError("Handshake must contain only protocolVersion and capability");
+    }
+    if (value.protocolVersion !== "1") {
+        throw new CapabilityValidationError("Unsupported capability protocol version");
+    }
+    if (value.capability === undefined)
+        return { protocolVersion: "1" };
+    if (!isRecord(value.capability) || Object.keys(value.capability).some((key) => !CAPABILITY_KEYS.has(key))) {
+        throw new CapabilityValidationError("Capability contains unknown or private fields");
+    }
+    const capability = value.capability;
+    if (typeof capability.agentId !== "string" || capability.agentId.length === 0 ||
+        !AVAILABILITY.includes(capability.availability) ||
+        !Array.isArray(capability.supportedModes) ||
+        capability.supportedModes.some((mode) => !MODES.includes(mode)) ||
+        !OWNERSHIP.includes(capability.ownership) ||
+        typeof capability.supportsInterrupt !== "boolean" ||
+        typeof capability.supportsEphemeralTranscript !== "boolean" ||
+        typeof capability.supportsSavedTranscript !== "boolean" ||
+        !isoDate(capability.checkedAt) || !isoDate(capability.expiresAt)) {
+        throw new CapabilityValidationError("Capability fields are invalid");
+    }
+    if (Date.parse(capability.checkedAt) >= Date.parse(capability.expiresAt)) {
+        throw new CapabilityValidationError("Capability expiry must follow its check time");
+    }
+    return { protocolVersion: "1", capability: capability };
+}
+export function reasonVoiceAvailability(rawHandshake, requirements) {
+    let handshake;
+    try {
+        handshake = validateCapabilityHandshake(rawHandshake);
+    }
+    catch {
+        return { available: false, reason: "capability_invalid" };
+    }
+    const capability = handshake.capability;
+    if (!capability)
+        return { available: false, reason: "capability_absent" };
+    const reject = (reason) => ({ available: false, reason, capability });
+    if (capability.agentId !== requirements.agentId)
+        return reject("agent_mismatch");
+    if (Date.parse(capability.expiresAt) <= (requirements.now ?? new Date()).getTime())
+        return reject("expired");
+    if (capability.availability === "unavailable")
+        return reject("reported_unavailable");
+    if (!capability.supportedModes.includes(requirements.mode))
+        return reject("mode_unsupported");
+    if (requirements.allowedOwnership && !requirements.allowedOwnership.includes(capability.ownership)) {
+        return reject("ownership_unsupported");
+    }
+    if (requirements.requireInterrupt && !capability.supportsInterrupt)
+        return reject("interrupt_unsupported");
+    if (requirements.transcriptPolicy === "ephemeral" && !capability.supportsEphemeralTranscript) {
+        return reject("transcript_policy_unsupported");
+    }
+    if (requirements.transcriptPolicy === "saved" && !capability.supportsSavedTranscript) {
+        return reject("transcript_policy_unsupported");
+    }
+    return { available: true, reason: "available", capability };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+import { loadGatewayConfig, validateByoConfig } from "./config.js";
+import { startHealthServer } from "./service.js";
+import { M2mGrantSource } from "./grants.js";
+import { LiveKitMediaRoom } from "./adapters/livekit.js";
+import { ByoSpeechHttpAdapter } from "./adapters/speech.js";
+import { OpenAiTurnSpeechAdapter } from "./adapters/openaiSpeech.js";
+import { OpenClawChatCompletionsAdapter, OpenClawResponsesAdapter } from "./adapters/openclaw.js";
+import { ZeroClawWebhookAdapter } from "./adapters/zeroclaw.js";
+import { VoiceGateway } from "./gateway.js";
+import { CapabilityPublisher, GatewayReadiness } from "./readiness.js";
+import { createChatCommitSink, SessionControlClient } from "./sessionControl.js";
+import { runVoiceSessionStage, VoiceSessionStageError, voiceSessionStageLog } from "./mediaStages.js";
+import { MediaSuccessMetrics } from "./mediaMetrics.js";
+import { transcriptionFailureLog, ttsFailureLog } from "./speechErrors.js";
+import { healthReportFromReadiness, healthReportFromSessionFailure, mapSessionStageToCodes, reportVoiceHealthToControlPlane, voiceHealthReportEndpoint, } from "./doctor.js";
+const config = await loadGatewayConfig();
+const validation = validateByoConfig(config);
+const mediaMetrics = new MediaSuccessMetrics();
+const speech = config.speechMode === "openai_turn"
+    ? new OpenAiTurnSpeechAdapter({ apiKey: config.openAiApiKey ?? "", baseUrl: config.openAiBaseUrl, transcriptionModel: config.openAiTranscriptionModel, speechModel: config.openAiSpeechModel, voice: config.openAiVoice, observe: (event) => mediaMetrics.mark(event), logFailure: (line) => process.stderr.write(`${line}\n`) })
+    : new ByoSpeechHttpAdapter(config.speechEndpoint ?? "", config.speechCredential ?? "");
+const readiness = new GatewayReadiness(config, "probe" in speech ? speech : undefined);
+startHealthServer(config, readiness);
+const publisher = config.capabilityPublishEndpoint && config.capabilityPublishCredential
+    ? new CapabilityPublisher(config.capabilityPublishEndpoint, config.capabilityPublishCredential)
+    : undefined;
+const reportHealth = async (snapshot) => {
+    if (!config.sessionControlEndpoint || !config.grantCredential)
+        return;
+    try {
+        await reportVoiceHealthToControlPlane(voiceHealthReportEndpoint(config.sessionControlEndpoint), config.grantCredential, healthReportFromReadiness(snapshot));
+    }
+    catch {
+        process.stderr.write("voice health report failed\n");
+    }
+};
+const refresh = async () => {
+    const current = await readiness.check();
+    if (publisher) {
+        try {
+            await publisher.publish(readiness.capability());
+        }
+        catch {
+            process.stderr.write("voice capability publication failed\n");
+        }
+    }
+    await reportHealth(current);
+    if (!current.ready)
+        process.stderr.write(`voice gateway unavailable: ${current.reasons.join(",")}\n`);
+    return current;
+};
+const current = await refresh();
+setInterval(() => { void refresh(); }, 30_000).unref();
+if (!validation.valid)
+    process.stderr.write(`voice gateway configuration invalid: ${validation.reasons.join(",")}\n`);
+if (current.ready) {
+    const grantSource = new M2mGrantSource(config.grantEndpoint, config.grantCredential);
+    const control = new SessionControlClient(config.sessionControlEndpoint, config.grantCredential);
+    const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    while (true) {
+        let session;
+        try {
+            session = await control.claim();
+        }
+        catch (error) {
+            const message = error.message ?? "claim failed";
+            process.stderr.write(`voice session claim unavailable: ${message}\n`);
+            // Back off harder on rate limits so we don't dig a deeper 429 hole.
+            await delay(/\b429\b/.test(message) ? 15_000 : 5_000);
+            continue;
+        }
+        if (!session) {
+            await delay(3_000);
+            continue;
+        }
+        mediaMetrics.beginSession();
+        const runtimeProtocol = config.runtimeProtocol ?? config.openClawApiMode;
+        const runtimeEndpoint = config.runtimeEndpoint ?? config.openClawEndpoint;
+        const runtimeToken = config.runtimeToken ?? config.openClawToken;
+        const runtimeModel = config.runtimeModel ?? config.openClawChatModel;
+        const runtime = runtimeProtocol === "zeroclaw_webhook"
+            ? new ZeroClawWebhookAdapter(runtimeEndpoint, runtimeToken, config.runtimeTimeoutMs)
+            : runtimeProtocol === "chat_completions"
+                ? new OpenClawChatCompletionsAdapter({
+                    endpoint: runtimeEndpoint,
+                    token: runtimeToken,
+                    model: runtimeModel,
+                    backendModel: config.openClawVoiceModelOverride,
+                    spokenName: config.openClawSpokenName,
+                    // Working Call only: API attaches a bounded brief from the bound chat.
+                    workChatBrief: session.workChatBrief,
+                    maxTokens: config.openClawMaxTokens,
+                    timeoutMs: config.runtimeTimeoutMs,
+                    observe: (event) => mediaMetrics.mark(event),
+                })
+                : new OpenClawResponsesAdapter(runtimeEndpoint, runtimeToken);
+        const finalTurnSink = createChatCommitSink(session, control);
+        mediaMetrics.mark(finalTurnSink ? "chat_policy_normal" : "chat_policy_private");
+        if (session.workChatBrief)
+            process.stderr.write(`work_chat_brief_loaded chars=${session.workChatBrief.length}\n`);
+        else if (session.chatCommit.policy === "final_pair")
+            process.stderr.write("work_chat_brief_empty\n");
+        const gateway = new VoiceGateway(new LiveKitMediaRoom(mediaMetrics.mark), speech, runtime, undefined, mediaMetrics.mark, 30_000, (line) => process.stderr.write(`${line}\n`), finalTurnSink, config.runtimeTimeoutMs, config.speechSlaMs, config.presenceMs);
+        try {
+            const grant = await runVoiceSessionStage("grant_obtain", () => grantSource.obtain({ sessionId: session.id, projectId: session.projectId, meetingId: session.meetingId, voiceProcessingConsent: true }));
+            await runVoiceSessionStage("gateway_start", async () => {
+                try {
+                    const speechVoice = config.openAiVoiceOverride ?? session.speechVoice ?? config.openAiVoice;
+                    await gateway.start({ request: { projectId: session.projectId, meetingId: session.meetingId, agentId: session.agentId, initiatorId: "gateway", mode: "turn_based", transcriptPolicy: config.transcriptPolicy, speechVoice }, handshake: readiness.capability(), grant });
+                }
+                catch (error) {
+                    if (error instanceof VoiceSessionStageError)
+                        throw error;
+                    throw new VoiceSessionStageError("gateway_start");
+                }
+            });
+            await runVoiceSessionStage("status_joined", () => control.update(session.id, "joined"));
+            await runVoiceSessionStage("turn_loop", async () => {
+                // Soft-fail individual turns: a single STT/TTS/runtime blip must not hang up the call.
+                const startTurn = () => gateway.runTurn().catch((error) => {
+                    const line = transcriptionFailureLog(error) ?? ttsFailureLog(error);
+                    if (line)
+                        process.stderr.write(`${line}\n`);
+                    else
+                        process.stderr.write(`voice turn soft-fail: ${String(error.message ?? error).slice(0, 120)}\n`);
+                    return "turn-error";
+                });
+                let leaseExpiresAt = (await control.heartbeat(session.id)).expiresAt;
+                let nextHeartbeatAt = Date.now() + 30_000;
+                let nextStateAt = Date.now();
+                const sessionHardStopAt = Date.now() + 20 * 60_000; // heartbeat must not keep a zombie call forever
+                let turn = startTurn();
+                while (Date.parse(leaseExpiresAt) > Date.now() && Date.now() < sessionHardStopAt) {
+                    const outcome = await Promise.race([turn.then(() => "turn"), delay(1_000).then(() => "poll")]);
+                    if (outcome === "turn") {
+                        turn = startTurn();
+                        continue;
+                    }
+                    if (Date.now() >= nextHeartbeatAt) {
+                        try {
+                            leaseExpiresAt = (await control.heartbeat(session.id)).expiresAt;
+                        }
+                        catch { /* existing lease remains authoritative and bounded */ }
+                        nextHeartbeatAt = Date.now() + 30_000;
+                    }
+                    // State poll every 3s (was every 1s) — cuts control-plane RPS ~3x during calls.
+                    if (Date.now() >= nextStateAt) {
+                        nextStateAt = Date.now() + 3_000;
+                        try {
+                            const state = await control.state(session.id);
+                            leaseExpiresAt = state.expiresAt;
+                            if (["cancelled", "expired", "failed", "completed"].includes(state.status))
+                                break;
+                        }
+                        catch {
+                            // Transient 429/5xx on control plane must not tear down live media.
+                        }
+                    }
+                }
+            });
+            await gateway.close();
+            const final = await control.state(session.id);
+            if (!["cancelled", "expired", "failed", "completed"].includes(final.status))
+                await control.update(session.id, "completed", "ended");
+        }
+        catch (error) {
+            process.stderr.write(`${voiceSessionStageLog(error)}\n`);
+            const stage = error instanceof VoiceSessionStageError ? error.stage : "gateway_start";
+            const healthCodes = mapSessionStageToCodes(stage);
+            try {
+                await control.update(session.id, "failed", "media_failed", { healthCodes, stage });
+            }
+            catch { /* fail closed */ }
+            if (config.sessionControlEndpoint && config.grantCredential) {
+                try {
+                    await reportVoiceHealthToControlPlane(voiceHealthReportEndpoint(config.sessionControlEndpoint), config.grantCredential, healthReportFromSessionFailure(stage));
+                }
+                catch { /* fail closed */ }
+            }
+            try {
+                await gateway.close();
+            }
+            catch { /* fail closed */ }
+        }
+        mediaMetrics.summarizeSession();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+export interface GatewayConfig {
+    agentId: string;
+    canonicalAgentName?: string;
+    port: number;
+    transcriptPolicy: "off" | "ephemeral";
+    projectId?: string;
+    meetingId?: string;
+    sessionControlEndpoint?: string;
+    grantFile?: string;
+    grantEndpoint?: string;
+    grantCredential?: string;
+    speechEndpoint?: string;
+    speechCredential?: string;
+    speechMode?: "byo_http" | "openai_turn";
+    openAiApiKey?: string;
+    openAiBaseUrl?: string;
+    openAiTranscriptionModel?: string;
+    openAiSpeechModel?: string;
+    openAiVoice?: string;
+    openAiVoiceOverride?: string;
+    openClawEndpoint?: string;
+    openClawToken?: string;
+    openClawApiMode?: "responses" | "chat_completions";
+    runtimeKind?: "hermes" | "openclaw" | "zeroclaw";
+    runtimeProtocol?: "responses" | "chat_completions" | "zeroclaw_webhook";
+    runtimeEndpoint?: string;
+    runtimeToken?: string;
+    runtimeModel?: string;
+    openClawChatModel?: string;
+    openClawVoiceModelOverride?: string;
+    openClawVoiceModelAllowlist?: string[];
+    /** Short spoken identity for thin voice policy (e.g. Athena). Never dump tools/history here. */
+    openClawSpokenName?: string;
+    /** Completion token budget for spoken turns (default 80). */
+    openClawMaxTokens?: number;
+    runtimeTimeoutMs?: number;
+    speechSlaMs?: number;
+    presenceMs?: number;
+    capabilityPublishEndpoint?: string;
+    capabilityPublishCredential?: string;
+}
+export interface ConfigValidation {
+    valid: boolean;
+    reasons: string[];
+}
+export declare function validateByoConfig(config: GatewayConfig): ConfigValidation;
+export declare function loadGatewayConfig(env?: NodeJS.ProcessEnv): Promise<GatewayConfig>;