@perkos/perkos-voice 0.1.0

package/dist/grants.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+function parseGrant(raw) {
+    const value = raw?.grant ?? raw;
+    if (!value || typeof value !== "object")
+        throw new Error("invalid grant response");
+    const grant = value;
+    for (const key of ["url", "roomName", "token", "expiresAt", "meetingId", "agentIdentity"]) {
+        if (typeof grant[key] !== "string" || !grant[key])
+            throw new Error(`grant ${key} missing`);
+    }
+    return grant;
+}
+export class FileGrantSource {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async obtain() { return parseGrant(JSON.parse(await readFile(this.path, "utf8"))); }
+}
+export class M2mGrantSource {
+    endpoint;
+    credential;
+    fetcher;
+    constructor(endpoint, credential, fetcher = fetch) {
+        this.endpoint = endpoint;
+        this.credential = credential;
+        this.fetcher = fetcher;
+    }
+    async obtain(request) {
+        const response = await this.fetcher(this.endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-perkos-voice-credential": this.credential },
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            throw new Error(`grant request failed (${response.status})`);
+        return parseGrant(await response.json());
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export * from "./types.js";
+export * from "./mediaStages.js";
+export * from "./bragiDelivery.js";
+export * from "./config.js";
+export * from "./grants.js";
+export * from "./service.js";
+export * from "./adapters/livekit.js";
+export * from "./adapters/openclaw.js";
+export * from "./adapters/speech.js";
+export * from "./adapters/openaiSpeech.js";
+export * from "./readiness.js";
+export * from "./sessionControl.js";
+export * from "./capability.js";
+export * from "./state-machine.js";
+export * from "./ports.js";
+export * from "./gateway.js";
+export * from "./fakes.js";
+export * from "./onboarding.js";
+export * from "./installer.js";
+export * from "./adapters/zeroclaw.js";
+export * from "./doctor.js";
+export * from "./a2aEnrollment.js";
+export * from "./workCallContext.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+export * from "./types.js";
+export * from "./mediaStages.js";
+export * from "./bragiDelivery.js";
+export * from "./config.js";
+export * from "./grants.js";
+export * from "./service.js";
+export * from "./adapters/livekit.js";
+export * from "./adapters/openclaw.js";
+export * from "./adapters/speech.js";
+export * from "./adapters/openaiSpeech.js";
+export * from "./readiness.js";
+export * from "./sessionControl.js";
+export * from "./capability.js";
+export * from "./state-machine.js";
+export * from "./ports.js";
+export * from "./gateway.js";
+export * from "./fakes.js";
+export * from "./onboarding.js";
+export * from "./installer.js";
+export * from "./adapters/zeroclaw.js";
+export * from "./doctor.js";
+export * from "./a2aEnrollment.js";
+export * from "./workCallContext.js";

package/dist/installer.d.ts

@@ -0,0 +1,41 @@
+export declare const VOICE_INSTALL_CONTRACT_VERSION: "perkos.voice.install/v1";
+export type SupportedRuntime = "hermes" | "openclaw" | "zeroclaw";
+export type RuntimeProtocol = "openai_responses" | "openai_chat_completions" | "zeroclaw_webhook";
+export type VoiceEnvironment = "dev" | "qa" | "production";
+export type ServiceManager = "launchd" | "systemd" | "compose";
+export interface RuntimeProfile {
+    runtime: SupportedRuntime;
+    protocols: readonly RuntimeProtocol[];
+    defaultProtocol: RuntimeProtocol;
+    defaultEndpoint?: string;
+    defaultModel?: string;
+    pluginPackage: string;
+}
+export declare const RUNTIME_PROFILES: Readonly<Record<SupportedRuntime, RuntimeProfile>>;
+export interface VoiceInstallRequest {
+    version: typeof VOICE_INSTALL_CONTRACT_VERSION;
+    runtime: SupportedRuntime;
+    environment: VoiceEnvironment;
+    agentId: string;
+    canonicalAgentName: string;
+    releaseRevision: string;
+    configRevision: string;
+    serviceManager: ServiceManager;
+    protocol?: RuntimeProtocol;
+    runtimeEndpoint?: string;
+    runtimeModel?: string;
+}
+export interface VoiceInstallPlan {
+    runtime: SupportedRuntime;
+    environment: VoiceEnvironment;
+    protocol: RuntimeProtocol;
+    runtimeEndpoint: string;
+    runtimeModel?: string;
+    serviceName: string;
+    pluginPackage: string;
+    releaseRevision: string;
+    configRevision: string;
+    secretFileMode: "0600";
+    checks: readonly ["/health", "/ready", "/capabilities", "doctor_report"];
+}
+export declare function planVoicePluginInstall(request: VoiceInstallRequest): VoiceInstallPlan;

package/dist/installer.js

@@ -0,0 +1,83 @@
+export const VOICE_INSTALL_CONTRACT_VERSION = "perkos.voice.install/v1";
+export const RUNTIME_PROFILES = {
+    hermes: {
+        runtime: "hermes",
+        protocols: ["openai_chat_completions", "openai_responses"],
+        defaultProtocol: "openai_chat_completions",
+        defaultEndpoint: "http://127.0.0.1:8642/v1/chat/completions",
+        defaultModel: "hermes-agent",
+        pluginPackage: "perkos-voice",
+    },
+    openclaw: {
+        runtime: "openclaw",
+        protocols: ["openai_responses", "openai_chat_completions"],
+        defaultProtocol: "openai_responses",
+        defaultEndpoint: "http://127.0.0.1:18789/v1/responses",
+        pluginPackage: "@perkos/perkos-voice",
+    },
+    zeroclaw: {
+        runtime: "zeroclaw",
+        protocols: ["zeroclaw_webhook"],
+        defaultProtocol: "zeroclaw_webhook",
+        defaultEndpoint: "http://127.0.0.1:42617/webhook",
+        pluginPackage: "xyz.perkos.voice",
+    },
+};
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$/;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+function serviceSlug(value) {
+    return value.toLocaleLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48);
+}
+function validatePrivateRuntimeEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("runtime_endpoint_invalid");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error("runtime_endpoint_protocol_invalid");
+    if (!LOOPBACK_HOSTS.has(url.hostname))
+        throw new Error("runtime_endpoint_not_loopback");
+    if (url.username || url.password || url.search || url.hash)
+        throw new Error("runtime_endpoint_contains_credentials_or_metadata");
+}
+export function planVoicePluginInstall(request) {
+    if (request.version !== VOICE_INSTALL_CONTRACT_VERSION)
+        throw new Error("install_contract_unsupported");
+    if (!SAFE_ID.test(request.agentId))
+        throw new Error("agent_id_invalid");
+    if (!request.canonicalAgentName.trim() || request.canonicalAgentName.length > 64)
+        throw new Error("canonical_agent_name_invalid");
+    if (!request.releaseRevision.trim())
+        throw new Error("release_revision_missing");
+    if (!request.configRevision.trim())
+        throw new Error("config_revision_missing");
+    const profile = RUNTIME_PROFILES[request.runtime];
+    const protocol = request.protocol ?? profile.defaultProtocol;
+    if (!profile.protocols.includes(protocol))
+        throw new Error("runtime_protocol_unsupported");
+    const runtimeEndpoint = request.runtimeEndpoint?.trim() || profile.defaultEndpoint;
+    if (!runtimeEndpoint)
+        throw new Error("runtime_endpoint_discovery_required");
+    validatePrivateRuntimeEndpoint(runtimeEndpoint);
+    const runtimeModel = request.runtimeModel?.trim() || profile.defaultModel;
+    if (protocol === "openai_chat_completions" && !runtimeModel)
+        throw new Error("runtime_model_missing");
+    const slug = serviceSlug(request.canonicalAgentName) || serviceSlug(request.agentId);
+    const prefix = request.serviceManager === "launchd" ? "xyz.perkos.voice" : "perkos-voice";
+    return {
+        runtime: request.runtime,
+        environment: request.environment,
+        protocol,
+        runtimeEndpoint,
+        ...(runtimeModel ? { runtimeModel } : {}),
+        serviceName: `${prefix}.${slug}.${request.environment}`,
+        pluginPackage: profile.pluginPackage,
+        releaseRevision: request.releaseRevision,
+        configRevision: request.configRevision,
+        secretFileMode: "0600",
+        checks: ["/health", "/ready", "/capabilities", "doctor_report"],
+    };
+}

package/dist/mediaMetrics.d.ts

@@ -0,0 +1,15 @@
+export declare const MEDIA_SUCCESS_EVENTS: readonly ["track_subscribed", "turn_received", "stt_success", "openclaw_success", "openclaw_model_default", "openclaw_model_canary", "openclaw_latency_fast", "openclaw_latency_acceptable", "openclaw_latency_slow", "tts_success", "audio_publish_started", "audio_publish_completed", "tts_first_byte", "publish_cancelled", "remote_track_rejected", "self_loop_suppressed", "barge_in_candidate", "barge_in_confirmed", "publish_cancelled_barge_in", "publish_cancelled_session_close", "chat_commit_started", "chat_commit_succeeded", "chat_commit_failed", "chat_commit_skipped_cancelled", "turn_based_input_suppressed", "chat_policy_normal", "chat_policy_private", "work_chat_brief_loaded", "work_chat_brief_empty", "runtime_timeout", "turn_cancelled_session_close", "queued_turns_discarded", "openclaw_response_filtered", "openclaw_language_retry", "openclaw_safe_fallback", "chat_fallback_started", "chat_fallback_succeeded", "chat_fallback_failed", "voice_subtask_started", "voice_subtask_completed", "voice_subtask_timeout", "voice_subtask_failed", "voice_presence_started", "voice_presence_cancelled"];
+export type MediaSuccessEvent = typeof MEDIA_SUCCESS_EVENTS[number];
+export type MediaSuccessObserver = (event: MediaSuccessEvent) => void;
+export declare class MediaSuccessMetrics {
+    #private;
+    private readonly logger;
+    constructor(logger?: (line: string) => void);
+    mark: MediaSuccessObserver;
+    beginSession(): void;
+    summarizeSession(): void;
+    snapshot(): Record<MediaSuccessEvent, {
+        observed: boolean;
+        count: number;
+    }>;
+}

package/dist/mediaMetrics.js

@@ -0,0 +1,43 @@
+export const MEDIA_SUCCESS_EVENTS = [
+    "track_subscribed", "turn_received", "stt_success", "openclaw_success",
+    "openclaw_model_default", "openclaw_model_canary", "openclaw_latency_fast", "openclaw_latency_acceptable", "openclaw_latency_slow",
+    "tts_success", "audio_publish_started", "audio_publish_completed",
+    "tts_first_byte",
+    "publish_cancelled", "remote_track_rejected", "self_loop_suppressed",
+    "barge_in_candidate", "barge_in_confirmed", "publish_cancelled_barge_in",
+    "publish_cancelled_session_close", "chat_commit_started", "chat_commit_succeeded",
+    "chat_commit_failed", "chat_commit_skipped_cancelled",
+    "turn_based_input_suppressed", "chat_policy_normal", "chat_policy_private",
+    "work_chat_brief_loaded", "work_chat_brief_empty",
+    "runtime_timeout", "turn_cancelled_session_close", "queued_turns_discarded",
+    "openclaw_response_filtered", "openclaw_language_retry", "openclaw_safe_fallback",
+    "chat_fallback_started", "chat_fallback_succeeded", "chat_fallback_failed",
+    "voice_subtask_started", "voice_subtask_completed", "voice_subtask_timeout", "voice_subtask_failed",
+    "voice_presence_started", "voice_presence_cancelled",
+];
+export class MediaSuccessMetrics {
+    logger;
+    #counts = new Map();
+    constructor(logger = (line) => process.stderr.write(`${line}\n`)) {
+        this.logger = logger;
+    }
+    mark = (event) => {
+        const count = (this.#counts.get(event) ?? 0) + 1;
+        this.#counts.set(event, count);
+        this.logger(`voice media success: ${event} count=${count}`);
+    };
+    beginSession() {
+        this.#counts.clear();
+        this.logger("voice session metrics: started");
+    }
+    summarizeSession() {
+        const values = MEDIA_SUCCESS_EVENTS.map((event) => `${event}=${this.#counts.get(event) ?? 0}`).join(" ");
+        this.logger(`voice session metrics: completed ${values}`);
+    }
+    snapshot() {
+        return Object.fromEntries(MEDIA_SUCCESS_EVENTS.map((event) => {
+            const count = this.#counts.get(event) ?? 0;
+            return [event, { observed: count > 0, count }];
+        }));
+    }
+}

package/dist/mediaStages.d.ts

@@ -0,0 +1,12 @@
+export declare const VOICE_SESSION_STAGES: readonly ["grant_obtain", "livekit_connect", "audio_source_create", "track_create", "track_publish", "gateway_start", "status_joined", "turn_loop"];
+export type VoiceSessionStage = typeof VOICE_SESSION_STAGES[number];
+export declare class VoiceSessionStageError extends Error {
+    readonly stage: VoiceSessionStage;
+    readonly code = "VOICE_SESSION_STAGE_FAILED";
+    constructor(stage: VoiceSessionStage);
+}
+export declare function voiceSessionStageLog(error: unknown, fallback?: VoiceSessionStage): string;
+export declare function runVoiceSessionStage<T>(stage: VoiceSessionStage, operation: () => T | Promise<T>, options?: {
+    timeoutMs?: number;
+    cleanup?: () => void | Promise<void>;
+}): Promise<T>;

package/dist/mediaStages.js

@@ -0,0 +1,48 @@
+export const VOICE_SESSION_STAGES = [
+    "grant_obtain",
+    "livekit_connect",
+    "audio_source_create",
+    "track_create",
+    "track_publish",
+    "gateway_start",
+    "status_joined",
+    "turn_loop",
+];
+export class VoiceSessionStageError extends Error {
+    stage;
+    code = "VOICE_SESSION_STAGE_FAILED";
+    constructor(stage) {
+        super(`voice_session_stage_failed:${stage}`);
+        this.stage = stage;
+        this.name = "VoiceSessionStageError";
+    }
+}
+export function voiceSessionStageLog(error, fallback = "gateway_start") {
+    const stage = error instanceof VoiceSessionStageError ? error.stage : fallback;
+    return `voice_session_stage_failed:${stage}`;
+}
+export async function runVoiceSessionStage(stage, operation, options = {}) {
+    let timer;
+    try {
+        const pending = Promise.resolve().then(operation);
+        if (!options.timeoutMs)
+            return await pending;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new VoiceSessionStageError(stage)), options.timeoutMs);
+        });
+        return await Promise.race([pending, timeout]);
+    }
+    catch (error) {
+        try {
+            await options.cleanup?.();
+        }
+        catch { /* fixed fail-closed stage wins */ }
+        if (error instanceof VoiceSessionStageError)
+            throw error;
+        throw new VoiceSessionStageError(stage);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/onboarding.d.ts

@@ -0,0 +1,67 @@
+export declare const EXTERNAL_AGENT_CONTRACT_VERSION: "perkos.voice.external-agent/v1";
+export type ExternalAgentPreflightCode = "contract_invalid" | "runtime_unhealthy" | "runtime_not_ready" | "runtime_response_failed" | "runtime_response_too_slow" | "media_unavailable" | "speech_unavailable" | "control_plane_unavailable" | "capability_publish_unavailable";
+export interface ExternalAgentOnboardingContract {
+    version: typeof EXTERNAL_AGENT_CONTRACT_VERSION;
+    runtime: {
+        mode: "responses" | "chat_completions" | "zeroclaw_webhook";
+        nonStreaming: true;
+        cancellation: true;
+        responseTimeoutMs: number;
+        healthTimeoutMs: number;
+    };
+    media: {
+        livekit: true;
+        inboundAudio: true;
+        outboundAudio: true;
+        bargeIn: true;
+    };
+    speech: {
+        stt: true;
+        tts: true;
+        transcriptPersistence: "off";
+    };
+    control: {
+        dynamicSessions: true;
+        encryptedM2mDelivery: true;
+        oneTimeDiscovery: true;
+        capabilityHandshake: "allow_listed";
+    };
+    install: {
+        immutableRelease: true;
+        secretFileMode: "0600";
+        healthPath: "/health";
+        readinessPath: "/ready";
+        capabilityPath: "/capabilities";
+        configRevision: string;
+    };
+}
+export interface ExternalAgentProbePorts {
+    health(signal: AbortSignal): Promise<boolean>;
+    readiness(signal: AbortSignal): Promise<boolean>;
+    runtimeTurn(signal: AbortSignal): Promise<boolean>;
+    media(signal: AbortSignal): Promise<boolean>;
+    speech(signal: AbortSignal): Promise<boolean>;
+    controlPlane(signal: AbortSignal): Promise<boolean>;
+    capabilityPublisher(signal: AbortSignal): Promise<boolean>;
+}
+export interface ExternalAgentPreflightResult {
+    ready: boolean;
+    codes: ExternalAgentPreflightCode[];
+    checkedAt: string;
+}
+export interface InstalledExternalAgentState {
+    imageRevision?: string;
+    configRevision?: string;
+    secretFileMode?: string;
+}
+export interface DesiredExternalAgentState {
+    imageRevision: string;
+    configRevision: string;
+}
+export interface InstallDecision {
+    action: "noop" | "reconfigure" | "replace_release";
+    reasons: string[];
+}
+export declare function validateExternalAgentContract(contract: ExternalAgentOnboardingContract): string[];
+export declare function runExternalAgentPreflight(contract: ExternalAgentOnboardingContract, ports: ExternalAgentProbePorts, now?: () => Date): Promise<ExternalAgentPreflightResult>;
+export declare function evaluateExternalAgentInstall(current: InstalledExternalAgentState, desired: DesiredExternalAgentState): InstallDecision;

package/dist/onboarding.js

@@ -0,0 +1,72 @@
+export const EXTERNAL_AGENT_CONTRACT_VERSION = "perkos.voice.external-agent/v1";
+export function validateExternalAgentContract(contract) {
+    const reasons = [];
+    if (contract.version !== EXTERNAL_AGENT_CONTRACT_VERSION)
+        reasons.push("version_unsupported");
+    if (contract.runtime.nonStreaming !== true)
+        reasons.push("runtime_nonstreaming_required");
+    if (contract.runtime.cancellation !== true)
+        reasons.push("runtime_cancellation_required");
+    if (!Number.isInteger(contract.runtime.responseTimeoutMs) || contract.runtime.responseTimeoutMs < 1_000 || contract.runtime.responseTimeoutMs > 60_000)
+        reasons.push("runtime_response_budget_invalid");
+    if (!Number.isInteger(contract.runtime.healthTimeoutMs) || contract.runtime.healthTimeoutMs < 250 || contract.runtime.healthTimeoutMs > 10_000)
+        reasons.push("runtime_health_budget_invalid");
+    if (!contract.media.livekit || !contract.media.inboundAudio || !contract.media.outboundAudio || !contract.media.bargeIn)
+        reasons.push("media_contract_incomplete");
+    if (!contract.speech.stt || !contract.speech.tts || contract.speech.transcriptPersistence !== "off")
+        reasons.push("speech_contract_incomplete");
+    if (!contract.control.dynamicSessions || !contract.control.encryptedM2mDelivery || !contract.control.oneTimeDiscovery || contract.control.capabilityHandshake !== "allow_listed")
+        reasons.push("control_contract_incomplete");
+    if (!contract.install.immutableRelease || contract.install.secretFileMode !== "0600")
+        reasons.push("install_hardening_incomplete");
+    if (contract.install.healthPath !== "/health" || contract.install.readinessPath !== "/ready" || contract.install.capabilityPath !== "/capabilities")
+        reasons.push("service_paths_invalid");
+    if (!contract.install.configRevision.trim())
+        reasons.push("config_revision_missing");
+    return reasons;
+}
+async function boundedProbe(probe, timeoutMs) {
+    try {
+        const ok = await probe(AbortSignal.timeout(timeoutMs));
+        return ok ? "ok" : "failed";
+    }
+    catch (error) {
+        return error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "failed";
+    }
+}
+export async function runExternalAgentPreflight(contract, ports, now = () => new Date()) {
+    if (validateExternalAgentContract(contract).length > 0) {
+        return { ready: false, codes: ["contract_invalid"], checkedAt: now().toISOString() };
+    }
+    const codes = [];
+    const health = await boundedProbe(ports.health, contract.runtime.healthTimeoutMs);
+    if (health !== "ok")
+        codes.push("runtime_unhealthy");
+    const readiness = await boundedProbe(ports.readiness, contract.runtime.healthTimeoutMs);
+    if (readiness !== "ok")
+        codes.push("runtime_not_ready");
+    const runtime = await boundedProbe(ports.runtimeTurn, contract.runtime.responseTimeoutMs);
+    if (runtime === "timeout")
+        codes.push("runtime_response_too_slow");
+    else if (runtime !== "ok")
+        codes.push("runtime_response_failed");
+    if (await boundedProbe(ports.media, contract.runtime.healthTimeoutMs) !== "ok")
+        codes.push("media_unavailable");
+    if (await boundedProbe(ports.speech, contract.runtime.healthTimeoutMs) !== "ok")
+        codes.push("speech_unavailable");
+    if (await boundedProbe(ports.controlPlane, contract.runtime.healthTimeoutMs) !== "ok")
+        codes.push("control_plane_unavailable");
+    if (await boundedProbe(ports.capabilityPublisher, contract.runtime.healthTimeoutMs) !== "ok")
+        codes.push("capability_publish_unavailable");
+    return { ready: codes.length === 0, codes, checkedAt: now().toISOString() };
+}
+export function evaluateExternalAgentInstall(current, desired) {
+    if (current.imageRevision !== desired.imageRevision)
+        return { action: "replace_release", reasons: ["image_revision_changed"] };
+    const reasons = [];
+    if (current.configRevision !== desired.configRevision)
+        reasons.push("config_revision_changed");
+    if (current.secretFileMode !== "0600")
+        reasons.push("secret_permissions_invalid");
+    return reasons.length > 0 ? { action: "reconfigure", reasons } : { action: "noop", reasons: [] };
+}

package/dist/openclaw-plugin.d.ts

@@ -0,0 +1,16 @@
+interface VoicePluginConfig {
+    agentId: string;
+    agentName: string;
+    environment: "dev" | "qa" | "production";
+    secretFile: string;
+    runtimeEndpoint?: string;
+    runtimeProtocol?: "responses" | "chat_completions";
+    runtimeModel?: string;
+    sessionControlEndpoint: string;
+    grantEndpoint: string;
+    capabilityPublishEndpoint: string;
+    port?: number;
+}
+export declare function voiceGatewayEnv(config: VoicePluginConfig): NodeJS.ProcessEnv;
+export default function register(api: any): void;
+export {};

package/dist/openclaw-plugin.js

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function voiceGatewayEnv(config) {
+    return {
+        VOICE_AGENT_ID: config.agentId,
+        VOICE_CANONICAL_AGENT_NAME: config.agentName,
+        VOICE_PORT: String(config.port ?? 18081),
+        VOICE_TRANSCRIPT_POLICY: "off",
+        VOICE_SECRET_FILE: config.secretFile,
+        VOICE_SESSION_CONTROL_ENDPOINT: config.sessionControlEndpoint,
+        VOICE_GRANT_ENDPOINT: config.grantEndpoint,
+        VOICE_CAPABILITY_PUBLISH_ENDPOINT: config.capabilityPublishEndpoint,
+        PERKOS_VOICE_RUNTIME: "openclaw",
+        PERKOS_VOICE_RUNTIME_PROTOCOL: config.runtimeProtocol ?? "responses",
+        PERKOS_VOICE_RUNTIME_ENDPOINT: config.runtimeEndpoint ?? "http://127.0.0.1:18789/v1/responses",
+        ...(config.runtimeModel ? { PERKOS_VOICE_RUNTIME_MODEL: config.runtimeModel } : {}),
+    };
+}
+export default function register(api) {
+    const config = api.config?.plugins?.entries?.["perkos-voice"]?.config;
+    const logger = api.logger ?? console;
+    let child;
+    api.registerService({
+        id: "perkos-voice",
+        start: async () => {
+            if (!config)
+                throw new Error("PerkOS Voice plugin config is missing");
+            const cli = resolve(dirname(fileURLToPath(import.meta.url)), "cli.js");
+            child = spawn(process.execPath, [cli], {
+                env: { ...process.env, ...voiceGatewayEnv(config) },
+                stdio: ["ignore", "inherit", "inherit"],
+            });
+            child.once("exit", (code, signal) => logger.error(`[perkos-voice] gateway exited code=${code ?? "none"} signal=${signal ?? "none"}`));
+            logger.info(`[perkos-voice] gateway started for ${config.agentName} (${config.environment})`);
+        },
+        stop: async () => {
+            if (!child || child.exitCode !== null)
+                return;
+            child.kill("SIGTERM");
+            await new Promise((resolveStop) => {
+                const timeout = setTimeout(() => { child?.kill("SIGKILL"); resolveStop(); }, 5_000);
+                child?.once("exit", () => { clearTimeout(timeout); resolveStop(); });
+            });
+        },
+    });
+}

package/dist/ports.d.ts

@@ -0,0 +1,23 @@
+import type { TranscriptPolicy, VoiceGatewayGrant, VoiceMode } from "./types.js";
+export interface MediaTurnInput {
+    turnId: string;
+    audio: AsyncIterable<Uint8Array>;
+}
+export interface MediaRoom {
+    setBargeInHandler?(handler: (turnId: string) => Promise<void>): void;
+    setInputSuppressed?(suppressed: boolean): void;
+    join(grant: VoiceGatewayGrant): Promise<void>;
+    receiveTurn(): Promise<MediaTurnInput>;
+    publish(turnId: string, audio: AsyncIterable<Uint8Array>): Promise<"completed" | "cancelled" | "stream_stalled">;
+    cancelPublish(turnId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface SpeechPipeline {
+    transcribe(turnId: string, audio: AsyncIterable<Uint8Array>, policy: TranscriptPolicy): Promise<string>;
+    synthesize(turnId: string, text: string, mode: VoiceMode, speechVoice?: string): AsyncIterable<Uint8Array>;
+    cancel(turnId: string): Promise<void>;
+}
+export interface AgentRuntime {
+    respond(turnId: string, input: string, signal: AbortSignal): Promise<string>;
+    cancel(turnId: string): Promise<void>;
+}

package/dist/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/presenceTone.d.ts

@@ -0,0 +1,5 @@
+/** First audible presence while the runtime is still thinking. 0 disables. */
+export declare const VOICE_PRESENCE_MS = 1500;
+/** Soft two-tick PCM loop (48 kHz mono int16). Local — no TTS, interruptible. */
+export declare function presenceToneFrames(signal: AbortSignal, sampleRate?: number): AsyncIterable<Uint8Array>;
+export declare function presencePublishId(turnId: string): string;

package/dist/presenceTone.js

@@ -0,0 +1,43 @@
+/** First audible presence while the runtime is still thinking. 0 disables. */
+export const VOICE_PRESENCE_MS = 1_500;
+const SAMPLE_RATE = 48_000;
+const FRAME_MS = 20;
+const FRAME_SAMPLES = Math.round(SAMPLE_RATE * FRAME_MS / 1_000);
+const CYCLE_MS = 1_200;
+const AMPLITUDE = 2_400;
+function whenAborted(signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+function sampleAt(sampleIndex) {
+    const cycleSamples = Math.round(SAMPLE_RATE * CYCLE_MS / 1_000);
+    const pos = sampleIndex % cycleSamples;
+    const t = pos / SAMPLE_RATE;
+    const ms = t * 1_000;
+    if (ms < 70)
+        return Math.sin(2 * Math.PI * 523.25 * t) * AMPLITUDE;
+    if (ms >= 250 && ms < 320)
+        return Math.sin(2 * Math.PI * 659.25 * t) * AMPLITUDE;
+    return 0;
+}
+/** Soft two-tick PCM loop (48 kHz mono int16). Local — no TTS, interruptible. */
+export async function* presenceToneFrames(signal, sampleRate = SAMPLE_RATE) {
+    const frameSamples = sampleRate === SAMPLE_RATE ? FRAME_SAMPLES : Math.round(sampleRate * FRAME_MS / 1_000);
+    let sampleIndex = 0;
+    while (!signal.aborted) {
+        const frame = new Int16Array(frameSamples);
+        for (let index = 0; index < frameSamples; index += 1) {
+            frame[index] = sampleAt(sampleIndex + index);
+        }
+        sampleIndex += frameSamples;
+        yield new Uint8Array(frame.buffer, frame.byteOffset, frame.byteLength);
+        await Promise.race([
+            new Promise((resolve) => setTimeout(resolve, FRAME_MS)),
+            whenAborted(signal),
+        ]);
+    }
+}
+export function presencePublishId(turnId) {
+    return `${turnId}:presence`;
+}

package/dist/readiness.d.ts

@@ -0,0 +1,27 @@
+import type { GatewayConfig } from "./config.js";
+import type { VoiceCapabilityHandshake } from "./types.js";
+export interface Probeable {
+    probe(): Promise<void>;
+}
+export interface ReadinessSnapshot {
+    ready: boolean;
+    reasons: string[];
+    checkedAt?: string;
+}
+export declare class GatewayReadiness {
+    #private;
+    private readonly config;
+    private readonly speech?;
+    private readonly fetcher;
+    constructor(config: GatewayConfig, speech?: Probeable | undefined, fetcher?: typeof fetch);
+    snapshot(): ReadinessSnapshot;
+    check(): Promise<ReadinessSnapshot>;
+    capability(now?: Date): VoiceCapabilityHandshake;
+}
+export declare class CapabilityPublisher {
+    private readonly endpoint;
+    private readonly credential;
+    private readonly fetcher;
+    constructor(endpoint: string, credential: string, fetcher?: typeof fetch);
+    publish(handshake: VoiceCapabilityHandshake): Promise<void>;
+}